contrib/libpcap/rpcapd/rpcapd.manadmin.in

   1 .\"  rpcapd.8
   2 .\"
   3 .\"  Copyright (c) 2002-2005 NetGroup, Politecnico di Torino (Italy)
   4 .\"  Copyright (c) 2005-2009 CACE Technologies
   5 .\"  Copyright (c) 2018-     The TCPdump Group
   6 .\"  All rights reserved.
   7 .\"
   8 .\"  Redistribution and use in source and binary forms, with or without
   9 .\"  modification, are permitted provided that the following conditions
  10 .\"  are met:
  11 .\"
  12 .\"  1. Redistributions of source code must retain the above copyright
  13 .\"  notice, this list of conditions and the following disclaimer.
  14 .\"  2. Redistributions in binary form must reproduce the above copyright
  15 .\"  notice, this list of conditions and the following disclaimer in the
  16 .\"  documentation and/or other materials provided with the distribution.
  17 .\"  3. Neither the name of the Politecnico di Torino nor the names of its
  18 .\"  contributors may be used to endorse or promote products derived from
  19 .\"  this software without specific prior written permission.
  20 .\"
  21 .\"  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\"  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\"  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24 .\"  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25 .\"  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26 .\"  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27 .\"  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28 .\"  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29 .\"  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30 .\"  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31 .\"  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .TH RPCAPD @MAN_ADMIN_COMMANDS@ "April 20, 2018"
  34 .SH NAME
  35 rpcapd \- capture daemon to be controlled by a remote libpcap application
  36 .SH SYNOPSIS
  37 .na
  38 rpcapd
  39 [
  40 .B \-b
  41 .I address
  42 ] [
  43 .B \-p
  44 .I port
  45 ] [
  46 .B \-4
  47 ] [
  48 .B \-l
  49 .I host_list
  50 ]
  51 .br
  52 .ti +8
  53 [
  54 .B \-a
  55 .IR host , port
  56 ] [
  57 .B \-n
  58 ] [
  59 .B \-v
  60 ] [
  61 .B \-d
  62 ] [
  63 .B \-i
  64 ]
  65 .br
  66 .ti +8
  67 [
  68 .B \-D
  69 ] [
  70 .B \-s
  71 .I config_file
  72 ] [
  73 .B \-f
  74 .I config_file
  75 ]
  76 .br
  77 .ad
  78 .SH DESCRIPTION
  79 .LP
  80 \fIRpcapd\fP is a daemon (Unix) or service (Win32) that allows the capture
  81 and filter part of libpcap to be run on a remote system.
  82 .LP
  83 Rpcapd can run in two modes: passive mode (default) and active mode.
  84 .LP
  85 In passive mode, the client (e.g., a network sniffer) connects to
  86 .BR rpcapd .
  87 It then sends hem the appropriate commands to start the capture.
  88 .LP
  89 In active mode,
  90 .B rpcapd
  91 tries to establish a connection toward the client
  92 (e.g., a network sniffer). The client then sends the appropriate commands
  93 to rpcapd to start the capture.
  94 .LP
  95 Active mode is useful in case
  96 .B rpcapd
  97 is run behind a firewall and
  98 cannot receive connections from the external world. In this case,
  99 .B rpcapd
 100 can be configured to establish the connection to a given host,
 101 which has to be configured in order to wait for that connection. After
 102 establishing the connection, the protocol continues its job in almost
 103 the same way in both active and passive mode.
 104 .SH Configuration file
 105 .LP
 106 The user can create a configuration file in the same folder of the
 107 executable, and put the configuration commands in there. In order for
 108 rpcapd to execute the commands, you have to restart it on Win32, i.e.
 109 the initialization file is parsed only at the beginning). The UNIX
 110 version of rpcapd will reread the configuration file when receiving a
 111 HUP signel. In that case, all the existing connections remain in place,
 112 while the new connections will be created according to the new parameters.
 113 .LP
 114 In case a user does not want to create the configuration file manually,
 115 they can launch rpcapd with the requested parameters plus "-s filename".
 116 Rpcapd will parse all the parameters and save them into the specified
 117 configuration file.
 118 .SH Installing rpcapd on Win32
 119 .LP
 120 The remote daemon is installed automatically when installing WinPcap.
 121 The installation process places the rpcapd file into the WinPcap folder.
 122 This file can be executed either from the command line, or as a service.
 123 For instance, the installation process updates the list of available
 124 services list and it creates a new item (Remote Packet Capture Protocol
 125 v.0 (experimental) ).  To avoid security problems, the service is
 126 inactive and it has to be started manually (control panel -
 127 administrative tools - services - start).
 128 .LP
 129 The service has a set of "standard" parameters, i.e. it is launched
 130 with the
 131 .B \-d
 132 flag (in order to make it run as a service) and the
 133 .B "-f rpcapd.ini"
 134 flag.
 135 .SH Starting rpcapd on Win32
 136 .LP
 137 The rpcapd executable can be launched directly, i.e.  it can run in the
 138 foreground as well (not as a daemon/service).  The procedure is quite
 139 simple: you have to invoke the executable from the command line with all
 140 the requested parameters except for the
 141 .B \-d
 142 flag.  The capture server will
 143 start in the foreground.
 144 .SH Installing rpcapd on Unix-like systems
 145 TBD
 146 .SH Starting rpcapd on Unix-like systems
 147 .B rpcapd
 148 needs sufficient privileges to perform packet capture, e.g.
 149 run as root or be owned by root and have suid set. Most operating
 150 systems provide more elegant solutions when run as user than the
 151 above solutions, all of them different.
 152 .SH OPTIONS
 153 .TP
 154 .BI \-b " address"
 155 Bind to the IP address specified by
 156 .I address
 157 (either numeric or literal).
 158 By default,
 159 .B rpcapd
 160 binds to all local IPv4 and IPv6 addresses.
 161 .TP
 162 .BI \-p " port"
 163 Bind to the port specified by
 164 .IR port .
 165 By default,
 166 .B rpcapd
 167 binds to port 2002.
 168 .TP
 169 .B \-4
 170 Listen only on IPv4 addresses.
 171 By default,
 172 .B rpcapd
 173 listens on both IPv4 and IPv6 addresses.
 174 .TP
 175 .BI -l " host_list"
 176 Only allow hosts specified in the
 177 .I host_list
 178 argument to connect to this server.
 179 .I host_list
 180 is a list of host names or IP addresses, separated by commas.
 181 We suggest that you use use host names rather than literal IP addresses
 182 in order to avoid problems with different address families.
 183 .TP
 184 .B \-n
 185 Permit NULL authentication (usually used with
 186 .BR \-l ).
 187 .TP
 188 .BI \-a " host" , "port"
 189 Run in active mode, connecting to host
 190 .I host
 191 on port
 192 .IR port .
 193 In case
 194 .I port
 195 is omitted, the default port (2003) is used.
 196 .TP
 197 .B -v
 198 Run in active mode only; by default, if
 199 .B \-a
 200 is specified,
 201 .B rpcapd
 202 it accepts passive connections as well.
 203 .TP
 204 .B \-d
 205 Run in daemon mode (UNIX only) or as a service (Win32 only)
 206 Warning (Win32): this switch is provided automatically when
 207 the service is started from the control panel.
 208 .TP
 209 .B \-i
 210 Run in inetd mode (UNIX only).
 211 .TP
 212 .B \-D
 213 Log debugging messages.
 214 .TP
 215 .BI \-s " config_file"
 216 Save the current configuration to
 217 .I config_file
 218 in the format specified by
 219 .BR rpcapd-config (@MAN_FILE_FORMATS@).
 220 .TP
 221 .BI \-f " config_file"
 222 Load the current configuration from
 223 .I config_file
 224 in the format specified by
 225 .BR rpcapd-config (@MAN_FILE_FORMATS@);
 226 all switches specified from the command line are ignored.
 227 .TP
 228 .B \-h
 229 Print this help screen.
 230 .br
 231 .ad
 232 .SH "SEE ALSO"
 233 pcap(3PCAP), rpcapd-config(@MAN_FILE_FORMATS@)