application — format of application component configuration
General syntax rules of Kernun Firewall configuration files are described in configuration(7). This man page describes types, sections and items specific for the application component configuration.
Repeatable sections/items are marked by
the '*' before section/item name.
Configuration directives have attributes of several value-types. For the basic types description, see configuration(7).
Enumeration is a list of words (names) representing integer values. Some enumerations accept both names and direct integer values; in this case, enumeration description contains values for every name (in parenthesis next to name). For other enumerations, using of names is obligatory.
The following enumerations are used in application configuration directives:
yes-no (see common(5))direction (see common(5))ip-version (see common(5))osi4-proto (see common(5))time-cond (see common(5))zip-mode (see common(5))dbglev (see log(5))logfail-mode (see log(5))lock-type (see ipc(5))source-address-mode (see source-address(5))doctype-ident-method (see acl(5))listen-on-sock (see listen-on(5))proc-priority (name-usage obligatory)Process priority type.
normal, realtime
Configuration of application library component consists of following prototypes:
priority ... ;
doctype-identification { ... }
graph ... ;
summary { ... }
alone-application { ... }
* clone-application name { ... }
* proxy name { ... }
priority [normal];priority realtime realtime;Process priority setting.
proc-priority, optional, default: normal)realtime (type: uint8)Realtime priority (parameter of rtprio() call).
Accepted values between 0 and 31; 0 is the highest priority.
Priority value must be between 0 and 31.
doctype-identification {
* order ... ;
mime-types ... ;
magic ... ;
}
Document type recognition attributes.
This section defines attributes and order of different methods of document type recognition methods.
order [for for] order;Default order of methods usage.
If omitted, only Content-Type defines document type.
for for (type: direction-set, optional, default: *)Document transfer direction set.
This element defines directions for which the order is specified by this item.
For some proxies, both directions can be used while for others either direction is not applicable; consult proxy man page.
order (type: doctype-ident-method-list)Methods are used in given order unless type is recognized.
For some proxies, some methods are not applicable, consult proxy man page.
Only 3 methods can be specified.
mime-types filename;EXTENSION method attributes.
filename (type: name of shared-file, see common(5))Extensions to MIME types mapping file.
magic [filename [scan-size]];MAGIC method attributes.
filename (type: name of shared-file, see common(5), optional, default: NULL)Magic numbers to MIME types mapping file.
If omitted, system default file is used.
scan-size (type: uint32, optional, default: 4096)Size of initial part of data used for type recognition.
[End of section doctype-identification description.]
graph top;top (type: uint16)summary {
top-clients ... ;
top-users ... ;
top-groups ... ;
top-servers ... ;
top-categories ... ;
top-senders ... ;
top-recipients ... ;
top-mime-types ... ;
top-qnames ... ;
top-qtypes ... ;
top-callers ... ;
top-receivers ... ;
top-sids ... ;
top-server-ports ... ;
spam-threshold ... ;
activity-report { ... }
top-src-ips ... ;
top-dst-ips ... ;
top-rules ... ;
}
General definition of graph parameters for periodic summary lists.
top-clients [top];Top clients in statistics.
top (type: uint16, optional, default: 20)top-users [top];Top users in statistics.
top (type: uint16, optional, default: 20)top-groups [top];Top groups in statistics.
top (type: uint16, optional, default: 10)top-servers [top];Top servers in statistics.
top (type: uint16, optional, default: 20)top-categories [top];Top Clear Web categories in statistics.
top (type: uint16, optional, default: 10)top-senders [top];Top mail senders in statistics.
top (type: uint16, optional, default: 20)top-recipients [top];Top mail recipients in statistics.
top (type: uint16, optional, default: 20)top-mime-types [top];Top attachment MIME types in statistics.
top (type: uint16, optional, default: 10)top-qnames [top];Top query names in statistics.
top (type: uint16, optional, default: 20)top-qtypes [top];Top query types in statistics.
top (type: uint16, optional, default: 10)top-callers [top];Top call initiators in statistics.
top (type: uint16, optional, default: 20)top-receivers [top];Top call receivers in statistics.
top (type: uint16, optional, default: 20)top-sids [top];Top SIDs (ids-agent rule identifiers) in statistics.
top (type: uint16, optional, default: 20)top-server-ports [top];Top server ports in statistics.
top (type: uint16, optional, default: 20)spam-threshold [value];Spam score threshold for a mail to be considered SPAM.
value (type: uint16, optional, default: 5000)activity-report {
server-max ... ;
}
Generate a detailed report of client/user activity.
server-max [val];The number of characters displayed from the end of a long server name in a client/user activity report. If the item has value 0, the whole server name will be displayed.
val (type: uint16, optional, default: 40)[End of section summary.activity-report description.]
top-src-ips [top];Top source IP addresses.
top (type: uint16, optional, default: 20)top-dst-ips [top];Top destination IP addresses.
top (type: uint16, optional, default: 20)top-rules [top];Top Snort rules.
top (type: uint16, optional, default: 20)[End of section summary description.]
alone-application {
phase ... ;
* tag ... ;
log-debug { ... }
log-stats { ... }
use-resolver ... ;
cfg-resolution ... ;
monitoring { ... }
stats-daily { ... }
stats-weekly { ... }
stats-monthly { ... }
nodaemon ... ;
singleproc ... ;
app-user ... ;
idle-timeout ... ;
run-block-sigalrm ... ;
}
This section defines general TNS-wide nonrepeatable application attributes.
phase [number];Application Startup Phase.
number (type: uint8, optional, default: 50)Phase number; the lower one, the earlier start.
tag value;Configuration factorization tag.
This feature allows admin to create groups of Kernun applications (specially proxies and servers) according to various aspects (belonging to one customer, applications of particular network traffic etc.).
Each application can have several tag attributes and the KAT tool can run some commands (like 'ps', 'start' atc.) for applications with or without given tag.
value (type: str)Tag must contain letters, digits, hyphens and dots, only.
log-debug {
level ... ;
mem-level ... ;
facility ... ;
file ... ;
rotate ... ;
mem-file ... ;
syslog-failure ... ;
data-limit ... ;
dump-hold-time ... ;
}
log-debug section is derived from
log section prototype.
For detail description of it, see log(5).
log-stats {
level ... ;
mem-level ... ;
facility ... ;
file ... ;
rotate ... ;
mem-file ... ;
syslog-failure ... ;
data-limit ... ;
dump-hold-time ... ;
}
log-stats section is derived from
log section prototype.
For detail description of it, see log(5).
use-resolver name;Resolver Specification.
This item defines resolver configuration used for this proxy.
name (type: name of resolver, see resolver(5))cfg-resolution [max-addrs [min-ttl [def-ttl [max-ttl [hosts-ttl [pool-dir]]]]]];Attributes for resolution of domain names in configuration.
max-addrs (type: uint8, optional, default: 10)Maximum of addresses per a single domain name.
min-ttl (type: uint32, optional, default: 10)Minimum TTL accepted, used instead of too small TTL values (e.g. 0).
def-ttl (type: uint32, optional, default: 1m)Default TTL used in case of unsuccessful DNS resolution.
max-ttl (type: uint32, optional, default: 1d)Maximum TTL accepted, used instead of large TTL values.
hosts-ttl (type: uint32, optional, default: 1d)TTL used for names in /etc/hosts.
pool-dir (type: str, optional, default: "/tmp")Directory for temporary files used to share results.
monitoring {
disabled ... ;
comm-dir ... ;
interval ... ;
user ... ;
aproxy-user ... ;
data ... ;
}
monitoring section is derived from
monitoring section prototype.
For detail description of it, see monitoring(5).
stats-daily {
}
stats-daily section is derived from
summary section prototype.
For detail description of it, see above.
stats-daily section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
stats-weekly {
}
stats-weekly section is derived from
summary section prototype.
For detail description of it, see above.
stats-weekly section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
stats-monthly {
}
stats-monthly section is derived from
summary section prototype.
For detail description of it, see above.
stats-monthly section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
nodaemon;Do not daemonize itself.
singleproc;Do not fork any child processes.
app-user [name];User to run the program as.
If the program is started by root, it changes its identity. Otherwise, the program must be started by named user.
name (type: str, optional, default: "kernun")idle-timeout [seconds];If no data is transmitted for a session within the period of specified amount of seconds, connection (TCP case) or logical connection (UDP case) is closed.
Value of 0 (zero) means 'no limitation'.
seconds (type: uint32, optional, default: 3600)run-block-sigalrm [val];Block SIGALRM while a module runs.
val (type: yes-no, optional, default: yes)[End of section alone-application description.]
clone-application name {
phase ... ;
* tag ... ;
log-debug { ... }
log-stats { ... }
use-resolver ... ;
cfg-resolution ... ;
monitoring { ... }
stats-daily { ... }
stats-weekly { ... }
stats-monthly { ... }
nodaemon ... ;
singleproc ... ;
app-user ... ;
idle-timeout ... ;
run-block-sigalrm ... ;
}
This section defines general TNS-wide repeatable application attributes.
phase [number];Application Startup Phase.
number (type: uint8, optional, default: 50)Phase number; the lower one, the earlier start.
tag value;Configuration factorization tag.
This feature allows admin to create groups of Kernun applications (specially proxies and servers) according to various aspects (belonging to one customer, applications of particular network traffic etc.).
Each application can have several tag attributes and the KAT tool can run some commands (like 'ps', 'start' atc.) for applications with or without given tag.
value (type: str)Tag must contain letters, digits, hyphens and dots, only.
log-debug {
level ... ;
mem-level ... ;
facility ... ;
file ... ;
rotate ... ;
mem-file ... ;
syslog-failure ... ;
data-limit ... ;
dump-hold-time ... ;
}
log-debug section is derived from
log section prototype.
For detail description of it, see log(5).
log-stats {
level ... ;
mem-level ... ;
facility ... ;
file ... ;
rotate ... ;
mem-file ... ;
syslog-failure ... ;
data-limit ... ;
dump-hold-time ... ;
}
log-stats section is derived from
log section prototype.
For detail description of it, see log(5).
use-resolver name;Resolver Specification.
This item defines resolver configuration used for this proxy.
name (type: name of resolver, see resolver(5))cfg-resolution [max-addrs [min-ttl [def-ttl [max-ttl [hosts-ttl [pool-dir]]]]]];Attributes for resolution of domain names in configuration.
max-addrs (type: uint8, optional, default: 10)Maximum of addresses per a single domain name.
min-ttl (type: uint32, optional, default: 10)Minimum TTL accepted, used instead of too small TTL values (e.g. 0).
def-ttl (type: uint32, optional, default: 1m)Default TTL used in case of unsuccessful DNS resolution.
max-ttl (type: uint32, optional, default: 1d)Maximum TTL accepted, used instead of large TTL values.
hosts-ttl (type: uint32, optional, default: 1d)TTL used for names in /etc/hosts.
pool-dir (type: str, optional, default: "/tmp")Directory for temporary files used to share results.
monitoring {
disabled ... ;
comm-dir ... ;
interval ... ;
user ... ;
aproxy-user ... ;
data ... ;
}
monitoring section is derived from
monitoring section prototype.
For detail description of it, see monitoring(5).
stats-daily {
}
stats-daily section is derived from
summary section prototype.
For detail description of it, see above.
stats-daily section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
stats-weekly {
}
stats-weekly section is derived from
summary section prototype.
For detail description of it, see above.
stats-weekly section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
stats-monthly {
}
stats-monthly section is derived from
summary section prototype.
For detail description of it, see above.
stats-monthly section:Item top-clients is not valid.
Item top-users is not valid.
Item top-groups is not valid.
Item top-servers is not valid.
Item top-categories is not valid.
Item top-senders is not valid.
Item top-recipients is not valid.
Item top-mime-types is not valid.
Item top-qnames is not valid.
Item top-qtypes is not valid.
Item top-callers is not valid.
Item top-receivers is not valid.
Item top-sids is not valid.
Item top-server-ports is not valid.
Item spam-threshold is not valid.
Section activity-report is not valid.
Item top-src-ips is not valid.
Item top-dst-ips is not valid.
Item top-rules is not valid.
nodaemon;Do not daemonize itself.
singleproc;Do not fork any child processes.
app-user [name];User to run the program as.
If the program is started by root, it changes its identity. Otherwise, the program must be started by named user.
name (type: str, optional, default: "kernun")idle-timeout [seconds];If no data is transmitted for a session within the period of specified amount of seconds, connection (TCP case) or logical connection (UDP case) is closed.
Value of 0 (zero) means 'no limitation'.
seconds (type: uint32, optional, default: 3600)run-block-sigalrm [val];Block SIGALRM while a module runs.
val (type: yes-no, optional, default: yes)[End of section clone-application description.]
proxy name {
phase ... ;
* tag ... ;
log-debug { ... }
log-stats { ... }
use-resolver ... ;
cfg-resolution ... ;
monitoring { ... }
stats-daily { ... }
stats-weekly { ... }
stats-monthly { ... }
nodaemon ... ;
singleproc ... ;
app-user ... ;
idle-timeout ... ;
run-block-sigalrm ... ;
listen-on { ... }
tcpserver { ... }
udpserver { ... }
source-address ... ;
doctype-identification { ... }
}
This section defines general TNS-wide proxy attributes.
proxy section is derived from
clone-application section prototype.
For detail description of it, see above.
proxy section:Addresses to listen on must be specified.
listen-on {
* non-transparent ... ;
* transparent ... ;
}
listen-on section is derived from
listen-on section prototype.
For detail description of it, see listen-on(5).
listen-on section:At least one address to listen on must be specified.
tcpserver {
queue-size ... ;
init-children ... ;
max-children ... ;
max-children-per-ip ... ;
min-idle ... ;
max-idle ... ;
parent-cycle ... ;
info-cycle ... ;
min-start-rate ... ;
max-start-rate ... ;
kill-rate ... ;
fork-wait ... ;
fork-retries ... ;
lock ... ;
alt-lock ... ;
listener ... ;
conn-rate ... ;
conn-rate-per-ip ... ;
conn-rate-table ... ;
terminate-wait ... ;
}
tcpserver section is derived from
tcpserver section prototype.
For detail description of it, see tcpserver(5).
udpserver {
max-sessions ... ;
}
udpserver section is derived from
udpserver section prototype.
For detail description of it, see udpserver(5).
source-address [client] [addr4 addr4] [addr6 addr6] cluster [cluster];source-address [client] [addr4 addr4] [addr6 addr6] [physical];source-address [client] [addr4 addr4] [addr6 addr6] no-fallback;Source address for outgoing connections to servers.
If omitted, the proper address of the proxy will be used, i.e. in the case of a cluster, the cluster address will be used.
If not specified by the SOURCE-PORT item, a generic port will be used.
The elements entered within this item will be used by the proxy until the first of them is applicable:
- The CLIENT keyword means the original client IP address is used. This mode will be succesful in all cases except mismatch of IP address families.
- The ADDR4/ADDR6 keyword-value pairs mean that the specified address is used for a connection of corresponding address family.
- The CLUSTER keyword means that one of cluster addresses will be used. By default, the main address of the bridge is used, however, any preferred alias address can be listed in the cluster list.- The PHYSICAL option means that the address of the physical interface is used instead of the cluster one.
- The DEFAULT option means the default behavior - i.e. using of the physical address.
- The NO-FALLBACK option means that if no other way of setting the address is acceptable, the session is rejected. Without this option, the system tries to find a suitable source IP address automatically.
client (type: key, optional)addr4 addr4 (type: host, optional, default: [0.0.0.0])addr6 addr6 (type: host, optional, default: [::])source-address-mode, optional, default: physical)cluster (type: host-list, optional, default: {})Address family must respect the element's address family..
doctype-identification {
* order ... ;
mime-types ... ;
magic ... ;
}
doctype-identification section is derived from
doctype-identification section prototype.
For detail description of it, see above.
[End of section proxy description.]