kat — Kernun Admin Tool


kat [-hv]

kat [-d dbglev] [-f cfgfile]

kat [-d dbglev] [-f cfgfile] command [params...]


The kat is a complex tool for the Kernun Firewall Administrator to facilitate his/her work (configuration, process management, log inspection etc.). It can be used in two modes:

The KAT tool uses standard Kernun logging library for displaying messages (see logging(7)), the messages are written both to the standard error output (i.e. sent to the terminal, typically) and to the system log (as configured in /etc/syslog.conf file). This behavior can be changed by setting the environment variable KERNUN_LOG_FILE to a file name willing to be the log target. As usual, every message (produced by the KAT, not by other system programs called by the KAT) has a log-id prefix (e.g. CMLK-872-E) that can be found in Kernun section 6 manual pages (CMLK-720(6) in above example).


The KAT options are as follows:


Print usage information and exit.


Display version information and exit.

-d dbglev

Set debugging level to a specific number. Permitted values are 3 through to 9, 3 being the least and 9 the most verbose. See logging(7) for details.

-f cfgfile

Define the default configuration filename for the KAT cml command (see the section called “KAT commands” below) when issued without parameter.

KAT commands

The command line length must be at most 512 characters and at most 50 arguments are allowed. Command names can be prefixed by a slash ('/') or dot-slash ('./') characters for the cml(8) commands compatibility. Command names are case insensitive.

There are several groups of KAT commands:


cml, apply, rlog, rcsdiff

component management

showapp, start, stop, restart, reload

process management

ps, kill

other admin tools interface

af, cluster, monitor, quarc, router, triplicator


help, man, dbg, !, quit

If the KAT runs in read-only mode (due to current user type), it allows only commands they do not change the firewall functions. Other commands are disabled.

Configuration commands

One of the essential functions of the KAT is to support the configuration task. The cml command starts the Configuration Meta Language (CML) tool, while the apply command distributes the configuration files (generated by the CML) onto proper places of filesystem so that operating system and Kernun applications can run according to the settings made by the Kernun administrator.

cml [-g] [-r revision] [filename]

Start the CML tool with filename as the configuration file name. For detail information about the tool, see cml(8).

If the filename is omitted, the configuration file is set according to the following rules:

  1. the same configuration file as the last cml command used

  2. value of the -f option (if given when kat started)

  3. value of environment variable $KERNUN_CONF

  4. value of C preprocessor macro KERNUN_CONF (in compile time)

  5. "conf/kernun.cml".

In the last three cases, if the filename has a relative pathname, it is relative to the kernun-root directory defined during the installation process. If you want to choose another directory, you can set the environment variable $KERNUN_ROOT to the directory pathname (w/o the final slash).

The directory where the configuration file resides becomes the configuration directory used also in subsequent apply command (see below).

Typically, the /generate command of the cml(8) tool is used at the end of the configuration process to prepare a full set of configuration files to be applied in the system (see the apply command below). The generate-only mode of the CML run can be requested by using the -g option — the CML only loads the configuration, generates the output and exits.

The -r option allows user to request loading of a particular revision from RCS file filename,v. The acceptable forms for revision are major.minor, '0' for the last version stored in RCS, or -n for the n-th version preceding the last version stored in RCS.

apply system-name [ host [ port ] ]

Copy files generated by the CML tool to the target system. The files are expected to be in the configuration directory of the last cml command. If no such command was executed yet, the directory is determined by the same way as specified above in the cml command description.

In the configuration directory, subdirectories named SYSTEM-name are searched for. If some of them matches the argument given to this command, the $KERNUN_ROOT/bin/ shell-script is executed to distribute the file tree.

The command will operate locally (i.e. copy the files into filesystem root on local host) unless the apply-host directive is specified in the particular system section. In this case, the generated output tree is first copied by the ssh(1) to the target machine and then, the kat apply is run there. The last two parameters can be used to redefine the address and port where the ssh daemon on the target host listens on.

Besides copying files onto proper place in the filesystem, the command typically does some other work, like modifying operating system user set, creation of chroot-directories including all necessary files, mounting device filesystem etc.


The names of system sections in the CML are case-insensitive, but after generating the file tree, they becomes the regular UNIX file names that are case sensitive, of course. If you have changed the system name capitalisation not changing the spelling, you will have to remove the old configuration output tree by hand.

rlog [ [-r] rev ] [ [-r] rev ] [ file ]

Display RCS log of given file (kernun.cml by default).

Without -r options, the command shows the complete log. When some rev arguments used, only these revision logs are displayed.

For the rev specification, the following forms are allowed:

revision number

For instance, 2.13.


The current revision.

-1, ...

The previous and older revisions.

If the rev starts with a digit, the -r text should be omitted.

rcsdiff [ [-r] rev ] [ [-r] rev ] [ file ]

Display differences (the diff(1) output) between two versions of given file (kernun.cml by default).

Without -r options, the command compares the file with the last revision in the RCS file. With a single -r option, the command compares the file with the given revision. With two -r options, the command compares the two given revisions.

For the rev specification, the same forms as in the rlog command are allowed.

Component management commands

The KAT tool facilitates managing of Kernun firewall components, i.e. Kernun applications (Kernun proxies, SSH servers, nameservers, DHCP server, NTP daemon, postfix SMTP forwarders, PIKE monitor) and networking components (packet filter, network interfaces and routing) configured in the configuration file. All networking components are started by operating system itself. All applications are started after operation system boot by means of the rc-script placed into the directory /usr/local/etc/rc.d during the installation process.

All components write a hash of their configuration into the file /var/run/name during the startup process. Commands of this group can then detect components running with outdated configuration and needed to be restarted.

All commands of this group primarily look for component names in the $KERNUN_ROOT/etc/component.lst file generated by the cml.generate command. They do not respect the running applications (except for displaying their status etc.), they can be managed by Process management commands (see the section called “Process management commands” below).

showapp [-n] [ -tT tag ] [ -o format ]

Display all configured components.



Display only new components, i.e. such ones with changed configuration.

-o format

Display columns in order given by the format string. The string consists from heading names separated by commas. By default, command behaves like with the NAME,PROG,TYPE,PARM,TAGS,STAT,PRTY format.

-tT tag

Display all components with (-t) or without (-T) given tag. Use the asterisk (*) value for any tag. For the list of the tags, use the C3H support.

start options params

Start the component(s).

Prior to starting any application, the KAT checks, whether requested applications are not already running, in which case the KAT rejects to start it.

stop options params

Immediately stop component(s).

This command is not effectual to unconfigured or exiting proxies. Those must be killed by the kill command (see below).

restart options params

Immediately stop component(s).

reload options params

Gracefully stop component(s).

This command should be preferred in the normal circumstances. Use it rather than the restart command. All particular proxies are switched to an exiting state in which they do not accept new incoming requests awaiting to the end of all established connections.

All the control commands (start, stop, restart and reload) have following parameter specification possibilities:

command name

Start/stop/restart/reload a component referenced in the configuration by the name.

command -a type

Start/stop/restart/reload all components of given type. For the list of the types, use the C3H support. Generally, proxy type names (like http-proxy) and component types (like proxy, sshd, postfix, cluster.monitor, interface and routing) can be used.

command -tT tag

Start/stop/restart/reload all components with (-t) or without (-T) given tag. Use the asterisk (*) value for any tag. For the list of the tags, use the C3H support.


Start/stop/restart/reload all Kernun applications (i.e. all components except network interfaces and routing). Before execution, the KAT tool asks the user to confirm it.

All the control commands recognize following options:


Start/stop/restart/reload only new components, i.e. such ones with changed configuration.


Answer yes to confirmation when starting all Kernun applications.

If there are more components to start, the KAT tool tries to repeat attempts to start them until all components succeed, or two consecutive loop iterations do not improve the state.

Process management commands

In the contrary to previous group of commands, process management commands does not deal with applications (proxies/ssh servers) according to the way how they are configured. Instead, current running processes are dealt with. The name of the proxy or ssh server is read from the ps(1) system command output.

ps [-abdS] [ -tT tag ] { name[=parent-pid] | [ -p program-name ] }

Display information (using the system ps(1) command) about

all Kernun applications (proxy and server parents)

if used without parameter.

all Kernun applications of given program type

if used with the program-name parameter.

all processes (including children) of all Kernun applications given by name

if used with the name parameter.

all processes (including children) of a single Kernun application

if used with the name and the parent-pid parameters.

Option -a causes displaying information about all processes (including children) in any form of command.

Option -b forces brief output format.

Option -d restricts information to only such applications that are still running although they have been unconfigured (dead).

Option -t restricts information only to applications with given tag. If the asterisk (*) value is used, applications with any tag are displayed.

Option -T restricts information only to applications without given tag. If the asterisk (*) value is used, applications without any tag are displayed.

Option -S shortens output lines up to the terminal width.

kill [ -signal ] name[=parent-pid] [ child-pid ]

Send a signal to

a non-proxy component process

The component is identified by its name.

a single proxy-parent

The proxy is identified by its name and it must be the only live (not counting exiting processes) parent of given proxy.

a selected proxy-parent

The proxy is identified by its name and parent-pid. This form of command acts to the exiting processes, too.

all proxy-parents

The proxy is identified by its name and an asterisk (*) is used instead of the parent-pid. This form of command acts to the exiting processes, too.

all components

The asterisk (*) is used both for the name and the parent-pid. This form of command acts to the exiting processes, too.

a selected proxy-child

The proxy is identified by its name and eventually parent-pid, child process is identified by its child-pid.

all proxy-children

The proxy is identified by its name and eventually parent-pid, the signal is sent to all children of given parent(s) if the asterisk (*) is used instead of the child-pid parameter.

If no signal is specified, the default signal is used (15, or TERM). When sending the TERM or the HUP (1) signal to a proxy parent, the KAT repeats sending of it until killing succeeds. If the retry limit (10x) is reached, the KILL (9) signal is sent (to parent and all children), instead.

kill -d name[=parent-pid] [ child-pid ]

Send the TERM signal to all unconfigured (dead) components.

Log control and management

The KAT tool facilitates log level control, log rotation and log inspection.

log { incr | decr | restart | rotate } [ proxy ]

Control proxy logging. Subcommands incr and decr increases/decreases proxy logging level. Subcommand restart forces proxy to reopen the log file. Subcommand rotate rotates particular proxy log file (i.e. renames the file and restarts proxy logging). If used without proxy name, rotates all proxies.

Other admin tools interface

There are some other administrator tools in the Kernun Firewall. Commands in this group facilitate using of them.

cluster { take | drop } [ VCID ]

Take or drop Master role for all virtual clusters, or just the one with number VCID.

af blacklist { show | count | flush | add ... | del ... | unblock IP-address | upload | refresh }

Adaptive Firewall autonomous blocking module control.


Show the current blacklist set in the packet filter.


Print number of addresses in the current blacklist in the packet filter.


Flush all addresses of the current blacklist in the packet filter.

add IP-address

Add an IP address to the current blacklist in the packet filter.


The table remains changed only until the next table refresh interval. Do not use this command to block an IP address. Use the BLOCK command instead.

del IP-address

Delete an IP address from the current blacklist in the packet filter.


The table remains changed only until the next table refresh interval. Do not use this command to unblock an IP address. Use the UNBLOCK command instead.

block IP-address

Adds given address to the PF blacklist table and the AKBL database table.

unblock IP-address

Removes given address from the PF blacklist table and all IDS database tables.


Upload the Adaptive Firewall IDS database to central server.


Fetch a new Adaptive Firewall IPS database (according to the configuration either feed it from the local IDS database, or download it from the central server) and install it to the packet filter.

af pf { find IP-address | show table-name }

Works with AF packet filter tables.

find IP-address

Search for an IP address in all Adaptive Firewall packet filter blocking tables.

show table-name

Show table content.

af download ids-agent-rules

Downloads IDS agent rules and install them.

af download adaptive-database

Downloads the Adaptive database install the data into PF tables.

af ...

Calls tool.

monitor ...

Monitor proxies activity, see monitor(1).

quarc ...

Control mail quarantine, see

router name ...

Provides additional routing protocol daemon commands:

show route [all]

Show routing table.

show ospf

Show OSPF configuration information.

show ospf state[all]

Show OSPF status information.

triplicator proxy command [ params ]

Display or change data in grey-list triplet database, see triplicator(1).

Miscellaneous commands

dbg level [ { con | log [filename] } ]

Change amount of displayed messages to the level (see logging(7) for possible values and their meaning).

If you want to change the level only for console or log, you can specify the con or log keyword respectively. In the case of log, you can also change the target file name.

help command

Get help about the KAT command.

man [section] topic

Interface to the man(1) command with the priority of the Kernun manual pages.

[!] command...

Execute shell command.

If the command name does not collide with any KAT command, the '!' prefix should be omitted.


Quit the KAT tool.

C3H Support

The Command Completion and Context Help (C3H) support helps you to write correct commands or proper parameters a bit faster. The simple basic rule is: If you don't know what to do now, press <TAB>!. Of course, it does not work absolutely perfectly in all situations, but it works e.g. when selecting a configuration file (cml, quarc), a system name (apply), a proxy name (application management, process management, showlog, monitor), a manual page name (man), a signal name (kill) etc.

Control Sequences

The End-of-file control sequence (^D, Control-D) can be used for quitting the KAT tool.

The ^R (Control-R) sequence is used for command history searching. You can type part of some previous command (the part is displayed in the prompt) and C3H searches in the history to the last command containing such a string. This command is then displayed on the command line and you can tune the selection by adding more characters to the pattern, removing some characters by the Backspace key or repeating the search by pressing ^R again. If your selection is completed, press Enter, the selected command is placed into the command line buffer and you can edit it. The KAT tool saves command history at the end of its work and restores it at the beginning.

The ^U (Control-U) sequence is used for clearing the command line.



The file name where log messages will be redirected. If not set, system logging is used.

See Also

Kernun:, monitor(1),, triplicator(1), kernun.cml(5), adaptive-firewall(7), configuration(7), logging(7), tcpserver(7), transparency(7), cml(8), pf-control(8)


bzip2(1), diff(1), kill(1), man(1), ps(1), ssh(1), tail(1), pf(4), pfctl(8)


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