controller - the sipstone controller program
controller config_file
The controller is the master program that starts request generators to generate SIP requests to test performance of a SIP Proxy or Registrar Server (Server Under Test or SUT). No assumption is made on the location of Proxy and Registrar servers, hence they can be either co-located or separate entities. The controller uses loaders for request generation and call handlers for responding to generated calls. On startup, the controller generates configuration files for one or more loaders and call handlers. It then executes the loaders and call handlers using rexec or rsh. A shared file system like NFS is used for storing shared configuration files, and test results. For the rest of this discussion, the term loader refers to the entity that initiates requests, and callhandler refers to the entity that accepts such requests and sends back responses.
As defined in the SIPstone document, the sipstone test-suite can generate SIP requests on behalf of a range of users. All such users are identified by a common prefix (e.g., sipuser). To this prefix is appended a number selected from a range. For instance, if user range is specified as 1000 to 2000, then the user names for the example above, are sipuser1000, sipuser1001, upto sipuser2000. It is to be noted that this naming convention assumes that these users are provisioned suitably at the SUT and are recognized by the SUT.
We define five parameters namely, start-rate, final-rate, step-size, duration, and taLimit. This will be easy to understand with the following example: Consider values (10, 50, 20, 30, 500). Here, the duration is 30 seconds, and it defines a run. In each run, a fixed number of requests are generated per second. In our example, each loader generates 10 requests/sec for the first run. It then increases the rate by the step-size, hence the new rate is 30 (10+20), and this is repeated for the second run. The third and final run has a request rate of 50. It is to be noted that a request rate is applied to an individual loader, so that if there are three loaders running simultaneously, the actual request rate starts at 30 and ends at 150. However, if at the end of any test run, the average turn around time for that run exceeds 500 ms (the taLimit parameter), then the test process ends. .
The sipstone test-suite adopts distribution as the means for generating high request rates. Accordingly, the controller can spawn a number of loader processes on several machines to generate high request rates. The callhandler program can also be run on many machines. rexec or rsh programs are the preferred way of starting remote processes. In order to share configuration and result data, we depend on a shared filesystem like NFS.
On startup, the controller reads its configuration files, and generates configuration files for loaders and callhandlers. It then starts the callhandler(s). Callhandler(s) register themselves as well as register a block of user's allocated to them with SUT. If all registrations are successfull, the callhandler sends back a "Success" message back to the SUT. When all callhandlers have successfully registered, the controller then invokes the loader(s).
Each configuration file contains a key-value pair for each parameter separated by whitespace. Comments begin with a #.
Configuration parameter (required) Description loaderName caller This parameter will be used in From headers of SIP INVITE requests. This is the caller, and must be a valid user in the domain recognized by the SUT. loaderProgPath /path/to/sipstone The path to the loader program, without trailing slash. In most cases, this is same as the current directory, but fully-qualified. loaderProgName startLoader.sh In most cases, this parameter is the name of the loader executable. However, if you want to customize the way the loader is started, you may want to use the startLoader.sh script which is started by controller, and which then starts the loader. handlerProgPath /path/to/sipstone The path to the callhandler program, without trailing slash handlerProgName starthandler.sh File name of the callhandler program rexecProgPath /usr/local/gnu/bin path to the 'rexec' program in controller's machine, without trailing slash rexecProgName rexec|rsh [args] %H %C the full command that is needed to execute the rexec or rsh program. For example, Solaris users may use the command rsh -l username, and Linux users may use the command rexec -l user -p password. It is to be noted that any such command is expected to either automatically contain the password, or not need password at all (.rhosts or hosts.equiv is set suitably). The controller program cannot supply or negotiate for passwords. It just substitutes the hostname of remote host at %H and the command, which is generated automatically in %C and executes it using the execvp system call. domain acme.com SUT domain(registrar/proxy) serverAddress sipproxy.acme.com SUT hostname(registrar/proxy) serverPort 5060 SUT port testType Registration|Outbound|Proxy480|Proxy200 The type of test that the controller needs to initiate. This parameter is not used currently, but will be used to implement the test based on the SIPstone spec in subsequent releases. requestMethod REGISTER|INVITE The type of SIP request that loader's will generate. For REGISTER only tests no callhandler is needed protocol TCP|UDP The transport to use. Defaults to UDP isSendAck true|false Does the loader send an ACK when it gets a final response? useAuthentication (true | false) Does the agents try with Authorization credentials when they get a 401 or 407 ? digestPassword The password to be used for digest authentication. Currently, only digest is supported. isDebug true|false whether debug messages are sent to stderr isLog true|false whether detailed action messages are logged to a file. If isLog and isDebug are both on, then all the debug messages will also be logged to the log file. The name of the log file is usually the name of the configuration file appended with .log controllerListenPort udp-port The port to which callhandler's send the "Success" message indicating to the controller that it can start the loader(s). requestRateFrom start-rate The initial request generation rate per second. (e.g., 10) requestRateTo end-rate The final sending rate per second, included. (e.g. 50) requestStepSize step-size The step size (e.g., 20) runDuration period-secs The test duriation for a given sending rate in seconds. (e.g., 30) taLimit turn around time (milli secs) The maximum acceptable turn around time to consider a test run as success. No further test runs will be invoked, if a particular run involves transactions whose turn around time exceeds taLimit. the default for this parameter is 5000. The SIPstone recommended values are 500 for REGISTER and 2000 for INVITE. loaderName myloader This is a common loader property that is used only for INVITE tests. The value here is the caller name for INVITE. For REGISTER this is not used but the loader specific property given below is used. loaderCount loader-count Number of Loaders to use in the test. This must be atleast one. Each loader has seven properties, and the first loader is identified by suffix 0 Loader specific properties loaderAddress0 hostname or ip the host name where this loader (Loader 0) will be executed loaderDomain0 domain the domain name of the callers for this loader (e.g., cs.columbia.edu loaderNamePrefix0 user-name-prefix The user name(s) to be used in REGISTER tests. (e.g., sipuser) loaderNameSuffix0 base-number (e.g., 1001) loaderRange0 number-of-users (e.g.,10). In the context of this example, then, the constructed users are sipuser1001, sipuser1002, ... sipuser1010 loaderBodyFileName0 file-name|null null if no SDP is needed for outgoing requests. fileName a file containing a SDP that gets appended to each request. loaderPort0 port-number (e.g.,7855). The port the loader will use for sending out and receiving SIP messages. loaderAddress1, .... These parameters are repeated as many times as needed handlerCount handler-count The number of call handlers in the test. Each handler has seven properties, with the first handler identified by suffix 0. A call handler is needed only for INVITE tests. It is not needed for REGISTER only tests. Handler specific properties handlerAddress0 host or ip the host domain name where this handler will be executed handlerDomain0 caller-domain the domain name of the callees for this handler handlerNamePrefix0 callee-name-prefix same as explained in loader. (e.g., sipuser) handlerNameSuffix0 start-suffix (e.g., 3001) handlerRange0 number-of-users The number of users allocated to this call handler. For example, if this is 70, then the user names start from sipuser3001 and end at sipuser3070 handlerListenPort port-number the port number that this handler should bind and listen. can be zero.
The following files are generated by the controller at the end of the test, in its working directory:
| controller.conf.log | This file contains all debug information if debug is enabled. |
| controller.conf.dataobj | This file contains test results. Each line corresponds to a test record. A description is given in the Interpreting results section. |
| controller.conf.analyze | The controller performs some initial analysis on controller.conf.dataobj and saves the results in this file |
| controller.conf.analyze.log | contain the debug information when analyzing data |
| controller.conf.gnup | the result in gnuplot points format |
| controller.conf.gnul | the result in gnuplot lines format |
- .dataobj files
Files ending with extension dataobj contain exact data collected during test for every transaction. This is a "space" delimited text file. The first line contains the number of records in that file. Each subsequent record is a multi-tuple, and has the following format:
call-id : sending time in UTC(sec, microsec) : total responses received : (response code, received time in UTC (sec, microsec))+
The + indicates one or more, and multiple such tuples can be present, if number of responses-received is more than 1 (e.g., 100, 180, 200 for INVITE). all fields are separated by space.
- .analyze files
Files ending with extension analyze are derived from dataobj files. Similar to databj files, these are also "space" delimited text files. They contain for each transaction,
relative sending time (in ms, from 0) : sending rate : failure rate : average turnaround time (in ms).
It is to be noted that the Controller's dataobj and analyze files are summarized over all loader files. This means the .analyze files will capture the aggregated sending rate of all loaders.
- .gnup, .gnul files
These are gnuplot command files that display .analyze files using gnuplot. To view them, start gnuplot with the appropriate file name as a command line argument.
The sipstone tools use SIP templates for constructing SIP INVITE, REGISTER, ACK, and BYE requests. These are contained in the files invite.template, register.template, ack.template, bye.template in the distribution. Normally, these files do not need any changes. However they can be suitably modified to suit any particular application needs. A sample registration template is shown here. The following parameters are recognized:
- $M (request_method, REGISTER/INVITE)
- $T (protocol, TCP/UDP)
- $S (registrar_domain e.g., cs.columbia.edu)
- $N (caller e.g., sipuser0)
- $D (caller_domain e.g., cs.columbia.edu)
- $H (local host name e.g., lima.cs.columbia.edu)
- $I (IP address of local host)
- $P (local port)
- $X (callee_name, e.g., hgs)
- $Y (callee_domain, e.g., columbia.edu)
- $B (body_file - the actual body will be substituted here)
- $L (length of SDP)
- $C (call_id)
- $Q (CSeq)