doc/man_pages/wifidump.adoc

   1 include::../attributes.adoc[]
   2 = wifidump(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 wifidump - Provides an interface to capture Wi-Fi frames from a remote host through SSH.
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *wifidump*
  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*=<public key path> ]
  30 [ *--remote-interface*=<interface> ]
  31 [ *--remote-channel-frequency*=<channel frequency> ]
  32 [ *--remote-channel-width*=<channel width> ]
  33
  34 [manarg]
  35 *wifidump*
  36 *--extcap-interfaces*
  37
  38 [manarg]
  39 *wifidump*
  40 *--extcap-interface*=<interface>
  41 *--extcap-dlts*
  42
  43 [manarg]
  44 *wifidump*
  45 *--extcap-interface*=<interface>
  46 *--extcap-config*
  47
  48 [manarg]
  49 *wifidump*
  50 *--extcap-interface*=<interface>
  51 *--fifo*=<path to file or pipe>
  52 *--capture*
  53 *--remote-host=myremotehost*
  54 *--remote-port=22*
  55 *--remote-username=user*
  56 *--remote-interface=eth2*
  57 *--remote-channel-frequency=5180*
  58 *--remote-channel-width=40*
  59
  60 == DESCRIPTION
  61
  62 *Wifidump* is an extcap tool that allows you to capture Wi-Fi traffic from a
  63 remote host over an SSH connection using *tcpdump*. The requirement to capture Wi-Fi
  64 frames is that the remote host must have the necessary binaries to manage and put
  65 the wanted interface into monitor mode. Such binaries include: *ip*, *iw*, and
  66 *iwconfig*. Also, because using monitor mode and managing the Wi-Fi interface requires
  67 root privileges, the system must be configured to allow the wanted user to run
  68 these binaries using sudo without entering a password.
  69
  70 Typically wifidump is not invoked directly. Instead it can be configured through
  71 the Wireshark graphical user interface or its command line. The following will
  72 start Wireshark and start capturing from host *remotehost*:
  73
  74     $ wireshark '-oextcap.wifidump.remotehost:remotehost' -i wifidump -k
  75
  76 To explicitly control the remote capture command:
  77
  78     $ wireshark '-oextcap.wifidump.remotehost:remotehost' \
  79                 '-oextcap.wifidump.remotechannelfrequency:5180' \
  80                 '-oextcap.wifidump.remotechannelwidth:40' \
  81                 -i wifidump -k
  82
  83 Supported interfaces:
  84
  85 1. wifidump
  86
  87 == OPTIONS
  88
  89 --help::
  90 Print program arguments.
  91
  92 --version::
  93 Print program version.
  94
  95 --extcap-interfaces::
  96 List available interfaces.
  97
  98 --extcap-interface=<interface>::
  99 Use specified interfaces.
 100
 101 --extcap-dlts::
 102 List DLTs of specified interface.
 103
 104 --extcap-config::
 105 List configuration options of specified interface.
 106
 107 --capture::
 108 Start capturing from specified interface and write raw packet data to the location specified by --fifo.
 109
 110 --fifo=<path to file or pipe>::
 111 Save captured packet to file or send it through pipe.
 112
 113 --remote-host=<remote host>::
 114 The address of the remote host for capture.
 115
 116 --remote-port=<remote port>::
 117 The SSH port of the remote host.
 118
 119 --remote-username=<username>::
 120 The username for ssh authentication.
 121
 122 --remote-password=<password>::
 123 The password to use (if not ssh-agent and pubkey are used). WARNING: the
 124 passwords are stored in plaintext and visible to all users on this system. It is
 125 recommended to use keyfiles with a SSH agent.
 126
 127 --sshkey=<SSH private key path>::
 128 The path to a private key for authentication.
 129
 130 --remote-interface=<remote interface>::
 131 The remote network interface to capture from.
 132
 133 --remote-channel-frequency=<channel frequency>::
 134 The remote channel frequency in MHz.
 135
 136 --remote-channel-width=<channel width>::
 137 The remote channel width in MHz.
 138
 139 --extcap-capture-filter=<capture filter>::
 140 The capture filter. It corresponds to the value provided via the *tshark -f*
 141 option, and the Capture Filter field next to the interfaces list in the
 142 Wireshark interface.
 143
 144 == EXAMPLES
 145
 146 To see program arguments:
 147
 148     wifidump --help
 149
 150 To see program version:
 151
 152     wifidump --version
 153
 154 To see interfaces:
 155
 156     wifidump --extcap-interfaces
 157
 158 Only one interface (wifidump) is supported.
 159
 160 .Example output
 161     interface {value=wifidump}{display=Wi-Fi remote capture}
 162
 163 To see interface DLTs:
 164
 165     wifidump --extcap-interface=wifidump --extcap-dlts
 166
 167 .Example output
 168     dlt {number=147}{name=wifidump}{display=Remote capture dependent DLT}
 169
 170 To see interface configuration options:
 171
 172     wifidump --extcap-interface=wifidump --extcap-config
 173
 174 .Example output
 175     arg {number=0}{call=--remote-host}{display=Remote SSH server address}{type=string}
 176         {tooltip=The remote SSH host. It can be both an IP address or a hostname}{required=true}{group=Server}
 177     arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned}
 178         {tooltip=The remote SSH host port (1-65535)}{range=1,65535}{group=Server}
 179     arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string}
 180         {tooltip=The remote SSH username. If not provided, the current user will be used}{group=Authentication}
 181     arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=password}
 182         {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}{group=Authentication}
 183     arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect}
 184         {tooltip=The path on the local filesystem of the private ssh key}{mustexist=true}{group=Authentication}
 185     arg {number=5}{call=--sshkey-passphrase}{display=SSH key passphrase}{type=password}
 186         {tooltip=Passphrase to unlock the SSH private key}{group=Authentication}
 187     arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string}
 188         {tooltip=The remote network interface used to capture}{default=auto}{group=Capture}
 189     arg {number=7}{call=--remote-channel-frequency}{display=Remote channel}{type=selector}
 190         {tooltip=The remote channel used to capture}{group=Capture}
 191     arg {number=8}{call=--remote-channel-width}{display=Remote channel width}{type=selector}
 192         {tooltip=The remote channel width used to capture}{group=Capture}
 193     arg {number=9}{call=--remote-filter}{display=Remote capture filter}{type=string}
 194         {tooltip=The remote capture filter}{group=Capture}
 195     arg {number=10}{call=--remote-count}{display=Packets to capture}{type=unsigned}
 196         {tooltip=The number of remote packets to capture.}{group=Capture}
 197     arg {number=11}{call=--log-level}{display=Set the log level}{type=selector}
 198         {tooltip=Set the log level}{required=false}{group=Debug}
 199     arg {number=12}{call=--log-file}{display=Use a file for logging}{type=fileselect}
 200         {tooltip=Set a file where log messages are written}{required=false}{group=Debug}
 201
 202 To capture:
 203
 204     wifidump --extcap-interface=wifidump --fifo=/tmp/wifidump.pcap --capture --remote-host 192.168.1.10 --remote-username user --remote-channel-frequency 5180 --remote-channel-width 40
 205
 206 NOTE: To stop capturing CTRL+C/kill/terminate application.
 207
 208 The wifidump binary can be renamed to support multiple instances. For instance if we want wifidump
 209 to show up twice in wireshark (for instance to handle multiple profiles), we can copy wifidump to
 210 wifidump-host1 and wifidump-host2. Each binary will show up an interface name same as the executable
 211 name. Those executables not being "wifidump" will show up as "custom version" in the interface description.
 212
 213 == SEE ALSO
 214
 215 xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:extcap.html[extcap](4), xref:https://www.tcpdump.org/manpages/tcpdump.1.html[tcpdump](1)
 216
 217 == NOTES
 218
 219 *Wifidump* is part of the *Wireshark* distribution.  The latest version
 220 of *Wireshark* can be found at https://www.wireshark.org.
 221
 222 HTML versions of the Wireshark project man pages are available at
 223 https://www.wireshark.org/docs/man-pages.
 224
 225 == AUTHORS
 226
 227 .Original Author
 228 [%hardbreaks]
 229 Adrian Granados <adrian[AT]intuitibits.com>