What is tranqap

Why this project exists

I used to work on an IMS project, which involved multiple machines. In nutshell, IMS stands for IP Multimedia Subsystem and it is a SIP based implementation of voice service in LTE mobile network. I don't want to explain what IMS is, as it is totally out of the scope of this post, but if you are interested the page for IMS in Wikipedia is a good start.

Tracing a voice call in an IMS setup involves packet capturing on four different machines, which turned out to be a pretty tedious job. Up to now, my work required to collect PCAP files from one or maximum two remote machines. To achieve this I used a simple bash script, which starts tcpdump over SSH and redirects the output to a Wireshark instance running locally. You can find the script in my dotfiles shared on GitHub.

Using this script for capturing traffic from four remote machines was not very straightforward. I often ended up forgetting to start the script for any of the machines, forget to save the file, close wireshark by mistake and so on.

At this point the idea for tranqap was born.

What is tranqap

tranqap aims to make PCAP file collection from remote machines easy. It automates things like:

• Logging to the remote machine over SSH.

• Checking if the user has got sufficient rights to execute tcpdump.

• Executing tcpdump and redirecting the capture to a local Wireshark instance.

The tool runs on Linux and doesn't require the installation of any specific software (besides tcpdump) on the target. In theory there are no restrictions about the target machine as long as it has got SSH server and tcpdump installed.

How you can use tranqap

Let's imagine you work on a network application, spread on a multiple host. For example a generic IMS setup consists of three SIP servers and one HSS (Diameter server). To trace any functionality, more or less you have to inspect the network traffic on each node. At best - this job is tedious.

With tranqap you have got a configuration file, which contains all destination machines (called targets). For example:

{
    "targets" : [
        {
            "Name": "HSS",
            "Host": "192.168.20.51",
            "Port": 22,
            "User": "devel",
            "Key": "keys/dev",
            "Destination": "PCAPs/hss",
            "File Pattern": "trace",
            "File Rotation Count": 10,
            "Use sudo": true
        },
        {
            "Name": "S-CSCF",
            "Host": "192.168.20.53",
            "Port": 22,
            "User": "devel",
            "Key": "keys/dev",
            "Destination": "PCAPs/s-cscf",
            "File Pattern": "trace",
            "File Rotation Count": 10,
            "Use sudo": true
        }
    ]
}

The configuration contains only two targets, but you get the point. PCAP files will be saved in PCAPs/s-cscf directory (Destination parameter), named trace.pcap (File pattern parameter) and 10 captures will be kept (File Rotation Count parameter).

tranqap is console application. When you start it, you see the tranqap prompt:

tranqap> start
tranqap> wireshark
tranqap> stop

start executes tcpdump on both targets. At this point PCAP files are being saved in the destination directory. At any moment you can start wireshark either for all or for specific targets and inspect the traffic in real time. Finally stop terminates the capture on all targets. On the next invocation of start, the PCAP files will be rotated.

Finally here is a screencast showing tranqap in action:

What is shown in the video:

• There is a test setup with two virtual machines, managed by Vagrant. Vagrantfile and corresponding tranqap config can be found here.

• SSH configuration about both machines is shown with vagrant ssh-config.

• Based on this file, a config.json file is created for tranqap.

• tranqap is started and target command is executed. It shows information about the targets and their packet capturing capabilities.

• start command is executed. PCAP files are generated on both machines.

• On stop, the PCAP files are rotated.

• Any time wireshark command can be executed and the traffic for each machine is piped to a dedicated Wireshark instance.