1CISCODUMP(1) CISCODUMP(1)
2
6 ciscodump - Provide interfaces to capture from a remote Cisco router
7 through SSH.
8
10 ciscodump [ --help ] [ --version ] [ --extcap-interfaces ]
11 [ --extcap-dlts ] [ --extcap-interface=<interface> ]
12 [ --extcap-config ] [ --extcap-capture-filter=<capture filter> ]
13 [ --capture ] [ --fifo=<path to file or pipe> ]
14 [ --remote-host=<IP address> ] [ --remote-port=<TCP port> ]
15 [ --remote-username=<username> ] [ --remote-password=<password> ]
16 [ --remote-filter=<filter> ] [ --sshkey=<public key path> ]
17 [ --remote-interface=<interface> ]
18 ciscodump --extcap-interfaces
20 ciscodump --extcap-interface=<interface> --extcap-dlts
22 ciscodump --extcap-interface=<interface> --extcap-config
24 ciscodump --extcap-interface=<interface> --fifo=<path to file or pipe>
26 --capture --remote-host=remoterouter --remote-port=22
27 --remote-username=user --remote-interface=<the router interface>
28
30 Ciscodump is an extcap tool that relies on Cisco EPC to allow a user to
31 run a remote capture on a Cisco router in a SSH connection. The minimum
32 IOS version supporting this feature is 12.4(20)T. More details can be
33 found here:
34 https://www.cisco.com/c/en/us/products/collateral/ios-nx-os-software/ios-embedded-packet-capture/datasheet_c78-502727.html
35 Supported interfaces:
37 1. cisco
39
41 --help
42 Print program arguments.
44 --version
46 Print program version.
48 --extcap-interfaces
50 List available interfaces.
52 --extcap-interface=<interface>
54 Use specified interfaces.
56 --extcap-dlts
58 List DLTs of specified interface.
60 --extcap-config
62 List configuration options of specified interface.
64 --capture
66 Start capturing from specified interface and save it in place
68 specified by --fifo.
69 --fifo=<path to file or pipe>
71 Save captured packet to file or send it through pipe.
73 --remote-host=<remote host>
75 The address of the remote host for capture.
77 --remote-port=<remote port>
79 The SSH port of the remote host.
81 --remote-username=<username>
83 The username for ssh authentication.
85 --remote-password=<password>
87 The password to use (if not ssh-agent and pubkey are used).
89 WARNING: the passwords are stored in plaintext and visible to all
90 users on this system. It is recommended to use keyfiles with a SSH
91 agent.
92 --remote-filter=<filter>
94 The remote filter on the router. This is a capture filter that
96 follows the Cisco IOS standards
97 (https://www.cisco.com/c/en/us/support/docs/ip/access-lists/26448-ACLsamples.html).
98 Multiple filters can be specified using a comma between them.
99 BEWARE: when using a filter, the default behavior is to drop all
100 the packets except the ones that fall into the filter.
101 Examples:
103 permit ip host MYHOST any, permit ip any host MYHOST (capture the traffic for MYHOST)
105 deny ip host MYHOST any, deny ip any host MYHOST, permit ip any any (capture all the traffic except MYHOST)
107 --sshkey=<SSH private key path>
109 The path to a private key for authentication.
111 --remote-interface=<remote interface>
113 The remote network interface to capture from.
115 --extcap-capture-filter=<capture filter>
117 Unused (compatibility only).
119
121 To see program arguments:
122 ciscodump --help
124 To see program version:
126 ciscodump --version
128 To see interfaces:
130 ciscodump --extcap-interfaces
132 Only one interface (cisco) is supported.
134 Example output
136 interface {value=cisco}{display=SSH remote capture}
138 To see interface DLTs:
140 ciscodump --extcap-interface=cisco --extcap-dlts
142 Example output
144 dlt {number=147}{name=cisco}{display=Remote capture dependent DLT}
146 To see interface configuration options:
148 ciscodump --extcap-interface=cisco --extcap-config
150 Example output
152 ciscodump --extcap-interface=cisco --extcap-config
154 arg {number=0}{call=--remote-host}{display=Remote SSH server address}
155 {type=string}{tooltip=The remote SSH host. It can be both an IP address or a hostname}
156 {required=true}
157 arg {number=1}{call=--remote-port}{display=Remote SSH server port}{type=unsigned}
158 {default=22}{tooltip=The remote SSH host port (1-65535)}{range=1,65535}
159 arg {number=2}{call=--remote-username}{display=Remote SSH server username}{type=string}
160 {default=<current user>}{tooltip=The remote SSH username. If not provided, the current
161 user will be used}
162 arg {number=3}{call=--remote-password}{display=Remote SSH server password}{type=string}
163 {tooltip=The SSH password, used when other methods (SSH agent or key files) are unavailable.}
164 arg {number=4}{call=--sshkey}{display=Path to SSH private key}{type=fileselect}
165 {tooltip=The path on the local filesystem of the private ssh key}
166 arg {number=5}{call--sshkey-passphrase}{display=SSH key passphrase}
167 {type=string}{tooltip=Passphrase to unlock the SSH private key}
168 arg {number=6}{call=--remote-interface}{display=Remote interface}{type=string}
169 {required=true}{tooltip=The remote network interface used for capture}
170 arg {number=7}{call=--remote-filter}{display=Remote capture filter}{type=string}
171 {default=(null)}{tooltip=The remote capture filter}
172 arg {number=8}{call=--remote-count}{display=Packets to capture}{type=unsigned}{required=true}
173 {tooltip=The number of remote packets to capture.}
174 To capture:
176 ciscodump --extcap-interface cisco --fifo=/tmp/cisco.pcap --capture --remote-host 192.168.1.10
178 --remote-username user --remote-interface gigabit0/0
179 --remote-filter "permit ip host 192.168.1.1 any, permit ip any host 192.168.1.1"
180 Note
182 Packet count is mandatory, hence the capture will start after this
183 number.
184
186 The configuration of the capture on the routers is a multi-step
187 process. If the SSH connection is interrupted during it, the
188 configuration can be in an inconsistent state. That can happen also if
189 the capture is stopped and ciscodump can’t clean the configuration up.
190 In this case it is necessary to log into the router and manually clean
191 the configuration, removing both the capture point
192 (WIRESHARK_CAPTURE_POINT), the capture buffer
193 (WIRESHARK_CAPTURE_BUFFER) and the capture filter
194 (WIRESHARK_CAPTURE_FILTER).
195 Another known issues is related to the number of captured packets
197 (--remote-count). Due to the nature of the capture buffer, ciscodump
198 waits for the capture to complete and then issues the command to show
199 it. It means that if the user specifies a number of packets above the
200 currently captured, the show command is never shown. Not only is the
201 count of the maximum number of captured packets, but it is also the
202 exact number of expected packets.
203
205 wireshark(1), tshark(1), dumpcap(1), extcap(4), sshdump(1)
206
208 ciscodump is part of the Wireshark distribution. The latest version of
209 Wireshark can be found at https://www.wireshark.org.
210 HTML versions of the Wireshark project man pages are available at
212 https://www.wireshark.org/docs/man-pages.
213
215 Original Author
216 Dario Lombardo <lomato[AT]gmail.com>
217 2022-02-16 CISCODUMP(1)