doc/man_pages/ciscodump.adoc

   1 include::../attributes.adoc[]
   2 = ciscodump(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 ciscodump - Provide interfaces to capture from a remote Cisco device through SSH.
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *ciscodump*
  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 [ *--remote-filter*=<filter> ]
  30 [ *--sshkey*=<public key path> ]
  31 [ *--remote-interface*=<interface> ]
  32 [ *--remote-count*=<count> ]
  33
  34 [manarg]
  35 *ciscodump*
  36 *--extcap-interfaces*
  37
  38 [manarg]
  39 *ciscodump*
  40 *--extcap-interface*=ciscodump
  41 *--extcap-dlts*
  42
  43 [manarg]
  44 *ciscodump*
  45 *--extcap-interface*=ciscodump
  46 *--extcap-config*
  47
  48 [manarg]
  49 *ciscodump*
  50 *--extcap-interface*=ciscodump
  51 *--fifo*=<path to file or pipe>
  52 *--capture*
  53 *--remote-host*=remotedevice
  54 *--remote-port*=22
  55 *--remote-username*=user
  56 *--remote-interface*=<the device interface>
  57 *--remote-count*=<count>
  58
  59 == DESCRIPTION
  60
  61 *Ciscodump* is an extcap tool that relies on Cisco EPC to allow a user to run a remote capture
  62 on a Cisco device in a SSH connection. It supports IOS, IOS-XE based device and ASA devices.
  63
  64 The tool configures capture on the device, reads data and removes configuration from the device. Provided credentials must allow the tool to configure the device.
  65
  66 When capture is started, packets are provided as they are received from the device. Capture stops when:
  67
  68 * requested count of packets is reached (*--remote-count* is mandatory)
  69 * when capture finishes on the device (e.g. capture buffer is full)
  70 * the capture is stopped by the user
  71
  72 Capture performance depends on a device type. The tool tries to read packets as soon as they received, but is usually slower than capturing device captures packets. Therefore packets are read in batches.
  73
  74 IOS/IOS-XE provides only access to all captured packets from the top. Therefore reading of second batch means to read all packets from first batch, but ignore them and then read new packets in second batch.
  75
  76 ASA provides access to specific packet so tool reads every packet just once.
  77
  78
  79 === SUPPORTED CISCO SOFTWARE
  80
  81 The application supports IOS version is 12.4 and higher. The IOS version supporting capture feature is 12.4(20)T and higher. More details can be
  82 found here: https://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html
  83
  84 The application supports IOS-XE version 16.1 and higher. Search for "Embedded Packet Capture Configuration Guide, Cisco IOS XE" to get more details.
  85
  86 The application supports ASA version 8.4 and higher. More details can be found here: https://community.cisco.com/t5/security-documents/asa-using-packet-capture-to-troubleshoot-asa-firewall/ta-p/3129889
  87
  88
  89 == OPTIONS
  90
  91 --help::
  92 Print program arguments.
  93
  94 --version::
  95 Print program version.
  96
  97 --extcap-interfaces::
  98 List available interfaces.
  99
 100 --extcap-interface=<interface>::
 101 Use specified interfaces.
 102
 103 --extcap-dlts::
 104 List DLTs of specified interface.
 105
 106 --extcap-config::
 107 List configuration options of specified interface.
 108
 109 --capture::
 110 Start capturing from specified interface and save it in place specified by --fifo.
 111
 112 --fifo=<path to file or pipe>::
 113 Save captured packet to file or send it through pipe.
 114
 115 --remote-host=<remote host>::
 116 The address of the remote host for capture.
 117
 118 --remote-port=<remote port>::
 119 The SSH port of the remote host.
 120
 121 --remote-username=<username>::
 122 The username for ssh authentication.
 123
 124 --remote-password=<password>::
 125 The password to use (if not ssh-agent and pubkey are used). WARNING: the
 126 passwords are stored in plaintext and visible to all users on this system. It is
 127 recommended to use keyfiles with a SSH agent.
 128
 129 --remote-filter=<filter>::
 130 +
 131 --
 132 The remote filter on the device. This is a capture filter that follows the Cisco
 133 standards.
 134
 135 For IOS/IOS-XE see https://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.html.
 136
 137 For ASA see https://www.cisco.com/c/en/us/td/docs/security/asa/asa96/configuration/firewall/asa-96-firewall-config/access-acls.html.
 138
 139 Multiple filters can be specified using a comma between them. BEWARE: when using
 140 a filter, the default behavior is to drop all the packets except the ones that
 141 fall into the filter.
 142
 143 Examples for IOS/IOS-XE:
 144
 145     permit ip host MYHOST any, permit ip any host MYHOST (capture the traffic for MYHOST)
 146
 147     deny ip host MYHOST any, deny ip any host MYHOST, permit ip any any (capture all the traffic except MYHOST)
 148
 149 Examples for ASA:
 150
 151     permit any4 host MYHOST, permit host MYHOST any4 (capture IPv4 traffic for MYHOST)
 152
 153 NOTE: Different capture types support or do not support specific ACL keywords. The tool is not able to check it, just tries to configure it. If error occurs, the tool just reports it and terminates. Debris are left in configuration in this case.
 154 --
 155
 156 --sshkey=<SSH private key path>::
 157 The path to a private key for authentication.
 158
 159 --remote-interface=<remote interface>::
 160 +
 161 --
 162 The remote network interface to capture from. One interface or list of interface names can be used. Interfaces are separated by comma.  Interface names must be supported by the device.
 163
 164 There are interface names causing different capture types. They are specific to used Cisco software.
 165
 166 *IOS special names*
 167
 168 * `process-switched` - capture process switched packets in both directions
 169 * `from-us` - capture process switched packets originating at the device
 170
 171 *IOS-XE special names*
 172
 173 * `control-plane` - captures in/out packets touching control plane
 174
 175 *ASA special names*
 176
 177 * `asp-drop` - capture packets dropped by all asp categories
 178 * `TYPE---ifname` - syntax to refer ASA capture types, see https://www.cisco.com/c/en/us/td/docs/security/asa/asa-cli-reference/A-H/asa-command-ref-A-H/ca-cld-commands.html#wp2435483314
 179 ** `isakmp---ifname` - capture isakmp packets
 180 ** `lacp---ifname` - capture lacp packets (just physical interfaces are supported)
 181 ** `tls-proxy---ifname` - capture tls-proxy packets
 182 ** `inline-tag---ifname` - capture all SGT tagged packets
 183 ** `raw-data---ifname` - same as `ifname`
 184 * syntax to capture decrypted traffic for some of capture types:
 185 ** `isakmp/decrypted---ifname` - capture isakmp packets including decrypted payload
 186 ** `tls-proxy/decrypted---ifname` - capture tls-proxy packets including decrypted payload
 187 ** `inline-tag/decrypted---ifname` - capture inline-tag packets including decrypted payload
 188 ** `raw-data/decrypted---ifname` - capture raw-data packets including decrypted payload
 189
 190 Use e. g. `isakmp/decrypted---outside` to capture encrypted and decrypted isakmp traffic on `outside` interface.
 191 --
 192
 193 --remote-count=<count>::
 194 Count of packets to capture. Capture is stopped when count is reached.
 195
 196 --extcap-capture-filter=<capture filter>::
 197 Unused (compatibility only).
 198
 199 == EXAMPLES
 200
 201 To see program arguments:
 202
 203     ciscodump --help
 204
 205 To see program version:
 206
 207     ciscodump --version
 208
 209 To see interfaces:
 210
 211     ciscodump --extcap-interfaces
 212
 213 Only one interface (ciscodump) is supported.
 214
 215 .Example output
 216     interface {value=ciscodump}{display=SSH remote capture}
 217
 218 To see interface DLTs:
 219
 220     ciscodump --extcap-interface=ciscodump --extcap-dlts
 221
 222 .Example output
 223     dlt {number=147}{name=ciscodump}{display=Remote capture dependent DLT}
 224
 225 To see interface configuration options:
 226
 227     ciscodump --extcap-interface=ciscodump --extcap-config
 228
 229 .Example output
 230     ciscodump --extcap-interface=ciscodump --extcap-config
 231     arg {number=0}{call=--remote-host}{display=Remote SSH server address}
 232         {type=string}{tooltip=The remote SSH host. It can be both an IP address or a hostname}
 233         {required=true}{group=Server}
 234     arg {number=1}{call=--remote-port}{display=Remote SSH server port}
 235         {type=unsigned}{default=22}{tooltip=The remote SSH host port (1-65535)}
 236         {range=1,65535}{group=Server}
 237     arg {number=2}{call=--remote-username}{display=Remote SSH server username}
 238         {type=string}{default=<current user>}{tooltip=The remote SSH username. If not provided, the current user will be used}
 239         {group=Authentication}
 240     arg {number=3}{call=--remote-password}{display=Remote SSH server password}
 241         {type=password}{tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}
 242         {group=Authentication}
 243     arg {number=4}{call=--sshkey}{display=Path to SSH private key}
 244         {type=fileselect}{tooltip=The path on the local filesystem of the private ssh key}
 245         {group=Authentication}
 246     arg {number=5}{call=--proxycommand}{display=ProxyCommand}
 247         {type=string}{tooltip=The command to use as proxy for the SSH connection}{group=Authentication}
 248     arg {number=6}{call--sshkey-passphrase}{display=SSH key passphrase}
 249         {type=password}{tooltip=Passphrase to unlock the SSH private key}{group=Authentication
 250     arg {number=7}{call=--remote-interface}{display=Remote interface}
 251         {type=string}{tooltip=The remote network interface used for capture}
 252         {required=true}{group=Capture}
 253     arg {number=8}{call=--remote-filter}{display=Remote capture filter}
 254         {type=string}{tooltip=The remote capture filter}{default=<filter to exclude current host>}
 255         {group=Capture}
 256     arg {number=9}{call=--remote-count}{display=Packets to capture}
 257         {type=unsigned}{tooltip=The number of remote packets to capture.}
 258         {required=true}{group=Capture}
 259     arg {number=10}{call=--debug}{display=Run in debug mode}
 260         {type=boolflag}{default=false}{tooltip=Print debug messages}
 261         {required=false}{group=Debug}
 262     arg {number=11}{call=--debug-file}{display=Use a file for debug}
 263         {type=string}{tooltip=Set a file where the debug messages are written}
 264         {required=false}{group=Debug}
 265
 266 To capture on IOS/IOS-XE:
 267
 268     ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
 269         --remote-username user --remote-interface gigabit0/0,gigiabit0/1
 270         --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1"
 271         --remote-count=10
 272
 273 To capture on IOS/IOS-XE:
 274
 275     ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
 276         --remote-username user --remote-interface outside,dmz
 277         --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1"
 278         --remote-count=10
 279
 280     ciscodump --extcap-interface ciscodump --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
 281         --remote-username user --remote-interface raw-data/decrypted---outside
 282         --remote-filter "permit host 192.168.1.1 any4, permit any4 host 192.168.1.1"
 283
 284 == KNOWN ISSUES
 285
 286 When capture stopped by the user before it finishes on Windows platform, configuration is not cleared on the device. Next run will probably fails because parts of configuration already exists on the device.
 287
 288 Reading performance on IOS/IOS-XE is poor because re-reading of capture buffer over and over.
 289
 290 The configuration of the capture on the device is a multi-step process. If the SSH connection is interrupted during
 291 it, the configuration can be in an inconsistent state. That can happen also if the capture is stopped and ciscodump
 292 can't clean the configuration up. In this case it is necessary to log into the device and manually clean the
 293 configuration, removing configuration elements:
 294
 295 * IOS
 296 ** capture points WSC_P_<number> (depends on count of capture interfaces)
 297 ** the capture buffer WSC_B
 298 ** the capture capture acl WSC_ACL (if filter was used)
 299 * IOS-XE
 300 ** the capture WSC
 301 ** the capture capture acl WSC_ACL (if filter was used)
 302 * ASA
 303 ** the capture WSC
 304 ** the capture capture acl WSC_ACL (if filter was used)
 305
 306 On IOS platforms, only IPv4 commands issued and only IPv4 packets are captured.
 307
 308 == SEE ALSO
 309
 310 xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4), xref:sshdump.html[sshdump](1)
 311
 312 == NOTES
 313
 314 *ciscodump* is part of the *Wireshark* distribution.  The latest version
 315 of *Wireshark* can be found at https://www.wireshark.org.
 316
 317 HTML versions of the Wireshark project man pages are available at
 318 https://www.wireshark.org/docs/man-pages.
 319
 320 == AUTHORS
 321
 322 .Original Author
 323 [%hardbreaks]
 324 Dario Lombardo <lomato[AT]gmail.com>