Table of Contents
List of Figures
system
-level definitionsHTTPS
and SSH
SMTP
Proxy System Sections and Forward AgentSMTP
Proxy ACLsSMTP
Proxy Mail FilterSMTP
Proxy Mail Sever in the Internal
NetworkIMAP4
ProxyPOP3
Proxyreturn
block-policy
instead of return
in rulerc.conf
configurationsysctl.conf
configurationcrontab
configurationhttp-proxy
log
(the log was filtered, in order to save space).
source-address client
)
sip-proxy
configured to listen transparently on a port range 5060-5062
SIP
ProxySQL*Net
Proxysystem
http-proxy
system
http-proxy
apply-host
is used to distinguish
the local system from the remote oneCLUSTER
definitionCLUSTER
to define two nodespikemon
and virtual clustersica-auto
The documentation of Kernun UTM consists of several parts; all of them are
available in the electronic form. The complete documentation is installed
with the software in the directories
/usr/local/kernun/doc
and
/usr/local/kernun/man
, so it is always available on
any Kernun UTM system. The documentation is also contained in the
kernun-doc
directory on the installation medium and is therefore
also accessible before the installation. The Kernun UTM documentation is available in
the following formats:
Only several short documents that should be read before the installation of Kernun UTM are available as plain text files:
KERNUN-CHANGES.txt
List of changes between individual versions of Kernun UTM.
KERNUN-INSTALL.txt
Short installation instructions. This file basically refers to Chapter 2, Kernun UTM System Management in the Kernun UTM Handbook.
KERNUN-RELNOTES.txt
Release notes; various notices concerning the installation, configuration, and use of Kernun UTM.
The Kernun UTM Handbook, that is, this document. The PDF version of the handbook contains also the reference pages except for section 6. This format is suitable for printing and reading as a book, basically from the beginning to the end.
The Kernun UTM Handbook. The HTML version of the handbook contains also all the reference pages. It is available either as a single very long HTML file, or broken into many smaller HTML files. This format is suitable as a reference, with the possibility of hypertext navigation between its parts.
The reference part of the documentation is available also in the form of the standard manual pages that can be viewed using the man(1) command. The manual pages are categorized into sections, similarly as the system manual pages. Kernun UTM uses the following manual page sections:
User commands, mainly various tools for runtime monitoring and generation of statistics.
Configuration. Individual sections of the
/usr/local/kernun/conf/kernun.cml
configuration file are documented in this
section.
For each log message, except for the debugging ones, there is a manual page that describes the conditions, under which the message is logged, and the possible consequences of its appearance in the Kernun UTM log. The manual pages' names are the IDs of the corresponding messages.
The manual pages in this section explain general concepts. They cover features that are common to many parts of Kernun UTM, such as proxies.
Administrative commands, including application proxies and configuration management tools.
If you are looking for the description of a Kernun UTM feature, you can find its explanation in Section 8 (if it is a separate program), or in Section 7 (if it is a part of a program). If the feature is configurable, its configuration is defined in detail in Section 5. The corresponding manual pages in Section 5 and Section 7 or 8 often have the same name; they are distinguished only by the section number.
This Handbook will help you learn how to administer Kernun UTM. An overview of individual products from the Kernun family is given in Chapter 1, Kernun UTM Product Overview. The first steps and the installation instructions are provided in Chapter 2, Kernun UTM System Management. For the first time, it suffices to read only the sections needed for the initial installation (Section 3, “Licensing”, Section 5.1, “Standalone Installer”, and Section 5.2, “Initial Configuration”). Reading of the remaining parts of the chapter can be postponed until you need to know more about alternative installation methods, upgrades, backups, or disk layout. If you already have a preinstalled and licensed instance of Kernun UTM, you can skip Chapter 2, Kernun UTM System Management altogether. Chapter 3, User Interface contains an introduction to the graphical and command line administrative interface. Beginners will probably find the GUI (Section 1, “Graphical User Interface”) to be the easiest way of controlling Kernun UTM. If, for any reason, you cannot (or do not want to) use the graphical interface, you find the information about the command line tools in Section 2, “Command Line Interface” and Section 3, “Administrative Utilities”. If you know how to connect to a running Kernun UTM system, monitor and control its operation, view logs, and edit the configuration, you may learn principles of the Kernun UTM configuration and find an explanation of the initial configuration generated during the installation in Chapter 4, Configuration Basics. Chapter 5, Advanced features deals with configuration of advanced features . At any time, details about features, commands, configuration syntax and semantics, as well as the meaning of log messages can be found in the reference pages, which are contained in the Appendix of this Handbook and available also in the form of manual pages.
Table of Contents
The Kernun family consists of several products that are each useful for a specific set of network security tasks. We will provide a brief introduction to each of them now.
Kernun UTM is a new type of a UTM secure device that contains multiple features, such as firewall, antivirus, antispam, antispyware, content filtering, intrusion detection (IDS or IPS), routing, QoS or VPN, in a single package. It has been designed to protect private data networks and DMZ segments (demilitarized zones, including servers with public services, for example WWW, FTP, mail servers, secure remote VPN connection, etc.). It provides antivirus and antispam protection, as well as an ability to block unsuitable protocols (Skype, ICQ, etc.) and unsuitable Web pages.
Kernun UTM is highly flexible during the process of secure policy implementation. This includes simple rules of status inspection, as well as sophisticated management on the level of application protocols. Thanks to its ability to inspect the contents of each application protocol, this technology is the ideal solution for environments with high security demands.
A typical implementation of the Kernun UTM technology is located on the perimeter of the protected network as a gateway between the Internet and the internal network. All connections to and from the Internet are authorized or prohibited at a central location. Kernun UTM also serves as an antivirus and antispam gateway, and as a server, where VPN connections for clients who work from home or while travelling and of VPN tunnels between branches are terminated. Public service network servers (DMZ) are usually located on another network interface.
Kernun Clear Web is a web filter. It controls access of users to the WWW according to a configured policy. The main functions of Kernun Clear Web are: web server categorization, user authentication, definition of web access policy, antivirus protection, traffic monitoring, statistical reports, and web-based graphical user interface.
The interface for administration of Kernun Clear Web is completely different from that of Kernun UTM and it is not covered by this Handbook. For more information about use and management of a Kernun Clear Web system, see its own documentation.
Table of Contents
In this chapter, we explain how to create and manage a Kernun UTM installation. The system management tasks include installation, upgrade, system backup and restore. An auditing tool can be used to receive notification of discovered bugs and available new software updates. We also provide information about the use of license files and installation of up to three independent Kernun UTM versions on a single computer.
Kernun UTM uses (slightly modified) FreeBSD as its underlying operating system. Although experience with FreeBSD or another operating system based on Unix would certainly be beneficial when performing advanced administrative tasks, it is not required. Kernun UTM provides its own set of powerful tools for installation, configuration, and monitoring of operation.
Each Kernun UTM release is distributed using the following types of distribution media:
A bootable disk image, which contains the installation tools and the full installation image.
An installable image of the Kernun UTM system partition. It can be installed either using the installer booted from the installation medium, or from a running Kernun UTM system using the Kernun GUI or the sysmgr(8) command line tool. Each full image is uniquely identified by its build number.
A patch image contains only the differences between two versions of Kernun UTM, and is therefore much smaller than the full image. Patch images are usually created for maintenance updates. Their sole purpose is to optimize the amount of data that needs to be downloaded in order to update a Kernun UTM installation to the current version. The result of installation is the same, no matter whether the full image or a patch image is used; the only difference is in the size of the image. A patch image is identified by its build number and by the build number of its base image.
Kernun UTM releases are identified by version and build numbers.
The version number denotes the source code version of the
Kernun UTM software (the operating system, application proxies, administrative
tools, preinstalled third-party software packages, etc.). The format of
the version number is either 3.0
for releases
(containing new features), or 3.0.1
for patch
releases (containing bug corrections and minor improvements).
Some bug fixes are implemented using the fast development cycle and are
distributed as hotfix releases, numbered e.g.
3.0.1-h3
.
The build number identifies the particular build,
i.e., a binary image that comprises the core Kernun UTM software, the operating
system, and third-party software, such as antivirus scanners, system
monitoring tools, or administrative utilities. A build number contains the
version number (formatted without the dots and with a fixed number of digits),
the date and time when the image was created, and the hardware architecture.
Examples: 030000h00.200809241501.i386
or
030001h00.200810170823.amd64
.
Kernun UTM is able to use one or two disk devices. Each disk device is either a physical disk, or a logical disk provided by a hardware RAID. The disk space is divided into three system partitions, one data partition, and swap space. In single disk configurations, all four partitions and the swap space are located on the single disk. In configuration with two disks, the system partitions are on one disk, whereas the data partition and the swap space on the other.
Each system partition may contain a complete Kernun UTM installation including the operating system, application proxies, administrative tools, and additional software. The data partition contains logs, statistics, installation images, and backups. The contents of the data partition are shared by all Kernun UTM installations in the system partitions.
The use of three system partitions minimizes downtimes during reinstallations and upgrades. While the system started from one system partition is fully operational, it is possible to install another version in the second partition. Then the new version can be started by a simple reboot. It is always possible to revert to the old version if anything goes wrong with the new one. The next upgrade will be installed in the first partition while running the system from the second one. In this way, two system partitions can be alternated for subsequent upgrades. The third system partition can be used in a similar fashion, so that two previous versions are always available, or for an alternative installation, e.g. when testing a completely new configuration.
When a system partition is booted, it becomes the root file system.
The other system partitions can be mounted to the directories
/1
, /2
, and
/3
. There are lines in /etc/fstab
prepared for this, but the partitions are not mounted automatically.
The data partition is always mounted as /data
automatically. It contains the following directories:
/data/backup
System backups are stored here. They can be used for restoration or copied to another medium.
/data/dist
This is where Kernun UTM installation images are kept. During each installation, the installed image is stored here for future reuse.
/data/log
This directory contains log files. The log directory
/var/log
from all system partitions is symlinked
here.
/data/rrd
This directory contains database files used to store system data for system performance monitoring, as well as graphs generated from this data.
/data/statistics
Reports with detailed statistics of proxy operation are stored in this directory.
The standard disk space layout is created during the first installation of Kernun UTM on a new computer. It can be re-created or modified using the installer booted from the installation medium, but such action deletes all data on the system and data disks.
It is strongly recommended not to modify the standard disk layout, as many parts of Kernun UTM depend on it. You may add additional file systems and directories, but do not delete or move any file system or directory created by the Kernun UTM installer.
Kernun UTM requires a valid license file to operate properly. Without a license file, the software can be installed, the operating system runs allowing both local and remote administrator access, but no licensed component may be started. The licensed components include all application-level network proxies and some additional modules (for example, antivirus, antispam, and Web filter).
The license file is a cryptographically signed text file. It contains the following information:
The customer identification
An optional identifier used to distinguish different licenses of the same customer
A unique serial number
The license size (the permitted number of protected network devices)
A computer identifier, if the license is valid exclusively with particular hardware.
The expiration date, if the license is valid for a limited time.
(Only Kernun 3.3 and newer) The expiration date of upgrade subscription. Before this date, new features (components) added to Kernun will be automatically licensed if covered by the subscription. After this date, existing features will continue to work (until the optional license expiration date), but new features will not be licensed.
(Only Kernun 3.2 and older) The release version number, if the license is valid for a single Kernun release (e.g., 3.1) only. The license can be used on all patch releases and hotfixes of the licensed release (e.g, 3.1.2 or 3.1.1-h5), but not on other releases (e.g., 3.2).
The list of licensed components.
(Only Kernun 3.3 and newer) The list of licensed groups of components. Licenses are usually issued for groups of components. For example, there are groups corresponding to various Kernun products, such as Kernun Net Access or Kernun Kernun Mail Access. The use of component groups makes it possible to add new licensed components to users with active subscription without the need for a new license file.
(Only Kernun 3.3 and newer) Various parameters of the licensed components.
A cryptographic signature used to verify the integrity of the license.
License files from Kernun 3.0 are not valid for 3.1 and newer releases.
Licenses from Kernun 3.1 and 3.2 are recognized by Kernun 3.3 and newer.
The license file must be installed as
/usr/local/kernun/license.dat
. The license file is
stored in the system partition and must therefore be reinstalled after
each installation or upgrade. The license file can be copied to
Kernun UTM either from the command line using SCP, or at the
License tab of the GUI System
Manager.
The set of configurable components changes depending on the type
of the Kernun product and the set of licensed components. For example,
if the HTTP proxy is not licensed, it should not be configured. A
single configuration file may comprise configurations of many Kernun
systems with different products. In each configuration section related
to a single system (section system
), the product can
and should be specified using the product
item. The
product specification consists of the Kernun software type, the list of
licensed components, the list of licensed component groups, and the
upgrade subscription expiration value. The product specification should be
filled according to the contents of the license file present in the
configured system. When the configuration is verified,
a check is made that only components usable in the selected products
are configured. When the configuration is applied, it is checked that
the product specified in the configuration complies with the product
installed in the target Kernun system. At the time of writing of this
text, there are two product types available:
kernun
— all Kernun products;
unspecified
— the product type is not
specified and will not be checked when applying the
configuration.
The recognized names of licensed components and component groups are the same as in the license files. Components:
product-kernun, product-kernun-net-access,
product-kernun-mail-access, product-kernun-vpn-access,
product-kernun-office-access, product-kernun-web-access,
product-kernun-secure-box,
product-kernun-secure-box-retail
— Kernun product
names;
dns-proxy, ftp-proxy, gk-proxy, h323-proxy, http-proxy,
imap4-proxy, pop3-proxy, sip-proxy, smtp-proxy, sqlnet-proxy,
tcp-proxy, udp-proxy
— individual proxies;
icap-server
— server for the ICAP
protocol;
mod-antivirus
— module for communication
with an antivirus in proxies;
mod-antispam
— module for spam checking
in mail proxies;
mod-pwf
— module for communication with
an external Web filter in the HTTP proxy;
http-cookie
— support for special handling
of security-related HTTP cookies, for example, various session ID
cookies;
mod-match, mod-match-replace
— module for
matching and replacement of HTML form data.
Component groups:
kernun-net-access, kernun-mail-access, kernun-vpn-access,
kernun-office-access, kernun-web-access, kernun-secure-box,
kernun-secure-box-retail
— individual Kernun products;
modules-data-scanning
— modules for
security scanning of data, such as the antivirus module;
modules-secure-box
— special modules for
the Kernun Secure Box products;
modules-web-filter
— modules providing
URL-based categorization and filtration of WWW servers.
When the initial configuration file is created (see Section 5.2, “Initial Configuration”),
the product type is detected, the currently installed license file is
examined, and the system.product
item is set
appropriately. Therefore, it is recommended to install the license
file during the installation of the system,
before the initial configuration script is executed. The license file
can be installed by the standalone installer, as described in Section 5.1, “Standalone Installer”. If the license file is not installed during
the generation of the initial configuration or if a new system is being
added to an already existing configuration, the product
item must be set manually.
If you set the product
item manually, select the
correct product type and enter the list of licensed components, the list
of licensed component groups, and the upgrade subscription expiration date
according to your license file[1]. It is
also possible to include the samples/include/products.cml
file in the main
configuration file. This file contains definitions of variables
that can be used instead of the system.product
item.
Some products may have optional components. Their respective
variables in samples/include/products.cml
have
a parameter containing the list of licensed optional components. For
example, Kernun Net Access with the optional antivirus and antispam modules will be
specified as:
$PRODUCT-KERNUN-NET-ACCESS { mod-antivirus, mod-antispam };
Even if no optional components are licensed, the empty list must be written explicitly as the variable's parameter:
$PRODUCT-KERNUN-NET-ACCESS { };
Variables for products without optional components do not have a parameter and are therefore written without the braces:
$PRODUCT-KERNUN-MAIL-ACCESS;
The Kernun UTM boot manager is located on the system disk. It is installed during the initialization of the system performed by the standalone installer. Depending on the partitioning scheme, there is either ZFS or LEGACY (UFS) boot manager.
The Kernun GUI or the command line bootmgr(8) utility can be used to change partition labels, enable and disable booting from individual partitions, and set whether the default boot partition is fixed, or is always changed to the last booted partition.
There is a default partition selected for boot, which boots
automatically. It is also possible to select another partition during the
boot sequence. The boot manager displays the menu as shown in Figure 2.1, “ZFS boot manager screen 1”. Press option 7
to select the
boot partition. Another menu is displayed (see Figure 2.2, “ZFS boot manager screen 1”).
In this menu, press the number that corresponds to the system to be booted. For
example, press option 5<Enter>
to boot the Kernun 3.10.6.h3.
The boot manager displays labels of up to three system
partitions and allows selection of the partition to boot from by pressing
F1
, F2
, or
F3
.
F1 Kernun 3.0 2008/10/01 07:36 (030000h00.200809241501.i386) F2 Kernun 3.0 2008/10/18 05:21 (030000h00.200810170852.i386) F3 Kernun 3.0.1 2008/11/15 07:22 (030001h00.200811142135.i386) Default: F2
If no option is selected, the default one is chosen automatically after a timeout.
Anybody with physical access to the Kernun UTM console may select a system partition to boot from, boot a different kernel or kernel modules, or boot to the single user mode and access the system without a password. If the system console is not physically secure, the following actions can be done to protect the system against unauthorized access:
Disable boot device selection in the BIOS (for example, by setting a BIOS password).
Enable only the desired system partition in the boot manager (using bootmgr(8)).
Add line “-n
” to
/boot.config
. This prevents interrupting the
boot process in the stages one and two.
#
printf -- '-n\n' > /boot.config
Protect the loader with a password by adding a password line to
/boot/loader.conf
. Make the file readable only
by root.
#
echo 'password="
SECRET
"' >> /boot/loader.conf#
chmod go-rw /boot/loader.conf
Force verification of the root password as a condition for
entering the single user mode. Locate the line beginning with
“console
” in
/etc/ttys
and change its last word to
“insecure”
.
Kernun UTM can be installed using either the standalone installer booted from the installation medium, or command line or GUI system management tools. The first installation on a new computer must be done using the standalone installer, which does not require an already installed Kernun UTM with initialized system and data disks and is able to initialize the standard disk layout, as described in Section 2, “Disk Space Layout”. Once there is at least one working Kernun UTM instance on the computer, further installations can by done from it using either the GUI, or the sysmgr command line tool. The standalone installer is able to install in any system partition. The GUI and command line installations cannot be performed in the system partition that contains the currently running Kernun UTM instance.
Regardless of the installation method, the newly installed system partition is, by default, enabled in the boot manager and made the default selection for the next boot. The boot manager can be reconfigured using the GUI or the command line utility bootmgr(8).
The standalone installer is normally used only for the first installation on a new computer, after replacing a disk, or if disk repartitioning is needed. In other situations, installation using the GUI (Section 5.3, “Installation from the GUI”) or the command line (Section 5.4, “Installation from the Command Line”) is more comfortable.
Since version 3.11.7-h3, the installer boots using only UEFI (with disabled Secure Boot), while previous versions used only legacy BIOS. If your hardware does not support UEFI, consider installing an older version and upgrading it to the latest version.
To start the standalone installer, you need the Kernun UTM installation medium[2]. Boot from the USB flash drive and following the boot loader and kernel messages, you will see the installer menu.
*** KERNUN INSTALLATION *** Build 030000h00.200809241501.i386 1. Install Kernun 2. Check for existing Kernun installations 3. Restore backup 4. Start rescue shell 5. Mount Kernun file systems 6. Resize installer's in-memory temporary file system (current size 32m) 7. Halt 8. Power down 9. Reboot 0. Install license Select action:
Press 1<Enter>
. If the disk partitioning for
Kernun UTM has already been done, the device names of the system and data disks are
displayed and the installer asks whether you want repartitioning.
Detected Kernun system disk ad0 Detected Kernun data disk ad0 Repartition disks (y/n)?
Reply n
to skip disk
partitioning. If you reply y
or if the disk
partitioning has not been done yet, the system suggests the default
installation:
Default installation parameters: System disk: ada0 (131072 MB) SSD disk: ada1 (524288 MB) Swap size: 8192 MB Install with default parameters? (y/n)
Reply y<Enter>
to finish the
installation with default parameters. If you reply n
,
the installation parameters are asked. Select the system disk and partitioning
schema:
Detected disk devices: ada0 131072 MB ada1 524288 MB media RPM non-rotating Kernun system disk(ada0 ada1) [ada0]:<Enter>
Use ZFS (y/n)y<Enter>
Always select a disk that the BIOS (or UEFI) will be able to boot from as the system disk[3]. If there is only one disk device, the selection of devices will be skipped and the single device will be used. The ZFS partitioning schema is prefered over the legacy (UFS) schema. Note that ZFS boots using UEFI while UFS boots using legacy BIOS.
When the installer asks a question, it offers a default value
in brackets. Press <Enter>
to
select the default value.
The installer then asks for the swap size. Reasonable default value is provided. It can be changed if the default value does not meet the expectations.
System disk size is 131072 MB Memory size is 4096 MB Swap partition size in MB [8192]:<Enter>
Disk ada0 [131072 MB] will contain 3 GPT partitions: ada0p1 with freebsd-boot ada0p2 with freebsd-swap [8192 MB] ada0p3 with freebsd-zfs Use these values (y/n)?y<Enter>
Disk partitioning will delete contents of selected disks, continue (y/n)?y
If you want to cancel the installation process, answer
n
to the last question. It will return to the
main menu without changing the disk contents.
Answering y
to the ``continue'' question will
initialize the selected system and data disks with the standard disk
layout for Kernun UTM. Any existing contents of the disks will be lost.
If there is a SSD disk, it is offered to be used. Select
the device name to use the SSD disk, or select NO
not to use it.
Detected disk devices:
ada1 524288 MB
media RPM non-rotating
Create SSD disk (NO ada1) [NO]: ada1<Enter>
Creating KBI disk on ada1
Messages concerning creation of disk partitions and file systems will then be displayed, followed by:
Current Kernun installations: Boot manager on ZFS pool 'kernun' F1: Unused F2: Unused F3: Unused type=Kernun ZFS boot manager ver. 1.0 current_booted=NONE bootable= update=1 default_selection=NONE Select partition for installation (1 2 3) [1]:<Enter>
Overwrite partition /dev/ad0s1 by new Kernun installation (y/n)?y
These lines show the configuration of the Kernun UTM boot manager, see
bootmgr(8). The first installation will be
usually performed in the first system partition, so just press
<Enter>
. Finally, you are asked to
confirm whether you want to overwrite the selected system
partition.
The installer creates any missing
standard directories in the data partition, creates a new empty file
system in the selected system partition, and displays a list of the
installation images (identified by build numbers) available on the medium
and in the /data/dist
directory. If there is more
than one image, one can be selected, with the
newest image as the default. If the image from the medium is selected, it
is first copied to /data/dist
. The selected image
is then unpacked to the system partition. The
/etc/fstab
file in the newly installed partition
is adjusted according to the system partition number. The build number
of the installed Kernun UTM is stored in the
/kernun-version
file in the system partition. The
content of the newly installed Kernun UTM instance is stored in
/kernun-installed.fsdb.bz2
. This file is used by
the backup tools in order to decide which files have changed since the
installation and therefore need to be backed up. After the installation
is finished, the installer waits for
<Enter>
and then returns to the
main menu.
... Available installation images: 1 030000h00.200809241501.i386 Copying installation image to /data/dist Clearing system partition 1 ... Installing kernun-030000h00.200809241501.i386.txz to system partition 1 Unpacking image Removing file system content databases for installed images Creating /etc/fstab Writing build number into /kernun-version Creating file system content database Installation successfully finished Press Enter for return to menu...
Optionally, if you have a license file for your newly installed
system available, you can install it now. This ensures that the initial
configuration script will set the system.product
configuration item correctly after reboot. It will also ask whether the
licensed proxies should be enabled in the initial configuration. The
license installation is done in several steps:
Prepare a USB disk with a UFS or FAT file system.
Copy the license file license.dat
to the
root directory of the USB disk. Alternatively, if you have some other
license files (for example, for the antivirus engine), you can pack
them all[4] in
the license.tar
file in the
tar format with all paths relative to the Kernun
system root directory.
Do not connect the USB disk yet and select
0
from the installer main menu.
When prompted, connect the USB disk. The license files present will be installed.
Select 9
from the main menu to have the
newly installed Kernun UTM booted. You can then perform its initial
configuration, as described in the following section.
The /data/dist
directory may contain full and
patch installation images. A full image can be always installed. A patch
image contains only the differences from a base image. Hence the base image
must be available in order to install the patch image. The base image may
itself be a patch image, and its base image is then required as well. Generally,
each patch image requires a continuous sequence of base images starting
with a full image followed by zero or more patch images.
When a newly installed Kernun UTM system is booted for the first time, an
interactive initial configuration script
(/etc/rc/kernun-config
) is executed early in
the boot process[5].
It prompts the administrator for various basic system
parameters, creates and applies the Kernun UTM configuration file, and
finishes the boot procedure with the new configuration. The initial
configuration can be modified later using the standard Kernun GUI or
command line configuration tools.
First, the time zone needs to be set. We recommend to use UTC for
the CMOS clock—select Yes
by pressing
<Tab><Enter>
in
the first dialog.
Even if the CMOS clock is currently set to the local time, it is
better to select UTC here and adjust the time later using the
date(1) command or by configuring NTP,
see section ntp
in
system(5). After selecting the CMOS clock
mode, the time zone menu is displayed. Choose the time zone suitable for
your location. Then set the administrator password
(user root
).
After that, a new SSH host key is generated. It is used to authenticate the system to a remote access client[6] (GUI or command line SSH). You should write down the reported key fingerprint and compare it with the fingerprint reported by SSH or the GUI when making the first remote connection to the system. The SSH host keys should be the same for all Kernun UTM installations on the same computer. Therefore, if an SSH host key exists during the installation, it is copied to the newly installed system partition and the generation of a new key is skipped during the initial configuration. The GUI and command line installers look for an SSH host key in the current system partition. The standalone installer takes an SSH host key from the first system partition that contains one and is different from the partition, in which the installation is taking place.
Answer n
to the following question (or
just press <Enter>
) if you
want to input the basic configuration parameters and generate the
initial Kernun UTM configuration file.
**********************************************************************
Fingerprint of the SSH host DSA key. Compare this value with the value
reported by SSH client or Kernun GUI when connecting in order to check
that you are connecting to this system.
1024 71:0a:ec:8d:dd:9e:e7:2d:2b:91:79:0e:1a:ca:89:2b
/etc/ssh/ssh_host_dsa_key.pub
**********************************************************************
*** KERNUN INITIAL SYSTEM CONFIGURATION ***
Skip Kernun configuration (y/n)? [n] <Enter>
Two network interfaces are configured in the default configuration: internal, intended to be connected to the protected network, and external, which is typically connected to the Internet. The configuration script asks for the names, IP addresses, and network masks of these interfaces. Then, the DNS server and default router addresses need to be specified. The initial configuration will allow the administrator SSH access from the internal network (using the GUI or a command line SSH client). If you want to allow some application protocols to pass from clients in the internal network to servers in the external network, you can enable the respective proxies. The configuration of the proxies will contain the default values of various parameters, which will be sufficient for the simplest use. More complicated configuration requirements can be implemented later by editing the generated initial configuration file using the GUI or command line configuration tools (modifying proxy configuration, adding new proxies, etc.). An example of the initial configuration setup is given and explained below.
In many environments, an initial configuration with enabled proxies may violate a security policy. Therefore, it is recommended not to enable any proxy in the initial configuration unless you are sure that you really need it.
Hostname without domain []:fw
Domain []:![]()
example.com
Show only Ethernet interfaces (y/n)? [y]By repeating the following test with connected and disconnected network cables, you can determine interface names of physical network cards. *** Media state of network interfaces *** ed0: media: Ethernet autoselect (100baseTX <full-duplex>) ed1: media: Ethernet autoselect (100baseTX <full-duplex>) Show again (y/n)? [y] *** Media state of network interfaces *** ed0: media: Ethernet autoselect (none)
ed1: media: Ethernet autoselect (100baseTX <full-duplex>) Show again (y/n)? [y] *** Media state of network interfaces *** ed0: media: Ethernet autoselect (100baseTX <full-duplex>) ed1: media: Ethernet autoselect (100baseTX <full-duplex>) Show again (y/n)? [y]
n
Internal interface name (ed0 ed1) []:ed0
Internal IP address []:![]()
192.168.10.1
Internal interface netmask [24]: External interface name (ed0 ed1) []:ed1
External IP address []:![]()
192.168.11.2
External interface netmask [24]: DNS server IP address []:10.1.1.1
Default router IP address []:![]()
192.168.1.1
Postmaster e-mail [postmaster@example.com]:![]()
Enable some proxies (y/n)?
y
Enable DNS proxy (y/n)? [n]![]()
y
Enable FTP proxy (y/n)? [n] Enable HTTP proxy (y/n)? [n] Enable HTTPS proxy (y/n)? [n] Enable POP3 proxy (y/n)? [n] Enable IMAP4 proxy (y/n)? [n] Enable SMTP proxy (y/n)? [n] Enable SSH proxy (y/n)? [n]y
Hostname: fwDomain: example.com Internal interface: ed0 Internal IP: 192.168.10.1 Internal netmask: 24 External interface: ed1 External IP: 192.168.11.2 External netmask: 24 Name server: 10.1.1.1 Default router: 192.168.11.1 Postmaster e-mail: postmaster@example.com Enabled proxies: DNS SSH Use these values (y/n)?
y
![]()
The configuration begins with
setting the host name and the domain name. Then, the internal and external
interfaces are selected. First, the available network interfaces are listed.
You can choose
whether you want to show all
interfaces, or just Ethernet interfaces. The interfaces are repeatedly
listed with their media states. This can be useful if you are not
sure about the names of physical interfaces. You can unplug network cables
one by one and observe, which interface changes its state. In the example
, the cable was unplugged from the network
interface
ed0
. The internal and external
interface
names, IP addresses, and network masks are defined. The DNS server IP
address
is used by Kernun UTM for domain name
resolution. The default router
is typically
a router in the external network. The postmaster e-mail address
is used by the SMTP proxy to forward mail sent
to the postmaster.
You can also enable some proxies for
access from the internal to the external network. Questions about
individual proxies are asked only if you reply
y
to
the initial “enable some proxies” query. Otherwise, all proxies
are disabled without further questions. The generated initial
configuration file will contain configuration of the disabled
proxies as well, with their configuration sections marked as hidden. A proxy
can be easily enabled later by unhiding its configuration using the
GUI or the command line configuration interface. Only licensed proxies are
offered for enabling.
Finally, all values defined during the configuration setup are listed
. If you are satisfied, reply
y
and the initial
configuration file will be generated and applied. If you reply
n
, the whole configuration setup will be repeated
with the previously specified values as defaults.
After defining values for the initial configuration, the SSH key for remote administrator access is generated. You must enter a passphrase used to encrypt the key. The same passphrase is also used for the initial download of the key from Kernun UTM.
The configuration script will now generate the root's SSH key. The passphrase for the key will be also used as the password for initial key download from Kernun GUI. Enter SSH key passphrase: Repeat SSH key passphrase: Generating public/private dsa key pair. Your identification has been saved in /home/keygen/id_dsa. Your public key has been saved in /home/keygen/id_dsa.pub. The key fingerprint is: 33:27:5a:63:53:b1:ba:47:bf:e8:58:4a:d0:f6:d4:d4 root@fw.example.com
The SSH key generation is the last step in the initial configuration process. After that, the normal operation of the newly installed Kernun UTM begins.
The SSH (private) key needs to be downloaded to the administrator's
local computer and subsequently copied to any system used by the
administrator to access Kernun UTM. The administrator's computer must be
in a network routed via the Kernun UTM internal interface, e.g.,
192.168.10.0/24
in our
configuration example. There is a special user account keygen
dedicated to SSH key download. The
GUI is able to download the key automatically, you only need to select
Initialize new firewall in the Connect to
Server dialog. See also Section 1.1, “Kernun GUI Launcher” for
details. For command line SSH access, you can either use the key
downloaded by the GUI, or download the key manually:
Use SCP to copy the private OpenSSH key
(id_dsa
), the public OpenSSH key
(id_dsa.pub
), and the Putty key
(key.ppk
).
$
scp keygen@192.168.10.1:* .
keygen@192.168.10.1's password: id_dsa 100% 736 0.7KB/s 00:00 id_dsa.pub 100% 609 0.6KB/s 00:00 key.ppk 100% 807 0.8KB/s 00:00$
Log in to Kernun UTM as user
root
using the newly
obtained key.
$
ssh -i id_dsa root@192.168.10.1
Enter passphrase for key 'id_dsa': ...[root@fw ~]#
Delete the key files in the home directory of user keygen
.
[root@fw ~]#
rm ~keygen/*
Disable the keygen
account.
[root@fw ~]#
pw lock keygen
Log out from Kernun UTM.
[root@fw ~]#
logout
Connection to 192.168.10.1 closed.$
The steps after the first one are not strictly necessary, but they are
recommended for security reasons. Although the secret SSH keys are
protected by a passphrase, they should be kept in a secure store that
can be accessed only by authorized administrators. If the key is downloaded by
the GUI, the key files on Kernun UTM as well as the
keygen
account are automatically
removed when the GUI connects to Kernun UTM with the downloaded key for
the first time.
In this section, we assume that the reader has at least the
basic knowledge of the Kernun GUI. An introduction to the Kernun GUI can be
found in Section 1, “Graphical User Interface” of this manual. The installation and
its related tasks are controlled by the Kernun GUI System
Manager, which is accessible using the
button in
the main window toolbar, as shown in Figure 2.3, “The System Manager icon in the toolbar”.
The installation is done from the Installation
images tab in the System Manager window, see Figure 2.4, “Installation images in the System Manager”. It displays a list of available
installation images (stored on Kernun UTM in
/kernun/dist
). An image is marked as
installable if it is either a full image, or a patch image with an
available base image. The version number, build date, and build
number are listed for each image. Installation images can be copied
from the administrator's local machine, where the GUI runs, to
Kernun UTM by clicking the button.
The button can be used to copy
in the opposite direction. It is also possible to
delete a selected image ( ) or all
images older than the selected one[7] ( ).
Each installed image is is copied to
/data/dist
. As the images may consume a lot of
disk space on a regularly updated Kernun UTM, it is recommended to
delete old images regularly or when you need more space on the data
disk. An easy way to do this is to select one of the newest images
and click .
It is usually sufficient to retain only the one or two most recent
images.
To initiate the installation of the selected image, click the Quick Wizards page. A wizard window (see Figure 2.5, “Selection of the installation target”) appears and prompts you to select the target system partition. It displays the number and label of the system partition that contains the currently running system. This partition cannot be overwritten by the installation. One of the other two system partitions, which are also listed with their labels, needs to be chosen. If you started the wizard from the Quick Wizards page, you are then supposed to choose the desired installation image. Finally, the recapitulation of the selected values is displayed. Click the button to launch the installation process (it deletes all the existing content of the selected partition).
button. In the example, we will install the newest (last) installation image from the list. The installation of Kernun UTM can be alternatively initiated using the button on theWhen performing an installation, make sure that you have selected the correct system partition, in order to avoid inadvertently overwriting a system partition that you want to retain.
The installation process takes several minutes; it can be aborted using a button in the progress dialog displayed in the meanwhile. The newly installed system partition is made bootable, but the default boot partition is not changed. The reason is that the new Kernun UTM instance is not configured and until its initial configuration is performed from the console, it will be inaccessible via the network. The boot manager configuration after the finished installation can be viewed in the System Manager's Kernun systems tab, as shown in Figure 2.6, “The system partitions after the installation”. It is possible to change the partition label (using the button) or make the new system partition the default boot partition (the button).
If the installation process terminates because of an error, the output of the failed command is displayed. The example in Figure 2.7, “An error during the installation” shows an error message caused by a corrupted installation image file.
The command line installation functionality is provided by
the
sysmgr(8) and
bootmgr(8) utilities. An installation
image that is to be installed must be stored in the
/data/dist
directory, along with the
corresponding base image(s), if it is a patch image. The existing
images can be listed using the following command:
[root@fw ~]#
sysmgr images
* 030000h00.200809241501.i386 030000h00.200810170852.i386* 030001h00.200811142135.i386
The installable images are marked with an asterisk. The image
is a patch image that cannot be installed,
because its base image is missing. Information about the currently installed
instances of Kernun UTM can be obtained using the
bootmgr command or from the
/kernun-version
file. In order to get access to this
file in other system partitions, the file systems in those partitions
need to be mounted first.
[root@fw ~]#
bootmgr
Boot manager on /dev/ad0 F1: Kernun 3.0 2008/10/01 07:36 (030000h00.200809241501.i386)F2: Unused F3: Unused type=Kernun 1024 B boot manager (74 character labels) current_booted=1
bootable=1 update=yes default_selection=F1
[root@fw ~]#
cat /kernun-version
030000h00.200809241501.i386[root@fw ~]#
mount /2
[root@fw ~]#
cat /2/kernun-version
030000h00.200810170852.i386![]()
[root@fw ~]#
mount /3
mount: /dev/ad0s3a on /3: incorrect super block
The bootmgr command displays labels of the
system partitions and the number
of the system partition that contains the currently running system
. The second system partition in
the example contains another Kernun UTM version
, even though it was manually relabeled as
“Unused”. The third system partition is really unused;
it does not even contain a file system
.
We will install a new Kernun UTM version in the second system partition. We choose the newest version available according to the sysmgr images report. Unlike the standalone installer described in Section 5.1, “Standalone Installer”, the command line installer asks no questions. The image build number and the target system partition number are given on the command line and the installation starts immediately. The standard partition label, containing the Kernun UTM version, date of installation, and build number, is set for the newly installed partition. The initial configuration process (see Section 5.2, “Initial Configuration”) is started after booting from the newly installed system partition.
[root@fw ~]#
sysmgr install 2 030001h00.200811142135.i386
Clearing system partition 2 ... Installing kernun-030001h00.200811142135.i386.txz to system partition 2 Unpacking image Installing SSH host keys Removing file system content databases for installed images Creating /etc/fstab Writing build number into /kernun-version Creating file system content database Installation successfully finished[root@fw ~]#
bootmgr
Boot manager on /dev/ad0 F1: Kernun 3.0 2008/10/01 07:36 (030000h00.200809241501.i386) F2: Kernun 3.0.1 2008/11/17 16:39 (030001h00.200811142135.i386) F3: Unused type=Kernun 1024 B boot manager (74 character labels) current_booted=1 bootable=1 2 update=yes default_selection=F2
Be careful when running sysmgr install. Especially, make sure that you specify the correct system partition number. Otherwise, you might inadvertently overwrite a system partition that you would like to retain.
The newly installed system partition is made the
default choice for the next boot. As it is not configured, it will
be inaccessible via the network after the reboot and its initial
configuration will need to be performed from the console. If you want to
keep the current default boot partition, so that you retain a fully
working system after the reboot, use the -n
parameter of the sysmgr command:
[root@fw ~]#
sysmgr install -n 2 030001h00.200811142135.i386
Typically, the interaction with Kernun UTM is performed using a VGA console. However, in some cases it is neccessary to switch the system output to a serial console, which is also available on most of Kernun devices. In order to redirect the output to a serial console, plug-in the console to a serial port, restart Kernun UTM, and follow these steps:
Press <Space> repeatedly until the booting process
prompts with boot:
When the prompt boot:
appears, type
“-h
”
and confirm by pressing <Enter>
. The output of
booting proccess should now be redirected to the serial console and
continue.
>> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loaderboot:
-h
Kernun UTM provides both GUI and command line tools used to back up
system partitions and restore data from backups created in this way.
They can be used to back up not only the current system partition, but
any of the three system partitions. A backup file does not contain
the complete contents of a system partition, but only the changes made
since its installation. The size of the backup file therefore depends
on the amount of changes that have been made in the system partition
since its last installation. After an installation, the content of a
system partition is stored in the
/kernun-installed.fsdb.bz2
file. When doing
backup, this file is compared with the current content of the system
partition. Added and modified files are stored in the backup file,
along with information about deleted files and files with changed
metadata attributes[8].
The backup and restore operations process only a subset of files
contained in a system partition, mainly Kernun configuration files.
The list of files included in a backup can be viewed and modified
in the /etc/kernun-fsdb-include
file. During
backup and restore operations, this file is passed to
diskdb(1)
using the -I
parameter.
Backup files are stored in the /data/backup
directory, from which they should be copied to a safe place.
They should not be renamed, because their names contain
important information for backup processing: the build number of
the Kernun UTM instance, the number of the backed up system partitions,
and the date and time when the backup was created.
A backup created on a particular Kernun UTM version (build number) should
be restored to a system partition containing a newly installed image with
the same build number. On the other hand, a system partition with any
partition number can be used for restoring, not only the one where the backup
was created. The restore program adjusts the contents of the file system table
/etc/fstab
accordingly.
Kernun UTM provides tools for manual backup and
restoring of system partitions using local backup files in
/data/backup
. The administrator should create a backup
at least after every major configuration change and copy it to a storage
medium other than a local disk. Solutions for automated backup, remote backup,
or backup of the data partition are not provided out of the box, because
backup policies required for different deployments vary significantly.
More sophisticated backup scenarios can be implemented using
operating system tools
(tar(1),
cron(8), etc.) or various third-party
backup software. The Kernun UTM tools support only complete restoring of
a backup to a newly installed system partition. Nevertheless, a backup file is a
tar(1) archive compressed by
bzip2(1) and can therefore be freely
manipulated using these tools.
In some situations, especially when a backup is restored to a different version of Kernun UTM or to a system partition that has been modified since the installation, conflicts may be reported during restoring. It is also possible that unresolved conflicts from an earlier restore operation interfere with the current one. In such a case, the old conflicts need to be resolved or discarded first. See Section 7, “Upgrade” for explanation of conflicts and instructions on how to resolve them.
A backup can be created in the GUI in the Kernun
systems tab of the System Manager (Figure 2.6, “The system partitions after the installation”). All you need to do is select a system partition
and click on the button. A backup file will be
created and stored in /data/backup
. The new
backup will appear in the Backups tab, see Figure 2.8, “Existing backup files in the GUI”. Using buttons under the list of backup files,
a file can be downloaded to the administrator's computer, uploaded
back to Kernun UTM, or removed.
Click on the Quick Wizards page. A wizard window appears. It prompts for the target system partition (must not be the currently booted one), for selection of a backup file and for a corresponding installation image. There are also buttons for uploading a locally stored backup or image to Kernun UTM. As the last step, the recapitulation of the selected values is displayed, as shown in Figure 2.9, “Parameters of a restore operation”. When you click , the selected image is installed in the chosen system partition and the selected backup is unpacked. Then it is possible to do any combination of the following operations: set the newly restored partition as the default boot partition; change the partition label; reboot Kernun UTM immediately (see Figure 2.10, “Final settings after restoring a backup”).
button if you want to start the restore operation. Alternatively, restoring can be initiated using on theThe
sysmgr(8) utility is used to create
and restore backups from the command line. A new backup file in
/data/backup
is created by the following command:
[root@fw ~]#
sysmgr backup 2
Creating backup content database /kernun-backup.fsdb.bz2 Creating file system content database Creating backup file /data/backup/backup-030000h00.200809241501.i386-2-200807281400.tbz[root@fw ~]#
If a backup of the current system partition is to be created, the
partition number (2
in our example) may be
omitted. A list of existing backup files is displayed by
[root@fw ~]#
sysmgr backups
backup-030000h00.200809241501.i386-1-200810031714.tbz backup-030000h00.200809241501.i386-2-200809261822.tbz backup-030000h00.200809241501.i386-2-200809301350.tbz
A backup can be restored to a selected system partition; it must not be the currently used system partition. A clean installation of an image with the correct build number should be done first.
[root@fw ~]#
sysmgr install 2 030000h00.200809241501.i386
... Installation successfully finished[root@fw ~]#
sysmgr restore 2 \
>
backup-030000h00.200809241501.i386-1-200810031714.tbz
Processing changes of file system contents Unpacking files from backup Resolving conflicts All conflicts resolved[root@fw ~]#
An attempt to restore a backup in a system partition that contains a Kernun UTM instance with a different build number is detected and a warning is displayed:
[root@fw ~]#
sysmgr restore 2 \
>
backup-030000h00.200809241501.i386-1-200810031714.tbz
Backup is from different build than currently installed in /2. Installed: 030001h00.200811142135.i386 Backup: 030000h00.200809241501.i386 It is strongly recommended to restore a backup to the Kernun build that was used for creating the backup. Continue anyway (y/n)?n
[root@fw ~]#
A backup can be restored also from the standalone
installer booted from the Kernun UTM installation medium. This can be helpful
after installing a new system disk or when moving a Kernun UTM installation
to a new computer. First, select a system partition and install Kernun UTM
from an image corresponding to the backup that is to be restored,
following the procedure described in Section 5.1, “Standalone Installer”.
If the backup file is not already located in /data/dist
,
you can copy it there using the emergency repair environment
tools, as described in Section 9, “Emergency Repair Environment”.
*** KERNUN INSTALLATION *** Build 030001h00.200811142135.i386 1. Install Kernun 2. Check for existing Kernun installations 3. Restore backup 4. Start rescue shell 5. Mount Kernun file systems 6. Resize installer's in-memory temporary file system (current size 32m) 7. Halt 8. Power down 9. Reboot 0. Install license Select action:1
Detected Kernun system disk ad0 Detected Kernun data disk ad0 Repartition disks (y/n)? n Current Kernun installations: Boot manager on /dev/ad0 F1: Kernun 3.0 2008/10/01 07:36 (030000h00.200809241501.i386) F2: Kernun 3.0.1 2008/11/17 16:39 (030001h00.200811142135.i386) F3: Unused type=Kernun 1024 B boot manager (74 character labels) current_booted= bootable=1 2 update=yes default_selection=F2 Select partition for installation (1 2 3) [1]:![]()
3
Overwrite partition /dev/ad0s3 by new Kernun installation (y/n)?![]()
y
Available installation images: 1 030000h00.200809241501.i386 2 030001h00.200811142135.i386 Select image to install (1-2) [2]:1
Enter the label that will be used to identify this installation in the boot manager. The label can be at most 44 characters long. The Kernun build number will be appended after the entered label automatically. Label [Kernun 3.0 2008/11/20 10:26]: Clearing system partition 3 ... Installing kernun-030000h00.200809241501.i386.txz to system partition 3 ... Installation successfully finished Press Enter for return to menu... *** KERNUN INSTALLATION *** Build 030001h00.200811142135.i386 1. Install Kernun 2. Check for existing Kernun installations 3. Restore backup 4. Start rescue shell 5. Mount Kernun file systems 6. Resize installer's in-memory temporary file system (current size 32m) 7. Halt 8. Power down 9. Reboot 0. Install license Select action:![]()
3
Select partition to be restored (1 2 3) [1]:![]()
3
Available backups for build installed in partition 3: 1 backup-030000h00.200809241501.i386-1-200810010405.tbz 2 backup-030000h00.200809241501.i386-1-200810040604.tbz Select backup to restore (1-2) [2]:![]()
1
Restoring backup-030000h00.200809241501.i386-1-200810010405.tbz to partition 3 Are you sure (y/n)?![]()
y
Conflicts resolution data in /data/restore already existRemove old /data/restore (y/n)?
y
Processing changes of file system contents Unpacking files from backup![]()
Resolving conflicts All conflicts resolved Press Enter for return to menu...
In the example above, we assume that the backup file is already
stored in the /data/backup
directory and the corresponding
installation image in the /data/dist
directory. We
start the backup restoring procedure by carrying out a fresh Kernun UTM
installation in an unused system
partition
. The installation image
is chosen so that it corresponds to the
backup file that will be restored. After returning to the installer
main menu, we select
. The partition
installed in the previous step should be
selected. A list of backups compatible with the content of the target
system partition is displayed. We choose one of the offered backup
files
and the restoring begins. The
message
indicates that there are
unresolved conflicts from previous restore or upgrade operations.
Usually, you should reply
n
to the question
. This will interrupt the
restore operation. You can restart it after you resolve the conflicts
according to instructions given in Section 7, “Upgrade”. If you are
sure that you do not need to resolve the old
conflicts[9], you may reply
y
and the conflict resolution data will be
deleted. The message and question concerning the old conflicts
will not be displayed if there are no pending conflicts. Finally
, the backed up files are unpacked from the backup
file and checked for conflicts. No conflicts should occur if the
backup is restored to the same Kernun UTM build that was installed at the time
the backup was created. The restored files are installed in their
proper places and the restore operation successfully finishes.
The upgrade procedure described in this section is applicable if you want to retain as much as possible from the configuration of the old Kernun UTM instance in the new instance. If you want to configure a new Kernun UTM version from scratch, follow the installation and configuration procedures described in Section 5, “Installation”.
Upgrading to a new version or build of Kernun UTM is basically done by restoring a backup of the old version in a system partition that contains a fresh installation of the new version. The upgrade procedure comprises the following steps:
The syntax and semantics of the configuration files are sometimes slightly changed between versions. In order to be usable in the new Kernun version, the old configuration file must be converted in step 1. This is done automatically during the upgrade process. The configuration conversion script expects the configuration in a normalized format. Using just some formatting accepted by normal Kernun configuration tools (GUI or CML) is not sufficient. The normalization during the upgrade process is done either automatically (by GUI), or using a command in the command line upgrade.
If you are upgrading from a Kernun version that does not implement automatic configuration normalization during the upgrade process, that is, from a version older than 3.3.2, you should perform the normalization manually. It can be done simply by opening and saving the configuration by either GUI, or CML. The normalization step may be skipped if the configuration has been saved recently and has not been modified outside the Kernun configuration tools, for example, by a text editor.
The upgrade operation results in a newly installed system partition
that contains the new version of Kernun UTM. If we want to keep the configuration
across upgrades, we need to copy the main Kernun UTM configuration file
/usr/local/kernun/conf/kernun.cml
and any other
changes done in the old installation to the new one. The configuration files
that have been changed, created, or deleted since the installation are
found and saved when the old system partition is backed up in
step 2.
Step 3 requires a full or patch installation image. Although it is possible to replace the contents of the currently used system partition with the new version, it is not recommended. You should always install an upgrade to a currently unused system partition, for two reasons. First, the old Kernun UTM instance can continue running until the upgrade is finished. Second, you can quickly return Kernun UTM to an operational state if something goes wrong with the upgrade.
The recommended practice is to use two system partitions for regular upgrades. One partition is occupied by the currently running version, while the other contains the old version and will be used for installation of the next upgrade. After each upgrade, the roles of the two partitions are switched. The third system partition can be reserved for special tasks, such as preparation of a completely new configuration.
Set the boot manager (as described in Section 4, “Boot Manager”) default boot partition so that it always boots the currently used Kernun UTM instance. Consider disabling the automatic updating of the default boot partition or disabling the unused partitions altogether.
Restoring of the backup from step 2 in the system partition installed in
step 3 effectively copies the
complete configuration from the old system partition. Restoring of a backup
to a build different from the one used for its creation may cause
conflicts. These are files that cannot be restored
automatically and a manual intervention of the administrator is necessary.
A conflict occurs if there are two incompatible changes of the same file.
The original version of the file comes from the installation image of
the Kernun UTM instance that is being upgraded; we will call it “old”. The
second version (called “backed-up”) is contained in the backup file,
if the file was changed[10] at some time between the installation of the old
version and the start of the upgrade process. The third version
of the file (called “new”) is obtained from the installation image of
the new Kernun UTM instance installed in step 3. There are two potential changes of the
file. One between the old and the backed-up version, the second between
the old and the new version. If only one change exists, no conflict occurs
and the changed (backed-up or new) version of the file will be used. For
example, /etc/ttys
may have been
changed by the administrator in the installed Kernun UTM, but remains the same in
the build we are upgrading to. Another example is a proxy executable,
which is modified in the new Kernun UTM version, but left unchanged by the
administrator. If all three versions exist, i.e. when the backed-up
and the new version differ, a conflict occurs. The automated upgrade tools
are unable to handle the file and the administrator must decide whether
the new file, the backed-up file, or some combination of the two should be
used. For example, a third party software added in the new build
creates a new user account in /etc/master.passwd
, and the
administrator has created another user account. During the upgrade, a conflict
is reported for /etc/master.passwd
. The administrator
can resolve this particular conflict by merging the two versions of the file,
adding both new user accounts to the resulting file.
The detected conflicts are recorded in the
/data/restore/resolve
file during step 4. The conflicting files from the backup
file (the “backed-up” version) are not unpacked to the
root directory tree. Instead, they are stored in corresponding locations
under the /data/restore/conflicts
directory. The root
directory tree contains the files as installed (the “new”
version). In step 5, the
administrator specifies for each file how the conflict should be resolved,
choosing from the following possibilities:
The new version is retained and the backed-up version is deleted
from /data/restore/conflicts
.
The backed-up version replaces the new version.
The new or the backed-up version is used, but is modified first, for example by merging the contents of the two versions in a text editor.
The conflict is postponed until a later iteration of conflict resolution.
The /data/restore
directory is deleted when all conflicts
are resolved. Only one upgrade procedure can be in the conflict resolution
stage at a time. If a conflict resolution session is started and there is
already the /data/restore
directory with unresolved
conflicts, the administrator can either cancel the second resolution, or
delete the old /data/restore
directory, thus effectively
using the “new” versions of the files for all conflicts in the earlier
conflict resolution session.
In step 6, a script is executed
that edits the contents of the main configuration file
/usr/local/kernun/conf/kernun.cml
to make
it compatible with the upgraded Kernun UTM. Sometimes, if there
are complex changes in the configuration syntax and semantics between
the two Kernun UTM versions, or if the configuration file contains certain
advanced constructs, the script may be unable to perform a perfect
conversion. It is therefore recommended to always check the result of the
automatic conversion in step 7.
The new configuration file needs to be applied before the upgraded system can be put into normal operation. The low-level configuration files are generated and the configuration is applied in the context of the newly installed system using the applycfg command of sysmgr(8). If the generation or application of the configuration fails, the configuration should be corrected and applied again.
Finally, the upgraded Kernun UTM can be put into the normal production mode by rebooting to the newly installed system partition.
No modifications of the configuration (steps 6 and 7) are often required during the upgrade procedure. This is usually true when upgrading between two builds of the same version or between patch releases of the same version, for example, from 3.0 to 3.0.1 or from 3.0.1 to 3.0.2.
An upgrade is initiated from the Quick Wizards page of the System Manager. There are two alternatives. Click if you want to start the complete upgrade procedure. If you already have a recent backup of the system partition that you want to upgrade, you can skip the first step — creation of a backup. In this case, use the button. We will describe only the former alternative; the latter is almost identical, only the backup step is missing.
The GUI assumes that we want to upgrade the currently running Kernun UTM instance. Therefore, the current system partition will be backed up. After clicking on the Figure 2.11, “Parameters of an upgrade operation”). Click on the button to start the upgrade.
button, we select the target system partition in which the upgraded Kernun UTM will be installed. Then we select the installation image of the new version. Our selections are displayed in the settings recapitulation window (The GUI displays the progress of the upgrade procedure. First, the current system partition is backed up. Then, the new system partition is installed and the backup is restored in it. If there are any conflicts, the conflict resolution window is displayed, as shown in Figure 2.12, “The conflict resolution window during an upgrade”. The window shows a list of conflicting files. You can determine how to resolve the conflict of a file by clicking in the Action column. The following actions are possible:
+
— uses the
“backed-up“ version of the file;
.
— uses the “new”
version of the file, as installed from the new installation
image;
-
— deletes the file;
!
— postpones the conflict to the
next iteration of conflict resolution.
It is also possible to select a file and then click a button on the right-hand side of the window to display the differences between the two versions of the file, or to open one of them in an editor.
After you give instructions for conflict resolution and optionally edit some conflicting files, click Figure 2.13, “Final settings after an upgrade”) that makes it possible to realise any combination of the following actions: set the newly upgraded system partition as the default boot partition; run the configuration conversion script; change the partition label; reboot Kernun UTM immediately.
to have the conflicts resolved. Finally, a window is displayed (seeCommand line upgrades are realized using the sysmgr(8) utility. Unlike when using the GUI, which performs all the required steps automatically, a command line upgrade must be done step by step. An example of the upgrade procedure follows:
[root@fw ~]#
cml -l -f /usr/local/kernun/conf/kernun.cml
RCSL-730-N File '/usr/local/kernun/conf/kernun.cml' locked for current user CMLM-790-N RCS command completed[root@fw ~]#
sysmgr checkcfg
... Configuration is correct[root@fw ~]#
sysmgr backup
Creating backup content database /kernun-backup.fsdb.bz2 Creating file system content database Creating backup file /data/backup/backup-030000h00.200809241501.i386-1-200811300006.tbz![]()
[root@fw ~]#
sysmgr install 2 030002h00.200811291341.i386
Clearing system partition 2 ... Installation successfully finished![]()
[root@fw ~]#
sysmgr upgrade 2 \
>
backup-030000h00.200809241501.i386-1-200811300006.tbz
Processing changes of file system contents Unpacking files from backup Resolving conflicts There are pending conflicts, see /data/restore/resolve *** CONFLICT RESOLUTION ***![]()
1. Resolve with easy editor (ee) 2. Resolve with editor vi 3. Do not resolve now Select action:
2
# Conflict resolution file for system partition /2# Each line of this file contains an instruction for one file. You # can edit the file and then apply the instructions by running # "sysmgr resolve". Every line contains three fields: # - one character that defines an action to be done with the file # - one character for file type ('d' for a directory, '-' for any # other type) # - path to the file, interpreted either relative to /2 for the # existing file and relative to //data/restore/conflicts # for the file from the backup # Procedure of conflict resolution: # 1. Locate all lines beginning with '!'. These denote conflicting # files. # 2. Optionally edit the conflicting files. # 3. Change the character '!' to # + ... to use the file from backup, temporarily stored in # /data/restore/conflicts # . ... to keep the current file # - ... to delete the current file # ! ... keep the conflict for future resolution # 4. Run "sysmgr resolve". # 5. Repeat steps 1-4 until all conflicts are resolved. # Merging file from the backup with the current file can be done # either by editing the current file and specifying action '.' # (keep) or editing the file from the backup and specifying # action '+' (use backup). ! - ./etc/motd ! - ./etc/login.conf ... Resolving conflicts There are pending conflicts, see /data/restore/resolve
![]()
[root@fw ~]#
vi /data/restore/resolve
...![]()
[root@fw ~]#
sysmgr resolve
Resolving conflicts All conflicts resolved![]()
[root@fw ~]#
sysmgr upgradecfg 2
Upgrading Kernun configuration /2/usr/local/kernun/conf/kernun.cml /2/usr/local/kernun/conf/kernun.cml,v <-- /2/usr/local/kernun/conf/kernun.cml new revision: 1.2; previous revision: 1.1 done Automatic configuration upgrade done. It is recommended to review the configuration before returning Kernun UTM to production use.![]()
[root@fw ~]#
sysmgr applycfg 2
... System kernun applied in system partition 2![]()
[root@fw ~]#
cml -u -f /usr/local/kernun/conf/kernun.cml
CMLM-790-N RCS command completed[root@fw ~]#
Before upgrade, the configuration should be locked
[11], checked and
normalized
. This step ensures that
the configuration upgrade step
will
understand the configuration file. The upgrade procedure starts by
backing up the current system partition
.
Specify a system partition number to upgrade a currently
inactive partition. If a recent backup already exists, this step can
be skipped. A new Kernun UTM version is installed to an unused system
partition
. This command also sets
the default boot manager label for the newly installed partition, and
makes it bootable and the default boot selection for the next booting.
The backup is then restored to the newly installed system partition
. This command writes the list of
conflicts to
/data/restore/resolve
. The
conflicting files from the backup are stored in the
/data/restore/conflicts
directory. If there are
conflicts, the conflict resolution menu is displayed . You can either resolve the conflicts,
or postpone the conflict resolution to do it later. If you choose
to resolve the conflicts, the conflict resolution file
/data/restore/resolve
is opened in a text editor.
Edit the file according to the displayed instructions to determine the way of resolution
of individual conflicts. After the file is saved and the editor is
terminated, the conflict resolution is executed in accordance with
the file. If some conflicts remain unresolved, a message
is printed. It is then possible to
edit
/data/restore/resolve
manually and restart the conflict resolution
. Commands
and
can be repeated until all
conflicts are resolved. The main configuration file is
upgraded
and applied
. Finally, the lock is released
. You can then reboot to
the new system partition and start using the upgraded Kernun UTM.
The Kernun auditing tool kernun-audit(1) provides a convenient source of information about bugs discovered in the Kernun software. The auditing tool also reports when a new software version becomes available. A Kernun audit is usually executed daily by the cron daemon via the periodic command. It downloads the up-to-date auditing database, and then examines the product type, version, and architecture of the installed system. Based on these values, the relevant records are extracted from the database and reported. There are two classes of records: bugs and software updates.
Each bug that is discovered in the currently installed version of the Kernun product is reported. A bug has a unique identification number, a description, a list of versions, in which it occurs, a solution, and a workaround. The recommended solution is always a software update to a version in which the bug has been fixed (if such version is available). The workaround (if available) describes how to minimize the impact of the bug without updating the software. It should be applied if the software has not been fixed yet or if an immediate update is infeasible. Nevertheless, the workaround should always be regarded as a temporary solution and the Kernun installation should be updated as soon as possible.
Software updates are reported only for the same product and architecture as in the installed system. The latest patch release from each release branch is shown. Only versions newer than the currently installed version are displayed. For example, if 3.1 is the version installed and 3.0–3.0.6, 3.1–3.1.3, and 3.2–3.2.1 are available, 3.1.3 and 3.2.1 will be the versions reported.
The initial configuration of a Kernun system runs the auditing tool
daily using the DEFAULT-CRONTAB
and
DEFAULT-PERIODIC
variables from the
included crontab and the periodic configuration file
crontab.cml
. Auditing can be disabled by setting
daily_status_security_kernun_audit_enable
to
"NO"
in that file. The auditing tool
kernun-audit can be also executed manually from the
command line. The product name, version number, and architecture name are
obtained from the current system, or can be specified using the command line
arguments of kernun-audit. The identification of the
current system is stored in the files /kernun-product
(product name) and /kernun-version
(build number,
which contains the version number before the first dot and the
architecture name after the second dot). If the location (local or remote)
of the audit database is not specified, the database is downloaded from
download.kernun.com
by
default.
The www.kernun.com
Web
site provides an online version of the Kernun auditing tool. After filling
the Kernun product, version, and architecture in a form, the auditing report
is generated in the same format as the one kernun-audit
produces.
The instructions in this section are intended for experienced administrators with profound knowledge of Kernun UTM and FreeBSD.
The Kernun UTM installer booted from the installation medium can be used to repair the system if all system partitions are unable to boot. The available functions are accessible from the installer main menu:
1. Install Kernun 2. Check for existing Kernun installations 3. Restore backup 4. Start rescue shell 5. Mount Kernun file systems 6. Resize installer's in-memory temporary file system (current size 32m) 7. Halt 8. Power down 9. Reboot 0. Install license
Option 1
is described in
Section 5.1, “Standalone Installer”. Options 7
,
8
, and 9
are
self-descriptive. Option 2
displays the boot manager
configuration and the disk device names.
System disk is /dev/ad0 Boot manager on ZFS pool 'kernun' F1: Kernun 3.11 2018/06/06 07:36 (031100h00.201806111345.amd64) F2: Unused F3: Unused type=Kernun ZFS boot manager ver. 1.0 current_booted=NONE bootable=1 update=1 default_selection=F1
Option 3
restores a backup selected from a list
of backup files found in /data/backup
. If the backup
is stored on another medium, it must be first copied to the
/data/backup
directory, using for example the rescue shell
(option 4
). For details about backup and restoring, see
Section 6, “Backup and Restoring”.
Option 4
starts a rescue shell
(bash). It provides the environment for emergency
maintenance of a computer with non-bootable Kernun UTM installations. The
rescue shell (as well as the whole standalone installer) runs in a custom
FreeBSD environment. The standard Kernun UTM kernel is used. The root file
system is mounted from the installation medium and is therefore read-only.
A read-write RAM disk for temporary data is mounted under
/tmp
, symlinked also from
/var/tmp
. The standard size of the RAM disk is
32 MB. It can be resized using option 6
of the
installer main menu.
The content of the RAM disk is lost when the installer is terminated or when the RAM disk is resized.
Do not make the RAM disk too large, because its content is stored in the kernel memory. If the free kernel memory gets too low, the kernel may panic.
Option 5
of the menu mounts any existing Kernun UTM
partitions under the directories /1
,
/2
, /3
(the system partitions),
and /data
(the data partition). The rescue shell
provides many standard FreeBSD command line programs. Programs from a mounted
Kernun UTM system partition can be run as well.
It is often useful to perform a chroot(8) to a mounted Kernun UTM system partition and to run commands in the chrooted environment.
Kernun can be deployed in any virtualization environment with support for FreeBSD OS.
See also the notice in Section 24, “High Availability Clusters”.
The following virtualiztion environments are tested for compatibility with Kernun.
The emulators/open-vm-tools-nox11 is installed and staretd automatically if the VMWare environment is detected.
The virtualization support is built in the FreeBSD OS. See also https://docs.microsoft.com/cs-cz/windows-server/virtualization/hyper-v/Supported-FreeBSD-virtual-machines-on-Hyper-V and https://wiki.freebsd.org/HyperV for more detailed information.
The emulators/virtualbox-ose-additions is installed and started automatically if the VirtualBox environment is detected.
[1] Collect values from lines
starting with component:
, group:
, and
upgrade:
in the license file.
[2] You can use dd
on Linux / BSD or
ImageWriter on Windows to copy the USB flash drive image
to the device.
[3] It is usually the first disk: da0
(SCSI), ad0
(PATA), ad10
(SATA).
[4] including
usr/local/kernun/license.dat
[5] More precisely speaking, the initial
configuration script is executed during any system boot if there is no
Kernun UTM configuration file
/usr/local/kernun/conf/kernun.cml
and none of
the files /etc/rc.conf
and
/etc/rc.conf.local
contain the line
kernun_config_enable=NO
.
[6] The host key is used by the SSH client (or GUI) to ensure that it is communicating with the intended server. It is different from the client's key, which is used to authenticate the client to the server.
[7] An image is considered older if it has a lower version number or an earlier build date.
[8] for example, access rights, owner, or modification time
[9] for example because they are in a system partition that is not used any more
[10] By a change, we mean modification of the contents of the file, deletion of the file, a change of the file attributes (e.g., the owner or access rights), or creation of a previously nonexistent file.
[11] Steps and
are supported by Kernun since
release 3.6. In the prior versions, these steps should be
skipped.
Kernun UTM can be administered locally, or remotely via the network. Local administrator access is usually limited to the initial installation, when the network is not yet configured, and emergency situations after a failure or misconfiguration if the network is not accessible. The administrator can access the system locally via a text system console. It provides the same set of command line tools as the remote text login via SSH. In normal operation, Kernun UTM is usually administered remotely. There are two options for remote access: a text command line interface and a graphical user interface.
An administrator can log in to Kernun UTM remotely via SSH and get shell access to the system. Administrative tools accessible from the shell include the primary Kernun UTM command line control and configuration tools kat(8) and cml(8), see also Section 2, “Command Line Interface”. Besides these two, many additional command line utilities are available, including specific Kernun UTM commands introduced in Section 3, “Administrative Utilities” and all the standard FreeBSD commands.
Kernun UTM's graphical user interface (GUI for short, described in Section 1, “Graphical User Interface”) provides a similar functionality as the command line utilities, but in a more intuitive and comprehensive way. It shows the current state of all system components and can display details for each component. The GUI contains also a powerful log analyzer, a configuration editor, and a system manager, which administers installations, backups, and upgrades. There is some functionality that is unique to the GUI and cannot be accessed from the command line, such as displaying of performance graphs. The GUI runs on the administrator's local computer and communicates with Kernun UTM via the network, using SSH internally. Hence, the same prerequisites are needed for both the command line and GUI access to Kernun UTM (especially, SSH keys and the SSH protocol enabled on the way between Kernun UTM and the administrator's computer).
In this section, we will introduce the Kernun GUI. In later chapters dealing with configuration (Chapter 4, Configuration Basics, and Chapter 5, Advanced features) we will assume that the administrator knows how to use the GUI.
The Kernun GUI is available in two functionally equivalent versions: for Microsoft Windows and for UNIX. The binary executables of the Kernun GUI are distributed for MS Windows and for FreeBSD [12]. The Kernun GUI can be easily compiled also for other UNIX platforms. See the README file for instructions on how to compile the Kernun GUI.
On UNIX machines, the Kernun GUI expects OpenSSH to be installed
(namely, the ssh, ssh-agent,
ssh-keygen and ssh-add programs are
expected to be located in a directory listed in the PATH
environment variable).
There are no prerequisites to be installed on MS Windows. All the necessary executables are included in the Kernun GUI distribution.
The Kernun GUI provides the following functionalities:
monitoring of the state of Kernun UTM;
management (starting, stopping, restarting, …) of Kernun UTM (or its particular components);
work with logs (both current online logs and downloaded offline logs) and statistics;
modification and application of the configuration of Kernun UTM;
administration of Kernun UTM installations, backups, and installation images.
When the GUI is started, the launcher window is displayed, see Figure 3.1, “GUI Launcher”. The launcher provides buttons to open (and change) a local copy of the Kernun UTM configuration file (for more information on work with the configuration in the GUI see Section 1.4, “GCML — Configuration”) or examine a local log file (see Section 1.3, “Logs”). However, the main purpose of the GUI launcher is to establish a new connection to Kernun UTM and launch the main GUI management window.
The GUI communicates with Kernun UTM via
SSH connections. You therefore need to have the
sshd
service running and correctly
configured (see Section 2.3, “SSH Server”).
The parameters of the SSH connection to Kernun UTM are specified in the
Connection Parameters dialog, as depicted in Figure 3.2, “Connecting to Server”. You need to fill in the
Host name or IP address of the Kernun UTM machine,
Username, Port and select the
SSH key file.
If you are connecting to Kernun UTM via SSH for the first time, you need to initialize Kernun UTM (i.e., download your private SSH key from Kernun UTM). To do this, use the dialog that appears after the Hostname and the Password you entered during the installation. See also Section 5.2, “Initial Configuration”.
button is pressed. Fill in theIf you intend to apply the configuration to other Kernun UTM than the one you are logged in (for example, the second Kernun UTM in a cluster), you must check the Forward SSH agent check box. See ssh(1) for information about security risks of SSH agent forwarding.
It is unsafe to leave the SSH keys loaded in the ssh-agent after finishing your work with Kernun UTM.
The key is deleted automatically on
UNIX, if there was no
ssh-agent running before the Kernun GUI was started.
Otherwise, you need to unload it yourself (e.g. using
ssh-add -d private_key_file
).
On MS Windows, the Kernun GUI instances are managed by the GUI launcher, which is set to unload the keys automatically (after a timeout) if there are no main Kernun GUI applications running. You can change this behavior or unload the key manually using the context menu of the Kernun GUI taskbar icon.
The functionality of the Kernun GUI main window, depicted in Figure 3.3, “GKAT — Kernun UTM management console”, is basically equivalent to the command line administrative tool kat(8). It displays the states of individual Kernun UTM components and allows them to be started, stopped, and monitored.
When connected to Kernun UTM, the state of the proxies and other
system components is indicated
by their state icons. The states of the components are also
propagated to the state icon of their parent component groups and of
the whole Kernun UTM. There are the following component groups:
Proxies, System Components
(such as SSH servers, mail forwarders, or DNS servers),
Network (interfaces, packet filtering, routing),
and Open VPN servers.
A running component is denoted by green icon background , whereas the background of a stopped component
is red
. There are several icon overlays that
indicate further information concerning the component's state:
Not up-to-date configuration — the
configuration of the component has changed; reload it, so that the changes
can take effect.
Parent exiting flag — the proxy is in a special state: it
does not accept new connections, but only waits for the already active sessions to finish.
For example, this state may appear when a proxy is reloaded, some sessions
remain open in the old proxy instance, and only the new instance accepts
new connections. Total restart of the proxy stops the old proxy instance and
starts another, so no sessions remain open.
Not in configuration — the system component
is not in the configuration. Kill the component to solve the problem.
Component's state changing — this overlay
is displayed while the component's state (started/stopped/restarted/reloaded) is being changed.
It disappears immediately after the action is finished.
In the situation depicted in Figure 3.3, “GKAT — Kernun UTM management console” we know that all proxies are running, even though the Proxies subtree is collapsed. The IPS component is stopped, which is why the System Components and Kernun icons are partially green and red. Kernun UTM has four network interfaces, the packet filter and the routing table running. No Open VPN server is configured. You can click on a component, group, or the whole Kernun UTM icon in the proxy tree to select it and display its details in the right-hand part of the window. The information about the RTT (Round Trip Time) in milliseconds between the GUI and Kernun UTM is displayed next to the Kernun UTM name.
On the Manage page of the whole Kernun UTM (that is, with the top-level Kernun node selected from the component list in the left-hand part of the window), the administrator can easily manage (start/stop/reload/restart) the whole Kernun UTM, as depicted in Figure 3.4, “Kernun UTM Manage Page”.
The selected action can be applied either to all components, or to the components marked with a tag in the configuration. The tag or the All components option can be selected from a combo box. A change in the configuration takes effect only after the system state is synchronized with the updated configuration. This can be always done by rebooting, restarting, or reloading the whole Kernun UTM, but it often suffices to restart only a subset of components, while the remaining parts of Kernun UTM may be left running. The Synchronize system button automates this process. It displays a window (depicted in Figure 3.5, “System state synchronization dialog”) that lists the actions required to bring all the components into sync with the configuration. You can manually alter the proposed actions by clicking on a component in the Action column. When you are satisfied, click and all the selected actions will be executed.
The Process List page (Figure 3.6, “Process List page”) contains the list of the running parent proxy processes[13].
The context menu in the process list
(Figure 3.7, “Process List context menu”) can be used to send the TERM
(Kill parent process) or KILL
(Kill -9 parent process)
signals to the particular process, to copy the contents of
the process list to the clipboard or to save them to a file.
The Graphs page contains graphs of various system parameters, see Figure 3.8, “Graphs page”. There are many monitored parameters of the operating system (CPU load, used memory and disk space, etc.), hardware (temperature measurement, if supported by the hardware), and cluster behavior (switches between the cluster master and backup). Kernun UTM collects parameter values and creates graphs depicting how they evolve in time, with several time scales available. The most detailed graphs show only the recent history, while coarse-grained graphs extend further into the past. Right-click on a graph to open a context menu that makes it possible i.a. to save the graph to a file or to add it to Favorite graphs.
The Top page (Figure 3.9, “Top page”) shows the output of the popular top(1) command. The Misc page (Figure 3.10, “Misc page”) displays the output of several commands, showing i.a. the disk space (the df -hi command), the network state (netstat) or the uptime and current load of Kernun UTM (w | head -n 1). The Version page (Figure 3.11, “Version”) shows the version of Kernun UTM and of the FreeBSD system used by Kernun UTM.
When the Proxies node or a particular proxy is selected in the component tree, it is possible to control and monitor all proxies or the single proxy, respectively. The set of pages is similar in both cases, but the Process List and Graphs pages are available only if a single proxy is selected.
The Manage page for all proxies is similar to the Manage page of the whole Kernun UTM (Figure 3.4, “Kernun UTM Manage Page”), but the button and the combo box used to restrict operations to the tagged components are missing. For individual proxies, there are three additional buttons. terminates the proxy like , but works also for proxies that are removed from the configuration. The and buttons change the log level. For more information about log levels, see logging(7).
The Process List page contains the list of running processes, restricted to the processes that belong to the particular proxy; both parent and child processes are listed. The functionality is identical to the global process list (Figure 3.6, “Process List page”), including the possibility to send signals to processes.
The Monitor page, see Figure 3.12, “Proxy Monitor”, shows the current active sessions of all proxies, or of the selected proxy. Its content is available only for proxies, for which monitoring(5) is enabled in the configuration. Proxies can be configured to generate the monitoring information into different directories, so it is possible to select the directory, from which the GUI will read the monitoring data.
The Graphs page's functionality is similar to the system-level one shown in Figure 3.8, “Graphs page”, but different graphs are displayed: the number of proxy child processes and the number of bytes transferred by the proxy.
The Log page shows the current log messages of the selected proxy, or of all proxies. New messages are added immediately, so the log view provides information about the current proxy activity. Select from the context menu in the log view to open the Details window with a reference page containing information about the selected message. Click on the Row Detail tab in the Details window to display the message as a whole, rather than split into fields. Figure 3.13, “Proxy Log” shows the log page with the Details window displayed.
The Network node in the component tree groups individual network interfaces, the routing table, and the packet filter[14].
All nodes in the Network subtree share the Manage page containing buttons for starting/stopping/restarting/reloading a component, similar to that of the whole Kernun UTM, as depicted in Figure 3.4, “Kernun UTM Manage Page”, but without the Synchronize system button and the component tag selection combo box. Other pages differ for various types of nodes in the Network component subtree. For the Network node, individual network interface nodes, and routing there are pages containing output of the ifconfig(8) and netstat(8) commands with various parameters. The Network node provides an additional page sockstat -4 with the list of all existing IPv4 sockets. Each network interface has a Graphs page with traffic statistics graphs in bits and packets per second. Otherwise, the page behaves like its system-level counterpart (Figure 3.8, “Graphs page”). The current configuration and state table of the packet filter node can be displayed using pages containing the output of the pfctl(8) command.
The toolbar and the menu of the main GKAT window contain almost identical sets of actions. They are adapting to the currently displayed components (page) of the application, i.e., only the useful (and usable) buttons or menu items are enabled.
Figure 3.14. Main window toolbar buttons, listed together with the corresponding menu items, and sometimes keyboard shortcuts:
— Shows the about dialog box with information about the GUI version.
diff program).
— Opens the basic preferences dialog, in which you can set the default behavior of your GUI (e.g., your default<Ctrl+L> — Opens a form, in which you can choose certain restrictions of the log information to be analyzed (date, time, proxy, etc.), and then downloads the log from Kernun UTM and displays it in a new window (for more information on log analyzing see Section 1.3, “Logs”).
— Opens a proxy statistics browser window. If configured, daily, weekly and monthly statistics of traffic handled by proxies are computed from the log. The browser window displays a hierarchy of available statistics ordered first by the frequency (weekly/monthly/daily), then chronologically, and finally by the proxy name. After choosing an item from the hierarchy, the corresponding statistical output (in the form of a HTML document with images containing graphs) is displayed.
The
submenu:— Lets you choose and edit a sample Kernun UTM configuration that you can later use as your Kernun UTM configuration.
— Opens a local configuration file for editing. You can later upload it to your Kernun UTM to use it as its configuration or save it back to your computer.
— Opens an RCS Browser displaying all the changes you have made in the Kernun UTM configuration and making it possible to switch back to any of the previous versions.
The
submenu:— Opens the console with an ssh connection to Kernun UTM.
— Opens a dialog, in which you can create custom remote commands that can be executed in the console. When created, they are added to the menu and can be easily invoked.
Section 5, “Installation”, Section 6, “Backup and Restoring”, and Section 7, “Upgrade” for details. The system manager has also the License page, accessible also from . It displays the current license file and provides a button for uploading a license file to Kernun UTM.
— Provides routines to install, backup, and upgrade Kernun UTM installations. SeeRTT gets too high or the connection is interrupted.
— Restarts the connection from the GUI to Kernun UTM. It may be useful if your<Ctrl+T> — Opens the current page in a new window and keeps it up-to-date (refreshes the selected page).
Refresh Frequency — The period, with which new data is downloaded from Kernun UTM. The lower is the period, the more traffic load Kernun UTM produces towards the GUI.
Start/Stop — Starts and stops refreshing (downloading of new information from Kernun UTM) of the current page.
— Makes a static copy of the current page and opens it in a new window. This window is never refreshed. It can be used to analyze the snapshotted situation (e.g., the traffic log).
— Clears the contents of the current page.
<Ctrl+M> — Shows or hides the Filters and Markers window, which is used to specify filtering and marking for the displayed log (see Section 1.3, “Logs”).
<Ctrl+D> — Shows or hides the details window, which displays the details of the current row (e.g., in a log) and the reference page for the current row type.
<Ctrl+B> — Shows or hides the bookmarks window. Bookmarks are used to assign a name to a certain line of a snapshotted situation. You can then easily jump from one bookmarked line to another.
<Ctrl+F> — Opens a dialog used to search for selected text in a selected column. The view highlights all the found occurrences and jumps to the first one.
<Ctrl+G> — Jumps to the next line marked by the chosen marker.
<Ctrl+Shift+G> — Jumps to the previous line marked by the chosen marker.
<Ctrl+I> — Adjusts the column widths according to the widths of their contents.
<Ctrl+Up> — Scrolls to the beginning of the current page.
<Ctrl+Down> — Scrolls to the end of the current page and keeps scrolling so that the newly added lines are displayed. This function is most useful with the Log page, if we want to display newly added messages continuously.
The Kernun GUI contains a powerful log analyzer. It provides tools for filtering out undesired log entries and for marking those that are more important to you with different colors. The log window (possibly displayed as a part of another window) is displayed in several modes: you can either open a local log file, download a “historical” log file from Kernun UTM, take a snapshot of the currently displayed log, or work with the up-to-date (and changing) log.
The first setting concerning logs is the specification of the log level for the particular proxy (permanently in the configuration or temporarily using buttons on the Manage page). There are seven different log levels, as described in logging(7). The higher the level is, the more information the Kernun UTM stores (and sends to your log analysis window).
Figure 3.15, “Example of a simple HTTP filter and marker set” shows an example of a log display window (created by selecting in the GKAT main menu). The logs are presented as tabular data. You can drag a column by its title and drop it elsewhere to change the column order. Each column has a context menu used to select which columns are to be displayed. For example, if you are analyzing a log from a particular proxy in a single Kernun UTM network, you may want not to display the columns Fw (Kernun UTM name), Proxy and PID (as the PID is also included in the column called SID, which is a concatenation of the PID and the number of the current session[15] served by this process). You can use the Save column visibility settings option, so that you do not have to set it every time.
The filters and markers are accessible using <Cltr+M>). Filters are used to display only the log entries that you are interested in, while the main point of markers is to highlight some special rows (columns) in the log. A selected marker can be then easily used to jump to the next/previous marked line.
(Both filters and markers are managed (created, deleted, moved, changed) in a similar way. From now on we will only describe management of filters. However, all of the operations work in the marker context, too.
The only difference between the management of filters and markers is that markers are applied automatically after a change, whereas filters need to be explicitly applied by selecting the Filters node, or by clicking on the same button, which appears blinking after any change in the filter set. Moreover, the context menu of a marker contains an option used to change the highlighting color and highlighted column(s).
option from the context menu of theIf you work with the current live log, the filters only apply to the newly incoming log messages. The old ones are not filtered out even if you apply the filter. To filter out older log entries, tear off a snapshot. Markers take effect instantly in all situations.
There can be many filters in the system. They are all presented in the filter tree under the Filters node. Some of the filters may be turned off (by unchecking the box next to their name). Each filter is a tree of conditions with logical operators And, Or and Not. Each condition consists of a column to be examined, a relational operator and a desired value. The relational operator defines the relation between the value in the column and the desired value that must be fulfilled in order for the row to be included in the log. The following relational operators are available: Is, Contains, Matches regex and their negations, Starts with and Ends with; they are all self-explanatory.
The easiest way to create a filter is to drag and drop a field from the log table. A new filter is created and a new condition inside this filter is initialized with the value of the field you dropped there. You can also drag a field and drop it on the relational operator (then the new condition is added as a child of the operator) or on another condition (in this case, you are asked whether you want to use And or Or to connect it with the target condition or whether you want to add the new condition to the same parent). Other useful options (including creation of a new filter) are listed in the context menu of the selected node of the filter tree.
Having created some filters, you can copy a particular node (and all its subnodes) to another place simply by dragging it there. In this way you can easily create a filter from an existing marker, and vice versa.
You may want to save filters you create for future use. You can save a single filter or any subset of filters. Both saving and loading of filters is done using the context menu of the chosen filter (or the Filters node). A filter can be saved either to a local file, or to the registry. The filters (and markers, of course) in the registry are displayed in (and can be loaded from) the submenu of the top-level Filters/Markers context menu.
To rename a filter/marker, double-click on its name or select
from the context menu.This section describes the GUI functionality for examination and modification of the Kernun UTM configuration. It does not describe the configuration language. See Section 1, “Configuration Language” for an introduction to the configuration syntax and semantics, and Section 2, “The Initial Configuration” for a simple configuration example.
Kernun GUI provides a GUI editor for the Kernun UTM configuration
files (
). The
GUI CML editor is functionally equivalent to the line-oriented
cml(8) tool. The GUI CML editor is aware
of the CML syntax and semantics and highlights points of the configuration
that are detected as erroneous. When connected to Kernun UTM,
the Kernun GUI can automatically download the configuration from Kernun UTM,
present it in the graphical CML editor, and commit it back to
Kernun UTM. The GUI CML editor can also open a local file; in this
case, a connection to Kernun UTM is not required.kernun
.cml
Figure 3.16, “GUI CML Editor” shows the main GUI configuration window. The configuration is displayed in an expandable configuration tree. You can select a node to display and easily edit its details in the right-hand part of the window. The displayed details include the selected node's type and name, its full path in the configuration (as displayed by cml(8) in the command line prompt), a brief description, and the constraints (if there are any). There is also a form with fields (editable, if appropriate) that represent the elements of the selected node. A short description, the name of the element, and the expected data type are displayed to the right of each field. The labels of the required fields are highlighted (bold). Several field types help you fill in data of the correct data type. If you make a mistake (e.g., do not fill in all the required information or do not respect the expected data type) the background of the incorrect field is highlighted, an exclamation mark button appears next to it (click on the button to show the error message) and the error is also displayed in the configuration tree.
When editing the configuration, select
in the main menu to display the differences between the current contents of the configuration and the original configuration file downloaded from Kernun UTM. The currently edited configuration can be saved to a local file using the menu item. In addition to online marking of incorrect configuration nodes, it is possible to invoke verification of the whole configuration using .When you finish editing of the configuration, you may want to save and apply it to Kernun UTM or save it as a local file. Both can be easily done using the <Ctrl+S>) invokes a dialog, depicted in Figure 3.17, “Configuration commit dialog”, where you can choose actions to be done with the configuration on Kernun UTM (save/generate/apply/synchronize state, all done by default) and the configuration to apply. The results of the action are displayed in a text box. If you have made any changes to the configuration, you are asked to fill in the RCS Log Message describing the changes. First, the configuration file is saved and stored in a RCS file, in which the complete history of changes is kept and from which any old version of the configuration file can be retrieved. Then, low-level system and proxy configuration files are generated. The application of the configuration means copying the low-level configuration files to locations, in which Kernun UTM components look for them at the startup. Finally, the system state is synchronized with the configuration. This is the same action as the one performed by , including the possibility of reviewing and modifying the list of performed actions in the dialog window shown in Figure 3.5, “System state synchronization dialog”.
menu. Committing of the configuration (Each line of the configuration tree represents a node of the Kernun UTM configuration and has an icon according to its type. You can select a node by clicking on its name. The easiest way to move in the tree is using the cursor keys. <Up>/<Down> selects the next/previous node, <Right> expands the current section, <Left> jumps to the parent of the current node (or collapses an expanded section). A non-empty section node can also be expanded/collapsed by clicking on the +/- sign next to it. Useful commands for interaction with the configuration tree are available in the menu, the context menu of the selected node, and on the toolbar. A section can be expanded, along with all of its subsections (and their subsections, etc.) by selecting <Ctrl++> (and collapsed using the <Ctrl+-> command). Because the order of individual sections and items matters, you can move a node up and down (<Ctrl+Up>/<Ctrl+Down>) using commands from the same menu. You can also (<Ctrl+D>), (<Ctrl+H>), (<Ctrl+C>), (<Ctrl+X>) or (<Ctrl+V>, pastes the last copied/cut node under the selected one) a node.
If you are more familiar with the line-oriented cml(8) tool, you may want to see the text version of the configuration of the current node (section). This is accessible from the menu or from the context menu of the node. A read-only window containing the output of the /show -a cml command is displayed.
Inserting a new node using the
<Ins>), or next
to the current node (<Ctrl+I>)). Then you need to
choose the type of the new node (section, item, data variable
definition, section variable definition, section variable application,
for
loop, switch/case, include file, or comment).
In the case of inserting a section, item or section variable, you need to
choose the type of the section/item and its name (if appropriate).
Finally, the new node is inserted and you can edit its properties in
the details window.
Several form field types are used to represent the properties of a node. It is important to understand each of them, in order to fill in correct data.
Text box — Expects text data. However, you
cannot fill in anything; you still need to preserve the data type
specified in the parentheses in the field label (e.g., the
sock type means
[
).
The syntax of values of various data types used in the Kernun UTM
configuration is described in Section 1, “Configuration Language”.ip
]:port
Check box — Can either be checked (true), or unchecked (false).
Combo box (selection) — You can
choose exactly one of the specified options. If you want to
enter its content manually, you need to use the
menu item, which allows you to write there “anything”
(e.g., a variable name). If there is
a “fork” icon next to the combo box, the value of
the combo box decides which further form fields are displayed
(e.g., in system.smtp-proxy.delivery-acl.sender
the error value requires further constraints
on the error, whereas the ok option does
not).
List of values — Some CML
properties (e.g.system.acl.service
) expect
a list of values of a certain type (str,
addr…). You need to be able to create new values, as
well as change and delete the old ones. The value list field type
displays each value of the list in a separate row. You can
simply edit a particular value in the same way as you are used to
work with the above-mentioned field types. A value can be deleted
from the list using the icon next
to it. To insert a new value, click the
button. The value lists can be
multidimensional (any value list can contain sublists, which can
also contain sublists, etc.). You can append a new
sublist by clicking the
button. On the right from
a sublist there is a button with a submenu that allows to
or
(creates
the negation of the current sublist).
List items can also be loaded from a file, in which each line
represents one item of the list. To “inject” a file
into a list, click on the button and select the shared-file
section name, in which the file name and the format (e.g., IP
addresses, text or REGEXPs) are specified.
The contents of the shared-file
can be
edited in the GUI in the details of the path
item of
the shared-file
section.
As orientation in a very big configuration may become difficult, the Kernun GUI provides tools to simplify it.
First of all, you can use <Ctrl+B>) to create bookmarks (like in your Web browser) to important positions in the configuration tree. The bookmark window is displayed in the top right part of Figure 3.18, “Bookmarks and relevant sections in GUI CML”. To add a bookmark to the current configuration node, select the option from its context menu or the option from the context menu of the bookmark list in the Bookmarks window. You are asked to fill in the bookmark's title before adding it. You can jump to a bookmarked node by double-clicking the bookmark's name in the Bookmarks window. Additional bookmark operations (removing, renaming) are available from the context menu of individual bookmarks.
(In addition to simple bookmarks, the Kernun GUI provides smart bookmarks, accessible via <Ctrl+R>). Smart bookmarks are used to highlight the configuration nodes that are relevant to the chosen nodes (e.g., the ACLs for proxies) and to easily jump to them. The function of finding and highlighting of the relevant nodes is only available for proxies (it would not make much sense for other nodes), but the relevant nodes may include any sections (proxies, ACLs or other sections). A node is relevant to a proxy if a change to the node may alter the behavior of the proxy.
(There are two lists of bookmarks in the Relevants window. The first one (Proxies) displays the list of all proxies in the configuration and makes it possible to select the proxies, for which the relevant nodes are to be highlighted. The other list (Relevant sections) displays bookmarks to configuration nodes that are relevant to the chosen proxies. Again, you can double-click a bookmark to jump to it in the configuration tree. After selecting the proxies in the Proxies list, the relevant nodes are highlighted in the configuration tree and bookmarks to them are displayed in the relevant sections list.
There are more actions available from the context menus of the items of the bookmarks lists, including
(which adds the current item to the simple bookmarks), (works like double-clicking on the item), and several default selection templates for the proxies. Furthermore, you can choose the types of relevant nodes that you are interested in for the Relevant section items.You might not want the relevant item list to be to refreshed automatically (after every change in the configuration and in the selection of the proxies), especially on a slower machine. This behavior can be controlled from the context menu of any of the relevant items using the
check box in its context menu. If it is unchecked, you have to refresh the list manually by clicking the button.The Kernun GUI provides configuration wizards in order to simplify the configuration of complex tools (OpenVPN, IPSec). All the wizards are accessible via the
menu item. Select to open a dialog that describes all the wizards and the use of the created part of the configuration, and makes it possible to start the selected wizard.Each wizard is divided into several pages that prompt the user to fill in individual fields. The form fields are the same as in the GCML, so you can use references to other parts of configuration or data variables. The fields highlighted with orange background are filled incorrectly and you need to correct their values before you are allowed to proceed. The last page of each wizard displays the part of the configuration that has been created using the wizard and the result of verification of the configuration after the changes are committed into the configuration. If you do not like the values, you can return back in the wizard, correct the respective fields and proceed to the wizard overview again. When you finish the wizard, the created configuration is committed to the main system configuration. You can cancel the wizard at any moment to undo all the changes and return back to the GCML.
The Help button located on each wizard page opens a help window next to the current page that describes all the fields on it. The contents of the help window always correspond to the current page.
All that can be created using wizards can be done also manually using the standard GCML interface. Another option is to create only the core part of the configuration using the wizard and then modify it using the GCML.
There are currently five wizards in the Kernun GUI. They are described in more detail in the corresponding sections of the handbook.
Section 3.1.1, “TCP Proxy to Server in External Network” — enables connection from clients in the internal network to server(s) in the external network (e.g., access to HTTPS servers).
Section 3.1.2, “TCP Proxy to Server in Internal Network” — enables access of external clients to servers in the local network (e.g., a proxy for local IMAP4S mail servers allowing employees to download their mail from home).
OpenVPN Remote Access Server — configures an OpenVPN server that will accept connections from clients in the external network (road warriors).
OpenVPN Network to Network — configures a local OpenVPN peer, which will connect local and remote networks (behind another OpenVPN peer).
IPSec — configures IPSec in the tunnel or transport mode to secure the communication between the specified local and remote networks.
The Kernun GUI implements a configuration locking mechanism, which prevents changes made by different users from being accidentally overwritten. The first user to open the CML configuration in edit mode or the System Manager acquires the configuration lock. Any other user trying to open the configuration at the same time will not be able to acquire the lock. Hence, the user will be presented with the Figure 3.19, “Configuration already locked by other user” dialog presenting the available options. The choice to break the lock must be confirmed explicitly in Figure 3.20, “Break lock confirmation” as a potentially dangerous operation.
The Kernun GUI also prevents the user from modifying the configuration in two different places at once. Therefore opening the System Manager while editing the configuration results in Figure 3.21, “Configuration and System Manager at the same time”.
The Kernun GUI unlocks the configuration automatically when the user closes the window, which has acquired the lock. Possible errors are reported (Figure 3.22, “Configuration unlock failed”).
After the locking phase, the CML configuration editor checks whether the actual contents of the configuration file have been stored in the revision control system (RCS). If not, the user will be asked whether to do so (Figure 3.23, “Commit configuration to RCS confirmation”). The configuration file or the RCS version file may not even be initialized (Figure 3.24, “Initialize RCS confirmation”).
Before commiting the configuration to Kernun, the CML configuration editor checks whether it still owns the lock. If not, it may have either been broken and still locked (Figure 3.25, “Configuration lock broken”) or broken and then unlocked (Figure 3.26, “Configuration not longer locked”).
Besides the GUI (Section 1, “Graphical User Interface”) there is another approach to Kernun UTM services, namely the text-only, or command-line interface (CLI). Its common features as well as its particular tools are described further in this section.
All command-line tools can be used in the interactive mode, which means that they display prompts and expect commands entered by the user. The user can use common features of the command-line interface, known e.g. from the bash(1) tool, namely:
The user can browse through the list of commands entered recently using the cursor keys, change the command text and re-enter it by pressing the <Enter> key.
Using the <Ctrl+R> key combination, the user can invoke the command history searching. When s/he starts typing a part of a command, the CLI displays the most recent command containing this string. When a cursor key is pressed, the search is stopped and the selected command is copied to the command line for further processing.
Most of hotkey bindings known from bash(1) are available in Kernun UTM's CLI tools. For example, <Ctrl+A> skips to the beginning of the line, <Ctrl+E> skips to the end of the line, <Ctrl+U> clears the line, <Ctrl+D> exits the tool etc.
KAT@fw>
apply fw
CMLK-720-E Directory '/usr/local/kernun/conf' contains no SYSTEMKAT@fw>
cml -g
RCS file: /usr/local/kernun/conf/kernun.cml,v ... CKGB-719-N ---- System 'fw' successfully generatedKAT@fw>
<^R>
Searching for: 'ap' > apply fw
The command history is saved when a CLI tool is closed
and made available again the next time it is started.
However, there is a bug in the library used for the line-editing
support and in some cases, the reading of the history file fails
and the tool coredumps.
The recovery is very simple: remove the history file
(~/.kat_hist
for the KAT and
~/.cml_hist
for the CML)
and restart the tool.
One of the most important and most useful features implemented in Kernun UTM's CLI tools is Command Completion and Context Help, or shortly C3H.
The C3H support helps you write correct commands or proper parameters more quickly. The rule of thumb is: “If you don't know what to do now, press the <Tab> key!”. Of course, it does not work absolutely perfectly in all situations, but it works e.g. when selecting a command name, a command argument name (if there is only a defined set of ones), a system name (the apply command in the KAT), a proxy name (application or process management in the KAT, language reference in the CML), a file name (some KAT or CML commands, a file name reference in the CML), a correct operator or delimiter (in the CML language), and many others.
KAT@fw>
<Tab>
apply # apply generated system config files cml # start configuration tool ...KAT@fw>
a<Tab>
KAT@fw>
applyKAT@fw>
apply<Tab>
KAT@fw>
apply fw CMLK-820-N [root] Applying 'SYSTEM-fw', Source: kernun.cml,v 1.1 ... ... System /usr/local/kernun/conf/SYSTEM-fw applied to /.KAT@fw>
start s<Tab>
SMTP SSH SSHDKAT@fw>
start Sm<Tab>
KAT@fw>
start SMTP CMLK-841-N [root] Executing 'start' operation of N=SMTP A= T= ... CMLK-849-N [root] Successful end of 'start' operationKAT@fw>
ps -<Tab>
-a -b -d -p -S -t -TKAT@fw>
ps -p <Tab>
KAT@fw>
ps -p smtp-proxy
The KAT utility is the core management facility for administration of Kernun UTM. It is available directly on Kernun UTM when used locally, can be used when accessing Kernun UTM remotely in the text mode via SSH, and, in fact, most of operations implemented in the GUI (Section 1, “Graphical User Interface”) are realized using the KAT on the remote machine.
The complete command summary is available in kat(8); this section points out only the most important features and shows the typical tasks an administrator can do using the KAT tool.
The KAT can be used in two modes:
In this mode, the program is called without parameters.
It displays its own prompt
KAT@
and
expects commands issued by the user.
In this mode, the KAT accepts also ordinary UNIX shell commands,
so it can be used as a simplified UNIX shell with added commands
for Kernun UTM management.hostname
>
In this mode, the program is called with a KAT command as a parameter; the command is executed and the tool exits. This mode is used for quick execution of a single KAT command without the need of starting the KAT explicitly.
[root@fw ~]#
kat ps
12345 1 Ss 0:00.01 SMTP: parent: ready on 1 address: ...[root@fw ~]#
The management of the Kernun UTM configuration is one of the most important functions provided by the KAT. The configuration tool CML (see Section 2.4, “CML — Configuration Meta Language” below) can be invoked from the KAT simply by typing the command cml. After finishing the configuration, the KAT apply command must be executed to put the changes into effect.
KAT@fw>
cml
CMLI-700-N CLI interactive mode entered RCS file: /usr/local/kernun/conf/kernun.cml,v ... CMLR-710-K File '/usr/local/kernun/conf/kernun.cml' loadedCML>
... work interactively with the CMLCML>
./generate CKGB-719-N ---- System 'fw' successfully generatedCML>
./quit CMLI-709-N CLI interactive mode closedKAT@fw>
apply fw
CMLK-820-N [root] Applying 'SYSTEM-fw', Source: kernun.cml,v 1.1 ...
In the case of a mistake, the administrator can
go through the log of previous revisions,
compare different versions and revoke an older one.
For this purpose, several commands have the -r
option
with a value of revision number, or 0
,
-1
, etc. for previous RCS versions
of the configuration file.
KAT@fw>
rlog
RCS file: kernun.cml,v Working file: kernun.cml head: 1.2 ... ---------------------------- revision 1.1 date: ... Initial revision ---------------------------- ===================================================================KAT@fw>
rcsdiff -r 0 -r 1.1
=================================================================== RCS file: kernun.cml,v retrieving revision 1.2 retrieving revision 1.1 diff -c -r1.2 -r1.1 ...KAT@fw>
cml -r -1
CMLK-825-N [root] Revoking revision 1.1 of '/.../kernun.cml' CMLI-700-N CLI interactive mode entered
Kernun UTM consist of a set of components, and the KAT tool facilitates the work with them. The commands of this group work with the configuration currently applied in the system. Thus, applications that are not configured cannot be operated (e.g. stopped) using these commands. For such tasks, the process management (see Section 2.3.4, “Process management” below) commands need to be used. The commands have several options used to select the proper set of components by type, by name etc., and also by the current state of the component's configuration (e.g. restart only the updated ones).
KAT@fw>
restart
----> Are you sure to do this operation with the whole firewall? (y/[n])
n
KAT@fw>
showapp -n
SMTP smtp-proxy proxy - : UPDATED 50 CMLK-840-I Found 1 component(s)KAT@fw>
restart -n SMTP
CMLK-841-N [root] Executing 'restart' operation of N=SMTP A= T= ... CMLK-849-N [root] Successful end of 'restart' operationKAT@fw>
showapp
... SMTP smtp-proxy proxy - : CURRENT 50 ... CMLK-840-I Found 14 component(s)KAT@fw>
restart -n SMTP
CMLK-841-N [root] Executing 'restart' operation of N=ROUTES A= T= CMLK-740-W Component 'ROUTES' running, skipping... CMLK-712-E No appropriate component foundKAT@fw>
The running applications (components) of Kernun UTM can be operated using the commands of this group. The administrator can monitor a list of application processes and send them signals.
KAT@fw>
ps -b SMTP
12345 1 SMTP: parent: ready on 1 address: [192.168.10.1]:25KAT@fw>
kill -info SMTP *
12345 1 SMTP: parent: ready on 1 address: [192.168.10.1]:25 CMLK-830-N [root] Sending signal 29 to application 'SMTP'(), process: * CMLK-130-N [root] Sending signal 29 to process 12345KAT@fw>
The CML tool is a simple syntax-driven editor of the Kernun UTM configuration. The complete command summary is available in cml(8); this section points out only the most important features and shows the typical configuration tasks.
The user can move within the configuration in the manner very similar to moving across the file system, with the sections of the configuration playing the role of directories. At every moment, the user is in a node of the configuration tree; the “path” to the node is shown in the prompt. To descend into a subnode, simply type the subnode's header with the opening left brace. To ascend, analogously type the closing right brace.
CML>
sy<Tab>
CML>
system<Tab>
<new name> fwCML>
system fw {CML.fw>
routes {CML.fw.routes>
}CML.fw>
In the case of a command error or incompleteness, the CML advises the proper continuation in the prompt text.
CML.fw>
routesCML.fw.routes> [OPEN]
<Tab>
CML.fw.routes> [OPEN]
{CML.fw.routes>
Type an existing section to enter it for editing;
type a new one to append it after the “cursor”.
If a new node should be placed elsewhere,
the cursor position needs to be changed.
Special CML commands are used for such “control” operations.
To be distinguishable from the section and item names,
they start with a special character sequence
(“/
”
or “./
”).
The show command is used to display the content of
a node, the goto command to move the cursor.
CML.fw>
./show
[ 1] ## Host name without domain [ 2] hostname fw; ... --> [25] routes { ... } ... }CML.fw>
./goto = acl
--> acl INTOK { ... }CML.fw>
acl NEW {CML.fw.NEW>
} ... CMLR-592-W .: Section 'NEW' definition not correctCML.fw>
./show . acl
acl INTOK { ... } --> acl NEW { ... }CML.fw>
The above example illustrates also the “online verification” function. After completing the configuration directive, the CML tries to check whether it would be readable by the low-level configuration reader, and prospective errors are displayed.
The show and goto commands can be typed in a shortened version without names, as shown in the following example.
The rules for entering sections apply to items, too. Type a non-existent item to add it, or an existing unrepeatable item to change it. The only difference concerns work with repeatable items. If you type one, a new item will be added; to edit an item, use the edit command. The C3H (Section 2.2, “C3H — Command Completion and Context Help”) may help significantly, if used.
CML.fw>
acl INTOK {
CML.fw.INTOK>
./
acl INTOK { [ 1] from { ^system.INT.ipv4.net }; [ 2] service { DNS, FTP, HTTP, HTTPS, POP3, IMAP4, SMTP, SSH }; --> [ 3] accept; }CML.fw>
1
--> from { ^system.INT.ipv4.net };CML.fw.INTOK>
./edit <Tab>
CML.fw.INTOK>
./edit from { ^system.INT.ipv4.net };CML.fw.INTOK>
./edit from {$INT-ADDR
};CML.fw.INTOK>
from { $EXT-ADDR };
CML.fw.INTOK>
./
acl INTOK { [ 1] from { $INT-ADDR }; --> [ 2] from { $EXT-ADDR }; [ 3] service { DNS, FTP, HTTP, HTTPS, POP3, IMAP4, SMTP, SSH }; [ 4] accept; }
Context-oriented online help is available at every point of the configuration using either C3H (the <Tab> key), or the info command.
CML.fw.INTOK>
./info descr
Repeatable section acl... General ACL definition. Constraints: Exactly one of DENY and ACCEPT must be specified. ... Item SERVICE must be specified.. acl <name> { * from ...; * to ...; ... service ...; }CML.fw.INTOK>
doctype-ident-order <Tab>
doctype-ident-order [for <for>] <order>; Elements: --> [ KEY DIRECTION-SET for = * ] DOCTYPE-IDENT-METHOD-LIST order
The delete command can be used to remove unneeded configuration directives (the last removed node can be restored using the undelete command). The hide command provides a similar function. However, a hidden node remains in the configuration, even though it plays no role in the actual configuration, and can be re-enabled in the future using the unhide command.
CML.fw.INTOK>
./
acl INTOK { [ 1] from { $INT-ADDR }; --> [ 2] from { $EXT-ADDR }; [ 3] service { DNS, FTP, HTTP, HTTPS, POP3, IMAP4, SMTP, SSH }; [ 4] accept; }CML.fw.INTOK>
./delete
--> service { DNS, FTP, HTTP, HTTPS, POP3, IMAP4, SMTP, SSH };CML.fw.INTOK>
./undelete
--> from { $EXT-ADDR };CML.fw.INTOK>
./hide
--> hidden from { $EXT-ADDR };CML.fw.INTOK>
./unhide
--> from { $EXT-ADDR };
The CML has a clipboard, which can be used to copy and move configuration directives. Repeatable sections can be renamed when being pasted.
CML.fw>
./copy
CMLM-751-N 1 node(s) stored to clipboardCML.fw>
./paste
CMLT-570-E Section 'INTOK' already definedCML.fw>
./paste NEW
--> acl NEW { ... }
When the configuration changes are finished, the configuration should be saved. Before actually saving it, the CML verifies the configuration. If the verification fails, the save operation does not proceed. The verification can be skipped (e.g. when saving temporarily), but it is strongly recommended not to do so regularly.
CML.fw>
./save
CKGB-711-N ---- Trying verification of system 'fw'... CFGR-500-E FTP.NEW: Authentication method must be set CFGR-500-E HTTP.NEW: Authentication method must be set CKGB-718-E ---- System 'fw' verification failed CMLM-713-E Saving cancelledCML.fw>
./save !
CMLS-715-N Configuration saved to file '/.../kernun.cml' /.../kernun.cml,v <-- /.../kernun.cml new revision: 1.3; previous revision: 1.2 enter log message, terminated with single '.' or end of file: >>temporary saving
>>.
done CMLT-800-N Configuration identification: kernun.cml,v 1.3 ...
Kernun UTM contains many administrative utilities, which can be invoked from the shell command line. The most important of them, kat(8) and cml(8), have been described in Section 2, “Command Line Interface”. In addition to these two utilities and the standard FreeBSD commands there is a set of Kernun-specific utilities, which are introduced in this section. For detailed description, see the respective reference pages.
The full contents of terminal sessions of the administrator are
logged[16] in the
/var/log/session-USER-DATE-HOST.log.gz
files.
Kernun UTM boot manager configuration tool. It can be used to view and set system partition labels, toggle the bootable flag of system partitions, and select the default system partition for the next boot. Its functionality is provided also by the GUI, on the Kernun systems page of the System Manager.
This program can traverse the file system and create a database file containing information about all files and directories in it. It is able to compare two such databases and display the list of changes to the file system between the times of creation of the databases. The diskdb program is used internally by the Kernun UTM backup, restore, and upgrade tools. It can be used also to detect unexpected changes to vital system files.
Program for management of password files for user authentication. See Section 14.1, “Authentication Methods” for more information.
It selects messages from Kernun UTM's logs using various criteria. Automatically selects the log files that cover the required time interval.
This tool reports bugs in the installed Kernun software and availability of new versions. It is usually run automatically at a regular interval (daily) and the reports are e-mailed to the administrator. See also Section 8, “Audit”.
Utilities for manipulation and viewing of blacklists for http-proxy(8). See Section 18.2, “Blacklists in HTTP Proxy” for instructions on the use of blacklists in the HTTP proxy.
A utility for online monitoring of active proxy sessions. Monitoring is provided also by the GUI on the GKAT Monitor pages for proxies. The configuration of monitoring is described in Section 6.3, “Monitoring of Active Sessions”.
This script is used by the out-of-band authentication to obtain the list of logged-in users from a Samba server. The script should be copied to the Samba server machine and run automatically, as described in Section 14.8, “Out of Band Authentication”.
A tool for SMTP proxy quarantine management. In the ACLs of the smtp-proxy(8) it can be specified that some mail messages are not to be delivered, but stored in the quarantine instead. The quarantine management tool can be used to list the quarantined content, as well as remove or resend messages from the quarantine.
This is the command line interface to system parameter monitoring, as described in Section 6.5, “Monitoring of System Parameters”. It is also used by the GUI to generate graphs displayed on the Graphs page (Figure 3.8, “Graphs page”).
This script processes Kernun UTM logs and generates proxy statistics. The configuration of statistics is described in Section 6.4, “Proxy Statistics Generation”. The statistics can be displayed by the GUI in the window invoked by selecting from the main menu.
This is a program for fast filtration of a Kernun UTM log based on proxy name and message ID matching. It can multiplex selected messages to several output streams for further processing. For example, the process of proxy statistics generation uses switchlog to quickly select statistical messages written by proxies and pass them to sum-* scripts.
A tool for SMTP proxy greylisting database management. Greylisting is one of antispam techniques implemented in Kernun UTM. See Section 16.2, “White-, Grey-, and Blacklists” for more information.
This is the command-line alternative to the GUI System Manager window. It can perform installation, upgrade, backup, and restoring of Kernun UTM. Refer to Chapter 2, Kernun UTM System Management for detailed instructions on how to perform various Kernun system management tasks.
[12] The binary executables are compiled for the version of FreeBSD used by Kernun UTM.
[13] Usually, there are many simultaneous requests on each Kernun UTM proxy, which need to be handled simultaneously. To do that, for every proxy there is one parent process, which only manages its child processes (starts and kills them), while these child processes take care of the traffic. Therefore, the number of the child processes depends on the current traffic.
[14] Kernun UTM uses the PF packet filter (see
pfctl(8) and
pf.conf
(5)), which provides
stateless and stateful packet filtration, NAT, and traffic
shaping.
[15] A session encompasses the communication of a particular proxy process with a single client.
[16] A session is copied into a file using the
screen
(1) command invoked from
/root/.profile
.
In the first section of this chapter, we will introduce the principles of
the Kernun UTM configuration. We will describe the syntax and semantics of the
configuration language and its two different representations. The textual
representation is used in the configuration file (usually
/usr/local/kernun/conf/kernun.cml
) and by the command
line configuration tool
cml(8). The graphical representation is used
by the Kernun GUI. Then we will discuss the initial
configuration that is generated when the newly installed Kernun UTM is booted for
the first time. We will explain the meaning of individual items in this
configuration and how to change them. For information about configuration of
additional functionality not included in the initial configuration, such
as more types of proxies, authentication, antivirus, or antispam
modules, refer to Chapter 5, Advanced features.
Kernun UTM keeps its configuration in a text format called CML
(Configuration Meta Language). The configuration is usually stored in the
/usr/local/kernun/conf/kernun.cml
file. Whenever the
configuration file is saved by the GUI or command line tools, it is also saved
to a RCS (Revision Control System) file called
/usr/local/kernun/conf/kernun.cml,v
. The RCS file contains
the complete history of the configuration, which makes it possible to return to
any past version of the configuration file, show differences between two versions,
and more. The Kernun GUI and
cml(8) provide functions for work with RCS
files. For more advanced operations with RCS, you can use command line system
tools, see rcsintro(7).
Speaking more precisely, there are two levels of configuration: high and low. Usually, the administrator maintains only the high-level configuration file. On the other hand, each Kernun UTM component reads its low-level configuration file upon starting. The Kernun UTM configuration handling tools generate a set of low-level configuration files[17] from the single high-level configuration file. In fact, the high-level configuration is more or less an extension of the low-level configuration of proxies. This concept makes it possible to keep a simple configuration file for each proxy and, at the same time, maintain a single file that describes the whole system in a comfortable way.
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 systemsystem 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];
}
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
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.
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.
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.
Integers — a nonnegative decimal or hexadecimal value; several types with different numbers of bits
Port number — an integer or
a service name from /etc/services
String — a sequence of characters in double quotes. It is possible to omit the quotes for strings that contain only a limited set of characters.
Regular expression — delimited by slashes
Host — an IP address in dotted decimal format enclosed in brackets or a host name
Interface address, network address — an IP address with mask, enclosed in brackets
Socket — a host and a port number
Enumeration — a set of names representing integer constants
List — a sequence of values of a basic type, separated by commas and enclosed in braces. Lists can be nested.
Set — a set of values of a basic type. Syntax is similar to lists with additional features—ranges, exclusion of members, and wildcards. Sets of some types allow special members, e.g., regular expressions in a set of strings or host addresses.
In the GUI, the values must be entered including quoting characters, such as double quotes for strings and brackets for IP addresses.
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.
A newly installed Kernun UTM is configured by an interactive script during
the first boot, as described in Section 5.2, “Initial Configuration”. The initial
configuration is identical to the configuration sample file
/usr/local/kernun/conf/samples/cml/simple.cml
. The
configuration script takes this file and substitutes the values of parameters
entered by the administrator, e.g., IP addresses. The configuration file
simple.cml
is suitable for Kernun UTM with two network
interfaces, one connected to the internal (protected) network and
the other to the external network (the Internet). Kernun UTM
will be configured so that clients that use selected network protocols in
the internal network may access servers in the external network, but access is
denied for other protocols and to clients in the external network. The administrator
can connect to Kernun UTM from the internal network. Although it is possible to
enable proxies for some application protocols using the initial configuration
script, we will assume that the administrator has chosen the more secure way,
i.e., not to enable any proxy initially, but to do so later selectively
using the GUI.
The global level of the initial configuration file is depicted in Figure 4.4, “The global level of the initial configuration file”. It begins with three standard include
files[18].
The first file, samples/include/products.cml
, defines
variables usable as the system.product
item. See Section 3, “Licensing” for more information about Kernun product
specification in the configuration.
The second file, samples/include/crontab.cml
, defines
variables usable as the contents of the system.crontab
and
system.periodic-conf
sections. The third file,
samples/include/root-servers.cml
, contains a list of
root DNS servers. Then, several
shared-dir
and shared-file
sections
specify files that are copied from the configuration directory to their
target locations when the configuration is applied. The configuration
can be edited on one Kernun UTM and then applied remotely to another. In this
case, the shared files and directories are copied from the system where the
configuration is edited to the system where it is applied.
The rest of the sample configuration is the system fw
section. It defines a single Kernun UTM system. The configuration of a standalone
Kernun UTM usually contains only one system
section. If several
alternative configurations are used or several systems are configured from
one place (e.g., in high-availability clusters), more than one
system
sections can be defined.
First, the type of the Kernun product is specified (Figure 4.5, “Various system
-level definitions”) using one of standard product variables
from samples/include/products.cml
. The
product specification controls which components can be configured. During
the application of the configuration, a check is made that the product
installed on the target system matches the specification. See also Section 3, “Licensing” for a more detailed explanation of the product
specification in the configuration. The
system
parameters start with host and domain names.
The configuration of actions executed periodically by the
cron
(8) daemon and by the
periodic
(8) command is
defined in the sections crontab
and
periodic-conf
. These sections are filled in by
the application of variables defined in crontab.cml
.
The following part of the system
section, displayed
in Figure 4.6, “Definitions of network interfaces”, contains the
settings of two network interfaces, connected to the internal
(INT
) and external (EXT
) network, respectively.
Two values are specified for each interface: the name of the network interface
device as used by the operating system (item dev
), and
the IP address with the network mask (item ipv4
). Note that
interface
is a repeatable section, so it can occur more
than twice. For example, a demilitarized zone network can be connected
via a third interface in a more complex network topology.
The system
section then defines further network-related
parameters, see Figure 4.7, “Definitions of various network parameters”. Domain name
resolution parameters are set in the section resolver
. In
the initial configuration, the only item in this section selects a DNS
server. There may be several resolver
sections. The
section that is used globally for resolutions performed by Kernun UTM components
is chosen by use-resolver
. Each proxy can use the global
resolver, or the resolver setting can be overridden for the proxy using a
use-resolver
section local to the proxy configuration
section. In the initial configuration, the global resolver is shared by
all proxies. Note that the resolver is used for address resolution performed
by Kernun UTM itself. If clients in the internal network should have access
to the DNS, which is usually the case, either a DNS server can be configured
in the internal network, or the clients can resolve via
a Kernun UTM dns-proxy.
As the Kernun UTM dns-proxy does not cache responses
obtained from DNS servers in the external network, it is inefficient
to configure clients in the internal network to resolve directly via the
proxy. The recommended configuration is to create a caching-only DNS
server in the internal network and to set dns-proxy
as its forwarder. The internal DNS server can be created in Kernun UTM,
by adding section system.nameserver
to the configuration.
The routes
subsection defines static routes. In the
sample configuration, only the default
route to a router
in the external network is specified. The use-services
item
selects a shared-file
[19] that will be copied into
/etc/services
. It defines port numbers assigned to
various network services. The last network-related parameter is a list of
root DNS servers, section ns-list
. It is set by the
application of the section variable ROOT-SERVERS
defined
in the included file root-servers.cml
.
Kernun UTM is usually administered remotely via the network. The
administrator connects to Kernun UTM using SSH, either directly in order to
obtain a shell command line, or via the GUI, which uses SSH internally.
Therefore, an SSH server for administrator's access should be defined in the
configuration. The initial configuration contains a single SSH server
section called ssh-server SSHD
, see Figure 4.8, “An SSH server for administrative access”. It listens on the standard
SSH port 22 on the internal network interface only. Hence the administrator
can connect to the Kernun UTM from the internal network only. If access from the
external network is desired, the SSH server must be reconfigured to listen
on the external interface as well.
The server allows password-based authentication of non-root users. It
is used for the initial download of the root's SSH key using the special
keygen
account, as described in
Section 5.2, “Initial Configuration”. The root can log in to Kernun UTM with the SSH
keys listed in section ssh-keys
. By default, this section
contains the key generated by the initial configuration process and
accessible via the keygen
account.
Kernun UTM generates some e-mail messages locally, mainly as the
output of periodic actions executed by
cron
(8). These messages
are delivered to the address provided in the admin
item by
the mail server configured in the local-mailer
section, see
Figure 4.9, “The server for handling locally-originated mail”. The default local mailer
configuration refers to the standard file master.cf
selected by a global shared-file
parameter.
The server that handles local mail is Postfix-configured so that it
does not listen for any incoming network connections. It handles only mail
sent by the mail
(1) command. The
administrator's e-mail address is set as an alias for the root
user in
/etc/aliases
.
Kernun UTM utilizes both the packet filter and application proxy firewalling technologies. The use of application proxies is preferred, because it provides a higher level of security and finer control of the network traffic. The network traffic is therefore passed through Kernun UTM mainly via proxies that handle individual application protocols.
It is possible to enable proxies for several frequently used network protocols in the initial configuration. However, in order to maintain better control over the network traffic it is advisable not to enable any proxy when the initial configuration script creates the configuration of a newly installed Kernun UTM, but rather to selectively enable and configure the proxies later, when the administrator connects to Kernun UTM via the GUI. The part of the configuration that is directly related to proxies is shown in Figure 4.10, “Hidden proxies and a global ACL”. Note that all proxy sections are hidden, so that proxy parameters are defined, but have no effect and the hidden proxies are not started[20].
Proxies can be non-transparent or transparent, see
Section 7, “Networking in Proxies” for more details. By
default, all proxies in the initial configuration except
dns-proxy
are configured as transparent, which enables
the use of clients in the internal network without any reconfiguration.
Access control in proxies is driven by access control lists (ACLs). Each proxy has one or more layers (phases) of ACLs. Individual phases are consulted at specific moments during the processing of the network communication.
For example, in http-proxy,
there are three phases of ACLs: the session-acl
sections
are consulted when a new connection from a client is accepted. They make
early decisions based on values, such as the client's IP address. The second
phase, request-acl
, is checked after the HTTP request is
received from the client. Its actions can depend e.g. on the request URI
or on the values of some request headers. The third phase,
doc-acl
, is applied when the HTTP reply headers are received.
On the other hand, tcp-proxy, which handles only the TCP
data stream without deeper understanding, has a single ACL phase,
session-acl
.
The ACLs that belong to one phase are tested sequentially. The input
conditions of every ACL section are evaluated and the first ACL, for which all
the conditions are true, is selected. The chosen ACL can accept
or deny
the session, thus effectively allowing it to continue
or terminating it. Various parameters that affect further
handling of the session by the proxy can be set by the ACL. If no matching
ACL is found, the session is terminated.
ACLs can be located at two different places in the configuration.
Global ACLs defined in the system
section belong to the
first phase (session-acl
). Each global ACL has a
service
item containing the list of proxies, to which
it is applicable. The initial configuration contains one global
acl INTOK
that applies to all proxies and accepts
sessions originated from clients in the internal network, as can be seen
in Figure 4.10, “Hidden proxies and a global ACL”. Note that sessions initiated by
clients in the external network do not match the from
condition of acl INTOK
and there is
no other ACL that could match, hence these sessions are
denied[21]. Local ACLs are defined in the configuration
sections of individual proxies. Each such ACL applies only to the proxy,
in which it is defined. Phase one (session-acl
) ACLs in
a proxy are merged with the global ACLs that have this proxy in their
service
lists. For each session-acl
in
a proxy there must be a global ACL with the same name.
The first-phase ACLs are checked in the order defined for the
global ACLs. The per-proxy session-acl
sections can
add proxy-specific items to the ACLs, but do not change the order of ACLs.
In a typical scenario, the DNS proxy provides the domain name
resolution service for clients behind Kernun UTM. It is defined by its
particular dns-proxy
section which resides in the
system
section. In this example, the
listen-on
section specifies that the DNS proxy will listen
non-transparently on the internal interface on port 53. This means that
clients from the internal network must set the IP address of Kernun UTM's
internal interface as their DNS server in order to use this proxy. The
chroot-dir
item specifies that the process will be
chrooted to the directory
/usr/local/kernun/root
, see chroot(8).
The requests-table-size
and
sockets-table-size
items are obligatory for
dns-proxy
. Every domain name resolution request is stored
in a table that contains all the necessary information. The size of this
table is specified by the requests-table-size
item. It is
recommended to reserve slightly more items than the estimated number of
parallel requests. Besides the number of requests, the number of simultaneously
opened sockets is monitored as well. This maximum must be specified by the
sockets-table-size
item. See dns-proxy(5) for details.
The DNS proxy is not designed to be used as a name server. The typical scenario is that all clients ask another server in the internal network and this server queries the proxy (if needed) and caches the answers. See Section 3, “Caching Name Server” for details.
dns-proxy
needs at least one
request-acl
section providing details on what
traffic is permitted or not, and the way it should be dealt with. In
this example, the accept
item specifies that
request-acl RESOLVE describes an
accepting request-acl. This means that this section defines
the positive case — the conditions, under which the request is accepted.
Then query * resolve ROOT-SERVERS directs the proxy to use the
ROOT-SERVERS
to resolve all the requests. Further on, it is
defined that all the respective replies from the
ROOT-SERVERS
are permitted to be returned to the clients.
The ROOT-SERVERS
item is defined in the sample file
samples/include/root-servers.cml
, which is included
in the configuration using the include
keyword. This file contains
the definition of the $ROOT-SERVERS
variable, which defines the
ns-list
section — a list of DNS root servers.
In order to apply that definition, it is necessary to
include the $ROOT-SERVERS
keyword in the configuration.
Finally, dns-proxy
must be referenced by at least one
system ACL. In this example, the access to the DNS proxy is granted for all
clients from the internal network.
http-proxy
is the proxy daemon for HyperText
Transfer Protocol (RFCs 1945, 2616). It supports version 0.9, 1.0 and 1.1
HTTP clients and version 1.0 and 1.1 HTTP servers. The proxy also supports
secure communication via the SSL/TLS protocols.
In the example depicted in Figure 4.12, “HTTP Proxy”,
http-proxy
is configured to listen on the internal
network interface on port 80 in the transparent
mode, and
on port 3128 in the non-transparent
mode; see Section 2.5, “Application Proxies and ACLs” for details about transparency.
Again, the proxy is configured by chroot-dir
to be chrooted
into /usr/local/kernun/root/
, see chroot(8).
The document-root
item defines the root directory
of the error document set. In this example, it refers to
DOCROOT
— the shared-dir
section
defined at system
is a list of path
items designating directories for further use. Note that the relative path
(i.e., one that does not start with “/”) is in fact relative
to /usr/local/kernun/conf.
http-proxy
uses three-phase ACLs.
session-acl
is checked once for each client
connection. It permits or denies client access and sets some
connection parameters.
request-acl
is checked for each HTTP
request after the request headers are received from the client,
but before anything is sent to the server. It decides whether
the request is permitted or denied, and it can also set some request
parameters. Note that there can be several requests per connection
if persistent connections are used.
doc-acl
is checked for each HTTP request
after the response headers are received from the server, but before
the response is sent to client.
The session-acl
section of any proxy is always based on
an acl
defined at the system
level. The items that are common for all types of proxies are defined
in the common part at the system
level. The items
that are specific for each proxy are defined within the particular
proxy's section
[22].
In this simple example, http-proxy
is configured not to
use authentication (auth none
). You might have noticed
that we did not specify the accept
item in
session-acl INTOK
, nor did we restrict
the IP range of clients that can use http-proxy
.
The reason is that we only specify the acl
section INTOK
that we defined earlier. In fact,
FIREWALL.HTTP.INTOK
is a local copy of
FIREWALL.INTOK
, and we have particularized this local copy.
Finally, request-acl
and doc-acl
are
configured to accept any request or document, respectively. However,
CONNECT method requests are limited to port 443 to allow SSL/TLS
connections only.
See dns-proxy(5) for details.
ftp-proxy
provides the proxy service for
File Transfer Protocol (RFC 959) and its extensions. For crucial commands,
it behaves like a server for the client and vice versa, with full syntax
and semantics verification. Commands that have no impact on the session state
are only recognized and simply forwarded to server.
The simple configuration of ftp-proxy
is quite
similar to the simple configuration of http-proxy
(see Section 2.7, “HTTP Proxy”). In the example at Figure 4.13, “FTP proxy”, it is configured to
listen on the internal network interface on port 21 in the
transparent
mode and chrooted into
/usr/local/kernun/root/
(see
chroot(8)). No restrictions are configured,
so everyone (from the internal network — as specified
in the INTOK
acl) is allowed to use the
ftp-proxy
. As usual, the ftp-proxy FTP
must be present in some ACL; in this case, it is referenced
in the service
list in the INTOK
definition.
ftp-proxy
uses three-phase ACLs.
session-acl
is checked once for each client
connection. It permits or denies client access and sets some
connection parameters.
command-acl
decides how to handle particular
protocol commands depending on client parameters, destination server,
proxy-user, etc. Each command is checked against command
items in the order of their appearance in the cfg file,
and the first matching one is used. If no one matches, the command
is denied.
doc-acl
is checked for each HTTP request
after the response headers are received from the server, but before
the response is sent to the client. It decides how to handle particular
files transferred via the proxy, depending on the file name, type and transfer
direction.
For more information about ftp-proxy
, see
ftp-proxy(8) and ftp-proxy(5).
Both HTTPS and SSH protocols are handled by the generic
tcp-proxy
, because they use encrypted communication and
Kernun UTM therefore cannot understand the protocol data. The configurations
of tcp-proxy HTTPS
and
tcp-proxy SSH
are almost identical, see Figure 4.14, “Proxies HTTPS
and SSH
”. They differ only by the port they
listen on—the port number is 443 for HTTPS
and
22
for SSH.
Both proxies listen for clients connecting transparently via the
internal interface of Kernun UTM (section listen-on
).
The proxies run with identity of proxy-user kernun
and are chrooted into directory
/usr/local/kernun/root
. They do not define any ACL,
therefore the global acl INTOK
applies to them
unmodified.
smtp-proxy
is the proxy daemon for Simple
Mail Transfer Protocol (RFCs 2821, 2822, 2045 etc.). The SMTP protocol
is used to send electronic mail from clients to mail servers as well
as between mail servers. The task of
smtp-proxy
is to apply a security policy, check the incoming
mail for correctness and then use some smtp-forwarder
to queue and distribute mail. In other words, there must be an SMTP
server (other than Kernun UTM) to deliver e-mail.
The easiest way is to employ the common UNIX postfix
daemon for this task. The configuration can be included in the
Kernun UTM configuration and the proper configuration
files for postfix are then generated automatically.
In the typical scenario depicted in Figure 4.15, “SMTP
Proxy System Sections and Forward Agent”, postfix is
configured to listen at Kernun UTM's loopback address and forward
e-mails send to it by smtp-proxy
, which listens
at Kernun UTM's internal address. Note that under this settings mail
does not arrive from the Internet to the internal network. We will
explain an alternative scenario in the second part of this chapter.
The postfix program is configured from
Kernun UTM by the agent
section in smtp-forwarder
. It must contain a
master-cf
item — an anchor to
shared-file
that contains the Postfix
master.cf
configuration file. There is a sample
in samples/shared/postfix-master.cf
. There also
must be specified at least one server
item in
smtp-forwarder
— an address, to which the
mail is to be sent.
The proxy itself listens transparently on Kernun UTM
internal address port 25 (as defined by the listen-on
section). Besides the common chroot-dir
item there must also be
present a postmaster
item, which defines the postmaster e-mail address,
and a mail-pool
item, which defines the directory used as temporary
storage for incoming mails.
smtp-proxy
uses four types of ACLs on three
levels:
session-acl
— (level 1) is
checked once for each client connection. It either defines the general
protocol behavior, or rejects the connection. In addition to the generic
ACL conditions and actions, some smtp-proxy-specific conditions and
parameters can be set (see smtp-proxy(5)).
delivery-acl
— (level 2) is
checked once for each mail recipient. It either defines the response to
the RCPT TO command, i.e. the way of delivery, or rejects the particular
addressee.
mail-acl
— (level 3M) is
checked once for each mail recipient. Its rules control whether the
forwarding of the mail to the particular recipient should be rejected or
accepted.
doc-acl
— (level 3D) is
checked once for each recipient and document (MIME part) and
defines the document processing mode (e.g. filtering, replacing
etc.).
The example in Figure 4.16, “SMTP
Proxy ACLs” shows three
different delivery-acl
items. The first one
(BAD-SENDER
) refuses mail with incorrect senders
(i.e., the MAIL FROM argument), the second one (BAD-RCPT
)
rejects mail with incorrect recipients and the last one
(OTHER
) accepts all other mail (that is, mail that
matches neither of the preceding delivery-acls). The
mail-acl
and doc-acl
items are configured
to accept all e-mails.
During the delivery-acl
phase, the correctness of all the commands
(HELO, MAIL FROM and
RCPT TO) and their arguments is checked
and the proper decision is made.
When resolving domain names, the current
resolver
section setting is applied.
It means that the search
list (if present)
is tried when some resolution fails.
If this search-list contains a domain that has
the *.domain
MX record set,
every resolution
succeeds and errors such as unknown-perm
never occur. This is probably not the desired behaviour.
You can solve this problem by defining a new
resolver
section
without the search
item
and then using this resolver
in the particular smtp-proxy only
by means of a use-resolver
item
in the proxy's configuration section.
smtp-proxy
checks the correctness of the mail
headers and MIME structure. Mail that does not conform to the RFCs is rejected.
However, many clients do not respect RFCs and if the security policy
allows sending of such e-mails, you can instruct the proxy to correct or even
pass them. We therefore add a mail-filter
item, which handles
the most common cases, to the session-acl
item. For details on
the particular entries, see
smtp-proxy(8) and
mod-mail-doc(5).
In the example depicted in Figure 4.17, “SMTP
Proxy Mail Filter”,
a reference to mail-filter
is added into
session-acl
of smtp-proxy
. The
mail-filter
itself is configured to:
accept-8bit-header
— accept non-US-ASCII
characters in mail or MIME document headers;
correct-8bit-body
— accept and correct
missing declaration of the use of non-US-ASCII characters in mail bodies
or MIME documents;
correct-bad-char
— accept and correct
the use of NUL char (0x00) or bare CR (not followed by LF) in mail
bodies or MIME documents.
correct-boundary
— accept and correct
the use of incorrect characters in MIME multipart boundaries.
correct-quoting
— accept and correct
characters in SMTP and MIME headers that should be included in quotes,
but are not.
stamp-filter
— remove 'Received:'
headers that contain local-dependent information from mails.
The number of the removed lines is counted and added to the e-mail
as a special header X-Kernun-Loop-Info.
stamp-limit 30
— define the maximum
number of Received-headers in mail. This check prevents mail loops.
treat-binary-as-8bit
— accept messages
that use BINARY Content-Transfer-Encoding and treat them as 8BIT,
even though it makes no sense in the current SMTP.
treat-rfc822-as-text
— handle the included
documents as text.
There can be a mail server in the internal network. This type of mail server usually serves as the SMTP forwarder for the internal network (that is, it forwards mail addressed outside the local network, and stores mail addressed to the internal network).
From Kernun UTM's point of view, the internal SMTP server
sends some e-mails[23]
to the internal interface of smtp-proxy
.
Such mail is already handled by smtp-proxy
configured
sooner in this chapter. What is new is that there can be mail from the
external network addressed to someone in the local network (precisely
speaking, to the mail server in the internal network). Kernun UTM should
therefore listen on the external interface, accept mail addressed
to the internal network and forward it to the internal mail server.
It is possible either to create another SMTP server, or to extend the
existing one. The example in Figure 4.18, “SMTP
Proxy Mail Sever in the Internal
Network” shows the latter option:
Unlike other screenshots, the figure shows only the
sections and items added to the configuration of the sample
smtp-proxy
. A new smtp forwarder INTERNAL
,
which forwards mails to the internal network
(to the server 192.168.1.25), has been added. Then there is
smpt-proxy SMTP
configured to listen in the non-transparent
mode on the external interface on port 25. Furthermore, there is new
delivery-acl TO-INTERNAL
, which accepts only e-mails for
the selected domains (example.com) and delivers them via
smtp-forwarder INTERNAL
. Note that the order of the
access control lists of the same type (delivery-acl
in
this case) is significant. When Kernun UTM looks
for the delivery-acl
to use, it follows the first matching
one and then stops the search. The delivery-acl TO-INTERNAL
section must be therefore created between the BAD-RCPT
and
OTHER
sections configured earlier. The delivery-acl
OTHER
section has slightly changed; it now accepts only mail from the
internal network. Note that from { ^system.INT.ipv4.net
};
must be located at the beginning of the ACL, so that the entry
conditions are kept before the action (accept
in this
case). Finally, the original delivery-acl OTHER
was
restricted to accept mail from the external network (which was not
necessary until the second listen-on
item was added).
The IMAP4 and POP3 protocols are used to access electronic mail that is stored on mail servers. Both make it possible for client e-mail programs to download mail and present it to the user. Unlike POP3, IMAP4 enables them also to upload mail to the mailbox on the IMAP4 server.
imap4-proxy
is the proxy daemon for Internet
Message Access Protocol version 4rev1 (IMAP4rev1), as defined by
RFC 3501. The proxy supports secure communication via the SSL/TLS
protocols.
The proxy is configured in the imap4
section.
In the sample configuration depicted in Figure 4.19, “IMAP4
Proxy”,
the proxy-user
and chroot-dir
items
define the operating-system-level user, under which the proxy should run,
and the directory, to which it should be chrooted. The proxy listens
transparently for requests at Kernun UTM's internal address at port 143 and,
again, the proxy must be referenced by at least one ACL in the
system
section.
The mail-pool
item defines the directory,
in which e-mails are temporarily stored by the proxy. Note that this
directory must be created manually by the administrator and that it
must be writable by proxy-user
. Note also that the
directory can be the shared by smtp-proxy
,
imap4-proxy
and pop3-proxy
(or by
any combination of them).
imap4-proxy
uses three-phase ACLs. The first
phase, session-acl
, is checked once for each client
connection. It permits or denies client access and sets some connection
parameters. The second phase, command-acl
, is also
checked once for each connection, but it can be selected according to
the client certificate if SSL/TLS is enabled by
session-acl
. Various parameters can be set in
command-acl
, e.g., the permitted sets of IMAP4 commands
and capabilities, timeouts, SSL/TLS on the server connection.
The third-phase ACLs are used only if mail processing is enabled in
command-acl
. Two types of these ACLs exist.
mail-acl
is checked once for each transferred e-mail.
It defines the rules of the acceptance or rejection of the mail according
to its content and antivirus/antispam test results. doc-acl
is checked once for each document (MIME part) of a mail. It defines
document processing, e.g., filtration or replacement by a fixed file.
See mod-mail-doc
(5).
In this example, command-acl COMMOK
defines
that no mail scanning is to be performed on either downloaded or
uploaded e-mails. The item no-mail-scanning
means,
in this context, that the mail is not even opened. Were the
no-mail-scanning
item absent, the mail would be
stored and unfolded to headers and attachments, etc., and various tests
could be performed on any part. This alternative will be discussed in
Section 15, “Antivirus Checking of Data” and Section 16, “Antispam Processing of E-mail”.
pop3-proxy
is the proxy daemon for Post
Office Protocol version 3 (RFCs 1939, 2449, 1734). The proxy supports
secure communication via the SSL/TLS protocols.
The proxy is configured in the pop3
section.
In the sample configuration depicted in Figure 4.20, “POP3
Proxy”,
the proxy-user
and chroot-dir
items
define the operating-system-level user, under which the proxy should run,
and the directory, in which it should be chrooted. The proxy listens
transparently for requests at Kernun UTM's internal address at port 110
and, again, the proxy must be referenced by at least one ACL in the
system
section.
The mail-pool
item defines the directory,
in which the mails are temporarily stored by the proxy. Note that this
directory must be created manually by the administrator and that it
must be writable by proxy-user
. Note also that the
directory can be the shared by smtp-proxy
,
imap4-proxy
and pop3-proxy
(or by
any combination of them).
pop3-proxy
uses three-phase ACLs. The first phase,
session-acl
, is checked once for each client connection.
It permits or denies client access and sets some connection parameters.
The second phase, command-acl
, is also checked once for
each connection, but it can be selected according to the client
certificate if SSL/TLS is enabled by session-acl
.
Various parameters can be set in command-acl
, e.g.,
the permitted sets of POP3 commands and capabilities, timeouts, SSL/TLS on
the server connection. The third-phase ACLs are used only if mail
processing is enabled in command-acl
. Two types of
these ACLs exist. mail-acl
is checked once for each mail
transferred from the server to the client. It defines rules of the acceptance
or rejection of the mail according to its content and antivirus/antispam
test results. doc-acl
is checked once for each document
(MIME part) of a mail. It defines document processing, e.g., filtration
or replacement by a fixed file. See mod-mail-doc(5).
In this example, the no-mail-scanning
item in
command-acl COMMOK
defines that no mail scanning is to
be performed. In this context, as the POP3 protocol is intended only for
download of e-mails, it means that the downloaded mail is not even opened.
Were the no-mail-scanning
item absent, the mail
would be stored and unfolded to headers and attachments, etc., and
various tests could be performed on any part. This alternative will be
discussed in Section 15, “Antivirus Checking of Data” and Section 16, “Antispam Processing of E-mail”.
In the previous section we described the initial configuration as generated by the configuration script during the first boot after the installation of Kernun UTM. In this section we will demonstrate how to modify the configuration. We will make the following changes:
enable dns-proxy;
enable http-proxy;
restrict HTTP to a subset of the internal network;
allow only the HTTP method
GET
.
First of all, we want to permit the HTTP traffic. As the transparent mode of the proxy is used, the clients connect directly to servers. Therefore, the clients must be able to resolve server addresses, which is why we need to enable DNS as well. The following steps produce a working configuration with the required changes.
Start the GUI and connect to Kernun UTM, as described in Section 1.1, “Kernun GUI Launcher”. If Kernun UTM is running the unmodified initial configuration, you will see the GKAT window with only a few components running, as depicted in Figure 4.21, “The Kernun UTM running the initial configuration”.
Select
in the menu to open the configuration.In the left-hand part of the configuration window, look for a line
containing hidden dns-proxy DNS
. Select the line
with the left mouse button, then click the right mouse button to open the
context menu and select . The
line will change to dns-proxy DNS
.
Repeat the same action for the line containing
hidden http-proxy HTTP
.
Select the line acl INTOK
and then
select
from the context menu. In the Create Item/Section dialog,
select acl
as the type of the section and set the section's
name, for example NET1_DENY
. You have created a new global
ACL.
Now select the newly created ACL and use from
, service
, and
deny
items.
Select the from
item. In the right-hand part of
the configuration window you can see the current value of the item, which is the
empty set. Add a new value to the set by clicking on the button . Enter the address (with mask) of the subnet that is to be
denied, for example, [192.168.10.128/25]
.
Select the service
item. Using , add HTTP
to the list.
Now we have the new ACL denying access from a subnetwork
ready. However, as the ACLs are checked in sequence and the first matching is used,
we must exchange our two ACLs. This can be done in several ways. One
possibility is to select acl NET1_DENY
and click on
in its context menu.
Finally, we want to restrict the HTTP
proxy to allow
only the GET
method. Open the http-proxy HTTP
section by clicking on the small plus sign. Select the
request-acl ALL2
line.
Add a request-method { GET }
item
to this ACL in the same way as when you modified values in acl NET1_DENY
.
The configuration should now correspond to Figure 4.22, “The modified configuration”.
Save, generate, and apply the configuration by selecting Commit configuration window is displayed, as depicted in Figure 3.17, “Configuration commit dialog”.
. TheClick
to enter a RCS log message with a description of the change you have made.The configuration is saved to Kernun UTM, recorded as a new version in the RCS file, the low-level configuration files are generated and applied (copied to the locations where Kernun UTM components will look for them).
The Synchronize system with
configuration window is displayed, as depicted in Figure 4.23, “Activation of the new configuration”. It informs you that components DNS
and HTTP
have been reconfigured and need to be started for
the new configuration to take effect.
Now you can switch to the Log page of the Proxies node in the GKAT window. If you start a Web browser on a machine in the internal network and try to access a Web server in the external network, you will see proxy log messages appearing.
The process of adding new TCP proxies can be simplified even more using two wizards (for general information on wizards, see Section 1.4.6, “Configuration Wizards”). When creating a TCP proxy, you first need to decide whether you want to enable the connection of clients in the internal network to a server in the external network (the server must have a public IP address and the clients connect to this address), or whether you have a server in the internal network (with a private IP address) and clients from the external network will connect to Kernun UTM, which will forward them to the server. The Kernun GUI provides one wizard for each of the alternatives. The following subsections describe the creation of sample proxies in both cases.
As we have said before, a proxy needs to be created in order to allow
communication from the internal to the external network. The proxy should be
transparent, which means that clients in the local network would not be aware of the fact
that they do not connect directly to the server. The TCP proxy to external network wizard
will lead you through the creation of the transparent TCP proxy.
In this example, we will configure the transparent tcp-proxy
to allow some privileged local clients to shop on www.ebay.com.
First of all, you need to delete or hide the
tcp-proxy HTTPS
from the initial configuration,
because it would collide with the proxy we want to create. Then
select to start the wizard.
On the first page, you are asked to choose the
tcp-proxy
section name, the interface
to the network that contains the clients and the port of the service that is
supposed to use the proxy. In our example, we choose the INT
interface and the 443
port, as shown in
Figure 4.25, “TCP proxy general network settings”.
On the second page, you define the clients in the internal network
that are allowed to connect using this proxy and the servers in the external
network, to which the clients may connect, in the form of either IP addresses
or host names. If you already have an appropriate ACL created in the
configuration, you may select the Use existing accepting ACL
radio button and then choose the ACL to be used for this proxy. As we do not
have any usable ACL in the system, however, we choose to create a new
one, and set its name and the IP address of the privileged client that is
allowed to log in to the ebay.com server. The configuration is
depicted in Figure 4.26, “TCP proxy ACL settings”.
The third page contains more advanced connection settings, including several connection timeouts and a limit of the number of proxy children. If you do not fill in any of these fields, the corresponding item will not be included in the resulting configuration. Since we know that there will be no problems with the traffic load, we leave all the limits empty. In order to get more detailed traffic examination outputs, we choose to monitor the proxy (which i.a. produces graphs of the proxy usage, see Figure 3.8, “Graphs page”) and to generate proxy statistics (see Figure 5.26, “Statistics browser window”). The filled page is shown in Figure 4.27, “TCP proxy miscellaneous settings”.
Finally, the last page (Figure 4.28, “TCP proxy recapitulation”) shows
the recapitulation of the wizard settings in the form of the text configuration
that is to be added to the main system configuration. There is also the
outcome of system verification of the configuration with the created proxy.
You can click Finish
to commit the proxy into the configuration,
Back
to return and modify the wizard settings, or
Cancel
to close the wizard and discard all the settings.
Besides the above-mentioned wizard for a transparent proxy,
the Kernun GUI also provides a wizard for a non-transparent tcp-proxy
.
In this case, clients connect to to a specified port at Kernun UTM, which
forwards the communication to a server behind it. This is useful when
creating servers without a public IP address in the internal network (which
is a recommended practice). We will create an IMAP4S
proxy that will
allow employees at home connect to a mail server in the internal company network behind
Kernun UTM and read their mail. The wizard is very similar to the
Section 3.1.1, “TCP Proxy to Server in External Network” wizard; actually, only the second page
differs.
On the first page, we choose the proxy name, the interface on which
it is supposed to listen (this time, it is the external interface
EXT
) and the port for secure IMAP4, 993
.
On the second page, we similarly define the ACL, with a slight difference
in the process of its creation. We only define restrictions concerning
clients, as they always connect to Kernun UTM.
After choosing the ACL, we need to specify where to plug the
communication in (in our case the IP address of the IMAP4S server) and the port
it listens on. This is specified in a single field as
[192.168.10.7] : 993
. Furthermore, we want the server to receive
packets with the original client's IP address (rather than that of Kernun UTM), so we
check the Client source address
check box. The second
page is shown in Figure 4.29, “Non-transparent TCP proxy ACL settings”.
The last two pages are the same as in the transparent proxy wizard.
[17] They are mainly
proxy configuration files and some system configuration files, e.g.,
/etc/rc.conf
.
[18] All relative paths here are relative to the
configuration directory
/usr/local/kernun/conf
.
[19] Sections
shared-file
are created at the global level of the
configuration file.
[20] For the present, you can ignore the section
smtp-forwarder
. It will be discussed later, together with
the smtp-proxy.
[21] In fact, such sessions do not even begin regardless of ACLs, because the proxies are configured to listen on the internal interface only.
[22] Moreover, some items can be configured at both levels. The proxy-specific one takes precedence in that case.
[23] In particular, mail sent from the internal network addressed to someone outside the local network.
Table of Contents
This chapter covers the configuration of various advanced features of Kernun UTM. You can find here instructions on how to configure each feature, along with the description of the most important configuration parameters; the remaining ones are listed in the relevant parts of the reference documentation. It is assumed that you know the principles of the Kernun UTM configuration and how to use the Kernun GUI. If not, consult Chapter 4, Configuration Basics and Section 1, “Graphical User Interface”.
In addition to the application layer control, Kernun UTM includes a TCP/IP packet filter with advanced features, such as stateful filtering, network address translation (NAT), traffic normalization, traffic shaping, OS fingerprinting etc. This section offers a general overview of the packet filter's capabilities, as well as examples of a few typical packet filter configurations[24].
It is very important to consider the way packets are handled in Kernun UTM. When combining packet filter rules, traffic shaping and application proxy access control lists, we need to take into account the order, in which network traffic is processed by individual components of the system.
Upon entering the system, network packets get inspected by the packet filter at first. The packet filter itself consists of a number of components. The order, in which these components handle network traffic, is always the same:
State engine
Traffic normalization engine
Traffic shaping / queuing engine
Network address translation engine
Packet filtering engine
This order applies to both incoming and outgoing traffic, i.e. it is the same whether the packet is entering or leaving the system. As regards incoming packets, application proxies may take control only after they are processed by all the packet filter engines. On the other hand, traffic originated at application proxies goes through packet filter engines and then leaves the system for the network.
Network address translation rules always create states. If an initial packet of a connection is translated by an NAT rule and then passed by the packet filter, it is automatically also passed on its way back, thanks to the created state.
As for packet filtering, states are created only if the rules explicitly
specify so using the keep-state
modifier. However, if the
raw
packet filter rule is specified, the state is kept by default;
if you do not want to keep the state in such a case, you need to add
no state
to the raw rule.
The packet filtering rules are defined in the
system.packet-filter
section. The following list
introduces its items and subsections:
set-option
— a repeatable item
containing packet filter specific options, see
pf.conf(5);
timeouts
— a non-repeatable section defining
various filter timeouts;
altq
— the specification of traffic
shaping rules, which assign the traffic to individual queues defined in the
system.pf-queue
sections;
scrub-acl
— the traffic normalization
rules; by default, all incoming traffic is normalized and IP fragments are
reassembled;
rdr-acl
— redirection NAT rules,
applied to incoming traffic, change the destination address;
nat-acl
— mapping NAT rules,
applied to outgoing traffic, modify the source address;
binat-acl
— bidirectional NAT
rules combine both redirection and mapping;
filter-acl
— packet filtering,
either unidirectional or bidirectional rules (both stateless and stateful);
load-anchor
— loading of rule subsets
from files.
In the following sections we go through several typical
configuration examples that involve capabilities of Kernun UTM's packet filter.
We will start with the initial configuration as described in Section 2, “The Initial Configuration”. The resulting packet filter configurations
can be found in the configuration sample file packet-filter.cml
in the
/usr/local/kernun/conf/samples/cml
directory.
Packet filtering basically means controlling (either passing, or blocking) network traffic based on basic TCP/IP attributes, including the source and destination IP addresses and ports, the network interface the packet emerges on, its direction (inbound or outbound), and a few other protocol-specific characteristics.
Even if the traffic is passed by the packet filter, there must exist an application proxy with an ACL permitting the communication; otherwise, it is denied. In other words, Kernun UTM does not forward network packets, but instead, it attempts to transparently grab them and process them with application proxies. However, the mechanism of traffic grabbing by application proxies can be bypassed, as described in Section 1.4, “Selective Packet Forwarding”.
By default, the packet filter rules allow all traffic, but there is only a limited set of application proxies in the initial configuration, see Section 2, “The Initial Configuration”.
Blocking traffic using the packet filter may be useful in many situations. For example, we may relieve application proxies of the burden of processing traffic that we know for certain is undesired. Also, application proxies always grab connections, and only then they may selectively deny them. This means that the connection is always established at first, and then immediately closed if denied by a policy. It may be advantageous to pretend to some clients that there is no application proxy in the way, which can be achieved by resetting those connections using the packet filter. Furthermore, there are antispoofing rules to block traffic with faked source addresses, see Section 1.3, “Antispoofing Using Packet Filter”, and it is possible to bypass the application proxy processing and forward some traffic directly to its destination, see Section 1.4, “Selective Packet Forwarding”.
Individual packet-filtering rules are located in filter-acl
subsections within the system.packet-filter
configuration section.
The most important items in filter-acl
are summarized
here:
from
— A set of hosts, addresses
and networks that the packet's source address must match. Optionally it may
also include constraints concerning source TCP/UDP ports. If omitted, all source
addresses and ports match.
to
— The set of hosts, addresses
and networks that the packet's destination address must match. Optionally it may
also include constraints concerning destination TCP/UDP ports. If omitted, all
destination addresses and ports match.
iface
— The network interface that
this rule applies to. Moreover, the direction of communication may be
specified, either in
for inbound traffic or
out
for outbound traffic. If this item is not present,
the rule applies to all network interfaces and all directions.
protocol
— The IP protocol that
this rule applies to. Protocols are accepted with their symbolic names,
such as icmp
, udp
, tcp
,
or esp
. Moreover, a shortcut tcp-udp
has been
added for user comfort, meaning both the TCP and UDP protocols. Similarly, the
shortcut esp-ah
is interpreted as both the ESP and AH
protocols[25]. Additional protocol-specific parameters
are available for the ICMP and TCP protocols, specifically icmp-type
to match the ICMP message type, and flags
to match the TCP flags field.
deny / accept
— The
deny
item blocks traffic; the accept
item is used to pass it.
keep-state
— This item lets the
packet filter create a state for the connection as a packet is passed.
The following packets in the same connection will then be handled in
exactly the same way as the first one, without the need to search the
ruleset. Another advantage is that packets of the same connection in
the opposite direction are implicitly passed.
Port specification is available only for the TCP and UDP protocols.
Thus, if a port constraint is present in a from
or
to
item, the protocol
item must be specified
and must be one of tcp
, udp
, or
tcp-udp
.
Example: If we want to block the traffic coming in on our external
interface to the TCP port 22, we shall use the to
,
iface
and deny
items, as shown in
Figure 5.1, “A simple blocking packet filter rule”.
The deny
part of the rule means that Kernun UTM will
silently discard packets coming in to port 22. However, this behavior is not very
effective, for several reasons. First, everyone knows that there is
a filter blocking those connections, and that can attract unwanted attention.
Furthermore, the standard application will not give up if there is no response to
its connection attempts. Therefore, it is customary to send back
information that the port is closed. We will do so by adding a
return
item to our filter rule, see Figure 5.2, “A blocking packet filter rule with return
”.
We can change the packet filter's default behavior of silently
discarding packets by setting the block-policy return
option.
If we do so, it will properly react to blocked ports as if those ports were
closed even if there are no return
items in individual rules. See
an example in Figure 5.3, “Option block-policy
instead of return
in rule”.
Should some specific clients be allowed to connect to port 22, we have to add a packet filter rule before the blocking rule we have just created. Rule evaluation abides by the so-called first-match principle. This means that rules are evaluated in the order, in which they appear in the configuration, and as soon as a matching rule is found, the evaluation stops and the remaining rules are ignored. Therefore, more specific rules must precede those with more generic matching criteria. Figure 5.4, “More specific rule must come first” shows how to add a rule allowing connections to port 22 to a set of IP addresses, preserving the default behavior of blocking port 22 to other clients.
IP address spoofing is an attack based on counterfeiting the source IP address in order to confuse another computer system. It may be extremely dangerous if attackers from the outside pretend to have an internal source IP addresses; although they never get a response back, it may be sufficient to perform a successful denial-of-service or another kind of attack.
The goal of antispoofing is obviously to prevent spoofing attacks. We can stop intruders from the outside who pretend to have an internal source IP address quite easily. In general, internal network addresses can appear as the source of communication only on the internal network interface. As there may exist more than one protected network interface, this rule can be applied to other networks and interfaces as well.
A simple antispoofing rule consists of interface specification
followed by the antispoof
and deny
items, see
Figure 5.5, “Simple antispoofing rule”. In effect, the internal network
192.168.10.0/24
is blocked when
it appears as a source IP address on any other interface than INT
[26].
This simple antispoofing rule works for networks directly connected
to named interfaces. However, if our internal network is not flat, but
consists of several routed networks instead, we need to involve all the
internal networks in antispoofing. This can be achieved using the routes
modifier in the antispoof
item. The resulting rule is depicted
in Figure 5.6, “Antispoofing rule including routes”.
The routes
modifier has an effect
only if there are some routes within the internal network.
To illustrate this fact, the sample configuration file
packet-filter.cml
introduces a second internal network,
192.168.11.0/24
, specified in
the routes
section. Now, both our internal networks,
192.168.10.0/24
and 192.168.11.0/24
, get blocked in the source
address field on all interfaces except the internal interface
INT
.
Standard routers and filtering gateways accept all network datagrams, and if they are destined for another host, they send them out in accordance with the system's routing table. This mechanism is known under the name forwarding.
Kernun UTM does not forward network packets by default. Only traffic either destined for the system itself or grabbed transparently by application proxies will find its way through; everything else is thrown away. See transparency(7) for more detailed information.
It is possible to bypass application proxies and control the
communication only with packet filter rules. To do so, we need to inform
the transparent grabbing system which packets should be left untouched.
For that purpose, a special tag NOTRANSP
has been introduced.
Tagging is a feature of the packet filtering engine; network packets can be assigned a string value that will accompany those packets on their way through the network stack. Other Kernun UTM components may then check which tags, if any, are assigned to traffic they are processing.
The tag name NOTRANSP
that the
transparency engine uses to recognize bypassing packets is configurable.
By changing kernel sysctl variable net.inet.ip.no_transp_tag
,
we can define another tag string to be used to distinguish between standard
transparent proxy traffic and bypassing datagrams. Sysctl variables (also
called MIBS) are configured in system.sysctl
configuration section, see Section 2.6, “Kernel Parameters in /etc/sysctl.conf
”.
To assign a tag to packets, add a tag
item to
a filter-acl
rule inside the packet-filter
section.
Figure 5.7, “Selective packet forwarding rule” illustrates a rule causing the packet flow
between two hosts to bypass transparent proxy processing, forwarding them
directly to the network in accordance with the system routing table. Note that we have
introduced a new interface, DMZ, representing a demilitarized zone with
public accessible servers. The rule bypass-int-dmz
permits bidirectional traffic between an internal host and a host in the DMZ.
Apart from tag
, two more important filter-acl
items are introduced in the sample rule bypass-int-dmz
depicted in Figure 5.7, “Selective packet forwarding rule”:
:
fastroute
— This option means that
packets get forwarded through Kernun UTM to their destination. It is called
selective packet forwarding, as opposed to
global forwarding, which is performed by the standard routers
and packet filtering gateways. Without fastroute
, packets
tagged NOTRANSP
would not reach their destinations.
symmetric
— Adds a second rule,
allowing traffic in the opposite direction on the same interface. Source
and destination IP addresses are swapped in the second rule, as well as
the traffic direction in
or out
.
Considering the fact that we have two interface specifications in the rule,
we end up with four individual packet flow permissions:
Incoming packets on interface INT
going from
192.168.1.20
to
172.16.31.50
(the basic rule for iface ^system.INT in
).
Outgoing traffic on interface INT
returning back from
172.16.31.50
to
192.168.1.20
(the symmetric rule for iface ^system.INT in
).
Outgoing packets on interface DMZ
originated at
192.168.1.20
and destined for
172.16.31.50
(the basic rule for iface ^system.DMZ out
).
Incoming datagrams on interface DMZ
traveling from
172.16.31.50
to
192.168.1.20
(the symmetric rule for iface ^system.DMZ out
).
If a packet filter rule sets the NOTRANSP
tag for
a packet, a state is automatically created for the packet. This accepts
all following packets of the same connection in both directions. If we
want to selectively forward some communication via the
NOTRANSP
mechanism without creating a state, we need to add
an explicit rule that matches the packets and does not contain
keep-state
.
There are three types of NAT rules: mapping rules (nat-acl
),
redirection rules (rdr-acl
) and bidirectional NAT rules
(binat-acl
).
Mapping changes source IP addresses (and often ports) of outgoing packets. It always applies to outbound traffic, but it also creates states for backward incoming communication. The state engine fully recognizes individual TCP connections, UDP sessions and ICMP control messages that belong to them. Hence, if a state is created, only legal communication is passed and translated forth and back.
The nat-acl
sections allow for a similar set of
items as filter-acl
rules. The item from
is used to match source IP addresses and ports, similarly to
is matched against destination IP addresses and ports. The interface
specification may not include the in/out
direction as
mapping rules apply only to outbound traffic. The deny
modifier does not block traffic, but effectively denies any NAT mapping if
matched.
A new important item is introduced for mapping rules:
map-to
. Its purpose is to specify the final address
and port combination after the translation.
A sample mapping rule is depicted in Figure 5.8, “Mapping NAT rule”.
It illustrates the use of the map-to
item; it
specifies an IP address (using a reference to the outgoing interface's address
^system.DMZ.ipv4.host
) and a port (0 in our example,
meaning any port number available).
As always, mapping rules are implemented using the first-match
principle, i.e. the first matching rule is applied immediately, without
consulting the rest of the nat-acl
rules.
Unlike mapping, redirection deals with destination IP addresses and ports. Redirection rules are thus applied to the inbound traffic, creating states. The same powerful state engine is in charge of matching backward outgoing packets and changing their addresses and ports back to their original values.
Apart from the target redirection address and port combination,
which is specified using the rdr-to
modifier, all other item
names and features are the same in mapping and redirection rules. The
example in Figure 5.9, “Redirection NAT rule” assumes connections from the
172.16.31.0/24
network,
destined for the DMZ interface's local address 172.16.31.1
and port 80. Those
connections get redirected to internal server at 192.168.1.20
, port 80.
Imagine that we have an NAT network and want to bypass Kernun for some traffic
(e.g. ICMP packets, in order to be able to ping to the internet from the local
network). For that special case we need to create an NAT rule for the NAT and, at the same time,
tag the traffic with the NOTRANSP
tag to forward it, rather than give
it to Kernun's proxies. The NAT rule automatically creates a state, so the reply to the
ping should be delivered to the requester without the need to add any other rule.
However, there is a catch in the PF implementation. The NOTRANSP tag in
combination with NAT rule gets lost and the returning packet is passed to Kernun, rather
than forwarded. For this case, Kernun automatically generates a rule pass any
to any tagged NOTRANSP no state tag NOTRANSP
in the pf.conf file, in order
to keep the tag. This rule permanently stores the NOTRANSP tag to the
state of the tagged packet and is not applied to any other packets.
Figure 5.10, “Forwarding of ICMP Packets over NAT” shows a configuration of selective forwarding
of ICMP packets on Kernun UTM for clients behind NAT. The filter-acl ICMP
section tags the packet by the NOTRANSP tag to be passed through Kernun without giving
it to the proxies, while the nat-acl ICMP-NAT
rewrites the addresses
and creates a state for the reply packets to be passed back. The returned packets are
first NATed, then the above-mentioned rule is applied and restores the NOTRANSP tag, and
the packet is therefore forwarded into the local network.
The packet filter, together with the network stack in the operating system kernel, provide some means for defense against Denial of Service (DoS) and Distributed Denial of Service (DDoS) attacks. Such attacks try to overload a target computer system or network by sending huge amount of traffic. A DoS attack is originated from a single malicious computer. A DDoS attack is similar, but data are sent by many computers at the same time. It allows the attacker to magnify the number of network packets many times in comparison with a single-origin DoS, hence making the effect on the target network worse and any defense harder.
Basic protection against some (D)DoS attacks on the transport layer of the TCP/IP is built into the network stack of the operating system kernel in form of the SYN cache and SYN cookies. They are effective especially against the SYN flood attack, when the attacker sends many TCP connection requests in the form of TCP SYN segments. The SYN cache keeps information about TCP connection handshakes that have not been completed yet. A SYN cache entry occupies less memory than the full state record of an established TCP connection. Hence the system is able to withstand much more SYNs. SYN cookies take one step further, keeping no state and encoding all information necessary to complete the handshake into the SYN/ACK segment sent to the client.
The SYN cache is always enabled. By default, SYN cookies are also
enabled. They can be disabled by setting the sysctl variable
net.inet.tcp.syncookies=0
, see Section 2.6, “Kernel Parameters in /etc/sysctl.conf
” for instructions on setting sysctl
variables. SYN cookies are used when the SYN cache becomes full. It is
possible to disable the SYN cache and use only SYN cookies by setting the
sysctl variable net.inet.tcp.syncookies_only=1
.
The SYN cache and SYN cookies protect only against SYN flood attacks on TCP-based application protocols handled by a proxy or by a server running locally on the Kernun system. Additional defenses are provided by the packet filter. They are effective for communication handled by the packet filter and not passing via any proxy, but can be combined with a proxy, too. They can also block attacks that perform full TCP handshake and then send excessively large volumes of application-layer data in order to overload a server.
The packet filter allows limiting numbers of simultaneous connections that match a filtering rule or originate from a single source addres. The limits are configured by adding per-rule options. There are two variants how to create such packet filter rules:
A filter-acl
is created with item
keep-state
. A raw option is added by item
option
containing limit specifications delimited by
comma, for example, option "keep state (source-track rule,
max-src-nodes 100)"
. Note that “keep
state
” is specified here, in addition to the separate
keep-state
item.
A filter-acl
is created containing the whole
packet filter rule written in a raw
item, for
example:
pass quick inet proto tcp from any to any keep state (max 100)
Available limit specifications are:
max number
It limits the maximum number of simultaneous states (connections) the rule may create. When this limit is reached, further connection attempts are silently dropped. New connections are allowed only after some of the existing states time out. Note that a state times out some time after the related connection is closed.
source-track rule
Enables counting the states created for each
individual source IP address. The per-IP limits (e.g.,
max-src-nodes
and max-src-states
)
are compared to the number of states created by this
rule.
source-track global
Enables counting the states created for each individual source IP address. The per-IP limits are compared to the sum of states created by all rules that use this option.
max-src-nodes
number
It limits the maximum number of distinct IP addresses that can have states at the same time.
max-src-states
number
It limits the maximum number of states that can be created for a single source IP address.
max-src-states
number
It limits the maximum number of established TCP
connections that can be created for a single source IP
address. In contrast to max-src-states
, this option
counts only connection that completed the 3-way TCP
handshake.
max-src-conn-rate number
/ seconds
It limits the rate of establishing new TCP connections over a time interval.
overload
<table
>
, overload
<table
> flush
, overload
<table
> flush global
If a source IP address reaches one of the limits
max-src-conn
or max-src-conn-rate
,
it will be added to a named packet filter
. If
table
flush
is used, all states created by the matching
rule and originating from this IP address will be deleted,
effectively terminating all existing connection from the offending IP
address. If flush global
is used, all states from
this IP address are deleted, regardless the rule that created
them.
Example: The following rules will block any IP adress that initiates more than 100 HTTP connections per second.
table <dos_attack> persist block quick from <dos_attack> pass in proto tcp from any to any port 80 keep state \ (source-track rule, max-src-conn-rate 100/1, overload <dos_attack> \ flush global)
Additional user accounts can be allowed access to the system in the
configuration. Each user is represented by a user
section
within the users
section. The user
section must
contain a role
item with a value admin
or
audit
. The admin
class has full access
to the system and permissions to configure and operate all Kernun UTM components.
The audit
class can only view the system configuration and
logs. The user
section can also contain a
ssh-key
item, which generates a corresponding line in the
.ssh/authorized_keys
file for the user's ssh key.
The Kernun UTM configuration can hold any number of
interface
sections that correspond to a physical
device. Virtual network interfaces can be created from other tools
than Kernun UTM configuration utilities; these, however, need to be referenced in
the Kernun UTM configuration. For example, an instance of openvpn
creates the tun0
interface when started. To be able to
use it in the Kernun UTM configuration, include the virtual
parameter
in its dev
item (as illustrated in the interface
VPN-PRAHA
section in Figure 5.12, “Network Interfaces”).
Such an interface is not generated in the rc.conf
file.
An interface can be assigned multiple IP addresses.
To do so, add an arbitrary number of alias
sections
to the interface
section. Each of them
must contain an ipv4
item that defines its IPv4 address,
as depicted in Figure 5.12, “Network Interfaces” in
interface EXT
.
See interface(5) for details.
Static routes provide the capability to explicitly route packets
for a given network to a static machine, which works as a gateway for
this network when this cannot be done automatically by
the system routing table management daemon (such as
routed
). See
route(8) for further info.
A static route is set by a static
section in
the routes
section. The static
section
must contain one dest
item — the routed network
address — and a gw
item — the address of
the gateway machine for the routed network.
Kernun UTM supports dynamic IP routing via BIRD's (The BIRD Internet Routing Daemon) implementation of OSPF (Open Shortest Path First) protocol. It allows routers to automatically change routes, so that the path remain functional in case of failure of an router in the path.
BIRD uses separate configuration for IPv4 and IPv6. In the
example below, bird4
defines rules for IPv4 routing of
one Kernun UTM in the role of router. This router would be one of multiple
routers in network, either Kernun UTM or any other device that supports
OSPF. For example, two clusters of Kernun UTM with all nodes connected with
each other via VPN.
BIRD, or more precisely OSPF, requires each router to be
identified by an unique ID. use-id
in the example
above, uses IPv4 address of interface INT as this ID. The sections
device
, kernel
,
static
and ospf
defines different
protocols (or pseudo-protocols) which BIRD should use for import or
export of routes. The device
protocol is not a real
routing protocol. It doesn't generate any routes and it only serves as
a module for getting information about network interfaces from the
kernel. Except for very unusual circumstances, you probably should
include this protocol in the configuration since almost all other
protocols require network interfaces to be defined for them to work
with. The kernel
is also a pseudo-protocol. Instead of
communicating with other routers in the network, it performs
synchronization of BIRD's routing tables with the OS kernel.
Basically, it sends all routing table updates to the kernel and from
time to time (item scan
) it scans the kernel tables to
see whether some routes have disappeared or whether a new route has
been added by someone else. The section static
analogically sets rules for static routes defined in
system
→ routes
→
static
.
The ospf
section defines, besides import/export
rules, one or more areas (area
). In OSPF, the network
is divided into areas that are logical groupings of hosts and networks.
Each area maintains a separate link state database whose information
may be summarized towards the rest of the network by the connecting
router. Thus, the topology of an area is unknown outside of the area.
This reduces the routing traffic between parts of an autonomous system.
An area is identified by it's id
. "O" in this example,
identifies backbone area (or area 0.0.0.0) which forms the core of an
OSPF network. In interface
sections we assign
different properties for selected network interfaces. Especially, the
cost
item. The OSPF routing policies for constructing
a route table are governed by link cost factors associated with each
routing interface. Cost factors may be the distance of a router
(round-trip time), data throughput of a link, or link availability and
reliability, expressed as simple unitless numbers. Other items defines
different rules for communication with other routers via given network
interface.
For more information on BIRD configuration see http://bird.network.cz/?get_doc&f=bird-3.html
The /etc/rc.conf
configuration file is
used to automatically perform various actions at the system startup. It
contains information about the configuration of network interfaces, the
services that should be started after a boot and optionally their parameters,
the configuration of the machine's host name, console settings, etc.
See rc.conf(5) for details.
The rc.conf
file is generated by Kernun UTM and
should therefore not be configured directly, but in
rc-conf
section of the Kernun UTM configuration. An entry in
rc.conf
is set through the set-env
item. Examples of useful items include set-env fsck_y_enable yes
(which will make fsck answer itself "YES" to all
questions and thus make automatic OS booting possible).
It is even possible to extend an already set value by redefinition,
such as set-env variable "$variable ..."
.
The /etc/sysctl.conf
file is read when the OS
enters the multi-user mode and sets default settings for the kernel. Its
contents are generated from the variable
s items in the
syctl
section. Each variable
sets
one kernel setting. For example, variable
net.inet.ip.forwarding "1"
turns on IP forwarding.
The crontab
is the configuration file for
the cron daemon, which runs selected commands
periodically. Each entry in crontab
contains
seven fields separated by a white space character:
minute — permitted values: 0-59
hour — permitted values: 0-23
day of month — permitted values: 1-31
month — permitted values: 1-12 (or names)
week — permitted values: 0-7 (0 or 7 is Sun, or use names)
user — user under whom the program should be run
command — the command to be run and its parameters
A field may be set to "*", which stands for its entire range. Numerical ranges, lists and their combinations are also allowed. For example, "3-7", "1,2,7,8", "1-3,8-14,20". Step values and more complex expressions can be used as well, see crontab(5) for details.
There is a sample crontab configuration in
samples/include/crontab.cml
. It can be included
in crontab
by the application of the
$default-crontab
variable, which is set in
include samples/include/crontab.cml
.
Additional entries can be set by plan
items
in the crontab
section. For example plan
"1 2 * * * root
/usr/local/kernun/bin/upgradeFBSD.sh"
will schedule
the script upgradeFBSD.sh
(which automatically
synchronizes and compiles the OS source) to be run every day at 02:01 under
the user root.
Kernun UTM's dns-proxy
is not designed to be used as a
name server — it does not cache DNS queries. A possible solution
is a combination of named and dns-proxy.
In this scenario, named listens for DNS queries on the internal
interface and provides the cache. It queries dns-proxy
that is bound to the loopback interface and, in accordance with ACLs, permits or
denies the query, sends a response or queries the DNS root servers.
The configuration in Figure 5.18, “Caching Name Server configuration” shows the
named daemon configured in the nameserver
section to listen on Kernun UTM's internal address on port 53
(listen-sock ^system.INT.ipv4.host : 53
), while Kernun UTM uses it
as its resolver (server ^system.INT.ipv4.host : 53
in
the resolver
section). dns-proxy
is bound to
the loopback interface by the non-transparent [127.0.0.1] : 53
item in the
listen-on
section of dns-proxy
. See
named.conf(5) for more details.
The other typical scenario is that one or more name servers exist in the internal network. In this situation, clients are configured to query the server in the internal network, which queries dns-proxy that is configured to listen on the internal address, while Kernun UTM itself uses the internal name server as its resolver.
Note that in both of these scenarios it is necessary to have multiple name servers running in order to provide different DNS responses for different clients, because the response is cached on the name server and therefore not matched against the ACLs of dns-proxy. Nevertheless, it is always possible to plug requests coming from particular clients to a host with a different IP address, ignoring the DNS name in the request for every service.
In this scenario, named listens for DNS queries on the internal interface and queries dns-proxy, which provides the response.
The configuration in Figure 5.19, “DNS Server - Proxy configuration” shows
Kernun UTM using named as the resolver (server
^system.INT.ipv4.host : 53
in the resolver
section).
dns-proxy
is bound to the loopback interface by
non-transparent [127.0.0.1] : 53
in the
listen-on
section of dns-proxy
.
See Section 3, “Caching Name Server” for further information.
In the configuration depicted in Figure 5.20, “DNS Server - BIND configuration”,
the named daemon is configured in the
nameserver
section to listen on the internal
address on port 53 (listen-sock ^system.INT.ipv4.host :
53
) and to forward the request to dns-proxy
on the loopback interface (forwarder [127.0.0.1] : 53
).
Finally, there is the zone pha
section.
The name pha.tns.cz
item assigns its name and
the generate
item makes KGB generate the zone data from
hosts-table
. The reverse
item makes
zone pha-reverse
provide reverse DNS records
for the local network.
The hosts-table
section contains multiple
host
items, each defining the host name (e.g.
"builder.pha.tns.cz") and the IP address (e.g.
"192.168.1.101") for a certain MAC address (e.g.
"00:1D:7D:02:F7:C6").
It is possible to globally force the clients to use SafeSearch
functionality for Google, YouTube and Bing by using
samples/include/safe-search.cml
.
The Dynamic Host Configuration Protocol (DHCP) is used by a client to obtain information necessary to connect to an IP network automatically, with no need of manual administration. This information includes the client's IP address, network mask, default gateway, DNS server address, etc.
The DHCP server is configured in the dhcp-server
section. In this example, the DNS server address pushed by the DHCP server is
192.168.10.1 (name-server
item). The lease time is set
to 10 hours (default-lease-time
) and the maximum lease time
to 1 day (max-lease-time
). Furthermore, there is a setting
for the domain name (domain
), the router address
(router
) and the NTP server (time-server
).
There is a range of IP addresses (range [192.168.10.50]
[192.168.10.99]
) reserved for subnet devel
, which also
has the domain name altered to (domain devel.tns.cz
). The
addresses assigned by DHCP server will therefore by between 192.168.10.50
and 192.168.10.99.
The hosts-table
section defines a single host with a
predefined IP address: the host u2 with the MAC address
00:17:08:3e:a7:ba is assigned the IP address 192.168.10.22
(host [192.168.10.22] { u2 }
"00:17:08:3e:a7:ba"
).
See dhcp-server(5) for details.
It is very important to keep the correct time and date on all computer systems, including firewalls, internal servers, routers and even workstations. Kernun UTM provides a time synchronization function by means of an NTP server.
Kernun UTM's NTP server allows two functions: to synchronize the local time with a remote NTP server, and to serve this time data to the local systems. It uses the NTP protocol version 4, but retains compatibility with versions 3, 2 and 1 of the NTP protocol. It can play the client and server role at the same time. Thus, in a typical scenario, Kernun UTM's NTP server exchanges NTP messages with a few public time servers in order to keep its own time and date synchronized, while offering time synchronization to the whole local network.
Local time zone of the Kernun UTM system is set in the console during the first boot, see Section 5.2, “Initial Configuration”.
From now on, we will assume that the initial configuration file is
loaded in the GUI, as shown in Section 2, “The Initial Configuration”. To define
NTP server parameters, we add a new ntp
section at the
system
level, for instance after the ssh-keys
section. As a minimum, we need to define one server in an item within
the ntp
section, ns2.tns.cz
in our example. Furthermore, we want to let the internal systems synchronize their time
with Kernun UTM, which is achieved by adding an extra restrict
item. We use a reference ^system.INT.ipv4.net
to specify our
local network; in more complex topologies, we would have to repeat the
restrict
item and specify internal networks explicitly
or using variables. The nopeer
and noquery
flags of the restrict
item are used to allow only client
synchronization requests. Figure 5.22, “Minimum NTP server configuration” shows
the relevant part of configuration.
Reliance on a single external time server may lead to time synchronization outages.
Therefore, it is quite common to use more than one time server. The server
item can be repeated, which results in a stabler configuration.
Moreover, if there are more firewalls or parallel network servers, it is sometimes
beneficial to let them know about each other's NTP server, acting together as
peers. An NTP peer is not an authoritative source of time data, but may serve
for minor time corrections upon Internet blackouts. We achieve this effect
by specifying another NTP server with a peer
item within
the ntp
section, as shown in Figure 5.23, “Peer for NTP server”.
If the drift-file
item is used, Kernun UTM's NTP server attempts
to compute the error in the intrinsic frequency of the local on-board clock.
The item must be accompanied with a filename, e.g. /var/ntp.drift
.
The NTP server also includes support for local reference clocks,
if available.[27]
The on-board system clock itself may be used as a reference clock. An
example of its use is depicted in Figure 5.24, “On-board clock with NTP server”.
The clock
item accepts three parameters:
Type
—number 1 for local
on-board clock.
Unit
—number 0 as the first (the only) unit of
local on-board clock.
Stratum
—the distance in hops from
an accurate authoritative time source; for the local on-board clock, we use number
10 to make it higher than standard Internet NTP servers.
The resulting configuration file is available among Kernun UTM samples
under the name ntp.cml
in
/usr/local/kernun/conf/samples/cml
.
All Kernun UTM proxies write information about their state and progress into the log. The log can be
used later to analyze the traffic, generate statistics, find out why a certain connection was refused,
or look for system errors. Logging is switched on for all proxies by default. To
alter the log settings of a proxy, add a log
section with desired items (see below) into it.
Logging can be done either by the standard syslog daemon (the default is the
LOCAL4
facility, which logs into the /var/log/kernun-debug
file), or directly
into a specified file. Moreover, there is a possibility to log a small amount of the last data for each proxy into a
memory-mapped file, which can be used for system failure analysis. The facility
item is used to
change the facility number, the file
item to enable logging into a file and the mem-file
item to specify the memory-mapped file.
There are 9 levels of log messages (the lower the number, the higher the severity) and the administrator can choose
the level of logging. The log level of a proxy can be set either in the configuration using the
level
item, or at runtime by sending a SIGUSR1
/SIGUSR2
signal to
the proxy process to increase/decrease the level. The proxy logs only messages with a level lower or equal to its log level.
The log message level is appended to the MsgID
column of the message, so you can easily filter only
messages of a certain log level in the log browser (Section 1.3, “Logs”).
Each log message contains the MsgID
column, which stands for the type of the message. For every log message
type, there is a manual page in the section 6. The Message ID consists of a component code (an application name, possibly with
a suffix), message number and message log level.
Most of the information on normal traffic can be gathered from the level I
(information statistical
messages) and level N
(noticeable conditions), which are both logged with any log level set.
For example, a simple HTTP 1.1 request is started by TCPS-706-N
which informs about a new TCP connection
and assigns the connection to a child, then a session is started (HTTP-710-I
) and proceeds with the first
phase of acl. If the session is accepted, then the HTTP request is started (HTTH-702-I
), request-acl is
evaluated (HTTH-811-I
) and the client is connected to the server (MNIO-710-N
). When
the answer, the document, arrives from the server, doc-acl is evaluated and the message HTTH-893-I
is
added to the log. If the document was accepted, the request end message HTTH-713-I
is added and the proxy
waits for other requests on the same socket (we are communicating over the multi-request HTTP 1.1 protocol). Then, possibly, more
requests are served and, eventually, the session is ended (HTTP-711-I
), the proxy finishes the connection and
waits for a new one (messages TCPS-707-N
and TCPS-715-N
). The log of the described
situation is shown in Figure 5.25, “Log of an HTTP request”.
For more information on logging, see logging(7). For details concerning configuration of logging, see the log(5) manual page.
The created log files grow enormously and might fill all the free disk space. Another problem of logging is that
manipulation with big files is more difficult (and slower) than with smaller ones. Kernun UTM provides tools for
log rotation as a method of solving the above-mentioned problems. Log files are regularly (daily, weekly or monthly)
renamed and the system starts afresh with an empty log file. The old log files are thrown away after a certain period.
The administrator can configure log rotation by adding an rotate
item into the system-level
rotate-log
section for the entire Kernun UTM or into the log
section of a particular proxy,
if it logs into a separate file. In the rotate
item you can specify the owner, group and rights of the
file, the number of coexisting history logs, the compression method and the time of log creation. The logs can be
rotated either periodically (daily, weekly or monthly), or when the size of the log exceeds a specified limit.
The log rotation will only work if you have it scheduled in the crontab
, as illustrated e.g. in
the sample crontab file /usr/local/kernun/conf/samples/include/crontab.cml
.
Each of the connection-oriented proxies (http-, ftp-, imap4-, pop3-,
smtp-, sip-, sqlnet- and tcp-proxy) and udp-proxy are able to write
information about the current sessions (connections they are currently serving) into special binary files that can be
used to monitor their current state. A log does not provide all the necessary information when huge files are being downloaded:
we are informed that the request has started, but do not know anything until it ends. This is the right time to use the
monitor(1)
application, which collects information about the current session's progress and is able to present it to the user
(either as plain text, or in the HTML format). Monitoring is best accessible from the GKAT window of the Kernun GUI via
the Monitor tab in the detail of a proxy (or the Proxies
root node). The information
in the monitor include the name and type of the proxy, the PID of the proxy process, the duration of the current session,
the server and client IP addresses and names, the number of bytes transferred and delivered in both directions, the connection
speeds, and the URI of the document (in the case of http- or ftp-proxy). Monitoring is only available for proxies that contain
the monitor
section in their configuration.
Monitoring information is also stored in a database that is used for graph generation; for more details see Section 6.5, “Monitoring of System Parameters”.
Every proxy can generate statistics of its usage; these statistics are then shown in the statistics browser window (Figure 5.26, “Statistics browser window”), which is accessible via the menu in the GKAT. In the browser, the tree on the left-hand side shows the available statistics (for each of the available periods and all the proxies that generated statistics in that period). The right-hand part of the window shows the statistics of the selected period, date and proxy as an HTML page.
To enable the generation of statistics for the desired proxies or the whole system,
insert stats-daily
, stats-weekly
and/or stats-monthly
sections into their configurations. Inside these sections, you can specify the number of top results
for each watchable parameter (if not set, the default value will be used). By default, the generation
scripts for each of the periods are scheduled in the crontab. Therefore, no changes should be necessary.
Figure 5.27, “Configuration of statistics” shows a sample statistics configuration for an http-proxy
.
Sample configuration with generation of statistics for most of the proxies and the whole system
is included in /usr/local/kernun/conf/samples/cml/statistics.cml
.
Kernun UTM is able to monitor various system parameters, from hardware temperature to
proxy loads, and store their values in a database. Later it is possible to create
and view graphs generated from these values and thus examine the traffic load history.
The graphs are generated by the command line tool rrd, described in the
rrd(1)
manual page, which can be also used to view the available graph types and intervals. The easiest way to
access the graphs is using the Graphs tab in the GKAT window of the Kernun GUI. It is available
for all the proxies and network interfaces, and for several system components. All the system parameters are
displayed in the Graphs tab of the top-level GKAT node, as depicted in Figure 3.8, “Graphs page”.
While system components other than proxies generate their graphs automatically, you have to insert
a monitoring
section into the configuration of a proxy to generate its graphs.
Chosen graphs can be added to the Favorite graphs
tab in the Graphs tab of
the top-level GKAT node to make them more accessible; the period of the displayed graphs can be changed using a combo box.
In general, a proxy can listen in two modes: non-transparent and transparent. In the non-transparent mode, the client must be aware of Kernun UTM, as it is connecting explicitly to some of its IP addresses. For example, the proxy address and port must be entered in the preferences dialog of the Web browser. According to the configuration of the protocol and of Kernun UTM, the proxy typically connects to a server and mediates the communication.
In the transparent mode, on the other hand, Kernun UTM captures clients' connections and hands them over to the proxies. Although the client thinks to be connected directly to the server IP address, it is in fact communicating with the proxy. Hence, the client does not have to be configured for using the proxy. The proxy typically creates the connection on its own and mediates the communication. According to the configuration, the proxy can either connect to a server (the one the client was connecting to, or even to another one), or it can react otherwise, e.g. deny the connection.
Incoming transparency (i.e., proxy listening in the
transparent mode) is configured by specifying the
transparent
item in the
listen-on
section in the proxy
configuration.
Let us demonstrate the transparency aspects on the example of
http-proxy
. It is configured to listen in the
transparent
mode on port 80 and in the
non-transparent
mode on port 3128, as
depicted in Figure 5.28, “HTTP Proxy listening both in transparent and
non-transparent mode”.
When one proxy listens in both modes simultaneously, clients can choose whether to connect in the transparent mode (by connecting directly to the Web server to its port 80), or non-transparently (by connecting to the proxy to port 3128). Examples of Web browser configuration dialogs are shown in Figure 5.29, “Configuration of non-transparent mode in Firefox and Microsoft Internet Explorer Web browsers”.
Figure 5.29. Configuration of non-transparent mode in Firefox and Microsoft Internet Explorer Web browsers
After the configuration is applied to Kernun UTM and
the proxy is restarted, it starts to listen on the two
given sockets. This can be verified in the
Network | sockstat tab of the GKAT
window, as depicted in
Figure 5.30, “Sockstat tab showing the list of all sockets
”. We can see
sockets listening for connection in the
transparent mode (rows marked ) and
in the non-transparent mode (rows marked
).
These sockets occur in the list more than once as they
are shared by the parent process and all the child
processes. The listening sockets show
*:* in the ForeignAddr column.
The non-transparent listening sockets show the
IP address they listen on in the
LocalAddr column.
The transparent listening sockets show the special symbol
>> in the
LocalAddr column, preceded by the
name of the interface, from which they accept connections.
In this example we can also see two clients to be actually
connecting through the proxy, both to the Web server at 194.228.50.79
. Client from IP
192.168.1.31
is connecting
via the non-transparent proxy. We can see the
connection from the client to Kernun UTM's internal IP address
(row marked ), and the connection from
Kernun UTM's external IP address to the server (row marked
).
Client from the IP address 192.168.1.12
is
connecting transparently. We can see the connection
from the client to the server, which was
grabbed by Kernun UTM (row marked
)
and the connection from Kernun UTM to the server
(row marked
).
The realized connections can be traced in the log, as is shown in Figure 5.31, “Tracking transparent and non-transparent
connections in the http-proxy
log
(the log was filtered, in order to save space).
”. We have filtered the log
messages that inform about the session—see the filters box in the
screenshot. The complete track of the session is more detailed,
concerning matching of ACLs, requests, documents, etc. The selected
message (HTTP-710-I) denotes the start of the
session in http-proxy
,
and informs about the facts that are known at the time the session is
being established (client address, server address and the transparency
flag). The session end message (HTTP-711-I) would
also provide other informations concerning the session (the number of
requests, the length of the session, etc.).
Figure 5.31. Tracking transparent and non-transparent
connections in the http-proxy
log
(the log was filtered, in order to save space).
When a client is connecting to a server, the question is what IP address the server sees as the client IP address. Different approaches can be useful in different situations.
If a network with private addressing is hidden behind Kernun UTM, Kernun UTM must connect from its own (external, public) IP address. When the client network uses public IP addresses, both approaches can be desired: either the internal addressing should be hidden (the traffic should be formally realized from Kernun UTM's IP address), or not. On the other hand, a server protected in a DMZ may need to know the IP address of the real client.
By default, Kernun UTM proxy connects to the server from Kernun UTM's IP address (i.e. hiding the client's real IP address). However, there are two other options, which can be specified in the first-layer ACL (see Section 2.5, “Application Proxies and ACLs” for details on ACLs):
source-address client
denotes that the
IP address of the real client should be used as the source
address;
source-address force
denotes
that the given address
address
should be faked
as the source address for the connection to the server.
The source-address
item can be either specified
on the system
level of the configuration, in which
case it influences all the proxies that reference the ACL, or
in the session-acl
section of the particular proxy.
In Figure 5.32, “Transparency for servers (source-address client
)
”, the real
client address is configured to be used as the source address for all
the named proxies, because it is specified in the system
ACL.
In Kernun UTM, a single port can be shared by several proxies or servers, provided that they do not collide in their listen sockets. For example, it is desirable to provide a transparent SSH proxy for connecting to SSH servers in the Internet and, at the same time, to provide an SSH server for administration of Kernun UTM. Both should be available from the protected network.
An example of such configuration is shown in Figure 5.33, “A port shared by two applications ”. When a packet arrives, Kernun UTM kernel delivers it to the most specific socket that is suitable for it. Consult transparency(7) for more information, including the definition of conflicting sockets and the socket preference. This way, it is possible to provide services on their traditional ports as well as transparent proxies on the same ports.
Kernun UTM proxy can be configured to listen on a set of contiguous
ports. This ability is also known as listening on a port
range and is available for TCP and UDP-based
proxies. If a transparent proxy listens on a port range (and
ACLs do not specify otherwise), the proxy connects to the
port the client was connecting to. If a non-transparent proxy
listens on a port range, the situation is similar to the regular
non-transparent proxy (one that listens on a single port): the
port (as well as the server IP address) would be either provided in
some ACL in the Kernun UTM configuration (for example, in the
plug-to
item), or it is a part of the application
protocol. An example of sip-proxy
configured
to listen on a port range is shown in the Figure 5.34, “The sip-proxy
configured to listen transparently on a port range 5060-5062
”.
Proxies cannot listen on ranges of ports that collide with
the system default port ranges. The system normally assigns ports to connections
with unspecified source port from three port ranges, which can be
modified by the portrange-default
,
portrange-high
, portrange-low
items in the
system.sysctl
section. None of those ranges may overlap
with the range of ports that a proxy is listening on. In the case of a port range
collision, the system would not know, which ports are free to use and
which are occupied.
Note that this problem does not occur when the proxy listens on separate ports. In this case, the single ports are reserved for the use of the proxy (even if they are inside one of the system port ranges).
h323-proxy
and gk-proxy
are the proxy daemons for a set of multimedia
communication protocols called H.323 protocols.
Kernun UTM supports them only for backward compatibility,
because this protocol family is now widely replaced by the SIP protocols
(see Figure 5.35, “SIP
Proxy” below).
Therefore, this manual does not cover this topic.
For more information, see h323-proxy(8), h323-proxy(5), gk-proxy(8) and gk-proxy(5).
sip-proxy
is the proxy daemon
for the Session Initiation Protocol (RFC 3261 et al.),
i.e. mainly Internet telephone calls and related services.
The proxy is configured in the sip
section.
In the sample configuration depicted in Figure 5.35, “SIP
Proxy”,
chroot-dir
defines directory into which it should be chrooted.
The proxy listens transparently for requests at Kernun UTM's internal address
at port 5060. However, due to the hop-by-hop logic of the protocol,
the proxy must listen on this port non-transparently
on all internal and external interfaces as well.
As usually, the proxy must be referenced by at least one ACL in the
system
section. In order to enable incoming calls,
we will need to allow also sessions from the external network.
sip-proxy
uses two-phase ACLs. The first phase,
session-acl
, is checked once for each client connection.
It permits or denies client access and sets some connection parameters.
This is where the administrator can specify that some important data
that is usually stored in SIP messages headers (e.g. internal addresses)
is to be hidden.
The second phase, request-acl
, is checked once for
each request and it can be used e.g. to change the target server
according to the Request-URI.
sip-proxy
requires specification of the maximum
of sessions and data channels used in parallel.
An estimate is three times number of the phones
for sessions-table-size
and two times number of the phones
for sockets-table-size
.
Finally, the proxy requires a file to store the registration data
of clients (local phones).
The complete resulting configuration can be found
in /usr/local/kernun/conf/samples/cml/sip-proxy.cml
.
See sip-proxy(8) and sip-proxy(5) to learn more about sip-proxy
.
sqlnet-proxy
is the proxy daemon
for the proprietary Oracle SQL*Net Protocol.
The proxy
can handle features, such as session redirection,
or database user checking.
The proxy is configured in the sql
section.
In the sample configuration depicted in Figure 5.36, “SQL*Net
Proxy”
chroot-dir
defines directory into which it should be chrooted.
The proxy listens transparently for requests at Kernun UTM's internal address
at port 1521.
As usually, the proxy must be referenced by at least one ACL in
system
section.
The sqlnet-proxy
uses two-phase ACLs. The first phase,
session-acl
, is checked once for each client connection.
It permits or denies client access and sets some connection parameters.
The second phase, service-acl
, is checked once for
each CN (connect) or RD (redirect) message and it can be used
e.g. to change the target server according to the SERVICE name.
The complete resulting configuration can be found
in /usr/local/kernun/conf/samples/cml/sqlnet-proxy.cml
.
Since the protocol is proprietary, clients often violate it
and it is necessary to avoid some checks using configuration directives,
such as connect-string-charset
.
See sqlnet-proxy(8) and sqlnet-proxy(5) to learn more about sqlnet-proxy
.
Kernun UTM provides a generic proxy for handling application protocols based on UDP. Its philosophy is similar to the generic TCP proxy, which is used for the HTTPS and SSH protocols in the initial configuration, as described in Section 2.9, “HTTPS and SSH Proxy”. The proxy waits on one or more ports, transparently or non-transparently, for datagrams from clients. Although UDP is a stateless protocol, the UDP proxy defines logical sessions that group together related datagrams. See udp-proxy(8).
We will demonstrate the UDP proxy on the DNS protocol. It is one of typical applications of the UDP proxy[28]. Kernun UTM provides the DNS proxy (refer to Figure 4.11, “DNS Proxy”), which is a better choice for accessing DNS servers in the Internet, because it performs thorough checks of the protocol. However, if Kernun UTM connects two trusted internal networks and clients in one of them send DNS requests to a server in the other, the use of the UDP proxy may be sufficient.
The DNS proxy in the sample configuration in Figure 5.37, “UDP proxy
” was replaced by the UDP proxy. It listens on the
internal network interface on the DNS UDP port 53 non-transparently. The item
max-sessions
in section udpserver
limits
the maximum number of logical sessions that can be handled by the proxy
simultaneously. All DNS requests from the internal network are accepted by
global acl INTOK
. This ACL is extended in the proxy by
the plug-to
item, which forwards all requests to a single DNS
server. As DNS is a request-reply protocol, we define that each logical
session contains at most one request (client to server) and one response
(server to client) datagram.
The setup described in this section can be tested by specifying in
plug-to
a DNS server that accepts and recursively solves
requests from Kernun UTM. The client machines must be configured to use
Kernun UTM as their DNS server.
Web browsers support access to FTP servers by using URLs beginning with
ftp:
. If no proxy is configured for FTP in the browser
parameters, the browser accesses FTP servers using the native FTP protocol.
Such communication can be mediated by a transparent FTP proxy. Another
situation is the non-transparent case, when a proxy for FTP is specified in
the browser settings. Then the browser communicates with the proxy using
the HTTP protocol, rather than FTP. Hence, the communication is processed by the HTTP
proxy, which gets a URL starting with ftp:
. The proxy
must act as a FTP client, contact an FTP server, and send the result to the
browser via HTTP. The HTTP proxy does not support FTP directly. Instead,
it communicates with the FTP proxy using an internal
protocol[29]. The FTP proxy
handles the FTP part of the communication.
Both
http-proxy(8) and
ftp-proxy(8)
need to be reconfigured in order to cooperate
in the processing of ftp:
requests from Web browsers. In the
ftp-proxy
section, a new non-transparent
listening socket should be added to the listen-on
section. The
two proxies run on the same system and they communicate via the loopback
interface. Hence, the socket for HTTP-FTP cooperation listens on the
localhost
address and on an arbitrarily chosen port.
It is necessary to allow connections from the HTTP proxy
to the FTP proxy by adding a system-level acl
and to tell the
FTP proxy in the corresponding session-acl
that it should
expect requests from the HTTP proxy instead of the standard FTP. The HTTP
proxy must be told to pass FTP requests to the FTP proxy by adding a
ftp-proxy
item to section http-proxy
.
An example of FTP and HTTP configuration is shown in Figure 5.38, “Cooperation of HTTP and FTP”. Port 8022 has been chosen and stored in variable
HTFTP_PORT
. A new acl HTFTP
section has been
created, which permits connections in the FTP proxy from the local host to the
HTFTP port on the local host. In the ftp-proxy FTP
section, the FTP proxy is switched (by item htftp-mode
) to
the HTFTP mode for connections accepted on the HTFTP socket. The HTTP proxy is
instructed how to contact the FTP proxy by item ftp-proxy
.
The complete resulting configuration can be found in file
/usr/local/kernun/conf/samples/cml/htftp.cml
. After
applying these configuration changes and restarting the HTTP and FTP proxies, it
should be possible to set the HTTP proxy as the proxy for FTP in the Web
browser and to start using ftp:
URLs.
Kernun UTM supports network communication securing using the standard SSL
(Secure Sockets Layer) protocol and its newer version TLS (Transport Layer
Security). As the SSL/TLS protocol ensures end-to-end security, Kernun UTM
cannot read or modify data from an SSL/TLS connection between a client
and a server. This means that protocols using SSL/TLS encapsulation, e.g.,
HTTPS, POP3S, or IMAP4S, cannot be processed by a protocol-specific proxy.
Instead, generic TCP proxy is usually used to forward such communication. In
the case of HTTPS, a nontransparent HTTP proxy can be utilized for tunneling
HTTPS data in an HTTP connection with the CONNECT
HTTP request
method. Sometimes, however, we need to have access to encrypted data for the
purposes of analysis or even modification. An example is antivirus checking of
files transferred via HTTPS.
The configuration described in this section is useful for fixed secure tunnels, e.g., via tcp-proxy, or for securing a single HTTP server by http-proxy. It is unsuitable for inspecting HTTPS traffic between ordinary HTTP clients (browsers) and servers, because the proxy presents a single server certificate (containing a single fixed host name) for any server accessed by a client. Common behavior of browsers is to compare the accessed server host name with the name in the server certificate and to issue a security warning if they do not match. If you need to handle this, HTTPS inspection, introduced in Section 19, “HTTPS Inspection”, is a viable option.
To access data protected by SSL/TLS, a proxy must split the communication into two SSL/TLS connections. Data from a client is first sent to the proxy via the first secure connection terminated on Kernun UTM. The encrypted data stream is decrypted by the proxy, processed, encrypted again and sent to the server via the second secure connection. Data from the server is passed via the two connections in the opposite direction. It is also possible to convert the unencrypted version of an application protocol (for example, HTTP) used by a client to the encrypted version (for example, HTTPS) accepted by a server, or vice versa.
An example of a proxy that uses SSL/TLS security is presented in Section 14.7, “HTTP Authentication Proxy”, and its configuration is shown in Figure 5.51, “Configuration of the HTTP authentication proxy”. This proxy converts a secured connection from a client to plain HTTP sent to the server. Another example is depicted in Figure 5.39, “SSL/TLS security configuration”. It is an HTTP proxy that enforces authentication of the remote server and also authenticates Kernun UTM to the remote server.
The parameters of an SSL/TLS connection are defined by the section
ssl-params
. All the available parameters are explained in
ssl(5). In our example, this section selects
the X.509 certificate with the related private key used by the proxy to
authenticate itself to clients and servers (item id
),
and the list of certification authority certificates
(auth-cert
) with the related certificate revocation lists
(crl
) for verification of certificates provided by peer
clients and servers. The verify-peer
item forces the proxy to
request and verify certificates of peers. If a peer does not provide
a certificate or the certificate cannot be verified, the SSL/TLS handshake
fails and the session is terminated.
The client-ssl SSL
item in the
session-acl INTOK
section switches the connection from the
client to the SSL/TLS mode and sets the protocol parameters. If the client
establishes an encrypted connection and sends a valid certificate, it can
send an HTTP request. Otherwise, the session is terminated. After receiving
an HTTP request, the proxy searches for a request ACL. It selects
request-acl TNS-CERT
only if the client's certificate
contains “SSL access
” in the subject
field, because of the client-cert-match
item. The request ACL
enables SSL/TLS on the connection to the server and sets the protocol parameters.
The server-cert-match
item defines conditions that must be
fulfilled by the server's certificate (it must contain a common name ending by
“kernun.com
” in our example). Note that
if the client-cert-match
item is not matched, the single ACL
is skipped and the search continues at the next request ACL, whereas if the
server-cert-match
item is not matched, the request is terminated
immediately.
If you apply this kind of configuration and access a Web server via the proxy, your Web browser will show that the peer certificate is that of the proxy. In the proxy log, you will see details of the client's and server's certificates as received by the proxy.
Kernun UTM applies different rules to network traffic depending on the identity of the communicating parties. A client or a server can be identified in several ways. The basic one is the IP address and the port number, which are available for any network connection. The IP-based identity is used very often, but it distinguishes between computers, not users. Sometimes it is necessary to apply different rules to different users, while each user can work on several machines and each machine can be utilized by more than one user. In such situations, we need to identify individual users, independently on the IP addresses of the computers they use. Kernun UTM provides various means of user authentication. An authenticated user name can be used as one of the conditions tested when searching for an applicable ACL.
Some application protocols allow the passing of user credentials to a proxy within the normal protocol data flow. In Kernun UTM, such type of authentication is supported by the HTTP and FTP proxies. Many other proxies are able to use out-of-band (OOB) authentication, which binds a user name to a client machine IP address. Kernun UTM also provides a special authentication mode usable for protecting access to protected HTTP servers from clients in the external network—the HTTP authentication proxy.
Examples of configuration for all variants of authentication except NTLM
described
in this section are summarized in the sample configuration file
/usr/local/kernun/conf/samples/cml/auth.cml
.
Kernun UTM supports several methods, described in detail in
auth(7). Section
ftp-proxy FTP
in Figure 5.40, “Authentication methods”
contains sample auth
items for different authentication
methods. To switch to another authentication method, simply hide
the single not hidden auth
item and unhide another one.
No user authentication is performed.
The user provides a user name and a password, which
are compared to name-password pairs in a password file stored locally
on Kernun UTM. The administrator must create—by utility
fwpasswd(1)—a file containing valid
user names with encrypted passwords
(/etc/proxy-passwd
in the
example configuration).
The user name and password are verified by a RADIUS
server. There are two variants: name/password (the user enters his name
and the password) and challenge/response (the user enters her name, the
RADIUS server generates a challenge, and the user replies by
a response derived from the challenge and some secret
information, e.g., using an authentication token
hardware). If the radius
method is chosen in an
auth
item, it must reference a
radius-client
section that defines the parameters needed
to connect to a RADIUS server.
The user name and password are verified in an LDAP
database. If the ldap
method is chosen in an
auth
item, it must reference
an ldap-client-auth
section that defines the parameters
needed to connect to an LDAP server. If a secure connection to the LDAP
server is used (the LDAP server URI begins with
ldaps
), the certificates to be used must
be specified in the
ldap-client-auth.ssl
subsection.
The Kerberos authentication is specific to the http-proxy. If a user is authenticated in an Active Directory domain (or has a Kerberos TGT), a Web browser uses the user's Kerberos tickets and does not require any interaction with the user (name and password entry).
The NTLM authentication is specific to the http-proxy and HTTP clients (Web browsers) running on Microsoft Windows client operating systems. If a user is authenticated in an Active Directory domain, a Web browser uses the user's credentials known by the system since the login time and does not require any interaction with the user (name and password entry). It can be combined with other authentication methods for clients that do not support NTLM.
If a proxy runs in chroot, the paths in
auth passwd
and ldap-client-auth.ssl
are interpreted in the context of the chroot directory.
User authentication in the FTP proxy can be enabled using the
auth
item that specifies an authentication method other than
none
in session-acl
. For example, a
proxy with the configuration shown in Section 14.1, “Authentication Methods” will
use a local password file. If authentication is enabled and the user does
not provide valid credentials, the proxy terminates the session.
Otherwise, it is possible to match user name or group using a
user
item of command-acl
. There are several
ways of sending authentication data to the proxy, see
ftp-proxy(8). An example FTP session initiation
with authentication, using a command line FTP client:
$
ftp fw.pha.tns.cz
Connected to ftp.tns.cz. 220-fw.pha.tns.cz KERNUN FTP Proxy (Version KERNUN-3_0-RELEASE) Ready. Target server name/address and authentication to proxy required. You can use loginname in form of proxy_user@server_user@server. 220 Log in with USER and PASS command.Name (192.168.10.1:user):
guest@anonymous@ftp.tns.cz
331-USER command successful. Proxy user: 'guest'. Target-server user: 'anonymous'. Target server: ftp.tns.cz, port: 21. Enter password in form proxy_user_password@server_user_password. 331 Enter password or response, please.Password:
****@****
230-User 'guest' succesfully authenticated. 230-pha.tns.cz KERNUN FTP Proxy (Version KERNUN-3_0-RELEASE) Ready. 230-Welcome to ftp.tns.cz FTP service. 230----- proxy connected to [194.228.50.76]/ftp.tns.cz port 21 ---- ---- proxy connected to ftp.tns.cz port 21 ---- 230-Please specify the password. 230 Login successful. Remote system type is UNIX. Using binary mode to transfer files.ftp>
A similar, but unsuccessful session initiation (due to a wrong password):
$
ftp fw.pha.tns.cz
Connected to ftp.tns.cz. 220-fw.pha.tns.cz KERNUN FTP Proxy (Version KERNUN-3_0-RELEASE) Ready. Target server name/address and authentication to proxy required. You can use loginname in form of proxy_user@server_user@server. 220 Log in with USER and PASS command.Name (192.168.10.1:user):
guest@anonymous@ftp.tns.cz
331-USER command successful. Proxy user: 'guest'. Target-server user: 'anonymous'. Target server: ftp.tns.cz, port: 21. Enter password in form proxy_user_password@server_user_password. 331 Enter password or response, please.Password:
****@****
421 User 'guest' not authenticated. ftp: Login failed.ftp>
Selected log messages related to these two FTP sessions are displayed in Figure 5.41, “Log of authentication in FTP proxy”.
The HTTP proxy supports proxy authentication using the Basic authentication method, i.e., a name and a password entered by the user. The technical details of the authentication are described in http-proxy(8). Proxy authentication in HTTP works as follows: the first request sent by the client (browser) is unauthenticated, the proxy replies with response code 407 “Proxy Authentication Required”; upon reception of this response code, the browser displays a dialog (see Figure 5.42, “Proxy authentication dialog in a Web browser”) asking for user credentials; the browser then repeats the request with the user name and password attached.
Figure 5.43, “User authentication configuration in the HTTP proxy” contains an HTTP proxy
configuration with user authentication. The authentication is enabled and
the authentication method (a password file in this case) is selected by the
auth
item in session-acl
. If a request
contains user credentials, they are checked and if correct, the
user name—and the list of groups the user belongs to—is
remembered for matching with the user
item in a
request-acl
. Unlike in the case of FTP proxy, a request
containing invalid or no credentials is not rejected. The processing
continues, but no request-acl
containing a
user
item matches, except for the one with
user none
. There should be a
request-acl
that matches unauthenticated requests and
returns the 407 response. In the example configuration, there are two
request-acl
sections. The first one,
request-acl ALL-2
, matches any successfully
authenticated user. The request is processed normally, i.e., forwarded to
the target server. The other, request-acl ASK-AUTH
,
matches if the request does not contain valid user credentials[30]. The 407 response is
forced by the auth-req
item. This item also sets the
realm (prompt) that is usually displayed by the
browser in the authentication dialog, as depicted in Figure 5.42, “Proxy authentication dialog in a Web browser”.
If we apply this sample configuration to Kernun UTM and invoke
a new request in a Web browser, the log will contain messages similar to
those in Figure 5.44, “Log of user authentication in the HTTP proxy”. The first request was
unauthenticated. The two orange messages inform us that
request-acl ASK-AUTH
was selected and response 407
was returned to the browser. After the user filled in the authentication
dialog, the request was repeated. The user name and password were correct,
user guest
was authenticated
successfully, and request-acl ALL-2
was selected,
as indicated by the two green messages.
Because many Web browsers do not expect to be required to perform proxy authentication when no HTTP proxy is configured in the browser, proxy authentication may not work with a transparent proxy. It is possible in such a case that users are displayed a 407 error page instead of the authentication dialog. Use proxy user authentication with a non-transparent HTTP proxy only, unless you check that Web browsers on your client machines handle it correctly with a transparent HTTP proxy.
The Kerberos authentication is an alternative to the Basic authentication described in Section 14.3, “Basic Authentication in HTTP Proxy”. It provides a single-sign-on capability for clients authenticated in an Active Directory domain or a Kerberos realm. If a user is logged in a domain, or has a valid Kerberos ticket, a Kerberos-capable Web browser can authenticate the user to the proxy automatically, without asking the user for a name and a password.
Kerberos authentication in Active Directory is supported for Microsoft Windows server and Samba 4 acting as an Active Directory domain controller. Older Samba versions (3.x) cannot be configured as an AD domain controller.
Authentication to a Samba server uses different
authentication mechanism than a MS Windows Server by default. This
authentication mechanism (GSS-SPNEGO) fails and may allocate all available
memory. Hence, the client (Kernun http-proxy) should be
configured to use GSSAPI instead. This can be done by adding file
.ldaprc
to the root directory and to home directories
of users involved in authentication (root
and kernun
). The file should contain line:
SASL_MECH GSSAPI
If an HTTP proxy uses the Kerberos authentication, it cannot be run chrooted, because it needs access to some system components that are not contained in the standard Kernun chroot environment.
An example of a Kerberos configuration is stored in the sample
configuration file
/usr/local/kernun/conf/samples/cml/kerberos-auth.cml
.
The system
section contains global configuration related
to the Kerberos authentication in section kerberos-auth
,
Figure 5.45, “Kerberos authentication — section
system
”. Two parameters are required:
the name of the Active Directory domain (or Kerberos realm)
domain
and the address of the domain controller (or the
Kerberos KDC) ad-controller
. The Kerberos authentication
itself provides the name of an authenticated user to the proxy.
A request-acl
can be selected according to the user name
or group membership. For the latter option, the proxy needs to know the
list of groups the user belongs to. The list can be obtained from an LDAP
server. As the Active Directory contains all the necessary information and
provides LDAP interface, the Active Directory controller is usually used
as the LDAP server. Obtaining group membership can be configured by
unhiding the hidden item ldap
and section
ldap-client-auth
in the sample configuration in Figure 5.45, “Kerberos authentication — section
system
”. The URL of the LDAP server references
the Active Directory controller. The proxy authenticates itself to the
LDAP server by Kerberos using the machine account of the Kernun system in
the Active Directory. The Kerberos authentication for LDAP is enabled by
ldap-client-auth.kerberos
. Alternatively, the proxy can
authenticate itself using a name and a password of a user with the
permission to access the Active Directory contents for reading. The user's
credentials must be specified in the bindinfo
item in
place of
, and the
corresponding password in place of
ADUser
. The Active
Directory stores user account data
in a different format than other LDAP servers used for LDAP authentication.
The Active Directory format must be selected by item
ldap-password
active-directory
, which also specifies the domain name.
The Active Directory domain name must be written using UPPERCASE LETTERS in the configuration.
A user's primary group name (usually Domain Users
) is neither logged nor
matched by request-acl.user.group
.
The Kerberos configuration can be enabled in an HTTP proxy by item
session-acl.kerberos-auth
. Outcome of the Kerberos
authentication is processed like the Basic authentication. The user name,
optional list of groups, or the fact that the authentication failed, can
be used as conditions in request-acl
sections. There is
usually one or more request ACLs that permit access to successfully
authenticated users and one request ACL that denies access to
unauthenticated users and asks for authentication. The sample
configuration in Figure 5.46, “Kerberos authentication — section
http-proxy
” allows
access to any authenticated user
(request-acl AUTH-OK
). Users that are not
authenticated are requested to perform authentication by
request-acl AUTH-REQ
.
In the Kerberos and LDAP configurations presented so far, user and
group names are matched in ACLs and written to logs in a short form,
without information about domains they belongs to. This may not be
sufficient in a multi-domain environment, where different domains may
contain users and groups with the same names. Such a multi-domain
environment can comprise either domains in a single Active Directory
forest, or even domains from several forests if there are explicit trusts
between forests[31]. Configuration item
kerberos-auth.user-match full
switches to using long
user name in logs and ACLs in format
“user@REALM
” instead of the default short
format “user
”. Likewise, adding value
“group-match domain”
to item
ldap-client-auth.active-directory
enables using long
group names “group@domain
”.
The LDAP server on each Active Directory controller returns only
data from its own domain. Hence, group membership of a user must be
queried in the domain which the user belongs to. The proxy is able to
select the LDAP server according to the domain name of the authenticated
user. To do this, there must be an ldap-client-auth
section for each domain. Section kerberos-auth
must
contain item ldap domain
, instead of naming a single
ldap-client-auth
section. Then the
ldap-client-auth
section will be selected by its Active
Directory domain name (specified in item
active-directory
).
Information about membership of Kerberos-authenticated users in
groups can be cached in order to decrease load of LDAP servers.
Configuration of caching consists of adding the global section
oob-auth OOB
and referencing it by item
http-proxy.oob-auth-srv
. Cached group membership
information for a user name expires after a timeout controlled by items
kerberos-auth.timeout-idle
(expiration after a period of
inactivity) and kerberos-auth.timeout-unauth
(unconditional expiration).
The Kerberos authentication requires some initialization steps before in order to start working. There are two supported methods of initialization.
In order to work correctly, Kerberos authentication requires several conditions to be fulfilled:
The Kernun system and the Active Directory domain controller must have their system time synchronized. By default, maximum allowable clock difference is 5 min. It is possible to synchronize Kernun system's clock to the Active Directory time by configuring the domain controller as an NTP server in the Kernun configuration.
The Kernun system must resolve the domain name of the Active Directory domain controller to the correct IP address. The reverse resolution of this IP address must also work and yield the original domain name used for the forward resolution as the first name of the response.
The first method adds the Kernun system to the Active Directory
domain by deleting its machine account if it already exists and creating
a new machine account. Then it sets up the Kerberos keytab with all keys
necessary for authentication and obtaining group membership information.
A user account
in the
Active Directory with user
Domain Admins
rights is required for
this task. The initialization process is performed by issuing shell
commands on the Kernun system:
#
kinit
user
#
ldapdelete -v -H ldap://
ADC
cn=COMPUTER
,cn=Computers,dc=D1
,dc=D2...
#
msktutil -c --computer-name `hostname -s` -s HTTP/`hostname` \ -h `hostname` --server
ADC
--no-pac#
chown kernun /etc/krb5.keytab
where
is the
address of the domain controller, and ADC
are
components of the Active Directory domain name (e.g., for domain
D1, D2, ...
example.com
, we use
dc=example,dc=com
). The computer account name
will
be the value of COMPUTER
--computer-name
with appended character
'$'
. If the default computer account name
`hostname -s`
is used, a command for automatic
password renewal (msktutil --auto-update) will be
added to /etc/crontab
. It is possible to choose
another computer account name. A non-default name must be configured in
the http-proxy by setting
kerberos-auth.kinit
to
"
. In this case,
the machine account password renewal must be handled manually, or (better)
password expiration must be turned off for the account by option
computername
$"--dont-expire-password
of msktutil.
The computer account name must be entered to the
configuration with the appended character '$'
.
Example: The initialization commands will be, for the domain
administrator admin
, the Active
Directory domain EXAMPLE.COM
,
the domain controller ad.example.com
, and the Kernun system
kernun.example.com
:
#
kinit admin
#
ldapdelete -v -H ldap://ad.example.com \ 'cn=kernun$,cn=Computers,dc=example,dc=com'
#
msktutil -c --computer-name `hostname -s` -s HTTP/`hostname` \ -h `hostname` --server ad.example.com --no-pac
#
chown kernun /etc/krb5.keytab
If clients should access the proxy via a name different from the
fully qualified host name of the Kernun system, that name must be
specified in the -s
argument of the
msktutil command. The same name must be configured in
kerberos-auth.proxy-host
or
session-acl.kerberos-auth
.
Instead of saving the created keytab into the default location
/etc/krb5.keytab
, another file name can by set by
adding option
-k
to the
msktutil command line. The custom keytab location must
be configured as a keytab_file
shared-file
referenced from
kerberos-auth.keytab
.
If the system is to be removed from the domain later (when Kerberos
authentication is no more required or if the system will be moved to
another domain), remove file /etc/krb5.keytab
and
delete the machine account on the Active Directory Controller.
The second method of Kerberos initialization comprises generating a keytab on the Active Directory controller, transferring the keytab to the Kernun system, and configuring Kernun to use the keytab. The initialization procedure consists of several steps:
Create a user account in the Active Directory. The
account must be configured so that its password never
expires and it must have enough rigths to read user and group
information from the Active Directory (usually, membership
in the Domain Users
group suffices).
Generate the keytab using the command line on the domain controller:
C:\>
ktpass /out
KEYTAB
/princ HTTP/PROXY
@AD_DOMAIN
/mapuserUSER
@AD_DOMAIN
/pass * /crypto All /ptype KRB5_NT_PRINCIPAL
where the parameters are:
KEYTAB
The file name for the created keytab file.
PROXY
The proxy name used by clients. If it it not the
fully qualified host name of the Kernun system, the name must be
configured in kerberos-auth.proxy-host
or
session-acl.kerberos-auth
.
AD_DOMAIN
The Active Directory domain name, in upper case.
USER
The name of the user created in step 1. The command will
request entering this user's password. Alternatively, the password
may be specified on the command line by
/pass
instead of PASSWD
/para *
.
Copy the keytab to the Kernun system or to the computer running Kernun GUI.
Configure the keytab as a shared-file
and add
a reference to this shared file into
kerberos-auth.keytab
. The keytab shared-file should
be stored in a location included in backup and upgrade, for example,
/usr/local/kernun/conf
.
Set kerberos-auth.kinit
to the proxy principal
name HTTP/
.PROXY
Example: The keytab creation command will be, for the Kernun user
account kernun
, the Active
Directory domain EXAMPLE.COM
,
the Kernun system kernun.example.com
, and the output keytab
file krb5.keytab
:
C:\>
ktpass /out krb5.keytab /princ HTTP/kernun.example.com@EXAMPLE.COM /mapuser kernun@EXAMPLE.COM /pass * /crypto All /ptype KRB5_NT_PRINCIPAL
Configuring a keytab as a shared file makes easy distribution of the keytab to cluster nodes.
If Kerberos authentication is no more required, remove the keytab from the Kernun system and delete the user account from the Active Directory controller.
As was already mentioned, web browsers usually refuse proxy authentication on a transparent HTTP proxy. This problem can be solved by redirecting an unauthenticated transparent HTTP request to an authentication server. The server performs authentication, remembers the association of an IP address to a user name in the out-of-band authentication table, and redirects the request back to the origin server. As the Kerberos authentication is done in the background, it is invisible to the user.
An example of a Kerberos transparent proxy configuration is stored in
the sample configuration file
/usr/local/kernun/conf/samples/cml/kerberos-auth-transp.cml
.
The proxy must be configured as an OOB authentication server by
adding the oob-auth
global configuration section and
referencing it by item http-proxy.oob-auth-srv
. Kerberos
and optional LDAP configuration is like in the non-transparent case, see
Figure 5.45, “Kerberos authentication — section
system
”.
The HTTP proxy configuration is shown in Figure 5.47, “Transparent Kerberos authentication — session ACLs” and Figure 5.48, “Transparent Kerberos authentication — request ACLs”. Global
acl INTOK-AUTH
and the corresponding
session-acl INTOK-AUTH
handle transparent requests to
origin servers. These requests are authenticated using out-of-band
authentication. Authenticated users are passed by
request-acl HTTP-OK
. If a user is not authenticated,
the request will be redirected to the authentication server by
request-acl HTTP-RDR
. Redirected requests are handled
by global acl HTTP-AUTH
and the corresponding
session-acl HTTP-AUTH
. The client is asked for
Kerberos authentication by request-acl AUTH-REQ
.
Authentication is performed by the browser without asking the user for
a name or a password. Then request-acl AUTH-OK
stores
the IP address of the successfully authenticated user into the out-of-band
table and redirects the browser to the originally requested URI. Further
requests use OOB authentication and are handled without redirection to the
authentication server.
In Firefox, Kerberos authentication must be explicitly
enabled for each server, in our example fw.pha.tns.cz
. It can be done by typing
a special uri about:config
into the address line to show
advanced settings, and then setting the server name to option
network.negotiate-auth.trusted-uris
.
Internet Explorer, Chrome and Opera users may be prompted for a password to authenticate to the authentication server. To avoid it they must configure the browser for automatic logon. To do this
Go to the Internet Options
dialog
box, on the Security
tab select Local
intranet
, and then click Custom
Level
.
In the Security Settings
dialog
box, under Logon
, select Automatic
logon
only in Intranet zone
, and then
click OK
.
In the Internet Options
dialog box
on the Security Settings
tab with Local
intranet
still selected, click Sites
.
In the Local intranet
dialog box,
click Advanced
.
In the next dialog box (also titled Local
intranet
), type the URL of the authentication server
http://fw.pha.tns.cz:8080/ in the Add this Web site to the
zone box
, and then click Add
.
The NTLM authentication is an alternative to the Basic authentication described in Section 14.3, “Basic Authentication in HTTP Proxy”. It provides a single-sign-on capability for Microsoft Windows clients authenticated in an Active Directory domain. If a user is logged in a domain, an NTLM-capable Web browser can authenticate the user to the proxy automatically, without asking the user for a name and a password. The NTLM authentication can be used instead of the Basic authentication, or both authentication methods can be used together. In an NTLM-only configuration, clients incapable of the NTLM authentication cannot authenticate. In a configuration with both authentication methods, an NTLM-capable client uses NTLM and other clients use Basic.
If an HTTP proxy uses the NTLM authentication, it cannot be run chrooted, because it needs access to some system components that are not contained in the standard Kernun chroot environment.
The DNS domain name of the Active Directory controller
must correspond to the Active Directory domain name. For example, a domain
controller for the domain tns.cz
should be named like ad.tns.cz
.
An example of an NTLM configuration is stored in the sample
configuration file
/usr/local/kernun/conf/samples/cml/ntlm-auth.cml
.
The system
section contains global configuration related to
the NTLM authentication in section ntlm-auth
, see Figure 5.49, “NTLM authentication — section
system
”. Two
parameters are required: the name of the Active Directory domain
(domain
) and the address of the domain controller
(ad-controller
). The NTLM authentication itself provides
the name of an authenticated user to the proxy.
A request-acl
can be selected according to the user name
or group membership. For the latter option, the proxy needs to know the
list of groups the user belongs to. The list can be obtained from an LDAP
server. As the Active Directory contains all the necessary information and
provides LDAP interface, the Active Directory controller is usually used
as the LDAP server. Obtaining group membership can be configured by
unhiding the hidden item ldap
and section
ldap-client-auth
in the sample configuration in Figure 5.49, “NTLM authentication — section
system
”. The URL of the LDAP server references
the Active Directory controller. A user with the permission to access the
Active Directory contents for reading must be specified in the
bindinfo
item in place of
, and
the corresponding password in place of
ADUser
. The
Active Directory stores user account data
in a different format than other LDAP servers used for LDAP authentication.
The Active Directory format must be selected by item
ldap-password
active-directory
, which also specifies the domain name.
The NTLM configuration can be enabled in an HTTP proxy by item
session-acl.ntlm-auth
. Outcome of the NTLM authentication
is processed like the Basic authentication. The user name, optional list
of groups, or the fact that the authentication failed, can be used as
conditions in request-acl
sections. There is usually one
or more request ACLs that permit access to successfully authenticated
users and one request ACL that denies access to unauthenticated users and
asks for authentication. The sample configuration in Figure 5.50, “NTLM authentication — section
http-proxy
” allows access to any authenticated
user (request-acl AUTH-OK
). Users that are not
authenticated are requested to perform authentication by
request-acl AUTH-REQ
.
Administrators often want to enable the more user-friendly NTLM
authentication and to provide an alternative for clients that are not
capable of the NTLM authentication. Such a configuration can be created by
setting both items ntlm-auth
and
auth
in the same session-acl
, for
example, by unhiding the line
“hidden auth passwd ...
” in
Figure 5.50, “NTLM authentication — section
http-proxy
”. The proxy will offer both NTLM
and Basic authentication schemes. The client can choose any of
them[32].
After the NTLM authentication is configured and the configuration
applied to a Kernun system, it is necessary to add the Kernun system to
the Active Directory domain. A user account
in the Active Directory with
user
Domain Admins
rights is
required for this task. The Kernun system is added to the domain by the
shell command
#
net ads join -U
user
The system should then be rebooted in order to initialize and start the system components that provide an interface between the proxy and the Active Directory controller[33]. If the NTLM authentication is no more required, or if the Active Directory domain or the domain controller changes, the system should be removed from the domain by the shell command
#
net ads leave -U
user
It can be later added to another domain by
net ads join
.
Membership of a Kernun system in an Active Directory domain can be tested
by the shell command wbinfo -t
. If the system
has been successfully added to a domain, we get:
#
wbinfo -t; echo $?
checking the trust secret via RPC calls succeeded 0
Otherwise, the output is:
#
wbinfo -t; echo $?
checking the trust secret via RPC calls failed error code was NT_STATUS_NO_TRUST_SAM_ACCOUNT (0xc000018b) Could not check secret 1
Results of NTLM authentication can be cached by out-of-band authentication (see also Section 14.8, “Out of Band Authentication”), in order to decrease load of Active Directory and LDAP servers. Each new client is authenticated by NTLM. The combination of the client IP address, the user name and the list of groups is remembered in the OOB session table. Following requests from the same IP address will be authenticated as the same user and groups, without contacting the AD controller and the LDAP server. Computer accounts (i.e. users whose name ends with a dollar) are not added to the OOB session table.
Configuration of NTLM caching consists of adding the global section
oob-auth OOB
, referencing it by item
http-proxy.oob-auth-srv
, and adding item
auth oob OOB
to each
session-acl
that contains item
ntlm-auth
. Cached user and group information for a client
IP address expires after a timeout controlled by items
ntlm-auth.timeout-idle
(expiration after a period of
inactivity) and ntlm-auth.timeout-unauth
(unconditional
expiration).
The preferred authentication method in Active Directory environment is Kerberos, see Section 14.4, “Kerberos Authentication in HTTP Proxy”.
The HTTP proxy can be used to control access to a Web server in the protected network[34] from clients in the external network. A typical situation is a Web interface to a corporate mail server accessed by employees from machines in the Internet, for example from their homes. In such a case, the security policy often requires the use of sessions with limited lifetime authenticated by a strong mechanism, such as a challenge-response protocol that utilizes one-time passwords generated by hardware authentication tokens. Also, as we mentioned in Section 14.3, “Basic Authentication in HTTP Proxy”, HTTP proxy authentication does not often work if the proxy is not configured in the browser explicitly. For such situations, there is a special operation mode of the HTTP proxy, called the HTTP authentication proxy, or AProxy for short.
A typical AProxy configuration is displayed in Figure 5.51, “Configuration of the HTTP authentication proxy”. It is a configuration for access from
clients in the Internet to the server intweb.tns.cz
in the internal
network. As the Internet is an untrusted network, the connections from
clients are secured by TLS, which is enabled by the
ssl-params APROXY-SSL
section and the
client-ssl
item in session-acl APROXY-EXT
. The internal network is
considered secure, therefore plain unencrypted HTTP is used. (For
detailed explanation of SSL/TLS in Kernun UTM, see Section 13, “Secure Communication Using SSL/TLS”.)
The configuration section aproxy APROXY
defines
various parameters of the AProxy. The example contains only the
auth
item, which defines that the AProxy will verify user
credentials against a local password file. The default maximum session
time after a successful authentication is one hour. After that time, the
user is logged out and must authenticate again. Also, if the session is
idle—the client does not issue any request—for more than
5 minutes, the user must reauthenticate. These default timeout values
can be changed by items timeout-unauth
and
timeout-idle
of section aproxy
.
Further configurable AProxy parameters are described in
http-proxy(5).
The AProxy mode is activated by the aproxy
item of
a session-acl
. The user name obtained during AProxy
authentication can be used to select a request-acl
, by
matching an aproxy-user
item. In the sample
configuration, a client accesses the AProxy by connecting to the
external IP address of Kernun UTM. If authentication succeeds, the HTTP
requests from the client are passed to the internal server defined by
plug-to
.
An AProxy session cookie is a sensitive piece of
information and should be kept secret, because an attacker could use it to
steal the identity of an authenticated user. Hence, the AProxy is usually
configured so that the connections between clients and the proxy are
secured by SSL/TLS (see Section 13, “Secure Communication Using SSL/TLS”). It is possible to
operate the AProxy using plain HTTP by enabling
aproxy.insecure-cookies
and not configuring
client-ssl
on the client side of the proxy, but it is
strongly recommended not to so unless the clients are connected
to Kernun UTM via a trusted network.
A user starts by entering an AProxy URL to a Web browser. The AProxy returns an authentication dialog, as displayed in Figure 5.52, “The user authentication dialog of the HTTP authentication proxy”. The user fills in their login name and password and clicks . If a challenge-response authentication protocol is used[35], the user must fill in the login name only. The AProxy then displays a challenge and the user enters the response (obtained, e.g., from a hardware authentication token). If the authentication succeeds, a new session is initiated and the AProxy forwards the original HTTP request to the destination server. Further requests do not require reauthentication and are transparently passed to the server. The user must authenticate again only if the session expires because of a timeout. It is also possible to log out and terminate the session explicitly by accessing a special logout URL, as shown in Figure 5.53, “The logout confirmation message of the HTTP authentication proxy”.
The HTML authentication forms displayed by the AProxy are very
simple, but their appearance is easy to modify. Form templates
are stored in the
/usr/local/kernun/conf/samples/error_documents
directory.
The template files are: aproxy-password-form.html
(the form with user name and password fields),
aproxy-password-form.html
(the form with a response
field for challenge-response authentication), and
aproxy-logout.html
(the logout message).
The AProxy uses cookies to track sessions. The cookies are added to HTTP response messages by the proxy, but they appear to the client as coming from the server. The session cookies are then extracted by the proxy from the requests. As a cookie received from a server is never sent to other servers, it is impractical to use the AProxy for authentication of clients in the internal network accessing Web servers in the Internet.
Many application protocols do not support user authentication on a proxy. Even in protocols with a proxy authentication mechanism it may be undesirable to use it in some situations. Nevertheless, we may still want to perform access control and network usage monitoring for individual users. The out-of-band authentication (OOBA) provides a solution in such cases. It is based on the fact that for any network protocol, the proxy knows the IP address of the client machine. The OOBA simply binds user names with IP addresses. There is an OOBA server, which maintains a table containing pairs of user names and IP addresses. When a proxy accepts a new network connection, it sends the client IP address to the authentication server and receives the corresponding user name or the information that no user is authenticated from that IP address. As is the case with other authentication methods, the user name can be used as a condition for ACL selection.
As the out-of-band authentication cannot distinguish connections from a single IP address, more than one user cannot be authenticated on a single client machine at the same time. For this reason, computer accounts (i.e. users whose name ends with a dollar) are not automatically added to the OOB session table. On the other hand, one user can be authenticated on many machines simultaneously.
A sample configuration of the OOB authentication is displayed in
Figure 5.54, “Configuration of the out-of-band authentication”, with
http-proxy HTTP-OOBA
serving as the OOB
authentication server, and tcp-proxy HTTPS
, which
allows access only to users authenticated by the OOBA. The
oob-auth OOBA
section
defines parameters of the OOB authentication. Only the authentication
method is specified in this example. See
auth(5) for description of all available
parameters. This session is referenced in
http-proxy HTTP-OOBA
by the
oob-auth-srv
item. The HTTP proxy is switched to the OOBA
mode by adding the oob-auth
item to an aproxy
section and referencing this section by a session-acl
.
In the sample configuration, a password file is used to check user names
and passwords. As the OOBA is performed in the internal network, which is
assumed to be secure, plain HTTP without SSL/TLS is used, which is why
insecure-cookies
needs to be added to the
aproxy
section.
The html-form
OOB authentication method is selected in
the sample configuration. It authenticates users interactively in the
same way as the AProxy (Section 14.7, “HTTP Authentication Proxy”). The alternative
option, external
(marked as
hidden
in the sample configuration),
is to import the list of authenticated users from a server in the
network. The external OOBA is fully transparent. Users do not have to do
anything special, they just log in to the server that provides data to the
Kernun UTM OOB authentication server. Out of the box, Kernun UTM contains the
ooba-samba(1) script, which implements integration
with Samba.
The tcp-proxy HTTPS
proxy uses the OOB
authentication and accepts authenticated users only. The
OOBA is activated by setting the oob
method in the
auth
item. The OOBA server and proxies that provide OOBA
communicate via a session table file. Therefore, they must all reference
the same file in the oob-auth
sessions they use. If no
file is specified, as in our example, a common default file will be
used. The authenticated user name could be matched by
a session-acl
. Another way to reject
unauthenticated users without creating a denying ACL for them is to add
the required
parameter to the auth
item. It
causes immediate termination of sessions initiated by unauthenticated
users, even before ACL matching begins.
When the html-form
OOBA method is used, a user must
access the authentication page (Figure 5.52, “The user authentication dialog of the HTTP authentication
proxy”) by
opening the OOBA server URL in a Web
browser. After entering a valid name and password, a login confirmation
page is displayed, see Figure 5.55, “Login to the OOB authentication server”. It contains
a link that can be used to log the user out. Like in the case of AProxy,
the authentication pages displayed by the OOB authentication server can be
changed by modifying template files in
/usr/local/kernun/conf/samples/error_documents
.
There are two more OOBA authentication forms, ooba-login-confirm.html
(login confirmation) and ooba-logout-confirm.html
(logout confirmation), in addition to the AProxy ones, which are reused.
Kernun UTM can cooperate with the Dr.WEB or ClamAV antivirus programs
and any other antivirus program that supports ICAP protocol, e.g. Kaspersky
Anti-Virus for Proxy Server. This tutorial describes the configuration
of Kernun UTM only (that is, not the installation and configuration of the
antivirus programs). The complete configuration file is located in
/usr/local/kernun/conf/samples/cml/antivirus.cml
.
The ClamAV antivirus program can be installed either directly on Kernun UTM or on any other machine connected via the network. The administrator of Kernun UTM can choose either of two ways to transport files between Kernun UTM and ClamAV:
clamav-net
: Files to be checked by
the antivirus are sent to the antivirus via the TCP
connection.
clamav-file
: Files to be checked by
the antivirus are stored on the local file system. This
option can be only used if the antivirus program is running on the
same machine as Kernun UTM. The directory where the files are
stored is defined by the comm-dir
element (which
defaults to /data/tmp/antivirus
). Kernun UTM does not
create the directory (it must be explicitly created by the
administrator), and proper permissions need to be set (i.e., the
directory must be writable by proxy-user
).
The IP address and the port the antivirus program listens on
are specified in the section antivirus
on the
system
level of Kernun UTM's configuration, as
shown in Figure 5.56, “Configuration of the connection to the antivirus program” (we
suppose ClamAV listens on localhost's port 3310). It is possible
to limit the size (max-checked-size
) of files
scanned by the antivirus program. In the sample configuration, it
is 1 MB. Larger files are not scanned and the antivirus module
immediately reports the result as
SKIPPED
.
The Internet Content Adaptation Protocol (ICAP) is a lightweight HTTP-like protocol used to communicate with antivirus program. Kernun UTM makes use of it's Response Modification Mode to send data to be checked. Antivirus program sends back it's test results.
The IP address and the port the antivirus ICAP server listens
on are specified in the section antivirus
on the
system
level of Kernun UTM's configuration, as
shown in Figure 5.57, “Configuration of the connection to the antivirus program via ICAP”
(in this example it's 10.0.0.33
and standard
ICAP port, 1344
). The third parameter of
connection
item (/av/respmod
in this example) is an URI of the antivirus' Response Modification
Mode handler. Again, it is possible to limit the size
(max-checked-size
) of files scanned
by the antivirus program.
There are five possible results of a check of content by the antivirus:
The antivirus has scanned the data and has not found any virus.
At least one virus has been found.
The antivirus has not scanned the data. Either the
antivirus itself has decided not to scan, or the file has been
larger than the limit specified by
max-checked-size
. No virus has been found, but
the antivirus has not confirmed that the data is
virus-free.
The proxy has received a result from the antivirus, but does not understand it. It is not known whether there is any virus in the data, or not.
The proxy cannot communicate with the antivirus. This is usually caused by the antivirus not running or by misconfigured antivirus connection in the proxy.
The antivirus program can be used for online scanning of the
content transferred via ftp-proxy
,
http-proxy
, imap4-proxy
,
pop3-proxy
and smtp-proxy
. There is a
slight difference between mail-processing proxies
(imap4-proxy
, pop3-proxy
and
smtp-proxy
) and the other two
(http-proxy
and ftp-proxy
). In the
latter case, a special functionality is implemented that prevents clients
from reaching a timeout while very long files are being scanned. The
client is fed with chunks of the file at specified intervals until the
scanning of the file is completed.
Document scanning for the HTTP and FTP proxies is configured in
their doc-acl
. The antivirus
item
specifies the name of the antivirus
section to be used.
The interval
, chunk
and
limit
items can be used optionally to specify that
if scanning takes more than a certain time (5 seconds in the example),
a chunk of the (as yet unscanned) file of a certain size (up to 2,000 bytes)
is to be sent to the client at a certain interval (5 seconds). By default,
only documents for which the antivirus returns the result
free
are passed by the proxy. The
doc-acl.accept-antivirus-status
item can be used to specify
additional result codes, for which the checked data are to be passed, in
addition to free
.
We will describe two variants of smtp-proxy
configuration, differing in the way they handle
infected mail. In this section, we show the case
when infected mail is discarded, i.e. not sent to the
recipient(s), but stored in quarantine.
In smtp-proxy
, the item
use-antivirus
is used to define antivirus.
Infected mail is detected in the mail-acl
sections. One of them, a mail-acl
accepting all
e-mails (MAILOK
), already exists in the
Kernun UTM configuration. We will create more to process messages
with various antivirus scan results (see Figure 5.59, “Discarding infected messages in the SMTP proxy”).
When smtp-proxy
processes mail, the first
matching ACL is used. We must therefore place new
mail-acl
sections before the existing
MAILOK
.
The first added mail-acl
,
VIRUS
, discards infected mail
and puts it in quarantine. Its only entry condition is
virus-status
. It is matched if the
virus-status
of the message is
found
(i.e., it contains a document that
is infected by a virus). We define three actions:
discard
the message (i.e., the sender
is not returned an error), deny
it
(the message is not sent to the addressee) and store the
e-mail in quarantine
.
The quarantine directory must be defined (the
quarantine
item in the
smtp-proxy
section) and created in the file
system (e.g.,
/usr/local/kernun/root/var/quarantine
,
keeping in mind the smtp-proxy
runs in
chroot), and writable by kernun-user
. For more
information about ways of handling mail stored in quarantine,
see quarc.sh(1).
There are two more mail-acl
sections.
AV-ERROR
reports a transient error to the client if
the the antivirus is unable to check the message. The client can retry
sending the mail later. AV-UNKNOWN
discards and
quarantines the message if the antivirus does not scan it or if the
proxy cannot understand the antivirus' reply.
Contrary to the previous example, this section
describes a way to prevent infected mail from being discarded.
This example refers to smtp-proxy SMTP-2
,
which is marked hidden in the sample file[36].
This time,
smtp-proxy
removes the infected documents from
the message and delivers the e-mail to the addressee, sending a BCC copy to
a special (administrator's) e-mail
address. Moreover, the subject is changed to make it obvious that a
virus was removed from the message.
smtp-proxy
also stores infected mail in
quarantine. The configuration is depicted in Figure 5.60, “Replacing infected documents in the SMTP proxy”
The removal of infected document is ensured by creating a
special doc-acl DOC-INFECTED
section that matches
the infected documents. We place it in front of the existing
doc-acl DOCOK
in order to match before the
more generic doc-acl DOCOK
. The entry condition
virus-status found
limits the acl
scope to the infected documents (documents marked by the
antivirus program as containing a virus). We add the action item
replace
so that the matched (and therefore
infected) document is replaced by the given file. The
administrator must explicitly create this file if it does
not exist. Because the proxy is configured to run in chroot
environment, the file must be stored in the particular
subdirectory of the directory specified as
chroot-dir
(in this case,
/usr/local/kernun/root/etc/shared/error_documents/
).
The special behavior for infected e-mails (i.e., the
messages that contain an infected document) is defined in
mail-acl VIRUS
. The entry condition
virus-status found
limits the acl scope to
infected e-mails. The accept
item specifies
that the e-mail should be delivered to the addressee. We specify that
the message is to be stored in the quarantine, that a BCC copy be sent to a
special e-mail address (the copy-to
item) and that
the subject be prefixed with a specified text (the
prefix-subject
item).
Like in SMTP
, there is an additional
mail-acl AV-ERROR
that returns a transient error
to the client if the mail cannot be checked by the antivirus.
Finally, doc-acl REPLACE-AV-UNKNOWN
replaces
documents that are skipped by the antivirus.
In this section, we show the POP3 and the IMAP4 proxies configured to replace infected documents. See the Figure 5.61, “Replacing infected documents in the POP3 proxy” and Figure 5.62, “Replacing infected documents in the IMAP4 proxy”
First, we instruct Kernun UTM to scan the documents transferred
through the proxy with the antivirus by specifying
the item use-antivirus
. The item is specified
directly in command-acl
for the POP3 proxy, whereas
for IMAP4 proxy, it is specified separately for the
download
and for the upload
case.
In the second-level acl (mail-acl MAILOK
), we
specify that all e-mails should be accepted. In the third-level
acl, we specify that we want to replace infected
(doc-acl REPLACE-INFECTED
) and unscanned
(doc-acl REPLACE-AV-UNKNOWN
) documents, and to accept
all other documents (DOCOK
)[37].
Kernun UTM can cooperate with the SpamAssassin antispam software to reject or mark spam. Three more methods can be used in addition to the SpamAssassin protection: black-listing (rejection of mail from senders with addresses listed in an external database), white-listing (authorisation of the sender on his or her domain server) and grey-listing (an automatic method based on a local database). We will discuss the configuration of antispam first, and then briefly describe the individual methods in the next sub-chapter.
Like the Dr.WEB or ClamAV antivirus programs, you can install
SpamAssassin either directly on Kernun UTM or on any other machine
connected via the network. The antispam configuration in Kernun UTM is
analogous to the antivirus configuration. We define the
antispam
section on the system
level,
and we reference this section in the mail processing proxies
(smtp-proxy
, pop3-proxy
, and
imap4-proxy
).
We can use the results of the antispam check in the spam-score
item[38] in the mail-acl
section of the spam-checked proxy.
Having configured the SPAMASSASSIN
section, we
now reference it in the proxies. We replace the item no-mail-scanning
(in the
command-acl
section) with use-antispam enable SPAMASSASSIN 100K
.
Antispam checking is a very demanding operation, and typical spam mails are quite small. You may therefore want to check only messages below a certain limit size, such as 100 kB in our case.
Because we deleted the no-mail-scanning
item, Kernun UTM will search for
matching mail-acl
and doc-acl
sections and we must
therefore create them. (Otherwise, Kernun UTM's default reaction would be to
reject the mail.) We create a mail-acl
section that will mark spammed e-mails, but deliver them to the recipient(s).
We do so by adding an acl condition spam-score
and setting it to accept e-mails with a spam score exceeding 5.0 (we use the relational
operator ge
; the Kernun UTM spam score of 5000 corresponds to SpamAssassin's
score of 5.0 multiplied by 1000). We specify that such messages will be accepted, but define
a prefix-subject
item that adds a text prefix to their subject.
Finally, we add accepting mail-acl
and
doc-acl
and we get the configuration shown in
Figure 5.63, “Antispam protection for POP3 proxy”.
Analogously, we can add antispam support to the IMAP4
proxy.
We add the use-antispam
items to both download
and upload
sections, and then create the mail-acl
and
doc-acl
sections. Figure 5.64, “Antispam protection for IMAP4 proxy” shows the antispam
configuration of imap4-proxy
.
The configuration of smtp-proxy
is, again,
similar to the previous cases, only this time we define the use-antispam
item
right inside the proxy. In this example we show how to deny mails with too high a spam score
and store them in quarantine on the server. We do so by specifying a quarantine
item in the proxy and setting it to the path of the quarantine directory.
Remember that we work under a chrooted environment, so we need to create that directory
inside the chroot (in our example, /usr/local/kernun/root/var/quarantine
).
We add a mail-acl
SPAMQUARANTINE
with items deny
to
not deliver messages with SpamAssassin score exceeding 10, discard
to not inform the sender
about the delivery failure and quarantine
to place the mail into the quarantine directory.
Another mail-acl
, SPAMMARK
, is
used to pass e-mails with the score of 5-10, but mark it with a subject prefix.
The relevant part of the SMTP proxy configuration with antispam is shown in
Figure 5.65, “Antispam protection for SMTP proxy”.
The resulting configuration of mail proxies with antispam is available in the
/usr/local/kernun/conf/samples/cml/antispam.cml
sample file.
For more information on antispam configuration, see the mod-antispam(5) manual page.
Kernun UTM's smtp-proxy
provides
configurable client identity checking as protection against unsolicited
mail. White-listing implemented in Kernun UTM is based on the Sender
Policy Framework (http://www.openspf.org), which checks if the
sender is allowed in the sender policy of the return path domain and thus
authorizes the sender. After inserting a white-listing
item into
session-acl
, the result of the matching can be used in the delivery-acl
section using the spf
condition.
On the other hand, the black-listing method checks the sender's address against an external database of
forbidden IP addresses. The sender's presence in such a database (for example http://www.spamhaus.org)
means that the e-mail is denied during the session-acl
phase.
The configuration of black- and white-listing is depicted in Figure 5.66, “White- and black-listing for SMTP proxy”. The list of the main
black-listing databases is defined in /usr/local/kernun/conf/samples/include/smtp-blacklist.cml
.
Grey-listing is a mail-filtering method that does not rely on any external database or domain information. Instead,
it creates its own database of triplets (sender IP, sender e-mail address, recipient e-mail address) and behaves according
to the state of triplet in the database. New e-mail is saved as blocked
and a temporary error
answer is sent to the sender. If the sender tries to redeliver the mail within a predefined period (e.g., after some time,
but not too late), the state of the triplet changes to granted
and all mail with the same
triplet will then be passed without any blocking time. The grey-listing method is configured by the
grey-listing
section in the delivery-acl
, and the grey-listing
section with a path
item set to the filename of the grey-listing database in smtp-proxy
.
A sample grey-listing configuration is shown in Figure 5.67, “Grey-listing for SMTP proxy”. For more detailed information about
the method, see the description of the
triplicator(1) tool.
Kernun UTM provides tools to investigate and filter the contents of the passing packets. These tools make it possible for the administrator to filter the contents of the HTML and mail traffic.
The third-level ACL, doc-acl
, has as an entry condition mime-type
specification (see access-control(7), configuration(7) manual pages). The content type detection can be performed using several different methods;
the administrator can set the order of the used methods globally for the whole proxy, or separately
for each of its doc-acl
s.
The following content-type detection methods are available:
(Original Content-Type) — the proxy uses the type
declared by the document originator in the Content-Type
header;
(File Name Extension Mapping) — the proxy tries to guess the MIME type from the name of the document (if specified);
(Magic Number Recognition) — the proxy reads the initial block of the document and tries to guess the file type from it with help of the magic number file (see magic(5) manual page).
Method magic
is skipped in the http-proxy
when
the response is partial and does not contain its beginning. Partial HTTP response either
contains HTTP header Range
or has content-type multipart/byteranges
.
The method magic
is always skipped when the content-type is multipart/byteranges
.
Item request-acl.delete-req-hdr-range
can be used to make the server send the entire response.
The common usage of mime-type
conditions is in the http-proxy
, where
the administrator can forbid selected types of documents (e.g., video, applications). In our example, we will
start with the initial configuration file, as shown in Section 2, “The Initial Configuration”, and deny all documents
recognized as any of the video mime-types for the http-proxy HTTP
.
First,
we need to specify the order of the used Content-Type detection methods. We add the doctype-identification
section into the http-proxy HTTP
, insert the order
item into
it and select the intended methods in its detail. In order to do so, we append three values magic
,
extension
and content-type
into the doctype-ident-method-list
order
field, leaving the field direction-set for
unchecked (it can be used to define
different order for each of the traffic directions — upload and download).
The magic
and extension
methods need further configuration: the former
a magic file and the latter a file that contains the extension to the
content-type mapping database. We specify them by adding two
shared-file
items pointing to the corresponding configuration files. In our example, we will use
the sample configuration file for magic
located in samples/shared/magic
and
the extension
configuration file located in samples/shared/mime.types
. We
configure the selected methods to use these shared files by inserting two new items
into the added doctype-identification
section.
The magic
item points to the name of the
magic configuration shared-file
and the mime-types
item
to the name of the extension configuration shared-file
.
Having configured the order of the used
Content-Type detection methods, we can proceed to the filtering of all video documents. We do so by inserting new
doc-acl
called VIDEO
into the http-proxy HTTP
section.
We will add it right above the doc-acl DOCOK
section, so that VIDEO
takes precedence.
We restrict the ACL to the video MIME type by inserting the mime-type
option.
We define the set of matching MIME types in str-set type
. In this example we insert a single item,
video
. In a more complex situation, regular expressions can be used to define all the types
to be matched for the ACL. Finally, we need to add the deny
item into the inserted
doc-acl VIDEO
. Figure 5.68, “Content Type detection configuration for HTTP proxy” shows the relevant part of configuration.
The resulting configuration file can be found among Kernun UTM samples
under the name doctype-detection.cml
in
/usr/local/kernun/conf/samples/cml
. For more detailed information on Content Type detection,
see the doctype-identification(7)
manual page.
Besides other tools used to filter whole packets and documents (URL filtering, antivirus checking, etc.), Kernun UTM
provides an HTML filter that filters (or replaces) elements and attributes inside an HTML document. The filter is applied
to every passing document on the third level of ACL processing, so it is applicable with all proxies that have the
doc-acl
section
(http-proxy
, imap4-proxy
, pop3-proxy
, etc.). The filter gets the
whole HTML document, and deletes (or replaces) undesirable elements and attributes according to the specified rules.
If there are no rules in the HTML filter,
the document will be passed “as-is”. If we create a rule of some type, all the matching elements (or attributes)
will be accepted/denied according to the matching rule. If no rule matches, but there is a rule of the element/attribute
type specified, the element/attribute will be denied.
For example, the administrator may want to deny all the Adobe Flash animations and replace all the URIs that refer to
“suspicious” Web sites. We create a system
-level html-filter
section
and name it HTMLFILTER
.
Now we need to add rules that will filter the elements and attributes of the document.
First, we want to filter all the Flash animations. These can be contained in two HTML elements, embed
and object
, so we need to delete these two elements, but not all of them – only those with the
application/x-shockwave-flash
Content-Type. We add an embed-tag-type
item, which represents
a filter rule that applies to embed
tags with the corresponding content type. Now, we need to specify the
content types we want to filter (either as whole Content-Type names or using regexps) and the action that is to
be done (accept
or deny
). We append one value, “application/x-shockwave-flash”
to str-set val
and select deny
from the action
combo box. Now, we have
filtered all the embed
HTML elements with flash animations. We can do the same with the
object
elements using the object
filter item set to the same values.
The items added so far filter out the undesirable contents.
However, it may be useful to warn the users that we have changed the documents they are viewing. We can do so
using the replace-
filter items, which define the content that will replace a deleted
element/attribute. For elements that can appear in both the head
and body
HTML elements (such as embed
and object
) we can set the replace text separately for each
of the two cases. In our sample, we will create a replace-body-embed-tags
item and set its value to “Flash
embed tag DENIED” and a replace-body-object-tags
item and set its value to “Flash object tag DENIED
”.
We must not forget to create accepting rules for both object
and embed-tag-type
that will accept all the Content Types. Otherwise, the previously added rules would
delete all the embed
and object
elements.
Clickjacking protection can be implemented by filtering IFRAME elements. This is done by adding iframe-tag-src
rules, which follow the convention stated above. The SRC of the IFRAME element is being matched as a regexp
(/^http:\/\/([^.]+\.)*kernun.com\//
in the example matches the domain kernun.com
and its subdomains).
The replacement text can be set by replace-iframe-tags
.
The HTML filter provides another type of useful rules: attribute filters. These
can be used to delete (or replace) whole attributes from the document. In our example, we want to replace all the
“suspicious” URI attributes with a neutral one. We will add a new uri
item rule and set it to
deny
the undesired URI regexps, in our case /.*photo.*/
,
/.*video.*/
and /.*warez.*/
. Again, as we have created a new filter rule, we need to allow
all other URIs that do not match this rule. We add a new uri
item and set it to accept
all the URIs (*
). Now we add the replacement for the whole URI attribute (not only the value that is
matched in the uri
item) by inserting a new replace-uri
item rule and setting it to a neutral URI,
for example "href='http://www.kernun.com'"
[39].
Having created the whole HTML filter, we can use it in any
proxy that has a third-level ACL doc-acl
. We tell the proxy to use an HTML filter by inserting an
html-filter
item with the filter's name into the proxy's doc-acl
. The use of
a slightly more complex HTML filter blocking all the Flash documents and the specified URIs in the http-proxy HTTP
is depicted in Figure 5.69, “HTML filter example”.
The complete resulting configuration can be found in /usr/local/kernun/conf/samples/cml/html-filter.cml
.
More complex HTML filter rules are created in /usr/local/kernun/conf/samples/include/html-filter.cml
.
For more information on HTML filtration, see the mod-html-filter(5) manual page.
In Section 2, “The Initial Configuration”, we created simple mail-handling proxies (smtp-proxy
,
imap4-proxy
and pop3-proxy
), which just passed the e-mail and did not check it in
any way. Kernun UTM provides tools to decode the e-mail MIME structure and examine
each document. The mail may be scanned for viruses (see Section 15, “Antivirus Checking of Data”) and
for spam content (see Section 16, “Antispam Processing of E-mail”). These scans are added to the proxy by
inserting a use-antivirus
and/or use-antispam
item into the proxy
and setting them to the respective antivirus/antispam section name.
Kernun UTM has also a mail filter, which can be used to repair the MIME structure and headers of the e-mail
according to corresponding RFCs, so that other mail servers could process the mail and possibly deliver it to the recipient(s).
Errors in e-mails that are to be corrected can be specified in the mail filter. The relevant part of a sample
configuration with a mail filter is shown in Figure 5.70, “Mail filter example in use with IMAP4, POP3 and SMTP proxies”; the entire configuration can be found
in /usr/local/kernun/conf/samples/cml/mime-processing.cml
.
For more information on MIME filtration, see the
mod-mail-doc(5) manual page.
Kernun UTM's HTTP proxy provides several methods that can be used to change
requestURIs passed to servers and make decisions based on URIs. A URI can be
matched against regular expressions, searched in a local database
(blacklist), or evaluated by the Kernun Clear Web DataBase or by an
external Web filter. The sample configuration
/usr/local/kernun/conf/samples/cml/url-filter.cml
contains an HTTP proxy with all URI filtering methods.
An example of the HTTP proxy that matches HTTP requests by the
request URI is depicted in Figure 5.71, “Request URI matching and rewriting”. If a request URI
matches one of the regular expressions in the string specified in the
request-uri
item of
request-acl URI-REWRITE
, this ACL will be selected.
It accepts the request and applies the rewrite
item(s). There
can be several rewrite
items. Each of them contains
a regular expression and a string. A request URI that matches the regular
expression in a rewrite
clause will be rewritten to the
string. Pairs of characters dollar+digit ($1
,
$2
…) in the string will be replaced by parts
of the original URI matched by parenthesized parts of the regular
expressions. The rewrite
item in Figure 5.71, “Request URI matching and rewriting” matches any URI containing
kernun.cz
and rewrites cz
to
com
, leaving the rest of the URI unchanged.
In a request-acl
, there are two more types of
URI-matching conditions. We have already seen
request-uri
, which matches the whole URI. The other
conditions are: request-scheme
(matches the scheme part
of the URI) and request-path
(matches the path part of
the URI).
Figure 5.72, “Log of URI matching and rewriting” shows a log of an HTTP proxy
running with the configuration from Figure 5.71, “Request URI matching and rewriting” and
processing a request with URI http://www.kernun.cz/
.
The two most important messages are marked. The
HTTH-811-I
message informs that
request-acl URI-REWRITE
was selected. The following
message confirms that the URI was rewritten to
http://www.kernun.com/
.
A security policy may require to deny access to large groups of Web
servers. Adding a very large number of servers to
a request-acl.request-uri
item may slow down ACL
processing significantly. A better strategy is to create
a blacklist of forbidden servers in a special
format processed more efficiently by the HTTP proxy. A blacklist must be
prepared in a text file in the format described in
mkblacklist(1). The textual blackist is then
transferred to a binary form usable by the HTTP proxy by utilities
resolveblacklist(1) and
mkblacklist(1). A binary blacklist file can be
converted back to the text format by
printblacklist(1).
A blacklist contains a list of Web server addresses (domain
names or IP addresses) with an optional initial part of a request path.
A list of categories is assigned to each address. It is possible to select
a request-acl
based on a matching
blacklist
item with the set of categories assigned to the
request URI by the blacklist.
An HTTP proxy will use the blacklist database file specified by
blacklist-db
in the http-proxy
section,
see Figure 5.73, “A blacklist in the HTTP proxy”. If a request URI belongs to
the category chat
or news
, then
request-uri BLACKLIST
will be selected and the
request will be denied. Other requests will be processed according to
request-uri WEB-FILTER
, described in the next
section.
If a proxy runs in chroot, the path
blacklist-db
will be interpreted in the context of the
chroot directory.
A log of an HTTP proxy configured according to Figure 5.73, “A blacklist in the HTTP proxy” is displayed in Figure 5.74, “A log of blacklist usage in the HTTP proxy”. The log messages are related to two
requests. The first request to server www.example.com
does not match
categories selected in request-acl BLACKLIST
and the
request is accepted by request-acl WEB-FILTER
. The
second request to
news.example.com
matches
a category from request-acl BLACKLIST
, which rejects
the request. Note the ACL names reported in
ACL PHASE=2
messages and the log
markers that colorize accepting and rejecting messages.
Continuous updating of a blacklist so that it covers as many prospective unwanted Web servers as possible is a challenging task, greatly exceeding the capabilities of a typical company network administrator. Therefore, there are commercially available services that provide regularly updated databases of Web servers classified into many categories according to content. Kernun UTM contains one such service—the Kernun Clear Web DataBase.
Configuration of the Kernun Clear Web DataBase consists of two parts. One is used to detect URL categories and select ACLs according to the categories, the other deals with updating of the database of URLs.
The Clear Web DataBase takes a request URI and assigns to it a set
of categories. The categories can be matched by item
request-acl.clear-web-db-match
in the process of
request-acl
selection during an HTTP request processing.
Two examples of sections request-acl
with condition
clear-web-db-match
are shown in Figure 5.75, “Kernun Clear Web DataBase in the HTTP proxy”. There are three possible modes of
category matching, selectable in each condition item:
any
— at least one category of the
request URI matches the set of categories in the condition;
all
— all categories in the
condition are contained in the set of categories which the request URI
belongs to;
exact
— the request URI belongs to
all the categories from the condition and does not belong to any
additional category.
If the selected request-acl
contains
a clear-web-db-match
condition
(CLEAR-WEB
in the sample configuration) and the
deny
item, the proxy will return an error HTML page
containing information that the request has been denied by the Clear Web
DataBase and the list of matching categories.
As an alternative to denying a request URI matching given categories
absolutely, the proxy provides the bypass feature, a
sort of “soft deny”. It is activated by item
request-acl.clear-web-db-bypass
(used in
CLEAR-WEB-BYPASS
in the sample configuration). When
a user attempts to access a Web server restricted by the bypass, an error
page is returned by the proxy, containing a link, through which
the user can obtain limited-time access to the requested server and all
Web servers that belong to the same categories. After the bypass
expiration time, which can be changed using item duration
,
the error page will be displayed again. The user can then reactivate the
bypass. Each bypass activation is logged.
Bypass sessions activated by users are tracked by an internal
table managed by the proxy. The maximum number of simultaneously active
bypass sessions is controlled by
http-proxy.max-bypass-sessions
. If this number is set to
0, the number of bypass sessions will become unlimited, and the sessions
will be tracked by cookies. In this case, an activated bypass is valid for
the target server and all servers in the same domain, but not for other
servers, even if they belong to the same categories.
Clients often use the HTTP proxy also for access to intranet WWW
servers. These internal servers can be located in the internal network,
using private IP addresses from ranges defined by RFC 1918 (networks
10.0.0.0/8
, 172.16.0.0/12
, and 192.168.0.0/16
). Or they may be accessible
from the Internet, but restricted to internal users.
Such internal servers are not contained in the Clear Web DataBase
and would be categorized as unknown
. In order to
distinguish internal servers from public web servers with unknown
categories, host names or IP addresses of the internal servers can be
listed in the configuration by item
clear-web-db.internal-servers
. Private IP addresses from
RFC 1918 are included by specifying
internal-servers private-ip
, so they need not be
written explicitly.
If a server from an HTTP request matches some element of the list of
internal servers, it will be assigned category
internal-servers
. This category is not used for any
public web server included in the standard Clear Web DataBase.