-
Notifications
You must be signed in to change notification settings - Fork 78
Linuxmodule
Click kernel module driver for Linux
The Click modular router can be compiled as a Linux kernel module, called click.o. 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
click-install. 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-uninstall. For example:
# click-install config.click # click-uninstall
The module’s API is a filesystem similar to the proc(5) 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 are called handlers.
click-install installs a router configuration by writing it to /click/config or /click/hotconfig. The configuration can use most of Click’s element classes (see elements). Several element classes control how the module receives and transmits packets: FromDevice and PollDevice steal packets from devices before Linux processes them, ToDevice sends packets directly to devices, and ToHost sends packets to Linux for normal processing. Removing the module or installing a null configuration will restore your machine’s default networking behavior.
The handlers under /click include:
-
/click/config
Read/write. Contains a Click-language description (see click) 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.
-
/click/hotconfig
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.
-
/click/errors
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.
-
/click/messages
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.
-
/click/classes
Read-only. The primitive element classes supported by the router, listed one per line.
-
/click/list
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.
-
/click/flatconfig
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.
-
/click/packages
Read-only. The packages that are currently linked to the Click module, listed one per line.
-
/click/requirements
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.
-
/click/threads
Read-only. The PIDs of any currently running Click kernel threads, listed one per line.
-
/click/priority
Read/write. The CPU priority for Click kernel threads. Lower values have higher priority.
-
/click/version
Read-only. The kernel module’s version number.
When compiled with --enable-adaptive, Click provides three additional handlers:
-
/click/min_cpu_share
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.
-
/click/max_cpu_share
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.
-
/click/cpu_share
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 handler:
-
/click/assert_stop
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 /click/.h 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 ith element in /click/list (starting from 0) has directory ‘/click/.e/i’, and if the element is named n, that directory can be accessed as ‘/click/n’. This works even if the name contains slashes (click.o creates directories for each name component).
Handlers in these element directories include:
-
/click/xxx/class
Read-only. The element’s class.
-
/click/xxx/name
Read-only. The element’s name.
-
/click/xxx/config
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.
-
/click/xxx/ports
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.
-
/click/xxx/handlers
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 handlers:
-
/click/xxx/scheduled
Read-only. A Boolean value: "true" if the element is currently on the task list, "false" if it is not.
-
/click/xxx/tickets
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 RED) add read/write min_thresh, max_thresh, and max_p files representing RED parameters, and Counter elements (see Counter) provide read-only count and rate 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, use the /click/xxx/.h directory, which contains element xxx’s handlers and no subelements.
The subdirectories and generic files are always created, but element-specific files are created only if the router configuration was initialized successfully.
You almost certainly should load Click using click-install. 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 click-uninstall, kill the current router by installing an empty configuration ("echo > /click/config"), unload any element packages, and finally rmmod(8) the "click" module.
If you get an unaligned access error, try running your configuration through click-align before installing it.
click, click-align, click-install, click-uninstall, insmod(1), rmmod(1), click, elements, FromDevice, PollDevice, ToDevice, FromHost, ToHost, Queue
Eddie Kohler, kohler@seas.harvard.edu
Robert Morris, rtm@lcs.mit.edu
https://github.com/tbarbette/fastclick