icap-server — format of icap-server 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 icap-server 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 icap-server configuration directives:
enabling (see common(5))yes-no (see common(5))language (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))obligation (see common(5))range-op (see common(5))dbglev (see log(5))logfail-mode (see log(5))week-day (see time(5))month (see time(5))lock-type (see ipc(5))auth-method (see auth(5))user-match-mode (see auth(5))virus-status (see antivirus(5))source-address-mode (see source-address(5))transparency (see acl(5))user-auth-spec (see acl(5))doctype-ident-method (see acl(5))header-op (see acl(5))listen-on-sock (see listen-on(5))clear-web-db-category (see clear-web-db(5))clear-web-db-match-mode (see clear-web-db(5))Configuration of icap-server library component consists of following prototypes:
* icap-server name { ... }
icap-server 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 { ... }
doctype-identification { ... }
client-conn { ... }
document-root ... ;
hdr-line-len ... ;
preview ... ;
blacklist-db ... ;
max-bypass-sessions ... ;
ssl-session-cache { ... }
ldap-cache { ... }
* session-acl name { ... }
* service-acl name { ... }
* request-acl name { ... }
* doc-acl name { ... }
}
This section defines ICAP server attributes.
icap-server section is derived from
proxy section prototype.
For detail description of it, see application(5).
icap-server section:Section udpserver is not valid.
Item source-address is not valid.
At least one SESSION-ACL must be specified (proxy must be named in some SYSTEM.ACL.SERVICES).
At least one SERVICE-ACL must be specified.
At least one REQUEST-ACL must be specified.
At least one DOC-ACL must be specified.
Document root path required.
monitoring (see monitoring(5))Item aproxy-user is not valid.
Item data used as uri.
listen-on.non-transparent (see listen-on(5))Element port is optional, default: 1344.
Element proto is optional, default: tcp.
listen-on.transparent (see listen-on(5))Element port is optional, default: 1344.
Element proto is optional, default: tcp.
client-conn {
recv-bufsize ... ;
close-timeout ... ;
send-bufsize ... ;
log-limit ... ;
}
Connection from client options.
client-conn section is derived from
sock-opt section prototype.
For detail description of it, see netio(5).
client-conn section:Item conn-timeout is not valid.
Item recv-timeout is not valid.
Item send-timeout is not valid.
document-root path;Directory containing error documents and forced responses.
path (type: name of shared-dir, see common(5))hdr-line-len [bytes];Maximum (multi)line length in ICAP message headers (sets buffer size in header processing modules).
bytes (type: uint32, optional, default: 12Ki)preview disable;preview [enable] bytes;Default document preview mode and size.
If used, this setting is valid whenever no re-setting is defined in a particular SERVICE-ACL.
If not used, just the particular SERVICE-ACL setting is significant for the preview mode and size.
enabling, optional, default: enable)bytes (type: uint32)blacklist-db fname;Blacklist categorization database file.
fname (type: str)max-bypass-sessions [num];Maximum number of simultaneous Clear Web DataBase bypass sessions.
num (type: uint32, optional, default: 1000)ssl-session-cache {
capacity ... ;
dir ... ;
lock ... ;
}
ssl-session-cache section is derived from
ssl-session-cache section prototype.
For detail description of it, see ssl(5).
ldap-cache {
max-sessions ... ;
max-user ... ;
max-groups ... ;
truncate-groups ... ;
timeout ... ;
file ... ;
lock ... ;
}
Use cache for LDAP groups results.
max-sessions [val];Maximum number of simultaneously active LDAP user sessions.
val (type: uint16, optional, default: 200)MAX-SESSIONS must be nonzero.
max-user [val];Maximum length of a user name.
val (type: uint16, optional, default: 48)MAX-USER must be nonzero.
max-groups [val];Maximum space used by a list of groups for a single user.
Each group name of length L takes L+1 characters from this space.
val (type: uint16, optional, default: 1024)MAX-GROUPS must be nonzero.
truncate-groups;Too long group list handling flag.
If used, a too long list of groups is truncated.
If omitted, the user cannot authenticate if his/her list of groups does not fit to the space allocated according to MAX-GROUPS.
timeout [sec];User record expiration timeout.
sec (type: uint32, optional, default: 3600)file [path];LDAP caching file name.
path (type: str, optional, default: "/tmp/ldap-cache")lock none;lock semaphore;lock lock2 [path];lock [multilock2] [path];An alternative implemetation of locks.
lock-type, optional, default: multilock2)path (type: str, optional, default: <NULL>)If set to directory, file in that directory is created with name PREFIX.PID.XXXXXX, where PREFIX is a string defined by the proxy, PID is the proxy parent process ID and X is a random suffix. If not set, directory /tmp is assumed. Automatic generation of lock file name is strongly recommended, because each lock must have a unique name.
[End of section icap-server.ldap-cache description.]
session-acl name {
* from ... ;
* to ... ;
* time ... ;
time-period-set { ... }
deny ... ;
accept ... ;
* doctype-ident-order ... ;
rule ... ;
auth ... ;
idle-timeout ... ;
source-address ... ;
linger-time ... ;
client-keepalive ... ;
language ... ;
client-ssl ... ;
* client-cert-match ... ;
}
session-acl section is derived from
acl-1 section prototype.
For detail description of it, see acl(5).
session-acl section:Item user is not valid.
Item idle-timeout-peer is not valid.
Item plug-to is not valid.
SSL/TLS required on connection in order to match client certificates.
auth (see auth(5))Element mode is optional, default: allowed.
linger-time seconds;Read end of client connection will linger for EOF after closing the write end.
seconds (type: uint32)client-keepalive [req req] [idle idle];Parameters of client connection keep-alive.
req req (type: uint16, optional, default: 100)Max. number of requests on single connection (0 = unlimited, 1 = persistent client connections not used).
idle idle (type: uint16, optional, default: 15)Max. idle time before the first request or between requests on single connection (0 = unlimited).
language [lang];Language of responses generated by Kernun.
If omitted in SESSION-ACL, English is used.If omitted in higer layer ACLs, settings from lower layer is used.
lang (type: language, optional, default: EN)client-ssl params;Use SSL/TLS on the connection from a client.
params (type: name of ssl-params, see ssl(5))client-cert-match [subject subject] [issuer issuer];Requirements for client certificate.
subject subject (type: str-set, optional, default: *)acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *)acceptable certificate issuers
[End of section icap-server.session-acl description.]
service-acl name {
* from ... ;
* server ... ;
* user ... ;
* time ... ;
time-period-set { ... }
* session-acl ... ;
deny ... ;
accept ... ;
* doctype-ident-order ... ;
rule ... ;
* request-method ... ;
* request-uri ... ;
* request-path ... ;
* user-agent ... ;
* client-cert-match ... ;
use-antivirus ... ;
request-time ... ;
language ... ;
preview ... ;
send-opt-clearweb ... ;
auth-req ... ;
user-match ... ;
ldap-groups ... ;
max-bytes ... ;
flush ... ;
client-altq ... ;
}
The ICAP service sublevel of the second level of ACL.
This sublevel decides about particular ICAP service, i.e. types of document inspection required. It exploits data from ICAP protocol level.
service-acl section is derived from
acl-2 section prototype.
For detail description of it, see acl(5).
service-acl section:Item parent-acl used as session-acl.
request-method val;Entry condition - ICAP request method.
val (type: str-set)request-uri val;Entry condition - ICAP request URI.
ICAP URIs have form icap://[<USER>@]<HOST>[:<PORT>]<PATH>[?<QUERY>] (e.g., icap://icap.tns.cz/av-scan).
val (type: str-set)request-path val;Entry condition - ICAP URI path.
val (type: str-set)user-agent val;Entry condition - User-Agent ICAP header.
val (type: str-set)client-cert-match [subject subject] [issuer issuer];Entry condition - client certificate.
subject subject (type: str-set, optional, default: *)acceptable certificate subjects
issuer issuer (type: str-set, optional, default: *)acceptable certificate issuers
use-antivirus disable [interval interval] [chunk chunk] [limit limit];use-antivirus enable channel [interval interval] [chunk chunk] [limit limit];Antivirus usage mode.
If omitted, or disabled, no antivirus is enabled. In this case, neither any ANTIVIRUS global section can be present nor any ACL can have VIRUS item specified.
If enabled, it can be configured for passing initial part of unchecked data to the client before the antivirus check is completed. In this case, if a virus is found later, the connection to the client is broken.
enabling)channel (type: name-list of antivirus, see antivirus(5))interval interval (type: uint16, optional, default: 0)Seconds between passing blocks of unchecked data (0 = do not send unchecked data).
chunk chunk (type: uint32, optional, default: 0)Size of each block of unchecked data.
limit limit (type: uint32, optional, default: 0)Maximum size of unchecked data passed before antivirus check is completed. Remaining data will be passed only after successful checking.
request-time seconds;Limited time of single request.
seconds (type: uint32)language lang;Language of responses generated by Kernun.
If omitted in SESSION-ACL, English is used.If omitted in higer layer ACLs, settings from lower layer is used.
lang (type: language)preview disable;preview [enable] bytes;Document preview mode and size.
If used, this setting is valid for the OPTIONS request response belonging to this SERVICE-ACL.
If not used and the global setting (ICAP-SERVER level) is defined, the global setting is valid.
If no PREVIEW setting is specified on neither ICAP-SERVER nor SERVICE-ACL level, the OPTIONS response is derived by the icap-server according to services offered (document type identification by the magic library, antivirus scanning, etc.).
enabling, optional, default: enable)bytes (type: uint32)send-opt-clearweb;OPTIONS response control.
If used, the server includes clearweb categories into the response to the OPTIONS request.
auth-req realm;Send authentication request back to client.
realm (type: str)realm sent to clients
user-match [mode];ACL matching mode of authenticated usernames.
mode (type: user-match-mode, optional, default: short)ldap-groups [name];Get list of user groups by LDAP.
name (type: name of ldap-client-auth, see ldap(5), optional, default: NULL)Default LDAP connection for the case of no user domain sent by the ICAP client.
max-bytes [cout [cin]];Maximum number of transferred bytes (0 = unlimited).
cout (type: uint64, optional, default: 0)Bytes received from client.
cin (type: uint64, optional, default: 0)Bytes sent to client.
flush client;Force immediate data flushing to network.
client (type: key)Flush data to client.
client-altq altq [paltq paltq];ALTQ queues for data sent to client.
altq (type: name of pf-queue, see pf-queue(5))queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL)priority queue name (if set, used for TCP ACK without data)
[End of section icap-server.service-acl description.]
request-acl name {
* from ... ;
* server ... ;
* user ... ;
* time ... ;
time-period-set { ... }
* service-acl ... ;
deny ... ;
accept ... ;
* doctype-ident-order ... ;
rule ... ;
* request-method ... ;
* request-uri ... ;
* request-scheme ... ;
* request-path ... ;
* blacklist ... ;
* clear-web-db-match ... ;
clear-web-db-bypass { ... }
replace-response ... ;
deny-msg ... ;
language ... ;
client-altq ... ;
}
The HTTP request sublevel of the second level of ACL.
This sublevel decides about particular document inspection methods according to the encapsulated document HTTP data.
request-acl section is derived from
acl-2 section prototype.
For detail description of it, see acl(5).
request-acl section:Item parent-acl used as service-acl.
Items DENY and CLEAR-WEB-DB-BYPASS are mutually exclusive.
Item CLEAR-WEB-DB-BYPASS requires CLEAR-WEB-DB-MATCH.
Items REPLACE-RESPONSE and CLEAR-WEB-DB-BYPASS are mutually exclusive.
Item DENY-MSG requires DENY.
request-method val;Entry condition - HTTP request method.
val (type: str-set)request-uri val;Entry condition - HTTP message URI.
Encapsulated HTTP messages have URI in form <SCHEME>://<HOST>[:PORT]<PATH>[?<QUERY>] (e.g., http://www.tns.cz:80/kernun/index.html).
val (type: str-set)request-scheme val;Entry condition - HTTP message URI scheme.
If URI does not contain scheme, scheme HTTP is assumed.
val (type: str-set)request-path val;Entry condition - HTTP message URI path.
val (type: str-set)blacklist categories;Entry condition - HTTP message URI blacklist category.
If used, this ACL is selected if request URI (server and possibly initial part of path) is found in the blacklist with at least one matching category.
categories (type: str-set)clear-web-db-match [any] categories-set;clear-web-db-match all categories-list;clear-web-db-match subset categories-set;clear-web-db-match exact categories-list;Entry condition - HTTP message URI Clear Web category.
If used, this ACL is selected if the request URI is found in the Clear Web DataBase with at least one matching category.
clear-web-db-match-mode, optional, default: any)categories-set (type: clear-web-db-category-set)categories-list (type: clear-web-db-category-list)clear-web-db-bypass {
status ... ;
cookie ... ;
activation ... ;
duration ... ;
}
clear-web-db-bypass section is derived from
clear-web-db-bypass section prototype.
For detail description of it, see clear-web-db(5).
replace-response code reason mime-type path;Send a local file instead of a server response.
code (type: uint16)Status code of response.
reason (type: str)Reason phrase.
mime-type (type: str)Document Content-Type.
path (type: str)File to send (absolute, or relative to document-root).
Reply-code must be 4xx or 5xx.
deny-msg [template template] [msg];The error page returned when a request is denied by ACL. If not set, a generic "denied by security policy" page is returned, except when the denying ACL contains item CLEAR-WEB-DB-MATCH. In this case, the returned page will display the categories of the request URI that match the CLEAR-WEB-DB-MATCH item. See also http-proxy(8) for the instructions how to create custom error pages.
template template (type: str, optional, default: "")error page template file name, without the .html.LANGUAGE-CHARSET suffix, relative to the DOCUMENT-ROOT directory
msg (type: str, optional, default: "")a message inserted into the error page template
language lang;Language of responses generated by Kernun.
If omitted in SESSION-ACL, English is used.If omitted in higer layer ACLs, settings from lower layer is used.
lang (type: language)client-altq altq [paltq paltq];ALTQ queues for data sent to client.
altq (type: name of pf-queue, see pf-queue(5))queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL)priority queue name (if set, used for TCP ACK without data)
[End of section icap-server.request-acl description.]
doc-acl name {
* from ... ;
* server ... ;
* user ... ;
* time ... ;
time-period-set { ... }
* request-acl ... ;
deny ... ;
accept ... ;
rule ... ;
* content-type ... ;
* mime-type ... ;
virus-status ... ;
force-doctype-ident ... ;
html-filter ... ;
replace-response ... ;
deny-msg ... ;
client-altq ... ;
}
doc-acl section is derived from
acl-3 section prototype.
For detail description of it, see acl(5).
doc-acl section:Item parent-acl used as request-acl.
Item direction is not valid.
Item size is not valid.
Item modify-header is not valid.
Item replace is not valid.
Item DENY-MSG requires DENY.
replace-response code reason mime-type path;Send a local file instead of a server response.
code (type: uint16)Status code of response.
reason (type: str)Reason phrase.
mime-type (type: str)Document Content-Type.
path (type: str)File to send (absolute, or relative to document-root).
Reply-code must be 4xx or 5xx.
deny-msg [template template] [msg];The error page returned when a request is denied by ACL. If not set, a generic "denied by security policy" page is returned, except when the denying ACL contains item CLEAR-WEB-DB-MATCH. In this case, the returned page will display the categories of the request URI that match the CLEAR-WEB-DB-MATCH item. See also http-proxy(8) for the instructions how to create custom error pages.
template template (type: str, optional, default: "")error page template file name, without the .html.LANGUAGE-CHARSET suffix, relative to the DOCUMENT-ROOT directory
msg (type: str, optional, default: "")a message inserted into the error page template
client-altq altq [paltq paltq];ALTQ queues for data sent to client.
altq (type: name of pf-queue, see pf-queue(5))queue name
paltq paltq (type: name of pf-queue, see pf-queue(5), optional, default: NULL)priority queue name (if set, used for TCP ACK without data)
[End of section icap-server.doc-acl description.]
[End of section icap-server description.]