SILK.CONF(5)

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:

    %C  The textual class name

    %F  The textual flowtype name for this class/type pair

    %H  The hour (24-hour clock) as a two-digit, zero-padded number

    %N  The textual sensor name

    %T  The textual type name

    %Y  The year as a four-digit, zero-padded number

    %d  The day of the month as a two-digit, zero-padded number

    %f  The flowtype ID, as an unpadded number

    %m  The month of the year as a two-digit, zero-padded number

    %n  The sensor ID, as an unpadded number

    %x  The default filename, which is equivalent to "%F-%N_%Y%m%d.%H"

    %%  A literal "%" character

    For example, to place all spooled files directly in the data root directory, the path format %x could be used. To use two levels of hierarchy, the first containing the year and month, and the second containing the day and sensor name, like "2006-01/23-alpha/...", the format would be "%Y-%m/%d-%N/%x".

    If no path format is set by the configuration file, the default path format of "%T/%Y/%m/%d/%x" is used.

    All path formats are currently required to end in %x so that information may be extracted from the filename. This requirement may be lifted in the future.

    Example: %C/%T/%Y/%m/%d/%x

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

end group
    Close a group block by using the "end group" command. Following this command, top-level commands are again accepted.

    Example: end group

sensors sensor-name-or-group-ref ...
    Sensors are associated with a sensor group by means of the "sensors" command within a group block. 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 to the group being defined.

    Example: sensors my-sensor-1 my-sensor-2 @my-group-1

SEE ALSO
rwfilter(1), rwfglob(1), SiLK Installation Handbook