doc/ciscodump.pod

   1
   2 =head1 NAME
   3
   4 ciscodump - Provide interfaces to capture from a remote Cisco router through SSH.
   5
   6 =head1 SYNOPSIS
   7
   8 B<ciscodump>
   9 S<[ B<--help> ]>
  10 S<[ B<--version> ]>
  11 S<[ B<--extcap-interfaces> ]>
  12 S<[ B<--extcap-dlts> ]>
  13 S<[ B<--extcap-interface>=E<lt>interfaceE<gt> ]>
  14 S<[ B<--extcap-config> ]>
  15 S<[ B<--extcap-capture-filter>=E<lt>capture filterE<gt> ]>
  16 S<[ B<--capture> ]>
  17 S<[ B<--fifo>=E<lt>path to file or pipeE<gt> ]>
  18 S<[ B<--remote-host>=E<lt>IP addressE<gt> ]>
  19 S<[ B<--remote-port>=E<lt>TCP portE<gt> ]>
  20 S<[ B<--remote-username>=E<lt>usernameE<gt> ]>
  21 S<[ B<--remote-password>=E<lt>passwordE<gt> ]>
  22 S<[ B<--remote-filter>=E<lt>filter<gt> ]>
  23 S<[ B<--sshkey>=E<lt>public key path<gt> ]>
  24 S<[ B<--remote-interface>=E<lt>interfaceE<gt> ]>
  25
  26
  27 B<ciscodump>
  28 S<B<--extcap-interfaces>>
  29
  30 B<ciscodump>
  31 S<B<--extcap-interface>=E<lt>interfaceE<gt>>
  32 S<B<--extcap-dlts>>
  33
  34 B<ciscodump>
  35 S<B<--extcap-interface>=E<lt>interfaceE<gt>>
  36 S<B<--extcap-config>>
  37
  38 B<ciscodump>
  39 S<B<--extcap-interface>=E<lt>interfaceE<gt>>
  40 S<B<--fifo>=E<lt>path to file or pipeE<gt>>
  41 S<B<--capture>>
  42 S<B<--remote-host=remoterouter>>
  43 S<B<--remote-port=22>>
  44 S<B<--remote-username=user>>
  45 S<B<--remote-interface>=E<lt>the router interfaceE<gt>>
  46
  47 =head1 DESCRIPTION
  48
  49 B<ciscodump> is an extcap tool that relys on Cisco EPC to allow a user to run a remote capture
  50 on a Cisco router in a SSH connection. The minimum IOS version supporting this feature is 12.4(20)T. More details can be
  51 found here:
  52 http://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html
  53
  54 Supported interfaces:
  55
  56 =over 4
  57
  58 =item 1. cisco
  59
  60 =back
  61
  62 =head1 OPTIONS
  63
  64 =over 4
  65
  66 =item --help
  67
  68 Print program arguments.
  69
  70 =item --version
  71
  72 Print program version.
  73
  74 =item --extcap-interfaces
  75
  76 List available interfaces.
  77
  78 =item --extcap-interface=E<lt>interfaceE<gt>
  79
  80 Use specified interfaces.
  81
  82 =item --extcap-dlts
  83
  84 List DLTs of specified interface.
  85
  86 =item --extcap-config
  87
  88 List configuration options of specified interface.
  89
  90 =item --capture
  91
  92 Start capturing from specified interface and save it in place specified by --fifo.
  93
  94 =item --fifo=E<lt>path to file or pipeE<gt>
  95
  96 Save captured packet to file or send it through pipe.
  97
  98 =item --remote-host=E<lt>remote hostE<gt>
  99
 100 The address of the remote host for capture.
 101
 102 =item --remote-port=E<lt>remote portE<gt>
 103
 104 The SSH port of the remote host.
 105
 106 =item --remote-username=E<lt>usernameE<gt>
 107
 108 The username for ssh authentication.
 109
 110 =item --remote-password=E<lt>passwordE<gt>
 111
 112 The password to use (if not ssh-agent and pubkey are used). WARNING: the
 113 passwords are stored in plaintext and visible to all users on this system. It is
 114 recommended to use keyfiles with a SSH agent.
 115
 116 =item --remote-filter=E<lt>filterE<gt>
 117
 118 The remote filter on the router. This is a capture filter that follows the Cisco IOS standards (http://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.html). Multiple filters can be specified using a comma between them. BEWARE: when using a filter, the default behavior is to drop all the packets except the ones that fall into the filter.
 119
 120 Examples:
 121
 122     permit ip host MYHOST any, permit ip any host MYHOST (capture the traffic for MYHOST)
 123
 124     deny ip host MYHOST any, deny ip any host MYHOST, permit ip any any (capture all the traffic except MYHOST)
 125
 126 =item --sshkey=E<lt>SSH private key pathE<gt>
 127
 128 The path to a private key for authentication.
 129
 130 =item --remote-interface=E<lt>remote interfaceE<gt>
 131
 132 The remote network interface to capture from.
 133
 134 =item --extcap-capture-filter=E<lt>capture filterE<gt>
 135
 136 Unused (compatibility only).
 137
 138 =back
 139
 140 =head1 EXAMPLES
 141
 142 To see program arguments:
 143
 144     ciscodump --help
 145
 146 To see program version:
 147
 148     ciscodump --version
 149
 150 To see interfaces:
 151
 152     ciscodump --extcap-interfaces
 153
 154 Only one interface (cisco) is supported.
 155
 156   Output:
 157     interface {value=cisco}{display=SSH remote capture}
 158
 159 To see interface DLTs:
 160
 161     ciscodump --extcap-interface=cisco --extcap-dlts
 162
 163   Output:
 164     dlt {number=147}{name=cisco}{display=Remote capture dependant DLT}
 165
 166 To see interface configuration options:
 167
 168     ciscodump --extcap-interface=cisco --extcap-config
 169
 170   Output:
 171     ciscodump --extcap-interface=cisco --extcap-config
 172     arg {number=0}{call=--remote-host}{display=Remote SSH server address}
 173         {type=string}{tooltip=The remote SSH host. It can be both an IP address or a hostname}
 174         {required=true}
 175     arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned}
 176         {default=22}{tooltip=The remote SSH host port (1-65535)}{range=1,65535}
 177     arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string}
 178         {default=<current user>}{tooltip=The remote SSH username. If not provided, the current
 179         user will be used}
 180     arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=string}
 181         {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}
 182     arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect}
 183         {tooltip=The path on the local filesystem of the private ssh key}
 184     arg {number=5}{call--sshkey-passphrase}{display=SSH key passphrase}
 185         {type=string}{tooltip=Passphrase to unlock the SSH private key}
 186     arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string}
 187         {required=true}{tooltip=The remote network interface used for capture}
 188     arg {number=7}{call=--remote-filter}{display=Remote capture filter}{type=string}
 189         {default=(null)}{tooltip=The remote capture filter}
 190     arg {number=8}{call=--remote-count}{display=Packets to capture}{type=unsigned}{required=true}
 191         {tooltip=The number of remote packets to capture.}
 192
 193
 194 To capture:
 195
 196     ciscodump --extcap-interface cisco --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
 197         --remote-username user --remote-interface gigabit0/0
 198         --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1"
 199
 200 NOTE: Packet count is mandatory, hence the capture will start after this number.
 201
 202 =head1 KNOWN ISSUES
 203
 204 The configuration of the capture on the routers is a multi-step process. If the SSH connection is interrupted during
 205 it, the configuration can be in an inconsistent state. That can happen also if the capture is stopped and ciscodump
 206 can't clean the configuration up. In this case it is necessary to log into the router and manually clean the
 207 configuration, removing both the capture point (WIRESHARK_CAPTURE_POINT), the capture buffer (WIRESHARK_CAPTURE_BUFFER)
 208 and the capture filter (WIRESHARK_CAPTURE_FILTER).
 209
 210 Another known issues is related to the number of captured packets (--remote-count). Due to the nature of the capture
 211 buffer, ciscodump waits for the capture to complete and then issues the command to show it. It means that if the user
 212 specifies a number of packets above the currently captured, the show command is never shown. Not only is the count of
 213 the maximum number of captured packets, but it is also the _exact_ number of expected packets.
 214
 215 =head1 SEE ALSO
 216
 217 wireshark(1), tshark(1), dumpcap(1), extcap(4), sshdump(1)
 218
 219 =head1 NOTES
 220
 221 B<ciscodump> is part of the B<Wireshark> distribution.  The latest version
 222 of B<Wireshark> can be found at L<https://www.wireshark.org>.
 223
 224 HTML versions of the Wireshark project man pages are available at:
 225 L<https://www.wireshark.org/docs/man-pages>.
 226
 227 =head1 AUTHORS
 228
 229   Original Author
 230   -------- ------
 231   Dario Lombardo             <lomato[AT]gmail.com>