15.3. Packet Dumping

15.3. Packet Dumping
	Chapter 15. Network Diagnostic Tools

The FireBrick includes the ability to capture packet dumps for diagnostic purposes. This might typically be used where the behaviour of the FB2900 is not as expected, and can help identify whether other devices are correctly implementing network protocols - if they are, then you should be able to determine whether the FB2900 is responding appropriately. The packet dumping facility may also be of use to you to debug traffic (and thus specific network protocols) between two hosts that the brick is routing traffic between.

This feature is provided via the FB2900's HTTP server and provides a download of a pcap format file (old format) suitable for use with tcpdump or Wireshark.

A packet dump can be performed by either of these methods :-

via the user interface, using a web-page form to set up the dump - once the capture data has been downloaded it can be analysed using tcpdump or Wireshark
using an HTTP client on another machine (typically a command-line client utility such as curl)

The output is streamed so that, when used with curl and tcpdump, you can monitor traffic in real time.

Limited filtering is provided by the FB2900, so you will normally apply any additional filtering you need via tcpdump.

15.3.1. Dump parameters

Table 15.1 lists the parameters you can specify to control what gets dumped. The "Parameter name" column shows the exact parameter name to specify when constructing a URL to use with an HTTP client. The "Web-form field" column shows the label of the equivalent field on the user interface form.

Table 15.1. Packet dump parameters

Parameter name	Web-form field	Function
interface	Interface	One or more interfaces, as the name of the interface. e.g. interface=WAN, also applies for name of PPPoE on an interface
l2tp	L2TP session	Where L2TP is available, one or more sessions, using the full hex accounting ID, can be specified, e.g. l2tp=002132D94AE297DFF51E01 or you can use l2tp=* followed by a calling line ID - this sets up logging for a session based on calling line id when it next connects.
snaplen	Snaplen	The maximum capture length for a packet can be specified, in bytes. Default 0 (auto). See notes below.
timeout	Timeout	The maximum capture time can be specified in seconds. Default 10.
ip	IP address (2-off)	Up to two IPs can be specified to filter packets
self	Include this TCP session	By default any TCP traffic to or from the IP and ports of the TCP session used for the dump is excluded. You can opt to include it, but that is usually a bad idea for obvious reasons as you may be dumping the packet dump itself. Note that if dumping tunnel wrappers and dumping via that tunnel then the dump traffic is not normally detected/excluded.

15.3.2. Security settings required

The following criteria must be met in order to use the packet dump facility :-

You must be accessing from an IP listed as trusted in the HTTP service configuration (see Section 14.3).
You must use a user and password for a "DEBUG level" user - the user level is set with the level attribute on the user object.

Note

These security requirements are the most likely thing to cause your attempts to packet dump to fail. If you are getting a simple "404" error response, and think you have specified the correct URL (if using an HTTP client), please check security settings are as described here.

15.3.3. IP address matching

You may optionally specify up to two IP address to be checked for a match in packets on the interface(s) and/or L2TP session(s) specified. If you do not specify any IP addresses, then all packets are returned. If you specify one IP address then all packets containing that IP address (as source or destination) are returned. If you specify two IP addresses then only those packets containing both addresses (each address being either as source or destination) are returned.

IP matching is only performed against ARP, IPv4 or IPv6 headers and not in encapsulated packets or ICMP payloads.

If capturing too much, some packets may be lost.

15.3.4. Packet types

The capture can collect different types of packets depending on where the capture is performed. All of these are presented as Ethernet frames, with faked Ethernet headers where the packet type is not Ethernet.

Table 15.2. Packet types that can be captured

Type	Notes
Ethernet	Interface based capture contains the full Ethernet frame with any VLAN tag removed.
IP	IP only, currently not possible to capture at this level. An Ethernet header is faked.
PPP	PPP from the protocol word (HDLC header is ignored if present). An Ethernet header is faked and also a PPPoE header. The PPPoE header has the session PPPoE ID that is the local end L2TP session ID.

The faked protocol header has target MAC of 00:00:00:00:00:00 and source MAC of 00:00:00:00:00:01 for received packets, and these reversed for sent packets.

15.3.5. Snaplen specification

The snaplen argument specifies the maximum length captured, but this applies at the protocol level. As such PPP packets will have up to the snaplen from the PPP protocol bytes and then have fake PPPoE and Ethernet headers added.

A snaplen value of 0 has special meaning - it causes logging of just IP, TCP, UDP and ICMP headers as well as headers in ICMP error payloads. This is primarily to avoid logging data carried by these protocols.

15.3.6. Using the web interface

The web form is accessed by selecting the "Packet dump" item under the "Diagnostics" main-menu item. Set up the dump parameters with reference to Table 15.1 and click the "Dump" button. Your browser will ask you to save a file, which will take time to save as per the timeout requested.

15.3.7. Using an HTTP client

To perform a packet dump using an HTTP client, you first construct an appropriate URL that contains standard HTTP URL form-style parameters from the list shown in Table 15.1. Then you retrieve the dump from the FB2900 using a tool such as curl.

The URL is http://<FB2900 IP address or DNS name>/pcap?parameter_name=value[&parameter_name=value ...]

The URL may include as many parameter name and value pairs as you need to completely specify the dump parameters.

Packet capturing stops if the output stream (HTTP transfer) fails. This is useful if you are unable to determine a suitable timeout period, and would like to run an ongoing capture which you stop manually. This is achieved by specifying a very long duration, and then interrupting execution of the HTTP client using Ctrl+C or similar.

Only one capture can operate at a time. The HTTP access fails if no valid interfaces or sessions etc. are specified or if a capture is currently running.

15.3.7.1. Example using curl and tcpdump

An example of a simple real-time dump and analysis run on a Linux box is shown below :-

curl --silent --no-buffer --user name:pass
   'http://1.2.3.4/pcap?interface=LAN&timeout=300&snaplen=1500'
   | /usr/sbin/tcpdump -r - -n -v

Note

Linebreaks are shown in the example for clarity only - they must not be entered on the command-line

In this example we have used username name and password pass to log in to a FireBrick on address 1.2.3.4 - obviously you would change the IP address (or host name) and credentials to something suitable for your FB2900.

We have asked for a dump of the interface named LAN, with a 5 minute timeout and capturing 1500 byte packets. We have then fed the output in real time (hence specifying --no-buffer on the curl command) to tcpdump, and asked it to take capture data from the standard input stream (via the -r - options). We have additionally asked for no DNS resolution (-n) and verbose output (-v).

Consult the documentation provided with the client (e.g. Linux box) system for details on the extensive range of tcpdump options - these can be used to filter the dump to better locate the packets you are interested in.


15.2. Access check		Chapter 16. VRRP