Skip to content

FromDump

Jump to bottom Edit New page
Tom Barbette edited this page Jul 28, 2023 · 5 revisions

FromDump Element Documentation

NAME

FromDump — Click element; reads packets from a tcpdump file

SYNOPSIS

FromDump(FILENAME [, keywords STOP, TIMING, SAMPLE, FORCE_IP, START, START_AFTER, END, END_AFTER, INTERVAL, END_CALL, FILEPOS, MMAP])

Batching: Batching natively supported
Ports: no inputs, 1-2 outputs
Processing: agnostic, but output 1 is push
Drivers: userlevel, ns

DESCRIPTION

Reads packets from a file produced by `tcpdump -w FILENAME' or ToDump and emits them from the output, optionally stopping the driver when there are no more packets.

FromDump also transparently reads gzip- and bzip2-compressed tcpdump files, if you have zcat(1) and bzcat(1) installed.

Keyword arguments are:

  • STOP — Boolean. If true, then FromDump will ask the router to stop when it is done reading its tcpdump file (or the END time is reached). Default is false.
  • TIMING — Boolean. If true, then FromDump tries to maintain the timing of the original packet stream. The first packet is emitted immediately; thereafter, FromDump maintains the delays between packets. Default is false.
  • SAMPLE — Unsigned real number between 0 and 1. FromDump will output each packet with probability SAMPLE. Default is 1. FromDump uses fixed-point arithmetic, so the actual sampling probability may differ substantially from the requested sampling probability. Use the sampling_prob handler to find out the actual probability.
  • FORCE_IP — Boolean. If true, then FromDump will emit only IP packets with their IP header annotations correctly set. (If FromDump has two outputs, non-IP packets are pushed out on output 1; otherwise, they are dropped.) Default is false.
  • FORCE_LEN — Integer. This parameter allows to force a desired frame length for all the frames of a trace, given that this length is in [MIN_MTU, MAX_MTU] range. To replay a trace with the real frame sizes (not the captured ones), set value to 0. Otherwise, set value to -1 to disable this feature (default case). When FORCE_LEN is 0 or in [MIN_MTU, MAX_MTU], expensive packet operations might be applied, therefore it is likely to experience lower traffic injection throughput.
  • START — Absolute time in seconds since the epoch. FromDump will output packets with timestamps after that time.
  • START_AFTER — Argument is relative time in seconds (or supply a suffix like `min', `h'). FromDump will skip the first T seconds in the log.
  • END — Absolute time in seconds since the epoch. FromDump will stop when encountering a packet with timestamp at or after that time.
  • END_AFTER — Argument is relative time in seconds (or supply a suffix like `min', `h'). FromDump will stop at the first packet whose timestamp is at least T seconds after the first timestamp in the log.
  • INTERVAL — Argument is relative time in seconds (or supply a suffix like `min', `h'). FromDump will stop at the first packet whose timestamp is at least T seconds after the first packet output.
  • END_CALL — Specify a handler to call once the end time is reached, or the dump runs out of packets. This defaults to 'FromDump.active false'. END_CALL and STOP are mutually exclusive.
  • ACTIVE — Boolean. If false, then FromDump will not emit packets (until the `active' handler is written). Default is true.
  • FILEPOS — File offset. If supplied, then FromDump will start emitting packets from this (uncompressed) file position. This is dangerous; there's no cheap way to check whether you got the offset wrong, and if you did get it wrong, FromDump will emit garbage.
  • MMAP — Boolean. If true, then FromDump will use mmap to access the tcpdump file. This can result in slightly better performance on some machines. FromDump's regular file discipline is pretty optimized, so the difference is often small in practice. Default is true on most operating systems, but false on Linux.
  • ACCELERATION — Integer. Accelerate the timing of the trace, given in percent. Ineffective if TIMING is not true. Defaults to 100, the original time.
  • TIMING_FNT — String. A function that can be used to change the ACCELERATION according to the current time. The parsing uses TinyFNT and therefore follows the format. The variable containing the time is x. E.g. "10 + min(90,10*x)" will have an acceleration from 10 to 100% in 9 seconds. See ReplayUnqueue for more details. Ineffective if TIMING is not true. Defaults to an empty string (inactive).
  • BURST — Amount of packets to read and send together as a batch. Likely useless with TIMING, but can enhance performance without TIMING when a trace is used to replay packets as fast as possible.

You can supply at most one of START and START_AFTER, and at most one of END, END_AFTER, and INTERVAL.

Only available in user-level processes.

NOTES

By default, `tcpdump -w FILENAME' dumps only the first 68 bytes of each packet. You probably want to run `tcpdump -w FILENAME -s 2000' or some such.

FromDump sets packets' extra length annotations to any additional length recorded in the dump.

FromDump is a notifier signal, active when the element is active and the dump contains more packets.

If FromDump uses mmap, then a corrupt file might cause Click to crash with a segmentation violation.

ELEMENT HANDLERS

  • count (read-only) — Returns the number of packets output so far.
  • reset_counts (write-only) — Resets "count" to 0.
  • sampling_prob (read-only) — Returns the sampling probability (see the SAMPLE keyword argument).
  • active (read/write) — Value is a Boolean.
  • encap (read-only) — Returns the file's encapsulation type.
  • filename (read-only) — Returns the filename supplied to FromDump.
  • filesize (read-only) — Returns the length of the FromDump file, in bytes, or "-" if that length cannot be determined (because the file was compressed, for example).
  • filepos (read/write) — Returns or sets FromDump's position in the (uncompressed) file, in bytes.
  • packet_filepos (read-only) — Returns the (uncompressed) file position of the last packet emitted, in bytes. This handler is useful for elements like AggregateIPFlows that can record statistics about portions of a trace; with packet_filepos, they can note exactly where the relevant portion begins.
  • extend_interval (write-only) — Text is a time interval. If END_TIME or one of its cousins was specified, then writing to this handler extends END_TIME by that many seconds. Also, ACTIVE is set to true.
  • reset_timing (write-only) — Resets timing information. Useful when TIMING is true and you skate around in the file by writing filepos.

SEE ALSO

ToDump, FromDevice.u, ToDevice.u, tcpdump, mmap, AggregateIPFlows, FromTcpdump

Generated by click-elem2man from ../elements/userlevel/fromdump.hh:14 on 2023/07/28.

Add a custom footer
Clone this wiki locally