Over a million developers have joined DZone.

An Introduction to rpcap

DZone 's Guide to

An Introduction to rpcap

Stuck doing PCAPs on multiple remote machines? Here's a project that will make life easier.

· Open Source Zone ·
Free Resource

I used to work on an IMS project that involved multiple machines. In a nutshell, IMS stands for IP Multimedia Subsystem and it is a SIP-based implementation of a voice service in an 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 me to collect PCAP files from one or two remote machines. To achieve this, I used a simple bash script, which starts a 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 some of the machines, forgot to save the file, I closed Wireshark by mistake, and so on.

At this point, the idea for rpcap was born.

What Is rpcap?

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

  • Logging into the remote machine over SSH.
  • Checking whether the user has sufficient rights to execute a tcpdump.
  • Executing a 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 on the target machine as long as it has an SSH server and tcpdump installed.

How You Can Use rpcap

Let's imagine you work on a network application, spread across multiple hosts. For example, say it's a generic IMS setup consisting 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 rpcap, you have a configuration file that contains all destination machines (called targets). For example:

{ "targets" : [ { "Name": "HSS", "Host": "", "Port": 22, "User": "devel", "Key": "keys/dev", "Destination": "PCAPs/hss", "File Pattern": "trace", "File Rotation Count": 10, "Use sudo": true }, { "Name": "S-CSCF", "Host": "", "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 a PCAPs/s-cscf directory (Destination parameter) named trace.pcap (File pattern parameter) and 10 captures will be kept (File Rotation Count parameter).

rpcap is a console application. When you start it, you will see the rpcap prompt:

rpcap> start rpcap> wireshark rpcap> stop

start executes tcpdump on both targets. At this point, PCAP files are being saved in the destination directory. At any time, you can start Wireshark either for all targets or for specific ones 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 rpcap in action.

What is shown in the video:

  • There is a test setup with two virtual machines, managed by Vagrant. The Vagrantfile and corresponding rpcap 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 rpcap.
  • rpcap is started and the target command is executed. It shows information about the targets and their packet-capturing capabilities.
  • The start command is executed. PCAP files are generated on both machines.
  • On stop, the PCAP files are rotated.
  • Any time, the wireshark command can be executed and the traffic for each machine is piped to a dedicated Wireshark instance.
open source ,rpcap ,pcap ,ims

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}