Documente Academic
Documente Profesional
Documente Cultură
1
Starting the tool................................................................................................................................................................................... 1
Initial screen ....................................................................................................................................................................................... 2
Scenario building screen ...................................................................................................................................................................... 3
SIP messages ...................................................................................................................................................................................... 4
Condition ........................................................................................................................................................................................... 5
Commands and playing RTP ................................................................................................................................................................ 6
Variables ............................................................................................................................................................................................ 7
Inserting values in scenario .................................................................................................................................................................. 9
Call generation.................................................................................................................................................................................. 10
Scenario progress screen .................................................................................................................................................................... 11
Menu options .................................................................................................................................................................................... 11
Keywords ......................................................................................................................................................................................... 12
Version checker ................................................................................................................................................................................ 13
This is an updated tutorial page to reflect changes made in version 1.20. New users read everything. Old users
just focus on highlighted parts.
Rel 1.20
New Features:
- Multipart SDP bodies (used for BLA/BLF - Broadsoft style, multiple SDP bodies,..)
- Added new Menu item "Tools"
- Under Tools there is utility that can be used to calculate SDP body
- Under Options there is a new Remote RTP dialog. It can be used to unconditionally send RTP to a given RTP
address:port. As part of the dialog there is a parameter called "Group RTP Packets". Its default value is
"1", but one slower/older machines where RTP sounds choppy try setting this value to 2, 3, 4.
- '«' sign is added on Scenario Entry Text screen to mark the end of the line. This is actually replaced wity
'\r\n' just about before sending it on the wire.
- Starting to use MIG layout. Hoepfully next version fixes possible screen display issues noticed on Linux
version. Linux users, please report weird looking screens.
- Added continuous RTP flag. It enabled it will play over and over the same RTP pcap file. Well, technically the
RTP is played as long as a pause command demands. If you play an out-of-band DTMF digit you want to turn
off this flag, cause most likely you do not want the digit to be played multiple times.
NOTE: If user plans to work with RTP, one more package needs to be installed (JPcap).
1
Initial screen
Initial screen offers basic account settings, option to pick local network interface, transport is UDP (versions
1.00+ do not support TCP) and remote server.
1st step: Account - under number you are
supposed to enter a caller ID. Default
number is 1000, but this can be changed
as needed. A default client scenario will
register this number and will be used for
caller ID in an outgoing call. Provide
authentication parameters such username
and password. Change an RTP port if
needed. See below for more info about
authentication and RTP port.
• Authentication parameters are required if remote server challenges client's the requests. Default
client scenario takes into account configured authentication parameters and uses them for registration
purposes. If a server challenges requests, the following line is expected to be added in an outgoing
request:
• This automatically generates a 'Proxy-Authorization' header value using 'dead' for a username and
'beef' for a password to calculate an authentication response. Starting from version 0.9 users must
specify a header name. In this case it is 'Proxy-Authorization' but can be anything user needs.
NOTE: Keep in mind that sometimes authentication fails due to a wrong SIP header name is used. If Proxy-
Authorization is not working try using ‘Proxy-Authenticate’
2
Scenario building screen
Since version 1.00 introduces simultaneous calls, few new entry fields are added when the tool works in a
client mode. 'Calls/sec' controls the speed of calls generated, 'Max Concurrent' fields limits a maximum
concurrent calls (0 means infinite) and 'Total calls' controls when call generation stops (0 means infinite).
It is worth mentioning key-word [len]. It is used in Content-Length header and tells the tool to calculate SDP
message body and replace [len] with calculated number of bytes. This way user can easy change SDP bodies
without going through a hassle of manually calculating the length.
3
From: <sip:1000@[local_ip]:[local_port]>;tag=24417923471779367133
To: <sip:155@[remote_ip]:[remote_port]>
Call-ID: [call_number]@[local_ip]
CSeq: [cseq+1] INVITE
Max-Forwards: 70
Contact: <sip:1000@[local_ip]:[local_port];transport=[transport]>
User-Agent: SIPInspector_v_[ver]
Content-Type: application/sdp
Content-Length: [len] <--- See how [len] is used instead of exact number of bytes
v=0
o=111 843670094 843670094 IN IP4 [local_ip]
s=-
c=IN IP4 [local_ip]
t=0 0
a=sendrecv
m=audio [media_port] RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=ptime:20
At any point it is possible to go back to 'Initial screen' or click 'Run' to start executing the scenario.
Sometimes, custom scenarios become a mess. To get back default scenario, delete all messages go back to
'Initial screen' and then click on 'Next'.
SIP messages
Each SIP message has a direction and can be deemed as optional. If an incoming message is optional, scenario
control logic is allowed to skip to the next SIP message and evaluate if expected message is received. An
optional outgoing message is sent out ONLY if previously received message was optional. This is a new concept
and was introduced in version 1.00. The purpose is to handle unexpected and out-of-dialog messages
incoming messages. Typical examples are REGISTER or OPTIONS messages. The best way to handle such
messages is to put them at the beginning of the scenario. Take a look at the following cases:
Marked in green is what really is wanted. Extra messages that MAY come are marked in red. Most of times
they just need to be responded with 200 OK.
Scenario on the left instructs the tool to establish a call, send an RTP and wait for the other side to terminate a
call. At any point during this call an unexpected REGISTER and/or OPTIONS requests may come in. To stop
retransmissions, the tool will respond to both requests with 200 OK and the call scenario will not be
interrupted/affected.
4
Scenario on the right is typical
and useful when registering with
a server. The server may respond
with 100 and/or 407 before it
sends a 200 OK. Client must be
ready to calculate authorization
response and may be getting
some 'unexpected' messages, like
NOTIFY for MWI (Message
Waiting Indication).
If an incoming message is
mandatory, scenario will not
Figure 3
advance until an expected
message is received. Requests
and Responses offer set of standard SIP messages. They can be selected from a drop down list. But, users and
not limited to an offered selection. A new message can always be typed in and then added to a scenario.
Buttons "<<Add" or "Del>>" are used to add new entry or to remove existing entries.
Condition
Together with Variables it is the most difficult part to understand so I will spend extra words to make sure the
concept is described the best I can. Sometimes it is not known how exactly scenario will evolve. For example,
let's assume the tool works as a client and registers with the server. At times REGISTER requests may be
accepted, but at times they may be challenged. Conditions help us to create a scenario that will work in both
cases. Similarly, If the tool works as a server it is not guaranteed the client will not try to occasionally register
before it makes a call. To better handle cases like these, conditional and unconditional branching are
implemented.
Client scenario (taken from a scenario tree) may look like below. It registers with a server and provide
authentication response if asked. Then, it makes a call.
5
---- Play pcap=test.pcap
---- Pause[ms]=15000 // Pause is required and tells the tool how long
---> BYE // to keep playing an RTP
<--- 200 OK
Label - if a label button is selected, it is possible to enter any text for a label name. It represents a place of
interest in a scenario. Usually used in conjunction with 'goto' and 'if' condition entries.
Goto - When a goto button is selected, the tool automatically provides a list of available labels. Pick one and
and create an entry. Make sure label where to jump is already created.
if condition - if a button is selected, tool automatically enables fields for its creation. First field is a drop down
list of variables available. More
about variables is given later in
this manual. Second field is a
drop down list of relational
operators. Third field is a value
to be compared with the
variable. The fourth field is a
label where to jump to if
condition is satisfied.
Do not be surprised if following scenario does not This is a proper way to create a scenario for the
6
produce any audio on the other side. Such scenario client. In this scenario pcap file is played for 15
will end very quickly cause as soon as the seconds. After that call is terminated and RTP is
audio is started BYE is sent out which terminates the stopped.
call and stops RTP.
NOTE: On Figure5 there is a checkbox called ‘Cont’. The checkbox tells the tool to keep playing the same pcap
file over and over, until pause expires. Lets say you have a pcap file worth 30 seconds of RTP but you would
like to play the same file twice in a row. In that case you would need check this box and make sure it the
pause value is set to 60000[ms] = 60 seconds.
Variables
The purpose of a variable is to store a value retrieved from a received message. For example, in SIP, a fully
established dialog requires client to remember To tag parameter (toTag). While, initial roll-out of SIP Inspector
for that purpose used keyword [peer_tag_param], this is not enough. For example, users require remembering
custom parameters and parts of received message. Having hard-coded keywords embedded into SIP Inspector
was not an option. A more generic and flexible way to extract information was required. Variables have to be
used when working with PRACKs, SUBSCRIBEs,... See PRACK client/server scenarios that come with SIP
Inspector.
Variables are not global, but tied to a call-dialog instance. Each concurrent call will have its own value for
"toTag"
7
field can be left empty. If empty, it tells the tool to start searching from the beginning of the message until the
first match occurs. In my example I put "To". Starting from version 0.9, it is possible to use 'startline' instead
of a header name. It is required to remember response code or a request method.
Expression - Instead of using regular expression, I opted for wild-card expressions. In essence, users provide
pattern, and whatever is matched with '*' is stored into a variable. It is much simpler than regexp.
The purpose of a variable is to store a value retrieved from a received message. For example, in SIP, a fully
established dialog requires client to remember To tag paramter (toTag). While, initial roll-out of SIP Inspector
for that purpose used keyword [peer_tag_param], this is not enough. For example, users require to remember
custom parameters and parts of received message. Having hard-coded keywords embedded into SIP Inspector
was not an option. A more generic and flexible way to extract information was required. Variables have to be
used when working with PRACKs, SUBSCRIBEs,... See PRACK client/server scenarios that come with SIP
Inspector.
Variables are not global, but tied to a call-dialog instance. Each concurrent call will have its own value for
"toTag".
My example (shown on the picture above) stores a To tag parameter value into variable 'toTag'. The most
important thing while working with variables is to master a wild-card search. Let me expand a bit on it and
illustrate the principle with few examples. Let’s say user needs to extract pieces of the following Contact
header value and store it in different variables.
Putting a '*' at
the beginning
picks up the first
part of the
var2 "Contact" "* Coklin" var2="Zarko"
matched pattern.
Note the Header
field is enclosed
with quotes.
8
value starts with
"Zarko" and not
with " Zarko",
therefore wild-
card expression
returns "Coklin".
Convenient way
var4 Contact: "<sip:*@" var4="112" to get a
username.
In this case not
header is
provided.
var5 - "=500" var5="500"
Variable var5 is
assigned value
"500".
Referencing particular header instance is possible starting from version 0.92. You may find it useful while with Record-Route
headers.
Values field has to be created. It will have 3 lines for each VoIP number. And each line can be dissected into
values separated with ';'.
Let’s take an example where Values files has the content as follows:
Even though 3 different users are registered the scenario has only 2 messages: an outgoing REGISTER request
and an incoming 200 OK response. The trick is to repeat scenario execution 3 times, use [fieldN] key-words
which will be replaced with values inserted from the file.
9
// Lines can be commented using # or //
// Also, make sure values are separated with ;
1000;Zarko;Coklin
2000;John;Doe
3000;Fedor;Emelianenko
<----------
200 OK
The end result will be 3 REGISTER messages. All 3 will be different. All occurrences of [fieldN] will be
substituted and here is how:
Pretty useful, huh? Just do not forget to put [fieldN] where required in a SIP message, and do not forget to load Values File
prior running the script.
Call generation
If the tool works as a client it is possible to
specify speed at which calls are generated
[calls per second], maximum number of
concurrent calls and total number of calls
generated.
10
Scenario progress screen
Figure 9
Menu options
There are few menu options available to a user.
11
Keywords
Replaced with "z9hG4bK" + callNumber + position the current entry has in scenario.
[branch]
Example value it may have: "z9hG4bK15"
Usually used to compose responses and will be replaced with header(s) matching given
name found and extracted from previous received message. Any SIP header name can be
[last_*:]
used instead of '*'. For example, key word "[last_Via:]" will be replaced with "Via" headers
and values found in previous received message.
Replaced with given header value as found in last received SIP message. For example,
[val_last_*:]
[val_last_RSeq:] is used in PRACK requests to get a RSeq value.
[call_number] Replaced with global call counter. Keeps incrementing with every new generated call.
Replaced with From tag if previous received message was request or with To tag if previous
[peer_tag_param]
received message was response.
[username] Replaced with username configured under Authentication tab.
[password] Replaced with password configured under Authentication tab
This is a complex key word and takes into consideration username and password. The
whole key word goes like this:
[authentication username=value1; password=value2;]
[authentication]
Replaced with Proxy-Authorization header with MD5 digest calculated taking value1 for a
username and value2 for a password. If previous message is different than 401 or 407
nothing happens.
12
Version checker
Figure 10
13