Source Options

Non-option arguments specify the files, or interfaces, to read. For example, 'ipsumdump -r eth0 eth1' will read two tcpdump(1) files, named "eth0" and "eth1"; 'ipsumdump -i eth0 eth1' will read from two live network interfaces, "eth0" and "eth1".

Options that read files read from the standard input when you supply a single dash "-" as a filename, or when you give no filenames at all.

--tcpdump, -r

Read from one or more files produced by tcpdump(1)'s -w option (also known as "pcap files"). Stop when all the files are exhausted. This is the default. Files (except for standard input) may be compressed by gzip(1) or bzip2(1); ipsumdump will uncompress them on the fly.

--interface, -i

Read from live network interfaces. When run this way, ipsumdump will continue until interrupted with SIGINT or SIGHUP. When stopped, ipsumdump appends a comment to its output file, indicating how many packets were dropped by the kernel before output.

--ipsumdump

Read from one or more ipsumdump files. Any packet characteristics not specified by the input files are set to 0.

--format=format

Read from one or more ipsumdump files, using the specified default format. The format should be a space-separated list of content types; see ToIPSummaryDump(n) for a list.

--dag[=encap]

Read from one or more DAG-formatted trace files. For new-style ERF dumps, which contain encapsulation type information, just say --dag. For old-style dumps, you must supply the right encap argument: "ATM" for ATM RFC-1483 encapsulation (the most common), "ETHER" for Ethernet, "PPP" for PPP, "IP" for raw IP, "HDLC" for Cisco HDLC, "PPP_HDLC" for PPP HDLC, or "SUNATM" for Sun ATM. See <http://dag.cs.waikato.ac.nz/>.

--nlanr

Read from one or more NLANR-formatted trace files (fr, fr+, or tsh format). See <http://pma.nlanr.net/Traces/>.

--netflow-summary

Read from one or more NetFlow summary files. These are line-oriented ASCII files; blank lines, and lines starting with '!' or '#', are ignored. Other lines should contain 15 or more fields separated by vertical bars '|'. Ipsumdump pays attention to some of these fields:

  Field  Meaning                       Example
  -----  ----------------------------  ----------
  0      Source IP address             192.4.1.32
  1      Destination IP address        18.26.4.44
  5      Packet count in flow          5
  6      Byte count in flow            10932
  7      Flow timestamp (UNIX-style)   998006995
  8      Flow end timestamp            998006999
  9      Source port                   3917
  10     Destination port              80
  12     TCP flags (OR of all pkts)    18
  13     IP protocol                   6
  14     IP TOS bits                   0
    

--tcpdump-text

Read from one or more files containing tcpdump(1) textual output. It's much better to use the binary files produced by 'tcpdump -w', but if someone threw those away and all you have is the ASCII output, you can still make do. Only works with tcpdump versions 3.7 and earlier.

Data Options

    192.168.1.101 18.26.4.44

If you supply no dump content options, ipsumdump will not create a summary dump. This may be useful if you're only interested in creating a tcpdump file with --write-tcpdump.

Generic Options

--timestamp, -t

Include packet timestamp in the dump. Example: 1000212480.005813. For NetFlow summary input, the packet timestamp equals the flow-end timestamp. The timestamp has nanosecond precision when input timestamps had nanosecond precision.

--first-timestamp, -T

Include flow-begin timestamp in the dump. Example: 1000212479.001937. This is meaningful only for packet sources that include flow-begin timestamps, such as NetFlow summaries.

--packet-count, -c

Include packet count in the dump. Some kinds of logs -- such as NetFlow summary logs -- record information about flows, not packets. A flow represents multiple packets; the packet count says exactly how many. Example: 1. See also --multipacket, below.

--wire-length

Include wire length in the dump. This is the packet's length in the capture file, including any link headers and packet trailers. This is usually larger than --length, which returns the IP length.

--link

Include the link number in the dump. TSH-format NLANR logs, NetFlow summary logs, and some IP summary logs can contain a link number. Example: 2. For NetFlow summary logs, --link uses the input interface number.

Ethernet Options

--eth-src

Include the Ethernet source address in the dump. Example: "00-0A-95-A6-D9-BC". Note that Ethernet addresses are only printed for IP packets.

--eth-dst

Include the Ethernet destination address in the dump. Example: "00-0A-95-A6-D9-BC". Note that Ethernet addresses are only printed for IP packets.

IP Options

--src, -s

Include IP source address in the dump. Example: 192.168.1.101.

--dst, -d

Include IP destination address in the dump. Example: 18.26.4.44.

--length, -l

Include IP packet length in the dump, not including any link-level headers. Example: 72. See also --wire-length.

--protocol, -p

Include IP protocol in the dump. Can be "T" for TCP, "U" for UDP, "I" for ICMP, or a number for some other protocol.

--fragment, -g

Include IP fragment test in the dump. The field value is "F" for first fragments, "f" for second and subsequent fragments, and "." (a single period) for nonfragments.

--fragment-offset, --fragoff, -G

Include IP fragment offset in the dump. The field value is the fragment offset in bytes, possibly followed by a "+" suffix, indicating the MF (more fragments) flag. Examples: "0+" (fragment offset 0, more fragments forthcoming), 552 (fragment offset 552, this is the last fragment).

--ip-id

Include IP ID field in the dump. Example: 19371.

--ip-sum

Include IP checksum in the dump. Example: 34987.

--ip-opt

Include IP options in the dump. Single IP option fields have the following representations:

    EOL, NOP        Not written, but FromIPSummaryDump
                    understands 'eol' and 'nop'
    
    RR              'rr{10.0.0.1,20.0.0.2}+5' (addresses
                    inside the braces come before the
                    pointer; '+5' means there is space for
                    5 more addresses after the pointer)
    
    SSRR, LSRR      'ssrr{1.0.0.1,1.0.0.2^1.0.0.3}'
                    ('^' indicates the pointer)
    
    TS              'ts{1,10000,!45}+2++3' (timestamps only
                    [type 0]; timestamp values 1, 10000,
                    and 45 [but 45 has the "nonstandard
                    timestamp" bit set]; the option has
                    room for 2 more timestamps; the
                    overflow counter is set to 3)
                    
                    'ts.ip{1.0.0.1=1,1.0.0.2=2}+5'
                    (timestamps with IP addresses [type 1])
    
                    'ts.preip{1.0.0.1=1^1.0.0.2,1.0.0.3}'
                    (prespecified IP addresses [type 3];
                    the caret is the pointer)
                    
    Other options   '98' (option 98, no data),
                    '99=0:5:10' (option with data, data
                    octets separated by colons)
    

Multiple options are separated by semicolons. Any invalid option causes the entire field to be replaced by a single question mark "?". A period "." is used for packets with no options (except possibly EOL and NOP).

--ip-ttl

Include the IP time-to-live field in the dump.

--ip-tos

Include the IP type of service field in the dump.

--ip-hl

Include the IP header length in the dump. The length is measured in bytes.

--capture-length

Include the length of captured IP data in the dump. This can be less than the full IP length (see --length), since many packet capture programs will store only part of each packet's data.

Transport Options

--sport, -S

Include TCP or UDP source port in the dump. Example: 8928. For non-TCP or UDP packets, and for fragments after the first, this field is a single dash "-".

--dport, -D

Include TCP or UDP destination port in the dump. Example: 80.

--payload-length, -L

Include length of packet payload in the dump. This is the length of the TCP or UDP payload, for TCP or UDP packets, or the length of the IP payload, for other IP packets. Example: 1000.

--payload

Include the actual packet payload in the dump. This is the TCP or UDP payload, for TCP or UDP packets, or the IP payload, for other IP packets. Output as a double-quoted C string; non-ASCII characters, and double-quotes and backslashes, appear as C backslash escapes. Example: ",25\r\n\000".

--payload-md5

Include an MD5 checksum of the packet payload in the dump. The payload is as defined above. In ASCII output, the output is a 22-character string consisting of characters [a-zA-Z0-9_@]; in binary output, it's a 16-character binary digest. Example: "sQy@IjqXnFPwZtgtwaC5Hb".

--payload-md5-hex

Like --payload-md5, but in ASCII output, the checksum is printed as 32 hexadecimal digits (the same format used by md5sum). Example: "12f6bb1941df66b8f138a446d4e8670c".

TCP Options

TCP header fields equal a dash "-" for non-TCP packets and non-first fragments.

--tcp-flags, -F

Include TCP flags byte in the dump. Each flag is represented by an uppercase letter. Example: "PA" (PSH and ACK are on, everything else is off). If no flags are on, the field is "." (a single period).

Flag characters are "F" for FIN, "S" for SYN, "R" for RST, "P" for PSH, "A" for ACK, "U" for URG, "E" for ECE (flag bit 6), "C" for CWR (flag bit 7), and "N" for Nonce Sum (flag bit 8).

--tcp-seq, -Q

Include TCP sequence number in the dump. Example: 4009339012.

--tcp-ack, -K

Include TCP acknowledgement number in the dump. Example: 4009339012.

--tcp-window, -W

Include TCP receive window in the dump. This value is not scaled by the connection's window scale, if any. Example: 480.

--tcp-opt, -O

Include TCP options in the dump. Single TCP option fields have the following representations:

    EOL, NOP        No representation
    MSS             'mss1400'
    Window scale    'wscale10'
    SACK permitted  'sackok'
    SACK            'sack95-98'; each SACK block
                    is listed separately
    Timestamp       'ts669063908:38382731'
    Other options   '98' (option 98, no data),
                    '99=0:5:10' (option with data, data
                    octets separated by colons)
    

Multiple options are separated by semicolons. Any invalid option causes the entire field to be replaced by a single question mark "?". A period "." is used for packets with no options (except possibly EOL and NOP).

--tcp-sack

Include SACK-related TCP options in the dump, using the format given under "--tcp-opt", above.

UDP Options

UDP header fields equal a dash "-" for non-UDP packets and non-first fragments.

--udp-length

Include UDP length in the dump. This is the length reported in the UDP packet header. Example: 1000.

ICMP Options

ICMP header fields equal a dash "-" for non-ICMP packets and non-first fragments.

--icmp-type

Include ICMP type in the dump. Example: 3. A dash is output for non-ICMP packets.

--icmp-code

Include ICMP code in the dump. Example: 8.

--icmp-type-name

Include ICMP type in the dump, using textual names if known. Examples: "echo", "echo-reply", 100.

--icmp-code-name

Include ICMP code in the dump, using textual names if known. Examples: "filterprohibited", "srcroutefail", "reassembly", 97.

Other Options

--output=file, -o file

Write the summary dump to file instead of to the standard output.

--binary, -b

Write the summary dump in binary format. See below for more information.

--write-tcpdump=file, -w file

Write processed packets to a tcpdump(1) file -- or to the standard output, if file is a single dash "-" -- in addition to the usual summary output. Options including --filter and dump contents require IP; in the presence of these options, the output tcpdump(1) file will contain only IP packets. (ARP packets, for example, will not be written.)

--no-tcpdump-nano

The file written for --write-tcpdump will use microsecond-precision timestamps, rather than nonsecond-precision timestamps (the default).

--no-payload

Do not include IP packet payloads in any --write-tcpdump output.

--filter=filter, -f filter

Only include packets and flows matching a tcpdump(1) filter. For example, 'ipsumdump -f "tcp && src net 18/8"' will summarize data only for TCP packets from net 18. (The syntax for filter is currently a subset of tcpdump's syntax.)

--bad-packets

Print lines like "!bad IP header length 4" for packets with no IP headers, bad IP headers, or bad TCP/UDP headers. (A bad header has an incorrect length or unexpected version, or is spread across multiple fragments.) The "!bad" line will immediately precede the normal output line. Whether or not --bad-packets is true, a dash "-" is printed for any piece of information that came from a bad header, or that came from a portion of the header that was not captured.

--anonymize, -A

Anonymize IP addresses in the output. The anonymization preserves prefix and class. This means, first, that two anonymized addresses will share the same prefix when their non-anonymized counterparts share the same prefix; and second, that anonymized addresses will be in the same class (A, B, C, or D) as their non-anonymized counterparts. The anonymization algorithm comes from tcpdpriv(1); it works like 'tcpdpriv -A50 -C4'.

If --anonymize and --write-tcpdump are both on, the tcpdump output file will have anonymized IP addresses. However, the file will contain actual packet data, unlike tcpdpriv output.

--no-promiscuous

Do not place interfaces into promiscuous mode. Promiscuous mode is the default.

--sample=p

Sample packets with probability p. That is, p is the chance that a packet will cause output to be generated. The actual probability may differ from the specified probability, due to fixed point arithmetic; check the output for a "!sampling_prob" comment to see the real probability. Strictly speaking, this option samples records, not packets; so for NetFlow summaries without --multipacket, it will sample flows.

--multipacket

Supply this option if you are reading NetFlow or IP summaries -- files where each record might represent multiple packets -- and you would like the output summary to have one line per packet, instead of the default one line per record. See also --packet-count, above.

--collate

Sort output packets by increasing timestamp. Use this option when reading from multiple tcpdump(1) files to ensure that the output has sorted timestamps. Combine --collate with --write-tcpdump to collate overlapping tcpdump(1) files into a single, sorted tcpdump(1) file.

--interval=time

Process packets for time, an interval length in seconds (or give a suffix like '2m' or '1hr'). For --interface, ipsumdump will quit after it has run for time. For other options, ipsumdump will quit before writing a packet whose timestamp is more than time seconds later than the timestamp on the first packet it sees.

--skip-packets=count

Skip the first count packets.

--limit-packets=count

Output at most count packets, then quit.

--map-address=addrs

addrs is a space- or comma-separated list of IP addresses and/or prefixes. When the summary dump completes, ipsumdump will write those addresses to the standard error, paired with their anonymized counterparts.

--record-counts=time

Useful when reading from interfaces. This option causes ipsumdump to write a comment recording the cumulative number of packets output, and the number of packets dropped by the kernel before ipsumdump could process them, every time seconds. (Or you can say, for example, '2m' for 2 minutes.) A sample comment:

  !counts out 0 kdrop 0
    

This says that ipsumdump has output 0 records, and the kernel reported 0 packet drops since ipsumdump began.

--random-seed=seed

Set the random seed deterministically to seed, an unsigned integer. By default, the random seed is initialized to a random value using /dev/random, if it exists, combined with other data. The random seed indirectly determines which packets are sampled, and the values of anonymized IP addresses.

--no-mmap

Do not use memory mapping when reading files. This may prevent crashes if you feed ipsumdump a corrupted file. See BUGS, below.

--quiet, -q

Do not print a progress bar to standard error. This is the default when ipsumdump isn't running interactively.

--no-headers

Do not print the IP summary dump header lines that make the dump self-describing.

--config

Do not produce a summary. Instead, write the Click configuration that ipsumdump would run to the standard output.

--verbose, -V

Produce more verbose error messages.

--help, -h

Print a help message to the standard output, then exit.

--version, -v

Print version number and license information to the standard output, then exit.