The Tcpdump Group git mirrors - libpcap/blob - 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@ "13 January 2019"
  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 [
  74 .B \-f
  75 .I config_file
  76 ]
  77 [
  78 .B \-S
  79 ]
  80 .br
  81 .ti +8
  82 [
  83 .B \-K
  84 .I ssl_keyfile
  85 ] [
  86 .B \-X
  87 .I ssl_certfile
  88 ] [
  89 .B \-C
  90 ]
  91 .br
  92 .ad
  93 .SH DESCRIPTION
  94 .LP
  95 \fIRpcapd\fP is a daemon (Unix) or service (Win32) that allows the capture
  96 and filter part of libpcap to be run on a remote system.
  97 .LP
  98 Rpcapd can run in two modes: passive mode (default) and active mode.
  99 .LP
 100 In passive mode, the client (e.g., a network sniffer) connects to
 101 .BR rpcapd .
 102 The client then sends the appropriate commands to
 103 .B rpcapd
 104 to start the capture.
 105 .LP
 106 In active mode,
 107 .B rpcapd
 108 tries to establish a connection toward the client
 109 (e.g., a network sniffer). The client then sends the appropriate commands
 110 to rpcapd to start the capture.
 111 .LP
 112 Active mode is useful in case
 113 .B rpcapd
 114 is run behind a firewall and
 115 cannot receive connections from the external world. In this case,
 116 .B rpcapd
 117 can be configured to establish the connection to a given host,
 118 which has to be configured in order to wait for that connection. After
 119 establishing the connection, the protocol continues its job in almost
 120 the same way in both active and passive mode.
 121 .SH Configuration file
 122 .LP
 123 The user can create a configuration file in the same directory as the
 124 executable, and put the configuration commands in there. In order for
 125 .B rpcapd
 126 to execute the commands, it needs to be restarted on Win32, i.e.
 127 the configuration file is parsed only at the beginning. The UNIX
 128 version of
 129 .B rpcapd
 130 will reread the configuration file upon receiving a
 131 HUP signal. In that case, all the existing connections remain in place,
 132 while the new connections will be created according to the new parameters.
 133 .LP
 134 In case a user does not want to create the configuration file manually,
 135 they can launch
 136 .B rpcapd
 137 with the desired flags plus
 138 .BR "-s filename" .
 139 Rpcapd will parse all the parameters and save them into the specified
 140 configuration file.
 141 .SH Installing rpcapd on Win32
 142 .LP
 143 The remote daemon is installed automatically when installing WinPcap.
 144 The installation process places the
 145 .B rpcapd
 146 executable file into the WinPcap folder.
 147 This file can be executed either from the command line, or as a service.
 148 For instance, the installation process updates the list of available
 149 services list and it creates a new item (Remote Packet Capture Protocol
 150 v.0 (experimental)).  To avoid security problems, the service is
 151 inactive and it has to be started manually (control panel -
 152 administrative tools - services - start).
 153 .LP
 154 The service has a set of "standard" parameters, i.e. it is launched
 155 with the
 156 .B \-d
 157 flag (in order to make it run as a service) and the
 158 .B "-f rpcapd.ini"
 159 flag.
 160 .SH Starting rpcapd on Win32
 161 .LP
 162 The
 163 .B rpcapd
 164 executable can be launched directly, i.e.  it can run in the
 165 foreground as well (not as a daemon/service).  The procedure is quite
 166 simple: you have to invoke the executable from the command line with all
 167 the requested parameters except for the
 168 .B \-d
 169 flag.  The capture server will
 170 start in the foreground.
 171 .SH Installing rpcapd on Unix-like systems
 172 TBD
 173 .SH Starting rpcapd on Unix-like systems
 174 .B rpcapd
 175 needs sufficient privileges to perform packet capture, e.g.
 176 run as root or be owned by root and have suid set. Most operating
 177 systems provide more elegant solutions when run as user than the
 178 above solutions, all of them different.
 179 .SH OPTIONS
 180 .TP
 181 .BI \-b " address"
 182 Bind to the IP address specified by
 183 .I address
 184 (either numeric or literal).
 185 By default,
 186 .B rpcapd
 187 binds to all local IPv4 and IPv6 addresses.
 188 .TP
 189 .BI \-p " port"
 190 Bind to the port specified by
 191 .IR port .
 192 By default,
 193 .B rpcapd
 194 binds to port 2002.
 195 .TP
 196 .B \-4
 197 Listen only on IPv4 addresses.
 198 By default,
 199 .B rpcapd
 200 listens on both IPv4 and IPv6 addresses.
 201 .TP
 202 .BI -l " host_list"
 203 Only allow hosts specified in the
 204 .I host_list
 205 argument to connect to this server.
 206 .I host_list
 207 is a list of host names or IP addresses, separated by commas.
 208 We suggest that you use host names rather than literal IP addresses
 209 in order to avoid problems with different address families.
 210 .TP
 211 .B \-n
 212 Permit NULL authentication (usually used with
 213 .BR \-l ).
 214 .TP
 215 .BI \-a " host" , "port"
 216 Run in active mode, connecting to host
 217 .I host
 218 on port
 219 .IR port .
 220 In case
 221 .I port
 222 is omitted, the default port (2003) is used.
 223 .TP
 224 .B -v
 225 Run in active mode only; by default, if
 226 .B \-a
 227 is specified,
 228 .B rpcapd
 229 it accepts passive connections as well.
 230 .TP
 231 .B \-d
 232 Run in daemon mode (UNIX only) or as a service (Win32 only).
 233 Warning (Win32): this flag is specified automatically when
 234 the service is started from the control panel.
 235 .TP
 236 .B \-i
 237 Run in inetd mode (UNIX only).
 238 .TP
 239 .B \-D
 240 Log debugging messages.
 241 .TP
 242 .BI \-s " config_file"
 243 Save the current configuration to
 244 .I config_file
 245 in the format specified by
 246 .BR rpcapd-config (@MAN_FILE_FORMATS@).
 247 .TP
 248 .BI \-f " config_file"
 249 Load the current configuration from
 250 .I config_file
 251 in the format specified by
 252 .BR rpcapd-config (@MAN_FILE_FORMATS@)
 253 and ignore all flags specified on the command line.
 254 .TP
 255 .B \-h
 256 Print this help screen.
 257 .LP
 258 If
 259 .B rpcapd
 260 was compiled with SSL support, the following options are also
 261 available:
 262 .TP
 263 .B \-S
 264 Require that SSL be used on connections.
 265 .TP
 266 .B \-C
 267 With SSL enabled, XXX - I'm not sure how *fetching* the list of
 268 compression mechanisms does anything to compression.
 269 .TP
 270 .B \-S
 271 .I ssl_keyfile
 272 With SSL enabled, use
 273 .I ssl_keyfile
 274 as the SSL key file.
 275 .TP
 276 .B \-X
 277 .I ssl_certfile
 278 With SSL enabled, use
 279 .I ssl_certfile
 280 as the SSL certificate file.
 281 .br
 282 .ad
 283 .SH "SEE ALSO"
 284 .BR pcap (3PCAP),
 285 .BR rpcapd-config (@MAN_FILE_FORMATS@)