Kernun UTM Handbook


Table of Contents

How to Read the Documentation
1. Kernun UTM Product Overview
1. Kernun UTM
2. Kernun Clear Web
2. Kernun UTM System Management
1. Installation Media, Releases, and Builds
2. Disk Space Layout
3. Licensing
4. Boot Manager
4.1. ZFS boot manager
4.2. LEGACY (UFS) boot manager
4.3. Security notice
5. Installation
5.1. Standalone Installer
5.2. Initial Configuration
5.3. Installation from the GUI
5.4. Installation from the Command Line
5.5. Enabling Serial Console Output
6. Backup and Restoring
6.1. Backup and Restoring from the GUI
6.2. Backup and Restoring from the Command Line
6.3. Restoring a Backup in the Standalone Installer
7. Upgrade
7.1. Upgrade from the GUI
7.2. Upgrade from the Command Line
8. Audit
9. Emergency Repair Environment
10. Running in virtual machine environment
10.1. VMware
10.2. Hyper-V
10.3. VirtualBox
10.4. XEN
3. User Interface
1. Graphical User Interface
1.1. Kernun GUI Launcher
1.2. GKAT—Management Console
1.3. Logs
1.4. GCML — Configuration
1.5. Locking
2. Command Line Interface
2.1. Command Line Interface Details
2.2. C3H — Command Completion and Context Help
2.3. KAT — Kernun UTM Admin Tool
2.4. CML — Configuration Meta Language
3. Administrative Utilities
4. Configuration Basics
1. Configuration Language
2. The Initial Configuration
2.1. Global Level
2.2. System
2.3. SSH Server
2.4. Local Mail Handling
2.5. Application Proxies and ACLs
2.6. DNS Proxy
2.7. HTTP Proxy
2.8. FTP Proxy
2.9. HTTPS and SSH Proxy
2.10. SMTP Proxy
2.11. IMAP4 and POP3 Proxy
3. Changing the Configuration
3.1. Adding TCP Proxies
5. Advanced features
1. Packet Filter
1.1. Packet Flow
1.2. Packet Filtering
1.3. Antispoofing Using Packet Filter
1.4. Selective Packet Forwarding
1.5. Network Address Translation
1.6. Packet Forwarding along with NAT
1.7. Defending against DoS/DDoS Attacks
1.8. Honeypot
2. System Configuration
2.1. User Accounts
2.2. Network Interfaces
2.3. Static Routes
2.4. Dynamic IP routing with BIRD
2.5. File /etc/rc.conf
2.6. Kernel Parameters in /etc/sysctl.conf
2.7. Configuration of the cron Daemon
3. Caching Name Server
4. DNS and DHCP Services
4.1. DNS Server for the Local Zone
4.2. DHCP Server for the Local Network
5. Time Synchronization with NTP
6. Monitoring of Kernun UTM Operation
6.1. Logging Configuration
6.2. Log Rotation
6.3. Monitoring of Active Sessions
6.4. Proxy Statistics Generation
6.5. Monitoring of System Parameters
7. Networking in Proxies
7.1. Transparent Proxies
7.2. A Proxy and a Server on the Same Port
7.3. Listening on a port range
8. H.323 Proxies
9. SIP Proxy
10. SQLNet Proxy
11. UDP Proxy
12. Cooperation of HTTP and FTP Proxies
13. Secure Communication Using SSL/TLS
14. User Authentication
14.1. Authentication Methods
14.2. Authentication in FTP Proxy
14.3. Basic Authentication in HTTP Proxy
14.4. Kerberos Authentication in HTTP Proxy
14.5. Kerberos Authentication in Transparent HTTP Proxy
14.6. NTLM Authentication in HTTP Proxy
14.7. HTTP Authentication Proxy
14.8. Out of Band Authentication
15. Antivirus Checking of Data
15.1. Connecting with Dr.WEB
15.2. Connecting with ClamAV
15.3. Connecting via ICAP protocol
15.4. Antivirus Results
15.5. Antivirus in Proxies
15.6. SMTP Proxy: Discarding Infected Mails
15.7. SMTP Proxy: Replacing Infected Documents
15.8. Antivirus in POP3 and IMAP4 Proxies
16. Antispam Processing of E-mail
16.1. Antispam Engine
16.2. White-, Grey-, and Blacklists
17. Content Processing
17.1. Content Type Detection
17.2. HTML Filtering
17.3. MIME Processing
18. Filtering HTTP Requests by URI
18.1. URL Matching and Rewriting
18.2. Blacklists in HTTP Proxy
18.3. Kernun Clear Web DataBase
18.4. Using External Web Filter
19. HTTPS Inspection
19.1. Certificates
19.2. HTTPS inspection ACL flow
19.3. Transparent mode
19.4. Non-transparent mode
19.5. SNI inspection in HTTPS
19.6. TLS termination
20. Intrusion Detection/Prevention System
20.1. Update of Rules
21. Traffic Shaping
22. Virtual Private Networks — OpenVPN
22.1. Remote Access Server
22.2. Network to Network
22.3. Accessing the virtual network
22.4. Logs
23. Virtual Private Networks — IPsec
23.1. IPsec Configuration
24. High Availability Clusters
24.1. Controling multiple systems from GUI
24.2. Sharing the configuration among systems
25. Kernun Branch Access
25.1. Description and Plug-in
25.2. Installation
25.3. Configuration
25.4. Diagnostics and Troubleshooting
26. IPv6
27. Honeypot
I. Kernun UTM Reference (1)
HtmlMatchPasswd.pm — encapsulates the databases of the HTML form value control tool html-match-db(1) for storing two couples of credentials (internal username and password and external username and password). It also keeps the logs of the actions over the particular accounts.
clear-web-db-update.sh — tool for updating the Clear Web DataBase
clear-web-db — tool for managing the Clear Web DataBase
cluster-sync — tool for synchronizing files between cluster members
diskdb — tool for creating and querying file system content database
fwpasswd — create and update password authentication files
grep-debug — tool for selecting messages from Kernun logs
grep-stats — tool for selecting messages from Kernun logs
html-match-db — controls databases of HTML form values used by the generic data matching module
kernun-audit — checks for bugs and new versions of the Kernun software
license — tool for checking Kernun license file
log-ts — tool for selecting messages from Kernun logs
mkblacklist — tool for converting http-proxy blacklists into DB format
monitor — report current status of Kernun proxies
ooba-acs — uses Cisco ACS log to update out of band authentication user list
ooba-samba — uses a Samba server to update the out of band authentication user list
oobctl — tool for creating and querying file oob database
printblacklist — tool for converting http-proxy blacklists into textual format
quarc.sh — mail quarantine control tool
resolveblacklist — tool for resolving hostnames in http-proxy blacklists
rrd — system parameter watching
sum-stats — generates proxy usage statistics from Kernun logs
switchlog — distribute messages from Kernun log according to message id and proxy name
triplicator — SMTP Grey-listing Triplet Database Manipulator
II. Kernun UTM Reference (5)
acl — format of acl component configuration
ak47 — format of ak47 component configuration
altq — format of altq component configuration
antivirus — format of antivirus component configuration
application — format of application component configuration
atr — format of atr component configuration
atrmon.cfg — format of atrmon program configuration file
auth — format of auth component configuration
clear-web-db — format of clear-web-db component configuration
common — format of common component configuration
cwcatd.cfg — format of cwcatd program configuration file
dhcp-server — format of dhcp-server component configuration
dns-proxy — format of dns-proxy component configuration
dns-proxy.cfg — format of dns-proxy program configuration file
ftp-proxy — format of ftp-proxy component configuration
ftp-proxy.cfg — format of ftp-proxy program configuration file
gk-proxy — format of gk-proxy component configuration
gk-proxy.cfg — format of gk-proxy program configuration file
h323-proxy — format of h323-proxy component configuration
h323-proxy.cfg — format of h323-proxy program configuration file
http-cache — format of http-cache component configuration
http-control — format of http-control component configuration
http-proxy — format of http-proxy component configuration
http-proxy.cfg — format of http-proxy program configuration file
ica — format of ica component configuration
icap-server — format of icap-server component configuration
icap-server.cfg — format of icap-server program configuration file
imap4-proxy — format of imap4-proxy component configuration
imap4-proxy.cfg — format of imap4-proxy program configuration file
interface — format of interface component configuration
ipc — format of ipc component configuration
ips — format of ips component configuration
ipsec — format of ipsec component configuration
kernun.cml — format of Kernun configuration file
ldap — format of ldap component configuration
license — format of license component configuration
listen-on — format of listen-on component configuration
log — format of log component configuration
mod-antispam — format of mod-antispam component configuration
mod-html-filter — format of mod-html-filter component configuration
mod-mail-doc — format of mod-mail-doc component configuration
mod-match — format of mod-match component configuration
monitoring — format of monitoring component configuration
nameserver — format of nameserver component configuration
netio — format of netio component configuration
nls — format of nls component configuration
ntp — format of ntp component configuration
openvpn — format of openvpn component configuration
packet-filter — format of packet-filter component configuration
pf-control.cfg — format of pf-control program configuration file
pike — format of pike component configuration
pikemon.cfg — format of pikemon program configuration file
ping — format of ping component configuration
pop3-proxy — format of pop3-proxy component configuration
pop3-proxy.cfg — format of pop3-proxy program configuration file
proxy-ng — format of proxy-ng component configuration
radius — format of radius component configuration
resolver — format of resolver component configuration
router — format of router component configuration
rtadvd — format of rtadvd component configuration
sip-proxy — format of sip-proxy component configuration
sip-proxy.cfg — format of sip-proxy program configuration file
smtp-proxy — format of smtp-proxy component configuration
smtp-proxy.cfg — format of smtp-proxy program configuration file
snmpd — format of snmpd component configuration
sqlnet-proxy — format of sqlnet-proxy component configuration
sqlnet-proxy.cfg — format of sqlnet-proxy program configuration file
ssh — format of ssh component configuration
ssl — format of ssl component configuration
sysctl — format of sysctl component configuration
system — format of system component configuration
tcp-proxy — format of tcp-proxy component configuration
tcp-proxy.cfg — format of tcp-proxy program configuration file
tcpserver — format of tcpserver component configuration
test-expr — format of test-expr command-line arguments
time — format of time component configuration
udp-proxy — format of udp-proxy component configuration
udp-proxy.cfg — format of udp-proxy program configuration file
udpserver — format of udpserver component configuration
III. Kernun UTM Reference (6)
AK47-120 — Application of honeypot blacklist failed
AK47-121 — Failure of pfctl operation report
AK47-131 — Reading packet filter ak47-blacklist table failed
AK47-710 — Adaptive Kernun IPS module database refresh report
AK47-720 — AK47 IPS database refresh report
AK47-724 — Client was excluded from the IPS database due to whitelist
AK47-729 — AK47 IDS database refresh report
AK47-730 — Planned refresh of packet filter ak47-blacklist table
AK47-731 — Current packet filter ak47-blacklist table size report
AKHP-250 — Honeypot module cannost accept new connection
AKHP-251 — Honeypot module accepted unsupported client
AKHP-750 — New client was trapped to honeypot
AKHP-888 — Honeypot module statistics message
AKLD-709 — Final application termination message
AKWD-120 — Unrecognized event on watched file
AKWD-150 — Watched file is not regularly accessible
AKWD-160 — Watched file is not regularly accessible
AKWD-670 — Client occurence in watchdog file checked against thresholds
ARGS-000 — Application initialisation failed when preparing getopt() system call
ARGS-001 — Application has improperly started
ARGS-002 — Application command line arguments array is NULL
ARGS-010 — Application requested to register an illegal option char
ARGS-011 — Function initgetopt() failed due to duplicate command-line option
ARGS-012 — Function initgetopt() failed due to a large option set
ARGS-013 — Function initgetopt() failed due to a large option set
ARGS-500 — Command line argument array starts by a NULL pointer (bad program name)
ARGS-520 — Command-line option used more than once
ARGS-521 — Application called with an unknown command-line option
ARGS-522 — Application called with option without proper argument
ARGS-523 — Option -f specifies too long filename
ARGS-524 — Options on command line are followed by an extra argument
ARGS-529 — Terminal message in case of wrong command line parameters
ARGS-710 — KERNUN_ROOT environment variable has incorrect content
ASN1-300 — Parser ran out of read buffer
ASN1-700 — Parser read integer out of allowed range
ASN1-701 — Parser read integer coding length greater than 4 bytes
ASN1-702 — Parser read length encoding starting with two ones
ASN1-720 — Parser read IA5 string character with unknown code
ATRM-010 — Searching of ACL failed
ATRM-109 — General select() error
ATRM-610 — Request is not covered by configuration
ATRM-700 — Notification about the mode of operation of ATR monitor
ATRM-701 — ATR monitor has been initialized and is ready to accept packets
ATRM-707 — ATR monitor has finished
ATRM-708 — ATR monitor has unbound the sockets used for listening for clients
ATRM-709 — Final daemon termination message
ATRM-710 — Daemon runtime monitoring support cannot be initialized
ATRM-740 — Address state change report
ATRM-808 — Session has started, client connection has arrived
ATRM-809 — DNS session finished
ATRM-810 — ACL decision has been made, operation either accepted or rejected
ATRM-820 — ACL decision has been made, operation either accepted or rejected
ATRM-860 — Request processing finished
AUTH-110 — Authentication handle cannot be allocated
AUTH-111 — Authentication password file cannot be opened
AUTH-112 — Authentication tool cannot be opened
AUTH-131 — Authentication password file read failed
AUTH-135 — Call to authentication library failed
AUTH-631 — User not found in authentication password file
AUTH-632 — User password does not match to the one in password file
AUTH-635 — User password/response rejected by authetication tool
AUTH-731 — Proxy-user name too long
AUTH-740 — I/O error in communication with external authentication tool
AUTH-741 — Protocol error in communication with external authentication tool
AUTH-742 — Protocol error in communication with external authentication tool
AUTH-743 — Protocol error in communication with external authentication tool
AUTR-500 — Configuration does not contain RADIUS library settings
AUTR-501 — RADIUS server host is not correctly specified in configuration file
AUTR-600 — A call to RADIUS client library returned an error
AUTR-601 — RADIUS client library initialization failed
AUTR-602 — A response of unknown type was received from a RADIUS server
AUTR-603 — A user was rejected by a RADIUS server
AUTR-604 — A user was accepted by a RADIUS server
AUTR-605 — A RADIUS server has sent a challenge to a user
AUTR-606 — A user has respoded to an authentication challenge
CASE-500 — Obsolete feature used in configuration
CASE-510 — Interface definition does not contain IP address specification
CASE-511 — Interface definition does not contain IP address specification
CASE-513 — Only Ethernet interfaces can be aggregated
CASE-514 — Duplicite aggregation of one interface
CASE-515 — VLAN ID definition invalid
CASE-516 — Parent interface of VLAN interface is of inappropriate type
CASE-517 — Duplicate VLAN ID definition
CASE-518 — Cannot make alias without base address
CASE-804 — The kernel may be blocked by a packet cyclically fastrouted on lo0
CFGL-010 — Incorrect call of regexpizelist()
CFGL-031 — Incorrect key is to be searched in list
CFGL-340 — List extraction function called with insufficient array
CFGL-500 — Attempt to add item '*' into non-extended list
CFGL-501 — Too deep sublist nesting
CFGL-520 — Adding to '*'-list requested
CFGL-521 — Adding of exclude-member to simple list requested
CFGL-522 — Overlapping range is to be added to list
CFGL-523 — Lower and upper bounds are not compatible
CFGL-524 — Adding of string, regexp or sock range requested
CFGL-549 — Name-set represents no section
CFGP-100 — Revoking configuration file from RCS failed
CFGP-500 — Configuration file is empty
CFGP-501 — First character of configuration is illegal
CFGP-531 — Illegal character found
CFGP-532 — Configuration contains character string
CFGP-533 — Integer found in configuration is too large
CFGP-534 — Illegal character found in IP address
CFGP-535 — Illegal syntax of IP address
CFGP-544 — Alphanumeric character expected in configuration
CFGP-545 — Incorrect character escape sequence used in string
CFGP-546 — String expression not closed
CFGP-547 — String or regexp exceeded the maximum length
CFGP-548 — String or regexp not closed
CFGP-549 — IP address probably not closed
CFGP-591 — IPv4 address byte value too big
CFGP-592 — IPv4 address byte empty
CFGP-593 — Incorrect number of IPv4 address bytes
CFGP-594 — IPv4 address syntax error
CFGP-595 — IPv4 mask or IPv6 prefix specification invalid
CFGP-596 — IPv4 mask or IPv6 prefix specification invalid
CFGP-599 — IPv6 address cannot be parsed
CFGR-000 — Section/item parser routine failed
CFGR-003 — Application version tag misformed
CFGR-109 — Parser initialisation failed
CFGR-110 — System error during configuration reading
CFGR-160 — Item addition to list failed
CFGR-161 — Value to list conversion failed
CFGR-162 — Sublist creation failed
CFGR-500 — Configuration integrity constraints error
CFGR-501 — Parser started without configuration file
CFGR-502 — No VERSION statement in configuration
CFGR-503 — VERSION statement has incorrect argument
CFGR-504 — VERSION statement has incorrect argument
CFGR-505 — VERSION statement repeated
CFGR-511 — Configuration item must be closed by semicolon
CFGR-512 — Section must begin with left brace
CFGR-513 — List member must be followed by comma or right brace
CFGR-514 — Configuration ended incorrectly
CFGR-515 — Closing brace not found
CFGR-517 — Item/subsection name expected in configuration
CFGR-518 — Item/subsection name expected in configuration
CFGR-519 — Incorrect configuration directive found
CFGR-520 — Obligatory keyword not found
CFGR-521 — Integer value expected in configuration
CFGR-523 — String value expected in configuration
CFGR-524 — Enumeration value expected in configuration
CFGR-525 — Hostname/IP address expected in configuration
CFGR-526 — Hostname/regexp/IP network expected in configuration
CFGR-527 — Regular expression expected in configuration
CFGR-528 — Hostname/IP address not followed by a colon
CFGR-529 — IP address value and type incompatibility
CFGR-530 — Section reference invalid
CFGR-531 — Section reference invalid
CFGR-540 — Element is not optional
CFGR-541 — Element value type is not fractional
CFGR-542 — Integer value too large
CFGR-543 — Port/service name invalid
CFGR-544 — Empty hostname is not allowed
CFGR-545 — Direct integer value not allowed
CFGR-546 — Some forms of addresses are not allowed in this place
CFGR-547 — Enumeration keyword invalid
CFGR-548 — Time value is not in hhmm format
CFGR-550 — Section defined more than once
CFGR-551 — Name of repeatable section missing
CFGR-552 — Name of repeatable section too long
CFGR-559 — Nonrepeatable item defined more than once
CFGR-560 — List not closed by regular member
CFGR-561 — Excluding members not allowed in simple lists
CFGR-562 — Member ranges not allowed in simple lists
CFGR-563 — Operator '*' not allowed in simple lists
CFGR-564 — List member reading failed
CFGR-566 — Member ranges not allowed
CFGR-569 — List of values is not allowed
CFGR-590 — Negative final configuration message
CFGR-700 — Configuration file has been opened
CFGR-710 — Configuration hash reader report
CFGR-790 — Configuration successfully completed
CHSC-710 — Character set converter initialisation message
CHSC-719 — Character set converter initialisation failure
CHSC-720 — Incomplete or invalid multibyte character sequence
CKGB-100 — Cannot copy system configuration file prototype to system image
CKGB-121 — Kernun component configuration generation failed
CKGB-122 — Nameserver structure creation failed
CKGB-191 — Cannot create directory
CKGB-193 — Directory creation failed
CKGB-321 — Postfix MASTER.CF template line too long
CKGB-390 — Filename too long
CKGB-500 — Kernun configuration file contains no SYSTEM
CKGB-541 — Only one backbone area must be defined in OSPF configuration
CKGB-550 — More than one IFACE item found when IFACE ANY used
CKGB-551 — More than one INTERFACE section found when IFACE ANY used
CKGB-553 — Only FAILOVER protocol is possible for LAGG with ALTQ
CKGB-554 — Each interface can be used in just one INTERFACE section
CKGB-560 — ALTQ queue set definition incorrect
CKGB-561 — ALTQ queue set definition incorrect
CKGB-562 — ALTQ queue set definition incorrect
CKGB-563 — ALTQ queue set definition incorrect
CKGB-564 — ALTQ queue set definition incorrect
CKGB-565 — ALTQ queue set definition incorrect
CKGB-566 — ALTQ queue set definition incorrect
CKGB-567 — ALTQ queue set definition incorrect
CKGB-568 — ALTQ queue parent definition incorrect
CKGB-569 — ALTQ queues with equal priority found
CKGB-570 — DHCP client interface definition collision
CKGB-571 — Non-transparent proxy cannot listen on DHCP interface
CKGB-572 — Dynamic DNS forwarder cannot be used without DHCP interface
CKGB-573 — Proxy probably uses reserved port and will not operate
CKGB-574 — More Kaspersky antivirus HTTP daemon configured
CKGB-578 — Primary nameserver must be in zone table
CKGB-580 — System resolver nameserver specification invalid
CKGB-584 — Nameserver zone defined by incorrect address
CKGB-586 — Two interfaces with equal device names found
CKGB-587 — Socket collision report message
CKGB-588 — Exactly two systems must be present in the configuration
CKGB-589 — Cannot resolve listen-on address of pikemon
CKGB-590 — Exactly two systems must be present in the configuration
CKGB-710 — Kernun generation started
CKGB-711 — Kernun verification started
CKGB-718 — Kernun verification/generation has failed
CKGB-719 — Kernun verification/generation has succeeded
CKGB-790 — Particular system configuration file saved
CKGB-799 — Particular system configuration file failure
CMLI-100 — EditLine library initialisaton failed
CMLI-101 — EditLine library initialisaton failed
CMLI-102 — EditLine library initialisaton failed
CMLI-103 — EditLine library initialisaton failed
CMLI-120 — File completion failed
CMLI-125 — Path to Kernun manual pages invalid
CMLI-190 — KAT cannot display output to terminal
CMLI-700 — User interface startup message
CMLI-709 — User interface closeup message
CMLI-710 — CML C3H failed
CMLI-711 — CML C3H failed
CMLI-712 — CML C3H failed
CMLI-713 — CML C3H failed
CMLI-714 — Cannot use C3H for long lines
CMLI-720 — C3H cannot find filename continuation
CMLI-725 — Manual page section invalid
CMLI-775 — Automatic reply in batch mode
CMLI-780 — Invalid parameters of DBG command
CMLK-101 — Unaccessible diretory
CMLK-130 — KAT sends signal to proxy/ssh server
CMLK-140 — KAT cannot determine running processes
CMLK-149 — KAT component control command failed for some component
CMLK-155 — General I/O error message
CMLK-156 — Log file line misformed
CMLK-342 — Component misconfigured
CMLK-500 — Current directory information
CMLK-509 — Current directory change error report
CMLK-540 — Misformed line found in 'component.lst' file
CMLK-541 — Unknown component type found in 'component.lst' file
CMLK-542 — KAT cannot read proxy configuration
CMLK-543 — Compoenent monitoring is not available
CMLK-609 — Issued command denied in read-only mode
CMLK-700 — KAT exiting
CMLK-702 — KAT/CML file name invalid
CMLK-705 — Incorrect call of KAT command
CMLK-706 — Incorrect call of KAT command
CMLK-707 — Incorrect call of KAT command
CMLK-708 — KAT command option not known
CMLK-709 — KAT command name not known
CMLK-710 — Configuration hash report
CMLK-712 — KAT cannot find continuation
CMLK-713 — Too many arguments to KAT command
CMLK-714 — Incorrect selection for KAT operation
CMLK-715 — KAT command parameter invalid
CMLK-716 — KAT command parameters invalid
CMLK-720 — KAT cannot find CML SYSTEM file tree
CMLK-721 — KAT APPLY command requires system name
CMLK-725 — Configuration RCS version shortcut invalid
CMLK-731 — KAT KILL command invoked with incorrect signal name/number
CMLK-732 — KAT KILL command invoked without application name
CMLK-733 — KAT KILL command invoked with incorrect child specification
CMLK-739 — KAT command was interrupted
CMLK-740 — KAT detected running application, cannot start new one
CMLK-741 — KAT command parameter error
CMLK-742 — Not daemonized proxy cannot be started by KAT
CMLK-743 — Invalid component control command issued
CMLK-747 — Preliminary command summary message
CMLK-748 — Command can be applied to Kernun proxies only
CMLK-749 — Component control command failed to finish
CMLK-751 — Incorrect call of KAT command
CMLK-756 — Log rotation command invalid
CMLK-820 — KAT APPLY command is executed
CMLK-821 — Exporting system configuration to tarball
CMLK-825 — Revoking old configuration requested
CMLK-830 — KAT is sending signal to one or more application processes
CMLK-841 — General Kernun component start/stop execution message
CMLK-849 — Kernun component control command successfully issued
CMLK-856 — Log rotation command execution message
CMLK-857 — Old log file compression started
CMLM-115 — Configuration overwriting warning
CMLM-540 — CML configuration node verification failed
CMLM-620 — Auditor mode startup
CMLM-621 — Issued command denied in read-only mode
CMLM-701 — Configuration consistency warning
CMLM-702 — Configuration consistency warning
CMLM-703 — Configuration consistency warning
CMLM-712 — CML Load operation interrupted by user
CMLM-713 — CML /SAVE operation not completed
CMLM-714 — CML command-line options incompatible
CMLM-720 — Unknown CML command name
CMLM-721 — CML command misuse
CMLM-722 — Invalid arguments of CML command
CMLM-731 — Bad parameter, information not available
CMLM-732 — Bad parameter, information not available
CMLM-740 — Bad parameter, target node invalid
CMLM-741 — RCS operations not allowed without source file specified
CMLM-750 — Multinode operation allowed only for structured comments
CMLM-751 — Clipboard change message
CMLM-790 — RCS command terminal message
CMLM-799 — RCS command terminal message
CMLR-113 — Include file path is invalid
CMLR-510 — Configuration version inconsistency
CMLR-511 — Configuration file incomplete
CMLR-512 — Configuration file probably corrupted
CMLR-513 — Configuration root path setting failed
CMLR-515 — Include directive failed for some reason
CMLR-518 — Configuration file probably corrupted
CMLR-519 — Configuration file not loaded after previous errors
CMLR-530 — Incorrect CML path specification
CMLR-540 — Incorrect high-level configuration command usage
CMLR-542 — CML include file content incorrect
CMLR-543 — Compound comment syntax error
CMLR-550 — General CML syntax error message
CMLR-551 — CML parser detected syntax error
CMLR-552 — Section format error
CMLR-560 — Item completeness error
CMLR-564 — Excluding member misuse
CMLR-565 — Configuration directive not closed properly
CMLR-566 — List definition misformed
CMLR-567 — Item definition misformed
CMLR-569 — Item completeness error
CMLR-570 — Variable definition misformed
CMLR-571 — Variable definition misformed
CMLR-572 — Variable definition misformed
CMLR-573 — Variable definition misformed
CMLR-574 — CML SWITCH command syntax error
CMLR-575 — CML SWITCH/CASE command syntax error
CMLR-580 — CML parser detected syntax error
CMLR-581 — CML parser detected syntax error
CMLR-582 — CML parser detected syntax error
CMLR-583 — CML parser detected syntax error
CMLR-584 — CML parser detected syntax error
CMLR-585 — CML parser detected syntax error
CMLR-586 — CML parser detected syntax error
CMLR-587 — CML SWITCH/CASE command syntax error
CMLR-590 — Configuration directive misformed
CMLR-591 — Configuration directive misformed
CMLR-592 — Configuration directive misformed
CMLR-593 — Configuration directive specified twice
CMLR-710 — Final loading result message
CMLR-712 — Configuration loading was aborted
CMLR-713 — INCLUDE statements with relative paths found
CMLR-720 — Operation not allowed in this point of configuration
CMLR-721 — Improper use of /EDIT command
CMLR-732 — CML command parameter invalid
CMLR-770 — Incorrect variable definition
CMLS-110 — Configuration file cannot be opened
CMLS-114 — Configuration was not succesfully saved
CMLS-311 — Inline-file line format invalid
CMLS-321 — Variable or sublist tree too deep
CMLS-501 — Incorrect variable usage
CMLS-505 — Incorrect for loop usage
CMLS-506 — Incorrect variable application
CMLS-507 — CML SWITCH command incompleteness found
CMLS-510 — Inline-file line format invalid
CMLS-511 — Inline-file line format invalid
CMLS-540 — Meaningless ACL found
CMLS-541 — ACL level 1 inconsistency
CMLS-551 — Incorrect for loop usage
CMLS-561 — Two SHARED files/directories have the same name
CMLS-569 — Shared file or directory check failed
CMLS-719 — Bad filter parameter of /SHOW command
CMLT-302 — Name chosen is not allowed
CMLT-501 — Name chosen is not allowed
CMLT-502 — Name chosen is not allowed
CMLT-521 — Incorrect variable usage
CMLT-530 — Reference leading toward end of configuration
CMLT-533 — Variable/path incosistency warning
CMLT-534 — Variable or reference invalid
CMLT-539 — Incorrect value used in CML
CMLT-540 — Incorrect CML path construction
CMLT-541 — Incorrect CML path construction
CMLT-542 — Incorrect CML path construction
CMLT-543 — Incorrect CML path construction
CMLT-544 — Incorrect CML path construction
CMLT-545 — Incorrect CML path construction
CMLT-548 — Incorrect CML path construction
CMLT-549 — Path continuation invalid
CMLT-550 — Reference chain loops back
CMLT-551 — CML reference invalid
CMLT-556 — CML reference invalid
CMLT-559 — Undefined value referenced
CMLT-560 — Integer value incompatibility
CMLT-561 — Mnemonic name misuse
CMLT-562 — IP address used is invalid
CMLT-563 — Overlapping range is to be added to list
CMLT-564 — Item element value incorrect
CMLT-565 — SOCK type incompatibility warning
CMLT-566 — Inline-file specification incorrect
CMLT-567 — Denied format of value used in CML
CMLT-568 — List value inconsistency
CMLT-569 — Type and value inconsistency
CMLT-570 — Configuration redundancy warning
CMLT-572 — Name chosen is not allowed
CMLT-573 — ACL name '*' inconsistency
CMLT-574 — Dynamic names for some section types unimplemented
CMLT-575 — CML SWITCH command syntax error
CMLT-577 — Illegal sections in for-loop definition
CMLT-578 — Context inconsistency warning
CMLT-579 — Section variable definition incorrect
CMLT-583 — String concatenation is allowed in variable definition only
CMLT-584 — Parameter declaration misplaced
CMLT-589 — Top level section misuse
CMLT-591 — Parametrized variable misuse
CMLT-592 — Parametrized variable misuse
CMLT-593 — List tail meaningless
CMLT-594 — List not closed by regular member
CMLT-599 — Name specification syntax error
CMLT-720 — Operation not allowed in this point of configuration
CMLT-722 — Clipboard empty
CMLT-723 — Cannot undelete node
CMLT-724 — Undelete not possible
CMLT-770 — CML operation not allowed due to context check
CMLT-771 — Incorrect CML edit operation
CMLT-772 — CML command misuse
CMLT-773 — Some member of multiitem clipboard is not valid for pasting
CMLT-774 — Clipboard containing more items cannot be renamed
CMLT-800 — CML configuration identification report
CMLT-801 — CML configuration CDF version report
CMLT-802 — CML configuration root path report
CMLT-803 — CML configuration origin report
CWBP-707 — Bypass has not been activated or has expired and must be reactivated
CWBP-708 — The bypass activation page has not been returned to the proxy in time
CWBP-709 — Bypass cannot be activated due to an internal error
CWBP-710 — Bypass Cookie header prepared
CWBP-711 — Maximum number of bypass sessions has been reached
CWBP-712 — Bypass has been activated for a set of categories
CWBP-717 — Bypass is disabled due to an internal error in the bypass table
CWBP-718 — A URL is temporarily accessible due to bypass
CWDB-716 — A set of categories has been looked up in the Clear Web DataBase
DHCP-523 — DHCP subnet and address definition inconsistent
DHCP-540 — DHCP failover configuration needs RANGE specified
DHDR-710 — Document header syntax error
DHDR-711 — Document header syntax error
DHDR-712 — Document header syntax error
DHDR-713 — Document header syntax error
DHDR-721 — Document header syntax error
DNSC-001 — Zone name not found in cache
DNSC-002 — Domain name not found in cache
DNSC-192 — Cannot get list of IP addresses
DNSC-580 — No valid root server record for zone
DNSC-590 — Non-periodical cleanup did not clear cache sufficiently
DNSC-600 — Received answer contains our own address to be queried
DNSC-700 — Cache storing function finds resource record of incorrect type
DNSC-701 — Resolving process cannot continue due to incorrect answer
DNSC-702 — Resource record set contains no valid authority records
DNSC-705 — Glue records missing
DNSC-750 — DNS server EDNS parameters announcement
DNSC-897 — Cache cleanup efectivity report
DNSC-898 — Cache cleanup final report
DNSC-899 — Cache capacity report
DNSC-980 — No valid server record for domain
DNSE-001 — Request state is invalid
DNSE-003 — Event on socket non belonging to any request
DNSE-012 — Used socket registered by another request
DNSE-013 — Request tried to open second server connection
DNSE-097 — Invalid event in particular request state
DNSE-105 — ALTQ queue assigment has failed
DNSE-109 — Syscall select() in main proxy loop failed
DNSE-120 — Binding to a random port failed
DNSE-130 — Getting a socket or preparing it to work failed
DNSE-210 — Reading request from UDP socket failed
DNSE-211 — Accepting connection on TCP socket failed
DNSE-212 — Reading request from TCP connection failed
DNSE-218 — Timeout expired when reading DNS query or response
DNSE-219 — Client closed TCP connection
DNSE-221 — Connection to server failed
DNSE-228 — Reading reply from DNS server failed
DNSE-230 — Sending request to server failed
DNSE-239 — Server has closed connection during sending query to it
DNSE-240 — Reading reply from server failed
DNSE-249 — Server closed TCP connection
DNSE-260 — Reply was not sent to client
DNSE-269 — Client has closed connection during sending reply to it
DNSE-300 — Request table is exhausted
DNSE-301 — Sockets table is exhausted
DNSE-308 — DNS request table monitoring message
DNSE-309 — Requests table dump final info
DNSE-310 — Received query length exceeds allowed size
DNSE-340 — Reading reply from server failed
DNSE-342 — UDP reply from server exceeds 512 bytes
DNSE-360 — Proxy cannot send response via TCP
DNSE-361 — Reply is too long, it could cause problem to resolver
DNSE-390 — Cannot connect server due to long name
DNSE-590 — Proxy tried all possible forwarders getting no answer
DNSE-612 — Named DNS operation not implemented
DNSE-613 — Only single-query requests implemented
DNSE-614 — Named resource record class not implemented
DNSE-615 — DNS extensions denied in configuration
DNSE-670 — Request/response contains unimplemented version of EDNS
DNSE-710 — Received query/response is shorter than minimal size
DNSE-711 — Request is formally incorrect
DNSE-712 — Named DNS operation not known
DNSE-713 — Request must contain exactly one QUERY
DNSE-714 — Query resource record contains unknown class
DNSE-715 — IXFR query with invalid NS part
DNSE-716 — Bad transport protocol for AXFR request
DNSE-740 — Proxy received reply with unexpected response code
DNSE-741 — Query section of the answer does not match one of request
DNSE-742 — Nameserver response contains invalid flags
DNSE-743 — Zone transfer response does not start with SOA
DNSE-744 — Incremental zone transfer response does not end with proper SOA
DNSE-745 — Misformed response from server
DNSE-749 — Server connection is not idle
DNSE-750 — Too deep recursion of internal requests
DNSE-760 — DNS request cancelled due response limit expiration
DNSE-790 — Proxy tried all possible servers getting no answer
DNSE-791 — Retry of request is not allowed
DNSE-792 — Information about domain contains no glue record
DNSE-793 — Querying to name loops back to itself
DNSE-794 — Reasonable amount of attempts exhausted
DNSE-795 — Informational output of requests dependency
DNSE-798 — Internal request final report
DNSE-799 — Request timed out
DNSI-500 — Section LISTEN-ON contains incorrect address
DNSP-010 — Searching of ACL failed
DNSP-500 — Zone transfer cannot be resolved
DNSP-510 — Cannot force source address in dns-proxy
DNSP-610 — Request is not covered by configuration
DNSP-641 — Reply resource record policy decision
DNSP-649 — Reply resource record not found in configuration
DNSP-700 — Notification about the mode of operation of the proxy
DNSP-701 — The proxy has been initialized and is ready to accept packets
DNSP-708 — The proxy has unbound the sockets used for listening for clients
DNSP-709 — Final proxy termination message
DNSP-710 — Proxy runtime monitoring support cannot be initialized
DNSP-723 — The proxy has finished
DNSP-808 — Session has started, client connection has arrived
DNSP-809 — DNS session finished
DNSP-810 — ACL decision has been made, operation either accepted or rejected
DNSP-820 — ACL decision has been made, operation either accepted or rejected
DNSP-860 — Request processing finished
DNSP-888 — Unified DNS proxy statistics message
DNSR-001 — Name or label being stored is too long
DNSR-011 — Resource record of unknown type being stored
DNSR-301 — Read domain name exceeds 254 characters
DNSR-310 — DNS message RR count limit reached
DNSR-630 — Answer resource record has class oher than IN
DNSR-631 — Answer resource record has unimplemented or incorrect type
DNSR-653 — Query resource record type unimplemented
DNSR-654 — Reply resource record type unimplemented
DNSR-702 — Label contains incorrect character
DNSR-703 — Token does not start with 00 or 11 bits couple
DNSR-704 — Token length exceeds end of block
DNSR-705 — Token references offset greater than offset of itself
DNSR-710 — Resource record length differs from length field value
DNSR-711 — Resource record exceeds block boundary
DNSR-712 — Misformed CAA resource record
DNSR-717 — Received block length disagree with total length of resource records
DNSR-718 — Received block length disagree with total length of resource records
DNSR-719 — Resource record formally incorrect
DNSR-730 — Nameserver response inconsistency message
DNSR-731 — General appearance incorrectness message
DNSR-732 — DNS reply contains incorrect CNAME
DNSR-734 — Irrelevant additional record found
DNSR-735 — Nameserver response contains invalis CNAME chain
DNSR-753 — Query resource record type unknown
DNSR-754 — Reply resource record type unknown
DNSR-760 — EDNS0 OPT RR must close ADDITIONAL section
DNSR-761 — EDNS0 OPT RR must have empty name
DNSX-501 — QUERY or REPLY item will never act
DNSX-502 — No QUERY item contains operation requiring REPLY/FAKE definition
DNSX-503 — No REPLY item found in forwarding or resolving ACL
DNSX-510 — Faked name is longer then 254 characters
DNSX-511 — Faked name label is longer then 64 characters
DNSX-512 — Faked name contains invalid character
DNSX-513 — Faked address is not of proper type
DNSX-520 — Regexps used for query name matching must end with dot
FTPH-050 — FTP server directory format unknown
FTPH-710 — Internal HTTP to FTP protocol error
FTPH-711 — Internal HTTP to FTP protocol error
FTPH-712 — Internal HTTP to FTP protocol error
FTPH-713 — Internal HTTP to FTP protocol error
FTPH-714 — Internal HTTP to FTP protocol error
FTPH-715 — Internal HTTP to FTP protocol error
FTPH-716 — Internal HTTP to FTP protocol error
FTPH-739 — Resending FTP server reply to HTTP proxy
FTPH-750 — FTP directory listing not understood
FTPP-090 — TCP server returned with error
FTPP-099 — Final startup failure message
FTPP-573 — Proxy probably uses reserved port and will not operate
FTPP-808 — Session has started, client connection has arrived
FTPP-809 — Session finished
FTPP-888 — Unified TCP proxy statistics message
FTPS-009 — Answer prepared for client has no response code
FTPS-100 — FTP proxy control channel initialisation failed
FTPS-105 — ALTQ queue assigment has failed
FTPS-110 — Searching of ACL failed
FTPS-119 — Authentication system is unsable
FTPS-131 — Connection to server failed
FTPS-230 — Target server name cannot be resolved to IP address
FTPS-232 — Target server connection failed
FTPS-234 — Targer server response invalid
FTPS-238 — I/O operation on socket failed
FTPS-239 — Control socket closed by peer
FTPS-341 — Client reply buffer is over
FTPS-342 — Data command parameter exceeded internal buffer size
FTPS-530 — Next-hop server/proxy name cannot be resolved to IP address
FTPS-532 — Next-hop server/proxy connection failed
FTPS-534 — Next-hop server/proxy response invalid
FTPS-628 — User illegally requested connection to non-ftp port
FTPS-640 — FTP command has been rejected
FTPS-642 — Simple username expected
FTPS-643 — Username should contain target server
FTPS-644 — Password must combine proxy user's and remote user's ones
FTPS-679 — PORT family command has illegal parameter
FTPS-690 — Data transfer size limit exceeded
FTPS-691 — Data transfer size limit exceeded
FTPS-701 — Timeout reached
FTPS-710 — Too many commands used prior to connecting to server
FTPS-732 — Command not allowed if target server known
FTPS-738 — Remote server has answered with error message
FTPS-739 — Remote server has logically closed session
FTPS-744 — RNTO received without RNFR
FTPS-745 — Proxy received an unknown command
FTPS-746 — FTP command syntax error
FTPS-747 — FTP initialisation command USER/PASS duplicated
FTPS-748 — User setting required
FTPS-749 — Port required by user is invalid
FTPS-771 — Received EPSV command with bad argument
FTPS-773 — Data transfer parameter commands invalid if EPSV ALL is set
FTPS-774 — PORT family command contains bad argument
FTPS-791 — Reissuing the REST command failed
FTPS-810 — ACL decision has been made, operation either accepted or rejected
FTPS-819 — Proxy user authentication finished
FTPS-820 — ACL decision has been made, operation either accepted or rejected
FTPS-840 — FTP command received
FTPS-870 — File Transfer Protocol command handling
FTPT-001 — Wrong address of server requested
FTPT-101 — FTP proxy data channel initialisation failed
FTPT-105 — ALTQ queue assigment has failed
FTPT-110 — Searching of ACL failed
FTPT-119 — Cannot recognize document type
FTPT-181 — Data connection accept failed
FTPT-280 — Data connection to peer cannot be established
FTPT-281 — Cannot create listening socket for data transfer
FTPT-288 — Data connection not established
FTPT-289 — Another data connection arrived
FTPT-600 — Data arrived from wrong peer
FTPT-688 — PASV family command response contains bad address
FTPT-689 — Data connection arrived from bad peer
FTPT-690 — Data transfer size limit exceeded
FTPT-702 — Listening timeout expired
FTPT-746 — FTP command syntax error
FTPT-772 — Received repeated data transfer parameter command
FTPT-788 — PASV family command response invalid
FTPT-830 — ACL decision has been made, operation either accepted or rejected
FTPT-872 — Client used data command without transfer parameter setting
FTPT-880 — Data transfer initialized
FTPT-881 — Data connection server established
FTPT-890 — Data transfer stopped
H225-300 — Parser ran out of read buffer
H225-700 — Unrecoverable H.323 parser error
H225-710 — Received packet with unimplemented H.323 feature
H225-720 — Received packet with more RAS/CSA addresses
H245-700 — Unrecoverable H.323 parser error
H245-710 — Received packet with unimplemented H.323 feature
H245-711 — Received packet with unimplemented H.323 feature
HTCT-100 — An operation with the cookie table failed
HTCT-102 — An operation with the cookie table failed
HTCT-104 — An operation with the cookie table failed
HTCT-105 — An operation with the cookie table failed
HTCT-107 — An operation with the cookie table failed
HTCT-108 — An operation with the cookie table failed
HTCT-800 — A cookie has been received from other client than expected
HTCW-100 — Closing a Clear Web DataBase file failed
HTCW-101 — Opening a Clear Web DataBase file failed
HTCW-102 — Reading all records from a Clear Web DataBase file failed
HTCW-103 — The Clear Web DataBase cannot test whether its database was changed
HTCW-104 — Search operation in the Clear Web DataBase file failed
HTCW-105 — Inserting a record into the Clear Web DataBase file failed
HTCW-106 — Deleting a record from the Clear Web DataBase file failed
HTCW-700 — The Clear Web DataBase cannot open its updated database file
HTTA-100 — AProxy session table initialization failed
HTTA-101 — AProxy session table initialization failed
HTTA-102 — A new proxy process cannot use the session table
HTTA-157 — AProxy session table lock cannot be unlocked
HTTA-500 — AProxy session table must have non-zero size
HTTA-502 — Required item OOB_AUTH-SRV missing in configuration
HTTA-600 — An error occurred when calling authentication functions
HTTA-601 — RADIUS state does not fit into the session table entry
HTTA-710 — Information about OOB user authentication
HTTA-720 — Information about AProxy user authentication
HTTA-801 — Client returned invalid authentication data to AProxy
HTTA-802 — AProxy session table lock cannot be locked
HTTA-803 — Maximum number of sessions reached, no new session cannot be created
HTTA-804 — User name does not fit into the session table entry
HTTA-805 — Client returned invalid contents of the authentication form to AProxy
HTTA-806 — AProxy cannot prepare the authentication form
HTTA-807 — List of groups does not fit into the session table entry
HTTA-808 — OOB external authentication produces too long lines
HTTA-809 — OOBA update list line not understood
HTTA-810 — Unterminated line at the end of an OOBA update list is ignored
HTTA-811 — An OOB-authenticated user cannot be found in LDAP
HTTA-812 — A user tried logout without previous login
HTTA-813 — Authentication form incorrectly filled/sent
HTTA-858 — AProxy cannot decode the request
HTTF-800 — The proxy cannot convert FTP directory listing into an HTML page
HTTF-801 — The proxy cannot convert FTP directory listing into an HTML page
HTTF-802 — The proxy cannot convert FTP directory listing into an HTML page
HTTH-025 — Invalid method number in parsed request line
HTTH-101 — The proxy cannot replace credentials
HTTH-102 — The proxy cannot replace credentials
HTTH-105 — ALTQ queue assigment has failed
HTTH-300 — The response body is shorter than expected according to Content-Length
HTTH-600 — Kerberos authentication has failed
HTTH-702 — A new request has been started
HTTH-703 — Information about user authentication on the proxy
HTTH-704 — A URL is temporarily accessible due to bypass
HTTH-705 — Bypass has been activated for a single domain
HTTH-706 — Bypass life time has expired and must be reactivated
HTTH-707 — Bypass has not been activated or has expired and must be reactivated
HTTH-708 — The bypass activation page has not been returned to the proxy in time
HTTH-709 — Bypass cannot be activated due to an internal error
HTTH-711 — Maximum number of bypass sessions has been reached
HTTH-712 — Bypass has been activated for a set of categories
HTTH-713 — A request has terminated
HTTH-714 — A request has terminated
HTTH-715 — Detail request information
HTTH-716 — A set of categories has been looked up in the Clear Web DataBase
HTTH-717 — Bypass is disabled due to an internal error in the bypass table
HTTH-718 — A URL is temporarily accessible due to bypass
HTTH-741 — Proxy repairs invalid Host request header
HTTH-750 — Data from server were rejected by antivirus checking
HTTH-788 — Cannot set the value of the IP packet TOS field
HTTH-789 — Kerberos authentication cannot obtain group information from LDAP
HTTH-790 — An unsupported authentication header has been received
HTTH-791 — Negotiate authentication data format is invalid
HTTH-792 — The proxy cannot initialize client CONNECT data filtering
HTTH-793 — The proxy cannot initialize server CONNECT data filtering
HTTH-794 — The proxy cannot perform NTLM authentication
HTTH-795 — NTLM authentication data format is invalid
HTTH-796 — The proxy cannot execute an external program
HTTH-797 — Bad format of a cookie deletion request
HTTH-798 — Matching of request body data not possible
HTTH-799 — Matching of response data not possible
HTTH-800 — Cannot decode the server response due to an unsupported encoding
HTTH-801 — Http-proxy cannot communicate with ftp-proxy
HTTH-802 — Connection of http-proxy with ftp-proxy, is not configured
HTTH-803 — The client has not sent compulsory HTTP/1.1 Host header
HTTH-804 — Challenge/response proxy authentication is not supported
HTTH-805 — The request URI has been invalidated by a rewrite operation
HTTH-806 — The request specifies an unsupported scheme
HTTH-807 — Setup for request body decoding failed
HTTH-808 — Setup for request body encoding failed
HTTH-809 — The proxy cannot initialize the image filtration module
HTTH-810 — The proxy received the status line from the server twice
HTTH-811 — Reports REQUEST-ACL used for this request
HTTH-812 — HTTP header name contains an illegal character
HTTH-813 — HTTP header does not contain the colon separating name and value
HTTH-814 — Repeated HTTP header which may occur only once
HTTH-815 — Value of a HTTP header is invalid and cannot be parsed
HTTH-816 — Internal form of a HTTP header is invalid
HTTH-817 — Repeated HTTP header which may occur only once
HTTH-818 — HTTP request line must contain a HTTP method
HTTH-819 — HTTP request line must contain a HTTP request URI
HTTH-820 — HTTP version in request or response is invalid
HTTH-821 — Something invalid at the end of the HTTP request line
HTTH-822 — A bad %xx sequence in URI has been encountered
HTTH-823 — Internal form of URI is invalid
HTTH-824 — Internal form of HTTP version is invalid
HTTH-825 — Internal form of HTTP request line is invalid
HTTH-826 — Status line must contain version identifier
HTTH-827 — Status line must contain a valid status code
HTTH-828 — Internal form of HTTP status line is invalid
HTTH-829 — Internal form of a HTTP header is invalid
HTTH-830 — Unknown type of authentication
HTTH-831 — URI cannot be parsed
HTTH-832 — Only GET method is allowed in HTTP v. 0.9 requests
HTTH-833 — Received HTTP message has an unsupported version of HTTP
HTTH-834 — Content-Length header contains an invalid value
HTTH-835 — Request or status line is forbidden by REQUEST-ACL
HTTH-836 — Request or response header is forbidden by REQUEST-ACL
HTTH-837 — Request failed due to inoperative web filter
HTTH-838 — Invalid HTTP status code in response from server
HTTH-839 — Request continues despite web filter failure
HTTH-840 — Proxy cannot configure NAT address mapping on connection to server
HTTH-841 — Proxy cannot initialize data related to server connection
HTTH-842 — Proxy cannot create modules for communication with the server
HTTH-843 — Proxy cannot create module for sending CONNECT response headers
HTTH-844 — The proxy cannot process response headers
HTTH-845 — An unexpected error occurred when searching REQUEST-ACLs
HTTH-846 — The request is denied because it does not match any REQUEST-ACL
HTTH-847 — Matching REQUEST-ACL contains item DENY
HTTH-848 — Request URI has a form unsupported by http-proxy
HTTH-849 — A file to be sent as a response does not exist or is not readable
HTTH-850 — Antivirus has reported a virus
HTTH-851 — The proxy is unable to verify user authentication
HTTH-852 — The proxy cannot establish an SSL/TLS secure channel to the server
HTTH-853 — The request specifies an unsupported scheme
HTTH-854 — AProxy is enabled in the configuration, but cannot be initialized
HTTH-855 — FTP requests allow only downloading (GET) and uploading (PUT) data
HTTH-856 — HTTP Host header contains an invalid port number
HTTH-857 — Proxy cannot interpret Transfer-Encoding header
HTTH-858 — Transfer-Encoding header defines an incorrect encoding
HTTH-859 — Transfer-Encoding header defines an incorrect encoding
HTTH-860 — Communication with a FTP server failed
HTTH-861 — A file to be sent as a response does not exist or is not readable
HTTH-862 — The proxy cannot decode chunked trasfer encoding of response
HTTH-863 — The proxy cannot use an external program to reply to a request
HTTH-864 — Cannot decode the server response due to an unsupported encoding
HTTH-865 — Proxy informs the client about an unsupported content encoding
HTTH-866 — The proxy cannot encode the response into the chunked encoding
HTTH-867 — The proxy cannot decode a gzipped response
HTTH-868 — The proxy cannot perform requested HTML filtration
HTTH-869 — The proxy cannot return a directory listing obtained from ftp-proxy
HTTH-870 — The proxy cannot send the response to the antivirus
HTTH-871 — The client has closed the connection when it should not
HTTH-872 — The request line is wrong
HTTH-873 — A request cannot escape from a subdirectory
HTTH-874 — The request headers are wrong
HTTH-875 — Proxy cannot configure NAT address mapping on connection to ftp-proxy
HTTH-876 — Forwarding the request to ftp-proxy failed
HTTH-877 — Request line processing failed
HTTH-878 — The request line does not fit into the appropriate buffer
HTTH-879 — Request header processing failed
HTTH-880 — A request line does not fit into the appropriate buffer
HTTH-881 — The server has closed the connection when it should not
HTTH-882 — The status line is wrong
HTTH-883 — A cookie modification failed
HTTH-884 — The response headers are wrong
HTTH-885 — Status line processing failed
HTTH-886 — The status line does not fit into the appropriate buffer
HTTH-887 — Response header processing failed
HTTH-888 — A response line does not fit into the appropriate buffer
HTTH-889 — The request would require the proxy to connect back to itself
HTTH-890 — HTTP header value contains an illegal character
HTTH-891 — Repeated HTTP header which may occur only once
HTTH-892 — An unexpected error occurred when searching DOC-ACLs
HTTH-893 — Reports DOC-ACL used for this request
HTTH-894 — The request is denied because it does not match any DOC-ACL
HTTH-895 — Matching DOC-ACL contains item DENY
HTTH-896 — Proxy cannot use the module for guessing MIME types
HTTH-897 — The server has specified response body length incorrectly
HTTH-898 — The client has specified request body length incorrectly
HTTH-899 — The proxy is unable to verify user authentication
HTTH-901 — The proxy cannot extract lifetime information from a cookie
HTTH-923 — Proxy requests user authentication
HTTH-924 — Proxy authentication request sent to client
HTTH-925 — Proxy authentication request sent to client
HTTH-926 — Cannot create SSL/TLS with buffer
HTTH-927 — SSL/TLS accept did not fail with expected error
HTTH-928 — Client did not send anything
HTTH-929 — Skipping SNI inspection in unknown protocol
HTTH-930 — Skipping SNI inspection in SSLv3
HTTH-931 — Skipping SNI inspection because message size from SSL/TLS header does not match data size
HTTH-932 — Skipping SNI inspection in unknown protocol
HTTH-934 — Skipping SNI inspection in Skype protocol
HTTH-935 — Accept-Encoding header parsing failed
HTTH-936 — Skipping SNI inspection in empty message
HTTH-937 — SNI inspection resulted in an error
HTTP-104 — The main loop for serving clients (tcpserver) failed
HTTP-105 — ALTQ queue assigment has failed
HTTP-123 — Blacklist database cannot be used
HTTP-124 — The proxy cannot use SSL/TLS
HTTP-125 — The table for storing modified cookie cannot be initialized
HTTP-126 — The proxy cannot delete stored cookie values
HTTP-127 — The proxy cannot get a Kerberos ticket for LDAP
HTTP-501 — AProxy configuration error
HTTP-502 — AProxy configuration error
HTTP-710 — A new proxy session has been started
HTTP-711 — A proxy session has terminated
HTTP-712 — Session ACLs have been processed
HTTP-740 — Connecting to server in SSL/TLS inspection
HTTP-741 — No SNI specified
HTTP-801 — Error during initial processing of a new session
HTTP-802 — The next request on a persistent connection cannot be processed
HTTP-803 — Error during initialization of a new request
HTTP-804 — The client has closed the connection to the proxy
HTTP-810 — The proxy is unable to respond with a local file
HTTP-811 — The proxy is unable to respond with a local file
HTTP-812 — The proxy is unable to respond with a local file
HTTP-813 — Data size limit has been exceeded
HTTP-814 — Data size limit has been exceeded
HTTP-815 — Data size limit has been exceeded
HTTP-816 — Data size limit has been exceeded
HTTP-817 — An unexpected error occurred when searching SESSION-ACLs
HTTP-818 — The session is denied because it does not match any SESSION-ACL
HTTP-819 — Matching SESSION-ACL contains item DENY
HTTP-820 — The proxy captured a CONNECT request and will handle it itself
HTTP-821 — The proxy creates a TCP tunnel to the server
HTTP-822 — A shared library cannot be used
HTTP-823 — A shared library does not contain a required function
HTTP-824 — A shared library cannot be initialized
HTTP-825 — The proxy is unable to respond with locally generated data
HTTP-826 — SNI was inspected, now HTTPS will be inspected
HTTP-852 — The proxy cannot establish an SSL/TLS secure channel from the client
HTTP-888 — Unified HTTP proxy statistics message
HTTX-540 — Incomplete FAKE-CERT configuration
HTTX-810 — Cannot use FAKE-CERT on server SSL
HTTX-811 — Server SSL must be defined when FAKE-CERT used
HTTX-812 — Cannot define server SSL when FAKE-CERT not used
HTTX-813 — SNI-INSP must be defined in SSL-PARAMS referenced by SNI-SSL
HTTX-814 — SNI-INSP cannot be defined in SSL-PARAMS referenced by CLIENT-SSL
HTTX-815 — SNI-INSP cannot be defined in SSL-PARAMS referenced by SERVER-SSL
HTTX-816 — CAPTURED-CONNECT request will fail when SNI-RESULT is UNKNOWN-PROTOCOL
HTTX-817 — CAPTURED-CONNECT request will fail when SNI-RESULT is SKYPE
ICAB-700 — Received ICAP message has unsupported version of ICAP
ICAB-701 — ICAP version in request is invalid
ICAB-710 — ICAP request line misformed
ICAB-711 — Request line ends incorrectly
ICAB-720 — ICAP Encapsulation header is syntactically incorrect
ICAB-725 — ICAP Host header contains invalid port number
ICAB-730 — Unknown type of authentication
ICAP-888 — Unified ICAP server statistics message
ICAR-120 — An unexpected error occurred when searching REQUEST-ACLs
ICAR-140 — Setup for request body decoding failed
ICAR-150 — Proxy cannot use the module for guessing MIME types
ICAR-160 — ICAP server cannot send data to the antivirus
ICAR-170 — ICAP server cannot establish chunked encoding of data
ICAR-200 — ICAP client has closed connection in improper situation
ICAR-580 — The status line does not fit into the appropriate buffer
ICAR-581 — A response line does not fit into the appropriate buffer
ICAR-620 — Matching SERVICE-ACL contains item DENY
ICAR-621 — The request is denied because it does not match any SERVICE-ACL
ICAR-625 — Matching REQUEST-ACL contains item DENY
ICAR-626 — The request is denied because it does not match any REQUEST-ACL
ICAR-630 — Matching DOC-ACL contains item DENY
ICAR-631 — The request is denied because it does not match any DOC-ACL
ICAR-711 — ICAP request line sent by client is wrong
ICAR-712 — ICAP request headers are wrong
ICAR-713 — Error occured when reading HTTP headers encapsulated in ICAP request
ICAR-715 — Received ICAP request with unsupported feature
ICAR-716 — Client has not sent compulsory Host header
ICAR-727 — Challenge/response server authentication is not supported
ICAR-728 — Proxy requests user authentication
ICAR-729 — ICAP server is unable to verify user authentication
ICAR-740 — Errorneous or duplicite Encapsulated header
ICAR-760 — HTTP request within ICAP request does not contain Host header
ICAR-761 — Antivirus check final result report
ICAR-810 — A new request has been started
ICAR-818 — Summary of HTTP session being inspected by ICAP server
ICAR-819 — A request has terminated
ICAR-820 — Reports SERVICE-ACL used for this request
ICAR-825 — Reports REQUEST-ACL used for this request
ICAR-829 — Information about user authentication on server
ICAR-830 — Reports DOC-ACL used for this request
ICAS-090 — TCP server returned with error
ICAS-099 — Final startup failure message
ICAS-111 — Blacklist database cannot be used
ICAS-130 — Error during initial processing of a new session
ICAS-131 — The next request on a persistent connection cannot be processed
ICAS-132 — ICAP server cannot establish an SSL/TLS secure channel from the client
ICAS-133 — ALTQ queue assigment has failed
ICAS-139 — Error during initialization of a new request
ICAS-150 — The server is unable to respond with a local file
ICAS-191 — ICAP server cannot use SSL/TLS
ICAS-210 — Client has improperly closed connection
ICAS-220 — Client exceeded maximum time between requests
ICAS-230 — Client exceeded maximum time for request completing
ICAS-330 — Data size limit has been exceeded
ICAS-621 — Session denied due to no matching SESSION-ACL
ICAS-622 — Matching SESSION-ACL contains item DENY
ICAS-801 — Session has started, client connection has arrived
ICAS-809 — Session finished
ICAS-821 — SESSION-ACL search report
IFSC-100 — Cannot create socket for interface status checking
IFSC-101 — Cannot connect to socket for interface status checking
IFSC-120 — Cannot read from socket for interface status checking
IFSC-320 — Line read from socket for interface status checking is not understood
IFSC-710 — Interface status change message
IFSC-720 — Socket for interface status checking has been closed
IMAP-100 — The main loop for serving clients (tcpserver) failed
IMAP-101 — ALTQ queue assigment has failed
IMAP-200 — Cannot change source address of a connection to a server
IMAP-201 — The proxy cannot initialize a connection to a server
IMAP-202 — The proxy cannot initialize a connection to a server
IMAP-700 — Session ACL has been processed
IMAP-701 — Command ACL has been processed
IMAP-702 — A client has been disconnected from the proxy
IMAP-704 — A new client has connected to the proxy
IMAP-706 — Information about direction of a mail transfer
IMAP-710 — A command has been denied by ACL
IMAP-711 — A capability has been denied by ACL
IMAP-712 — An unimplemented capability received from the server
IMAP-713 — An unimplemented command received from the client
IMAP-760 — Mail ACL has been processed
IMAP-800 — Proxy initialization failed
IMAP-801 — An error occurred during searching SESSION-ACLs
IMAP-802 — The client has been denied by SESSION-ACL
IMAP-803 — The proxy is unable to verify user authentication
IMAP-804 — The proxy does not know a server address to connect
IMAP-805 — Initial processing of a new client connection has failed
IMAP-806 — Proxy cannot start SSL/TLS on the client connection
IMAP-807 — Proxy cannot start IMAP4 protocol
IMAP-808 — An error occurred during searching COMMAND-ACLs
IMAP-809 — The client has been denied by COMMAND-ACL
IMAP-810 — Limit for session duration has been reached
IMAP-811 — The client is sending too much data
IMAP-812 — The server is sending too much data
IMAP-813 — Proxy cannot start SSL/TLS on the server connection
IMAP-814 — The session is being idle for too long
IMAP-817 — A temporary file cannot be read
IMAP-818 — A mail from the server cannot be processed
IMAP-819 — The proxy is unable to get size of a temporary file
IMAP-820 — The client has unexpectedly disconnected from the proxy
IMAP-821 — The server has unexpectedly disconnected from the proxy
IMAP-822 — A FETCH response does not correspond to the FETCH command
IMAP-823 — Proxy cannot decode length of a literal
IMAP-824 — A client command line is too long
IMAP-825 — A server response line is too long
IMAP-843 — IMAP4 BINARY protocol extension (RFC3516) is not implemented
IMAP-844 — The proxy does not understand a request for mail data
IMAP-845 — The proxy detented data which should not occur in a FETCH response
IMAP-846 — The server response is not a valid mail
IMAP-847 — Bad format of an IMAP4 command line
IMAP-848 — A command tag does not fit to a buffer in the proxy
IMAP-850 — The proxy cannot create a temporary file
IMAP-851 — The proxy is unable pro process a mail
IMAP-852 — A mail from client to server is denied by configuration
IMAP-853 — A mail from client to server is denied by configuration
IMAP-854 — Bad format of an IMAP4 response line
IMAP-855 — A response tag does not match the last last command
IMAP-856 — A response tag does not match the last last command
IMAP-857 — The proxy is unable to get size of a temporary file
IMAP-858 — A command tag does not fit to a buffer in the proxy
IMAP-860 — The proxy cannot create a temporary file
IMAP-861 — The proxy cannot start processing of a mail
IMAP-862 — A mail from server to client is denied by configuration
IMAP-863 — A mail from server to client is denied by configuration
IMAP-865 — The proxy cannot finish processing of a mail
IMAP-867 — The client asked for a nonexistent part of a mail
IMAP-868 — The proxy cannot sent a mail in the form of literal string
IMAP-870 — There is not cached mail in the proxy
IMAP-871 — The proxy received unexpected data from the server
IMAP-888 — Unified IMAP4 proxy statistics message
IPCL-100 — The proxy cannot create a lock for synchronizing its processes
IPCL-101 — The proxy cannot write its PID to the lock file
IPCL-102 — The proxy cannot close a lock file
IPCL-103 — The proxy cannot delete a lock file
IPCL-104 — A proxy process cannot open a lock file
IPCL-106 — A proxy process cannot lock a lock file
IPCL-107 — A proxy process cannot unlock a lock file
IPSE-800 — Bad interface referenced in an IPSEC configuration section
IPSE-801 — No interface referenced in an IPSEC configuration section
IPSE-802 — Configuration directory of the ISAKMP daemon cannot be generated
IPSE-803 — The specified DH group value is not allowed
KERN-001 — Function called with NULL parameter
KERN-002 — Expression has incorrect (NULL) value
KERN-003 — An unexpected true value of a Boolean expression detected
KERN-011 — Library function returned unknown return value
KERN-012 — Application has detected an incorrect value
KERN-013 — Application has detected an incorrect value
KERN-020 — Application reached unreachable code
KERN-100 — System call failed with reported errno
KERN-510 — Regexp in FROM and TO items are meaningless
KERN-515 — Address has other address family than expected
KEYV-701 — Keyword-value parser error
KEYV-702 — Keyword-value parser error
KEYV-703 — Keyword-value parser error
KEYV-704 — Keyword-value parser error
KEYV-710 — Keyword-value parser error
KEYV-711 — Keyword-value parser error
KEYV-751 — Keyword-value parser error
KEYV-770 — MIME header continuation incomplete
LDAP-301 — Buffer for ldap filter is too short for storing string "(|(attribute_name=value)(attribute_name=value))"
LDAP-302 — Buffer for ldap filter is too short for storing string "(attribute_name=value)"
LDAP-501 — Bad attribute name
LDAP-502 — Invalid configuration of the server's URI
LDAP-601 — Bad username
LDAP-603 — User not found in the LDAP database
LDAP-607 — Bind to account successful
LDAP-610 — Bind LDAP server to the user's DN unsuccessful due to invalid credentials
LDAP-613 — Error when binding to the LDAP server using user's DN
LDAP-701 — LDAP initialization failed
LDAP-702 — More than 1 value returned as the group name
LDAP-703 — Setting LDAP_OPT_X_TLS_KEYFILE failed
LDAP-704 — More than one object for user found in named LDAP directory
LDAP-706 — More than one value returned as the users default GID number
LDAP-707 — ldap_start_tls_s returned error
LDAP-709 — Error while searching for the user's UID number
LDAP-710 — Error getting users's DN
LDAP-711 — Error retrieving group number from the group's node
LDAP-712 — Error retrieving user's default GID number
LDAP-713 — Error while searching for the user's GID list
LDAP-714 — Setting LDAP_OPT_X_TLS_REQUIRE_CERT option failed
LDAP-715 — Setting LDAP_OPT_TIMEOUT option failed
LDAP-716 — Setting LDAP_OPT_TIMELIMIT failed
LDAP-717 — Setting LDAP_OPT_NETWORK_TIMEOUT option failed
LDAP-718 — Error binding to the LDAP server
LDAP-721 — Setting LDAP_OPT_PROTOCOL_VERSION option failed
LDAP-722 — Setting LDAP_OPT_X_TLS_CERTFILE failed
LDAP-723 — Setting LDAP_OPT_X_TLS_CACERTFILE option failed
LDAP-724 — Setting LDAP_OPT_X_TLS_CACERTDIR option failed
LDAP-726 — Error retrieving group number from the group's node
LDAP-727 — Getting LDAP_OPT_X_TLS_CTX option failed
LDAP-728 — Setting LDAP_OPT_X_TLS_CTX option failed
LDAP-729 — List of groups for a user cannot be obtained from Active Directory
LDAP-730 — List of groups for a user cannot be obtained from Active Directory
LDAP-731 — List of groups for a user cannot be obtained from Active Directory
LDAP-732 — List of groups for a user cannot be obtained from Active Directory
LDAP-733 — Setting LDAP_OPT_REFERRALS failed
LDAP-734 — Failed to reinitialize the LDAP structure
LDAP-901 — Unsuscpected behaiour; ldap_result returned unsuspected value
LIBA-700 — Reports the list of user groups matched by an ACL
LIBA-810 — Statistical message for R.U.R. analysis
LIBI-009 — Closing of file descriptor failed
LIBI-101 — Socket number not applicable to select()
LIBI-102 — Traffic shaping support not present in kernel and system libraries
LIBI-103 — Cannot configure traffic shaping for a network socket
LIBI-141 — Function dupip() failed to allocate memory
LIBI-220 — Setting of socket option failed
LIBI-221 — File descriptor flag operation failed
LIBI-230 — Attempt to connect timed out
LIBI-752 — Internal routines cannot resolve domain name
LIBP-031 — System call of sigaction() failed
LIBP-120 — System call to daemon() failed
LIBP-130 — Parent process cannot resend signal to children
LIBP-730 — Kernun signal handler caught signal
LIBP-931 — Kernun signal handler has been registered
LIBT-001 — Syscall gettimeofday() failed
LIBT-120 — System clock disruption
LIBT-150 — Sleeping for a time interval terminated with error
LIBT-959 — A system call was interrupted by a signal
LIBU-020 — Wrong formatting directive
LIBU-021 — Printing bad address argument
LIBU-022 — Printing bad regexp argument
LIBU-023 — Printing bad IP argument
LIBU-140 — Error during re-creating file
LIBU-141 — Cannot properly set attributes of file created
LIBU-142 — Required file/directory does not exist
LIBU-143 — Filename already used
LIBU-144 — Filename already used
LIBU-145 — Input file opening failed
LIBU-146 — File cannot be renamed
LIBU-150 — System call failed
LIBU-155 — System control variable access failed
LIBU-156 — System control variable has invalid type
LIBU-320 — Printing too long string
LIBU-330 — Filename too long
LIBU-510 — Regular expression library fails to compile given regexp
LIBU-530 — Filename contains invalid characters
LIBU-533 — Filename longer than OS limitations
LIBU-534 — Library function cannot assemble file name
LICC-100 — The Kernun license file cannot be found or read
LICC-101 — The license fail verification failed
LICC-102 — Cannot check hardware serial number
LICC-103 — Cannot check hrdware serial number
LICC-500 — A component is not available and cannot be configured
LICC-501 — A component is not available and cannot be configured
LICC-502 — Each SYSTEM section should contain PRODUCT specification
LICC-700 — Information about a license
LICC-701 — Reports date when new functionality will not be licensed
LICC-800 — The license file has bad content
LICC-801 — The license file does not permit the named component to run
LICC-802 — The license is no longer valid
LICC-803 — Cannot check hardware serial number
LICC-804 — License was issued for another computer
LICC-805 — License was issued for another software version
LIST-001 — There are bad links in a linked list data structure
LSQL-101 — Opening the SQLite file with honeypot blacklist database failed
LSQL-103 — Removing of old format Honeypot DB file failed
LSQL-109 — SQLite database cannot be closed
LSQL-110 — SQL command compilation failed
LSQL-111 — SQL command execution failed
LSQL-119 — SQL command execution failed
LSQL-701 — Cannot set version to honeypot blacklist database
LSQL-702 — AK47 blacklist database has incorrect version
LSQL-703 — Removing of old format Honeypot DB file succeeded
LSTN-150 — Listen-on data structure array cannot be allocated
LSTN-250 — Proxy listening socket creation failed
LSTN-251 — Socket option failed to be set on the socket
LSTN-550 — Application cannot resolve address it should be listening on
LSTN-551 — The given IP address is not configured on any interface
LSTN-552 — No server address to listen on
LSTN-553 — Application cannot find address it should be listening on
LSTN-554 — Failed to prepare listening address
LSTN-555 — Failed to prepare listening address
LSTN-559 — No socket for requested traffic defined in listen-on section
LSTN-950 — Listening socket has been prepared
LSTN-953 — Listen-on address protocol family was deduced
LSTN-954 — Listen-on address protocol family was deduced
MAVC-120 — Antivirus module cannot initialize file for communication with engine
MAVC-121 — Antivirus module cannot initialize file for communication with engine
MAVC-123 — Antivirus module cannot read data
MAVC-130 — Communication with antivirus failed
MAVC-180 — Antivirus module cannot read data
MAVC-181 — Communication with antivirus failed
MAVC-510 — Antivirus list is empty
MAVC-600 — Antivirus check has found some viruses
MAVC-700 — Final antivirus check result report
MAVC-730 — Zero-length file check bypassed
MAVC-731 — Data are not checked by antivirus due to too big size
MAVP-209 — Antivirus communication problem
MAVP-310 — Request for an antivirus does not fit into a buffer
MAVP-550 — Configured URI for ICAP server antivirus check is invalid
MAVP-600 — Antivirus engine has found some virus
MAVP-652 — ICAP antivirus server returns non-virus violation
MAVP-701 — Unknown status message returned by antivirus engine
MAVP-707 — Error status message returned by antivirus engine
MAVP-708 — Proxy does not understand responses from antivirus engine
MAVP-709 — EOF received when waiting for data from antivirus
MAVP-731 — ClamAV antivirus response invalid
MAVP-740 — Antivirus engine does not check document
MAVP-751 — ICAP server responded by unclear response
MAVP-758 — ICAP server responded by unclear response
MAVP-759 — ICAP server responded by unclear response
MCHU-702 — Found error in chunked body from the client or server
MCHU-703 — Found error in chunked body from the client or server
MCHU-704 — Found error in chunked body from the client or server
MCHU-705 — Found error in chunked body from the client or server
MCHU-709 — Preview block too large
MEMM-000 — Memory manager detected a cycle in its internal data structures
MEMM-001 — Re-initialization of memory management is not allowed
MEMM-002 — Reparenting of root resource pool is not allowed
MEMM-003 — Invalid value in memory allocation limits
MEMM-004 — The structure of resource pools must always be a tree
MEMM-005 — Repeated deletion of a cleanup function attempted
MEMM-010 — Root resource pool can never be destroyed
MEMM-011 — Specification of a string to be copied is invalid
MEMM-100 — An allocation error occurred
MEMM-101 — Cannot allocate memory, process will terminate
MEMM-102 — Cannot allocate memory
MEMM-103 — Cannot allocate memory, process will terminate
MEMM-104 — Cannot allocate memory
MEMM-105 — Maximum size of a pool reached, cannot allocate more memory
MEMM-106 — Cannot allocate too large memory block
MEMM-107 — Maximum number of allocated blocks in a pool reached
MEMM-108 — Maximum number of sub-pools of a resource pool reached
MEMM-109 — Cannot allocate memory for a pool structure
MEMM-110 — Cannot register a function to be called at process exit
MEMM-111 — Cannot register a function to be called at process exit
MEMM-112 — Cannot register a cleanup function in a pool, process will terminate
MEMM-113 — Cannot register a cleanup function in a pool
MEMM-114 — Maximum number of registered cleanup handlers reached
MEMM-115 — Cannot allocate memory for a pool structure, process will terminate
MEMM-116 — Cannot create a new resource pool, process will terminate
MEMM-117 — Cannot create a new resource pool
MEMM-120 — Cannot allocate memory on the stack
MEMM-121 — Cannot allocate memory on the stack, process will terminate
MEMM-122 — Cannot register a pair of related cleanup functions in pools
MEMM-125 — A resource pool cannot get assigned name
MENC-751 — Invalid MIME header encoding encountered
MENC-752 — Invalid MIME header encoding encountered
MENC-753 — Invalid MIME header encoding encountered
MENC-791 — Incorrect BASE64 encoding encoutered
MGZI-100 — Gzip (de)compression cannot be initialized
MGZI-101 — Gzip (de)compression failed
MGZI-102 — An error occurred in the zlib data compression library
MGZI-103 — An unexpected end of file occurred while reading compressed data
MIME-101 — Proxy cannot use the library for guessing MIME types
MIME-103 — Proxy cannot use the library for guessing MIME types
MIME-104 — It is not known if compiled database is up to date
MIME-105 — The magic database cannot be compiled
MIME-106 — The magic database cannot be compiled
MIME-150 — The proxy is unable to open the file with definitions of MIME types
MIME-151 — Data structure for suffix->MIME type mapping cannot be initialized
MIME-152 — The proxy is unable to read the file with definitions of MIME types
MIME-153 — The proxy is unable to close the file with definitions of MIME types
MIME-154 — An error occurred when storing a value to DB database
MIME-160 — Error when looking MIME type in database
MIME-501 — Configuration specifies more than 3 doctype identification methods
MIME-502 — Magic database cannot be compiled
MIME-550 — There is very long line in the file defining MIME types
MIME-551 — A file extension occurs twice in the file defining MIME types
MIME-700 — The magic database will be recompiled by the proxy
MIME-701 — The magic database will not be recompiled by the proxy
MIMX-503 — Configuration specifies incorrect doctype identification method
MMAT-100 — The proxy cannot save values from a HTML form
MMAT-101 — The proxy cannot close a database with HTML form values
MMAT-102 — The proxy cannot open a database used for replacing HTML form values
MMAT-103 — The proxy cannot open a database of values searched for in HTML forms
MMAT-800 — The proxy denied further communication because of forbidden data
MMAT-801 — The proxy cannot store values from a HTML form for later searching
MMAT-802 — The proxy cannot look up received HTML form data in a database
MMAT-803 — Forbidden data found in a HTML form
MMAT-804 — The proxy cannot look up received HTML form data in a database
MMAT-805 — The proxy cannot look up received HTML form data in a database
MMAT-806 — The proxy denied further communication because of missing required data
MMCC-105 — ALTQ queue assigment has failed
MMCC-131 — Connection to server failed
MMCC-181 — H.245 control connection accept failed
MMCC-231 — Target server cannot be connected within timeout period
MMCC-232 — Target server connection failed
MMCC-281 — Cannot create listening socket for H.245 session
MMCC-530 — Next-hop server/proxy name cannot be resolved to IP address
MMCC-533 — Address being to be forced as source toward the server cannot be resolved
MMCC-650 — Data connection offer with wrong address
MMCC-700 — H.225/H.245 packet format error
MMCC-710 — H.323 destination missing
MMCC-711 — H.323 destination unknown
MMCC-720 — Q.931 packet format error
MMCC-721 — Unimplemented feature in H.323 protocol
MMCC-730 — Q.931 address unexpected
MMCC-731 — Unknown Q.931 message
MMCC-741 — Unimplemented feature in H.323 protocol
MMCC-742 — Unimplemented feature in H.323 protocol
MMCC-750 — Data connection offer with changed address
MMCC-781 — Peer cancelled H.245 connection before accepting
MMCC-808 — Session initialized, proxy is ready to mediate communication
MMCC-881 — H.245 session announced and ready
MMCD-105 — ALTQ queue assigment has failed
MMCD-110 — H.323 chnannel cannot be created
MMCD-219 — Peer cancelled channel connection before accepting
MMCD-600 — Maximal number of H.323 data channel reached
MMCD-610 — Data connection arrived from bad peer
MMCD-720 — H.323 data channel I/O failed
MMCD-721 — H.323 data channel I/O failed
MMCD-810 — H.323 data channel announced and ready
MMCG-121 — Udp-proxy was not able to find an ACL appropriate to session
MMCG-590 — ANY-address used as listen-on for gk-proxy
MMCG-709 — Final proxy termination message
MMCG-810 — A datagram from a client has arrived, a session has started
MMCG-811 — Session initialized, proxy is ready to mediate communication
MMCG-812 — Session finished
MMCG-821 — ACL decision has been made, operation either accepted or rejected
MMCG-888 — Unified GK proxy statistics message
MMCP-090 — TCP server returned with error
MMCP-099 — Final startup failure message
MMCP-100 — Proxy main loop select call failed
MMCP-104 — Original connection destination getting failed
MMCP-105 — ALTQ queue assigment has failed
MMCP-110 — Searching of ACL failed
MMCP-200 — Proxy main loop timeout reached
MMCP-239 — TPKT socket closed by peer
MMCP-500 — ACL misconfigured
MMCP-700 — Misformed TPKT packet received
MMCP-711 — Cannot determine target due to missing admission
MMCP-801 — Client connection arrives to proxy
MMCP-808 — Session has started, client connection has arrived
MMCP-809 — Session finished
MMCP-810 — ACL decision has been made, operation either accepted or rejected
MMCP-888 — Unified H.232 proxy statistics message
MMCR-700 — Nonrecoverable parser error reading RAS packet
MMCR-701 — Unknown RAS packet received
MMCR-710 — RRQ RAS packet does not contain crucial attributes
MMCR-720 — URQ RAS packet does not contain crucial attributes
MMCR-730 — Unknown client registers known H.323/URL identification
MMCR-800 — RAS packet parsing summary
MMCY-100 — YP map file cannot be opened
MMCY-110 — YP map file has incorrect content
MMCY-111 — RAS YP map file corrupted
MMCY-113 — RAS YP map file corrupted
MMCY-120 — YP map file cannot be extended
MMCY-121 — YP map file seek failed
MMCY-130 — Memory (re)mapping of YP file failed
MMCY-510 — RAS YP map file outdated
MNIO-001 — Invalid network communication mode
MNIO-003 — Unexpected data found in data buffers during certain operations
MNIO-021 — Invalid network communication mode
MNIO-100 — Proxy cannot check for unexpected connection close
MNIO-101 — Proxy cannot check for unexpected connection close
MNIO-102 — Proxy cannot check for unexpected connection close
MNIO-103 — Proxy cannot check for unexpected connection close
MNIO-150 — Cannot connect to server due to resolution error
MNIO-151 — Cannot connect to server due to bad socket name
MNIO-160 — Connection to a remote server timed out
MNIO-170 — Connection to a remote server failed
MNIO-171 — Address of a local network socket cannot be obtained
MNIO-172 — Address of a remote network socket cannot be obtained
MNIO-200 — Data from client contains bare line-feed character
MNIO-201 — Information about source address of the connection to the server
MNIO-202 — Proxy cannot configure source address according to the configuration
MNIO-301 — The proxy has received a line which does not fit into its buffers
MNIO-302 — The proxy has received a line which does not fit into its buffers
MNIO-303 — Timeout while waiting for connection close
MNIO-500 — The address specified in the SOURCE-ADDRESS cannot be used
MNIO-600 — Peer has sent a certificate which does not satisfy proxy's requirements
MNIO-710 — Network connection has been successfully established
MNIO-800 — Some error occurred during receiving data from a network socket
MNIO-802 — Some error occurred during sending data to a network socket
MNIO-803 — Connection to a remote server failed
MNIO-840 — Attempt to shut down one or both directions of a connection failed
MNIO-850 — There is no more addresses the proxy could try to connect to
MNIO-851 — A network socket cannot be created
MNIO-852 — An error occurred in handling the SSL/TLS protocol
MNIO-853 — A system call failed during a SSL/TLS operation
MNIO-870 — The proxy cannot shutdown a SSL/TLS connection properly
MNIO-871 — A TCP connection has been closed without a proper SSL/TLS shutdown
MNIO-872 — No memory rbio to swap with socket rbio
MODM-003 — System call setitimer() unexpectedly failed
MODM-004 — System call getitimer() unexpectedly failed
MODM-005 — An unregistered file descriptor has been selected for I/O
MODM-007 — A deadlock detected in the proxy
MODM-008 — Creating a temporary resource pool outside a module's run() function
MODM-009 — Cannot write data to nonexistent output buffer
MODM-010 — Debugging output of the module manager in case of an internal error
MODM-011 — Non-existent group number assigned to a new module
MODM-012 — Non-existent group number assigned to a new module
MODM-040 — Inconsistent file descriptor and netio structure
MODM-100 — A program cannot be executed
MODM-101 — A process for a program execution cannot be created
MODM-102 — A proxy cannot communicate with an executed program
MODM-156 — Proxy cannot determine transparency of a client connection
MODM-801 — A serious error occurred, the client will be disconnected
MODM-802 — A serious error occurred, the client will be disconnected
MODM-803 — An error occurred, an error message will be sent to the client
MODM-804 — A timeout expired which killed the current client's request
MODM-805 — A process exceeded a maximum allowed runtime
MODM-806 — A process exceeded a maximum allowed runtime
MODM-821 — Initialization of a new request failed
MODM-832 — Initialization of a new proxy module failed
MODM-835 — A per-client module cannot be attached to a request
MODM-838 — A per-client module cannot be detached from a request
MONI-100 — Proxy cannot initialize communication with monitoring utility
MONI-101 — Proxy cannot initialize communication with monitoring utility
MONI-102 — Proxy cannot initialize communication with monitoring utility
MONI-103 — Proxy cannot terminate monitoring properly
MONI-500 — Proxy cannot initialize communication with monitoring utility
MPWF-001 — Unknown content of ICAP response Encapsulated header
MPWF-200 — Proxy cannot communicate with the web filter
MPWF-201 — Proxy cannot communicate with the web filter
MPWF-202 — A web filtration request does not fit to a buffer
MPWF-203 — The proxy is unable to return the web filter response
MPWF-700 — The web filter has rejected the request
MPWF-800 — The web filter terminated its response unexpectedly
MPWF-801 — A web filter response does not fit to a buffer
MPWF-802 — A web filter response cannot be processed
MPWF-810 — Request failed due to inoperative web filter
MPWF-811 — Request continues despite web filter failure
MRDF-000 — Trying to subtitute a nonexisting string in a file
MRDF-003 — Unexpected data found in data buffers during certain operations
MRDF-100 — A file cannot be opened for reading
MRDF-101 — A file size cannot be obtained
MRDF-102 — A file cannot be mapped to memory
MRDF-103 — A file cannot be read to memory
MRDF-300 — Line longer than internal buffer size
MRDF-800 — Trying to subtitute a nonexisting string in a file
MRDF-801 — Files in a directory cannot be read for later use
MRDF-802 — A file cannot be read for later use
MSPA-105 — ALTQ queue assigment has failed
MSPA-310 — Antispam report truncated
MSPA-709 — Antispam failed, spam score invalid
MSPA-710 — Spam checker has returned unknown response
MSPA-800 — Information about mail size and antispam score
MSPA-810 — Report of partial spam scores by categories
MWRF-100 — The proxy cannot open a local file
NATT-002 — It is not possible to issue bind() syscall to desired address
NETL-002 — Function netopen() attempts to change netio socket type
NETL-003 — Internal buffer pointers are inconsistent
NETL-010 — Improper call to netctl() function
NETL-011 — Scratch of too many bytes requested
NETL-012 — Function ungetc() called to empty buffer
NETL-032 — Improper call of netgetcmd() function
NETL-033 — Network Virtual Terminal processing error
NETL-060 — Inconsistent options given to write operation
NETL-087 — Attempt to reconnect UDP socket
NETL-088 — Attempt to send data to not connected UDP socket
NETL-089 — Send to invalid address requested
NETL-101 — Shutdown operation with socket failed
NETL-202 — Setting socket flags by fcntl() or setsockopt() failed
NETL-203 — Preparing socket for TCP reset by setsockopt() failed
NETL-204 — Cannot obtain the value of the IP packet TOS field
NETL-205 — Cannot set the value of the IP packet TOS field
NETL-210 — General message of NAT operation failure
NETL-211 — Binding of socket to printed address failed
NETL-212 — Syscall getsockname() failed
NETL-220 — The proxy sends TCP reset instead of normal TCP connection close
NETL-231 — Socket read failed
NETL-262 — Writing data to socket failed
NETL-267 — Non-blocking write ended by some data unsent
NETL-283 — UDP data not sent
NETL-291 — Timeout reached during netio operation
NETL-331 — Too large UDP datagram received
NETL-390 — Netio function failed due to buffer shortage
NETL-391 — Netio function failed due to buffer shortage
NETS-001 — Select handler size is negative
NETS-010 — Adding too high socket number
NETS-011 — Unregistered socket used to select
NETS-012 — Unopened socket used to select
NETS-039 — Network I/O select routine failed
NETS-101 — Too many file descriptors are requested
NETS-228 — Timeout reached during select() syscall
NETS-700 — Select handler manipulation function already called
NTIF-001 — Network interface has no link address
NTIF-004 — Network interface name not found
NTIF-007 — Socket address information for netmask is not valid
NTIF-101 — Kernel routing information is not available
NTIF-102 — No memory available for kernel routing information
NTIF-103 — No memory available for network interface information
NTIF-901 — Function has started its operation
NTIF-902 — Function has finished its operation
NTLM-200 — The proxy cannot communicate with the NTLM helper program
NTLM-201 — The proxy cannot communicate with the NTLM helper program
NTLM-500 — NTLM-related communication with an AD controller should be limited
NTLM-501 — NTLM-related communication should be limited by INTERFACE or NETWORK
NTLM-800 — Client provided unexpected authentication information
NTLM-801 — The proxy cannot communicate with the NTLM helper program
NTLM-802 — An error has occured in the NTLM authentication module
NTLM-803 — The NTLM helper program have not replied in time
NTLM-804 — The NTLM helper program have returned an unexpected response
NTLM-805 — The NTLM helper program have returned an unexpected response
NTLM-806 — The NTLM helper program have returned an unexpected response
NTLM-807 — NTLM authentication failed
NTLM-808 — NTLM authentication cannot obtain group information from LDAP
NTLM-809 — The NTLM helper program have returned a too long response
NTPC-099 — Final startup failure message
NTPC-711 — Host name in NTP configuration failed to resolve
NTPC-718 — No NTP server IP address available
NTPC-719 — Final NTP regeneration success message
OOBA-001 — No OOBA handle exists for a given set of configuration parameters
OOBA-100 — The OOB authentication server cannot communicate with proxies
OOBA-101 — The OOB authentication server cannot communicate with proxies
OOBA-102 — The OOB authentication server cannot communicate with proxies
OOBA-103 — The OOB authentication server cannot communicate with proxies
OOBA-104 — The OOB authentication server cannot communicate with proxies
OOBA-105 — Proxy cannot terminate using a session table file properly
OOBA-106 — Proxy cannot terminate using a session table file properly
OOBA-107 — The proxy cannot communicate with the authentication server
OOBA-108 — Contents of the OOB authentication session table is not valid
OOBA-109 — The OOB authentication server cannot release its session table
OOBA-590 — OOB authentication server name misconfigured
OOBA-800 — Limit for number of OOB authenticated users has been reached
OOBA-801 — A user name does not fit into the OOBA session table entry
OOBA-802 — List of groups does not fit into the OOBA session table entry
OOBA-803 — List of groups does not fit into the OOBA session table entry
OSSL-000 — The proxy tried to initialize OpenSSL twice
OSSL-100 — An SSL context cannot be created
OSSL-101 — Cipher list for an SSL context cannot be set
OSSL-102 — The proxy cannot initialize OpenSSL error logging
OSSL-103 — Contents of the SSL error queue
OSSL-104 — The proxy cannot load a certificate for SSL/TLS
OSSL-105 — The proxy cannot load its private key
OSSL-106 — The proxy cannot load a certificate revocation list
OSSL-107 — The proxy cannot load a certificate revocation list
OSSL-108 — The proxy cannot load a certificate revocation list
OSSL-109 — Parameters for ephemeral DH key exchange cannot be created
OSSL-110 — Parameters for ephemeral DH key exchange cannot be created
OSSL-111 — A structure representing a new SSL/TLS connection cannot be created
OSSL-112 — The OpenSSL library cannot attach to a TCP connection
OSSL-113 — A SSL/TLS operation failed due to an OS-level I/O error
OSSL-114 — An SSL/TLS operation due to an error at the OpenSSL library level
OSSL-115 — The underlaying TCP connection has been unexpectedly closed
OSSL-116 — A system call has failed during an SSL/TLS operation
OSSL-117 — The proxy cannot load certificates of trusted certification authorities
OSSL-118 — The proxy will not use a certificate revocation list
OSSL-119 — Assigning security attributes to new SSL connection failed
OSSL-121 — The session id context cannot be set for an SSL context
OSSL-122 — Security attributes for SSL connection cannot be reset
OSSL-123 — Parent CA certificate adding failed
OSSL-124 — The OpenSSL library cannot create a memory buffer containing ClientHello request
OSSL-125 — The OpenSSL library cannot create a memory buffer containing ClientHello request
OSSL-130 — The SSL session cache cannot be initialized
OSSL-131 — The SSL session cache cannot be initialized
OSSL-134 — The SSL session cache cannot be initialized
OSSL-156 — The process cannot access the SSL/TLS session cache
OSSL-157 — The SSL/TLS session cache cannot be unlocked
OSSL-158 — An SSL/TLS session obtained from the session cache is unusable
OSSL-159 — An SSL/TLS session obtained from the session cache is unusable
OSSL-160 — The process cannot access the SSL/TLS session cache
OSSL-161 — The process cannot access a cached SSL/TLS session
OSSL-162 — The process cannot access the SSL/TLS session cache
OSSL-170 — Faked server private key load failed
OSSL-171 — Faking CA private key load failed
OSSL-172 — Faking CA certificate load failed
OSSL-173 — Faked certificate cannot be stored
OSSL-178 — Cached certificate for HTTPS inspection is unreadable
OSSL-179 — Faked certificate cannot be stored
OSSL-180 — Configuration file for FAKE-CERT section not found
OSSL-181 — Faked certificates configuration not accessible
OSSL-182 — Faked certificates cache hash tag file is not accessible
OSSL-183 — Faked certificates cache cannot be cleaned
OSSL-190 — PEM file with certificates cannot be open
OSSL-191 — PEM file with certificates cannot be read
OSSL-192 — The fingerprint computatin has failed for the certificate
OSSL-193 — The fingerprint computation has failed for the certificate
OSSL-510 — Server SSL parameters do not requires certificate verification
OSSL-511 — Configuration allows deprecated SSL protocols
OSSL-512 — Distrusted certificates list has been loaded
OSSL-513 — The peer certificate is listed in the distrusted list
OSSL-514 — The certificate chain of the peer is listed in the distrusted list
OSSL-515 — The distrusted certificate list failed to be loaded from the PEM file
OSSL-516 — If the AUTH-CERT item is KERNUN-DIST, the DISTRUSTED-CERTS should be used
OSSL-600 — The peer has not presented a certificate during SSL/TLS handshake
OSSL-601 — Peer's certificate could not be verified
OSSL-602 — Information about a valid peer certificate
OSSL-607 — Openssl syscall for creating the EC_KEY object using a named curve failed
OSSL-737 — SSL_accept was expected to fail but did not
OSSL-738 — SSL_accept failed with different error than expected
OSSL-739 — SSL_accept failed with different error than expected
OSSL-740 — SSL_accept failed with more errors than expected
OSSL-775 — Some X.509 extension from server certificate is unknown
OSSL-776 — Some X.509 extension from server certificate is unknown
OSSL-780 — Health report of FAKE-CERT cache directory
OVPN-001 — Openvpn failed to start the client connect script
OVPN-098 — Final startup failure message
OVPN-099 — Final startup failure message
OVPN-101 — Failed to exec the openvpn daemon
OVPN-102 — Error during accepting a connection on a socket
OVPN-103 — Failed to open the socket for reading
OVPN-104 — Failed to read line from the management socket
OVPN-105 — Connection from client has been closed before accepted
OVPN-107 — Openvpn configuration provider failed to create the server socket
OVPN-108 — Failed to bind the unix-domain socket
OVPN-109 — Failed to listen on the server socket
OVPN-111 — Failed to create the client socket
OVPN-112 — Cannot establish a connection to the openvpn management socket
OVPN-113 — The parent process tried to signal its children and received an error
OVPN-114 — An error occured during waiting for a child process
OVPN-115 — Failed to unlink the socket file
OVPN-116 — Openvpn failed to execute the client-connect script
OVPN-118 — Openvpn daemon failed to create the socket-root directory
OVPN-119 — Openvpn daemon was unable to unlink invalid sessions-db file
OVPN-301 — Openvpn configuration provider failed to read the row
OVPN-302 — Openvpn policy enforcement failed to read the row
OVPN-405 — Client is connected without permission, it will be disconnected now
OVPN-406 — Openvpn policy enforcement client disconnection report
OVPN-408 — Failed to load the client connect script
OVPN-410 — Client is disabled now
OVPN-412 — Openvpn daemon was unable to create the sessions-db file
OVPN-413 — Unexpected error occured while opening the sessions-db file
OVPN-501 — Failed to reread the configuration
OVPN-502 — Openvpn section must reference an interface of the correct type
OVPN-503 — Ifconfig-pool address must respect the interface range
OVPN-504 — Ifconfig-push address must respect the interface range
OVPN-505 — Address pushing in OPENVPN must respect the INTERFACE type
OVPN-506 — OPEVNPN pushing address collision
OVPN-507 — Interface not specified for openvpn
OVPN-508 — Invalid interface type referenced in the openvpn section
OVPN-510 — Ifconfig-pool collides with the ifconfig-push address
OVPN-511 — OPENVPN pushing address must not collid with the INTERFACE address
OVPN-512 — Ifconfig-ipv6-pool address must respect the interface IPv6 network range
OVPN-513 — Ifconfig-ipv6-push address must respect the interface IPv6 range
OVPN-514 — Items PROTO, LOCAL and REMOTE must respect each other's address family
OVPN-515 — Ifconfig-ipv6-pool collides with the ifconfig-ipv6-push address
OVPN-516 — Openvpn daemon failed to execute the configured client-connect script
OVPN-701 — Unknown command to the openvpn config provider
OVPN-702 — Failed to serve the client
OVPN-703 — Failed to connect to the openvpn manage socket
OVPN-705 — Failed to disconnect the client
OVPN-706 — Failed to list the connected clients
OVPN-707 — Openvpn management command failed
OVPN-709 — Reading the contents of file was unsuccessful
OVPN-712 — Failed to obtain the status from the openvpn
OVPN-713 — Openvpn daemon failed to connect to the configured client-connect socket
OVPN-715 — Openvpn sessions database was created succesfully
OVPN-801 — Openvpn config provider failed to serve the client
OVPN-802 — Openvpn parent process failed to create a child process
OVPN-806 — Too many openvpn terminated child processes
OVPN-807 — Openvpn parent process detected the reload request
OVPN-824 — Openvpn daemon was unable to initialize the SQLite library
OVPN-825 — A database error occured while accessing sessions-db
OVPN-826 — Openvpn daemon failed to insert new record into the sessions-db
OVPN-827 — Openvpn daemon failed to update a record in the sessions-db
OVPN-828 — Openvpn daemon tried to update a record in the sessions-db but the query had no effect
OVPN-829 — Unexpected SQL error occured while searching in sessions-db
OVPN-830 — Openvpn daemon failed to reset prepared SQL statements
OVPN-831 — Openvpn daemon failed to finalize prepared SQL statements
OVPN-832 — Openvpn daemon failed to close SQlite database connection
OVPN-833 — Openvpn daemon was unable to update sessions-db due to failed management socket connection
OVPN-834 — Openvpn daemon ignored invalid record in current connections table
OVPN-835 — Openvpn daemon encountered an old version of the sessions-db database
OVPN-836 — Openvpn daemon ignored invalid record in current connections table
OVPN-838 — Openvpn daemon encountered an unexpected error
OVPN-839 — Openvpn monitoring daemon detected an ongoing VPN connection of unknown origin
PFCD-109 — Syscall select() in main loop failed
PFCD-110 — Call of pfctl command failed
PFCD-120 — Reloading of some PF tables failed
PFCD-700 — Notification about the mode of operation of the pf-control
PFCD-701 — PF contorl daemon has been initialized and is ready to work
PFCD-708 — PF control daemon has finished
PFCD-709 — Final daemon termination message
PFCD-710 — Cannot determine current PF status
PFCD-720 — PF control daemon failed to load new PF tables
PFCD-728 — PF table change report
PFCD-729 — Packet filter table reload error
PFCD-820 — PF tables refresh report
PFLG-120 — Input printcap device initialisation failed
PFLG-121 — Input printcap device initialisation failed
PFLG-123 — Input printcap device initialisation failed
PFLG-129 — Input printcap device initialisation failed
PFLG-320 — PF logger data misunderstanding
PFLG-715 — PF control daemon timeout misconfiguration
PFLG-719 — Packet filter information line misunderstood
PFLG-751 — Incorrect data captured from the PF
PFLG-765 — PF controling daemon failed to read pfsync message
PFLG-768 — Inconsistent time data from PF
PFLG-769 — Inconsistent time data from PF
PFLG-810 — PF rule map record report
PFLG-850 — PF rule event log message
PFLG-860 — PF state end log message
PFLG-870 — Statistic message of non-blocking stateless PF rules
PFLG-888 — Unified packet filter statistics message
PIKE-100 — PIKE monitoring component cannot recognize cluster status
PIKE-109 — Syscall select() in main pikemon loop failed
PIKE-110 — Pikemon state change command failed
PIKE-118 — Cannot prioritize pikemon daemon
PIKE-120 — Pikemon status file corrupted or inaccessible
PIKE-121 — Pikemon restart failed
PIKE-501 — Single heart-beat listening socket must be specified
PIKE-510 — All virtual clusters must have unique ID
PIKE-511 — Interface devices used for PIKE are incorrect
PIKE-512 — Interface devices used for PIKE are incorrect
PIKE-513 — Interface devices used for PIKE are incorrect
PIKE-518 — PIKE timeouts inconsistency
PIKE-519 — PIKE virtual cluster configuration is not complete
PIKE-580 — PIKEMON command syntax error
PIKE-581 — Invalid VCID in PIKEMON command
PIKE-652 — HMAC verifiaction failed
PIKE-700 — Notification about the mode of operation of pikemon
PIKE-707 — The pikemon has finished
PIKE-709 — Final daemon termination message
PIKE-710 — Daemon runtime monitoring support cannot be initialized
PIKE-720 — Pikemon status file parsing result
PIKE-730 — PIKE monitor received packet of unsupported protocol version
PIKE-731 — PIKE peer uses incompatible set of virtual clusters
PIKE-740 — PIKE protocol state change message
PIKE-741 — Network recovery triggered by partner status change has started
PIKE-750 — PIKE monitor received packet of other than current protocol version
PIKE-751 — PIKE peer uses incompatible set of virtual clusters
PIKE-763 — SWAP message of PIKE protocol received
PIKE-780 — PIKEMON command execution message
PIKE-781 — SWAP command result informational message
PIKE-820 — Brief cluster health status information
PIKE-821 — Firewall drops master role for virtual cluster
PIKE-822 — Firewall takes master role for virtual cluster
PING-255 — ICMP ECHO sent incompletely
PING-710 — PIKE ping group state change message
PING-711 — Monitoring of a group of target host by ping has ended
PING-755 — ICMP ECHO sending failed
POP3-100 — The main loop for serving clients (tcpserver) failed
POP3-101 — ALTQ queue assigment has failed
POP3-200 — Cannot change source address of a connection to a server
POP3-201 — The proxy cannot initialize a connection to a server
POP3-202 — The proxy cannot initialize a connection to a server
POP3-700 — Session ACL has been processed
POP3-701 — Command ACL has been processed
POP3-702 — A client has been disconnected from the proxy
POP3-704 — A new client has connected to the proxy
POP3-710 — A command has been denied by ACL
POP3-711 — A capability has been denied by ACL
POP3-712 — An unimplemented capability received from the server
POP3-800 — Proxy initialization failed
POP3-801 — An error occurred during searching SESSION-ACLs
POP3-802 — The client has been denied by SESSION-ACL
POP3-803 — The proxy is unable to verify user authentication
POP3-804 — The proxy does not know a server address to connect
POP3-805 — Initial processing of a new client connection has failed
POP3-806 — Proxy cannot start SSL/TLS on the client connection
POP3-807 — Proxy cannot start POP3 protocol
POP3-808 — An error occurred during searching COMMAND-ACLs
POP3-809 — The client has been denied by COMMAND-ACL
POP3-810 — Limit for session duration has been reached
POP3-811 — The client is sending too much data
POP3-812 — The server is sending too much data
POP3-813 — Proxy cannot start SSL/TLS on the server connection
POP3-814 — The session is being idle for too long
POP3-815 — Proxy cannot create module for sending a processed mail to the client
POP3-820 — The client has unexpectedly disconnected from the proxy
POP3-821 — The server has unexpectedly disconnected from the proxy
POP3-823 — A client command line is too long
POP3-824 — A capability line is longer than the configured limit
POP3-825 — A server response line is too long
POP3-826 — An authentication challenge line is too long
POP3-827 — An authentication answer line is too long
POP3-829 — A command line is longer than the configured limit
POP3-830 — A line with capability is too long
POP3-831 — The command from the client is bad
POP3-832 — A response line is longer than the configured limit
POP3-833 — The response from the server is bad
POP3-835 — A mail line is longer than the configured limit
POP3-836 — The command from the client is bad
POP3-837 — A mail being retrieved from the server is too big
POP3-838 — A mail line is longer than the configured limit
POP3-840 — A mail message contains too long line
POP3-841 — The proxy does not understand a server response
POP3-850 — Proxy cannot store a mail for processing
POP3-851 — A mail cannot be processed
POP3-852 — A mail has been rejected by DOC-ACL
POP3-853 — A mail has been rejected by MAIL-ACL
POP3-860 — Information about selected MAIL-ACL
POP3-861 — Proxy cannot create module for processing a mail
POP3-888 — Unified POP3 proxy statistics message
PRXY-132 — Switching list of groups from root to another user failed
PRXY-133 — Switching real and effective GID from root to another user failed
PRXY-134 — Switching real and effective UID from root to another user failed
PRXY-135 — Setting login class for the proxy user failed
PRXY-139 — Proxy cannot change its root directory
PRXY-500 — Application configuration missing
PRXY-501 — Application configuration is not unique
PRXY-521 — No USE-RESOLVER used
PRXY-523 — Resolver configuration reduced
PRXY-530 — Invalid run-time user specified
PRXY-531 — Application cannot change its root directory if not started by root
PRXY-533 — Application cannot be switched to unknown user
PRXY-541 — Working directory specification invalid
PRXY-549 — Application cannot create working directory
PRXY-734 — The proxy was switched from root to some other user
PRXY-739 — Proxy changed its root directory
RCSL-100 — Insufficient permissions to configuration file
RCSL-110 — Unrecognised rcsdiff output
RCSL-120 — Creation of revision control file for configuration file failed
RCSL-139 — Current user name unknown
RCSL-700 — Some of configuration files does not exist
RCSL-710 — Text and RCS versions of configuration mismatch
RCSL-718 — Configuration file locking failed
RCSL-719 — Configuration file inconsistency warning
RCSL-720 — Configuration file with chosen name exists
RCSL-730 — Configuration file successfully locked
RCSL-738 — Configuration file lock status incorrect
RCSL-739 — Configuration file lock status incorrect
RDST-201 — Client has closed connection too early
RDST-901 — Function realdest() has started its operation
RDST-902 — Function realdest() has finished its operation
RGAI-330 — DNS response contains too many RRs
RGAI-331 — DNS response contains too many texts in RR
RGAI-730 — DNS answer contains irrelevant data
RGAI-731 — DNS response contains too long text
RGAI-735 — DNS response contains incorrect CNAME chain
RGAI-739 — No records in ANSWER section of DNS response were accepted
RGHD-330 — DNS response contains too many RRs
RGHD-730 — DNS answer contains irrelevant data
RGHD-735 — DNS response contains incorrect CNAME chain
RGHD-739 — No records in ANSWER section of DNS response were accepted
RSLC-761 — Nameserver response contains invalid name
RSLV-180 — Resolver mapping file unaccessible
RSLV-213 — DNS resolution failed
RSLV-589 — Resolver pool directory misconfigured
RSLV-713 — ACR successfully resolved domain name in configuration
RSLV-741 — Query section of the answer does not match one of request
RSLV-770 — Hostnames used in configuration was resolved
RSLV-795 — Proxy reloaded results of ACR name resolution
SDPB-710 — SDP line misformed
SDPB-720 — SDP line misformed
SDPB-721 — SDP version unrecognized
SDPB-740 — SDP line misformed
SDPC-120 — Data port assignment failure
SDPC-219 — Data channel unexpectedly closed
SDPC-230 — Invalid data channel
SDPC-310 — Data channel table exhausted
SDPC-350 — Oversized media data block
SDPC-800 — SIP data channel closed
SIPB-710 — SIP method recognition message
SIPB-719 — SIP line misformed
SIPB-750 — SIP line misformed
SIPB-751 — SIP line misformed
SIPB-760 — SIP line misformed
SIPB-781 — SIP line misformed
SIPB-789 — SIP line misformed
SIPC-130 — Control socket creation failed
SIPC-180 — Routing table search failed
SIPC-231 — Control socket acceptation failed
SIPC-232 — Control connection attempt unsuccessful
SIPC-240 — Control connection I/O error
SIPC-242 — Control connection I/O error
SIPC-249 — Client control connection closed
SIPC-250 — Control connection I/O error
SIPC-259 — Control connection unexpectedly closed
SIPC-310 — Control channel table exhausted
SIPC-330 — Control channel table exhausted
SIPC-340 — Control message line too long
SIPC-341 — Control message unrecognized
SIPC-588 — Listening socket missing for outgoing direction
SIPC-830 — Control channel establishing message
SIPM-310 — SIP message table exhausted
SIPM-380 — Control message too long
SIPM-751 — SIP over TCP message header invalid
SIPM-752 — SIP over UDP message header invalid
SIPM-753 — Unsupported document body in SIP message
SIPM-759 — SIP message misformed
SIPP-119 — Syscall select() in main proxy loop failed
SIPP-351 — Insufficient socket table size
SIPP-700 — Notification about the mode of operation of the proxy
SIPP-701 — The proxy has been initialized and is ready to accept packets
SIPP-708 — The proxy has unbound the sockets used for listening for clients
SIPP-709 — Final proxy termination message
SIPP-710 — Proxy runtime monitoring support cannot be initialized
SIPP-723 — The proxy has finished
SIPP-888 — Unified SIP proxy statistics message
SIPR-310 — Requests table is exhausted
SIPR-719 — Incomplete request removed
SIPR-729 — Request was not finished in time
SIPR-739 — Proxy rejects request
SIPR-740 — Client registration not accepted
SIPR-741 — Client registration not accepted
SIPR-742 — Client registration not accepted
SIPR-745 — Call transfer requested by user
SIPR-751 — Misplaced ACK/CANCEL request
SIPR-759 — Misplaced ACK/CANCEL request
SIPR-760 — Response message not accepted
SIPR-761 — Request matching response not found
SIPR-762 — Misordered response to request received
SIPR-769 — Cannot match response to request
SIPR-800 — Response to request arrived and forwarded
SIPS-130 — Routing table search failed
SIPS-310 — Session table exhausted
SIPS-311 — Session table exhausted
SIPS-530 — Listening socket missing for server session transaction
SIPS-531 — SIP misconfigured due to bad resolution
SIPS-710 — Received request that cannot establish session
SIPS-730 — Next-hop for request cannot be determined
SIPS-760 — Configured IDLE-TIMEOUT expired
SIPS-800 — Session has started, unmatched request arrived
SIPS-801 — Session initialized, proxy is ready to mediate communication
SIPS-809 — Session finished
SIPS-821 — SESSION-ACL search report
SIPS-822 — REQUEST-ACL search report
SIPY-110 — SIP YP map file unaccessible
SIPY-111 — SIP YP map file corrupted
SIPY-119 — SIP YP map is corrupted
SIPY-120 — SIP YP map file cannot be extended
SIPY-121 — SIP YP map file seek failed
SIPY-130 — Memory (re)mapping of SIP YP file failed
SIPY-510 — SIP YP map format is older than proxy version
SIPY-750 — SIP YP map record inconsistency
SLOG-009 — Application has improperly started
SLOG-011 — Improper combination of arguments to opentnslog() function
SLOG-020 — Logging function called with unknown severity code
SLOG-100 — Backup log file cannot be opened
SLOG-104 — Syslog socket opening failure
SLOG-110 — Forwarding log to file failed
SLOG-120 — A process cannot terminate its logging to memory correctly
SLOG-121 — A file with memory log of a process cannot be deleted
SLOG-122 — The process cannot perform logging into memory
SLOG-123 — The process cannot perform logging into memory
SLOG-124 — Memory logging file cannot be renamed
SLOG-500 — The process cannot perform logging into memory
SLOG-501 — The process cannot perform logging into memory
SLOG-700 — Application initial log message
SLOG-701 — Process initial log message
SLOG-702 — Change of program identification in log
SLOG-703 — PID suffix will be used
SLOG-704 — Communication to syslog daemon successfully reopened
SLOG-709 — Application introduction message after log reopening
SLOG-710 — Log destination changed to file
SLOG-711 — Log destination changed to standard error
SLOG-712 — Log destination changed to syslog daemon
SLOG-713 — Re-introduction log message
SLOG-714 — A memory log file has been successfully initialized for a process
SLOG-720 — Logging level changed to a new value
SMTB-350 — Header too long
SMTB-750 — Header contains invalid character
SMTB-751 — Header contains invalid quoted character
SMTB-752 — Header contains unpaired parenthesis
SMTB-753 — Header contains incorrect quotting
SMTB-754 — Duplicite CR found in end-of-line sequence
SMTB-760 — No semicolon found between header arguments
SMTB-761 — Unquoted character occurred in header
SMTB-762 — Illegal character used in structured header
SMTB-780 — MIME header syntax error
SMTB-781 — Incomplete value in MIME header
SMTB-789 — Mail or MIME header RFC violation
SMTC-541 — Header modification too long
SMTC-542 — Incorrect character found in header modification configuration
SMTC-560 — Mailbox address incorrect
SMTC-561 — Mailbox address incorrect
SMTC-562 — Mailbox address incorrect
SMTC-563 — Mailbox address incorrect
SMTC-564 — Mailbox address incorrect
SMTC-565 — Mailbox address incorrect
SMTC-569 — SMTP forwarders misconfiguration
SMTD-100 — Searching of ACL failed
SMTD-180 — MIME structure subdocument is not readable
SMTD-310 — Cannot read mail body line
SMTD-311 — Too long mail header line found
SMTD-312 — Too long mail header line handling report
SMTD-313 — Too long mail header line cannot be wrapped
SMTD-320 — Message MIME structure is too large
SMTD-340 — Mail will not be sent as-is, it must be re-assembled from parts
SMTD-360 — Cannot write mail body line
SMTD-370 — Mail antispam check skipped due to mail size
SMTD-530 — Incorrect MIME format in configuration
SMTD-531 — Incorrect header modification defined in configuration
SMTD-700 — Possible forwarding loop
SMTD-720 — Incorrect MIME specification
SMTD-721 — Incorrect multipart MIME boundary definition
SMTD-722 — Invalid Content-Transfer-Encoding
SMTD-726 — Mail text does not contain any boundary line
SMTD-727 — Boundary regeneration failed
SMTD-728 — Header and body not separated
SMTD-729 — MIME structure corrupted
SMTD-739 — Final message reporting mail/MIME header error
SMTD-742 — Incorrect character found in mail body
SMTD-790 — Non US-ASCII mail not correctly declared
SMTD-803 — DOC-ACL search report
SMTI-502 — SMTP forwarder contains too many servers
SMTI-520 — Incorrect black-list configuration
SMTI-552 — Antivirus configuration inconsistency
SMTI-553 — QUARANTINE configuration must be specified
SMTI-554 — SMTP proxy QUARANTINE configuration inconsistent
SMTI-555 — GREY-LISTING configuration must be specified
SMTI-556 — SPF in DELIVERY-ACL requires using of WHITE-LISTING in SESSION-ACL
SMTN-760 — Found ESMTP DSN extension parameter with invalid syntax
SMTN-761 — Found ESMTP DSN extension parameter with invalid syntax
SMTP-090 — TCP server returned with error
SMTP-099 — Final startup failure message
SMTP-104 — The proxy cannot use SSL/TLS
SMTP-239 — Control socket closed by peer
SMTP-738 — I/O operation on socket failed
SMTP-801 — Session has started, client connection has arrived
SMTP-809 — Session finished
SMTP-888 — Unified SMTP proxy statistics message
SMTR-101 — Searching of ACL failed
SMTR-105 — ALTQ queue assigment has failed
SMTR-109 — Session initialization failed
SMTR-169 — Mail storing failed
SMTR-180 — Quarantine storing failed
SMTR-181 — Quarantine storing failed
SMTR-202 — The proxy cannot establish an SSL/TLS secure channel from the client
SMTR-300 — The proxy has received line longer than protocol defined maximum
SMTR-310 — Mail size reached configuration limit
SMTR-330 — Mail too big
SMTR-500 — Mail cannot be sent due to unknown forwarder
SMTR-510 — Cannot force source address in SESSION-ACL
SMTR-540 — Configuration does not cover fatal error
SMTR-601 — Unknown client - access denied
SMTR-602 — Unknown client - access denied
SMTR-603 — Client found in black list
SMTR-609 — Client sent too many bad commands
SMTR-640 — Client sent too many RCPT commands
SMTR-641 — Client sent too many bad RCPT commands
SMTR-700 — SMTP command processing report
SMTR-701 — Unknown command sent by client
SMTR-702 — Incorrect character in SMTP command
SMTR-703 — Client has not closed session
SMTR-709 — Session idle timeout reached
SMTR-710 — SMTP command syntax error
SMTR-712 — SMTP command parameter syntax error
SMTR-719 — SMTP command arguments not valid
SMTR-730 — MAIL BODY parameter value not valid
SMTR-740 — Recipient change report
SMTR-741 — Found unknown ESMTP DSN extension parameter value
SMTR-742 — Found incorrect ESMTP DSN extension parameter value
SMTR-749 — SMTP command argument parsing error
SMTR-750 — No valid recipient remained
SMTR-760 — The proxy has received line with unencoded leading dot
SMTR-769 — EOF encountered during mail reception
SMTR-801 — SESSION-ACL search report
SMTR-802 — DELIVERY-ACL search report
SMTR-803 — MAIL-ACL search report
SMTR-810 — Client ESMTP DSN extension parameters report message
SMTR-811 — Opening mail report message
SMTR-819 — Final mail report message
SMTS-105 — ALTQ queue assigment has failed
SMTS-202 — The proxy cannot establish an SSL/TLS secure channel to the server
SMTS-208 — Forwarder closed connection not using the x21 message
SMTS-209 — Forwarder has sent x21 message
SMTS-300 — Forwarder sent too long line
SMTS-500 — Trivial configuration loop danger
SMTS-600 — Forwarding channel does not satisfy proxy SSL requirements
SMTS-700 — Forwarder sent unexpected response
SMTS-708 — Mail forwarding failed
SMTS-709 — Session idle timeout reached
SMTS-711 — Forwarder sent incorrect response
SMTS-720 — Forwarder sent unknown response
SMTS-729 — Negative response got from forwarder
SMTS-730 — Forwarder uses incorrect ESMTP option
SMTS-739 — Forwarder rejects connection from proxy
SMTS-740 — Recipient accepted/refused by forwarder
SMTS-741 — Incorrect mail for 7bit forwarders
SMTS-750 — Forwarder rejects mail body
SMTS-815 — Sending mail report message
SMTT-099 — Final startup failure message
SMTT-120 — Triplet database not accessible
SMTT-130 — Final message from triplet database purging
SMTT-500 — Triplicator called for configuration w/o grey-listing
SMTT-730 — Final message from triplet database purging
SMTT-740 — Triplet database modification failed
SMTT-741 — Triplet database modification incorrect - bad state
SMTT-742 — Triplet database modification incorrect - bad date/time
SMTT-743 — Triplet database modification incorrect - invalid IP address
SMTT-744 — Triplet database modification incorrect - bad sender/recipient address
SMTT-748 — Adding of redundant item to triplet database
SMTT-749 — Triplet database modification incorrect
SMTT-810 — Triplet information display
SMTT-820 — Triplet database statistical information
SMTT-830 — Final report message from triplet database cleanup
SMTT-831 — Final report message from triplet database backup
SMTT-832 — Final report message from triplet database restoring
SMTV-139 — Greylisting switched off due to database error
SMTV-371 — Checked domain SPF definition incorrect
SMTV-388 — Domain name stripped suring SPF verification
SMTV-389 — Checked domain SPF definition incorrect
SMTV-540 — Grey-listing database filename too long
SMTV-712 — SPF processing truncated
SMTV-751 — No SPF definition for domain verified
SMTV-752 — Checked domain SPF definition incorrect
SMTV-758 — SPF processing truncated
SMTV-759 — Final SPF processing message
SMTV-761 — Checked domain SPF definition incorrect
SMTV-762 — Checked domain SPF definition incorrect
SMTV-763 — Checked domain SPF definition incorrect
SMTV-771 — Checked domain SPF definition incorrect
SMTV-772 — Checked domain SPF definition incorrect
SMTV-780 — Checked domain SPF definition incorrect
SMTX-590 — Boundary length out of bounds
SQLP-090 — TCP server returned with error
SQLP-099 — Final startup failure message
SQLP-100 — Proxy main loop select call failed
SQLP-104 — Original connection destination getting failed
SQLP-200 — Proxy main loop timeout reached
SQLP-239 — TCP socket closed by peer
SQLP-500 — Database users checking not allowed in unknown protocols
SQLP-550 — Connect string character set invalid
SQLP-590 — Cannot use DB-USER for unknown protocol versions
SQLP-801 — Client connection arrives to proxy
SQLP-808 — Session has started, client connection has arrived
SQLP-809 — Session finished
SQLP-888 — Unified SQL proxy statistics message
SQLS-105 — ALTQ queue assigment has failed
SQLS-110 — Searching of ACL failed
SQLS-119 — The proxy is unable to verify user authentication
SQLS-131 — Connection to server failed
SQLS-230 — Target server name cannot be resolved to IP address
SQLS-231 — Target server cannot be connected within timeout period
SQLS-232 — Target server connection failed
SQLS-239 — TCP socket closed by peer
SQLS-530 — Next-hop server/proxy name cannot be resolved to IP address
SQLS-531 — Next-hop server/proxy cannot be connected within timeout period
SQLS-532 — Next-hop server/proxy connection failed
SQLS-533 — Address being to be forced as source toward the server cannot be resolved
SQLS-700 — TNS protocol version information
SQLS-711 — TNS protocol checksum is not zero
SQLS-719 — SQL*Net service name exceeds configured limit
SQLS-730 — SQL*Net proxy cannot determine target server
SQLS-732 — Unexpected packet type received
SQLS-740 — Packet exceeds Session Data Unit
SQLS-741 — Packet length less than header size
SQLS-742 — Data offset points into packet structure
SQLS-743 — Packet is too short to contain data
SQLS-747 — Server offers TDU less than SDU
SQLS-748 — Server offers SDU out of valid range
SQLS-749 — Transparent Network Substrate layer error
SQLS-750 — Connect packet contains invalid connect string
SQLS-751 — Connect packet contains invalid connect string
SQLS-752 — Connect packet contains invalid connect string
SQLS-753 — Incorrect character found in attribute name
SQLS-754 — Real destination server cannot be determined
SQLS-759 — Connect packet contains invalid connect string
SQLS-760 — Connect string must contain named attribute
SQLS-761 — Named attribute of connect string must be string
SQLS-762 — Named attribute of connect string must be list
SQLS-763 — Named attribute of connect string value invalid
SQLS-771 — Too many redirection packets encountered
SQLS-781 — Continuation packet exceeds total packet size
SQLS-782 — Total length of fragmented message not reached
SQLS-783 — MORE flag set in packet completing whole message
SQLS-784 — Connect/redirect string packet splitted in incorrect offset
SQLS-810 — ACL decision has been made, session either accepted or rejected
SQLS-819 — Proxy user authentication finished
SQLS-820 — ACL decision has been made, operation either accepted or rejected
SQLS-831 — Connection to server was refused
SQLS-832 — Connection to server was redirected to another server
SQLS-840 — Session initialized, proxy is ready to mediate communication
SQLS-850 — Connect string parser message
SQLT-620 — SQL*Net RPC session authentication started
SQLT-621 — Database user successfully authenticated by SQL server
SQLT-622 — Database user logged off
SQLT-628 — Database user logon failed
SQLT-629 — Database user not allowed by configuration
SQLT-720 — Logon packet has incorrect format
SQLT-721 — Logon packet contain too long user name
SQLT-722 — Logon packet contains user name with invalid characters
SQLT-723 — SQL*Net RPC LOGON partially misunderstood
SQLT-725 — SQL*Net proxy cannot recognize RPC LOGON encoding
SQLT-727 — SQL*Net proxy registered database authentication result
SQLT-728 — Incorrect logging sequence
SQLT-729 — SQL*Net Remote Procedure Call received w/o authentication
SURI-100 — Failed to generate the suricata configuration file
TCPC-100 — Socket for outgoing connection not created
TCPC-210 — Function tcpclient() has successfully connected to server
TCPC-218 — Connection to one of server's IP addresses failed
TCPC-219 — Function tcpclient() failed to connect to server
TCPC-229 — Source network address translation failed
TCPP-104 — The main loop for serving clients (tcpserver) failed
TCPP-105 — ALTQ queue assigment has failed
TCPP-124 — The proxy cannot use SSL/TLS
TCPP-200 — Proxy cannot configure NAT address mapping on connection to server
TCPP-201 — Proxy cannot initialize data related to server connection
TCPP-202 — Proxy cannot create modules for communication with the server
TCPP-300 — Configured maximum of size of data from server to client exceeded
TCPP-301 — Configured maximum of size of data from client to server exceeded
TCPP-710 — A new proxy session has been started
TCPP-711 — A proxy session has terminated
TCPP-712 — Reports ACL used for this session
TCPP-801 — Proxy cannot create modules for communication with the client
TCPP-802 — The proxy cannot establish an SSL/TLS secure channel from the client
TCPP-803 — The proxy cannot establish an SSL/TLS secure channel to the server
TCPP-804 — The proxy is unable to verify user authentication
TCPP-805 — The proxy cannot initialize client data filtering
TCPP-806 — The proxy cannot initialize server data filtering
TCPP-807 — Cannot set the value of the IP packet TOS field
TCPP-850 — Some unexpected error occurred when searching ACLs
TCPP-851 — No ACL matches the connection from the client
TCPP-852 — The ACL matching the client connection denies access
TCPP-853 — The proxy does not know to which server it should connect
TCPP-888 — Unified TCP proxy statistics message
TCPS-001 — The parent process encountered a child process in unknown state
TCPS-002 — The child process encountered an unknown command from the parent
TCPS-104 — Error during waiting for a connection on multiple sockets
TCPS-105 — Error during accepting a connection on a socket
TCPS-109 — Cannot allocate memory for communication between parent and children
TCPS-110 — Cannot deallocate memory for communication between parent and children
TCPS-113 — Allocation of file descriptor array by malloc() failed
TCPS-115 — Kernun TCP server cannot create communication socket for listener
TCPS-118 — Trying to kill a superfluos child which already terminated
TCPS-119 — Killing a superfluos child failed
TCPS-120 — Parent failed when trying to create a new child process
TCPS-123 — The parent process tried to signal its children and received an error
TCPS-124 — The parent process tried to signal its children and received an error
TCPS-125 — Getting exit status of a terminated child process returned error
TCPS-128 — Connection from client has been closed before accepted
TCPS-500 — There are some invalid values in the configuration
TCPS-501 — There are some invalid values in the configuration
TCPS-502 — There are some invalid values in the configuration
TCPS-503 — There are some invalid values in the configuration
TCPS-700 — Notification about the mode of operation of the proxy
TCPS-701 — The parent process finds out that all its children terminated
TCPS-702 — The parent process finds out that a child was terminated by a signal
TCPS-704 — The parent process finds out that a child exited
TCPS-705 — The select() syscall returned and reported no ready file descriptor
TCPS-706 — The proxy accepted a new connection from a client
TCPS-707 — A client connection was handled
TCPS-708 — Log level incremented in response to a received signal
TCPS-709 — Log level decremented in response to a received signal
TCPS-710 — Graceful proxy termination is performed after receiving a signal
TCPS-711 — Immediate proxy termination is performed after receiving a signal
TCPS-712 — Log level incremented in response to a received signal
TCPS-713 — Log level decremented in response to a received signal
TCPS-714 — The proxy parent process is waiting for termination of children
TCPS-715 — Connection to a client was closed, proxy is waiting for another client
TCPS-716 — The proxy has received an information request signal
TCPS-717 — Statistical message about management of child processes
TCPS-718 — The proxy has been initialized and is ready to accept packets
TCPS-719 — Termination of a proxy process by a signal
TCPS-722 — The proxy has unbound the sockets used for listening for clients
TCPS-723 — The proxy has finished
TCPS-730 — Log file will be reopened
TCPS-731 — An alternative locking algorithm will be used
TCPS-732 — The standard flock(2) locking algorithm will be used
TCPS-733 — Kernun TCP server created communication socket for listener
TCPS-800 — An address in an unsupported address family was specified for a socket
TCPS-802 — There is not place for storing state of a new process
TCPS-804 — A client connection was finished with error
TCPS-805 — The child process with given PID cannot be found in the scoreboard
TCPS-810 — The configured maximum of proxy child processes has been reached
TCPS-811 — The tcpserver cannot be initialized properly
TCPS-812 — Proxy runtime monitoring support cannot be initialized
TCPS-813 — The tcpserver cannot be initialized properly
TCPS-900 — Information about the number of server sockets
TCPS-902 — The proxy starts serving connections from clients
TCPS-903 — A client connection accepted, handling function will be called
TCPS-904 — A new child process was started
TCPS-905 — Initial set of children is being created
TCPS-906 — The proxy parent process started initial children and continues
TCPS-907 — A proxy child process is terminating itself
TCPS-908 — Immediate child termination is performed after receiving a signal
TCPS-909 — Graceful child termination is performed after receiving a signal
TCPS-910 — Log level incremented in response to a received signal
TCPS-911 — Log level decremented in response to a received signal
TCPS-912 — The child process is superfluous and should exit
TCPS-913 — The child process got SIGHUP, but there is no command from the parent
TCPS-914 — The child process is superfluous and exits
TCPS-915 — There are not enough idle children, parent is creating new ones
TCPS-916 — There are too many idle children, some of them are asked to exit
TEST-150 — Cannot display list of groups in configuration
TEST-500 — Configuration tester expects command as -t option
TEST-530 — Too high phase number requested
UDPP-121 — Udp-proxy was not able to find an ACL appropriate to session
UDPP-709 — Final proxy termination message
UDPP-712 — The proxy is unable to verify user authentication
UDPP-810 — A datagram from a client has arrived, a session has started
UDPP-811 — Session initialized, proxy is ready to mediate communication
UDPP-812 — Session finished
UDPP-821 — ACL decision has been made, operation either accepted or rejected
UDPP-888 — Unified UDP proxy statistics message
UDPS-011 — An error occurred during waiting for a child process
UDPS-109 — General select() error
UDPS-110 — The proxy is unable to create a child process
UDPS-121 — No route to client
UDPS-141 — No route to server
UDPS-242 — The proxy cannot initialize communication with a server
UDPS-320 — The number of active sessions reached table size
UDPS-350 — UDP datagram is being sent
UDPS-360 — The proxy received too large datagram
UDPS-368 — Amount of data transferred exceeded its limit during a session
UDPS-369 — The number of datagrams reached its limit during a session
UDPS-501 — There are no addresses on which the proxy should wait for datagrams
UDPS-510 — The proxy has failed
UDPS-540 — Cannot resolve name needed for server connection
UDPS-541 — Session is non-transparent and no plug-to server found in acl
UDPS-542 — Proxy cannot receive responses from server
UDPS-543 — Cannot use aliased interface for source-port broadcast input and output
UDPS-630 — Data from invalid host on server side socket
UDPS-631 — Data from server occured in session of one-way type
UDPS-700 — Notification about the mode of operation of the proxy
UDPS-701 — The proxy has been initialized and is ready to accept packets
UDPS-705 — Proxy-specific code encapsulated in special function has finished
UDPS-708 — The proxy has unbound the sockets used for listening for clients
UDPS-709 — The proxy has finished
UDPS-710 — The child process was unexpectedly terminated
UDPS-711 — The child process was unexpectedly terminated by a signal
UDPS-730 — Server addres of an any-port or any-sock session will be fixed
UDPS-751 — Session lasts longer than allowed and will be terminated
UDPS-752 — The peer has not sent any data for too long
UDPS-810 — Child process PID info
UDPS-812 — Proxy runtime monitoring support cannot be initialized
URIP-710 — Processing of %xx sequences in URI failed
URIP-720 — URI cannot be parsed
URIP-730 — Internal form of URI is invalid
IV. Kernun UTM Reference (7)
access-control — Kernun proxies access control system
ak47 — Adaptive Kernun 4.7
antivirus — Kernun virus checking support
auth — client authentication on proxy
cluster — Kernun firewall redundancy cluster support
configuration — general syntax of configuration files
data-matching — generic data matching and processing in proxies
doctype-identification — document type recognition methods and configuration
host-matching — configuration semantics of lists of hosts
ips — intrusion detection/prevention system and the related aspects
kernun — signpost to Kernun firewall manual pages
logging — Kernun firewall logging facility
monitoring — Kernun firewall runtime monitoring support
netio — Kernun firewall network I/O layer
port-range-listen — the ability of proxies to listen on a port range and the related aspects
resolving — DNS resolving in Kernun applications
tcpserver — TCP client connections and process management in proxies
time-matching — syntax and semantics of time specification in configuration
traffic-shaping — Kernun firewall traffic shaping support
transparency — network transparency and the related aspects
udpserver — UDP session and process management in proxies
V. Kernun UTM Reference (8)
ak-db.sh — Adaptive Kernun 4.7 blacklist control tool
atrmon — Adaptive Traffic Routing monitoring daemon
bootmgr — tool for configuring Kernun boot manager
cml — Configuration Meta-Language
cwcatd — Clear Web automatic categorization daemon
dns-proxy — Domain Name System (DNS) proxy
ftp-proxy — File Transfer Protocol (FTP) proxy
gk-proxy — H.323 Gatekeeper RAS proxy
h323-proxy — H.323 Protocol Family proxy
http-proxy — HyperText Transfer Protocol (HTTP) proxy
icamd — Intra Cluster Accessibility Master Daemon
icap-server — ICAP server for document inspection
icasd — Intra Cluster Accessibility Slave Daemon
imap4-proxy — Internet Message Action Protocol v. 4 (IMAP4) proxy
kat — Kernun Admin Tool
kavhttpd — Kaspersky AV in HTTP mode integrated in Kernun UTM
pf-control — Packet filter control daemon
pikemon — PIKE cluster protocol control daemon
pop3-proxy — Post Office Protocol v. 3 (POP3) proxy
sip-proxy — Session Initiation Protocol (SIP) proxy
smtp-proxy — Simple Mail Transfer Protocol (SMTP) proxy
sqlnet-proxy — Oracle SQL*Net Proxy
sysmgr — tool for Kernun installation, upgrade, backup, and restore
tcp-proxy — transparent generic TCP proxy
udp-proxy — generic UDP proxy

List of Figures

2.1. ZFS boot manager screen 1
2.2. ZFS boot manager screen 1
2.3. The System Manager icon in the toolbar
2.4. Installation images in the System Manager
2.5. Selection of the installation target
2.6. The system partitions after the installation
2.7. An error during the installation
2.8. Existing backup files in the GUI
2.9. Parameters of a restore operation
2.10. Final settings after restoring a backup
2.11. Parameters of an upgrade operation
2.12. The conflict resolution window during an upgrade
2.13. Final settings after an upgrade
3.1. GUI Launcher
3.2. Connecting to Server
3.3. GKAT — Kernun UTM management console
3.4. Kernun UTM Manage Page
3.5. System state synchronization dialog
3.6. Process List page
3.7. Process List context menu
3.8. Graphs page
3.9. Top page
3.10. Misc page
3.11. Version
3.12. Proxy Monitor
3.13. Proxy Log
3.14. Main window toolbar buttons, listed together with the corresponding menu items, and sometimes keyboard shortcuts:
3.15. Example of a simple HTTP filter and marker set
3.16. GUI CML Editor
3.17. Configuration commit dialog
3.18. Bookmarks and relevant sections in GUI CML
3.19. Configuration already locked by other user
3.20. Break lock confirmation
3.21. Configuration and System Manager at the same time
3.22. Configuration unlock failed
3.23. Commit configuration to RCS confirmation
3.24. Initialize RCS confirmation
3.25. Configuration lock broken
3.26. Configuration not longer locked
4.1. Tree structure of the configuration
4.2. Tree structure of the configuration
4.3. Including configuration files and using section variables
4.4. The global level of the initial configuration file
4.5. Various system-level definitions
4.6. Definitions of network interfaces
4.7. Definitions of various network parameters
4.8. An SSH server for administrative access
4.9. The server for handling locally-originated mail
4.10. Hidden proxies and a global ACL
4.11. DNS Proxy
4.12. HTTP Proxy
4.13. FTP proxy
4.14. Proxies HTTPS and SSH
4.15. SMTP Proxy System Sections and Forward Agent
4.16. SMTP Proxy ACLs
4.17. SMTP Proxy Mail Filter
4.18. SMTP Proxy Mail Sever in the Internal Network
4.19. IMAP4 Proxy
4.20. POP3 Proxy
4.21. The Kernun UTM running the initial configuration
4.22. The modified configuration
4.23. Activation of the new configuration
4.24. Reconfigured Kernun UTM is running
4.25. TCP proxy general network settings
4.26. TCP proxy ACL settings
4.27. TCP proxy miscellaneous settings
4.28. TCP proxy recapitulation
4.29. Non-transparent TCP proxy ACL settings
5.1. A simple blocking packet filter rule
5.2. A blocking packet filter rule with return
5.3. Option block-policy instead of return in rule
5.4. More specific rule must come first
5.5. Simple antispoofing rule
5.6. Antispoofing rule including routes
5.7. Selective packet forwarding rule
5.8. Mapping NAT rule
5.9. Redirection NAT rule
5.10. Forwarding of ICMP Packets over NAT
5.11. User account configuration
5.12. Network Interfaces
5.13. Static Routes
5.14. BIRD dynamic routing
5.15. rc.conf configuration
5.16. sysctl.conf configuration
5.17. crontab configuration
5.18. Caching Name Server configuration
5.19. DNS Server - Proxy configuration
5.20. DNS Server - BIND configuration
5.21. DHCP configuration
5.22. Minimum NTP server configuration
5.23. Peer for NTP server
5.24. On-board clock with NTP server
5.25. Log of an HTTP request
5.26. Statistics browser window
5.27. Configuration of statistics
5.28. HTTP Proxy listening both in transparent and non-transparent mode
5.29. Configuration of non-transparent mode in Firefox and Microsoft Internet Explorer Web browsers
5.30. Sockstat tab showing the list of all sockets
5.31. Tracking transparent and non-transparent connections in the http-proxy log (the log was filtered, in order to save space).
5.32. Transparency for servers (source-address client)
5.33. A port shared by two applications
5.34. The sip-proxy configured to listen transparently on a port range 5060-5062
5.35. SIP Proxy
5.36. SQL*Net Proxy
5.37. UDP proxy
5.38. Cooperation of HTTP and FTP
5.39. SSL/TLS security configuration
5.40. Authentication methods
5.41. Log of authentication in FTP proxy
5.42. Proxy authentication dialog in a Web browser
5.43. User authentication configuration in the HTTP proxy
5.44. Log of user authentication in the HTTP proxy
5.45. Kerberos authentication — section system
5.46. Kerberos authentication — section http-proxy
5.47. Transparent Kerberos authentication — session ACLs
5.48. Transparent Kerberos authentication — request ACLs
5.49. NTLM authentication — section system
5.50. NTLM authentication — section http-proxy
5.51. Configuration of the HTTP authentication proxy
5.52. The user authentication dialog of the HTTP authentication proxy
5.53. The logout confirmation message of the HTTP authentication proxy
5.54. Configuration of the out-of-band authentication
5.55. Login to the OOB authentication server
5.56. Configuration of the connection to the antivirus program
5.57. Configuration of the connection to the antivirus program via ICAP
5.58. Use of antivirus in the FTP and HTTP proxies
5.59. Discarding infected messages in the SMTP proxy
5.60. Replacing infected documents in the SMTP proxy
5.61. Replacing infected documents in the POP3 proxy
5.62. Replacing infected documents in the IMAP4 proxy
5.63. Antispam protection for POP3 proxy
5.64. Antispam protection for IMAP4 proxy
5.65. Antispam protection for SMTP proxy
5.66. White- and black-listing for SMTP proxy
5.67. Grey-listing for SMTP proxy
5.68. Content Type detection configuration for HTTP proxy
5.69. HTML filter example
5.70. Mail filter example in use with IMAP4, POP3 and SMTP proxies
5.71. Request URI matching and rewriting
5.72. Log of URI matching and rewriting
5.73. A blacklist in the HTTP proxy
5.74. A log of blacklist usage in the HTTP proxy
5.75. Kernun Clear Web DataBase in the HTTP proxy
5.76. An HTTP proxy configured for use of an external Web filter
5.77. A Web server blocked by the Web filter
5.78. Certification authorities for HTTPS inspection
5.79. HTTPS inspection ACL flow
5.80. HTTPS inspection configuration
5.81. HTTPS termination global configuration
5.82. HTTPS termination proxy configuration
5.83. Intrusion detection/prevention system
5.84. Configuration of traffic shaping queues
5.85. Traffic shaping by packet filter ACLs
5.86. Traffic shaping by proxy ACLs
5.87. OpenVPN components in a GKAT window
5.88. RAS: Virtual network settings
5.89. RAS: Physical network settings
5.90. Shared file creation dialog
5.91. RAS: Authentication settings
5.92. RAS: Client settings
5.93. RAS OpenVPN wizard: The resulting configuration
5.94. Net-to-Net OpenVPN wizard: Virtual network settings page
5.95. Net-To-Net OpenVPN wizard: Physical network settings page
5.96. Net-To-Net OpenVPN wizard: Authentication settings page
5.97. Net-To-Net OpenVPN wizard: The resulting configuration
5.98. IPsec components in a GKAT window
5.99. IPsec configuration
5.100. Simple cluster with two nodes and two networks
5.101. apply-host is used to distinguish the local system from the remote one
5.102. Definition of system variable CLUSTER
5.103. Usage of parameters inside CLUSTER definition
5.104. Use of variable CLUSTER to define two nodes
5.105. Definition of pikemon and virtual clusters
5.106. Multiple systems can be controlled using icamd / icasd daemons
5.107. Simplified icamd/icasd configuration using item ica-auto
5.108. Full icamd/icasd configuration
5.109. A schema of the front and the back face of Kernun Branch Access
5.110. IPv6 interfaces
5.111. IPv6 networking parameters
5.112. Proxies with IPv6 support
5.113. Honeypot

How to Read the Documentation

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:

Text files

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.

PDF

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.

HTML

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.

Manual pages

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:

Section 1

User commands, mainly various tools for runtime monitoring and generation of statistics.

Section 5

Configuration. Individual sections of the /usr/local/kernun/conf/kernun.cml configuration file are documented in this section.

Section 6

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.

Section 7

The manual pages in this section explain general concepts. They cover features that are common to many parts of Kernun UTM, such as proxies.

Section 8

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.

Chapter 1. Kernun UTM Product Overview

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.

1. Kernun UTM

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.

2. Kernun Clear Web

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.

Chapter 2. Kernun UTM System Management

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.

1. Installation Media, Releases, and Builds

Each Kernun UTM release is distributed using the following types of distribution media:

USB flash drive image

A bootable disk image, which contains the installation tools and the full installation image.

Full 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.

Patch image

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.

2. Disk Space Layout

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.

Warning

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.

3. Licensing

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.

Note

  • 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.

Note

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;

4. Boot Manager

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.

4.1. ZFS boot manager

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.

Figure 2.1. ZFS boot manager screen 1

ZFS boot manager screen 1

Figure 2.2. ZFS boot manager screen 1

ZFS boot manager screen 1

4.2. LEGACY (UFS) boot manager

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.

4.3. Security notice

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:

  1. Disable boot device selection in the BIOS (for example, by setting a BIOS password).

  2. Enable only the desired system partition in the boot manager (using bootmgr(8)).

  3. Add line “-n” to /boot.config. This prevents interrupting the boot process in the stages one and two.

    # printf --
            '-n\n' >
            /boot.config
  4. 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
  5. 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”.

5. Installation

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.

Note

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).

5.1. Standalone Installer

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.

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)

Reyply 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 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.

Tip

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.

Warning

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:

  1. Prepare a USB disk with a UFS or FAT file system.

  2. 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.

  3. Do not connect the USB disk yet and select 0 from the installer main menu.

  4. 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.

Note

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.

5.2. Initial Configuration

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.

Caution

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 1
Domain []: example.com
Show only Ethernet interfaces (y/n)? [y] 2

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) 3
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 4
Internal IP address []: 192.168.10.1
Internal interface netmask [24]:
External interface name (ed0 ed1) []: ed1 5
External IP address []: 192.168.11.2
External interface netmask [24]:
DNS server IP address []: 10.1.1.1 6
Default router IP address []: 192.168.1.1 7
Postmaster e-mail [postmaster@example.com]: 8
Enable some proxies (y/n)? y 9
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:           fw 10
Domain:             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 11
    

The configuration begins 1 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 2 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 3, the cable was unplugged from the network interface ed0. The internal 4 and external 5 interface names, IP addresses, and network masks are defined. The DNS server IP address 6 is used by Kernun UTM for domain name resolution. The default router 7 is typically a router in the external network. The postmaster e-mail address 8 is used by the SMTP proxy to forward mail sent to the postmaster.

You can also enable some proxies 9 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 10. If you are satisfied, reply y 11 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:

  1. 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
    $ 
  2. 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 ~]# 
  3. Delete the key files in the home directory of user keygen.

    [root@fw ~]# rm ~keygen/*
  4. Disable the keygen account.

    [root@fw ~]# pw lock keygen
  5. 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.

5.3. Installation from the GUI

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 1 button in the main window toolbar, as shown in Figure 2.3, “The System Manager icon in the toolbar”.

Figure 2.3. The System Manager icon in the toolbar

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 Upload button. The Download button can be used to copy in the opposite direction. It is also possible to delete a selected image (Remove) or all images older than the selected one[7] (Remove older).

Figure 2.4. Installation images in the System Manager

Installation images in the System Manager

Tip

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 Remove older. It is usually sufficient to retain only the one or two most recent images.

To initiate the installation of the selected image, click the Install 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 Install firewall button on 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 Finish button to launch the installation process (it deletes all the existing content of the selected partition).

Figure 2.5. Selection of the installation target

Selection of the installation target

Caution

When 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 Change Title button) or make the new system partition the default boot partition (the Set Default button).

Figure 2.6. The system partitions after the installation

The system partitions after the installation

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.

Figure 2.7. An error during the installation

An error during the installation

5.4. Installation from the Command Line

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 1
*  030001h00.200811142135.i386

The installable images are marked with an asterisk. The image 1 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) 1
F2: Unused
F3: Unused
type=Kernun 1024 B boot manager (74 character labels)
current_booted=1 2
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 3
[root@fw ~]# mount /3
mount: /dev/ad0s3a on /3: incorrect super block 4

The bootmgr command displays labels of the system partitions 1 and the number of the system partition that contains the currently running system 2. The second system partition in the example contains another Kernun UTM version 3, even though it was manually relabeled as “Unused”. The third system partition is really unused; it does not even contain a file system 4.

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

Caution

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.

Caution

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

5.5. Enabling Serial Console Output

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/loader
    boot: -h

6. Backup and Restoring

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.

6.1. Backup and Restoring from the GUI

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 Backup 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.

Figure 2.8. Existing backup files in the GUI

Existing backup files in the GUI

Click on the Restore button if you want to start the restore operation. Alternatively, restoring can be initiated using Restore backup 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 Finish, 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”).

Figure 2.9. Parameters of a restore operation

Parameters of a restore operation

Figure 2.10. Final settings after restoring a backup

Final settings after restoring a backup

6.2. Backup and Restoring from the Command Line

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

6.3. Restoring a Backup in the Standalone Installer

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 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 2
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 3
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 4

Select partition to be restored (1 2 3) [1]: 3 5
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 6
Restoring backup-030000h00.200809241501.i386-1-200810010405.tbz
to partition 3
Are you sure (y/n)? y
Conflicts resolution data in /data/restore already exist 7
Remove old /data/restore (y/n)? y 8
Processing changes of file system contents
Unpacking files from backup 9
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 1 in an unused system partition 2. The installation image 3 is chosen so that it corresponds to the backup file that will be restored. After returning to the installer main menu, we select Restore backup 4. The partition 5 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 6 and the restoring begins. The message 7 indicates that there are unresolved conflicts from previous restore or upgrade operations. Usually, you should reply n to the question 8. 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 78 will not be displayed if there are no pending conflicts. Finally 9, 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.

7. Upgrade

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:

  1. Normalizing the configuration.

  2. Backing up the system partition with the old version.

  3. Installing the new version.

  4. Restoring the backup created in step 2 to the installed new version.

  5. Resolving any conflicts arisen in step 4.

  6. Upgrading the Kernun UTM configuration file.

  7. Checking the upgraded configuration.

  8. Applying the upgraded configuration.

  9. Starting the new Kernun UTM version.

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.

Important

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.

Tip

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.

Tip

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.

7.1. Upgrade from the GUI

An upgrade is initiated from the Quick Wizards page of the System Manager. There are two alternatives. Click Upgrade Firewall 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 Restore backup into newer firewall 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 Upgrade Firewall 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 (Figure 2.11, “Parameters of an upgrade operation”). Click on the Finish button to start the upgrade.

Figure 2.11. Parameters of an upgrade operation

Parameters of an upgrade operation

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.

Figure 2.12. The conflict resolution window during an upgrade

The conflict resolution window during an upgrade

After you give instructions for conflict resolution and optionally edit some conflicting files, click OK to have the conflicts resolved. Finally, a window is displayed (see 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.

Figure 2.13. Final settings after an upgrade

Final settings after an upgrade

7.2. Upgrade from the Command Line

Command 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 1
RCSL-730-N File '/usr/local/kernun/conf/kernun.cml' locked for current user
CMLM-790-N RCS command completed
[root@fw ~]# sysmgr checkcfg 2
...
Configuration is correct
[root@fw ~]# sysmgr backup 3
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 4
Clearing system partition 2
...
Installation successfully finished
[root@fw ~]# sysmgr upgrade 2 \
> backup-030000h00.200809241501.i386-1-200811300006.tbz 5
Processing changes of file system contents
Unpacking files from backup
Resolving conflicts
There are pending conflicts, see /data/restore/resolve


*** CONFLICT RESOLUTION *** 6

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 7
# 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 8
[root@fw ~]# vi /data/restore/resolve 9
...
[root@fw ~]# sysmgr resolve 10
Resolving conflicts
All conflicts resolved
[root@fw ~]# sysmgr upgradecfg 2 11
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 12
...
System kernun applied in system partition 2
[root@fw ~]#  cml -u -f /usr/local/kernun/conf/kernun.cml 13
CMLM-790-N RCS command completed
[root@fw ~]# 

Before upgrade, the configuration should be locked 1[11], checked and normalized 2. This step ensures that the configuration upgrade step 11 will understand the configuration file. The upgrade procedure starts by backing up the current system partition 3. 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 4. 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 5. 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 6. 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 7 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 8 is printed. It is then possible to edit /data/restore/resolve manually 9 and restart the conflict resolution 10. Commands 9 and 10 can be repeated until all conflicts are resolved. The main configuration file is upgraded 11 and applied 12. Finally, the lock is released 13. You can then reboot to the new system partition and start using the upgraded Kernun UTM.

8. Audit

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.

9. Emergency Repair Environment

Warning

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.

Warning

The content of the RAM disk is lost when the installer is terminated or when the RAM disk is resized.

Caution

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.

Tip

It is often useful to perform a chroot(8) to a mounted Kernun UTM system partition and to run commands in the chrooted environment.

10. Running in virtual machine 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.

10.1. VMware

The emulators/open-vm-tools-nox11 is installed and staretd automatically if the VMWare environment is detected.

10.2. Hyper-V

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.

10.3. VirtualBox

The emulators/virtualbox-ose-additions is installed and started automatically if the VirtualBox environment is detected.

10.4. XEN

The sysutils/xe-guest-utilities is installed and started automatically if the XEN 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 contains 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 1 and 13 are supported by Kernun since release 3.6. In the prior versions, these steps should be skipped.

Chapter 3. User Interface

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).

1. Graphical User Interface

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.

1.1. Kernun GUI Launcher

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.

Figure 3.1. GUI Launcher

GUI Launcher

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.

Tip

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 Initialize new system button is pressed. Fill in the Hostname and the Password you entered during the installation. See also Section 5.2, “Initial Configuration”.

Figure 3.2. Connecting to Server

Connecting to Server

If 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.

Important

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.

1.2. GKAT—Management Console

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.

Figure 3.3. GKAT — Kernun UTM management console

GKAT — Kernun UTM management console

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.

1.2.1. Kernun UTM Details

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”.

Figure 3.4. Kernun UTM Manage Page

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 OK and all the selected actions will be executed.

Figure 3.5. System state synchronization dialog

System state synchronization dialog

The Process List page (Figure 3.6, “Process List page”) contains the list of the running parent proxy processes[13].

Figure 3.6. Process List page

Process List page

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.

Figure 3.7. Process List context menu

Process List context menu

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.

Figure 3.8. Graphs page

Graphs page

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.

Figure 3.9. Top page

Top page

Figure 3.10. Misc page

Misc page

Figure 3.11. Version

Version

1.2.2. Proxy Details

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 Synchronize system button and the combo box used to restrict operations to the tagged components are missing. For individual proxies, there are three additional buttons. Kill terminates the proxy like Stop, but works also for proxies that are removed from the configuration. The SIGUSR1 and SIGUSR2 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.

Figure 3.12. Proxy Monitor

Proxy Monitor

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 Help to MsgId 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.

Figure 3.13. Proxy Log

Proxy Log

1.2.3. Network Interface Details

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.

1.2.4. Toolbar and Menu

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:

Main window toolbar buttons, listed together with the corresponding menu items, and sometimes keyboard shortcuts:


  1. Help | About Kernun GUI — Shows the about dialog box with information about the GUI version.

  2. Settings | Preferences — Opens the basic preferences dialog, in which you can set the default behavior of your GUI (e.g., your default diff program).

  3. File | Analyze Log <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”).

  4. File | Statistics — 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.

  5. The Configuration submenu:

    • Edit Kernun configuration — Downloads the Kernun UTM configuration and opens a window, in which you can edit it (see Section 1.4, “GCML — Configuration”).

    • Configure Kernun from the remote example — Lets you choose and edit a sample Kernun UTM configuration that you can later use as your Kernun UTM configuration.

    • Import the configuration from a local file — 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.

    • Recent versions of the configuration file — 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.

  6. The Console submenu:

    • Kernun console — Opens the console with an ssh connection to Kernun UTM.

    • Add custom remote command — 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 Console menu and can be easily invoked.

  7. File | Kernun Systems Management — Provides routines to install, backup, and upgrade Kernun UTM installations. See 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 Settings | License. It displays the current license file and provides a button for uploading a license file to Kernun UTM.

  8. File | Reconnect — Restarts the connection from the GUI to Kernun UTM. It may be useful if your RTT gets too high or the connection is interrupted.

  9. View | Tear off the tab <Ctrl+T> — Opens the current page in a new window and keeps it up-to-date (refreshes the selected page).

  10. 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.

  11. Start/Stop — Starts and stops refreshing (downloading of new information from Kernun UTM) of the current page.

  12. View | Tear off a snapshot — 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).

  13. View | Clear the contents — Clears the contents of the current page.

  14. View | Show/Hide Filters&Markers Window <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”).

  15. View | Show/Hide Detail Window <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.

  16. View | Show/Hide Bookmarks Window <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.

  17. View | Find <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.

  18. View | Find next marked line <Ctrl+G> — Jumps to the next line marked by the chosen marker.

  19. View | Find previous marked line <Ctrl+Shift+G> — Jumps to the previous line marked by the chosen marker.

  20. View | Line-Up Columns <Ctrl+I> — Adjusts the column widths according to the widths of their contents.

  21. View | Jump to the beginning <Ctrl+Up> — Scrolls to the beginning of the current page.

  22. Keep at end <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.

1.3. Logs

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).

1.3.1. Filter and Marker Basics

Figure 3.15, “Example of a simple HTTP filter and marker set” shows an example of a log display window (created by selecting File | Analyze Log 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.

Figure 3.15. Example of a simple HTTP filter and marker set

Example of a simple HTTP filter and marker set

The filters and markers are accessible using View | Show/Hide Filters&Markers Window (<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.

Note

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 Apply filter option from the context menu of 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).

Important

If 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.

1.3.2. Creating Filter Conditions

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.

1.3.3. Saving and Loading Filters and Markers

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 Load filters/markers submenu of the top-level Filters/Markers context menu.

Tip

To rename a filter/marker, double-click on its name or select Rename from the context menu.

1.4. GCML — Configuration

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 (kernun.cml). 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.

1.4.1. Configuration Window Overview

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.

Figure 3.16. GUI CML Editor

GUI CML Editor

When editing the configuration, select File | Show differences 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 File | Save the configuration as a local file menu item. In addition to online marking of incorrect configuration nodes, it is possible to invoke verification of the whole configuration using Verify | Verify the configuration.

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 File menu. Committing of the configuration (<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 Synchronize system, 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”.

Figure 3.17. Configuration commit dialog

Configuration commit dialog

1.4.2. Interaction with the Configuration Tree

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 Edit 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 Expand current node recursively <Ctrl++> (and collapsed using the Collapse … <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 Remove (<Ctrl+D>), Hide (<Ctrl+H>), Copy (<Ctrl+C>), Cut (<Ctrl+X>) or Paste (<Ctrl+V>, pastes the last copied/cut node under the selected one) a node.

Tip

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 View | View expanded configuration 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 Insert menu is relatively easy with the GUI. First, you need to decide where you want to add the new node (as the first child, as the last child (<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.

1.4.3. Form Field Types

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 [ip]:port). The syntax of values of various data types used in the Kernun UTM configuration is described in Section 1, “Configuration Language”.

  • 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 Edit | Toggle combobox/explicit value 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 Delete icon next to it. To insert a new value, click the Append Value 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 Append Sublist button. On the right from a sublist there is a button with a submenu that allows to Remove the sublist or Exclude the sublist (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 Append File 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.

Tip

The contents of the shared-file can be edited in the GUI in the details of the path item of the shared-file section.

1.4.4. Bookmarks

As orientation in a very big configuration may become difficult, the Kernun GUI provides tools to simplify it.

First of all, you can use View | Show/Hide Bookmarks Window (<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 Bookmark this node option from its context menu or the Bookmark current position 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.

Figure 3.18. Bookmarks and relevant sections in GUI CML

Bookmarks and relevant sections in GUI CML

1.4.5. Relevant Nodes

In addition to simple bookmarks, the Kernun GUI provides smart bookmarks, accessible via View | Show/Hide Relevants window (<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 Bookmark this… (which adds the current item to the simple bookmarks), Jump to node (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.

Tip

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 Automatically refresh relevants check box in its context menu. If it is unchecked, you have to refresh the list manually by clicking the Refresh button.

1.4.6. Configuration Wizards

The Kernun GUI provides configuration wizards in order to simplify the configuration of complex tools (OpenVPN, IPSec). All the wizards are accessible via the Insert | Configuration wizard menu item. Select Overview of the wizards 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.

Tip

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.

1.5. Locking

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”).

Figure 3.19. Configuration already locked by other user

Configuration already locked by other user

Figure 3.20. Break lock confirmation

Break lock confirmation

Figure 3.21. Configuration and System Manager at the same time

Configuration and System Manager at the same time

Figure 3.22. Configuration unlock failed

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”).

Figure 3.23. Commit configuration to RCS confirmation

Commit configuration to RCS confirmation

Figure 3.24. Initialize RCS confirmation

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”).

Figure 3.25. Configuration lock broken

Configuration lock broken

Figure 3.26. Configuration not longer locked

Configuration not longer locked

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 ...

3. Administrative Utilities

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.

Note

The full contents of terminal sessions of the administrator are logged[16] in the /var/log/session-USER-DATE-HOST.log.gz files.

bootmgr(8)

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.

diskdb(1)

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.

fwpasswd(1)

Program for management of password files for user authentication. See Section 14.1, “Authentication Methods” for more information.

log-ts(1)

It selects messages from Kernun UTM's logs using various criteria. Automatically selects the log files that cover the required time interval.

kernun-audit(1)

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”.

mkblacklist(1), printblacklist(1), resolveblacklist(1)

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.

monitor(1)

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”.

ooba-samba(1)

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”.

quarc.sh(1)

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.

rrd(1)

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”).

sum-stats(1)

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 File | Statistics from the main menu.

switchlog(1)

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.

triplicator(1)

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.

sysmgr(8)

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.

Chapter 4. Configuration Basics

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.

1. Configuration Language

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 system 1
system fw { 2
  ## Host name without domain
  hostname fw; 3
  ## 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 { 4
    dev em0;
    ipv4 [192.168.10.1/24]; 5
  }

Figure 4.1. Tree structure of the configuration

Tree structure of the configuration

In the sample configuration there is a section of type system named fw 2. It contains several subsections and items. For example, an item hostname with an element (value) fw 3, or a subsection interface named INT 4 containing an item ipv4 5. Note that it is possible to include comments in the configuration file. They are also displayed by the GUI 1.

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 5. 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

system fw {
  ...
  ssh-server SSHD {
    listen-sock ^system.INT.ipv4.host 1 : 22;
    ...
  }
  ...
}

Here, 1 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; 1
  ...
  ## SSH daemon for remote administrator access from the internal network

  ssh-server SSHD {
    listen-sock $INT_IP 2 : 22;
    passwd-auth;
  }

The previous example is changed so that the reference path is stored in a variable called INT_IP 1 and the variable is used instead the full path later 2. 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.

Figure 4.2. Tree structure of the configuration

Tree structure of the configuration

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 1. It defines the variables DEFAULT-CRONTAB and DEFAULT-PERIODIC. The first variable is used at 2. Note that the GUI displays the contents of included files.

Figure 4.3. Including configuration files and using section variables

Including configuration files and using section variables

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.

Important

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.

2. The Initial Configuration

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.

2.1. Global Level

Figure 4.4. The global level of the initial configuration file

The global level of the initial configuration file

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.

2.2. System

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.

Figure 4.5. Various system-level definitions

Various system-level definitions

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.

Figure 4.6. Definitions of network interfaces

Definitions of network interfaces

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.

Figure 4.7. Definitions of various network parameters

Definitions of various network parameters

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.

Note

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.

2.3. SSH Server

Figure 4.8. An SSH server for administrative access

An SSH server for administrative access

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.

2.4. Local Mail Handling

Figure 4.9. The server for handling locally-originated mail

The server for handling locally-originated mail

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.

2.5. Application Proxies and ACLs

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.

Figure 4.10. Hidden proxies and a global ACL

Hidden proxies and a global ACL

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.

Note

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.

2.6. DNS Proxy

Figure 4.11. DNS Proxy

DNS Proxy

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.

Caution

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.

2.7. HTTP Proxy

Figure 4.12. HTTP Proxy

HTTP Proxy

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.

Important

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.

2.8. FTP Proxy

Figure 4.13. FTP proxy

FTP proxy

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).

2.9. HTTPS and SSH Proxy

Figure 4.14. Proxies HTTPS and SSH

Proxies HTTPS and SSH

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.

2.10. SMTP Proxy

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.

Figure 4.15. SMTP Proxy System Sections and Forward Agent

SMTP Proxy System Sections and Forward Agent

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.

Figure 4.16. SMTP Proxy ACLs

SMTP Proxy ACLs

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.

Warning

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.

Figure 4.17. SMTP Proxy Mail Filter

SMTP Proxy Mail Filter

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.

2.10.1. Mail Server in the Internal Network

Figure 4.18. SMTP Proxy Mail Sever in the Internal Network

SMTP Proxy Mail Sever in the Internal Network

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).

2.11. IMAP4 and POP3 Proxy

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.

2.11.1. IMAP4 Proxy

Figure 4.19. IMAP4 Proxy

IMAP4 Proxy

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”.

2.11.2. POP3 Proxy

Figure 4.20. POP3 Proxy

POP3 Proxy

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”.

3. Changing the Configuration

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.

  1. 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”.

  2. Select Configuration | Edit configuration of the firewall in the menu to open the configuration.

  3. 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 Hide/Unhide. The line will change to dns-proxy DNS.

  4. Repeat the same action for the line containing hidden http-proxy HTTP.

  5. Select the line acl INTOK and then select Add node next to this node | Section or Item 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.

  6. Now select the newly created ACL and use Add new node as last child | Section or Item from its context menu repeatedly to add the from, service, and deny items.

  7. 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 Append Value. Enter the address (with mask) of the subnet that is to be denied, for example, [192.168.10.128/25].

  8. Select the service item. Using Append Value, add HTTP to the list.

  9. 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 Move Up in its context menu.

  10. 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.

  11. Add a request-method { GET } item to this ACL in the same way as when you modified values in acl NET1_DENY.

  12. The configuration should now correspond to Figure 4.22, “The modified configuration”.

  13. Save, generate, and apply the configuration by selecting File | Commit the configuration to the firewall. The Commit configuration window is displayed, as depicted in Figure 3.17, “Configuration commit dialog”.

  14. Click Commit to enter a RCS log message with a description of the change you have made.

  15. 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).

  16. 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.

  17. Click OK in the synchronization dialog to finish the reconfiguration; Kernun UTM now contains running DNS and HTTP proxies, see Figure 4.24, “Reconfigured Kernun UTM is running”.

  18. 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.

Figure 4.21. The Kernun UTM running the initial configuration

The Kernun UTM running the initial configuration

Figure 4.22. The modified configuration

The modified configuration

Figure 4.23. Activation of the new configuration

Activation of the new configuration

Figure 4.24. Reconfigured Kernun UTM is running

Reconfigured Kernun UTM is running

3.1. Adding TCP Proxies

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.

3.1.1. TCP Proxy to Server in External Network

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 Insert | Configuration wizard | TCP proxy to external network 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”.

Figure 4.25. TCP proxy general network settings

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”.

Figure 4.26. TCP proxy ACL settings

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”.

Figure 4.27. TCP proxy miscellaneous settings

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.

Figure 4.28. TCP proxy recapitulation

TCP proxy recapitulation

3.1.2. TCP Proxy to Server in Internal Network

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.

Figure 4.29. Non-transparent TCP proxy ACL settings

Non-transparent TCP proxy ACL settings



[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.

Chapter 5. Advanced features

Table of Contents

1. Packet Filter
1.1. Packet Flow
1.2. Packet Filtering
1.3. Antispoofing Using Packet Filter
1.4. Selective Packet Forwarding
1.5. Network Address Translation
1.6. Packet Forwarding along with NAT
1.7. Defending against DoS/DDoS Attacks
1.8. Honeypot
2. System Configuration
2.1. User Accounts
2.2. Network Interfaces
2.3. Static Routes
2.4. Dynamic IP routing with BIRD
2.5. File /etc/rc.conf
2.6. Kernel Parameters in /etc/sysctl.conf
2.7. Configuration of the cron Daemon
3. Caching Name Server
4. DNS and DHCP Services
4.1. DNS Server for the Local Zone
4.2. DHCP Server for the Local Network
5. Time Synchronization with NTP
6. Monitoring of Kernun UTM Operation
6.1. Logging Configuration
6.2. Log Rotation
6.3. Monitoring of Active Sessions
6.4. Proxy Statistics Generation
6.5. Monitoring of System Parameters
7. Networking in Proxies
7.1. Transparent Proxies
7.2. A Proxy and a Server on the Same Port
7.3. Listening on a port range
8. H.323 Proxies
9. SIP Proxy
10. SQLNet Proxy
11. UDP Proxy
12. Cooperation of HTTP and FTP Proxies
13. Secure Communication Using SSL/TLS
14. User Authentication
14.1. Authentication Methods
14.2. Authentication in FTP Proxy
14.3. Basic Authentication in HTTP Proxy
14.4. Kerberos Authentication in HTTP Proxy
14.5. Kerberos Authentication in Transparent HTTP Proxy
14.6. NTLM Authentication in HTTP Proxy
14.7. HTTP Authentication Proxy
14.8. Out of Band Authentication
15. Antivirus Checking of Data
15.1. Connecting with Dr.WEB
15.2. Connecting with ClamAV
15.3. Connecting via ICAP protocol
15.4. Antivirus Results
15.5. Antivirus in Proxies
15.6. SMTP Proxy: Discarding Infected Mails
15.7. SMTP Proxy: Replacing Infected Documents
15.8. Antivirus in POP3 and IMAP4 Proxies
16. Antispam Processing of E-mail
16.1. Antispam Engine
16.2. White-, Grey-, and Blacklists
17. Content Processing
17.1. Content Type Detection
17.2. HTML Filtering
17.3. MIME Processing
18. Filtering HTTP Requests by URI
18.1. URL Matching and Rewriting
18.2. Blacklists in HTTP Proxy
18.3. Kernun Clear Web DataBase
18.4. Using External Web Filter
19. HTTPS Inspection
19.1. Certificates
19.2. HTTPS inspection ACL flow
19.3. Transparent mode
19.4. Non-transparent mode
19.5. SNI inspection in HTTPS
19.6. TLS termination
20. Intrusion Detection/Prevention System
20.1. Update of Rules
21. Traffic Shaping
22. Virtual Private Networks — OpenVPN
22.1. Remote Access Server
22.2. Network to Network
22.3. Accessing the virtual network
22.4. Logs
23. Virtual Private Networks — IPsec
23.1. IPsec Configuration
24. High Availability Clusters
24.1. Controling multiple systems from GUI
24.2. Sharing the configuration among systems
25. Kernun Branch Access
25.1. Description and Plug-in
25.2. Installation
25.3. Configuration
25.4. Diagnostics and Troubleshooting
26. IPv6
27. Honeypot

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”.

1. Packet Filter

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].

1.1. Packet Flow

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:

  1. State engine

  2. Traffic normalization engine

  3. Traffic shaping / queuing engine

  4. Network address translation engine

  5. 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.

Important

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.

1.2. Packet Filtering

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.

Important

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”.

Note

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.

Important

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”.

Figure 5.1. A simple blocking packet filter rule

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.

Figure 5.2. A blocking packet filter rule with return

A blocking packet filter rule with return

Tip

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”.

Figure 5.3. Option block-policy instead of return in rule

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.

Figure 5.4. More specific rule must come first

More specific rule must come first

1.3. Antispoofing Using Packet Filter

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].

Figure 5.5. Simple antispoofing rule

Simple antispoofing rule

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”.

Figure 5.6. Antispoofing rule including routes

Antispoofing rule including routes

Note

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.

1.4. Selective Packet Forwarding

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.

Note

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.

Important

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.

Figure 5.7. Selective packet forwarding rule

Selective packet forwarding rule

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:

    1. Incoming packets on interface INT going from 192.168.1.20 to 172.16.31.50 (the basic rule for iface ^system.INT in).

    2. 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).

    3. 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).

    4. Incoming datagrams on interface DMZ traveling from 172.16.31.50 to 192.168.1.20 (the symmetric rule for iface ^system.DMZ out).

Important

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.

1.5. Network Address Translation

There are three types of NAT rules: mapping rules (nat-acl), redirection rules (rdr-acl) and bidirectional NAT rules (binat-acl).

1.5.1. Mapping Rules

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).

Figure 5.8. Mapping NAT rule

Mapping NAT rule

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.

1.5.2. Redirection 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.

Figure 5.9. Redirection NAT rule

Redirection NAT rule

1.5.3. Bidirectional Rules

Bidirectional NAT rules are not yet fully supported by the CML language. The binat-acl section accepts only raw specifications of rules, in accordance with the pf.conf(5) manual page.

1.6. Packet Forwarding along with NAT

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

Forwarding of ICMP Packets over NAT

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.

1.7. Defending against DoS/DDoS Attacks

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 table. If 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)

1.8. Honeypot

...

2. System Configuration

2.1. User Accounts

Figure 5.11. User account configuration

User account configuration

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.

2.2. Network Interfaces

Figure 5.12. Network Interfaces

Network Interfaces

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.

2.3. Static Routes

Figure 5.13. Static Routes

Static Routes

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.

2.4. Dynamic IP routing with BIRD

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.

Figure 5.14. BIRD dynamic routing

BIRD dynamic routing

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 systemroutesstatic.

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

2.5. File /etc/rc.conf

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.

Figure 5.15. rc.conf configuration

rc.conf configuration

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 ...".

2.6. Kernel Parameters in /etc/sysctl.conf

Figure 5.16. sysctl.conf configuration

sysctl.conf configuration

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 variables items in the syctl section. Each variable sets one kernel setting. For example, variable net.inet.ip.forwarding "1" turns on IP forwarding.

2.7. Configuration of the cron Daemon

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.

Figure 5.17. crontab configuration

crontab configuration

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.

3. Caching Name Server

Figure 5.18. Caching Name Server configuration

Caching Name Server configuration

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.

4. DNS and DHCP Services

4.1. DNS Server for the Local Zone

In this scenario, named listens for DNS queries on the internal interface and queries dns-proxy, which provides the response.

Figure 5.19. DNS Server - Proxy configuration

DNS Server - Proxy configuration

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.

Figure 5.20. DNS Server - BIND configuration

DNS Server - BIND configuration

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.

4.2. DHCP Server for the Local Network

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.

Figure 5.21. DHCP configuration

DHCP configuration

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.

5. Time Synchronization with NTP

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.

Note

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.

Figure 5.22. Minimum NTP server configuration

Minimum NTP server 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”.

Figure 5.23. Peer for NTP server

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:

  1. Type—number 1 for local on-board clock.

  2. Unit—number 0 as the first (the only) unit of local on-board clock.

  3. 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.

Figure 5.24. On-board clock with NTP server

On-board clock with NTP server

The resulting configuration file is available among Kernun UTM samples under the name ntp.cml in /usr/local/kernun/conf/samples/cml.

6. Monitoring of Kernun UTM Operation

6.1. Logging Configuration

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”.

Figure 5.25. Log of an HTTP request

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.

6.2. Log Rotation

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.

6.3. Monitoring of Active Sessions

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”.

6.4. Proxy Statistics Generation

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 File | Statistics 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.

Figure 5.26. Statistics browser window

Statistics browser window

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.

Figure 5.27. Configuration of statistics

Configuration of statistics

6.5. Monitoring of System Parameters

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.

7. Networking in Proxies

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.

7.1. Transparent Proxies

7.1.1. Transparency for Clients

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”.

Figure 5.28. HTTP Proxy listening both in transparent and non-transparent mode

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

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 1) and in the non-transparent mode (rows marked 2). 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 3), and the connection from Kernun UTM's external IP address to the server (row marked 4).

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 5) and the connection from Kernun UTM to the server (row marked 6).

Figure 5.30. Sockstat tab showing the list of all sockets

Sockstat tab showing the list of all sockets

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).

Tracking transparent and non-transparent connections in the http-proxy log (the log was filtered, in order to save space).

7.1.2. Transparency for Servers

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 address denotes that the given 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.

Figure 5.32. Transparency for servers (source-address client)

Transparency for servers (source-address client)

7.2. A Proxy and a Server on the Same Port

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.

Figure 5.33. A port shared by two applications

A port shared by two applications

7.3. Listening on a port range

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 ”.

Figure 5.34. The sip-proxy configured to listen transparently on a port range 5060-5062

The sip-proxy configured to listen transparently on a port range 5060-5062


Warning

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).

8. H.323 Proxies

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).

9. SIP Proxy

Figure 5.35. SIP Proxy

SIP Proxy

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.

10. SQLNet 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.

Figure 5.36. SQL*Net Proxy

SQL*Net Proxy

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.

11. UDP 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.

Figure 5.37. UDP proxy

UDP proxy

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.

12. Cooperation of HTTP and FTP Proxies

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.

Figure 5.38. Cooperation of HTTP and FTP

Cooperation of HTTP and FTP

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.

13. Secure Communication Using SSL/TLS

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.

Figure 5.39. SSL/TLS security configuration

SSL/TLS security configuration

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.

14. User Authentication

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.

14.1. Authentication Methods

Figure 5.40. Authentication methods

Authentication methods

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.

None

No user authentication is performed.

Password file

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).

RADIUS

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.

LDAP

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.

Kerberos

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).

NTLM

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.

Note

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.

14.2. Authentication in FTP Proxy

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”.

Figure 5.41. Log of authentication in FTP proxy

Log of authentication in FTP proxy

14.3. Basic Authentication in HTTP 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.42. Proxy authentication dialog in a Web browser

Proxy authentication dialog in a Web browser

Figure 5.43. User authentication configuration in the HTTP proxy

User authentication configuration in the HTTP proxy

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.

Figure 5.44. Log of user authentication in the HTTP proxy

Log of user authentication in the HTTP proxy

Important

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.

14.4. Kerberos Authentication in 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.

Warning

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
    

Important

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 ADUser, and the corresponding password in place of ldap-password. 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 active-directory, which also specifies the domain name.

Important

The Active Directory domain name must be written using UPPERCASE LETTERS in the configuration.

Warning

A user's primary group name (usually Domain Users) is neither logged nor matched by request-acl.user.group.

Figure 5.45. Kerberos authentication — section system

Kerberos authentication — section system

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.

Figure 5.46. Kerberos authentication — section http-proxy

Kerberos authentication — section http-proxy

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.

Important

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.

14.4.1. Initialization by msktutil

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 user in the Active Directory with 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 ADC is the address of the domain controller, and D1, D2, ... are components of the Active Directory domain name (e.g., for domain example.com, we use dc=example,dc=com). The computer account name COMPUTER will be the value of --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 "computername$". 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 --dont-expire-password of msktutil.

Important

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 keytab_file to the msktutil command line. The custom keytab location must be configured as a 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.

14.4.2. Initialization by Generating a Keytab Manually

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:

  1. 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).

  2. Generate the keytab using the command line on the domain controller:

    C:\> ktpass /out KEYTAB /princ HTTP/PROXY@AD_DOMAIN
    /mapuser USER@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 PASSWD instead of /para *.

  3. Copy the keytab to the Kernun system or to the computer running Kernun GUI.

  4. 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.

  5. 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

Note

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.

14.5. Kerberos Authentication in Transparent HTTP Proxy

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.

Figure 5.47. Transparent Kerberos authentication — session ACLs

Transparent Kerberos authentication — session ACLs

Figure 5.48. Transparent Kerberos authentication — request ACLs

Transparent Kerberos authentication — request ACLs

Important

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.

Important

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.

14.6. NTLM Authentication in HTTP Proxy

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.

Important

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.

Important

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 ADUser, and the corresponding password in place of ldap-password. 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 active-directory, which also specifies the domain name.

Figure 5.49. NTLM authentication — section system

NTLM authentication — section system

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.

Figure 5.50. NTLM authentication — section http-proxy

NTLM authentication — section http-proxy

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 user in the Active Directory with 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.

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).

Tip

The preferred authentication method in Active Directory environment is Kerberos, see Section 14.4, “Kerberos Authentication in HTTP Proxy”.

14.7. HTTP Authentication 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.

Figure 5.51. Configuration of the HTTP authentication proxy

Configuration of the HTTP authentication proxy

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.

Warning

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.

Figure 5.52. The user authentication dialog of the HTTP authentication proxy

The user authentication dialog of the HTTP authentication proxy

Figure 5.53. The logout confirmation message of the HTTP authentication proxy

The logout confirmation message of the HTTP authentication proxy

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 Submit. 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).

Important

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.

14.8. Out of Band Authentication

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.

Note

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. On the other hand, one user can be authenticated on many machines simultaneously.

Figure 5.54. Configuration of the out-of-band authentication

Configuration of the out-of-band authentication

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.

Figure 5.55. Login to the OOB authentication server

Login to the OOB authentication server

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.

15. Antivirus Checking of Data

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.

15.1. Connecting with Dr.WEB

The Dr.WEB 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 Dr.WEB:

  • drweb-net: Files to be checked by the antivirus are sent to the antivirus via the TCP connection.

  • drweb-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).

    Note

    Special attention must be paid if the particular proxy that uses the antivirus runs in the chroot environment. Since the files are stored within the chroot environment, they are in fact created in a subdirectory of the directory specified as chroot-dir. You can either run the antivirus program within the same chroot environment, or you can create a symlink from comm-dir (e.g., /usr/local/kernun/root/data/tmp/antivirus) with a target out of the chroot environment (e.g., /data/tmp/antivirus). The easiest way, however, is to use drweb-net instead of drweb-file.

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 Dr.WEB listens on localhost's port 3000). 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.

Figure 5.56. Configuration of the connection to the antivirus program

Configuration of the connection to the antivirus program

We will reference the DRWEB section in proxies that will use the antivirus program.

Note

We recommend to increase the values SocketTimeout (e.g., to 3600) and FileTimeout (e.g., to 900) of the Dr.WEB configuration, as we experienced problems with the default values when scanning big files.

15.2. Connecting with ClamAV

The ClamAV antivirus configuration[36] is very similar to that of Dr.WEB (see Section 15.1, “Connecting with Dr.WEB”). The only difference is that clamav-file is used instead of drweb-file and clamav-net instead of drweb-net.

15.3. Connecting via ICAP protocol

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.

Figure 5.57. Configuration of the connection to the antivirus program via ICAP

Configuration of the connection to the antivirus program via ICAP

15.4. Antivirus Results

There are five possible results of a check of content by the antivirus:

Free

The antivirus has scanned the data and has not found any virus.

Found

At least one virus has been found.

Skipped

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.

Unknown

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.

Error

The proxy cannot communicate with the antivirus. This is usually caused by the antivirus not running or by misconfigured antivirus connection in the proxy.

15.5. Antivirus in Proxies

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.

Figure 5.58. Use of antivirus in the FTP and HTTP proxies

Use of antivirus in the FTP and HTTP proxies

15.6. SMTP Proxy: Discarding Infected Mails

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.

Figure 5.59. Discarding infected messages in the SMTP proxy

Discarding infected messages in the SMTP proxy

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.

15.7. SMTP Proxy: Replacing Infected Documents

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[37].

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”

Figure 5.60. Replacing infected documents in the SMTP proxy

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.

15.8. Antivirus in POP3 and IMAP4 Proxies

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”

Figure 5.61. Replacing infected documents in the POP3 proxy

Replacing infected documents in the POP3 proxy

Figure 5.62. Replacing infected documents in the IMAP4 proxy

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)[38].

16. Antispam Processing of E-mail

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.

16.1. Antispam Engine

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[39] in the mail-acl section of the spam-checked proxy.

16.1.1. Antispam with POP3

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.

Tip

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”.

Figure 5.63. Antispam protection for POP3 proxy

Antispam protection for POP3 proxy


16.1.2. Antispam with IMAP4

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.

Figure 5.64. Antispam protection for IMAP4 proxy

Antispam protection for IMAP4 proxy


16.1.3. Antispam with SMTP

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”.

Figure 5.65. Antispam protection for SMTP proxy

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.

16.2. White-, Grey-, and Blacklists

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.

Figure 5.66. White- and black-listing for SMTP proxy

White- and black-listing for SMTP proxy

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.

Figure 5.67. Grey-listing for SMTP proxy

Grey-listing for SMTP proxy

17. Content Processing

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.

17.1. Content Type Detection

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-acls.

The following content-type detection methods are available:

content-type

(Original Content-Type) — the proxy uses the type declared by the document originator in the Content-Type header;

extension

(File Name Extension Mapping) — the proxy tries to guess the MIME type from the name of the document (if specified);

magic

(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).

Note

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.

Figure 5.68. Content Type detection configuration for HTTP proxy

Content Type detection configuration for HTTP proxy

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.

17.2. HTML Filtering

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'"[40].

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”.

Figure 5.69. HTML filter example

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.

17.3. MIME Processing

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.

Figure 5.70. Mail filter example in use with IMAP4, POP3 and SMTP proxies

Mail filter example in use with IMAP4, POP3 and SMTP proxies


For more information on MIME filtration, see the mod-mail-doc(5) manual page.

18. Filtering HTTP Requests by URI

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.

18.1. URL Matching and Rewriting

Figure 5.71. Request URI matching and rewriting

Request URI matching and rewriting

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

Log of URI matching and rewriting

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/.

18.2. Blacklists in HTTP Proxy

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.

Figure 5.73. A blacklist in the HTTP proxy

A blacklist in the HTTP proxy

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.

Note

If a proxy runs in chroot, the path blacklist-db will be interpreted in the context of the chroot directory.

Figure 5.74. A log of blacklist usage in the HTTP proxy

A log of blacklist usage in the HTTP proxy

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.

18.3. Kernun Clear Web DataBase

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.

18.3.1. Clear Web DataBase in HTTP Proxy

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.

Figure 5.75. Kernun Clear Web DataBase in the HTTP proxy

Kernun Clear Web DataBase in the HTTP proxy

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.

18.3.2. Internal Servers in the Clear Web DataBase

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.

18.3.3. Updating the Clear Web DataBase

The Clear Web DataBase file location in controlled by clear-web-db.db, which defaults to /data/var/clear-web-db if not set. The database file is copied (or hardlinked, if possible) automatically to any chroot directories by the database update script and when the configuration is applied.

Although it is possible to update the Clear Web DataBase data manually by copying an updated clear-web.db file to the database directory, it is recommended to use the provided update script clear-web-db-update.sh for this purpose. It downloads the most appropriate full database and/or applies any incremental updates to get the most recent version of the database, minimizing the amount of downloaded data. To use this feature, you need to have valid download credentials. These are configured by clear-web-db.credentials. If not set, the serial number from the license file is used as both the username and the password.

The Clear Web DataBase data update script can be executed either manually by running clear-web-db-update.sh from the root console (Kernun console in the GUI), or automatically by cron in periodic intervals. Periodic updates are enabled by placing the clear-web-db (usually empty) section in the system configuration.

18.3.4. Automatic Categorization of Web Servers

If no record is found for a requested URL in the Clear Web DataBase, the “unknown” result is reported and matched in ACLs. A valid list of categories will be returned for repeated requests to the same URL only after the server becomes a part of the Clear Web DataBase downloaded in some future update. As an option, there is a faster way how to obtain categories for servers not yet known. It is possible to enable the cwcatd daemon that performs automatic local categorization of web pages.

If categories for a requested URL are not found in the Clear Web DataBase, the URL is appended to a queue that is processed by daemon cwcatd. The daemon reads uncategorized URLs from the queue. For each URL, it tries to download the referenced web page. The downloaded page is passed to an automatic categorizer, which tries to assign categories according to heuristics applied to the page content. If it succeeds, the result is stored in a local database. Future requests to a locally categorized server will get categories assigned according to the local database. If categories of the server appear in the downloaded Clear Web database in its periodic update, the result of the automatic local categorization will not be used any more.

Categories discovered automatically by the cwcatd daemon are not as correct and reliable as the contents of the Clear Web DataBase maintained by experienced human operators. But on the other hand, results of the automatic categorization are available almost immediately after the access to a web page with unknown categories.

Automatic categorization of web servers is enabled by adding subsection local-db to the configuration section clear-web-db. It instructs the http-proxy and the icap-server to enqueue URLs with unknown categories for