kat — Kernun Admin Tool
kat [-hv]
kat [-d ] [dbglev-f ]cfgfile
kat [-d ] [dbglev-f ] cfgfilecommand [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:
When no command is used, the KAT
will start interactive mode and prompts user for commands
(see the section called “KAT commands” below).
When a command is used, the KAT
executes only given command (see the section called “KAT commands”
below) and exits.
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:
-hPrint usage information and exit.
-vDisplay 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.
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
showapp, start, stop, restart, reload
ps, kill
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.
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.
[-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:
the same configuration file
as the last cml command used
value of the -f option
(if given when kat started)
value of environment variable
$KERNUN_CONF
value of C preprocessor macro
KERNUN_CONF (in compile time)
"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,vrevision are
major.minor,
'0' for the last version stored in RCS,
or - for
the nn-th version preceding the last
version stored in RCS.
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$KERNUN_ROOT/bin/apply.sh 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.
[-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:
For instance,
“2.13”.
0The current revision.
-1, ...The previous and older revisions.
If the rev starts with a digit,
the “-r” text should be omitted.
[-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.
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 kernun.sh 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/
during the startup process.
Commands of this group can then detect components running with
outdated configuration and needed to be restarted.name
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).
[-n]
[ -tT
tag
]
[ -o
format
]Display all configured components.
Options:
-nDisplay 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.
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.
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).
options
params
Immediately stop component(s).
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
nameStart/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.
command
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:
-nStart/stop/restart/reload only “new” components, i.e. such ones with changed configuration.
-yAnswer “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.
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.
[-abdS]
[ -tT
tag
] {
name=parent-pid] |
[ -p
program-name
] }Display information (using the system ps(1) command) about
if used without parameter.
if used with
the program-name
parameter.
if used with
the name parameter.
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.
-signal
]
name=parent-pid]
[
child-pidSend a signal to
The component is identified by
its name.
The proxy is identified by
its name and it must be
the only live (not counting exiting processes) parent
of given proxy.
The proxy is identified by
its name and
parent-pid.
This form of command acts to
the exiting processes, too.
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.
The asterisk (*)
is used both for the name and
the parent-pid.
This form of command acts to
the exiting processes, too.
The proxy is identified by
its name and eventually
parent-pid,
child process is identified by
its child-pid.
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.
-d
name=parent-pid]
[
child-pidSend the TERM signal to
all unconfigured (dead) components.
The KAT tool facilitates log level control, log rotation and log inspection.
incr |
decr |
restart |
rotate }
[
proxyControl 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.
There are some other administrator tools in the Kernun Firewall. Commands in this group facilitate using of them.
take |
drop }
[
VCIDTake or drop Master role for all virtual clusters, or
just the one with number VCID.
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.
IP-addressAdd 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.
IP-addressDelete 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.
IP-addressAdds given address to the PF blacklist table and the AKBL database table.
IP-addressRemoves 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.
pf {
find IP-address |
show table-name }Works with AF packet filter tables.
IP-addressSearch for an IP address in all Adaptive Firewall packet filter blocking tables.
table-nameShow table content.
download ids-agent-rulesDownloads IDS agent rules and install them.
download adaptive-databaseDownloads the Adaptive database install the data into PF tables.
...Calls af-db.sh(8) tool.
...Monitor proxies activity, see monitor(1).
...Control mail quarantine, see quarc.sh(1).
name...Provides additional routing protocol daemon commands:
route [all]Show routing table.
ospfShow OSPF configuration information.
ospf state[all]
Show OSPF status information.
proxy
command [
params ]Display or change data in grey-list triplet database, see triplicator(1).
levelcon | log
[filename]
}
]Change amount of displayed messages
to the level
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.
commandGet help about the KAT
command
[section]
topicInterface 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.
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.
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.
KERNUN_LOG_FILEThe file name where log messages will be redirected. If not set, system logging is used.
af-db.sh(1), monitor(1), quarc.sh(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)