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@ "21 August 2024"
  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 \-t
  47 .I data_port
  48 ] [
  49 .B \-4
  50 ]
  51 .ti +8
  52 [
  53 .B \-l
  54 .I host_list
  55 ] [
  56 .B \-a
  57 .IR host , port
  58 ] [
  59 .B \-n
  60 ] [
  61 .B \-v
  62 ] [
  63 .B \-d
  64 ] [
  65 .B \-i
  66 ]
  67 .ti +8
  68 [
  69 .B \-D
  70 ] [
  71 .B \-s
  72 .I config_file
  73 ]
  74 [
  75 .B \-f
  76 .I config_file
  77 ]
  78 [
  79 .B \-S
  80 ]
  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 .IR rpcapd .
 102 The client then sends the appropriate commands to
 103 .I rpcapd
 104 to start the capture.
 105 .LP
 106 In active mode,
 107 .I 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 .I rpcapd
 114 is run behind a firewall and
 115 cannot receive connections from the external world. In this case,
 116 .I 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 .I 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 .I rpcapd
 130 will reread the configuration file upon receiving a
 131 .B HUP
 132 signal. In that case, all the existing connections remain in place,
 133 while the new connections will be created according to the new parameters.
 134 .LP
 135 In case a user does not want to create the configuration file manually,
 136 they can launch
 137 .I rpcapd
 138 with the desired flags plus
 139 .BR "-s filename" .
 140 Rpcapd will parse all the parameters and save them into the specified
 141 configuration file.
 142 .SH Installing rpcapd on Win32
 143 .LP
 144 The remote daemon is installed automatically when installing WinPcap.
 145 The installation process places the
 146 .I rpcapd
 147 executable file into the WinPcap folder.
 148 This file can be executed either from the command line, or as a service.
 149 For instance, the installation process updates the list of available
 150 services list and it creates a new item (Remote Packet Capture Protocol
 151 v.0 (experimental)).  To avoid security problems, the service is
 152 inactive and it has to be started manually (control panel -
 153 administrative tools - services - start).
 154 .LP
 155 The service has a set of "standard" parameters, i.e. it is launched
 156 with the
 157 .B \-d
 158 flag (in order to make it run as a service) and the
 159 .B "-f rpcapd.ini"
 160 flag.
 161 .SH Starting rpcapd on Win32
 162 .LP
 163 The
 164 .I rpcapd
 165 executable can be launched directly, i.e.  it can run in the
 166 foreground as well (not as a daemon/service).  The procedure is quite
 167 simple: you have to invoke the executable from the command line with all
 168 the requested parameters except for the
 169 .B \-d
 170 flag.  The capture server will
 171 start in the foreground.
 172 .SH Installing rpcapd on Unix-like systems
 173 TBD
 174 .SH Starting rpcapd on Unix-like systems
 175 .I rpcapd
 176 needs sufficient privileges to perform packet capture, e.g.
 177 run as root or be owned by root and have suid set. Most operating
 178 systems provide more elegant solutions when run as user than the
 179 above solutions, all of them different.
 180 .LP
 181 If your system supports
 182 .BR systemd (1)
 183 and the corresponding
 184 .B rpcapd.socket
 185 and
 186 .B rpcapd@.service
 187 service files have been
 188 installed, the rpcapd service can be enabled by enabling the
 189 .B rpcapd.socket
 190 unit.
 191 .LP
 192 If your system supports
 193 .BR launchd (@MAN_ADMIN_COMMANDS@)
 194 and the
 195 .B org.tcpdump.rpcapd.plist
 196 file has been installed, the rpcapd service can be enabled by loading
 197 the
 198 .B org.tcpdump.rpcapd
 199 service.
 200 .LP
 201 If your system supports
 202 .BR inetd (@MAN_ADMIN_COMMANDS@)
 203 and the
 204 .B rpcapd.inetd.conf
 205 entry has been added to
 206 .BR inetd.conf (@MAN_FILE_FORMATS@),
 207 the rpcapd service can be enabled by telling inetd
 208 to reread its configuration file.
 209 .LP
 210 If your system supports
 211 .BR xinetd (@MAN_ADMIN_COMMANDS@)
 212 and the
 213 .B rpcapd.xinetd.conf
 214 entry has been added to
 215 .BR xinetd.conf (@MAN_FILE_FORMATS@),
 216 the rpcapd service can be enabled by telling xinetd
 217 to reread its configuration file.
 218 .SH OPTIONS
 219 .TP
 220 .BI \-b " address"
 221 Bind to the IP address specified by
 222 .I address
 223 (either numeric or literal).
 224 By default,
 225 .I rpcapd
 226 binds to all local IPv4 and IPv6 addresses.
 227 .TP
 228 .BI \-p " port"
 229 Bind to the port specified by
 230 .IR port .
 231 By default,
 232 .I rpcapd
 233 binds to port 2002.
 234 .TP
 235 .BI \-t " data_port"
 236 Use the port specified by
 237 .I data_port
 238 as the port for data transfer.
 239 By default,
 240 .I rpcapd
 241 uses a port chosen by the operating system.
 242 .TP
 243 .B \-4
 244 Listen only on IPv4 addresses.
 245 By default,
 246 .I rpcapd
 247 listens on both IPv4 and IPv6 addresses.
 248 .TP
 249 .BI \-l " host_list"
 250 Only allow hosts specified in the
 251 .I host_list
 252 argument to connect to this server.
 253 .I host_list
 254 is a list of host names or IP addresses, separated by commas.
 255 We suggest that you use host names rather than literal IP addresses
 256 in order to avoid problems with different address families.
 257 .TP
 258 .B \-n
 259 Permit NULL authentication (usually used with the
 260 .B \-l
 261 flag).
 262 .TP
 263 .BI \-a " host" , "port"
 264 Run in active mode, connecting to host
 265 .I host
 266 on port
 267 .IR port .
 268 In case
 269 .I port
 270 is omitted, the default port (2003) is used.
 271 .TP
 272 .B -v
 273 Run in active mode only; by default, if
 274 .B \-a
 275 is specified,
 276 .I rpcapd
 277 accepts passive connections as well.
 278 .TP
 279 .B \-d
 280 Run in daemon mode (UNIX only) or as a service (Win32 only).
 281 Warning (Win32): this flag is specified automatically when
 282 the service is started from the control panel.
 283 .TP
 284 .B \-i
 285 Run in inetd mode (UNIX only).
 286 .TP
 287 .B \-D
 288 Log debugging messages.
 289 .TP
 290 .BI \-s " config_file"
 291 Save the current configuration to
 292 .I config_file
 293 in the format specified by
 294 .BR rpcapd-config (@MAN_FILE_FORMATS@).
 295 .TP
 296 .BI \-f " config_file"
 297 Load the current configuration from
 298 .I config_file
 299 in the format specified by
 300 .BR rpcapd-config (@MAN_FILE_FORMATS@)
 301 and ignore all flags specified on the command line.
 302 .TP
 303 .B \-h
 304 Print this help screen.
 305 .LP
 306 If
 307 .I rpcapd
 308 was compiled with SSL support, the following options are also
 309 available:
 310 .TP
 311 .B \-S
 312 Require that SSL be used on connections.
 313 .TP
 314 .B \-C
 315 With SSL enabled, XXX - I'm not sure how *fetching* the list of
 316 compression mechanisms does anything to compression.
 317 .TP
 318 .BI \-K " ssl_keyfile"
 319 With SSL enabled, use
 320 .I ssl_keyfile
 321 as the SSL key file.
 322 .TP
 323 .BI \-X " ssl_certfile"
 324 With SSL enabled, use
 325 .I ssl_certfile
 326 as the SSL certificate file.
 327 .br
 328 .ad
 329 .SH "SEE ALSO"
 330 .BR pcap (3PCAP),
 331 .BR rpcapd-config (@MAN_FILE_FORMATS@)