387 lines
16 KiB
HTML
387 lines
16 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<title>WinPcap: Remote Capture</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<link href="style.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<!-- Generated by Doxygen 1.6.1 -->
|
|
<div class="navigation" id="top">
|
|
<div class="tabs">
|
|
<ul>
|
|
<li><a href="main.html"><span>Main Page</span></a></li>
|
|
<li><a href="pages.html"><span>Related Pages</span></a></li>
|
|
<li><a href="modules.html"><span>Modules</span></a></li>
|
|
<li><a href="annotated.html"><span>Data Structures</span></a></li>
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="contents">
|
|
<h1>Remote Capture</h1><table border="0" cellpadding="0" cellspacing="0">
|
|
<tr><td colspan="2"><h2>Modules</h2></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__remote__struct.html">Exported Structures and Definitions</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__remotefunc.html">Exported Functions</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__remote__pri__func.html">Internal Functions</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__remote__pri__struct.html">Internal Structures and Definitions</a></td></tr>
|
|
</table>
|
|
<hr/><a name="_details"></a><h2>Detailed Description</h2>
|
|
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<title>Using WinPcap Remote Capture</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<ul>
|
|
<li><a href="#RunningModes">Remote Capture Running Modes</a></li>
|
|
<li><a href="#Config">Configuring the Remote Daemon (rpcapd)</a></li>
|
|
<li><a href="#StartCap">Starting a capture on a remote machine</a></li>
|
|
<li><a href="#UNIX">Installing the Remote Capture Daemon in UNIX</a></li>
|
|
</ul>
|
|
<hr>
|
|
<p>WinPcap comes with Remote Capture capabilities. This is an highly
|
|
experimental feature that allows to interact to a remote machine and capture
|
|
packets that are being transmitted on the remote network.</p>
|
|
<p>This requires a <b>remote daemon </b>(called <code>rpcapd</code>) which
|
|
performs the capture and sends data back and a <b>local client </b>that sends
|
|
the appropriate commands and receives the captured data.</p>
|
|
<p>WinPcap extends the standard WinPcap code in such a way that all
|
|
WinPcap-based tools can expoit remote capture capabilities. For instance, the
|
|
capabillity to interact with a remote daemon are added to the client software
|
|
without any explicit modification to it. Vice versa, the remote daemon must be
|
|
explicitely installed (and configured) on the remote machine.</p>
|
|
<h2><a name="RunningModes"></a>Remote Capture Running Modes</h2>
|
|
<p>The Remote Capture Protocol (RPCAP) can work in two modes:</p>
|
|
<ul>
|
|
<li><b>Passive Mode</b> (default): the client (e.g. a network sniffer)
|
|
connects to the remote daemon, it sends them the appropriate commands, and
|
|
it starts the capture.</li>
|
|
<li><b>Active Mode</b>: the remote daemon try to establish a connection toward
|
|
the client (e.g. the network sniffer); then, the client sends the
|
|
appropriate commands to the daemon and it starts the capture. This name is
|
|
due to the fact thet the daemon becomes <i>active</i> instead of <i>waiting</i>
|
|
for new connections.</li>
|
|
</ul>
|
|
<p>The Active Mode is useful in case the remote daemon is behind a firewall and
|
|
it cannot receive connections from the external world. In this case, the daemon
|
|
can be configured to establish the connection to a given host, which will have
|
|
been configured in order to <i>wait</i> for that connection. After establishing
|
|
the connection, the protocol continues its job in almost the same way in both
|
|
Active and Passive Mode.</p>
|
|
<p>Analyzer (<a href="http://analyzer.polito.it/30alpha/">http://analyzer.polito.it/30alpha/</a>)
|
|
has a set of commands (in the <b>Capture</b> menu) that allows you to accept a
|
|
remote connection and then start the capture on the remote device. Currently,
|
|
Analyzer is the only tool that is able to work in active mode, since it requires
|
|
some modifications to the application code.</p>
|
|
<h2><a name="Config"></a>Configuring the Remote Daemon (rpcapd)</h2>
|
|
<p>The Remote Daemon is a standard Win32 executable running either in console
|
|
mode or as a service. The executable can be found in the <code>WinPcap</code>
|
|
folder and it has the following syntax:</p>
|
|
<pre> rpcapd [-b <address>] [-p <port>] [-6] [-l <host_list>] [-a <host,port>]
|
|
[-n] [-v] [-d] [-s <file>] [-f <file>]</pre>
|
|
<p>The daemon can be compiled and it is actually working on Linux as well.</p>
|
|
<p>Here there is a brief description of the allowed commands:</p>
|
|
<div align="left">
|
|
<table border="1">
|
|
<tr>
|
|
<th>Switch</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-b <address></pre>
|
|
</td>
|
|
<td>It sets the address the daemon has to bind to (either numeric or
|
|
literal). Default: it binds to all local IPv4 and IPv6 addresses.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-p <port></pre>
|
|
</td>
|
|
<td>It sets the port the daemon has to bind to. Default: it binds to port
|
|
2002.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-4</pre>
|
|
</td>
|
|
<td>It binds only to IPv4 addresses. Default: both IPv4 and IPv6 waiting
|
|
sockets are used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-l <host_list_file></pre>
|
|
</td>
|
|
<td>It specifies a file that keeps the list of the hosts which are allowed
|
|
to connect to this daemon (if more than one, the file keeps them one per
|
|
line). We suggest to use literal names (instead of numeric ones) in
|
|
order to avoid problems with different address families (IPv4 and IPv6).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-n</pre>
|
|
</td>
|
|
<td>It permits NULL authentication (usually used with '-l', that
|
|
guarantees that only the allowed hosts can connect to the daemon).
|
|
Default: the username/password authentication mechanism is required.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-a <host, port></pre>
|
|
</td>
|
|
<td>It forces the daemon to run in active mode and to connect to 'host' on
|
|
port 'port'. This does not exclude that the daemon is still able to
|
|
accept passive connections.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-v</pre>
|
|
</td>
|
|
<td>It forces the daemon to run in active mode only (default: the daemon
|
|
always accepts active connections, even if the '-a' switch is
|
|
specified).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-d</pre>
|
|
</td>
|
|
<td>Forces the daemon to run in background, i.e. as a daemon (UNIX only)
|
|
or as a service (Win32 only). <b>Warning</b> (Win32): this switch is
|
|
provided automatically when WinPcap installs this daemon into the Win32
|
|
services (control panel - administrative tools - services).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-s <file></pre>
|
|
</td>
|
|
<td>It saves the current configuration to file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-f <file></pre>
|
|
</td>
|
|
<td>It loads the current configuration from file; all the switches
|
|
specified from the command line are ignored and the file settings are
|
|
used instead.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>-h</pre>
|
|
</td>
|
|
<td>It prints an help screen.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<h3>Installing the remote daemon</h3>
|
|
<p>The remote daemon is installed automatically when installing WinPcap. The
|
|
installation process places the <code>rpcapd</code> file into the <code>WinPcap</code>
|
|
folder. This file can be executed either from the command line, or as a service.
|
|
For instance, the installation process updates the list of available services
|
|
list and it creates a new item (<b>Remote Packet Capture Protocol v.0
|
|
(experimental)</b> ). To avoid security problems, the service is inactive and it
|
|
has to be started manually (control panel - administrative tools - services -
|
|
start).</p>
|
|
<p>The service has a set of "standard" parameters, i.e. it it launched
|
|
with the "<code>-d</code>" flag (in orde to make it running as a
|
|
service) and the "<code>-f rpcapd.ini</code>" flag. The user can
|
|
create a file called <code>rpcapd.ini</code> in the same folder of the
|
|
executable, and put the configuration commands in there. In order for the
|
|
service to execute the commands, you have to stop and restart it again (i.e. the
|
|
initialization file is parsed only at the beginning). Viceversa, the UNIX
|
|
version of <code>rpcapd</code> is able to read the configuration file when
|
|
sending a kill -HUP signal to it. In that case, all the existing connections
|
|
remain in place, while the new connections will be created according to the new
|
|
parameters.</p>
|
|
<p>In case the user does not want to create the configuration file manually, it
|
|
can launch <code>rpcapd</code> with the requested parameters plus the "<code>-s
|
|
filename</code>" one. The daemon will parse all the parameters and save
|
|
them into the specified configuration file.</p>
|
|
<h3>Starting the remote daemon as a standard executable</h3>
|
|
<p>The <code>rpcapd</code> executable can be launched directly, i.e. it can run
|
|
in the foreground as well (not as a daemon/service). The procedure is quite
|
|
simple: you have to invoke the executable from the command line with all the
|
|
requested parameters but the "<code>-d</code>" flag. The capture
|
|
server will start in the foreground.</p>
|
|
<h2><a name="StartCap"></a>Starting a capture on a remote machine</h2>
|
|
<p>If you are using a tool that is already aware of the remote capture (like
|
|
Analyzer), everything is simple. The capture wizard will help you to locate the
|
|
appropriate interface on the remote machine.</p>
|
|
<p>If your preferred tool is not aware of the remote capture, you can still use
|
|
the remote capture. In this case you have to read the next Section.</p>
|
|
<p><b>Be carefully</b>: the capture server (<code>rpcapd</code>) must be up and
|
|
running on the remote machine.</p>
|
|
<h3>New string specifiers for interface selection</h3>
|
|
<p>If your preferred tool is not aware of the remote capture, the only thing you
|
|
must do is to insert, as interface specifier, the indication of the remote
|
|
machine you want to contact. The following forms are allowed:</p>
|
|
<div align="left">
|
|
<table border="1">
|
|
<tr>
|
|
<th>Adapter String</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>file://filename</pre>
|
|
</td>
|
|
<td>It opens a local file.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://host.foo.bar/adaptername</pre>
|
|
</td>
|
|
<td>It opens a remote adapter; the host is specified by means of the
|
|
literal name, without port number (i.e. it uses the RPCAP default port).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://host.foo.bar:1234/adaptername</pre>
|
|
</td>
|
|
<td>It is the same as before, but it uses a different port number.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://10.11.12.13/adaptername</pre>
|
|
</td>
|
|
<td>It opens a remote adapter, but the host is specified by means of an
|
|
IPv4 numeric address, without port number (i.e. it uses the RPCAP
|
|
default port).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://10.11.12.13:1234/adaptername</pre>
|
|
</td>
|
|
<td>It is the same as before, but it uses a different port number.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://[10.11.12.13]:1234/adaptername</pre>
|
|
</td>
|
|
<td>It is the same as before, but the numeric address is specified within
|
|
square brackets (like IPv6 addresses).</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://[1:2:3::4]/adaptername</pre>
|
|
</td>
|
|
<td>It opens a remote adapter, but the host is specified by means of an
|
|
IPv6 numeric address, without port number (i.e. it uses the RPCAP
|
|
default port). In case of IPv6 addresses you MUST use the square
|
|
brackets.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://[1:2:3::4]:1234/adaptername</pre>
|
|
</td>
|
|
<td>It is the same as before, but it uses a different port number.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://adaptername</pre>
|
|
</td>
|
|
<td>It opens a local adapter, without using the RPCAP protocol.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>adaptername</pre>
|
|
</td>
|
|
<td>It opens a local adapter; it is kept for compability, but it is
|
|
strongly discouraged.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>(NULL)</pre>
|
|
</td>
|
|
<td>It opens the first local adapter; it is kept for compability, but it
|
|
is strongly discouraged.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<p>The following formats are not allowed:</p>
|
|
<table border="1">
|
|
<tr>
|
|
<th>Adapter String</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://</pre>
|
|
</td>
|
|
<td>It cannot be used to open the first local adapter.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<pre>rpcap://hostname/</pre>
|
|
</td>
|
|
<td>It cannot be used to open the first remote adapter.</td>
|
|
</tr>
|
|
</table>
|
|
<h2><a name="UNIX"></a>Installing the Remote Capture Daemon in UNIX</h2>
|
|
<p>The WinPcap source archive can be compiled in UNIX as well. Currently, remote
|
|
capture has been tested on Linux and BSD. What you have to do is:</p>
|
|
<ul>
|
|
<li>download the WinPcap sources</li>
|
|
<li>unpack the sources
|
|
<ul>
|
|
<li>we suggest to use the <code>unzip -a</code> command in order to
|
|
convert DOS files to UNIX ones</li>
|
|
</ul>
|
|
</li>
|
|
<li>move to the <code>libpcap</code> folder</li>
|
|
<li>type:
|
|
<ul>
|
|
<li><code>./configure</code></li>
|
|
<li><b>Warning</b>: in case the previous step reports an error, please
|
|
regenerate the <code>configure</code> file using <code>automake</code>
|
|
(version 2.50 or higher required)</li>
|
|
<li><code>make</code></li>
|
|
</ul>
|
|
</li>
|
|
<li>move to the <code>rpcapd</code> folder</li>
|
|
<li>type <code>make</code></li>
|
|
</ul>
|
|
<p>The remote capture capabilities are turned on by default on Linux and
|
|
FreeBSD. In case you do not want remote capture capabilities in libpcap, you can
|
|
type</p>
|
|
<pre> ./configure --disable-remote</pre>
|
|
<p>at the "<code>configure</code>" step. All the possible flags are
|
|
listed when typing <code>./configure --help</code>.</p>
|
|
<p>What you obtained right now, is:</p>
|
|
<ul>
|
|
<li>a library file (<code>libpcap.a</code>), which can be linked to other
|
|
applications (like <code>tcpdump</code>) in order to enable the remote
|
|
capture for them.</li>
|
|
<li>an executable (<code>rpcapd</code>) that is the remote daemon</li>
|
|
</ul>
|
|
<p><b>Warning</b>: in order to run the <code>rpcapd</code> daemon, the program
|
|
must either</p>
|
|
<ul>
|
|
<li>run as root (or)</li>
|
|
<li>run as user, but it must be owned by root and must be SUID root (<code>chmod
|
|
u+s rpcapd</code>)</li>
|
|
</ul>
|
|
<h3>Known bugs</h3>
|
|
<p><b>FreeBSD</b>: the first time you call the <code>pcap_stat()</code>, the
|
|
function takes several seconds to return. Therefore, programs like Analyzer seem
|
|
to hang up for 20-30 seconds at the beginning of the capture (if this is done
|
|
with BSD as a remote probe). We're investigating to solve this issue.</p>
|
|
<p><i>For any question, please refer to the WinPcap help page.</i></p>
|
|
|
|
</body>
|
|
|
|
</html>
|
|
</div>
|
|
|
|
<hr>
|
|
<p align="right"><img border="0" src="winpcap_small.gif" align="absbottom" width="91" height="27">
|
|
documentation. Copyright (c) 2002-2005 Politecnico di Torino. Copyright (c) 2005-2009
|
|
CACE Technologies. All rights reserved.</p>
|