Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

ICAP for remote content inspection

September 14, 2021
Contributed by: 
S S C

The Internet Content Adaptation Protocol (ICAP) is a simple lightweight protocol for running the value-added transformation service on HTTP messages. In a typical scenario, an ICAP client forwards HTTP requests and responses to one or more ICAP servers for processing. The ICAP servers perform content transformation on the requests and send back responses with appropriate action to take on the request or response.

ICAP on a Citrix ADC appliance

In a Citrix ADC setup, the appliance acts as an ICAP client interoperating with third-party ICAP servers (such as antimalware and Data Loss Protection (DLP)). When the appliance receives an incoming web traffic, the appliance intercepts the traffic and uses a Content Inspection policy to evaluate if the HTTP request needs an ICAP processing. If yes, the appliance decrypts and sends the message as a plain text to the ICAP servers. The ICAP servers run the content transformation service on the request message and send back a response to the appliance. The adapted messages can either be an HTTP request or an HTTP response. If the appliance interoperates with multiple ICAP servers, the appliance performs load balancing of ICAP servers. This scenario happens when one ICAP server is not sufficient to handle all the traffic load. Once the ICAP servers return a modified message, the appliance forwards the modified message to the back-end origin server.

The Citrix ADC appliance also provides a secured ICAP service if the incoming traffic is an HTTPS type. The appliance uses an SSL based TCP service to establish a secured connection between the appliance and ICAP servers.

How ICAP request modification (REQMOD) works

In the request modification (REQMOD) mode, the Citrix ADC appliance forwards the HTTP request received from the client to the ICAP server. The ICAP server then performs one of the following:

  1. Sends back a modified version of the request and the appliance in turn sends the modified request to the back-end origin server or it pipelines the modified request to another ICAP server.
  2. Responds with a message indicating no adaptation is required.
  3. Returns an error and the appliance in turn sends the error message back to the user.

How ICAP response modification (RESPMOD) works

In the response modification (RESPMOD) mode, the Citrix ADC appliance sends an HTTP response to the ICAP server (the response sent by the appliance is typically the response sent by the origin server). The ICAP server then performs one of the following:

  1. Sends a modified version of the response and the appliance in turn sends the response to the user or pipelines the response to another ICAP server.
  2. Responds with a message indicating no adaptation is required.
  3. Returns an error and the appliance in turn sends the error message to the user.

ICAP license

The ICAP feature works on a Citrix ADC standalone or high availability setup with Citrix ADC Premium or Advanced license edition.

Configure ICAP for content transformation service

To use ICAP for content transformation service, you must begin by enabling the Content inspection and load balancing features. Once you enable the features, you can complete the following tasks

To enable content inspection

If you want the Citrix ADC appliance to act as an ICAP client, you must first enable the Content Inspection and load balancing features.

At the command prompt, type:

enable ns feature contentInspection LoadBalancing
<!--NeedCopy-->

Add ICAP profile

ICAP configurations for a Citrix ADC appliance are specified in an entity called the ICAP profile. The profile has a collection of the ICAP settings. The settings include parameters to dynamically generate an ICAP request, receive the ICAP response, and log content inspection data.

To dynamically generate an ICAP request to the ICAP server, a new parameter, “insertHTTPRequest” is added to the ICAP profile. If this parameter is configured, the appliance takes the configured value as a policy expression and evaluates the expression and includes the result as an encapsulated HTTP request or response and then sent it to the ICAP server. Also, a new parameter “insertICAPHeaders” is configurable to dynamically evaluate and include the ICAP headers.

When the appliance sends an ICAP request and does not receive a response the ICAP server, the connection becomes unresponsive. It occurs until the ICAP server sends a response or a session gets freed. The behavior can be handled by configuring the ICAP response time-out option. You can set a request time-out parameter for action if there is delayed ICAP response. If the Citrix ADC appliance does not receive a response within the configured request time-out, the request timeout action is performed.

ReqTimeoutAction: Possible values are BYPASS, RESET, DROP. BYPASS: This Ignores the remote ICAP server’s response and sends the request/response to Client/Server. RESET (default): Reset the client connection by closing it. DROP: Drop the request without sending a response to the user

To evaluate an ICAP response, a new policy expression ICAP.RES is used in the content inspection callout return expression. This expression evaluates the ICAP response similar to the HTTP.RES expression in a HTTP_CALLOUT.

For example, when a Citrix ADC appliance receives an HTTP request for a service hosted behind the Citrix ADC virtual IP address, the appliance might have to check the client’s authentication with an external server and take an action.

At the command prompt, type:

add ns icapProfile <name> [-preview ( ENABLED | DISABLED )][-previewLength <positive_integer>] -uri <string> [-hostHeader <string>] [-userAgent <string>] -Mode ( REQMOD | RESPMOD )[-queryParams <string>] [-connectionKeepAlive ( ENABLED | DISABLED )][-allow204 ( ENABLED | DISABLED )] [-insertICAPHeaders <string>][-insertHTTPRequest <string>] [-reqTimeout <positive_integer>][-reqTimeoutAction <reqTimeoutAction>] [-logAction <string>]

Example:

add icapprofile reqmod-profile -mode RESPMOD -uri “/req_scan” -hostHeader “Webroot.reqsca” -useragent “NS_SWG-Proxy”

add ns icapProfile icap_prof1 -uri "/example" -Mode REQMOD -reqtimeout 4 -reqtimeoutaction BYPASS

> add icapProfile reqmode-profile -uri '/example' -mode REQMOD -insertHTTPRequest q{HTTP.REQ.METHOD + " " + HTTP.REQ.URL + " HTTP/1.1\r\n" + "Host: " + HTTP.REQ.HOSTNAME + "\r\n\r\n"}

Log ICAP content inspection action

To dynamically generate content inspection log stream records or SYSLOG logs, you can use the ICAP.RES based policy expression on the ICAP response. This parameter is configurable in the ICAP profile to configure the policy expression to generate the dynamic log records.

At the command prompt, type:

add audit messageaction icap_log_expr INFORMATIONAL icap.res.full_header

set icapProfile reqmode-profile -logAction messageaction

Add ICAP service as a TCP or SSL_TCP service

After you enable the Content Inspection feature, you must add an ICAP service for the ICAP servers that will be part of the load balancing setup. The service that you add provides the ICAP connection between the Citrix ADC appliance and load balancing virtual servers.

Note: As an administrator, you can add an ICAP service and directly configure the ICAP server IP address in the Content Inspection action.

At the command prompt, type the following:

add service <name> <IP> <serviceType> <port>
<!--NeedCopy-->

Example:

add service icapsv1 10.10.10.10 SSL_TCP 1345

add service icapsv2 10.10.10.11 SSL_TCP 1345

Add a TCP or SSL_TCP based load balancing virtual server

After creating an ICAP service, you must create a virtual server to accept ICAP traffic and load balance the ICAP servers.

Note:

You can also use an SSL based TCP service over a secured channel. You use a SSL_TCP service and bind to the Content Inspection action.

At the command prompt, type the following:

add lb vserver <name> <serviceType> <port>
<!--NeedCopy-->

Example:

add lb vserver vicap TCP 0.0.0.0.0 –persistenceType NONE -cltTimeout 9000

add lb vserver vicap SSL_TCP 0.0.0.0 0 –persistenceType NONE -cltTimeout 9000
<!--NeedCopy-->

Bind ICAP service to the load balancing virtual server

After you create an ICAP service and virtual server, you must bind the ICAP service to the virtual server.

At the command prompt, type the following:

bind lb vserver <name> <serviceName>
<!--NeedCopy-->

Example:

bind lb vserver vicap icapsv1
<!--NeedCopy-->

Add content inspection action

After you enable the Content Inspection feature, you must add an ICAP action for handling the ICAP request information. The ICAP profile and services, or load balancing virtual server that are created are bound to the ICAP action. If the ICAP server is down, you can configure the ifserverdown parameter for the appliance to perform any one of the following actions.

CONTINUE: If the User wants to bypass the content inspection when the remote server is down, you can choose the “CONTINUE” action, as default. RESET (default): This action responds to the client by closing the connection with RST. DROP: This action silently drops the packets without sending a response to the user.

At the command prompt, type the following:

add contentInspection action <name> -type ICAP -serverName <string> -icapProfileName <string>

add ContentInspection action <name> -type ICAP -serverip <ip> - serverport <port> -icapProfileName <string>
<!--NeedCopy-->

Note:

If you can configure the ICAP service instead of a load balancing virtual server, you can mention the service name in the \<-serverip> option. When adding the Content Inspection action, the TCP service is automatically created for the given IP address with port 1344 and it is used for ICAP communication.

Example:

add ContentInspection action ci_act_lb -type ICAP -serverName vicap -icapProfileName icap_reqmod

add ContentInspection action ci_act_svc -type ICAP -serverName icapsv1 -icapProfileName icap_reqmod

add ContentInspection action ci_act_svc -type ICAP -serverip 1.1.1.1 - serverport 1344 -icapProfileName icap_reqmod
<!--NeedCopy-->

Add content inspection policies

After you create a Content Inspection action, you must create content inspection policies to evaluate requests for ICAP processing and audit logging. The policy is based on a rule which consists of one or more expressions. The rule is associated to the content inspection action that is associated if a request matches the rule.

At the command prompt, type the following:

add contentInspection policy <name> -rule <expression> -action <string>
<!--NeedCopy-->

Example:

add ContentInspection policy ci_pol_basic –rule true –action ci_act_svc

add ContentInspection policy ci_pol_HTTP –rule HTTP.REQ.URL.CONTAINS(“html”) –action ci_act_svc
<!--NeedCopy-->

Bind content inspection policies to the content switching or load balancing virtual server

To put an ICAP policy into effect, you must bind it globally or bind it to a Content Switching or load balancing virtual server, which front end the application. When you bind the policy, you must assign a priority to it. The priority determines the order in which the policies you define are evaluated.

Note:

The application virtual server must be of type - HTTP/SSL/CS-PROXY.

For information about configuring a load balancing setup for forwarding the traffic to the back-end origin server after content transformation, see Load Balancing.

Configure secured ICAP service

To establish a secured connection between the Citrix ADC appliance and the ICAP web servers, the appliance uses an SSL-based TCP service or load balancing virtual server bound to an ICAP action.

To establish a secured ICAP connection, complete the following tasks:

  1. Add SSL-based TCP service.
  2. Bind SSL-based TCP service to load balancing virtual server of type TCP or SSL_TCP.
  3. Bind SSL-based TCP service or load balancing virtual server to Content Inspection action.

Add SSL-based TCP service to load balancing virtual server

To establish a secured connection between the Citrix ADC appliance and the ICAP web servers, the appliance uses an SSL-based TCP service or load balancing virtual server bound to an ICAP action.

To establish a secured ICAP connection, complete the following tasks:

  1. Add SSL-based TCP service.
  2. Bind SSL-based TCP service to load balancing virtual server of type TCP or SSL_TCP.

Bind SSL-based TCP service or load balancing virtual server to Content Inspection action

Add SSL-based TCP service to load balancing virtual server

After you enable the Content Inspection feature, you must add a secured ICAP service that will be part of the load balancing setup. The service that you add provides a secured ICAP connection between the Citrix ADC appliance and load balancing virtual servers.

At the command prompt, type the following:

add service <name> <IP> <serviceType> <port>
<!--NeedCopy-->

Example:

add service icapsv2 10.102.29.200 SSL_TCP 1344 –gslb NONE –maxclient 0 –maxReq 0 –cip DISABLED –usip NO –useproxport YES –sp ON –cltTimeout 9000 –svrTimeout 9000 –CKA NO –TCPB  NO –CMP NO
<!--NeedCopy-->

Bind SSL-based TCP service to SSL_TCP or TCP load balancing virtual server

After you create a secured ICAP service, you must bind the service to the load balancing virtual server. It is required if you are using a load balancing virtual server to load balance the ICAP servers.

At the command prompt, type the following:

bind lb vserver <name> <serviceName>
<!--NeedCopy-->

Example:

bind lb vserver vicap icapsv2
<!--NeedCopy-->

Bind SSL-based TCP service or load balancing virtual server to the Content Inspection action

You add an ICAP action for handling the ICAP request information and also bind the SSL-based TCP service to the action.

At the command prompt, type the following:

add contentInspection action <name> -type ICAP -serverName <string> -icapProfileName <string>
<!--NeedCopy-->

Example:

add ContentInspection action ci_act_svc -type ICAP -serverName icapsv2 -icapProfileName icap_reqmod

add ContentInspection action ci_act_svc -type ICAP -serverName vicap -icapProfileName icap_reqmod
<!--NeedCopy-->

Configure ICAP protocol by using the GUI

  1. Navigate to Load Balancing > Services and click Add.
  2. In the Services page, enter the service details.
  3. Navigate to Load Balancing > Virtual Servers. Add a load balancing virtual server of type HTTP/SSL. Or, you can select a virtual server and click Edit.
  4. After entering the server basic details, click Continue.
  5. In the Advanced Settings section, click Policies.
  6. Go the Policies section and click the Pencil icon to configure the Content Inspection policy.
  7. On the Choose Policy page, select Content Inspection. Click Continue.
  8. In the Policy Binding section, click + to add a Content Inspection policy.
  9. In the Create ICAP Policy page, enter a name for the policy.
  10. In the Action field, click the “+” sign to add an ICAP action.
  11. In the Create ICAP Action page, enter a name for the action.
  12. Enter a name for the action.
  13. In the Server Name field, enter the name of the TCP service already created.
  14. In ICAP Profile field, click the “+” sign to add an ICAP profile.
  15. In the Create ICAP Profile page, enter a profile name, URI, and MODE.
  16. Click Create.
  17. In the Create ICAP Action page, click Create.
  18. In the Create ICAP Policy page, enter “true” in the Expression Editor and then click Create.
  19. Click Bind.
  20. When prompted to enable the Content Inspection feature, click Yes.
  21. Click Done.

For information about the Citrix ADC GUI configuration for load balancing and forwarding the traffic to the back-end origin server after content transformation, see Load Balancing.

Configure secured ICAP protocol by using the GUI

  1. Navigate to Load Balancing > Services and click Add.
  2. In the Services page, enter the service details.
  3. Navigate to Load Balancing > Virtual Servers. Add a virtual server of type HTTP/SSL. Or, you can select a virtual server and click Edit.
  4. After entering the server basic details, click Continue.
  5. In the Advanced Settings section, click Policies.
  6. Go the Policies section and click the Pencil icon to configure the Content Inspection policy.
  7. On the Choose Policy page, select Content Inspection. Click Continue.
  8. In the Policy Binding section, click + to add a Content Inspection policy.
  9. In the Create ICAP Policy page, enter a name for the policy.
  10. In the Action field, click the “+” sign to add an ICAP action.
  11. In the Create ICAP Action page, enter a name for the action.
  12. Enter a name for the action.
  13. In the Server Name field, enter the name of the TCP_SSL service already created.
  14. In ICAP Profile field, click the “+” sign to add an ICAP profile.
  15. In the Create ICAP Profile page, enter a profile name, URI, and MODE.
  16. Click Create.
  17. In the Create ICAP Action page, click Create.
  18. In the Create ICAP Policy page, enter “true” in the Expression Editor and then click Create.
  19. Click Bind.
  20. When prompted to enable the Content Inspection feature, click Yes.
  21. Click Done.

Audit log support for remote content inspection

If an incoming request or outgoing response is content inspected, the Citrix ADC appliance logs the ICAP details. The appliance stores the details as a log message in the ns.log file.

Each log message typically contains the following details:

<Source IP> <Destination IP> <Domain> <ICAP server IP><ICAP Mode> <Service URI> <ICAP response> <Policy action>
<!--NeedCopy-->

Example for content inspected request log message:

Apr 18 14:45:41 <local0.info> 10.106.97.104 04/18/2018:14:45:41 GMT 0-PPE-0 : default CI ICAP_LOG 788 0 : Source 10.102.1.98:39048 - Destination 10.106.97.89:8011 - Domain 10.106.97.89 - Content-Type application/x-www-form-urlencoded - ICAP Server 10.106.97.99:1344 - Mode REQMOD - Service /example - Response 204 - Action FORWARD
<!--NeedCopy-->

Example for content inspected response log message:

Apr 18 12:34:08 <local0.info> 10.106.97.104 04/18/2018:12:34:08 GMT 0-PPE-0 : default CI ICAP_LOG 71 0 : Source 10.106.97.105:18552 - Destination 10.106.97.99:80 - Domain NA - Content-Type NA - ICAP Server 10.106.97.99:1344 - Mode RESPMOD - Service /example - Response 400 - Action Internal Error
<!--NeedCopy-->
ICAP for remote content inspection
September 14, 2021
Contributed by: 
S S C
September 14, 2021
Contributed by: 
S S C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.