CLICK(5)

NAME
click - Click configuration language

DESCRIPTION
The Click language describes the configuration of a Click router. It has two main directives: declarations declare new elements, and connections connect those elements together. Click router configurations are like directed graphs of elements; in this interpretation, declarations specify the vertices of the graph and connections specify the edges. Other language statements define configuration parameters and create new element types.

  Declarations
A declaration looks like this: name :: class(config); (The semicolon, like all semicolons in Click syntax, is optional.) This declares an element called name that has element class class and configuration arguments config. If the configuration string is empty, the parentheses can be left off. Also, there can be two or more names in a comma-separated list, which has the same effect as multiple declarations. name :: class;
name1, name2, ..., nameN :: class(config);

  Connections
A connection looks like this: name1 [port1] -> [port2] name2; where the two names are names of previously declared elements, and the two ports are nonnegative integers. This says that name1's output port port1 should be connected to name2's input port port2. Two connections can be strung together into a single statement if the output element of one is the same as the input element of the other: n1 [p1] -> [p2] x;
x [p3] -> [p4] n2; is the same as n1 [p1] -> [p2] x [p3] -> [p4] n2; This can be extended to three or more connections. Furthermore, if an input or output port is 0, it can be omitted along with the brackets. These two lines are equivalent: n1 [0] -> [0] n2;
n1 -> n2;

You can also declare elements inside connections: ... -> [p1] name :: class(config) [p2] -> ...; is equivalent to name :: class(config);
... -> [p1] name [p2] -> ...; Every such declaration can declare at most one element.

  Anonymous elements
You may declare an element without specifying its name, in which case the system will choose an element name for you. For example: class(config); is equivalent to generatedname :: class(config); As usual, the parentheses can be left off if config is empty. You may also declare an anonymous element inside a connection: ... -> [p1] class(config) [p2] -> ...; is equivalent to generatedname :: class(config);
... -> [p1] generatedname [p2] -> ...;

The generatedname has the form `class@number', where the number is chosen to make the name unique. These numbers are predictable: when the system parses a Click file twice, that file's anonymous elements will get the same generated names each time. Nothing prevents a user from declaring an element named like an anonymous element. We suggest that users avoid the `@' character in their element names.

Not all elements can usefully be anonymous, since an anonymous element can be part of at most two connections (once as input, once as output).

CONFIGURATION STRINGS
Click configuration strings are comma-separated lists of arguments, where each argument is a space-separated list of objects. This section describes some common object types. See the element documentation for argument types expected by a particular element.

Configuration strings may contain comments (`// ... EOL' and `/* ... */'), which are replaced with single space characters. Inside single- or double-quoted strings, commas, spaces, and comment-starting sequences lose their regular meaning and are treated as normal characters.

The most common object types are:

•   Strings. Any sequence of characters. Single- or double-quoted strings are allowed (and required, if the string contains a space or comma). Inside double-quoted strings, backslash substitutions are performed; see below. You can concatenate strings by juxtaposing them. For example, `a"b"c' is equivalent to `abc'.

•   Booleans. `0', `false', and `no' mean false; `1', `true', and `yes' mean true.

•   Integers preceded by an optional `+' or `-' sign. Decimal, octal (first digit `0'), and hexadecimal (starting with `0x') are allowed.

•   Real numbers in decimal notation.

•   Times and delays in decimal real notation, followed by an optional unit: `s'/`sec', `ms', `us', `ns', `m'/`min', `h'/`hr'.

•   Bandwidths in decimal real notation, followed by an optional unit: `bps' or `Bps' for bits or bytes per second, with an optional SI prefix `k', `M', or `G'. The default unit is generally `Bps'.

•   IP addresses in the conventional `n.n.n.n' form (for example, `18.26.4.15').

•   IP network prefixes in the CIDR form `n.n.n.n/k' (for example, `18.26.4/24').

•   IPv6 addresses in any of the conventional forms (for example, `::', `1080::8:800:200C:417A', or `::18.26.4.15').

•   Ethernet addresses in the conventional `x:x:x:x:x:x' form (for example, `0:a0:c9:9c:fd:9c').

•   Element names.

Some elements, like Classifier, take arguments that don't fit any of these types. See the element documentation for details.

If the last argument in a configuration string is empty (containing only whitespace and comments), then it is ignored. Thus, `Element(1, )', `Element(1, /* comment */)', and `Element(1)' behave exactly alike.

Configuration strings may also contain parameter references, such as `$interface'. The parameter values are substituted in. Parameters may be defined either by compound element arguments, by explicit `define' statements, or on the command line.

  Backslash Substitutions

The following backslash substitutions are performed inside double quotes. Additionally, as a special case, a bare data substitution sequence `\< ... >' acts as if it were enclosed in double quotes. (Inside single quotes, `\< ... >' is not special.)

1.  C-like substitutions. Specifically, `\a', `\b', `\t', `\n', `\v', `\f', `\r', `\\', and `\[1, 2, or 3 octal digits]' have their C meanings. `\x[any number of hex digits]' is replaced with the byte defined by the last 2 hex digits.

2.  Data substitutions. An escape sequence `\< ... hex digits and spaces ... >' is replaced with the data represented by the hex digits. For example, the sequence `\< 48 45 4c 4C 4f >' is replaced with `HELLO'.

3.  Backlash-newline sequences (`\[LF]', `\[CR]', or `\[CR][LF]') are removed.

4.  Any other `\[CHAR]' sequence is replaced with `[CHAR]'.

COMPOUND ELEMENTS
A compound element is a scoped collection of elements that acts like a single element from outside. A compound element can be used anywhere an element class is expected (that is, in a declaration or connection). Syntactically, a compound element is a set of Click statements enclosed in braces `{ }'. Inside the braces, the special names `input' and `output' represent connections from or to the outside. Before a router is put on line, compound elements are systematically expanded until none remain; thus, they have no run-time overhead.

Here are some examples. This code, with a compound element, a -> { input -> X -> output } -> b; expands to a -> X -> b; Here is a more complicated example, with multiple ports: compound :: {
input -> X -> output;
input [1] -> Y -> [1] output;
};
a -> compound -> b;
c -> [1] compound [1] -> d; expands to a -> X -> b;
c -> Y -> d;

The `input' and `output' pseudoelements incur no run-time overhead.

The actual expansions will differ from these examples because the elements will have different names. A prefix is prepended to the components' names, providing locality relative to other names in the configuration. The new names have the form `compoundname/componentname', where compoundname is the name of the compound element being expanded, and componentname is the name of the component element inside that compound. For example, compound :: { input -> x :: X -> output };
a -> compound -> b; is really expanded to a -> compound/x :: X -> b; For this purpose, anonymous compound elements are given constructed names like `@number'. Nothing prevents a user from declaring an element named like a compound element component. We suggest that users generally avoid using the `/' character in their element names.

It is an error to use the `input' pseudoelement's input ports or the `output' pseudoelement's output ports. It is also an error to leave an intermediate port unused -- for example, to use `input [0]' and `input [2]' but not `input [1]'.

  The `elementclass' statement
The `elementclass' statement lets the user name a frequently-occurring compound element, and use the name as if it were a primitive element class. Syntactically, it looks like this: elementclass identifier compoundelement ; After this statement, every occurrence of the identifier will be replaced with the compoundelement. For example, this code, with an `elementclass': elementclass MyQueue {
input -> Queue -> Shaper(1000) -> output;
}
q :: MyQueue;
a -> q -> b; is equivalent to this code, without it: q :: { input -> Queue -> Shaper(1000) -> output };
a -> q -> b; which roughly expands to: a -> Queue -> Shaper(1000) -> b;

The user can declare element classes that have the names of previously existing element classes: elementclass Queue {
input -> Queue -> Shaper(1000) -> output;
} Element classes are nonrecursive and lexically scoped, so the `Queue' inside this definition refers to the original `Queue'. The scope of an element class definition extends from immediately after its closing right brace to the end of the enclosing scope.

A variant of the elementclass statement makes synonyms for preexisting element classes. For example, this statement elementclass MyQueue Queue; makes MyQueue a synonym for Queue.

  Configuration parameters
Compound elements may take configuration parameters, which are expanded into the configuration strings of its components. The parameters are named at the beginning of the compound element. Each parameter looks like a Perl variable -- a dollar sign followed by one or more letters, numbers, and underscores. For example, this compound element { $a, $b | ... } takes two configuration parameters, named `$a' and `$b'. Keyword arguments are also supported. For example, this compound element { COUNT $count | ... } takes a COUNT keyword parameter. Mismatched configuration parameters cause errors; for example: { $a, $b | ... } (1) // Error: too few arguments
{ $a, $b | ... } (1, 2, 3) // Error: too many arguments
{ COUNT $count | ... } (1) // Error: missing 'COUNT' parameter The special keyword `__REST__' matches any additional arguments supplied to the compound element. For example: { $a, COUNT $count, __REST__ $rest | ... }
(1, 2, COUNT 3, FOO 4) This compound element will be expanded with `$a' set to `1', `$count' set to `3', and `$rest' set to `2, FOO 4'.

In a compound element definition, all positional parameters must precede any keyword parameters, and `__REST__', if present, must appear last of all.

As the compound is expanded, its components' configuration strings are searched for references to the parameters. Any such references are replaced with the supplied arguments. For example, this code: ... -> { $a | input ->
A(1, $a, 3) -> output } (100) -> ... expands to this: ... -> A(1, 100, 3) -> ... You can avoid substitution by putting the dollar sign inside single quotes.

Use braces, like `${a}', to avoid including following letters in a variable name. Click also supports the shell-like `${VAR-DEFAULT}' syntax, which substitutes the value of `$VAR', or `DEFAULT' if that variable was not set. See also PARAMETER DEFINITIONS, below.

  Overloading
A single compound element may contain multiple overloaded definitions separated from one another by two vertical bars "||". Different definitions may have different numbers of input ports, different numbers of output ports, or different sets of configuration arguments. For example, this extended MyQueue compound element takes an optional capacity argument, just like Queue itself: elementclass MyQueue {
input -> Queue -> Shaper(1000) -> output;
||
$cap | input -> Queue($cap)
-> Shaper(1000) -> output;
} For each use of an overloaded compound element, Click will choose the first definition that matches the provided number of input ports, number of output ports, and configuration arguments. It is an error if no definition matches these properties exactly.

It is also possible to extend an existing element class with new overloaded definitions with "...". For example, this definition introduces a two-argument version of Queue: elementclass Queue {
$cap, $rate | input -> Queue($cap)
-> Shaper($rate) -> output;
|| ...
} (The ellipsis in this example must be typed verbatim.) The overloadings visible at a given declaration are those that lexically precede that declaration. For example, the following example is an error since the two-argument version of Test is not visible at the declaration where it is required: elementclass Test { $a | /* nothing */ }
test :: Test(1, 2);
elementclass Test { $a, $b | /* nothing */ || ... }

REQUIREMENTS
The `require' statement is used to link a configuration with optional packages and libraries. Its argument is a comma-separated list of requirements.

Packages, which are dynamic objects including new compiled element definitions, are included with `require(package)' declarations: require(package fastclassifier, package specialcode); Installation programs can use the package names to find and upload any necessary package code. The required package names are also checked against a list of currently active packages when a configuration is installed. If any required packages are unavailable, an error is reported.

Libraries, which are Click configuration files that (for instance) might declare new compound element definitions, are included with `require(library)' declarations: require(library mycompounds.click); Installation programs search CLICKPATH for the named library file. `require(library)' can only be used at file scope, and a given library file is included at most once, no matter how many times it is mentioned in `require' statements.

PARAMETER DEFINITIONS
Parameters are defined using the `define' statement. Its argument is a comma-separated list of pairs, each pair consisting of a configuration variable and a value: define($DEVNAME eth0, $COUNT 1); This sets the `$DEVNAME' parameter to `eth0' and the `$COUNT' parameter to `1'. Definitions are lexically scoped, so definitions inside a compound element are not visible outside it. However, all definitions in a given scope take place simultaneously, regardless of their ordering. The following two configurations have the same effect: 1) define($a 2); Message($a)
2) Message($a); define($a 2) It is an error to define a parameter more than once in any single scope. Click programs such as and allow parameters to specified on the command line; these override any global parameters with the same names.

LEXICAL ISSUES
Click identifiers are nonempty sequences of letters, numbers, underscores `_', at-signs `@', and slashes `/' that do not begin or end with a slash. The system uses `@' and `/' for special purposes: `@' in constructed names for anonymous elements and prefixes, and `/' in names for components of compound elements. Users are discouraged from using these characters in their own identifiers. Identifiers are case-sensitive. No component of an identifier may consist solely of numbers; for example, `1/x' is an illegal identifier.

The keywords `elementclass', `require', `provide', and `define' may not be used as identifiers. The normal identifiers `input' and `output' have special meaning inside compound element definitions.

The following characters and multi-character sequences are single Click tokens:
    -> :: ; , ( ) [ ] { } | || ...

Whitespace (using the C definition) and comments separate Click tokens. Click uses C++-style comments: from `//' to the end of the line, or from `/*' to the next `*/'. Either form of comment terminates an identifier, so this Click fragment
    an/identifier/with/slashes//too/many
has an identifier `an/identifier/with/slashes' and a comment `//too/many'. No identifier contains two consecutive slashes.

Parameters, which are used in compound elements, look like Perl variables. A parameter consists of a dollar sign `$' followed by one or more letters, numbers, and underscores.

A configuration string starts immediately following a left parenthesis `(', and continues up to the next unbalanced right parenthesis `)'. However, parentheses inside single or double quotes or comments do not affect balancing. Here are several examples; in each case, the configuration string consists of the text between the `#' marks (including the `#' marks themselves). C1(#simple string#)
C2(#string with (balanced parens)#)
C3(#string with ")quoted" paren#)
C4(#// end-of-line comment)
still going!#)
C5(#/* slash-star comment) */ and backslash \#)

A Click program may contain C preprocessor-style line directives. These lines start with `#' and have the form `# linenumber "filename"' or `#line linenumber "filename"'; they change the filenames and line numbers used for error messages. The filename portion is optional. Line directives are not recognized inside configuration strings.

ARCHIVES
Many Click programs also accept archives as configurations. The archive must contain a member called `config', which is treated as a Click-language configuration. The archive may also contain package code required by the configuration. The and programs will decompose the archive and install any package code before installing the configuration itself. The kernel module will not accept archives; use

BNF GRAMMAR
stmts ::= stmts stmt | empty
stmt ::= declaration | connection
| elementclassstmt | requirestmt
| definestmt | ";"
declaration ::= element-names "::" class opt-config
element-names ::= element-name
| element-names "," element-name
element-name ::= identifier
class ::= identifier | "{" compounds "}"
| "{" compounds "||" "..." "}"
compounds ::= compound | compounds "||" compound
compound ::= stmts | opt-formals "|" stmts
opt-formals ::= formals | empty
formals ::= formal | formals "," formal
formal ::= parameter | identifier parameter
connection ::= element opt-port "->" opt-port conntail
conntail ::= element | connection
element ::= element-name
| element-name "::" class opt-config
| class opt-config
opt-config ::= "(" configstring ")" | empty
opt-port ::= "[" portnumber "]" | empty
elementclassstmt ::= "elementclass" identifier class
requirestmt ::= "require" "(" configstring ")"
definestmt ::= "define" "(" configstring ")"
empty ::=

SEE ALSO

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