ToIPFlowDumps

ToIPFlowDumps Element Documentation

NAME

ToIPFlowDumps — Click element; creates separate trace files for each TCP/UDP flow

SYNOPSIS

ToIPFlowDumps(FILEPATTERN [, KEYWORDS])

Ports: 1 input, at most 1 output
Processing: agnostic
Drivers: userlevel

DESCRIPTION

Writes summary information about incoming packets, in the style of ToIPSummaryDump, to several files, one file per flow. It distinguishes flows by their aggregate annotations. You usually will run ToIPFlowDumps downstream of an AggregateIPFlows element.

The FILEPATTERN argument gives the pattern used by ToIPSummaryDump to generate filenames. Printf-like `%' escapes in the pattern are expanded differently for each flow. Available escapes are:

    %n      Aggregate annotation in decimal.
    %.0n    Upper 8 bits of aggregate annotation in decimal.
    %.1n, %.2n, %.3n   Similar for bits 16-23, 8-15, 0-7.
    %.4n    Upper 16 bits of aggregate annotation in decimal.
    %.5n    Lower 16 bits of aggregate annotation in decimal.
    %x, %X  Aggregate annotation in hex.
    %.0x, %.1x, ..., %.5x, %.0X, %.1X, ..., %.5X
            Like %.0n, ..., %.5n in hex.
    %s      Source IP address.
    %.0s, %.1s, %.2s, %.3s
            First through fourth bytes of source IP address.
    %d      Destination IP address.
    %.0d, %.1d, %.2d, %.3d
            First through fourth bytes of destination IP address.
    %S      Source port.
    %D      Destination port.
    %p      Protocol ('T' for TCP, 'U' for UDP).
    %%      A single % sign.

You may also use the `0' flag and an optional field width, so `%06n' expands to the aggregate annotation, padded on the left with enough zeroes to make at least 6 digits.

Keyword arguments are:

• NOTIFIER — The name of an AggregateNotifier element, like AggregateIPFlows. If given, then ToIPFlowDumps will ask the element for notification when flows are deleted. It uses that notification to free its state early. It's a very good idea to supply a NOTIFIER.
• ABSOLUTE_TIME — Boolean. If true, print absolute timestamps instead of relative timestamps. Defaults to false.
• ABSOLUTE_SEQ — Boolean. If true, print absolute sequence numbers instead of relative ones. Defaults to false.
• BINARY — Boolean. If true, then output binary records instead of ASCII lines. Defaults to false.
• GZIP — Boolean. If true, then run gzip to compress completed trace files. (The resulting files have .gz appended to their FILEPATTERN names.) Defaults to false.
• ALL_TCP_OPT — Boolean. If true, then output any non-padding TCP options present on TCP packets. Defaults to false.
• TCP_OPT — Boolean. If true, then output any MSS, window scaling, and SACK options present on TCP packets. Defaults to false.
• TCP_WINDOW — Boolean. If true, then output each TCP packet's window field. Defaults to false.
• IP_ID — Boolean. If true, then output packets' IP IDs. Defaults to false.
• MINCOUNT — Unsigned. Generate output only for flows with at least MINCOUNT packets. Defaults to 0 (output all flows).

NOTES

Only available in user-level processes.

EXAMPLES

This element

  ... -> ToIPFlowDumps(/tmp/flow%03n);

might create a file /tmp/flow001 with the following contents.

  !IPSummaryDump 1.1
  !data timestamp direction tcp_flags tcp_seq payload_len tcp_ack
  !flowid 192.150.187.37 3153 18.26.4.44 21 T
  !first_seq > 2195313811
  !first_seq < 2484225252
  !first_time 1018330170.887165
  0.000001 > S 0 0 0
  0.075539 < SA 0 0 1

Note that sequence numbers have been offset, so that the first sequence numbers seen by ToIPFlowDumps are output as 0. The `!first_seq' comments let you reconstruct actual sequence numbers if necessary. Similarly, timestamp annotations are relative to `!first_time'.

SEE ALSO

FromIPSummaryDump, ToIPSummaryDump, AggregateIPFlows

Generated by click-elem2man from ../elements/analysis/toipflowdumps.hh:14 on 2017/10/17.