Main Page Modules Data Structures File List Data Fields Globals Related Pages

# wpcap_remote.htm

Go to the documentation of this file.

    00001 <html>
    00002
    00003 <head>
    00004 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
    00005 <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
    00006 <meta name="ProgId" content="FrontPage.Editor.Document">
    00007 <title>Using WinPcap Remote Capture</title>
    00008 </head>
    00009
    00010 <body>
    00011
    00012 <hr>
    00013 <ul>
    00014   <li><a href="#RunningModes">Remote Capture Running Modes</a></li>
    00015   <li><a href="#Config">Configuring the Remote Daemon (rpcapd)</a></li>
    00016   <li><a href="#StartCap">Starting a capture on a remote machine</a></li>
    00017   <li><a href="#UNIX">Installing the Remote Capture Daemon in UNIX</a></li>
    00018 </ul>
    00019
    00020 <hr>
    00021 <p>WinPcap 3.0 comes with Remote Capture capabilities. This is an highly
    00022 experimental feature that allows to interact to a remote machine and capture
    00023 packets that are being transmitted on the remote network.</p>
    00024 <p>This requires a <b>remote daemon </b>(called <code>rpcapd</code>) which performs the
    00025 capture and sends data back and a <b>local client </b>that sends the appropriate
    00026 commands and receives the captured data.</p>
    00027 <p>WinPcap 3.0 extends the standard WinPcap code in such a way that all
    00028 WinPcap-based tools can expoit remote capture capabilities. For instance, the
    00029 capabillity to interact with a remote daemon are added to the client software without any explicit
    00030 modification to it. Vice versa, the remote daemon must be explicitely installed
    00031 (and configured) on the remote machine.</p>
    00032 <h2><a name="RunningModes"></a>Remote Capture Running Modes</h2>
    00033 <p>The Remote Capture Protocol (RPCAP) can work in two modes:</p>
    00034 <ul>
    00035   <li><b>Passive Mode</b> (default): the client (e.g. a network sniffer)
    00036     connects to the remote daemon, it sends them the appropriate commands, and
    00037     it starts the capture.</li>
    00038   <li><b>Active Mode</b>: the remote daemon try to establish a connection toward
    00039     the client (e.g. the network sniffer); then, the client sends the
    00040     appropriate commands to the daemon and it starts the capture. This name is
    00041     due to the fact thet the daemon becomes <i>active</i> instead of <i>waiting</i>
    00042     for new connections.</li>
    00043 </ul>
    00044 <p>The Active Mode is useful in case the remote daemon is behind a firewall and
    00045 it cannot receive connections from the external world. In this case, the daemon
    00046 can be configured to establish the connection to a given host, which will have
    00047 been configured in order to <i>wait</i> for that connection. After establishing
    00048 the connection, the protocol continues its job in almost the same way in both Active
    00049 and Passive Mode.</p>
    00050 <p>Analyzer (<a href="http://analyzer.polito.it/30alpha/">http://analyzer.polito.it/30alpha/</a>)
    00051 has a set of commands (in the <b>Capture</b> menu) that allows you to accept a
    00052 remote connection and then start the capture on the remote device. Currently,
    00053 Analyzer is the only tool that is able to work in active mode, since it requires
    00054 some modifications to the application code.</p>
    00055 <h2><a name="Config"></a>Configuring the Remote Daemon (rpcapd)</h2>
    00056 <p>The Remote Daemon is a standard Win32 executable running either in console
    00057 mode or as a service. The executable can be found in the <code>WinPcap</code>
    00058 folder and it has the following syntax:</p>
    00059 <pre>        rpcapd [-b &lt;address&gt;] [-p &lt;port&gt;] [-6] [-l &lt;host_list&gt;] [-a &lt;host,port&gt;]
    00060                [-n] [-v] [-d] [-s &lt;file&gt;] [-f &lt;file&gt;]</pre>
    00061 <p>The daemon can be compiled and it is actually working on Linux as well.</p>
    00062 <p>Here there is a brief description of the allowed commands:</p>
    00063 <div align="left">
    00064   <table border="1">
    00065     <tr>
    00066       <th>Switch</th>
    00067       <th>Description</th>
    00068     </tr>
    00069     <tr>
    00070       <td>
    00071         <pre>-b &lt;address&gt;</pre>
    00072       </td>
    00073       <td>It sets the address the daemon has to bind to (either numeric or
    00074         literal). Default: it binds to all local IPv4 and IPv6 addresses.</td>
    00075     </tr>
    00076     <tr>
    00077       <td>
    00078         <pre>-p &lt;port&gt;</pre>
    00079       </td>
    00080       <td>It sets the port the daemon has to bind to. Default: it binds to port
    00081         2002.</td>
    00082     </tr>
    00083     <tr>
    00084       <td>
    00085         <pre>-4</pre>
    00086       </td>
    00087       <td>It binds only to IPv4 addresses. Default: both IPv4 and IPv6 waiting
    00088         sockets are used.</td>
    00089     </tr>
    00090     <tr>
    00091       <td>
    00092         <pre>-l &lt;host_list_file&gt;</pre>
    00093       </td>
    00094       <td>It specifies a file that keeps the list of the hosts which are allowed
    00095         to connect to this daemon (if more than one, the file keeps them one per
    00096         line). We suggest to use literal names (instead of numeric ones) in
    00097         order to avoid problems with different address families (IPv4 and IPv6).</td>
    00098     </tr>
    00099     <tr>
    00100       <td>
    00101         <pre>-n</pre>
    00102       </td>
    00103       <td>It permits NULL authentication (usually used with '-l', that
    00104         guarantees that only the allowed hosts can connect to the daemon). Default: the
    00105         username/password authentication mechanism is required.</td>
    00106     </tr>
    00107     <tr>
    00108       <td>
    00109         <pre>-a &lt;host, port&gt;</pre>
    00110       </td>
    00111       <td>It forces the daemon to run in active mode and to connect to 'host' on
    00112         port 'port'. This does not exclude that the daemon is still able to
    00113         accept passive connections.</td>
    00114     </tr>
    00115     <tr>
    00116       <td>
    00117         <pre>-v</pre>
    00118       </td>
    00119       <td>It forces the daemon to run in active mode only (default: the daemon always
    00120         accepts active connections, even if the '-a' switch is specified).</td>
    00121     </tr>
    00122     <tr>
    00123       <td>
    00124         <pre>-d</pre>
    00125       </td>
    00126       <td>Forces the daemon to run in background, i.e. as a daemon (UNIX only)
    00127         or as a service (Win32 only). <b>Warning</b> (Win32): this switch is provided automatically when WinPcap
    00128         installs this daemon into the Win32 services (control panel - administrative
    00129         tools      - services).</td>
    00130     </tr>
    00131     <tr>
    00132       <td>
    00133         <pre>-s &lt;file&gt;</pre>
    00134       </td>
    00135       <td>It saves the current configuration to file.</td>
    00136     </tr>
    00137     <tr>
    00138       <td>
    00139         <pre>-f &lt;file&gt;</pre>
    00140       </td>
    00141       <td>It loads the current configuration from file; all the switches
    00142         specified from the command line are ignored and the file settings are
    00143         used instead.</td>
    00144     </tr>
    00145     <tr>
    00146       <td>
    00147         <pre>-h</pre>
    00148       </td>
    00149       <td>It prints an help screen.</td>
    00150     </tr>
    00151   </table>
    00152 </div>
    00153 <h3>Installing the remote daemon</h3>
    00154 <p>The remote daemon is installed automatically when installing WinPcap 3.0. The
    00155 installation process places the <code>rpcapd</code> file into the <code>WinPcap</code>
    00156 folder. This file can be executed either from the command line, or as a service.
    00157 For instance, the installation process updates the list of available services
    00158 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
    00159 started manually (control panel - administrative tools      - services - start).</p>
    00160 <p>The service has a set of &quot;standard&quot; parameters, i.e. it it launched
    00161 with the &quot;<code>-d</code>&quot; flag (in orde to make it running as a
    00162 service) and the &quot;<code>-f rpcapd.ini</code>&quot; flag. The user can
    00163 create a file called <code>rpcapd.ini</code> in the same folder of the
    00164 executable, and put the configuration commands in there. In order for the service to execute
    00165 the commands, you have to stop and restart it again (i.e. the initialization
    00166 file is parsed only at the beginning). Viceversa, the UNIX version of <code>rpcapd</code>
    00167 is able to read the configuration file when sending a kill -HUP signal to it. In
    00168 that case, all the existing connections remain in place, while the new
    00169 connections will be created according to the new parameters.</p>
    00170 <p>In case the user does not want to create the configuration file manually, it
    00171 can launch <code>rpcapd</code> with the requested parameters plus the &quot;<code>-s
    00172 filename</code>&quot; one. The daemon will parse all the parameters and save
    00173 them into the specified configuration file.</p>
    00174 <h3>Starting the remote daemon as a standard executable</h3>
    00175 <p>The <code>rpcapd</code> executable can be launched directly, i.e. it can run
    00176 in the foreground as well (not as a daemon/service). The procedure is quite
    00177 simple: you have to invoke the executable from the command line with all the
    00178 requested parameters but the &quot;<code>-d</code>&quot; flag. The capture
    00179 server will start in the foreground.</p>
    00180 <h2><a name="StartCap"></a>Starting a capture on a remote machine</h2>
    00181 <p>If you are using a tool that is already aware of the remote capture (like
    00182 Analyzer), everything is simple. The capture wizard will help you to locate the
    00183 appropriate interface on the remote machine.</p>
    00184 <p>If your preferred tool is not aware of the remote capture, you can still use
    00185 the remote capture. In this case you have to read the next Section.</p>
    00186 <p><b>Be carefully</b>: the capture server (<code>rpcapd</code>) must be up and
    00187 running on the remote machine.</p>
    00188 <h3>New string specifiers for interface selection</h3>
    00189 <p>If your preferred tool is not aware of the remote capture, the only thing you
    00190 must do is to insert, as interface specifier, the indication of the remote
    00191 machine you want to contact. The following forms are allowed:</p>
    00192 <div align="left">
    00193   <table border="1">
    00194     <tr>
    00195       <th>Adapter String</th>
    00196       <th>Description</th>
    00197     </tr>
    00198     <tr>
    00199       <td>
    00200         <pre>file://filename</pre>
    00201       </td>
    00202       <td>It opens a local file.</td>
    00203     </tr>
    00204     <tr>
    00205       <td>
    00206         <pre>rpcap://host.foo.bar/adaptername</pre>
    00207       </td>
    00208       <td>It opens a remote adapter; the host is specified by means of the
    00209         literal name, without port number (i.e. it uses the RPCAP default port).</td>
    00210     </tr>
    00211     <tr>
    00212       <td>
    00213         <pre>rpcap://host.foo.bar:1234/adaptername</pre>
    00214       </td>
    00215       <td>It is the same as before, but it uses a different port number.</td>
    00216     </tr>
    00217     <tr>
    00218       <td>
    00219         <pre>rpcap://10.11.12.13/adaptername</pre>
    00220       </td>
    00221       <td>It opens a remote adapter, but the host is specified by means of an
    00222         IPv4 numeric address, without port number (i.e. it uses the RPCAP
    00223         default port).</td>
    00224     </tr>
    00225     <tr>
    00226       <td>
    00227         <pre>rpcap://10.11.12.13:1234/adaptername</pre>
    00228       </td>
    00229       <td>It is the same as before, but it uses a different port number.</td>
    00230     </tr>
    00231     <tr>
    00232       <td>
    00233         <pre>rpcap://[10.11.12.13]:1234/adaptername</pre>
    00234       </td>
    00235       <td>It is the same as before, but the numeric address is specified within
    00236         square brackets (like IPv6 addresses).</td>
    00237     </tr>
    00238     <tr>
    00239       <td>
    00240         <pre>rpcap://[1:2:3::4]/adaptername</pre>
    00241       </td>
    00242       <td>It opens a remote adapter, but the host is specified by means of an
    00243         IPv6 numeric address, without port number (i.e. it uses the RPCAP
    00244         default port). In case of IPv6 addresses you MUST use the square
    00245         brackets. </td>
    00246     </tr>
    00247     <tr>
    00248       <td>
    00249         <pre>rpcap://[1:2:3::4]:1234/adaptername</pre>
    00250       </td>
    00251       <td>It is the same as before, but it uses a different port number.</td>
    00252     </tr>
    00253     <tr>
    00254       <td>
    00255         <pre>rpcap://adaptername</pre>
    00256       </td>
    00257       <td>It opens a local adapter, without using the RPCAP protocol.</td>
    00258     </tr>
    00259     <tr>
    00260       <td>
    00261         <pre>adaptername</pre>
    00262       </td>
    00263       <td>It opens a local adapter; it is kept for compability, but it is
    00264         strongly discouraged.</td>
    00265     </tr>
    00266     <tr>
    00267       <td>
    00268         <pre>(NULL)</pre>
    00269       </td>
    00270       <td>It opens the first local adapter; it is kept for compability, but it
    00271         is strongly discouraged.</td>
    00272     </tr>
    00273   </table>
    00274 </div>
    00275 <p>The following formats are not allowed:</p>
    00276 <table border="1">
    00277   <tr>
    00278     <th>Adapter String</th>
    00279     <th>Description</th>
    00280   </tr>
    00281   <tr>
    00282     <td>
    00283       <pre>rpcap://</pre>
    00284     </td>
    00285     <td>It cannot be used to open the first local adapter.</td>
    00286   </tr>
    00287   <tr>
    00288     <td>
    00289       <pre>rpcap://hostname/</pre>
    00290     </td>
    00291     <td>It cannot be used to open the first remote adapter.</td>
    00292   </tr>
    00293 </table>
    00294 <h2><a name="UNIX"></a>Installing the Remote Capture Daemon in UNIX</h2>
    00295 <p>The WinPcap source archive can be compiled in UNIX as well. Currently, remote
    00296 capture has been tested on Linux and BSD. What you have to do is:</p>
    00297 <ul>
    00298   <li>download the WinPcap sources</li>
    00299   <li>unpack the sources
    00300     <ul>
    00301       <li>we suggest using the <code>unzip -a</code> tool in order o convert DOS
    00302         files to UNIX ones</li>
    00303     </ul>
    00304   </li>
    00305   <li>move to the <code>libpcap</code> folder</li>
    00306   <li>type:
    00307     <ul>
    00308       <li><code>autoconf</code></li>
    00309       <li> <code>./configure</code></li>
    00310       <li> <code>make</code></li>
    00311     </ul>
    00312   </li>
    00313   <li>move to the <code>rpcapd</code> folder</li>
    00314   <li>type <code>make</code></li>
    00315 </ul>
    00316 <p>What you obtained right now, is:</p>
    00317 <ul>
    00318   <li>a library file (<code>libpcap.a</code>), which can be linked to other
    00319     applications (like <code>tcpdump</code>) in order to enable the remote
    00320     capture for them.</li>
    00321   <li>an executable (<code>rpcapd</code>) that is the remote daemon</li>
    00322 </ul>
    00323 <p><b>Warning</b>: in order to run the <code>rpcapd</code> daemon, the program must
    00324 either</p>
    00325 <ul>
    00326   <li> run as root (or)</li>
    00327   <li>run as user, but it
    00328 must be owned by root and must be SUID root (<code>chmod u+s rpcapd</code>)</li>
    00329 </ul>
    00330 <h3>Known bugs</h3>
    00331
    00332 <p><b>FreeBSD</b>: the first time you call the <code>pcap_stat()</code>, the
    00333 function takes several seconds to return. Therefore, programs like Analyzer seem
    00334 to hang up for 20-30 seconds at the beginning of the capture (if this is done
    00335 with BSD as a remote probe). We're investigating how to solve this issue.</p>
    00336
    00337 <p><i>For any question, please refer to the WinPcap help page.</i></p>
    00338
    00339 </body>
    00340
    00341 </html>

documentation. Copyright (c) 2002-2003 Politecnico di Torino. All rights reserved.