icap-server, test-icap — ICAP server for document inspection


icap-server [-hv] [-d dbglev] -f cfgfile

test-icap [-hv] [-d dbglev] -f cfgfile [-r] [-t test_expr]


The icap-server is a server of the Internet Content Adaptation Protocol (RFC 3507) implementing the security policy for the access control and the document inspection based on the Kernun configuration logic.

The test-icap program checks the syntax and partially the semantics of the configuration; for test expression syntax, see test-expr(5).

Startup and Configuration

The server reads its configuration and starts listening on TCP sockets (address/port couples) specified by listen-on configuration section, see listen-on(5).

Format of the configuration file is described in icap-server.cfg(5). General syntax of Kernun configuration files is explained in configuration(7).

Access Control

The icap-server uses standard Kernun access control (see access-control(7)) with four types of ACLs on three levels:

  1. session-acl (level 1) is checked once for each client connection and defines general protocol behavior, or rejecting the connection. In addition to the generic ACL conditions and actions, some icap-server-specific conditions and parameters can be set (see icap-server(5)).

  2. service-acl (level 2I) is checked once for each ICAP request received and defines the service(s) and attributes used for the request. All entry conditions of this level are related to the ICAP request line and ICAP headers. Accepting ACLs cause 2xx ICAP response codes while denying ACLs cause 4xx and 5xx codes.

  3. request-acl (level 2H) is checked once for each encapsulated (HTTP) request and/or document inspected and defines the behavior variation according to the HTTP request URI. All entry conditions of this level are related to the encapsulated HTTP request line, or client data sent by special ICAP headers X-Client-IP and X-Client-Username.

  4. doc-acl (level 3) is checked once for each encapsulated (HTTP) document inspected and defines document processing mode (e.g. document type identification, filtering, replacing etc.).

    The only exception from this rule is the case of antivirus checking with the keepalive option (see antivirus(7)). In this case the doc-acl is checked once more after the antivirus check is finished. If the doc-acl contains the virus-status item which corresponds with the final result, session continues. If the doc-acl contains the virus-status item which does not correspond with the final result, or it does not contain any virus-status ites, connection is reset.

Firewall administrator can choose any method described in auth(7) (except for NTLM) for authenticating users on the proxy.

Protocol Features

The recognized file type (see doctype-identification(7)) is returned to the client via the ICAP response header (X-Kernun-Content-Type).

If the request URI is categorized by clear-web-db, the set of categories found are sent to the client via the ICAP response header (X-Kernun-Categories).

In the case of request/document allowed by the policy and processed without any modification, the Kernun icap-server can return either the 200 response code (together with the original document) or the 204 response code (without data, if client permits it by the Allow header).

In the case of request/document refused by the policy (e.g. due to HTTP request attributes, file extension, recognized file type, virus found etc.), the ICAP response code has value 201 and either a standard or an own error web page is returned.

The Preview mode is supported. In this case, the client sends only a part of the document to the server, the server makes a decision and responds by the 100 Continue, or some error response. After the 100 Continue response, the client continues sending the rest of the document. The size of the preview block is recommended by the server to the client via the OPTIONS request response according to the services (antivirus, doctype recognition etc.) offered by corresponding service-acl. The admin can force another recommendation by the preview item.


On the ICAP layer, the server uses similar authentication methods as the http-proxy. However, the HTTP layer of authentication is more important, here. This can be applied if ICAP clients use the X-Client-IP and X-Client-Username headers. The server expects authentication being done by the ICAP client and the resulting username is told to the server. Very often, the username contains also the domain name and the server can use also this piece of information.

The Kernun authentication methods concludes also checking of group membership. For obtaining the list of groups, to which particular user belongs, a LDAP server can be used (see the service-acl.ldap-groups item). For increasing of throughput, the icap-server can store received group memberships to a cache (the single one for all potential domains). Parameters of the cache are defined in the ldap-cache section and they have the same meaning as the ones from the oob-auth section. The only exception is the timeout item defining the lifetime of a record in the cache. If the section is omitted, no caching takes place.



Print usage information.


Display version information and exit.

-d dbglev

Set debuging level to a specific number. Permitted values are 3 through to 9, 3 being the least and 9 the most verbose. See logging(7) for details. This setting is relevant only till configuration reading is finished.

-f cfgfile

Read cfgfile for configuration information.


Resolve names in configuration prior to testing.

-t test_expr

Test configuration according to given expression. Format of the test_expr is described in test-expr(5).

See Also

antivirus(5), application(5), icap-server(5), icap-server.cfg(5), listen-on(5), mod-html-filter(5), ssl(5), tcpserver(5), test-expr(5), access-control(7), configuration(7), doctype-identification(7), host-matching(7), logging(7), netio(7), resolving(7), tcpserver(7), time-matching(7), traffic-shaping(7)


This man page is a part of Kernun Firewall.
Copyright © 2000–2021 Trusted Network Solutions, a. s.
All rights reserved.