C-icap-0.2.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
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
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 path:
ldap://[username:password@]ldapserver?base?attr1,attr2?filter[{[cache=no]}]
The filter can contain the "%s" formating code which will be replaced by
the search key
Examples of supported ldap urls:
ldap://ldap.chtsanti.net?o=chtsanti?cn,uid?uid=%s
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
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
- Port
-
Format:
Port port
Description: The port number that the c-icap server uses to listen to requests.
Default: Port 1344
- 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
- ModulesDir
-
Format:
ModulesDir dir
Description: The location of modules
Default: ModulesDir @prefix@/lib/c_icap
- ServicesDir
-
Format:
ServicesDir dir
Description: The location of services
Default: ServicesDir @prefix@/lib/c_icap
- 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 @prefix@/etc/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/
acl aclname icap_resp_header{HeaderName} value1 ...
The icap response header
The values are in regex form: /avalue/
acl aclname http_req_header{HeaderName} value1 ...
The http request header
The values are in regex form: /avalue/
acl aclname http_resp_header{HeaderName} value1 ...
The http response header
The values are in regex form: /avalue/
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
Default: None set
- 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