CAPITEST(8)

NAME
capitest - performing ISDN connections for testing purposes

SYNOPSIS
capitest [-h|-]?
capitest -l [-v]
capitest -i [-f file name pattern] [options]
capitest {-o|-O} src.file [options] dest.number [src.number]
capitest {-b|-B} batch file [options]
capitest {-s|-S} [options] dest.number [src.number]

DESCRIPTION
capitest is used for several testing purposes. The first and easiest task (besides printing out usage information) is to list all available CAPI controllers and their capabilities. Then capitest can handle incoming or outgoing connections. And last but not least it can perform a self connection with data validation. All these tasks are used to check the capabilities and the availability of an ISDN controller, test if it is working and if the line it is attached to is working as well. The more advanced features like performing repeated connections, executing batch jobs and using user-user data for data validation can be used for stress testing and to verify correctnes of CAPI controller drivers.

Note that for outgoing and self connections capitest is only capable to work with a single ISDN controller. By default it is controller number 1, but this may be changed through a command line option. When handling incoming connections capitest can use a single controller like for the other tasks, but also handle connections through all available ISDN controllers.

capitest recognizes the following command line arguments to specify the main task. Some other options may be added to alter the main operation. They are described later.

? | -h
    Print out usage information for the program.

-l  This option specifies the task to execute for capitest as to list all ISDN controllers available over CAPI. The output will contain the controller name, the manufacturer name, the number of B-channels, the bitmask of global options and the bitmasks of the B-channel protocols supported. If -v is also specified, there will be a lot more information in the output. Additional information about the controller will be printed and the several bitmasks will be decoded, so the controller capabilities are more human readable.

-i  This option specifies the task to execute for capitest as to handle incoming connections. The program handles incoming connections until the user presses the key <Ctrl-C>.

    By default any number of concurrent connections is accepted. If only a limited number of connections should be accepted at a time, the number of concurrent connections may be altered by specifying option -n#.

-o src.file
    This option specifies the task to execute for capitest as to create an outgoing connection. The argument to this option must be the name of an existing file. The content of this file will be sent through the connection after it is established. The data will not be modified in any way but just sent out.

    By default only one connection is made and then the program terminates. If -n# is also specified, capitest creates this many concurrent identical outgoing connections and terminates after the last connection is completed.

-O src.file
    This option is much like ‘-o src.file’. The only difference lies in the fact, that the program does not terminate after one series of connections is completed. Instead it will continuously start over to further create new connections. It only termintes when the user presses the key <Ctrl-C>.

-b batch file
    The batch task is a generalization of executing outgoing calls through ‘-o src.file’. It is possible to use more than one controller at the same time for outgoing calls and the destination number can be different for each call. The argument to this option specifies a batch file containing descriptions for the outgoing calls to be made. The file must be made up of lines with four or five fields separated by spaces and / or tabs. The fields will contain the controller number to use, the connection type (one of the strings ‘voice’, ‘hdlc’, ‘x75’ or ‘fax’) the file to send, the destination phone number and the optional source phone number (may be left out). Empty lines and lines starting with ‘#’ or ‘’; are ignored.

    For every line containing valid call data a connection will be made. All these connections are performed concurrently. After all calls are completed the program will terminate. The batch of calls is only executed once.

-B batch file
    This option is much like ‘-b batch file’. The only difference lies in the fact, that the program does not terminate after all calls in the batch file are executed once. Instead it will continuously restart each call declared in the batch file as soon as it is finished. The program only termintes when the use presses the key <Ctrl-C>.

-s  This option specifies the task to execute for capitest as to do a self connection with checking for data transfer without errors. When the program starts it first registers for incoming calls and then creates an outgoing connection. The destination number must address the controller capitest currently works with. Both connections (the incoming and the outgoing side of the call) are established if possible. Thereafter some test pattern is sent out as data through the outgoing connection. This data is expected to return within the incoming connection. After the data transfer the connections will be terminated. Finally the received data is compared with the test pattern sent. If equal the self connection was successful and the line is working.

-S  This option is much like ‘-s’. The only difference lies in the fact that the program does not terminate after one self connection is finished. Instead it will continuously start over to make more self connections. It only terminates when the user presses the key <Ctrl-C>.

Exactly one of the above options must be specified. If none of them is given capitest has no clue which task it should execute. If more than one them are given there are conflicting task requests. In both of these cases no task will be executed. The program simply aborts with the usage output.

The following additional options may be combined with the options for the main task described above. Note that not all of these options may be given to all of the main task options.

-a  For incoming calls it is possible to not only use one controller. When this option is specified incoming calls are handled for all available controllers. It has preceedence over option ‘-c#’, i.e. even if the later is specified, incoming connections are accepted for all controllers. Note that this option is only valid for the main task option ‘-i’.

-c# By default capitest uses the first CAPI controller, i.e. controller number 1. If this option is specified the controller number is taken from its numeric argument. This number must identify a valid and installed ISDN controller. Note that for batch calls the controller number to use is specified within the batch file and not through this option.

-e  For incoming connections the data received will by default be ignored. If this option is specified, all received data blocks will be echoed back to the caller. If option ‘-f file name pattern’ is also given, the later has preceedence. That means data blocks are not echoed but stored into a file.

    Note that for fax connections the data received cannot be echoed because within fax connections data transfer only happens in one direction.

-f file name pattern
    This option is used to save the data for established incoming connections into files. If it is not specified, incoming data is not saved but simply discarded (or it may be echoed if ‘-e’ is specified). The argument to this option will not directly be used as the file name. As there might be more than one connection at a time, the really used file name is constructed from the argument by appending a unique number and an extension selected from the connection type, all three parts separated by dots. The number is incremented with every new call, starting at one. To not fill up all available disk space for continuous tests, the number wraps around at 999 and old files with this number are overwritten.

-n# By default capitest will only handle a single outgoing connection at a time and any number of concurrent incoming connections if enabled by ‘-i’. By specifying this option the maximum number of concurrent connections is taken from the options numeric argument. Note that the number of B-channels of the addressed controller limits the maximum number of parallel connections.

    Note also that for batch jobs the number of concurrent connections is determined by the number of lines with valid call data and not through this option.

-t {a|auto|v|voice|h|hdlc|x|x75|f|fax}
    With this option the user may select the B-channel protocol used for the established connections. The argument has the following meaning:

    a | auto
        Automatic detection of the B-channel protocol to use. This feature can only be used for incoming connections. Outgoing connections require to explicitly specify the protocol to use. Unfortunately the protocol detection can not distinguish all supported protocols. If the incoming connection is of type speech, telephony or 3.1kHz audio, the B-channel protocol for a voice connection is selected. Unrestricted digital data will lead to a X.75 SLP (also called ISO 7776) connection. Fax-group 3 connections are only automatically recognized if the sending side uses the HLC information element for Fax-G2/G3 in the D-channel (nearly nobody does this, though, usually fax connections are signalled as 3.1kHz audio). All other reported connection types are treated as an X.75 connection. It is in general advisable to explicitly delare the connection type to use.

    v | voice
        Select B-channel protocols for voice connections (i.e. all protocol layers are transparent).

    h | hdlc
        Select B-channel protocols for an HDLC connection (i.e. layer 1 HDLC, all upper layers transparent).

    x | x75
        Select B-channel protocols for an X.75 SLP (also called ISO 7776) connection.

    f | fax
        Select B-channel protocols for fax-group 3. For outgoing connections the source file may either be specified with SFF format or as simple ASCII text. The program will automatically detect the file type and set the protocol configuration accordingly. For incoming connections the fax data is always saved as an SFF file.

-u  With this option the program will send out user-user data to the partner. For outgoing connections the connection type will be signalled to the called party, so automatic detection of the connection type will actually work for all connection types (see explanation of option ‘-t’).

    The second effect is to send out checksum data for data connections to the partner at the end of the call. This information can be evaluated by the partner to verify that all data was transfered successfully. Surely this assumes the partner is also capitest, as it is the only application able to interpret the checksum data. If capitest detects a checksum error, an error message will be printed out.

-v  Increase the verbosity of the output for the task of listing the available CAPI controllers.

dest.number
    The destination number for an outgoing call. This string is sent unmodified to CAPI. So it must consist of dialable digits only.

src.number
    The calling party number for outgoing calls or the called party number for incoming calls (of self connections). This string is sent unmodified to CAPI. So it must consist of dialable digits only. If it is not given no local number is specified for the connections handled.

SEE ALSO
c4b(4).

STANDARDS
The capitest program uses standard CAPI messages to communication over ISDN. It only uses some extensions available in the CAPI implementation for the BSD operating systems. Currently this implementation called c4b is not standardized by the CAPI Association.

HISTORY
The capitest tool first appeared as an add-on for FreeBSD 4.6.

AUTHORS
This manual page and the capitest program were written by Thomas Wintergerst <twinterg@gmx.de>.