FromDevice Element Documentation

This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.

FromDevice Element Documentation

NAME

FromDevice -- Click element; reads packets from network device (Linux kernel)

SYNOPSIS

FromDevice(DEVNAME [, keywords PROMISC, BURST, TIMESTAMP...])

Ports: no inputs, 1 output
Processing: push
Drivers: linuxmodule
Package: linuxmodule (core)

This manual page describes the Linux kernel module version of the FromDevice element. For the user-level element, read the FromDevice.u manual page. Intercepts all packets received by the Linux network interface named DEVNAME and pushes them out output 0. The packets include the link-level header. DEVNAME may also be an Ethernet address, in which case FromDevice searches for a device with that address. FromDevice receives packets at interrupt time and stores them in an internal queue. Later, in the Click kernel thread -- that is, not at interrupt time -- a FromDevice task emits packets from that queue into the configuration. It emits at most BURST packets per task execution; BURST is 8 by default. Keyword arguments are:

PROMISC: Boolean. If true, the device is put into promiscuous mode while FromDevice is active. Default is false.

BURST: Unsigned integer. Sets the BURST parameter.

TIMESTAMP: Boolean. If true, then ensure that received packets have correctly-set timestamp annotations. Default is true.

QUIET: Boolean. If true, then suppress device up/down messages. Default is false.

ALLOW_NONEXISTENT: Allow nonexistent devices. If true, and no device named DEVNAME exists when the router is initialized, then FromDevice will report a warning (rather than an error). Later, while the router is running, if a device named DEVNAME appears, FromDevice will seamlessly begin outputing its packets. Default is false.

UP_CALL: Write handler. If supplied, this handler is called when the device or link comes up.

DOWN_CALL: Write handler. If supplied, this handler is called when the device or link goes down.

ACTIVE: Boolean. If false, then FromDevice will not accept packets from the attached device; instead, packets from the device are processed by Linux as usual. Default is true.

ALIGNMENT: Specifies the alignment of packets emitted by this FromDevice, in the form "ALIGN OFFSET", such as "4 0". FromDevice does not process this argument itself, but the click-align tool parses the argument and uses it in its calculations. The default ALIGNMENT is 4 2.

NOTES

Linux won't see any packets from the device. If you want Linux to process packets, you should hand them to ToHost. FromDevice accesses packets the same way Linux does: through interrupts. This is bad for performance. If you care about performance and have a polling-capable device, use PollDevice instead. Linux device drivers should have set packets' timestamp, packet-type, and device annotations, so packets emitted by FromDevice generally have these annotations.

Patchless Installations

On patchless installations, FromDevice works by repurposing the hooks used for Ethernet bridging. It is not advised to use FromDevice and the Ethernet bridge module simultaneously. On patched installations, FromDevice intercepts packets before they are passed to packet sniffers like tcpdump. However, on patchless installations, packet sniffers receive incoming packets before FromDevice can intercept them. This means that in a configuration such as

  FromDevice(eth0) -> ToHost;

packet sniffers will see eth0's packets twice, once before FromDevice runs and once when the packets are handed back to Linux via ToHost.

ELEMENT HANDLERS

active (read/write): The write handler sets the ACTIVE parameter. The read handler returns the ACTIVE parameter if the device is up, or "false" if the device is down.

count (read-only): Returns the number of packets emitted so far.

length (read-only): Returns the current length of FromDevice's internal packet queue.

reset_counts (write-only): Resets the count and drops handlers.

COMMENTS