RPCAP is the Remote Packet CAPture System for Linux. It comprises of two portions, a server part which runs on the target computer off which network packets are to be captured, and a client portion which runs on the system where the captured packets are received and processed. The server side code is a standalone executable while the client code comes in two versions, one a dynamically linked library (librpcap) which can be linked to a user program, and the other a test version which comprises an executable program for testing.

The sole function of RPCAP is to allow a user to capture live network traffic on another machine remotely. This funtionality has many applications, mainly in testing of networks and network code and protocols.

This is the third release of the code, with many added features and bugfixes. However, it is still experimental code, and your mileage may vary, though I've had no problems using it. However, at this stage, it would help if you are already familiar with libpcap, although the documentation is somewhat improved. The usage is almost identical to that of libpcap, with the notable differences being that (1) rpcap exposes only a (large) subset of libpcap; and (2) the setup of capture operations is rather different, since we seek to capture packet traffic on a remote machine, rather than locally.

RPCAP uses an RPC based mechanism to communicate with the remote system on which packets are captured. This is standard Sun (ONC) RPC as implemented on GNU/ Linux systems. The client side library (librpcap) presents an API that is a subset of the libpcap API. Of course, some functionality is missing, for example the code that does offline reads of captured and archived data, since this would have no application in the context of remote capture. However, I have implemented the saving of live capture data through pcap_dump_open and pcap_dump, in an identical manner and format to libpcap by using savefile.c from the libpcap code

All the libpcap functionality in rpcap, except for the dump saves of captured data, are implemented as RPC calls to the server rpcap process running on the target machine. While I could have utilised the RPC callback mechanism for getting the capture data too, the high overhead of RPC calls makes this a solution to avoid. Instead, rpcap uses a TCP connection between the target and client machines to dump captured data, running (on my experimental system) on port 21373. The end of capture is monitored by a UDP "callback" socket on port 61373.

Both the host (client) and target (server) processes are implemented as multithreaded processes, and will thus compile and link only on systems with thread support (libpthread), which means all Linux systems with glibc >= 2.0 (I think). AFAIK, Linux has had pthread support since glibc 2.0, but I'm not really sure. Check your local documentation if in doubt. RPC ought to be available on any system that supports NFS, which means almost all Linux systems extant.

The available API, which is a subset of the libpcap API, can be checked out indirectly in rpcap_client.c, which is the header file for both client and server RPC code. Briefly, the current implementation supports:

pcap_next remains to be done; however, as of now I am not very sure of its utility, given that tcpdump does not use it. If enough people ask me to do it however, I might change my mind.

I have tested the present functionality in the example program that is a part of the distribution in client_test.c, and it appears to work fine. Anyway, I'd be happy to receive any bug reports.

Read the INSTALL file for installation, compiling, etc., and the pcap (3) manpage for a description of the API and how to use it. Also look at the example (just one now, but this will be added to in the future) in client_test.c.

This example is heavily commented, and provides a kind of hands-on HOWTO in using rpcap. It does presume some familiarity with libpcap, since I have not commented any of the libpcap style API calls, since they are in every respect (signature, return value, et al) identical to their libpcap counterparts. You should quite easily be able to use rpcap after checking out the example.

There are two ways that a capture session can be invoked:

1. For a specified number of packets (say 25 packets). In this case, you can simply invoke pcap_loop with the number of packets to be captured specified in the cnt parameter passed to it. The rpcap system will deliver that number of packets to the application and then reset.

2. For an indefinite number of packets. This is how tcpdump works. If you run tcpdump with the default invocation, it continues to capture and display packets till it is terminated with a Ctrl-C (SIGINT). For programs of this type, you will have to specifically call the rpcap_end_capture_handler function to terminate capture and clean up. Invocation is quite easy, and typically would comprise of setting up a SIGINT (and/ or SIGTERM, etc.) signal handler, and invoking rpcap_end_capture_handler() by simply adding the line

as a part of the code. See rtdump.c in the accompanying rtdump package for an example of the invocation.

You will need to add an additional forward declaration of the function rpcap_end_capture to your remote capture programs, thus:

This function is not a libpcap function, so it cannot be included in pcap.h. Also, for a single function, it did not make sense to create an additional header file, thus this declaration.

You use rpcap in exactly the same way as with libpcap, with the obvious exception that you need to set things up to capture packets on another machine. The system is intialised on the target machine by simply building or copying (if possible) the rpcap_svc executable on it, and then executing it as a background process. Remember, though, that you have to have superuser privileges to run packet capture (libpcap) programs on Linux. Rpcap_svc will crash if you run it as an ordinary user.

Thus, first you become superuser, and simply invoke the target side code by typing "rpcap_svc &" and hitting Enter, to run it as a background process. The server side code on the target machine is now ready to respond to any capture requests from client machines. You can of course also set the SUID flag on the rpcap_svc executable, and invoke it as a regular user.

You will need to include the pcap.h file in your client program (you may find one in your standard include directory, which may (or may not) be /usr/include, but that may not work, depending on the version). I suggest that you use the pcap.h file that I have included in this archive by including it as #include "pcap.h"). The client needs to first initialize itself using the "init_rpcap" function, which is invoked with the name of the target machine, the IP address of the client machine as a text string (as in char *ip = "192.168.1.1"), and the port address on which the client will receive captured packets as an unsigned short int (I use 21373). Look at the enclosed client_test.c program for details.

Once you have this code in, do the packet capture stuff the same way you would with libpcap (yes, identically, callback and all), and build identically, except that you need to link to lrpcap rather than lpcap. A typical command line for building an rpcap application, assuming the librpcap library is in /usr/local/lib, is:

Mind though that you do not invoke any libpcap funtionality not present in rpcap, since the pcap.h file includes functions not present in rpcap, or else you will get link errors.

The RPC mechanism has several security issues. In addition, the capture code on the target runs with superuser privileges, apart from the obvious matter of the security of any network capture code. Thus, rpcap should NOT be used on any systems that are connected to the outside world, unless you know what you're doing. While you could run rpcap as an inetd invokable service, since it is an RPC service, this too is an absolute no-no.

This should not pose many problems, as long as the target platform supports multithreading and Sun RPC. This means most of the Unices. Win NT is another question, since it natively supports only DCE RPC. I believe that there is a port of ONC RPC to NT, which ought to ease the task. I plan to look at doing a FreeBSD port as and when I manage to get the Linux version working satisfactorily.

The API is nearly complete now, and seems to work OK. Also, the remote capture version of tcpdump, called rtdump, is ready now and is bundled with this release. Check the README.rtdump file in the accompanying distribution for details on building and using rtdump.

RPCAP is released under the GNU GPL, version 2. Check the enclosed COPYING file for details.

RPCAP has been written by S. Krishnan. You can contact me by e-mail on sri_krishnan@yahoo.com. I'd be happy to get any feedback that you may have on RPCAP, including proper documentation, bug reports, enhancements and suggestions for these, and bug fixes, of course.