NAME

silk.conf - SiLK site configuration file

DESCRIPTION

The silk.conf SiLK site configuration file is used to associate symbolic names with the numeric sensor, class, and type information stored in SiLK flow records. The complete list of sensors, classes, and types, as well as the default class and the default types for each class, and the defined path format are also used by the rwfilter(1) and rwfglob(1) tools to determine what filenames should be searched for your query.

In normal usage, the silk.conf file will be located at the root of the SiLK data spool referenced by the SILK_DATA_ROOTDIR environment variable, or specified on the command line using the --data-rootdir flag. This ensures that the sensor and class definitions in the site configuration match the data in the flow records you retrieve.

If you cannot place a config file in the data root directory, or the file in that location is incorrect, you can use the SILK_CONFIG_FILE environment variable to specify the location of your configuration file (including the filename).

SYNTAX

In the site configuration file, each line may be blank, or contain any amount of leading whitespace, which is ignored. At any location in a line, the character # indicates the beginning of a comment, which reaches until the end of the line. (If a literal # symbol is required in the argument of any command, it may be quoted as described below.) These comments are ignored.

Each non-empty line begins with a command name, followed by one or more arguments. Command names are a sequence of non-whitespace characters, not including the characters # or " (see below for valid commands). Arguments may either be textual atoms (any sequence of non-whitespace characters, non-#-or-" characters, including numerals and punctuation), or quoted strings. Quoted strings begin with the character " and end with the character ", and allow for C-style backslash escapes in between. The character # inside a quoted string does not begin a comment, and whitespace is allowed inside a quoted string.

There are three contexts for commands: top-level, class block, and group block contexts. The class block and group block contexts are used to describe individual features of classes and groups, while top-level commands are used to describe the entire configuration, and to define sensors.

The valid commands for each context are described below.

Top-Level Commands

class class-name: The class command begins a new class block. It takes as an argument the name of the class being defined. A class block is closed with the end class command. See below for a list of commands valid inside class blocks.; A site that does not use multiple classes should define a single class with a name like all or default.; Every valid configuration file must contain at least one class definition.; Currently, class and type names are compiled into the rwflowpack(8) and flowcap(8) daemons. When class names are added or modified, the source code for those programs must be modified as well.; Example: class all
default-class class-name: Several commands have a default class that they work on, which is defined by this option. The class to be set as default must be created before it may be set as the default class. If more than one default class is set, the last definition encountered is used.; Example: default-class all
group group-name: Sensor groups are a convenient way of defining named groupings of sensors for inclusion in classes. They cannot currently be used in the SiLK command-line tools, but only in the configuration file. The group command takes as an argument the group to be defined, and begins a group block. A group block is closed using the end group command. See below for details on valid commands within group blocks.; Example: group test-sensors
include ``file-name'': The include command is used to include the contents of another file. This may be used to separate large configurations into logical units. (Note, however, that all sensors, classes, groups, and types must be declared before they may be referenced.); Example: include ``silk-2.conf''
packing-logic ``file-name'': The packing-logic command provides a default value for the --packing-logic switch on rwflowpack(8). The value is the path to a plug-in that rwflowpack loads; the plug-in provides functions that determine into which class and type a flow record will be categorized. The path specified here will be ignored when the --packing-logic switch is explicitly specified to rwflowpack or when SiLK has been configured with hard-coded packing logic.; Example: packing-logic ``packlogic-twoay.so''
path-format ``format-string'': File and directory locations relative to the SILK_DATA_ROOTDIR may be defined using the path-format command. This command takes a format string specification that allows the following special sequences:
sensor sensor-id sensor-name: Individual sensor definitions are created with the sensor command. This command creates a new sensor with the given name and numeric ID. Sensor names must begin with a letter, and may not contain whitespace characters, or the characters / or _.; It is an error to define two different sensors with the same sensor ID or the same sensor name.; NOTE: It is extremely important not to change the sensor-id or sensor-name for a given sensor once that sensor is in use. The sensor-id field is stored numerically in SiLK data files, and the sensor-name field is used to construct filenames within the data root directory.; Example: sensor 0 S001
version version-number: The version command declares that this configuration file conforms to a given version of the configuration file format. If the tools do not support this version of the configuration file, they will report an error. Currently, only version 1 of the format is defined.; It is a recommended practice to include the version number at the beginning of all configuration files for compatibility with future versions.; Example: version 1

Class Block Commands

end class: The end class command ends the definition of a class. Following an end class command, top-level commands are again accepted.; Example: end class
default-types type-name ...: When no types are specified for the rwfilter or rwfglob commands, the default set of types for the selected class is used. Each of the types listed here is included as a default type of the class.; Example: default-types in inweb
sensors sensor-name-or-group-ref ...: The sensors command is used to associate sensor with a class. In short, to declare that these sensors have data for this class. Sensors may be listed by name or numeric ID, and sensor groups may also be added by prefixing their names with an at (@) character. When you add a sensor group, it is the same as individually adding each sensor in that group to the class.; Example: sensors my-sensor-1 my-sensor-2 @my-group-1
type flowtype-id type-name [ flowtype-name ]: Types within a class are defined using the type command. Classes are generally used to represent topological features with different collections of sensors (although they may overlap). Types, on the other hand, are used to distinguish traffic within a single topological area on some other dimension. For example, incoming and outgoing traffic is generally distinguished into different types. Web traffic is also frequently split into a separate type from normal traffic in order to partition the data better.; Types have a unique numeric ID (the flowtype ID), a type name that is unique within the class. They may, however, be the same as a type name in another class (the type name) and a flowtype name that must be unique across all classes (the flowtype name). If the optional flowtype name is not provided, a default flowtype name is constructed by concatenating the name of the class and the name of the type. (e.g. the type in in the class all would have a flowtype name of allin.); As with sensors, it is important to be careful when renaming or renumbering types because the numeric IDs are stored in data files, and the textual names are used as portions of file and pathnames.; Currently, class and type names are compiled into the rwflowpack(8) and flowcap(8) daemons. When class names are added or modified, the source code for those programs must be modified as well.; Example: type 0 in; Example: type 1 out out

Group Block Commands