This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.
Click kernel module driver for Linux
The Click modular router can be compiled as a Linux kernel module, called
It can steal packets from network devices before Linux gets a chance to
handle them, send packets directly to devices, and send packets to Linux
for normal processing.
The right way to load the Click kernel module is with
This installs the module if necessary, mounts the Click file system onto
the /click directory, and installs a configuration, including any required
packages. The right way to unload the Click kernel module is with
# click-install config.click
The module's API is a filesystem similar to the
filesystem. Click creates a number of files under /click (or wherever you
have mounted the filesystem), some read-only and some read/write (writable
by the superuser). You control the module by writing to these files, which
installs a router configuration by writing it to /click/config or
/click/hotconfig. The configuration can use most of Click's element classes
Several element classes control how the module receives and transmits
steal packets from devices before Linux processes them,
sends packets directly to devices, and
sends packets to Linux for normal processing. Removing the module or
installing a null configuration will restore your machine's default
The handlers under /click include:
- Read/write. Contains a Click-language description (see click(5)) of the most recent router configuration, not including any run-time reconfiguration. click-install writes a Click-language router description to this file to install a new router configuration.
- Write-only. 'click-install -h' writes a Click-language router description to this file to hot-swap install a new router configuration. The new router is installed only if it initializes correctly; otherwise, error messages will be reported to /click/errors, but the old router will keep working without interruption. If the new router initializes successfully, state from the old router, such as any packets stored in Queue elements, will be moved into the new router before it is installed. This happens on a per-element basis, and it only works if the new element and the old element have the same name. In contrast, /click/config always throws away the old router.
- Read-only. Errors reported by the Click router since the last reconfiguration (that is, the last write to /click/config or /click/hotconfig). Errors are also printed to the system log. Only the most recent 2-4KB of error messages are saved in this file.
- Read-only. All messages printed by the Click router since the last reconfiguration (that is, the last write to /click/config or /click/hotconfig). This includes messages generated by Print, among others. Messages are also printed to the system log. Only the most recent 2-4KB of messages are saved in this file.
- Read-only. The primitive element classes supported by the router, listed one per line.
- Read-only. The names of the elements in the current router configuration, listed one per line. The first line is an integer: the number of elements.
- Read-only. A Click-language description of the current router configuration, including the effects of any run-time reconfiguration. All element declarations come first, then all connections. Compound elements are expanded into their primitive components.
- Read-only. The packages that are currently linked to the Click module, listed one per line.
- Read-only. The packages required by the current configuration, listed one per line.
- /click/cycles, /click/meminfo
- Read-only. Cycle count and memory usage statistics.
- Read-only. The PIDs of any currently running Click kernel threads, listed one per line.
- Read/write. The CPU priority for Click kernel threads. Lower values have higher priority.
- Read-only. The kernel module's version number.
When compiled with --enable-adaptive, Click provides three additional
- Read/write. The minimum fraction of CPU time Click will use, even if it has no work to do. Expressed as a real number between 0.001 and 0.999. Default is 0.005. Raising this number will help Click in polling mode respond more quickly to network events.
- Read/write. The maximum fraction of CPU time Click will use, no matter how much work it has to do. Expressed as a real number between 0.001 and 0.999. Default is 0.8. Lowering this number will help user-level programs make progress, even under high network load.
- Read-only. The fraction of CPU time Click is currently using, expressed as a real number between 0 and 1.
When compiled with --enable-kassert, Click provides one additional
- Read/write. A Boolean value. If true, then Click will attempt to stop the running router, if any, if an assertion fails. Default is false.
Elements with unusual names (such as "config :: Idle;") will override these
handlers with directories. To reliably access a global handler, use the
directory, which contains only global handlers.
Every element in the current router configuration has a directory under
/click. You can access the directory by number or element name. The
element in /click/list (starting from 0) has directory
and if the element is named
that directory can be accessed as
This works even if the name contains slashes
creates directories for each name component).
Handlers in these element directories include:
- Read-only. The element's class.
- Read-only. The element's name.
- Read/write if the element supports run-time reconfiguration; otherwise read-only. The element's current configuration. Writing to this file (if it is writable) causes the element to reconfigure itself on the fly. If the reconfiguration fails, the element's old configuration is used instead.
- Read-only. Describes the element's input and output ports: how many there are, their processing type, and (for pull inputs and push outputs) what they are connected to.
- Read-only. Lists the element's handlers, one per line. Each line has the handler name and, after a tab, a permissions word. The permissions word is currently "r" (read-only), "w" (write-only), or "rw" (read/write).
Elements that have associated tasks often provide these two additional
- Read-only. A Boolean value: "true" if the element is currently on the task list, "false" if it is not.
- Read/write. Returns or sets the element's tickets, an integer that influences task scheduling priority. The more tickets a task has, the more often it will be scheduled relative to other tasks.
Particular elements may add additional handlers to their directories. For
example, RED elements (see
, and max_p
files representing RED parameters, and Counter elements (see
files to report packet counts and the recent rate.
Subelements with unusual names will override element-specific handlers
(consider "a, a/config :: Idle;"). To reliably access an element handler,
directory, which contains element
handlers and no subelements.
The subdirectories and generic files are always created, but
element-specific files are created only if the router configuration was
You almost certainly should load Click using
Nevertheless, the manual loading steps are as follows.
Load the proclikefs module with insmod(8): "/sbin/insmod proclikefs.ko". This module takes charge of the Click filesystem, allowing you to safely unload the Click module even if user-level programs have Click control files open.
Load the click module with insmod: "/sbin/insmod click.ko".
Mount the Click filesystem on a directory using mount(8). The usual choice is /click: "mount -t click none /click". The Click kernel module installs a symbolic link from /proc/click to /click.
Install a configuration by writing it to /click/config: "cat CONFIGFILE > /click/config", for example.
To uninstall Click without
kill the current router by installing an empty configuration ("echo >
/click/config"), unload any element packages, and finally
the "click" module.
If you get an unaligned access error, try running your configuration
before installing it.