CLICK.O(8)

NAME
click.o - Click kernel module driver for Linux

DESCRIPTION
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.

You should generally use to load the Click kernel module, rather than doing it manually. Nevertheless, the manual loading steps are as follows.

1.  Load the proclikefs module with "/sbin/insmod proclikefs.o". 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.

2.  Load the click module with insmod: "/sbin/insmod click.o".

3.  Mount the Click filesystem on a directory, DIR, using "mount -t click none DIR". Click-install will mount the filesystem on /click. For compatibility, the Click kernel module adds a symbolic link from /proc/click to /click.

4.  Install a configuration by writing it to /click/config: "cat CONFIGFILE /click/config", for example.

Use to remove the Click module, or try "/sbin/rmmod click".

The module creates a filesystem similar to the /proc filesystem for its API. It 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.

Install a router configuration by writing it to /click/config or /click/hotconfig. The configuration can use most of Click's element classes (see Several element classes control how the module receives and transmits packets: and 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 networking behavior.

The handlers under /click include:

/click/config
    Read/write. Contains a Click-language description (see of the most recent router configuration, not including any run-time reconfiguration. Write a Click-language router description to this file to install a new router configuration.

/click/hotconfig
    Write-only. Write 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 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. This behavior differs from /click/config, which 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.

  Element directories
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 has directory `/click/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). However, if an element name conflicts with a handler name, the handler is preferred. Thus, if you call an element "config", you will be able to access that element's handlers only via its number directory.

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 add read/write min_thresh, max_thresh, and max_p files representing RED parameters, and Counter elements (see provide read-only count and rate files to report packet counts and the recent rate.

The subdirectories and generic files are always created, but element-specific files are created only if the router configuration was initialized successfully.

BUGS
If you get an unaligned access error, try running your configuration through before installing it.

SEE ALSO

AUTHOR
Eddie Kohler, kohler@cs.ucla.edu
Robert Morris, rtm@lcs.mit.edu
http://www.pdos.lcs.mit.edu/click/