Diagnostics — capture#

The Capture tab records the packets on one of the router's interfaces into a file you download and open in a packet analyser such as Wireshark. Every capture is limited by packets, time and size at once, and ends at whichever limit it reaches first.

Starting a capture#

In the Packet capture panel:

Press Start capture. The router starts the capture before it answers, so a filter it cannot use, or an interface it cannot capture on, is reported at once under Capture not started. A limit above its maximum is reduced to the maximum. The filter may not begin with a hyphen or be longer than 256 characters.

One capture runs at a time on a router. Start capture needs the operator role, and no licence; for other roles it is disabled with the reason "Capturing needs the operator role".

While it runs#

The This capture panel shows how far the capture has got:

• the Packets, File and Elapsed tiles, each against its limit, and a bar for each limit;
• Interface, Filter (Everything when there is none), State and Started.

The dot beside the panel title reads capturing. The figures are the agent's own count of what it has written, so following a capture adds no load on the router.

Under the fields, a sentence says what will end the capture: with Stop when no one is watching on, "This capture stops within 20–25 seconds of the last time this page asked how it was doing, and at its limits in any case."; with it off, "This capture runs until it reaches a limit or is stopped; closing this page does not end it."

Press Stop capture to end it early. What it has captured is kept.

Stop when no one is watching#

With it on, any page showing the capture keeps it running, including another person's. Downloading or deleting the file does not count. A page that started the capture also asks the router to stop it when the page is closed. If no page has shown the capture for 20–25 seconds, the router stops it, and the stop is recorded in the audit log against the person who started it.

With it off, only the limits or Stop capture end the capture, after 300 seconds at most.

When it ends#

State says how it ended:

When nothing matched the filter, the panel reads "Nothing matched, so there is no file."

The file#

When the capture has ended, Download followed by the file's name downloads it, and Delete deletes it: press Delete, then Delete the capture file? within five seconds. Otherwise the file is deleted 15 minutes after the capture ends, or when the next capture starts; File deleted at shows when. Once it is deleted, the panel reads "The file has been deleted; the figures above are what it held."

While a file exists, the page checks on it every 15 seconds, and Download goes when the file is deleted, whether by the time limit or by another operator. When the agent restarts, it deletes any capture file left from before.

The file is kept in the agent's data directory on the router. It is not part of backups or support bundles.

In Advanced mode#

The Command panel shows the tcpdump command line the router runs.

When capture is not available#

The tab shows one of these instead, and Start capture is disabled:

• "Packet capture needs the agent to run on the router, and this one does not."
• "Packet capture is not available: tcpdump is not installed on this router."

For automation#

None of them needs a licence.

curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"interface":"eth1","filter":"tcp port 443","packets":5000,"seconds":60,"stop_when_unwatched":false}' \
  https://<router>:8443/api/capture

curl -sk -H "Authorization: Bearer $T" \
  https://<router>:8443/api/capture/download -o capture.pcap

bytes sets the size limit in bytes. A limit left out or set to 0 takes its default, and stop_when_unwatched is off unless set.

See also#

• Diagnostics — the other tabs.
• Diagnostics — tools — traceroute and DNS lookup, also run on the router.
• Logs — the router's system log.
• System — audit — the record of every capture.