2. Command Line Interface

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.

2.1. Command Line Interface Details

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:

History browsing

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.

History searching

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.

Hotkey binding

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 SYSTEM
  KAT@fw> cml -g
  RCS file: /usr/local/kernun/conf/kernun.cml,v
  ...
  CKGB-719-N ---- System 'fw' successfully generated
  KAT@fw> <^R>
  Searching for: 'ap' > apply fw

Warning

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.

2.2. C3H — Command Completion and Context Help

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> apply 
  KAT@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         SSHD
  KAT@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' operation
  KAT@fw> ps -<Tab>
  -a         -b         -d         -p         -S         -t         -T
  KAT@fw> ps -p <Tab>
  KAT@fw> ps -p smtp-proxy

2.3. KAT — Kernun UTM Admin Tool

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.

2.3.1. Modes of Operation

The KAT can be used in two modes:

Interactive mode

In this mode, the program is called without parameters. It displays its own prompt KAT@hostnameand 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.

Batch mode

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 ~]# 

2.3.2. Configuration Management

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' loaded
  CML> ... work interactively with the CML
  CML> ./generate
  CKGB-719-N ---- System 'fw' successfully generated
  CML> ./quit
  CMLI-709-N CLI interactive mode closed
  KAT@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

2.3.3. Component Management

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' operation
  KAT@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 found
  KAT@fw> 

2.3.4. Process management

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]:25
  KAT@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 12345
  KAT@fw> 

2.4. CML — Configuration Meta Language

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>  fw
  CML> 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> routes
  CML.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 correct
  CML.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 clipboard
  CML.fw> ./paste
  CMLT-570-E Section 'INTOK' already defined
  CML.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 cancelled
  CML.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 ...