/client

Tracing Communication

Wireshark

Wireshark is a free and open source Network Protocol Analyzer. It is a perfect tool to monitor, analyze and grab snapshots of communication between our libraries and third party entities (SMSCs, clients using our server library etc.) for debug purposes.

First step to use it is to download adequate version of Wireshark Network Protocol Analyzer from:

http://www.wireshark.org

Then it has to be installed along with necessary packet capture library (WinPcap/pcap).

Capture Setup

After installing Wireshark, start Wireshark and choose on which interface to capture transmission data:

Wireshark interface configuration screenshot

It may be useful to set up a capture filter to only trace packets exchanged with particular IP and port numbers. To do this select Options on the interface dialog:

Wireshark capture options screenshot

And then create appropriate expression in Capture Filter field of the Options dialog. To filter only communication from particular IP address enter host IP as the capture filter expression:

Wireshark capture filter screenshot

More insight on capture filter expressions can be found in Wireshark's documentation.

Once everything is set up every you may click Start to begin capturing packets exchanged.

Manage what is displayed

If at this point the trace does not automatically show packages decoded as appropriate SMSC access protocol then you may have to set the decoding arbitrarily by choosing Decode As... from the pop-up menu:

Wireshark decode as screenshot

Then it is necessary to find appropriate protocol on the list:

Wireshark decode as dialog screenshot

It may also be useful to set display filter so that only the protocol of interest is displayed in the list of traced packages. To do so enter protocol name in the Filter field below the toolbar:

Wireshark display filter screenshot

Once communication that is supposed to be captured is finished capturing can be stopped on the Wireshark toolbar:

Wireshark capture stop screenshot

Export Capture

To save a subset of the captured data choose Export Specified Packets... from the File menu in Wireshark's main window:

Wireshark export menu screenshot

In the Save file as dialog in the Packet Range group you can very precisely decide which packets you want exported to the file:

Wireshark export as screenshot

Such a trace, with selected operations can be great help in debugging problems reported to us.

Please bear in mind that Wireshark as a tool can also be very useful in identifying and diagnosing many other communication problems that exceed scope of this guide.

Security Considerations

Captured data is an unmatched source of information in many situations requiring insight into problems during deployment of our components. It may however contain security sensitive information like IP addresses, credentials etc.

On our part we guarantee not to disclose or misuse any information that is passed to us as a part of the capture file. The data is only used for providing support and resolving technical issues. The documents containing captured data may however be transmitted by third party services (like e.g. e-mail or storage) which we cannot hold any responsibility for.

Above are shown ways to limit exported information (packets) into capture file to an absolute minimum. Please be careful not to export any unnecessary data which may lead potential security threat.