configuration — general syntax of configuration files
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
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.
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
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.
The basic term of configuration description is an atom. There are the following atom types in Kernun configuration:
A positive integer value in decimal or hexadecimal
(C-style: 0x)
form; the decimal ones can have 'hexK',
'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.
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.
A sequence of letters, digits, underscores
('_') and hyphens ('-')
(e.g. ftp-data,
kerberos_master); words are case-insensitive.
A string of characters enclosed in double quotes.
C-style escapes ('\t',
'\r', '\n',
'\"', '\\' and
'\x)
must be used to code special characters.
If a string is a concatenation of words,
dots ('hex.') and
at-signs ('@') then it need not be enclosed in
quotes (e.g. root@tns.cz).
An IPv4 address in dotted decimal format.
It MUST be enclosed in square brackets
(e.g. [127.0.0.1]).
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.
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.).
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:
integer value (size: 8 bits).
integer value (size: 16 bits).
integer value (size: 32 bits).
integer value (size: 64 bits).
integer value
or word (recognized by
getservbyname(3), usually stored in
/etc/services file).
integer value of daytime in form hhmm.
fractional value (size: 32 bits after multiplying by 1000).
string or word value; known keywords used as simple string must be quoted.
Regular expression (see regexp).
Hostname (expressed as a string) or an IP address without mask.
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.
Network IP address. If mask is omitted, default mask according to class is assumed. Local part of address must be zero.
Hostname or IP address followed by colon
(':') and port number or name (e.g.
[127.0.0.1] : 3333,
ftp.freebsd.cz:ftp).
Exactly the keyword specified in configuration description (Section 5 manual page) of particular item can be used.
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
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;
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 }
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:
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).
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.
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:
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).
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.
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:
The element is defined to have an arbitrary keyword.
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).
The configuration of the acl library component consists of the following prototypes:
* user ... ;
...
user none;user [name]
[name [group
group]];User and group specification.
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;