Chapter 4. Configuration Basics

The configuration has a tree structure consisting of sections, items, and elements. A section is a named group of logically connected configuration directives. It can contain other (sub)sections and items. An item is a named group of values—elements. The configuration structure is reflected by the view of the configuration in the GUI, see Figure 4.1, “Tree structure of the configuration”, as well as in the corresponding textual configuration file:

## Configuration of a single Kernun UTM system 
system fw { 
  ## Host name without domain
  hostname fw; 
  ## Domain name
  domain pha.tns.cz;

  ## The default crontab defines typically used periodic actions
  crontab {
    $DEFAULT-CRONTAB;
  }

  ## The network interface connected to the internal network
  interface INT { 
    dev em0;
    ipv4 [192.168.10.1/24]; 
  }

Figure 4.1. Tree structure of the configuration

In the sample configuration there is a section of type system named fw . It contains several subsections and items. For example, an item hostname with an element (value) fw , or a subsection interface named INT containing an item ipv4 . Note that it is possible to include comments in the configuration file. They are also displayed by the GUI .

Nodes of the configuration tree are referenced by paths. A path lists the ancestor sections in the tree. In the above example, the fw.INT.ipv4 path denotes the item . Instead of specifying a value for an element, it is possible to use a reference to another value in the configuration with the same type. For example, the initial configuration contains

system fw {
  ...
  ssh-server SSHD {
    listen-sock ^system.INT.ipv4.host  : 22;
    ...
  }
  ...
}

Here, denotes the value obtained by going up the tree to the system type node (section system fw), and then down to the node named INT (it is interface INT), then to ipv4, and finally we take its host element (value).

References ensure the consistency if the same value appears at two or more places in the configuration. If the same path is to be repeated several times, e.g., in listen-on of several proxies, we may avoid the use of the full path by using a variable.

system fw {
  interface INT {
    dev em0;
    ipv4 [192.168.10.1/24];
  }
  set INT_IP = ^system.INT.ipv4.host; 
  ...
  ## SSH daemon for remote administrator access from the internal network

  ssh-server SSHD {
    listen-sock $INT_IP  : 22;
    passwd-auth;
  }

The previous example is changed so that the reference path is stored in a variable called INT_IP  and the variable is used instead the full path later . For the GUI view of the same configuration, see Figure 4.2, “Tree structure of the configuration”. In addition to these data variables it is possible to define variables containing several configuration items or even whole sections. These section variables can be parametrized. A simple example of section variables will be shown in the next paragraph, along with file includes.

Figure 4.2. Tree structure of the configuration

A configuration file can include another file. After the installation there are several include files in /usr/local/kernun/conf/samples/include. The initial configuration includes two of them, root-servers.cml (a list of root DNS servers) and crontab.cml (the default configuration of the cron (8) daemon that runs periodic actions in the system, e.g., log rotation). Example: the crontab.cml include file contains

set DEFAULT-CRONTAB system.crontab {
  ...
}
set DEFAULT-PERIODIC system.periodic-conf {

    set-env daily_clean_hoststat_enable "NO";
    set-env daily_status_disks_df_flags " -i";
    set-env daily_status_mail_rejects_enable "NO";
    set-env daily_status_include_submit_mailq "NO";
    set-env daily_submit_queuerun "NO";
}

It is included in the main configuration file kernun.cml

include "samples/include/crontab.cml";
...
system fw {
  ...
  crontab {
    $DEFAULT-CRONTAB;
  }

The same excerpt of the configuration viewed in the GUI is shown in Figure 4.3, “Including configuration files and using section variables”. The crontab.cml file is included at . It defines the variables DEFAULT-CRONTAB and DEFAULT-PERIODIC. The first variable is used at . Note that the GUI displays the contents of included files.

Figure 4.3. Including configuration files and using section variables

Configuration elements are of various types. All the types and their exact syntax are described in configuration(7). Here we only list the types and present the most important syntax rules.

We have introduced only the basic concepts of the Kernun UTM configuration language. The complete definition of the language syntax can be found in reference pages configuration(7) and cml(8). The semantics of the configuration is defined by the meaning of individual sections, items, and elements. Semantic rules also define the subsections and items each section may contain. There are constraints, e.g. that the existence of a configuration node requires or forbids the existence of another node. The set of possible values of a configuration element can be limited. A section or item can be repeatable (can occur several times, in the case of sections with different names), or non-repeatable (cannot occur more than once; non-repeatable sections do not have names). For example, in Figure 4.1, “Tree structure of the configuration”, the named sections system and interface are repeatable, whereas the section crontab is non-repeatable. The semantics of the configuration is described comprehensively in section 5 of the reference pages (in the appendix of this handbook or in manual pages displayed using the man(1)) command.