winpcap/dox/wpcap_remote.htm

   1 <html>
   2
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
   5 <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
   6 <meta name="ProgId" content="FrontPage.Editor.Document">
   7 <title>Using WinPcap Remote Capture</title>
   8 </head>
   9
  10 <body>
  11
  12 <hr>
  13 <ul>
  14   <li><a href="#RunningModes">Remote Capture Running Modes</a></li>
  15   <li><a href="#Config">Configuring the Remote Daemon (rpcapd)</a></li>
  16   <li><a href="#StartCap">Starting a capture on a remote machine</a></li>
  17   <li><a href="#UNIX">Installing the Remote Capture Daemon in UNIX</a></li>
  18 </ul>
  19 <hr>
  20 <p>WinPcap comes with Remote Capture capabilities. This is an highly
  21 experimental feature that allows to interact to a remote machine and capture
  22 packets that are being transmitted on the remote network.</p>
  23 <p>This requires a <b>remote daemon </b>(called <code>rpcapd</code>) which
  24 performs the capture and sends data back and a <b>local client </b>that sends
  25 the appropriate commands and receives the captured data.</p>
  26 <p>WinPcap extends the standard WinPcap code in such a way that all
  27 WinPcap-based tools can expoit remote capture capabilities. For instance, the
  28 capabillity to interact with a remote daemon are added to the client software
  29 without any explicit modification to it. Vice versa, the remote daemon must be
  30 explicitely installed (and configured) on the remote machine.</p>
  31 <h2><a name="RunningModes"></a>Remote Capture Running Modes</h2>
  32 <p>The Remote Capture Protocol (RPCAP) can work in two modes:</p>
  33 <ul>
  34   <li><b>Passive Mode</b> (default): the client (e.g. a network sniffer)
  35     connects to the remote daemon, it sends them the appropriate commands, and
  36     it starts the capture.</li>
  37   <li><b>Active Mode</b>: the remote daemon try to establish a connection toward
  38     the client (e.g. the network sniffer); then, the client sends the
  39     appropriate commands to the daemon and it starts the capture. This name is
  40     due to the fact thet the daemon becomes <i>active</i> instead of <i>waiting</i>
  41     for new connections.</li>
  42 </ul>
  43 <p>The Active Mode is useful in case the remote daemon is behind a firewall and
  44 it cannot receive connections from the external world. In this case, the daemon
  45 can be configured to establish the connection to a given host, which will have
  46 been configured in order to <i>wait</i> for that connection. After establishing
  47 the connection, the protocol continues its job in almost the same way in both
  48 Active and Passive Mode.</p>
  49 <p>Analyzer (<a href="http://analyzer.polito.it/30alpha/">http://analyzer.polito.it/30alpha/</a>)
  50 has a set of commands (in the <b>Capture</b> menu) that allows you to accept a
  51 remote connection and then start the capture on the remote device. Currently,
  52 Analyzer is the only tool that is able to work in active mode, since it requires
  53 some modifications to the application code.</p>
  54 <h2><a name="Config"></a>Configuring the Remote Daemon (rpcapd)</h2>
  55 <p>The Remote Daemon is a standard Win32 executable running either in console
  56 mode or as a service. The executable can be found in the <code>WinPcap</code>
  57 folder and it has the following syntax:</p>
  58 <pre>        rpcapd [-b &lt;address&gt;] [-p &lt;port&gt;] [-6] [-l &lt;host_list&gt;] [-a &lt;host,port&gt;]
  59                [-n] [-v] [-d] [-s &lt;file&gt;] [-f &lt;file&gt;]</pre>
  60 <p>The daemon can be compiled and it is actually working on Linux as well.</p>
  61 <p>Here there is a brief description of the allowed commands:</p>
  62 <div align="left">
  63   <table border="1">
  64     <tr>
  65       <th>Switch</th>
  66       <th>Description</th>
  67     </tr>
  68     <tr>
  69       <td>
  70         <pre>-b &lt;address&gt;</pre>
  71       </td>
  72       <td>It sets the address the daemon has to bind to (either numeric or
  73         literal). Default: it binds to all local IPv4 and IPv6 addresses.</td>
  74     </tr>
  75     <tr>
  76       <td>
  77         <pre>-p &lt;port&gt;</pre>
  78       </td>
  79       <td>It sets the port the daemon has to bind to. Default: it binds to port
  80         2002.</td>
  81     </tr>
  82     <tr>
  83       <td>
  84         <pre>-4</pre>
  85       </td>
  86       <td>It binds only to IPv4 addresses. Default: both IPv4 and IPv6 waiting
  87         sockets are used.</td>
  88     </tr>
  89     <tr>
  90       <td>
  91         <pre>-l &lt;host_list_file&gt;</pre>
  92       </td>
  93       <td>It specifies a file that keeps the list of the hosts which are allowed
  94         to connect to this daemon (if more than one, the file keeps them one per
  95         line). We suggest to use literal names (instead of numeric ones) in
  96         order to avoid problems with different address families (IPv4 and IPv6).</td>
  97     </tr>
  98     <tr>
  99       <td>
 100         <pre>-n</pre>
 101       </td>
 102       <td>It permits NULL authentication (usually used with '-l', that
 103         guarantees that only the allowed hosts can connect to the daemon).
 104         Default: the username/password authentication mechanism is required.</td>
 105     </tr>
 106     <tr>
 107       <td>
 108         <pre>-a &lt;host, port&gt;</pre>
 109       </td>
 110       <td>It forces the daemon to run in active mode and to connect to 'host' on
 111         port 'port'. This does not exclude that the daemon is still able to
 112         accept passive connections.</td>
 113     </tr>
 114     <tr>
 115       <td>
 116         <pre>-v</pre>
 117       </td>
 118       <td>It forces the daemon to run in active mode only (default: the daemon
 119         always accepts active connections, even if the '-a' switch is
 120         specified).</td>
 121     </tr>
 122     <tr>
 123       <td>
 124         <pre>-d</pre>
 125       </td>
 126       <td>Forces the daemon to run in background, i.e. as a daemon (UNIX only)
 127         or as a service (Win32 only). <b>Warning</b> (Win32): this switch is
 128         provided automatically when WinPcap installs this daemon into the Win32
 129         services (control panel - administrative tools - services).</td>
 130     </tr>
 131     <tr>
 132       <td>
 133         <pre>-s &lt;file&gt;</pre>
 134       </td>
 135       <td>It saves the current configuration to file.</td>
 136     </tr>
 137     <tr>
 138       <td>
 139         <pre>-f &lt;file&gt;</pre>
 140       </td>
 141       <td>It loads the current configuration from file; all the switches
 142         specified from the command line are ignored and the file settings are
 143         used instead.</td>
 144     </tr>
 145     <tr>
 146       <td>
 147         <pre>-h</pre>
 148       </td>
 149       <td>It prints an help screen.</td>
 150     </tr>
 151   </table>
 152 </div>
 153 <h3>Installing the remote daemon</h3>
 154 <p>The remote daemon is installed automatically when installing WinPcap. The
 155 installation process places the <code>rpcapd</code> file into the <code>WinPcap</code>
 156 folder. This file can be executed either from the command line, or as a service.
 157 For instance, the installation process updates the list of available services
 158 list and it creates a new item (<b>Remote Packet Capture Protocol v.0
 159 (experimental)</b> ). To avoid security problems, the service is inactive and it
 160 has to be started manually (control panel - administrative tools - services -
 161 start).</p>
 162 <p>The service has a set of &quot;standard&quot; parameters, i.e. it it launched
 163 with the &quot;<code>-d</code>&quot; flag (in orde to make it running as a
 164 service) and the &quot;<code>-f rpcapd.ini</code>&quot; flag. The user can
 165 create a file called <code>rpcapd.ini</code> in the same folder of the
 166 executable, and put the configuration commands in there. In order for the
 167 service to execute the commands, you have to stop and restart it again (i.e. the
 168 initialization file is parsed only at the beginning). Viceversa, the UNIX
 169 version of <code>rpcapd</code> is able to read the configuration file when
 170 sending a kill -HUP signal to it. In that case, all the existing connections
 171 remain in place, while the new connections will be created according to the new
 172 parameters.</p>
 173 <p>In case the user does not want to create the configuration file manually, it
 174 can launch <code>rpcapd</code> with the requested parameters plus the &quot;<code>-s
 175 filename</code>&quot; one. The daemon will parse all the parameters and save
 176 them into the specified configuration file.</p>
 177 <h3>Starting the remote daemon as a standard executable</h3>
 178 <p>The <code>rpcapd</code> executable can be launched directly, i.e. it can run
 179 in the foreground as well (not as a daemon/service). The procedure is quite
 180 simple: you have to invoke the executable from the command line with all the
 181 requested parameters but the &quot;<code>-d</code>&quot; flag. The capture
 182 server will start in the foreground.</p>
 183 <h2><a name="StartCap"></a>Starting a capture on a remote machine</h2>
 184 <p>If you are using a tool that is already aware of the remote capture (like
 185 Analyzer), everything is simple. The capture wizard will help you to locate the
 186 appropriate interface on the remote machine.</p>
 187 <p>If your preferred tool is not aware of the remote capture, you can still use
 188 the remote capture. In this case you have to read the next Section.</p>
 189 <p><b>Be carefully</b>: the capture server (<code>rpcapd</code>) must be up and
 190 running on the remote machine.</p>
 191 <h3>New string specifiers for interface selection</h3>
 192 <p>If your preferred tool is not aware of the remote capture, the only thing you
 193 must do is to insert, as interface specifier, the indication of the remote
 194 machine you want to contact. The following forms are allowed:</p>
 195 <div align="left">
 196   <table border="1">
 197     <tr>
 198       <th>Adapter String</th>
 199       <th>Description</th>
 200     </tr>
 201     <tr>
 202       <td>
 203         <pre>file://filename</pre>
 204       </td>
 205       <td>It opens a local file.</td>
 206     </tr>
 207     <tr>
 208       <td>
 209         <pre>rpcap://host.foo.bar/adaptername</pre>
 210       </td>
 211       <td>It opens a remote adapter; the host is specified by means of the
 212         literal name, without port number (i.e. it uses the RPCAP default port).</td>
 213     </tr>
 214     <tr>
 215       <td>
 216         <pre>rpcap://host.foo.bar:1234/adaptername</pre>
 217       </td>
 218       <td>It is the same as before, but it uses a different port number.</td>
 219     </tr>
 220     <tr>
 221       <td>
 222         <pre>rpcap://10.11.12.13/adaptername</pre>
 223       </td>
 224       <td>It opens a remote adapter, but the host is specified by means of an
 225         IPv4 numeric address, without port number (i.e. it uses the RPCAP
 226         default port).</td>
 227     </tr>
 228     <tr>
 229       <td>
 230         <pre>rpcap://10.11.12.13:1234/adaptername</pre>
 231       </td>
 232       <td>It is the same as before, but it uses a different port number.</td>
 233     </tr>
 234     <tr>
 235       <td>
 236         <pre>rpcap://[10.11.12.13]:1234/adaptername</pre>
 237       </td>
 238       <td>It is the same as before, but the numeric address is specified within
 239         square brackets (like IPv6 addresses).</td>
 240     </tr>
 241     <tr>
 242       <td>
 243         <pre>rpcap://[1:2:3::4]/adaptername</pre>
 244       </td>
 245       <td>It opens a remote adapter, but the host is specified by means of an
 246         IPv6 numeric address, without port number (i.e. it uses the RPCAP
 247         default port). In case of IPv6 addresses you MUST use the square
 248         brackets.</td>
 249     </tr>
 250     <tr>
 251       <td>
 252         <pre>rpcap://[1:2:3::4]:1234/adaptername</pre>
 253       </td>
 254       <td>It is the same as before, but it uses a different port number.</td>
 255     </tr>
 256     <tr>
 257       <td>
 258         <pre>rpcap://adaptername</pre>
 259       </td>
 260       <td>It opens a local adapter, without using the RPCAP protocol.</td>
 261     </tr>
 262     <tr>
 263       <td>
 264         <pre>adaptername</pre>
 265       </td>
 266       <td>It opens a local adapter; it is kept for compability, but it is
 267         strongly discouraged.</td>
 268     </tr>
 269     <tr>
 270       <td>
 271         <pre>(NULL)</pre>
 272       </td>
 273       <td>It opens the first local adapter; it is kept for compability, but it
 274         is strongly discouraged.</td>
 275     </tr>
 276   </table>
 277 </div>
 278 <p>The following formats are not allowed:</p>
 279 <table border="1">
 280   <tr>
 281     <th>Adapter String</th>
 282     <th>Description</th>
 283   </tr>
 284   <tr>
 285     <td>
 286       <pre>rpcap://</pre>
 287     </td>
 288     <td>It cannot be used to open the first local adapter.</td>
 289   </tr>
 290   <tr>
 291     <td>
 292       <pre>rpcap://hostname/</pre>
 293     </td>
 294     <td>It cannot be used to open the first remote adapter.</td>
 295   </tr>
 296 </table>
 297 <h2><a name="UNIX"></a>Installing the Remote Capture Daemon in UNIX</h2>
 298 <p>The WinPcap source archive can be compiled in UNIX as well. Currently, remote
 299 capture has been tested on Linux and BSD. What you have to do is:</p>
 300 <ul>
 301   <li>download the WinPcap sources</li>
 302   <li>unpack the sources
 303     <ul>
 304       <li>we suggest to use the <code>unzip -a</code> command in order to
 305         convert DOS files to UNIX ones</li>
 306     </ul>
 307   </li>
 308   <li>move to the <code>libpcap</code> folder</li>
 309   <li>type:
 310     <ul>
 311       <li><code>./configure</code></li>
 312       <li><b>Warning</b>: in case the previous step reports an error, please
 313         regenerate the <code>configure</code> file using <code>automake</code>
 314         (version 2.50 or higher required)</li>
 315       <li><code>make</code></li>
 316     </ul>
 317   </li>
 318   <li>move to the <code>rpcapd</code> folder</li>
 319   <li>type <code>make</code></li>
 320 </ul>
 321 <p>The remote capture capabilities are turned on by default on Linux and
 322 FreeBSD. In case you do not want remote capture capabilities in libpcap, you can
 323 type</p>
 324 <pre>    ./configure --disable-remote</pre>
 325 <p>at the &quot;<code>configure</code>&quot; step. All the possible flags are
 326 listed when typing <code>./configure --help</code>.</p>
 327 <p>What you obtained right now, is:</p>
 328 <ul>
 329   <li>a library file (<code>libpcap.a</code>), which can be linked to other
 330     applications (like <code>tcpdump</code>) in order to enable the remote
 331     capture for them.</li>
 332   <li>an executable (<code>rpcapd</code>) that is the remote daemon</li>
 333 </ul>
 334 <p><b>Warning</b>: in order to run the <code>rpcapd</code> daemon, the program
 335 must either</p>
 336 <ul>
 337   <li>run as root (or)</li>
 338   <li>run as user, but it must be owned by root and must be SUID root (<code>chmod
 339     u+s rpcapd</code>)</li>
 340 </ul>
 341 <h3>Known bugs</h3>
 342 <p><b>FreeBSD</b>: the first time you call the <code>pcap_stat()</code>, the
 343 function takes several seconds to return. Therefore, programs like Analyzer seem
 344 to hang up for 20-30 seconds at the beginning of the capture (if this is done
 345 with BSD as a remote probe). We're investigating to solve this issue.</p>
 346 <p><i>For any question, please refer to the WinPcap help page.</i></p>
 347
 348 </body>
 349
 350 </html>