Exact Extract
Exact Extract is a utility that extracts packets from one or more expcap files and writes them out into a user-specified format. It outputs capture files that are ordered by the expcap timestamps present in the original capture.
$ exact-pcap-extract -i cap0-0.expcap -w extracted -a -f expcap
Note
Exact Extract can take multiple expcap files as its input. It will search for the earliest timestamp in all of the input capture files. This means that the first packet written out will be the packet with the earliest timestamp across all of the input files.
The following table lists all commands available:
| Short | Long | Default | Description |
|---|---|---|---|
| i | input | (required) | The expcap files to extract packets from. |
| w | write | (required) | The filename used for extracted packets. Exact Extract will automatically append .pcap to the filename. |
| W | write-dir | (none) | The directory used to write extracted packets. If used in conjunction with '--write', packets are extracted to {write-dir}/{write}.pcap. It must be specified if steering options (--steer) are in use. |
| p | port | -1 | Only extract packets that were captured on the specified port number. If this is not specified and '--device' is not set, the user must use '--all' to extract packets that were captured on all ports. |
| d | device | -1 | Only extract packets that were captured on the specified device number (i.e., 0 corresponds to exanic0). If this is not specified and '--port' is not set, the user must use '--all' to extract packets that were captured on all ports. |
| a | all | (flag) | Extract packets that were captured on all ports and all devices. This flag must be set if neither '--port' or '--device' are specified. |
| f | format | expcap | The file format to use when writing out packets. Valid options are 'pcap' and 'expcap'. |
| c | count | 0 (no limit) | The maximum number of files to write out in total. |
| M | maxfile | 0 (128MB) | The maximum file size for output files, in MB. Output files will never exceed 128MB, regardless of the value specified with this option. If the output must be spread over multiple files, Exact Extract will append _n to the filename, where n is the current segment being written out (starting from 1). |
| u | usepcap | (flag) | If set, Exact Extract will write pcap timestamps in the microsecond format. |
| S | snaplen | 1518 | The limit in bytes for each individual packet in the output file. |
| r | skip-runts | (flag) | If this flag is set, runt frames will not be written to the output |
| D | allow-duplicates | (flag) | By default, Exact Extract will write over files which have the same name as specified by '--write'. If this flag is set, it will instead create a file with a duplicate name, and append __n to the duplicate file, where n is the current number of files with the same name. |
| t | hpt-trailer | (flag) | If this flag is set, Exact Extract will assume that each packet terminates in a Fusion HPT timestamp trailer. It will extract the timestamp from this trailer and write it to the pcap header (in microsecon/nanosecond format) and to the expcap trailer (in picosecond format) for all output files. Note: this option assumes all packets in the input captures have Fusion HPT trailers. If this is not true, the pcap/expcap timestamp fields will contain invalid values in the output file(s). |
| s | steer | (null) | --steer accepts one of the following values as valid options: hpt, vlan, expcap. A directory must be specified when using this option (via '--write-dir') If this option is set, Exact Extract will steer packets to separate files depending upon their content. Specifying '--steer vlan' will cause packets to be steered to separate files depending upon their VLAN ID. For example, packets with VLAN ID 100 will be steered to the file {write-dir}/{write}_vlan_100.pcap. Packets which do not have an 8021.Q tag will be written to the file named {write-dir}/{write}.pcap. Specifying '--steer hpt' will cause packets to be steered to separate files depending upon their Fusion HPT trailer, using the device ID and port number. For example, files with device ID 0 and port number 10 will be steered to the file {write-dir}/{write}_device_0_port_10.pcap. Note: use of this option assumes that all packets in the input file(s) have a Fusion HPT trailer. Specifying '--steer expcap' will cause packets to be steered to separate files depending upon their expcap footer, using the device ID and port number. For example, files with device ID 0 and port number 10 will be steered to the file {write-dir}/{write}_device_0_port_10.pcap. Note: use of this option assumes that all packets in the input file(s) have an expcap footer. |
NoteDepending upon the options specified by, Exact Extract may attempt to keep more files open simultaneously than is allowed the OS. If it is unable to override this limit, it will need to close and open outputs each time a packet is written in order to ensure that it does not exceed this limit. This can degrade the performance of Exact Extract, due to the additional overhead of repeatedly opening and closing output files.
On Linux, it is possible to override the number of open file descriptors limit by giving Exact Extract the "CAP_SYS_RESOURCE" capability to the binary. This can be accomplished by running:
$ sudo setcap cap_sys_resouce+ep exact-pcap-extract
The full list of permissions granted by CAP_SYS_RESOURCE is available on the capabilities(7) man page. Granting Exact Extract this permission should improve its performance, however it is not a requirement. Users will receive the warning "Could not raise the limit on concurrently open files" if they are exceeding the open file limit.
Feedback