Sensor Settings > Message Sources > EtherSensor ICAP

EtherSensor ICAP service configuration is stored in the icap.xml, file located in the Microolap EtherSensor [INSTALLDIR]\config common configuration directory.

A sample icap.xml configuration file:

<?xml version="1.0" encoding="utf-8"?>
<IcapConfig version="3.0">
<SensorId>icap-01</SensorId>
<Network max_connections="4000">
<ListenAddress
address="0.0.0.0:1344"
ssl="false" />
<ListenAddress
address="0.0.0.0:1345"
ssl="true" />
</Network>
<Icap>
<XHeader
enabled="true"
name="X-Client-IP" />
<XHeader
enabled="true"
name="X-Server-IP" />
<XHeader
enabled="true"
name="X-Client-Username" />
<XHeader
enabled="true"
name="X-Subscriber-ID" />
<XHeader
enabled="true"
name="X-Authenticated-User" />
<XHeader
enabled="true"
name="X-Authenticated-Groups" />
<AlwaysOk
enabled="true" />
<Preview
enabled="false"
size="4096" />
<Allow204
enabled="true" />
<SyncMode
enabled="false" />
<RawLog
enabled="false"
path=".\raw-log" />
<RequestLog
enabled="false"
http_enabled="true"
channel="ICAP-REQUEST" />
</Icap>
</IcapConfig>

IcapConfig tag

This is the root tag of the service configuration. The version attribute specifies the configuration version.

SensorId tag

Defines the interface ID. It is used in traffic analysis to determine the host from which messages have been received. Although the Microolap EtherSensor ICAP server's performance is very high, it makes sense to distribute the processing among several Microolap EtherSensor servers if there are too many connections.

Network tag

Defines the TCP/IP network settings for the service's server. The max_connections attribute specifies the maximum number of simultaneous connections from an ICAP client that the server can process. The default value of the max_connections attribute is 4000. For a server with a 2xDualCore Intel Xeon 2,3GHz CPU and 8GB RAM, the ICAP server can process up to 10,000 simultaneous connections.

For improved performance, use more CPU cores, a faster disk system or more RAM.

ListenAddress tag

The ListenAddress tag is nested within the Network tag. It specifies the network address (the IP address and port) that accepts new connections from ICAP clients. You can have between 1 and 60 ListenAddress tags with distinct network addresses where the server should be running. If the server should run on all addresses set up on a machine, specify only one tag with just one IP address: 0.0.0.0. The ssl attribute defines whether SSL will be used to protect data over this connection.

For example, the following configuration

instructs the system to run the service on all server IP addresses set up on port 1344.

instructs the system to run the service on network interfaces with these IP addresses: 1.2.3.4:1344 and 1.2.3.5:1345.

The Icap Tag

Groups settings related to the ICAP protocol and its processing.

Preview tag

The Preview tag is nested within the Icap tag. It specifies the parameters for the preview mode in ICAP. The preview mode in ICAP allows you to send, initially, only a part of the data. Then, after this part is analyzed, it can either send the remaining data or stop processing.

It doesn't make sense to use the preview mode in Microolap EtherSensor because the service always receives all traffic for analysis. This mode is supported because it is required by certain ICAP clients. It also ensures compatibility with the ICAP specification as per RFC 3507.

The enabled attribute for the Preview tag determines whether the mode is active:

enabled="true" - the preview mode is on

enabled="false" - the preview mode is off

The size attribute of the Preview tag defines the size of the data sent for the preview, in bytes. We recommend selecting 4096 (4 Kbytes). 0 means that only HTTP request or response headers will be sent for preview.

We recommend turning this mode off whenever possible (enabled="false"), turning it on only when an ICAP client cannot work any other way. This will allow you to significantly reduce traffic between the ICAP client and the server.

Allow204 tag

The Allow204 tag is nested within the Icap tag. It defines whether the subsystem ICAP server can or cannot use a short response with a 204 code. The short response means that if the ICAP server of the service receives any data from an ICAP client, it doesn't send the data back, but only sends a response with a 204 code. This allows you to reduce traffic sent from the ICAP server to ICAP clients and lower the workload to the service, improving performance.

The enabled attribute of the Allow204 tag specifies whether the server is allowed to use a short response:

enabled="true" - 204 code is allowed

enabled="false" - 204 code is not allowed

We recommend turning this mode on whenever possible (enabled="true"), turning it off only when an ICAP client doesn't support processing responses with a 204 code.

RawLog tag

The RawLog tag is nested within the Icap tag. It sets parameters for use of the RawLog mode for ICAP requests/responses of the server. RawLog is a mode for logging the "raw" data exchanged between the ICAP client and ICAP server. We recommend using this mode only if there is no other way to determine why communication between the ICAP client and ICAP server has been interrupted.

The enabled attribute of the RawLog tag specifies if the RawLog mode is active or not:

enabled="false" - the raw data log mode is off

The path attribute of the RawLog tag specifies the directory path to which the raw data of the TCP sessions between the ICAP client and ICAP server is to be saved.

We recommend turning this mode off whenever possible (enabled="false") because, with a heavy workload, service performance may decrease significantly, generating a heavier workload for the Microolap EtherSensor runtime environment disk system.

If you are unable to determine why an ICAP client cannot communicate with an ICAP server, please send the following to the Microolap EtherSensor manufacturer: RawLog data files, a detailed description of the ICAP client's and ICAP server's behavior and messages that the ICAP client saved to its standard logs.

RequestLog tag

The RequestLog tag is nested within the Icap tag. It establishes the parameters of the log mode for logging ICAP and HTTP errors, as well as HTTP requests processed by the ICAP server. This log is used to save errors that may appear in the communication between an ICAP client and a server and are related to incorrect formats of data sent by an ICAP client, incorrect usage of ICAP, etc.

The enabled attribute of the RequestLog tag determines whether if the log mode for ICAP and HTTP errors is on or off:

enabled="true" - the log mode is on

enabled="false" - the log mode is off

The http_enabled attribute of the RequestLog tag determines whether if the log mode for HTTP requests is on or off:

http_enabled="true" - the log mode for HTTP requests is on

http_enabled="false" - the log mode for HTTP requests is off

By default (if the attribute is missing), this mode is on.

The channel attribute of the RequestLog tag specifies the internal system name for the logging channel for HTTP requests. This parameter should always be set to channel="ICAP-REQUEST" and you should only change it if directly instructed to by the Microolap EtherSensor manufacturer.

AlwaysOk tag

The AlwaysOk tag is nested within the Icap tag. It determines whether if the "Everything is always OK" mode is on or off. In this mode, if the ICAP server detects errors from the client in ICAP, it doesn't send an error code in response, but rather responds with the 204 (No modifications) code.

The enabled attribute of the AlwaysOk tag determines whether the "Everything is always OK" mode is on or off.

enabled="true" - the mode is on

enabled="false" - the mode is off

If the tag is missing, this mode is off by default.

If the mode is active, the 204 response code is sent in return to errors even if it is prohibited by the Allow204 tag.

We recommend turning this mode on only when absolutely necessary because it sometimes may cause the ICAP client that sends the traffic to unexpectedly fail.

SyncMode tag

The SyncMode tag is nested within the Icap tag. It enables the "ICAP synchronous work" mode. In this mode, the ICAP server sends a response to an ICAP client only after the entire request has been received. This will happen even for large requests (download/upload ISO images or other large files). If the synchronous mode is disabled, the ICAP server works in streaming mode. This means that the server doesn't wait for the client to send the entire request, but starts responding immediately. The user doesn't see any lags in file transfers. This is especially important if the multimedia traffic is sent via ICAP (such as video streaming). The user doesn't have to wait for the entire video stream to be downloaded first to the ICAP proxy, then to the ICAP server, then returned by the ICAP server and only after that sent out from the ICAP proxy to the user.

The synchronous mode may, however, be required by certain ICAP clients largely for the purpose of using ICAP to work with antivirus software. Antivirus software usually needs to receive the entire object first (no matter what the object's size is) to decide what its response to the ICAP client will be.

The enabled attribute of the SyncMode tag determines whether the "ICAP synchronous work" mode is on or off.

enabled="true" - the mode is on

enabled="false" - the mode is off

If the tag is missing, this mode is on by default.

XHeader tag

The XHeader tag manages extended ICAP headers. The tag allows for notification of the ICAP client of whether the server supports the header or not, thus allowing or forbidding the ICAP client to send this header to the ICAP server.

The enabled attribute of the XHeader tag determines whether the header is supported:

enabled="true" - the header support is on

enabled="false" - the header support is off

If the tag is missing, the header is supported by default.

The name attribute of the XHeader tag specifies the name of the extended header.

Supported ICAP header names are:

X-Client-IP

X-Server-IP

X-Client-Username

X-Subscriber-ID

X-Authenticated-User

X-Authenticated-Groups

If these headers appear when processing the ICAP traffic, they are translated into the following headers:

X-Sensor-Icap-Client-Username

X-Sensor-Icap-Subscriber-ID

X-Sensor-Icap-Authenticated-User

X-Sensor-Icap-Authenticated-Groups

The values of X-Client-IP and X-Server-IP headers are saved in the X-Sensor-Src-Address and X-Sensor-Dst-Address headers.

By default (if XHeader tags are not specified in the configuration file), all headers are considered to be supported.

ICAP Manual Setup (Config File)

ICAP Manual Setup (Config File)