Configuration Language

Click configuration language

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.

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);

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.

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

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.

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]'.

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. (In fact, they are connection tunnel endpoints; see below for more.)

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

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.

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 */ || ... }

A connection tunnel is a pair of element names that acts as a tunnel for connections. Consider a tunnel 'p1 -> p2'. Then connections to p1 pass through the tunnel and are transformed, at compile time, into connections from p2. For example, this code, with a tunnel,

connectiontunnel p1 -> p2;
a -> p1; p2 -> b;

is transformed into this code, without it:

a -> b;

The connections to p1's ith input port have been expanded into connections from p2's ith output port. Thus, a is connected to b in the result because a was connected to p1's input port 0, and p2's output port 0 was connected to b. Here is a slightly more complicated example involving several connections and different port numbers:

connectiontunnel p1 -> p2;
a -> p1; b -> p1; p2 -> c;
a [1] -> [1] p1; p2 [1] -> Discard;

is transformed into

a -> c; b -> c;
a [1] -> Discard;

And one final example:

connectiontunnel p1 -> p2;
a -> p1; p2 -> b; p2 -> c;

becomes

a -> b; a -> c;

Connection tunnels can be connected to each other. The system will recursively expand the tunnels until none of them remain. (Circular connections are silently ignored.) For example:

connectiontunnel p1 -> p2, q1 -> q2;
a -> p1; p2 -> q1; q2 -> b;

becomes

a -> b;

An identifier that has been used for a connection tunnel cannot be used for an element, and vice versa. However, an identifier can be used for two tunnels, once as the input end and once as the output end. For example:

connectiontunnel p -> p/input, p/output -> p;
a -> p; // using 'p' as input
p/input -> Counter -> p/output;
p -> b; // using 'p' as output

becomes

a -> Counter -> b;

Compound elements use this mechanism.

A configuration can say that it depends on optional packages by using the 'require' statement. Its argument is a comma-separated list of package names:

require(fastclassifier, specialcode);

Installation programs can use the package names to find and upload any necessary package code. Furthermore, the required package names are checked against a list of currently active packages when a configuration is installed. If any required packages are unavailable, an error is reported.

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 userdriver and click-install allow parameters to specified on the command line; these override any global parameters with the same names.

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 'connectiontunnel', 'elementclass', 'require', 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.

Many Click programs also accept ar(1) 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 click-install and userdriver programs will decompose the archive and install any package code before installing the configuration itself. The linuxmodule kernel module will not accept archives; use click-install.

stmts ::= stmts stmt | empty
stmt ::= declaration | connection
    | tunnelstmt | 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
tunnelstmt ::= "connectiontunnel" identifier "->" identifier
elementclassstmt ::= "elementclass" identifier class
requirestmt ::= "require" "(" configstring ")"
definestmt ::= "define" "(" configstring ")"
empty ::=

userdriver, click-install, linuxmodule

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