Name

sipua - a SIP test user agent

Synopsis

sipua [options]

Availability

Binary and source "beta" distribution are available now for evaluation only. The code runs on Solaris, Linux, FreeBSD and Windows NT, with other Unix platforms available upon request.

Evaluation binaries are available free of charge for Solaris on SPARC (SunOS 5.8). Windows 2000 version does not implement audio module. Although a very rudimentary audio module is implemented in Solaris version, note that RTP implementation is incomplete and RTCP is not implemented. Evaluation version does not allow use of external audio tools. Note that windows version will need some of the DLL's which can be obtained from the support page.

Binary and source can be licensed. See the licensing section of siplib. The licensed version allows you to use external audio tools, like RAT and vat.

Version

sipua-1.21 released Apr 2002.

Description

sipua is a SIP user agent. sipua allows you to make as well as receive SIP calls. It is a simple user agent intended to test the features of libsip++. Visit the libsip++ page for a complete features list.

Features

Planned features with approximate release dates.

Options

-h
Print usage and exit.
-v
Print version information and exit.
-d   category
Makes the software print out debugging information for the particular category. Currently supported categories are all, sql, net, sdp, misc. The option can be repeated to allow debugging multiple categories.
-o   tracefile
Put debug trace in this trace file instead of displaying on the console. This can be used only with -d option.
-a   audiotool
Specify the external audio tool, e.g., rat, vat. The calling convention is

<tool> remotehost/remoteport[/selfport]
-p   port
Use this port number instead of default 5060 for SIP.
-n
Non-interactive mode. This is useful with -f option.
-f   commandfile
Use a command file instead of typing the commands on the console. Command file has a list of commands you want to execute, as you would type on the console. After all the commands are executed, the sipua> prompt appears, unless "exit" command are run or sipua was run using -n option. This option is used typically in testing routine sequence.
-P   port
Use this port number for media if an external audio tool is used. By default, the port numbers are allocated frm 10000 onwards. This does not apply if built-in audio tool is used.

Commands

sipua supports basic commands as listed below. Every command has three parts: the name of the command, possible options of the form attribute=value and list of required or optional arguments.
help
Print out the list of commands supported.
invite [options...] sipurl [requesturi]
Make an outgoing call to the specified user. If requesturi is present then that is used, otherwise it is set to the sipurl. sipurl becomes the To header of the outgoing INVITE SIP message. Various options supported are as follows:
invite uses the global parameters for subject, password and proxy and userid.
accept [options...]
This can be used for responding to an incoming call. Following options are supported.
Note that the default handling may over-ride any of these values. In particular for INVITE response the content must be SDP.
noresponse
This can be used to ignore an incoming call indication. This should be used for testing only.
reject [options...] [reason-string]
This can be used to reject an incoming call. Following options are supported.
reason-string specifies the reason text for rejecting the call. This is optional.
authenticate [options..]
This allows you to authenticate an incoming INVITE. Please be advised that you have to accept the call explicitly even after authentication. But if the authentication fails the call is automatically rejected with 401 error code. Following options are supported:
redirect newurl [reason-string]
Use this command to redirect an incoming call to a new address. reason-string is sent to remote in the 3xx response.
(register | unregister | register-get) [options...]sipurl [registrar]
register is used to register with a SIP registrar with the given sipurl. If registrar is specified then the registration request is sent to that, otherwise the registrar address is derived from sipurl. registrar is a SIP URL of the form sip:hostname. On the otherhand, sipurl is of the form sip:user@domain. unregister unregisters all the previous registrations for this sipurl. register-get allows you to retrieve the registration information from the server for this sipurl. Following options are supported for these commands:
reinvite
reinvite sends a re-INVITE message to the remote user for the current call using the existing media description. This is provided only for testing purpose.
bye
This command is used to terminate an on-going call. You also get an indication when the remote party terminates the call.
(get-ogrqh | get-ogrsh | get-inrqh | get-inrsh) header
This is used to get the Outgoing Request Header, Outgoing Response Header, Incoming Request Header and Incoming Response Header respectively. The appropriate header value from the last incoming or outgoing request associated with the active call is printed on the console. These commands should be used only for testing purpose.
options url [from]
This allows sipua to send out SIP OPTIONS method to the specified url. from specifies the From address to be used in OPTIONS.
qos [options...] sipurl [requesturi]
This command is similar to invite except that it makes two SIP calls to the destination and invokes two external audio tools. This is used for measuring the QoS of the audio call by comparing the audio packets sent in the first call to that received in the second call. It is expected that the destination of the call will just loopback thea audio stream, from first call to the second call. For instance, if the destination is a conference server with two participants invoked by this command, the audio sent by the first call is received by the second. The audio tool to be used for this command is rtpqos.
waitforresponse [sec]
Wait for response from remote for an outgoing call. If the sec optional parameter is specified then wait for atmost sec seconds. This is useful for automated scripts using the -f option to take action after the call is responded.
waitforcall [sec]
Wait for a new incoming call. If the sec optional parameter is specified then wait for atmost sec seconds. This is useful for automated scripts using the -f option to take action after an incoming call is received.
sleep nsec
Sleep for nsec seconds. This is useful only when -f option is used to run the commands from a file.
log (msgflow | debug | error) ( on [filename] | off)
This allows you to enable or disable debugging/trace options. msgflow option displays a message flow graph for the transactions. debug is for usual verbose mode trace, and error is for error display. You can either switch on or off these debugging options.
? (call | ep | calls | eps)
Use this option to query the system parameters. call represents the current call. ep represents the user agent server. calls and eps are count for number of calls and endpoints respectively. This version supports only one call and one endpoint.
(set | unset) (password | userid | subject | proxy) [value]
set allows to set or retrive the value of a global parameter. If value is specified then the parameter value is set to that. If it is not specified then the parameter value is printed onto stdout. unset resets the value of the parameter to empty. Currently following global variables are supported:
(exit | quit)
This allows you to gracefully exit the application. Note that ongoing calls are not explicitly terminated.

Using TLS (SIPS uri)

In order to use TLS for communication, you need to just replace all sip: in your commands with sips:. For example, to tell sipua, to use a TLS connection to an outbound proxy, you need to use the command set proxy sips:proxy.acme.com. All TLS connections use port 5061 by default. In order for TLS to work properly you need certificate files as explained in TLS notes.

Example

An example session is shown in this section using sample screen dumps. The user commands are shown in bold face and my comments are in italics. More examples can be found at a different web page.
$ sipua  
SIPUA, (c) 2000, Columbia University
Visit http://www.cs.columbia.edu/~kns10/software/sipua for more information.
Unlicensed copy. Contact hgs@cs.columbia.edu for a license.
SIP Endpoint: sipua@ind.cs.columbia.edu Server, Listening at 128.59.19.27:5060 
Waiting for connections...
Type help to get list of commands

Set the subject for a call

sipua> set subject This is a test mail

Make a call to a user. Here you have explicitly specified the
optional request uri.

sipua> invite sip:kundan@cs.columbia.edu sip:kns10@ind.cs.columbia.edu
Audio tool listening at 37700
Self Session Audio Rx128.59.19.194:37700 (0)pcmu/8000; 
Calling sip:kundan@cs.columbia.edu from sip:kns10@cisalpino.cs.columbia.edu
sipua> 
100 Trying

200 OK
Call Established Call is establied now
Accepted by remote
Remote Session Audio Rx128.59.19.27:38154 (0)/0; 
Audio tool connecting to 128.59.19.27:38154
Play thread started
Record thread started

You can start talking now

You can query the status of the call any time

sipua> ? call
Self: sip:kns10@cisalpino.cs.columbia.edu; Remote:sip:kundan@cs.columbia.edu; Active; 

You decide to terminate the call after sometime

sipua> bye
Record thread is terminating
Play thread is terminating

You get an incoming call indication from another user.

The remote address and subject is displayed.
sipua> Incoming call from sip:hgs@marta.cs.columbia.edu to sip:bob@cs.columbia.edu
Subject is This is a test mail
accept/reject/noresponse ? accept

You chose to accept the call. You could have alternatively 
rejected, or redirected the call, or demanded an authentication.

Remote Session is Audio Rx128.59.19.194:37700 (0)/0; 
Audio tool listening at 38154
Self Session is Audio Rx128.59.19.27:38154 (0)pcmu/8000; 
Accepting the call...
Audio tool connecting to 128.59.19.194:37700
sipua> Play thread started
Record thread started

After some time the remote closes the call. You get an indication.

Call closed by remote
Play thread is terminating
Record thread is terminating

You can query the status of the user agent server any time

sipua> ? ep
Endpoint: sipua@cisalpino.cs.columbia.edu Server, Listening at 128.59.19.194:5060

Notes

See Also

Authors

Kundan Singh, Sankaran Narayanan , and Henning Schulzrinne at Columbia University, Department of Computer Science

Acknowledgements

Copyright

Copyright 1999-2002 by Columbia University; all rights reserved
sipua is subject to licensing.

Last updated  by Kundan Singh