Toolpack Debug Application:Tbsigtrace

Revision as of 09:04, 26 July 2016

Tbsigtrace is a debug tool that is use to collect signalling protocol messages. It can trace SS7, ISDN, SIP, Sigtran and CAS messages and put it in a wireshark format.

Version history

This documentation relates to Tbsigtrace of version 2.3 and higher. Note that the Tbsigtrace signalling tracing tool that is distributed with version 2.0 to 2.2 is based on an older capturing tools that does not provide wireshark pcap format.

Application Location

The binary is located in the [InstallDir]/[PackageVersion]/bin/release/[Platform]/

Example:

Version 2.5.55, TMG unit (PPC 32bits)

/lib/tb/toolpack/pkg/2.5.55/bin/release/ppc-linux/tbsigtrace

Version 2.5.55, CentOS 64 bits system

/lib/tb/toolpack/pkg/2.5.55/bin/release/x86_64-linux64/tbsigtrace

Version 2.5.55, Windows system

C:\TelcoBridges\toolpack\pkg\2.5.55\bin\release\i586-win32\tbsigtrace.exe

How to use it

Command line

Options available:

-d Daemon mode

-name XYZ Application name

-db Not used

-c XYZ Configuration file to load

-gw XYZ SystemId (i.e. 12358)

-adapter TBXYZ Adapter name to connect or "all" to connect to all adapter in the system

-ss7 Default ss7 trace activation

-isdn Default isdn trace activation

-old Isdn trace in cap file with lapd layer

-ip Default ip trace activation (sip, sigtran and iua)

-h248 Default h248 trace activation

-lapd Default lapd trace activation

-cas Default cas trace activation

-cap CAP format enabled

-format TXT format enabled

-single Create one file by signaling entity

-regroup Regroup identical signaling entity types in one file

-L link Specify which the link to be captured

Examples

Starting with releases 2.4.59, 2.5.116 and 2.6, "-adapter all -regroup -cap" options are included automatically when launching tbsigtrace.
To avoid regrouping entities, you need to use "-single".
To have the text format, you need to use "-format".
The output files will be located in:

/lib/tb/toolpack/setup/12358/[major version]/apps/tbsigtrace

This will gather all ss7 links from one blade and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ss7

This will gather all isdn links from one blade and put them in several files

tbsigtrace -gw 12358 -adapter TB000544 -isdn
tbsigtrace -gw 12358 -adapter TB000544 -isdn -old       (for lapd layer analysis)

This will gather all sip traces and put them in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ip

This will gather traces on the CA001734_63 stack only

tbsigtrace -L CA001734_63

Specify the adapter name along with the entity name

tbsigtrace -L TB001734:CA001734_63

Specify many entities at once (all lines have the same effect)

tbsigtrace -L CA001734_63,CA001734_62,CA001734_61
tbsigtrace -L CA001734_63;CA001734_62;CA001734_61
tbsigtrace -L "CA001734_63,CA001734_62,CA001734_61"
tbsigtrace -L "CA001734_63 CA001734_62 CA001734_61"

In release 2.4 This will gather all sip and sigtran traces and put them in a single cap file for all adapters in the system

tbsigtrace -gw 12358 -ip

This will gather all h248 messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -h248

This will gather all IUA (ip and tdm sides) messages on the system and put this in a single cap file

tbsigtrace -gw 12358 -adapter TB000544 -ip -lapd

Configuration file (optional)

The configuration file will allow to get several blades in the same file

Example MTP2_LINK_0,MTP2_LINK_1 are on the same blade and MTP2_LINK_10,MTP2_LINK_11 are on an other blade

 <signaling>
 
 <sysmgr name = "MTP2_LINK_0" grpname="LS1" capfile="true" />
 <sysmgr name = "MTP2_LINK_1" grpname="LS1" capfile="true" />
 <sysmgr name = "MTP2_LINK_10" grpname="LS1" capfile="true" />
 <sysmgr name = "MTP2_LINK_11" grpname="LS1" capfile="true" />
 
 </signaling>

Web

You can start/stop tbsigtrace via web.

Create a new application configuration:

Name                   -> oamsigtrace
Application Type       -> User Specific
Bin Path               -> @{PKG_BIN}/tbsigtrace
Working Path           -> ../tbsigtrace
Command-line arguments -> -adapter all -ss7 -cap

Create a new application instance:

Name                   -> oamsigtrace
Host                   -> (put required host)
Application Config     -> oamsigtrace

You can control the application "oamsigtrace" with the application status page OR
you can use the option 'o' in tboamapp (page=Application launch manager) and change the state of oamsigtrace application
state (0=stop 1-mgmt 2-run).

How to interpret the data

When using wireshark (http://www.wireshark.org/) to analyze the captured data (in pcap format), you can apply multiple filters to scope your analysis around relevant data. For example, in the following picture, you can see that the 'q931' filter was applied to show only ISDN-related packets.

Be aware however that the pcap format is usually a container for "packet" data. So, when TDM protocol such as ISDN or SS7 (non-sigtran) traffic is captured, tbsigtrace wraps the protocol around fake protocols layers (i.e. Ethernet/IP/SCTP) for wireshark to be able to open it and analyze it. Again, in the picture below, you can see these fake layers that were inserted since the capture was made from a TDM link (T1) with the regular Q.921 (HDLC) transport protocol. These layers have been stripped and replaced by Ethernet/IP/SCTP.

Beside being able to use wireshark for analysis, these fake layers may also carry useful information. For example, when looking at an ISDN capture, the fake-SCTP layer will contain the network-variant (e.g. DMS, NET5, etc) from which the capture was made. Another useful information is contained in the fake-IP source and destination addresses:

• when (Src=w.x.y.z and Dst=0.0.0.0) it means an egress (outgoing) message.
• when (Src=0.0.0.0 and Dst=w.x.y.z) it means an ingress (incoming) message.

WARNING: tbsigtrace application should not be used all the time, otherwise it will reduce performance and fill completely your hard drive.