-
Notifications
You must be signed in to change notification settings - Fork 81
ToUserDevice
ToUserDevice — Click element; Pass packets to user-level programs via a character device.
ToUserDevice(DEV_MINOR, [KEYWORDS])
Ports: 1 input, no outputs
Processing: push
Drivers: linuxmodule
ToUserDevice provides a way to get packets from click running in linuxmodule into userspace through a character device. This is a way of giving packets to a user process without going through linux's routing or networking code. Internally, ToUserDevice has a queue of packets.
ToUserDevice can optionally apply encapsulation to the packets, either pcap encapsulation or length-delimited encapsulation.
The character device can act like a datagram socket, where one packet is returned per read()/recv() call (but the packet may end up truncated), or it can act like a streaming socket where all packet data is reliably returned in a stream. In order to reliably be able to detect packet boundaries, it makes the most sense to use one of the encapsulation types if using the streaming interface.
In addition, ToUserDevice can run in a mode where reads will block until there is data available (the default mode) or it can run in a mode where read() will return 0 (end-of-file) if the device is empty. This can be particularly useful with the pcap format where the character device will appear to be a valid pcap file.
Requires --enable-experimental.
Keyword arguments are:
- CAPACITY — Unsigned integer. Sets the capacity of the internal ring buffer that stores the packets. Defaults to 64.
- BLOCKING — Boolean. If true, then reads will block until there is data to return. If false, reads when the ring buffer is empty will return 0. Defaults to true.
- DROP_TAIL — Boolean. Sets the drop policy of this device if the ring buffer is currently full. Defaults to true.
- ENCAP — String. Must be one of: none, pcap, len32, or len_net16. Defaults to 'none.' Choosing pcap will cause each new open of the character device to first receive a valid pcap file header, and add individual pcap packet headers to each packet. len32 prepends a uint32 in host byte order before each packet with the packet's length. len_net16 prepends a uint16 in network byte order before each packet with the packet's length.
- PCAP_NETWORK — Unsigned integer. When using 'ENCAP pcap', this changes the reported network type of the pcap file. Defaults to 1 (Ethernet).
- PCAP_SNAPLEN — Unsigned integer. This limits the amount of packet data returned by the 'pcap' encapsulation type. Only affects the pcap type. Defaults to 65535.
- TYPE — String. Must be one of 'packet' or 'stream'. It defaults to 'packet' if ENCAP is 'none', and to 'stream' otherwise.
- BURST — Unsigned integer. Sets the maximum number of packets returned per read. Default is 1. Zero means unlimited. It is likely not wise to set this to anything except 1 if this is a 'TYPE packet' device.
- DEBUG — Boolean. Causes the element to print many debugging messages. Defaults to false.
The device must be first created in the /dev directory via 'mknod /dev/fromclickX c 241 X' where X is the minor device number (i.e. 0, 1, 2)
A user level application can then read directly from the device once it opens a file /dev/fromclickX
Generated by click-elem2man from ../elements/linuxmodule/touserdevice.hh:13 on 2018/10/03.