C-icap-0.5.x Configuration Reference

Modules/Subsystems

Configuration parameters

c-icap's core configuration

echo configuration

Description:
Simple test service
Example:
Service echo srv_echo.so

sys_logger configuration

Description:
Add support for logging access and server events to syslog server
Use "Module" configuration parameter to load this module and "Logger"
to make it default logger for the c-icap.
Example:
Module logger sys_logger.so
Logger sys_logger

bdb_tables configuration

Description:
Add support for Berkeley DB based lookup tables. The format for 
bdb path of the lookup table is:
	bdb:/path/to/bdb[{param1=val, ...}]
bdb table parameters can be one or more of the followings:
    cache-size=Size[K|M]
          The cache size to use. Default is the berkeleyDB default value.
    cache-num=num
        The number of caches to create. The cache will be split across
        num separate regions, where the region size is equal to the
        initial cache size divided by ncache.
Use the c-icap-mkbdb utility to build Berkeley DB c-icap lookup tables
Example:
Module common bdb_tables.so

dnsbl_tables configuration

Description:
Add support for dns lookup tables. Can be used to access
dns block lists. The dnsbl lookup table path definition is:
    dnsbl:domainname[{param1=val, ...}]
  dnsbl table parameters can be one or more of the followings:
       cache=no|cache_type
          The cache type to use or 'no' for no cache.
       cache-size=Size[K|M]
          The cache size in RAM
       cache-ttl=ttl
          The cache ttl to use

For example the lookup table  for accessing the black.uribl.com
dns black list is: 
    dnsbl:black.uribl.com
Example:
Module common dnsbl_tables.so

ldap_module configuration

Description:
Add LDAP support to c-icap. The user can use LDAP based lookup tables
using the following lookup table paths:
      ldap://[username:password@]ldapserver?base?attr1,attr2?filter[{[param=value, ...]}]
      ldaps://...
      ldapi://...
The filter can contain the "%s" formating code which will be replaced by
the search key.
ldap table parameters can be one or more of the followings:
     name=aName
	A unique name to use for this table
     cache=no|cache_type
	The cache type to use or no for no cache.
     cache-size=Size[K|M]
	The cache size in RAM
     cache-ttl=ttl
	The cache ttl to use
     cache-item-size=ItemSize[K|M]
	The maximum item size

Examples of supported ldap urls:
     ldap://ldap.chtsanti.net?o=chtsanti?cn,uid?uid=%s{cache=memcached}
     ldap://cn=Directory Manager:Apassword@ldap.chtsanti.net?o=chtsanti?mermberUid?(&(objectClass=posixGroup)(cn=%s))

WARNING: is not enough tested it may contain bugs!
Example:
Module common ldap_module.so

memcached configuration

Description:
  Add support for memcached c-icap cache.
Example:
  Module common memcached.so

Configuration parameters description

PidFile
Format:
PidFile pid_file
Description:
The file to store the pid of the main process of the c-icap server.
Default:
PidFile /var/run/c-icap/c-icap.pid
CommandsSocket
Format:
CommandsSocket socket_file
Description:
The path of file to use as control socket for c-icap
Default:
CommandsSocket /var/run/c-icap/c-icap.ctl
Timeout
Format:
Timeout seconds
Description:
The time in seconds after which a connection without activity
can be cancelled.
Default:
Timeout 300
MaxKeepAliveRequests
Format:
MaxKeepAliveRequests number
Description:
The maximum number of requests can be served by one connection
Set it to -1 for no limit
Default:
MaxKeepAliveRequests 100
KeepAliveTimeout
Format:
KeepAliveTimeout seconds
Description:
The maximum time in seconds waiting for a new requests before a 
connection will be closed.
If the value is set to -1, there is no timeout.
Default:
KeepAliveTimeout 600
StartServers
Format:
StartServers number
Description:
The initial number of server processes. Each server process
generates a number of threads, which serve the requests.
Default:
StartServers 3
MaxServers
Format:
MaxServers number
Description:
The maximum allowed number of server processes.
Default:
MaxServers 10
MinSpareThreads
Format:
MinSpareThreads number
Description:
If the number of the available threads is less than number,
the c-icap server starts a new child.
Default:
MinSpareThreads     10
MaxSpareThreads
Format:
MaxSpareThreads number
Description:
If the number of the available threads is more than number then 
the c-icap server kills a child.
Default:
MaxSpareThreads     20
ThreadsPerChild
Format:
 ThreadsPerChild number
Description:
The number of threads per child process.
Default:
ThreadsPerChild     10
MaxRequestsPerChild
Format:
MaxRequestsPerChild number
Description:
The maximum number of requests that a child process can serve.
After this number has been reached, process dies. The goal of this
parameter is to minimize the risk of memory leaks and increase the
stability of c-icap. It can be disabled by setting its value to 0.
Default:
MaxRequestsPerChild  0
InterProcessSharedMemScheme
Format:
InterProcessSharedMemScheme posix | mmap | sysv
Description:
The interprocess shared mem scheme to use. Available schemes:
posix Use posix shared memory (shm_open interface)
mmap  Use anonymous mmaped files as shared memory
sysv  use the sysv ipc shared memory
Default:
InterProcessSharedMemScheme posix
InterProcessLockingScheme
Format:
InterProcessSharedMemScheme file | sysv | posix
Description:
The interprocess locking scheme to use. Available schemes:
  file  Use lock file
  sysv  Use the sysv ipc semaphores
posix Use posix semaphores: Use it with caution you may experienced
        locking problems if one or more processes crashed.
Default:
InterProcessLockingScheme file
Port
Format:
Port [address:]port
Description:
The port number that the c-icap server uses to listen to requests.
Default:
None
TlsPort
Format:
TlsPort [address:]port [tls-method=method] [cert=path_to_pem_cert] [key=path_to_pem_key] [client_ca=path_to_pem_file] [ciphers=ciph1:ciph2...] [tls_options=[!]Opt1|[!]Opt2|...]
Description:
  The port number that the c-icap server uses to listen for TLS/SSL
requests. Options:
tls-method
	Set the SSL method to use. Available methods are:
	  SSLv23 TLSv1_2 TLSv1_1 TLSv1 SSLv3 SSLv2
cert
	Set the certificate to use by the icap server. The certificate
	should be in pem format.
key
	The key of the configured certificate in pem format. If none
	set then the c-icap searches for the key inside cert file.
client_ca
	File containing all CA that we accept client certs from. If it
	is set then c-icap enables client certificates verification.
cafile
	PEM file containing CA certificates to use when verifying client
	certificates. If not configured the root.pem file will be used.
capath
	Directory containing additional CA certificates to use when
	verifying client certificates.
ciphers
	Collon separated lists of the ciphers to accept. Please check
	openSSL manual for supported ciphers.
tls-options
	Sets various options:
	SSL_OP_NO_SSLv2  disable the use of SSLv2
	SSL_OP_NO_SSLv3  disable the use of SSLv3
	SSL_OP_NO_TLSv1  disable the use of TLSv1
	SSL_OP_NO_TLSv1_2 disable the use of TLSv1.2
	SSL_OP_NO_TLSv1_1 disable the use of TLSv1.1
	SSL_OP_NO_TICKET  disable the use of RFC5077 session tickets
	SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
	   When performing renegotiation as a server, always start a
	   new session.
	SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
	   Allow legacy insecure renegotiation between OpenSSL and
	   unpatched clients or servers.
	
	For more options please see the SSL_set_options documentation.
	
	By default the SSL_OP_ALL flag is set which enables all of the
	important bug workarrounds. To reset this flag use the
	"!SSL_OP_ALL" as first flag:
		tls-options=!SSL_OP_ALL:SSL_OP_NO_TICKET
	
Default:
  None
TlsPassphrase
Format:
TlsPassphrase /path/to/script
Description:
Path to the script to run to get the passphrases of TLS certificates 
keys. The c-icap will pass as arguments the IP address and port number
to the script.
Default:
No value
Example:
TlsPassphrase /use/local/c-icap/scripts/cert-passphrase.sh 
User
Format:
User username
Description:
The user owning c-icap's processes. By default, the owner is the
user who runs the program.
Default:
No value
Example:
User wwwrun
Group
Format:
Group groupname
Description:
The group of users owning c-icap's processes, which, by default
is the group of the current user.
Default:
No value
Example:
Group nogroup
ServerAdmin
Format:
ServerAdmin admin_mail
Description:
The Administrator of this server. Used when displaying information
about this server (logs, info service, etc)
Default:
No value
ServerName
Format:
ServerName aServerName
Description:
A name for this server. Used when displaying information about this
server (logs, info service, etc)
Default:
No value
TmpDir
Format:
TmpDir dir
Description:
dir is the location of temporary files.
Default:
TmpDir /var/tmp
MaxMemObject
Format:
MaxMemObject bytes
Description:
The maximum memory size in bytes taken by an object which
is processed by c-icap . If the size of an object's body is
larger than the maximum size a temporary file is used.
Default:
MaxMemObject 131072
DebugLevel
Format:
DebugLevel level
Description:
The level of debugging information to be logged.
The acceptable range of levels is between 0 and 10.
Default:
DebugLevel 1
Pipelining
Format:
Pipelining on|off
Description:
Enable or disable ICAP requests pipelining
Default:
Pipelining on
SupportBuggyClients
Format:
 
Description:
 
Default:
 
Allow204As200okZeroEncaps
Format:
Allow204As200okZeroEncaps
Description:
When used the c-icap instead of allow 204 return "200 OK" responses
with zero encapsulated entities.
Default:
No set
FakeAllow204
Format:
FakeAllow204 on|off
Description:
Support 204 responses from services preview handler to the clients
which does not support preview. Requires early responses support
from clients.
If disabled the c-icap will return 500 response in these cases
Default:
 
ModulesDir
Format:
ModulesDir dir
Description:
The location of modules
Default:
ModulesDir @PKGLIBDIR@
ServicesDir
Format:
ServicesDir dir
Description:
The location of services
Default:
ServicesDir @PKGLIBDIR@
TemplateDir
Format:
TemplateDir dir
Description:
The location of the text templates used by c-icap and its services,
categorized by language and services/modules
Default:
No value
Example:
 
TemplateDefaultLanguage
Format:
TemplateDefaultLanguage lang
Description:
Sets the default language to use for text templates
Default:
TemplateDefaultLanguage en
LoadMagicFile
Format:
LoadMagicFile path
Description:
Load a c-icap magic file. A magic file contains various 
data type definitions. Look inside default c-icap.magic file
for more informations.
It can be used more than once to use multiple magic files.
Default:
LoadMagicFile @SYSCONFDIR@/c-icap.magic
RemoteProxyUsers
Format:
RemoteProxyUsers onoff
Description:
Set it to on if you want to use username provided by the proxy server.
This is the recomended way to use users in c-icap.
If the RemoteProxyUsers is off and c-icap configured to use users or
groups the internal authentication mechanism will be used.
Default:
RemoteProxyUsers off
RemoteProxyUserHeader
Format:
RemoteProxyUserHeader Header
Description:
Used to specify the icap header used by the proxy server to send
the authenticated client username to c-icap server 
Default:
RemoteProxyUserHeader X-Authenticated-User
RemoteProxyUserHeaderEncoded
Format:
RemoteProxyUserHeaderEncoded onoff
Description:
Set it to off if the RemoteProxyUserHeader is not base64 encoded
Default:
RemoteProxyUserHeaderEncoded on
AuthMethod
Format:
AuthMethod Method Authenticator
Description:
Used to define the internal authentication mechanism to use. This
feature is not well tested and may cause problems. It is better to use
RemoteProxyUser configuration.
Method is the authentication method to use (basic, digest, etc).
Currently only basic authentication method is implemented as build in
module
Authenticator currently can only be "basic_simple_db"
It can be considered as a user/password store and can be
implemented as external module. The basic_simple_db is implemented as
build it module
Default:
No set
Example:
AuthMethod basic basic_simple_db
basic.Realm
Format:
basic.Realm ARealm
Description:
Specify the basic method realm
Default:
basic.Realm "Basic authentication"
Example:
basic.Realm "c-icap server authentication"
basic_simple_db.UsersDB
Format:
basic_simple_db.UsersDB LookupTable
Description:
Specify the lookup table where the usernames/passwords pairs 
are stored. The paswords must be unencrypted
For more information about c-icap lookup tables read c-icap server
manual page
Default:
No value
Example:
basic_simple_db.UsersDB hash:/usr/local/c-icap/etc/c-icap-users.txt
GroupSourceByGroup
Format:
GroupSourceByGroup LookupTable
Description:
Defines a lookup table where the groups of users are stored indexed
by group. It can be used more than once.
For more information about c-icap lookup tables read c-icap server
manual page
Default:
No set
Example:
GroupSourceByGroup hash:/usr/local/c-icap/etc/c-icap-groups.txt
GroupSourceByUser
Format:
GroupSourceByUser LookupTable
Description:
Defines a lookup table where the groups of users are stored indexed 
by user. It can be used more than once.
For more information about c-icap lookup tables read c-icap server
manual page
Default:
No set
Example:
GroupSourceByUser hash:/usr/local/c-icap/etc/c-icap-user-groups.txt
acl
Format:
acl name type[{param}] value1 [value2] [...]
Description:
Supported acl types are:
	acl aclname service service1 ...
	     The servicename
	acl aclname type OPTIONS|RESPMOD|REQMOD ...
	     The icap method
	acl aclname port port1 ...
	     The icap server port
	acl aclname src ip1/netmask1 ...
	     The client ip address
	acl aclname srvip ip1/netmask1 ...
	     The c-icap server ip address
	acl aclname icap_header{HeaderName} value1 ...
	     Matches the icap header HeaderName with value1 ...
	     The values are in regex form: /avalue/flags
	acl aclname icap_resp_header{HeaderName} value1 ...
	     The icap response header
	     The values are in regex form: /avalue/flags
	acl aclname http_req_header{HeaderName} value1 ...
	     The http request header
	     The values are in regex form: /avalue/flags
	acl aclname http_resp_header{HeaderName} value1 ...
	     The http response header
	     The values are in regex form: /avalue/flags
	acl aclname data_type type1 ...
	     The data type as recognized by the internal data type
	     recognizer. The types are defined in c-icap.magic file
	acl aclname auth username|* ...
	     The authenticated users. Using * instead of username means
	     all users.
	acl aclname group group1 ...
	     if the user of request belongs to given groups
	acl content_length{>|<|=} value1 ...
	     The content length of body data if the related information
	     included in http headers.
	     The parameter can take the value <, > or = to specify that
	     the acl will match if content length is less, greater or
	     equal to acl values.
	acl time value1 ....
	     It checks agains current time. The values format is:
	     [DAY[,DAY,[..]]][/][HH:MM-HH:MM]
	     The DAY can be one of the following:
		S - Sunday
		M - Monday
		T - Tuesday
		W - Wednesday
		H - Thursday
		F - Friday
		A - Saturday
	acl http_client_ip ip1[/netmask1] ...
	     The HTTP client ip address, if it is available.
	acl http_req_line value1 ...
	     The first line of HTTP request
	     The values are in regex form: /avalue/flags
	acl http_resp_line value1 ...
	     The first line of HTTP response
	     The values are in regex form: /avalue/flags
	acl http_req_url value1 ...
	     The HTTP request url without GET request arguments
	     The values are in regex form: /avalue/flags
	acl http_req_method value1 ...
	     The HTTP request method
Default:
 
icap_access
Format:
icap_access allow|deny [!]acl1 ...
Description:
Allowing or denying ICAP access based on defined access lists
Default:
None set
Example:
icap_access deny XHEAD
#Allow OPTIONS method for all:
icap_access allow localnet OPTIONS
#Require authentication for all users from local network:
icap_access allow AUTH localnet
icap_access deny all
client_access
Format:
client_access allow|deny acl1 [acl2] [...]
Description:
Allowing or denying connections on c-icap based on
defined access lists. Only the acl types src, srvip and port
can be used.
Default:
None set
Example:
client_access allow all
LogFormat
Format:
LogFormat Name Format
Description:
Name is a name for this log format.
Format is a string with embedded % format codes. % format codes 
has the following form:
    % [-] [width] [{argument}] formatcode
    if - is specified then the output is left aligned
    if width specified then the field is exactly width size
    some formatcodes support arguments given as {argument}

Format codes:
       %a:  Remote IP-Address
       %la: Local IP Address
       %lp: Local port
       %>a: Http Client IP Address. Only supported if the proxy 
       	    client supports the "X-Client-IP" header
       %<A: Http Server IP Address. Only supported if the proxy
       	    client supports the "X-Server-IP" header
       %ts: Seconds since epoch
       %tl: Local time. Supports optional strftime format argument
       %tg: GMT time. Supports optional strftime format argument
       %>ho: Modified Http request header. Supports header name
       	     as argument. If no argument given the first line returned
       %huo: Modified Http request url
       %<ho: Modified Http reply header. Supports header name
       	     as argument. If no argument given the first line returned
       %iu: Icap request url
       %im: Icap method
       %is: Icap status code
       %>ih: Icap request header. Supports header name
       	     as argument. If no argument given the first line returned
       %<ih: Icap response header. Supports header name
       	     as argument. If no argument given the first line returned
       %Ih: Http bytes received
       %Oh: Http bytes sent
       %Ib: Http body bytes received
       %Ob: Http body bytes sent
       %I: Bytes received
       %O: Bytes sent
       %bph: The first 5 bytes of the body preview data. Non 
       	     printable characters printed in hex form.
       	     Supports the number of bytes to output as argument.
       %un: Username
       %Sl: Service log string
         %Sa: Attribute value set by service. The attribute name must 
              given as argument.
Default:
None set
Example:
LogFormat myFormat "%tl, %a %im %iu %is %I %O %Ib %Ob %{10}bph" 
ServerLog
Format:
ServerLog LogFile
Description:
the file used by the build-in logger file_logger to 
store debugging information, errors and other
information about the c-icap server.
Default:
ServerLog @prefix@/var/log/server.log
AccessLog
Format:
AccessLog LogFile [LogFormat] [[!]acl1] [[!]acl2] [...]
Description:
LogFile is a file where to log access information.
LogFormat is the log format to use. If ommited c-icap uses:
 	"%tl, %la %a %im %iu %is"
Also acls can be used to select certain requests to be logged.
This directive can be used more than once to specify more than
one access log files
Default:
AccessLog @prefix@/var/log/access.log
Example:
AccessLog @prefix@/var/log/access.log MyFormat all
Logger
Format:
Logger LoggerName
Description:
Specify wich logger to use. By default uses the build in "file_logger" which
uses files for access and server logging.
Default:
Logger file_logger
Example:
Logger sys_logger
Module
Format:
Module Type ModuleFile
Description:
Load an external module/plugin to c-icap.
ModuleFile is the filename of the module. If no full path given then c-icap
searche in path defined by the ModulesDir configuration parameter.
Type is the type of the external module and can be one of the following:
- "logger" for modules implement a logger
- "common" for general purpose modules
Default:
 
Example:
Module logger sys_logger.so
Service
Format:
Service aName ServiceFile
Description:
It loads the service ServiceFile. The argument aName used 
as alias name for the service
Default:
 
Example:
Service echo_service srv_echo.so
ServiceAlias
Format:
ServiceAlias AliasName ServiceName[?param1=value1¶m2=value2...]
Description:
Used to define an alias name for a service.
Default:
 
Example:
ServiceAlias avscan srv_clamav?allow204=on&sizelimit=off&mode=simple
General configuration parameters for all services
Format:
 
Description:
PreviewSize: The preview data size to advertise to the icap client
MaxConnections: The client should not use more than MaxConnections
	for this service.
TransferPreview: The list of file extensions, seperated by commas,
	for which the client should send preview data.
TransferIgnore: The list of file extensions that should not be sent
	to the icap server
TransferComplete: The list of file extensions that should be sent
	in their entirety, without preview, to the icap server
OptionsTTL: The options ttl for the service. The "sec[s]", "min" or 
	"hour[s]" can be used to secify that the time is in seconds
	minutes or hours respectively. If no time-units given
	seconds are assumed.
Allow206 on|off: Enable/disable advertise of 206 responses.
Default:
 
sys_logger.Prefix
Format:
sys_logger.Prefix string
Description:
 string is be presented in every syslog message.
Default:
sys_logger.Prefix "C-ICAP:"
sys_logger.Facility
Format:
sys_logger.Facility daemon|user|local1|local2|local3|local4|local5|local6|local7
Description:
specifies the facility type of syslog. 
Default:
sys_logger.Facility daemon
sys_logger.access_priority
Format:
sys_logger.access_priority alert|crit|debug|emerg|err|info|notice|warning
Description:
determines  the  importance  of the access log message
Default:
sys_logger.access_priority info
sys_logger.server_priority
Format:
sys_logger.server_priority alert|crit|debug|emerg|err|info|notice|warning
Description:
determines  the  importance  of the server log message
Default:
sys_logger.server_priority crit
sys_logger.LogFormat
Format:
sys_logger.LogFormat LOGFORMAT
Description:
The log format to use. If no log format defined then 
the following will be used:
    "%la %a %im %iu %is"
Default:
None set 
Example:
Logformat BasicFormat "%la %a %im %iu %is"
sys_logger.LogFormat BasicFormat
sys_logger.access
Format:
sys_logger.access [!]acl1 ...
Description:
Allow selecting ICAP requests to be logged using acls.
By default all requests will be logged.
Default:
None set
Example:
sys_logger.access all
memcached.servers
Format:
memcached.servers hostname1 hostname2 ...
Description:
Set the memcached servers to use
Default:
memcached.servers 127.0.0.1
memcached.use_md5_keys
Format:
memcached.use_md5_keys on|off
Description:
Whether to use or not md5 hash as key when the key exceeds the
MEMCACHED_MAX_KEY (normaly 251 bytes)
Default:
memcached.use_md5_keys on