C-icap-0.5.x Configuration Reference
Modules/Subsystems
Configuration parameters
Description: Simple test service
Example: Service echo srv_echo.so
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
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
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
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
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
Example: Port 192.168.1.1:1344
Port [::1]:1346
- 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
Deprecated, please do not use.
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_SSLv3 disable the use of SSLv3
SSL_OP_NO_TLSv1 disable the use of TLSv1
SSL_OP_NO_TLSv1_3 disable the use of TLSv1.3
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 [forceUnload=off]
Description: Load an external module/plugin to c-icap.
ModuleFile is the filename of the module. If no full path given then
the c-icap uses the 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
forceUnload=off
Forces c-icap to not unload services/modules loaded as external
dynamic libraries on shutdown or reconfigure.
This option may required when the services/modules are using
c++, or they are linked with c++ libraries.
Default:
Example: Module logger sys_logger.so
- Service
-
Format:
Service aName ServiceFile [forceUnload=off]
Description: It loads the service ServiceFile. The argument aName used
as alias name for the service
forceUnload=off
Forces c-icap to not unload services/modules loaded as external
dynamic libraries on shutdown or reconfigure.
This option may required when the services/modules are using
c++, or they are linked with c++ libraries.
Default:
- 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