Name

configuration — general syntax of configuration files

Description

Configuring a proxy

Each Kernun firewall proxy must be started with a configuration file (the -f option). In fact, in the current version of the Kernun Firewall, these configuration files (so called low-level configuration files) are generated by the CML (Configuration Meta Language) tool (see cml(8)). Nevertheless, the syntax rules for the CML (high-level) configuration files are the same as for the low-level ones.

This manual page describes the general syntax rules for the configuration file. The definitions governing the configuration of particular applications are described in the pertinent section 5 manual pages (e.g. ftp-proxy.cfg(5) for ftp-proxy). In the CML, the description can be displayed by

  /info descr topic

Configuration versions

In order to make detection of errors stemming from the use of an old configuration files for newer applications easier and to simplify conversion of older configurations to newer formats, every configuration file must contain the version of Kernun firewall it is designed to work with. For example, version 2.3 of Kernun firewall expects the following line at the beginning of every configuration file:

  version KERNUN-2_3-RELEASE;

The version tag is Kernun's distribution version string. It can be obtained by running a Kernun application with the -v option. Also, every section 5 manual page refers to the proper version in the VERSION section. Configuration files generated by the CML have this line generated automatically.

Syntax

Structure of the configuration file

A configuration file consists of sections and items.

An item is a configuration command. It begins with a word (the item's keyword) followed by its elements, that is, attributes represented by values of various types. An example of an item command with its elements:

  command { RETR, STOR } size 33K;

An item can be defined as repeatable (all of its occurrences are chained) or non-repeatable (only one occurrence is allowed).

A section is a block of items and/or subsections. It begins with a word (the section's keyword) followed by items and subsections enclosed in a pair of braces. A repeatable section must have its name before the first opening brace. Examples:

  ftp-proxy FTP {          # repeatable section ftp-proxy named FTP
    proxy-user kernun;     # item proxy-user
    msgs {                 # non-repeatable subsection msgs
      welcome "Welcome";   # item welcome
    }
  }

The allowed sections, items, types etc. for each application configuration are described in the section 5 manual page (e.g. ftp-proxy.cfg(5) for the ftp-proxy). In order to facilitate configuring of similar functions in different proxies by the same means, the configuration description consists of so-called prototypes, from which particular proxy-dependent constructions are derived. For instance, the acl section prototype collects all general sections and items used in ACL declarations (see access-control(7)), the acl-1 section prototype is derived from the acl prototype by modifying some features to fit phase 1 ACL decisions and the ftp-proxy session-acl section is derived from the acl-1 prototype to fit session-initialisation phase decisions in FTP. In such cases, the special section 5 manual page describes only the modifications to the prototypes and the prototypes themselves are described in their own section 5 manual page (e.g. acl(5) in this case).

More occurrences of a non-repeatable section or of a repeatable section with the same name lead to an error.

The order of items/subsections with different names is irrelevant. The synonymic items/subsections are searched in the order they are entered and the order may be meaningful (e.g. first-match), if it is stated so in the section 5 manual page. Otherwise, it is simply an (OR-ed) list of information.

Configuration atoms

The basic term of configuration description is an atom. There are the following atom types in Kernun configuration:

integer

A positive integer value in decimal or hexadecimal (C-style: 0xhex) form; the decimal ones can have 'K', 'M', 'G' and 'T' suffices meaning 1000, 1000000, 1000000000 and 1000000000000 values respectively, or 'Ki', 'Mi', 'Gi' and 'Ti' suffices meaning 1024, 1048576, 1073741824 and 1099511627776 values respectively, or 'd', 'h' and 'm' suffices meaning days (x 86400), hours (x 3600) and minutes (x 60) respectively.

fractional

A positive fractional value with up to three decimal digits (e.g. 1.95, 2). Internally, this atom is stored as an integer value (multiplied by 1000) so it behaves like an integer.

word

A sequence of letters, digits, underscores ('_') and hyphens ('-') (e.g. ftp-data, kerberos_master); words are case-insensitive.

string

A string of characters enclosed in double quotes. C-style escapes ('\t', '\r', '\n', '\"', '\\' and '\xhex) must be used to code special characters. If a string is a concatenation of words, dots ('.') and at-signs ('@') then it need not be enclosed in quotes (e.g. root@tns.cz).

IP address

An IPv4 address in dotted decimal format. It MUST be enclosed in square brackets (e.g. [127.0.0.1]).

IP address with mask

IPv4 netmask must follow immediately after an IP address (inside the square brackets), starting with a slash; the allowed formats include single number (the number of bits), dotted decimal format and hexadecimal format (e.g. [127.0.0.0/8], [10.0.21.0/255.0.255.0], [10.0.0.0/0xFF000000]). Note that exactly four bytes must be specified in the dotted notation, even if they are zero.

regexp

A UNIX regular expression enclosed within a pair of slashes. Inside regexp, literal slashes and spaces must be escaped with backslash (e.g. /ab\ \/\ cd/ matches string "ab / cd"). The character 'i' following immediately after the closing slash makes this regexp to be case-insensitive (e.g. /abc/i matches all of "abC", "AbC", "ABC" etc.).

Atoms can be separated by a sequence of white-space charaters (space, tab, newline). Thus, newlines (except in comments) have the same meaning as a single space.

A comment starts with a hash ('#') character and ends at the end of line. Note that in the CML, comments are allowed on the session level only (i.e. between two items/subsections, not within items, after section names etc.).

Types

Item elements have defined types and only values (i.e. atoms) of proper type can be used in configuration (see the section called “Configuration atoms”). The following table defines the atom types that are allowed for known types:

uint8

integer value (size: 8 bits).

uint16

integer value (size: 16 bits).

uint32

integer value (size: 32 bits).

uint64

integer value (size: 64 bits).

port

integer value or word (recognized by getservbyname(3), usually stored in /etc/services file).

time

integer value of daytime in form hhmm.

fract

fractional value (size: 32 bits after multiplying by 1000).

str

string or word value; known keywords used as simple string must be quoted.

regexp

Regular expression (see regexp).

host

Hostname (expressed as a string) or an IP address without mask.

addr

Interface IP address. If mask is omitted, default mask according to class is assumed. Local part of address must not consist of all-zeros or all-ones.

net

Network IP address. If mask is omitted, default mask according to class is assumed. Local part of address must be zero.

sock

Hostname or IP address followed by colon (':') and port number or name (e.g. [127.0.0.1] : 3333, ftp.freebsd.cz:ftp).

key

Exactly the keyword specified in configuration description (Section 5 manual page) of particular item can be used.

Enumerations

For some types, mnemonic names may be used instead of direct integer values. For instance, the dns-type type recognizes the word CNAME instead of the value 5. Such types are called enumerations. For some enumerations, the use of mnemonic names is obligatory since the corresponding integer values have no real meaning (e.g. FTP command numbers in the ftp-cmd type). The description of allowed enumerations is a part of every section 5 manual page. In the CML, you can display the description of an enumeration using

  /info enum enumeration

Section-Name Types

Every repeatable section at the global level can be used to create a special type from the section's keyword and the suffix "-NAME". Prospective values of such a type include the names of all sections (of the proper type). Example:

Suppose the following definition:

  radius-client FIRST {
    server radius.xyz.com "shared secret";
  }

Then, the following item is correct, if its second element is of the radius-client-name type:

  auth radius FIRST;

Lists

A sequence of zero or more instances of a base-type (see above) is called a list. List items are enclosed in braces ('{' and '}') and separated by commas (','). If the list contains only one member, the braces are not neccesary. The type name for a list is derived from the base type by suffixing with "-LIST". Example:

The following value is acceptable for the type port-list:

  { ftp, ftp-data, 512 }

It represents three values (the ftp and ftp-data ports, and port 512).

A list can have another list as a member. In this case, all sublist members become members of the main list. Example:

The above list can be also expressed as:

  { { ftp, ftp-data }, 512 }

Sets

A set is another way to specify more values acceptable for an element. The type name for a set is derived from the base type by suffixing with "-SET".

The basic difference between lists and sets is that the former can be used by an application for 'going through all list members', and the latter only for testing 'whether a value matches the set or not'. That is why sets can have the following special members:

Ranges of values

Two values separated by a hyphen ('-'). Care should be taken if the lower value is represented by a word; in such a case, the word must be separated from the hyphen by at least one white-space character (e.g. 'ftp-http' is treated as one word, while 'ftp - http' is a correct range).

Excluding members

Members prefixed by an exclamation mark ('!') are treated as value that is not a member of current (sub)set. The matching algorithm works as FIRST-MATCH. Therefore, the excluding members must precede non-excluding members containing excluded values in the same (sub)set. Otherwise, the values are treated as being members of the (sub)set.

ANY value

The wildcard character * represents a set containing all acceptable values (possibly except the ones specified in excluding members of the (sub)set).

Examples:

The following values are acceptable for the type port-set:

  { ! { ftp - ftp-data }, * }      # all ports except FTP ones
  { ! { ftp - ftp-data }, 1-1024 } # all generic ports except FTP

The following value is syntactically correct, but has no meaning, because FTP ports were excluded after including them:

  { 1-1024, ! ftp - ftp-data }     # all generic ports

The following value is syntactically correct as well, but has no meaning either, because FTP ports were excluded in a subset and no * or range item is present within this subset:

  { { ! ftp - ftp-data }, 1-1024 } # all generic ports

In the last two examples above, configuration reader logs a warning.

For two types, suffix "-SET" extends the possibilities of specifying values:

str-set member

Besides strings and words, regular expressions can be specified. Note that matching of strings in str-set is done in ignore-case manner, whereas ignore-case matching of regular expressions must be forced by the 'i' suffix (see above the Configuration atoms paragraph).

host-set member

Besides hostnames, regular expressions can be specified. IP addresses can have a netmask.

Example:

The following host-set value matches any hostname ending with .cz and any address matching 10.0.*.1:

  { /^.*\.cz$/, [10.0.0.1/0xFFFF00FF] }

Matching of host values against host-sets is slightly more complicated, see host-matching(7) for details.

Elements

The order and types of elements in an item are fixed. Each element of an item has a type, as discussed above. Unless special conditions (stated below) apply, all elements must be included in every occurrence of an item.

An element can be omitted only if it is defined (in the pertinent Section 5 manual page) as an element with a default value and if one of the two following conditions are true:

  1. The element is defined to have an arbitrary keyword.

  2. No following element of the item is to be used.

Moreover, some items can be used in several different forms; the particular form is selected by the value of a special element (so called branching element).

An example of a section 5 manual page:

The configuration of the acl library component consists of the following prototypes:


* user ... ;
  ...
    

Description:

user none;

user [name] [name [group group]];

User and group specification.

<branching element> (type: user-auth-spec, optional, default: name)

name (type: str-set, optional, default: *)

user name (authenticated on firewall)

group group (type: str-set, optional, default: *)

list of groups; if present, both NAME and GROUP must match

This repeatable item can be used in two forms selected by the first element. The former one consists of the branching element (none) only. The latter one may have the branching element value (name) specified, or omitted, and many variations of the other elements are valid.

The following forms are all equivalent and only explicitely confirm the default values:

  user name * group *;
  user name *;
  user name;
  user *;
  user;

Two examples of defining user-list of two members:

  user { user1, user2 } group *;
  user name { user1, user2 };

Two examples of defining both lists as single-member ones:

  user name { user1 } group grp1;
  user user1 group { grp1 };

An incorrect example (group-list cannot be specified without user-list):

  user group *;

An incorrect example (the word none cannot be used as a username):

  user none group none;

Possible corrections of the previous mistake:

  user "none" group none;
  user { none } group none;

See Also

Kernun: ftp-proxy.cfg(5), log(5), host-matching(7)

FreeBSD: getservbyname(3), services(5)

Authors

This man page is a part of Kernun Firewall.
Copyright © 2000–2021 Trusted Network Solutions, a. s.
All rights reserved.