ICAP mode configuration file

The ICAP mode configuration file, kavicapd.xml, consists of several sections that specify settings for the kavicapd service and KAV SDK.

Preparing the ICAP mode configuration file

The Kaspersky Scan Engine distribution kit contains a %distr_kit%/etc/kavicapd.xml configuration file.

After installing Kaspersky Scan Engine, you can copy kavicapd.xml to your preferred location:

• If you copy kavicapd.xml to the /etc/ directory, Kaspersky Scan Engine automatically finds and parses this file.
• If you copy kavicapd.xml to a different location, you need to set the path to this location when you start Kaspersky Scan Engine:
  • If you want to use the init script to start Kaspersky Scan Engine, see section "Running Kaspersky Scan Engine in ICAP mode with the init script".
  • If you want to start Kaspersky Scan Engine from command line manually, see section "Running Kaspersky Scan Engine in ICAP mode manually".

Parameters of the ICAP mode configuration file

Following are the sections of the ICAP mode configuration file, kavicapd.xml. An example configuration file is at the end.

Some sections of the configuration file are optional. However, if a section exists in the configuration file, all of its child elements must be present. Elements must not be empty, unless stated otherwise.

SDKSettings

The following parameters specify KAV SDK settings.

• ScannersCount—Specifies the number of scanning processes. You can have up to 256 scanning processes.

  The default value is 16.

• ThreadsCount—Specifies the total number of scanning threads in all processes. You can have up to 256 scanning threads.

  The default value is 16.

• QueueLen—Specifies the length of the scan task queue.

  The default value is 1024.

• ScanTimeout—Specifies the scanning timeout, in milliseconds (ms). If the value of this parameter is 0, the timeout is disabled.

  The default value is 10000 (10 seconds).

• LicensePath—Specifies an absolute path to a directory where the application ID file, licensing file, and key file are stored.

  Kaspersky Scan Engine looks for these files in the following directories:

  • The directory specified in LicensePath.
  • The directory that contains the kavicapd executable file.
  • The %service_dir%/ppl directory.

  The default value is /opt/kaspersky/ScanEngine/bin.

• BasesPath—Specifies an absolute path to a directory where the anti-virus database is located.

  The default value is /opt/kaspersky/ScanEngine/bin/bases.

• TempPath—Specifies an absolute path to a directory where the files created at runtime are stored.

  The default value is /tmp/kavicapd.

  Do not delete any files from this directory.

• DiskUsageLimit—Specifies the maximum amount of disk space (in kilobytes) that can be allocated for unpacking a packed object.

  Limiting disk space allocated for an unpacked object helps protect the server from zip bombs (malicious archive files).

  If the value of this parameter is 0, the zip bomb protection is disabled.

  The default value is 102400.

• ScanningMode specifies a file scanning mode.

  A scanning mode is defined by a combination of flags separated by pipes (|).

  Possible values:

  • KAV_O_M_PACKED

    Scan compressed executable files.

  • KAV_O_M_ARCHIVED

    Scan archived files.

  • KAV_O_M_MAILBASES

    Scan files that contain email databases.

  • KAV_O_M_MAILPLAIN

    Scan email messages.

  • KAV_O_M_HEURISTIC_LEVEL_SHALLOW

    Set the scanning level of the advanced heuristic code analyzer to shallow (the Low level in the graphical user interface).

  • KAV_O_M_HEURISTIC_LEVEL_MEDIUM

    Set the scanning level of the advanced heuristic code analyzer to medium (the Medium level in the graphical user interface).

  • KAV_O_M_HEURISTIC_LEVEL_DETAIL

    Set the scanning level of the advanced heuristic code analyzer to detail (the High level in the graphical user interface).

  • KAV_O_M_MSOFFICE_MACRO

    Notify the user if a Microsoft Office document file contains a macro.

  • KAV_O_M_PHISHING

    Enable Phishing protection.

  The default value is KAV_O_M_PACKED | KAV_O_M_ARCHIVED | KAV_O_M_MAILPLAIN | KAV_O_M_MAILBASES | KAV_O_M_HEURISTIC_LEVEL_SHALLOW.

• LicensingMode—Specifies the licensing mode used in Kaspersky Scan Engine.

  Possible values:

  • 1—Offline licensing mode
  • 2—Online licensing mode

  The default value is 1.

KSNSettings

The following parameters specify Kaspersky Security Network (KSN) settings.

This is an optional section. If this section is absent from the configuration file, KSN is not used.

Note that by using KSN you agree to transfer data described in the About data provision.txt file to Kaspersky Lab. For more information about the procedure of data provisioning, see section "About data provisioning".

• UseKSN—A Boolean value that defines whether KSN is enabled.

  If the value of this parameter is 1, KSN is enabled. It also automatically enables the KAV_O_M_COMPOSITE_SCAN_KSN flag. If the value of this parameter is 0, KSN is disabled.

  The default value is 0.

• ObjectCheckOnDemandTimeoutMs—Specifies the KSN scanning timeout, in milliseconds (ms).

  This value cannot be 0.

  The default value is 10000 (10 seconds).

• CacheSizeKb—Specifies the maximum size, in kilobytes (KB), of the KSN status cache.

  This cache is used by Kaspersky Scan Engine to store scan results obtained from KSN.

  The default value is 30720.

ProxySettings

The following parameters specify proxy server settings for Kaspersky Scan Engine. Kaspersky Scan Engine uses these settings when it connects to the Internet.

This is an optional section. If this section is absent from the configuration file, Kaspersky Scan Engine does not use a proxy server when connecting to the Internet.

• UseProxy—A Boolean value that defines whether Kaspersky Scan Engine uses a proxy server when connecting to the Internet.

  If the value of this parameter is 1, Kaspersky Scan Engine uses a proxy server. If the value of this parameter is 0, Kaspersky Scan Engine does not use a proxy server.

  The default value is 0.

• Host—Specifies the proxy server IP address (IPv4 or IPv6) or a domain name.

  If a proxy server is used, this parameter is mandatory.

  Do not specify the protocol (http:// or https://) in this parameter.

• Port—Specifies the port number of the proxy server.

  The default value is 3128.

• User—Specifies the encrypted user name that is used for authenticating on a proxy server. The user name is encrypted by the kav_encrypt utility.

  If a proxy server is used, this parameter is mandatory.

  If the User parameter and the Pass parameter are empty, an anonymous proxy server is used.

• Pass—Specifies the encrypted password used for authenticating on a proxy server. The password is encrypted by the kav_encrypt utility.

  If this element and the User element are empty, an anonymous proxy server is used.

UpdateSettings

The following parameters specify update settings for Kaspersky Scan Engine.

This is an optional section. If this section is absent from the configuration file, updating is disabled.

• DisableBackup—A Boolean value that defines whether anti-virus database backup is enabled.

  If the value of this parameter is 0, anti-virus database backup is enabled. If the value of this parameter is 1, anti-virus database backup is disabled.

  The default value is 0.

• UpdatePeriodMinutes—Specifies the interval between automatic updates (in minutes).

  The maximum value is 44640.

  If this parameter is 0, Kaspersky Scan Engine does not perform automatic updates.

  The default value is 30.

• UseOnlyCustomSources—Specifies whether Kaspersky Lab update servers are used as a source of updates.

  If the value of this parameter is 1, only custom update sources are used. If the value of this parameter is 0, Kaspersky Lab update servers are used along with custom update sources.

  The default value is 0.

• UpdateSources—Contains custom update sources.
  • Source specifies a custom update source.
• USRSignalAction—Specifies an action that must be performed on receiving a signal specified in the USRSignalToHandle parameter.

  Possible values:

  • reload

    Reloads the database without updating it. It is assumed that the files in the database directory are already up to date and must be reloaded.

  • update

    Updates and reloads the database.

  The default value is update.

• USRSignalToHandle—Specifies the signal that must be received to update or reload the database (this action is specified in the USRSignalAction parameter).

  Possible values:

  • USR1

    Only the SIGUSR1 signal must be handled.

  • USR2

    Only the SIGUSR2 signal must be handled.

  • all

    Both the SIGUSR1 and SIGUSR2 signals must be handled.

  • None

    Signals must not be handled (database update is performed according to a pre-defined schedule).

ICAPSettings

The following parameters specify Kaspersky Scan Engine settings.

• Port—Specifies the port number of Kaspersky Scan Engine.

  The default value is 1344.

• MaxIcapSessionsCount—Specifies the maximum number of simultaneous connections to Kaspersky Scan Engine.
• RAMUsageLimit—Specifies the maximum amount of system memory, in kilobytes (KB) that can be allocated by Kaspersky Scan Engine.

  This measure prevents the operating system from running out of memory. Excessive use of system memory (in this case, RAM) can occur when Kaspersky Scan Engine scans large files or receives a lot of simultaneous scan requests. When the RAMUsageLimit limit is reached, Kaspersky Scan Engine stops processing the object that caused excessive consumption of memory.

  Set the value of RAMUsageLimit as high as possible, but keep in mind that you have to leave enough system memory for the proper functioning of Kaspersky Scan Engine. The anti-virus database and libraries used by Kaspersky Scan Engine occupy about 300 megabytes (MB)—and this amount doubles during reloading of the database. Kaspersky Scan Engine also requires memory resources for all of its components.

  Do not set the value of RAMUsageLimit lower than 7 MB. This is the minimum amount of system memory required to ensure the proper functioning of Kaspersky Scan Engine.

  If the value of this parameter is 0, the amount of system memory that can be allocated by Kaspersky Scan Engine is not limited.

  The default value is 0.

  Note that if the value of this parameter is set to 0, the operating system may run out of memory. If Kaspersky Scan Engine uses too much system memory, the operating system may stop the service.

• Exclusions

  Specifies the rules for the preview request mode (REQMOD). This feature enables the ICAP client to send preview requests to the ICAP plugin, which then skips scanning of objects that are not considered malicious.

  Possible parameters:

  • ContentSize

    The exclusion rule for the object size, in kilobytes (KB), that is specified in the Content-Length field of the HTTP header. If the Content-Length value is greater than or equal to the ContentSize value, the ICAP plugin does not scan this object. You can set this parameter only once.

    This parameter may be absent if you explicitly omitted it.

  • ContentType

    The exclusion rule for the object type that is specified in the Content-Type field. If the Content-Type field contains the value, which is specified in the ContentType element field, the ICAP plugin does not scan this object. You can set this parameter one or more times. The ICAP plugin will check all of these parameters.

    This parameter may be absent if you explicitly omitted it.

  • RequestURL

    The exclusion rule for sending the request to a URL. The URL is contained in the Host field (from the HTTP header) and in the URI field (from the HTTP starting line). If the RequestURL element contains the requested URL, the ICAP plugin does not scan the object. Before comparing the requested URL with the rule value from the RequestURL field, the ICAP plugin applies normalizing rules to this URL.

    The RequestURL parameter may contain masks.

    You can specify the asterisk (*) wildcard character from the third level of the domain and above. For example, *.domain.com: this value includes all subdomains of this domain. The asterisk (*) wildcard character can be used as a substitute for any sequence of characters.

    On the URI field, you can specify the asterisk (*) and question mark (?) wildcard characters, which can be used to substitute for any sequence of characters, or a single character, respectively. For example, domain.com/test/page=*: this value includes all pages that contain the /test/page= path (such as domain.com/test/page=123).

    You can set this parameter one or more times. The ICAP plugin will check all of these parameters.

    This parameter may be absent if you explicitly omitted it.

  If the object to scan complies with at least one of the rules, the ICAP plugin returns the code 204, regardless of the value that the Allow204 parameter of the kavicapd.xml file contains. If the object to scan does not comply with any of the rules, the ICAP plugin returns error code 100 and then waits for the ICAP client to send this object.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• ScanMaxFileSize—Specifies the maximum size (in kilobytes) of a file that can be scanned by Kaspersky Scan Engine.

  If the value of this parameter is 0, Kaspersky Scan Engine will scan files of any size. If the ContenSize exclusion rule is specified, the value of the ScanMaxFileSize parameter is equal to the value of this rule.

  The default value is 0.

• Allow204—A Boolean value that defines whether Kaspersky Scan Engine sends a 204 No Content HTTP status code instead of unchanged data to the proxy server.

  If the value of this parameter is 1, Kaspersky Scan Engine returns a 204 No Content HTTP status code instead of unchanged data. If the value of this parameter is 0, Kaspersky Scan Engine returns unchanged data.

• ScanInReqMode—Specifies the types of content that Kaspersky Scan Engine must scan in request modification (REQMOD) mode.

  This is an optional element. If this element is absent from the configuration file, the All value is used.

  Possible values:

  • Content

    Only scan the HTTP message body.

  • Url

    Only scan the requested URL.

  • All

    Scan the HTTP message body and the requested URL.

  • Empty value

    Do not scan HTTP messages in request modification (REQMOD) mode.

  The default value is All.

• ScanInRespMode—Specifies the types of content that Kaspersky Scan Engine must scan in response modification (RESPMOD) mode.

  This is an optional element. If this element is absent from the configuration file, the All value is used.

  Possible values:

  • Content

    Only scan the HTTP message body.

  • Url

    Only scan the requested URL.

  • All

    Scan the HTTP message body and the requested URL.

  • Empty value

    Do not scan HTTP messages in response modification (RESPMOD) mode.

  The default value is All.

• RulesFilePath—Specifies an absolute path to a file that contains service action rules.

  The default value is /opt/kaspersky/ScanEngine/icap_data/kavicapd_gui_rules.conf.

• CmdPath—Specifies an absolute path to a directory containing scripts that can be executed when the corresponding rules are triggered.

  The default value is /opt/kaspersky/ScanEngine/icap_data/scripts.

• ResponsesPath—Specifies an absolute path to a directory containing response templates that can be executed when the corresponding rules are triggered.

  The default value is /opt/kaspersky/ScanEngine/icap_data/templates.

• HTTPClientIpICAPHeader—Specifies the name of the header field in which the IP address of the HTTP client is specified.

  This element is optional. It can have an empty value.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• HTTPUserNameICAPHeader—Specifies the name of the header field in which the name of the HTTP client is specified.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.This element is optional. It can have an empty value.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• TransferBeforeScanEnding

  Specifies Partial mode for files that are sent to the proxy server.

  This element has the following attributes:

  • Delay specifies the delay(s) between the start of receiving the object and sending the first batch of files to the proxy server.

    The range of possible values is from 1 to 3600. This element may be absent if you explicitly omitted it.

    The preset value is 10.

  • ChunkSize specifies the data rates (kilobytes per second (KB/s)) of the file that is being scanned while the scan is in progress.

    The range of possible values is from 1 to 1024. This element may be absent if you explicitly omitted it.

    The preset value is 4.

  You can specify one of two values for the element.

  Possible values:

  • 0

    The file is sent only after the scanning ends.

  • 1

    The file can be sent before the scanning ends.

  The preset value is 0.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

Structure of the configuration file

Following is an example ICAP mode configuration file.

<Configuration>   <SDKSettings> <ScannersCount>16</ScannersCount> <ThreadsCount>16</ThreadsCount> <QueueLen>1024</QueueLen> <ScanTimeout>10000</ScanTimeout> <!-- 0 = unlimited --> <LicensePath>/opt/kaspersky/ScanEngine/bin</LicensePath> <BasesPath>/opt/kaspersky/ScanEngine/bin/bases</BasesPath> <TempPath>/tmp/kavicapd</TempPath> <LicensingMode>1</LicensingMode><!-- 1 = simplified licensing mode; 2 - online licensing mode --> <DiskUsageLimit>102400</DiskUsageLimit> <!-- 0 = turn zip-bomb protection off --> <ScanningMode>KAV_O_M_PACKED | KAV_O_M_ARCHIVED | KAV_O_M_MAILPLAIN | KAV_O_M_MAILBASES | KAV_O_M_HEURISTIC_LEVEL_SHALLOW</ScanningMode> </SDKSettings>   <KSNSettings> <UseKSN>0</UseKSN> <ObjectCheckOnDemandTimeoutMs>10000</ObjectCheckOnDemandTimeoutMs> <CacheSizeKb>30720</CacheSizeKb> </KSNSettings>   <UpdateSettings> <DisableBackup>0</DisableBackup> <UpdatePeriodMinutes>30</UpdatePeriodMinutes> <!-- 0 = turn update off --> <UseOnlyCustomSources>0</UseOnlyCustomSources> <UpdateSources> <!-- <Source></Source> --> </UpdateSources> </UpdateSettings>   <ProxySettings> <UseProxy>0</UseProxy> <Host>myproxy.mycompany.com</Host> <Port>3128</Port> <User>proxyuser</User> <Pass>proxypass</Pass> </ProxySettings>   <ICAPSettings> <Port>1344</Port> <MaxIcapSessionsCount>100</MaxIcapSessionsCount> <Exclusions> <ContentSize>2048</ContentSize> <ContentType>video/mp4</ContentType> <RequestURL>example.com</RequestURL> </Exclusions> <ScanMaxFileSize>0</ScanMaxFileSize> <!-- 0 = unlimited --> <RAMUsageLimit>0</RAMUsageLimit> <!-- 0 = unlimited --> <Allow204>0</Allow204> <ScanInReqMode>All</ScanInReqMode> <ScanInRespMode>All</ScanInRespMode> <RulesFilePath>/opt/kaspersky/ScanEngine/icap_data/kavicapd_gui_rules.conf</RulesFilePath> <CmdPath>/opt/kaspersky/ScanEngine/icap_data/scripts</CmdPath> <ResponsesPath>/opt/kaspersky/ScanEngine/icap_data/templates</ResponsesPath> <HTTPClientIpICAPHeader>X-Client-IP</HTTPClientIpICAPHeader> <HTTPUserNameICAPHeader>X-Client-Username</HTTPUserNameICAPHeader> <TransferBeforeScanEnding Delay="10" ChunkSize="4">0</TransferBeforeScanEnding> </ICAPSettings>   </Configuration>

Page top