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 fwCMLK-720-E Directory '/usr/local/kernun/conf' contains no SYSTEMKAT@fw>cml -gRCS 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 ps12345 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>cmlCMLI-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 fwCMLK-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>rlogRCS 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 -1CMLK-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])nKAT@fw>showapp -nSMTP smtp-proxy proxy - : UPDATED 50 CMLK-840-I Found 1 component(s)KAT@fw>restart -n SMTPCMLK-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 SMTPCMLK-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 SMTP12345 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 . aclacl 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 descrRepeatable 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>./copyCMLM-751-N 1 node(s) stored to clipboardCML.fw>./pasteCMLT-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>./saveCKGB-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 ...