doc/man_pages/sshdump.adoc

   1 include::../attributes.adoc[]
   2 = sshdump(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 sshdump - Provide interfaces to capture packets from a remote host through SSH using a remote capture binary.
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *sshdump*
  16 [ *--help* ]
  17 [ *--version* ]
  18 [ *--extcap-interfaces* ]
  19 [ *--extcap-dlts* ]
  20 [ *--extcap-interface*=<interface> ]
  21 [ *--extcap-config* ]
  22 [ *--extcap-capture-filter*=<capture filter> ]
  23 [ *--capture* ]
  24 [ *--fifo*=<path to file or pipe> ]
  25 [ *--remote-host*=<IP address> ]
  26 [ *--remote-port*=<TCP port> ]
  27 [ *--remote-username*=<username> ]
  28 [ *--remote-password*=<password> ]
  29 [ *--sshkey*=<private key path> ]
  30 [ *--sshkey-passphrase*=<private key passphrase> ]
  31 [ *--proxycommand*=<SSH proxy command> ]
  32 [ *--remote-interface*=<interface> ]
  33 [ *--remote-capture-command-select*=<capture command selection> ]
  34 [ *--remote-capture-command*=<capture command> ]
  35 [ *--remote-priv*=<privilege elevation command selection> ]
  36 [ *--remote-priv-user*=<privileged user name> ]
  37 [ *--remote-noprom* ]
  38 [ *--remote-filter*=<remote capture filter> ]
  39 [ *--remote-count*=<number> ]
  40
  41 [manarg]
  42 *sshdump*
  43 *--extcap-interfaces*
  44
  45 [manarg]
  46 *sshdump*
  47 *--extcap-interface*=<interface>
  48 *--extcap-dlts*
  49
  50 [manarg]
  51 *sshdump*
  52 *--extcap-interface*=<interface>
  53 *--extcap-config*
  54
  55 [manarg]
  56 *sshdump*
  57 *--extcap-interface*=<interface>
  58 *--fifo*=<path to file or pipe>
  59 *--capture*
  60 *--remote-host=myremotehost*
  61 *--remote-port=22*
  62 *--remote-username=user*
  63 *--remote-interface=eth2*
  64 *--remote-capture-command='tcpdump -U -i eth0 -w-'*
  65
  66 == DESCRIPTION
  67
  68 *Sshdump* is an extcap tool that allows one to run a remote capture
  69 tool over a SSH connection. The requirement is that the capture
  70 executable must have the capabilities to capture from the wanted
  71 interface.
  72
  73 The feature is functionally equivalent to run commands like
  74
  75     $ ssh remoteuser@remotehost -p 22222 'tcpdump -U -i IFACE -w -' > FILE &
  76     $ wireshark FILE
  77
  78     $ ssh remoteuser@remotehost '/sbin/dumpcap -i IFACE -P -w - -f "not port 22"' > FILE &
  79     $ wireshark FILE
  80
  81     $ ssh somehost dumpcap -P -w - -f udp | tshark -i -
  82
  83 Typically sshdump is not invoked directly. Instead it can be configured through
  84 the Wireshark graphical user interface or its command line. The following will
  85 start Wireshark and start capturing from host *remotehost*:
  86
  87     $ wireshark '-oextcap.sshdump.remotehost:"remotehost"' -i sshdump -k
  88
  89 To explicitly control the remote capture command:
  90
  91     $ wireshark '-oextcap.sshdump.remotehost:"remotehost"' \
  92                 '-oextcap.sshdump.remotecapturecommand:"tcpdump -i eth0 -Uw- not port 22"' \
  93                 -i sshdump -k
  94
  95 Supported interfaces:
  96
  97 1. sshdump
  98
  99 == OPTIONS
 100
 101 --help::
 102 Print program arguments.
 103
 104 --version::
 105 Print program version.
 106
 107 --extcap-interfaces::
 108 List available interfaces.
 109
 110 --extcap-interface=<interface>::
 111 Use specified interfaces.
 112
 113 --extcap-dlts::
 114 List DLTs of specified interface.
 115
 116 --extcap-config::
 117 List configuration options of specified interface.
 118
 119 --extcap-capture-filter=<capture filter>::
 120 The capture filter. It corresponds to the value provided via the *tshark -f*
 121 option, and the Capture Filter field next to the interfaces list in the
 122 Wireshark interface.
 123
 124 --capture::
 125 Start capturing from specified interface and write raw packet data to the location specified by --fifo.
 126
 127 --fifo=<path to file or pipe>::
 128 Save captured packet to file or send it through pipe.
 129
 130 --remote-host=<remote host>::
 131 The address of the remote host for capture.
 132
 133 --remote-port=<remote port>::
 134 The SSH port of the remote host.
 135
 136 --remote-username=<username>::
 137 The username for SSH authentication.
 138
 139 --remote-password=<password>::
 140 The password to use (if not ssh-agent and pubkey are used). WARNING: the
 141 passwords are stored in plaintext and visible to all users on this system. It is
 142 recommended to use keyfiles with a SSH agent.
 143
 144 --sshkey=<SSH private key path>::
 145 The path to a private key for authentication. NOTE: Only OPENSSH key/value pair format is supported.
 146
 147 --sshkey-passphrase=<SSH private key passphrase>::
 148 The passphrase for the private key for authentication.
 149
 150 --proxycommand=<proxy command>::
 151 The command to use as proxy for the SSH connection.
 152 --remote-interface=<remote interface>::
 153 The remote network interface to capture from.
 154
 155 --remote-capture-command-select=<capture command-selection>::
 156 +
 157 --
 158 The selection of the build-in support for remote capture commands. Either *dumpcap* for a remote
 159 capture command using dumpcap, *tcpdump* for a remote capture command using tcpdump, or *other*,
 160 where the remote capture command is to be given with the *--remote-capture-command* option.
 161
 162 Note that selecting dumpcap allows for specifying multiple capture interfaces as a whitespace
 163 separated list, while tcpdump does not.
 164 --
 165
 166 --remote-capture-command=<capture command>::
 167 +
 168 --
 169 A custom remote capture command that produces the remote stream that is shown in Wireshark.
 170 The command must be able to produce a PCAP stream written to STDOUT. See below for more
 171 examples.
 172
 173 If using tcpdump, use the *-w-* option to ensure that packets are written to
 174 standard output (stdout). Include the *-U* option to write packets as soon as
 175 they are received.
 176
 177 When specified, this command will be used as is, options such as the capture
 178 filter (*--extcap-capture-filter*) will not be appended.
 179 --
 180
 181 --remote-priv=<privilege elevation command selection>::
 182 The command to use to achieve privilege elevation to capture on the remote host. Either none, sudo or doas.
 183
 184 --remote-priv-user=<privileged user name>::
 185 If a command is used to achieve privilege elevation to capture on the remote host this may require a user name.
 186 If needed use this option to give that user name.
 187
 188 --remote-filter=<capture filter>::
 189 The remote capture filter. It corresponds to the value provided via the *tshark -f*
 190 option, and the Capture Filter field next to the interfaces list in the
 191 Wireshark interface.
 192
 193 --remote-count=<number>::
 194 The number of packets to capture.
 195
 196 == EXAMPLES
 197
 198 To see program arguments:
 199
 200     sshdump --help
 201
 202 To see program version:
 203
 204     sshdump --version
 205
 206 To see interfaces:
 207
 208     sshdump --extcap-interfaces
 209
 210 Only one interface (sshdump) is supported.
 211
 212 .Example output
 213     interface {value=sshdump}{display=SSH remote capture}
 214
 215 To see interface DLTs:
 216
 217     sshdump --extcap-interface=sshdump --extcap-dlts
 218
 219 .Example output
 220     dlt {number=147}{name=sshdump}{display=Remote capture dependent DLT}
 221
 222 To see interface configuration options:
 223
 224     sshdump --extcap-interface=sshdump --extcap-config
 225
 226 .Example output
 227     arg {number=0}{call=--remote-host}{display=Remote SSH server address}{type=string}
 228         {tooltip=The remote SSH host. It can be both an IP address or a hostname}{required=true}{group=Server}
 229     arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned}{default=22}
 230         {tooltip=The remote SSH host port (1-65535)}{range=1,65535}{group=Server}
 231     arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string}
 232         {tooltip=The remote SSH username. If not provided, the current user will be used}{group=Authentication}
 233     arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=password}
 234         {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}{group=Authentication}
 235     arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect}
 236         {tooltip=The path on the local filesystem of the private SSH key (OpenSSH format)}{mustexist=true}{group=Authentication}
 237     arg {number=5}{call=--sshkey-passphrase}{display=SSH key passphrase}{type=password}
 238         {tooltip=Passphrase to unlock the SSH private key}{group=Authentication}
 239     arg {number=6}{call=--proxycommand}{display=ProxyCommand}{type=string}
 240         {tooltip=The command to use as proxy for the SSH connection}{group=Authentication}
 241     arg {number=7}{call=--remote-interface}{display=Remote interface}{type=string}
 242         {tooltip=The remote network interface used for capture}{group=Capture}
 243     arg {number=8}{call=--remote-capture-command-select}{display=Remote capture command selection}{type=radio}
 244         {tooltip=The remote capture command to build a command line for}{group=Capture}
 245         value {arg=8}{value=dumpcap}{display=dumpcap}
 246         value {arg=8}{value=tcpdump}{display=tcpdump}{default=true}
 247         value {arg=8}{value=other}{display=Other:}
 248     arg {number=9}{call=--remote-capture-command}{display=Remote capture command}{type=string}
 249         {tooltip=The remote command used to capture}{group=Capture}
 250     arg {number=10}{call=--remote-priv}{display=Gain capture privilege on the remote machine}{type=radio}
 251         {tooltip=Optionally prepend the capture command with sudo or doas on the remote machine}{group=Capture}
 252         value {arg=10}{value=none}{display=none}{default=true}
 253         value {arg=10}{value=sudo}{display=sudo}
 254         value {arg=10}{value=doas -n}{display=doas}
 255     arg {number=11}{call=--remote-priv-user}{display=Privileged user name for sudo or doas}{type=string}
 256         {tooltip=User name of privileged user to execute the capture command on the remote machine}{group=Capture}
 257     arg {number=12}{call=--remote-noprom}{display=No promiscuous mode}{type=boolflag}
 258         {tooltip=Don't use promiscuous mode on the remote machine}{group=Capture}
 259     arg {number=13}{call=--remote-filter}{display=Remote capture filter}{type=string}
 260         {tooltip=The remote capture filter}{default=not ((host myhost) and port 22)}{group=Capture}
 261     arg {number=14}{call=--remote-count}{display=Packets to capture}{type=unsigned}{default=0}
 262         {tooltip=The number of remote packets to capture. (Default: inf)}{group=Capture}
 263     arg {number=15}{call=--log-level}{display=Set the log level}{type=selector}
 264         {tooltip=Set the log level}{required=false}{group=Debug}
 265         value {arg=14}{value=message}{display=Message}{default=true}
 266         value {arg=14}{value=info}{display=Info}
 267         value {arg=14}{value=debug}{display=Debug}
 268         value {arg=14}{value=noisy}{display=Noisy}
 269     arg {number=16}{call=--log-file}{display=Use a file for logging}{type=fileselect}
 270         {tooltip=Set a file where log messages are written}{required=false}{group=Debug}
 271
 272
 273 To capture:
 274
 275     sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10
 276     --remote-username user --remote-filter "not port 22"
 277
 278 To use different capture binaries:
 279
 280     sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10
 281     --remote-username user --remote-priv sudo --remote-capture-command-select tcpdump
 282     --remote-interface eth0 --remote-noprom
 283
 284     sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10
 285     --remote-capture-command='dumpcap -i eth0 -P -w -'
 286
 287     sshdump --extcap-interface=sshdump --fifo=/tmp/ssh.pcap --capture --remote-host 192.168.1.10
 288     --remote-capture-command='sudo tcpdump -i eth0 -U -w -'
 289
 290 NOTE: To stop capturing CTRL+C/kill/terminate the application.
 291
 292 The sshdump binary can be renamed to support multiple instances. For instance if we want sshdump
 293 to show up twice in wireshark (for instance to handle multiple profiles), we can copy sshdump to
 294 sshdump-host1 and sshdump-host2. Each binary will show up an interface name same as the executable
 295 name. Those executables not being "sshdump" will show up as "custom version" in the interface description.
 296
 297 == SEE ALSO
 298
 299 xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](1)
 300
 301 == NOTES
 302
 303 *Sshdump* is part of the *Wireshark* distribution.  The latest version
 304 of *Wireshark* can be found at https://www.wireshark.org.
 305
 306 HTML versions of the Wireshark project man pages are available at
 307 https://www.wireshark.org/docs/man-pages.
 308
 309 == AUTHORS
 310
 311 .Original Author
 312 [%hardbreaks]
 313 Dario Lombardo <lomato[AT]gmail.com>