How To: Configure an ICAP Service¶

Overview¶

BIG-IP Next SSL Orchestrator supports Internet Content Adaption Protocol (ICAP) based devices as security services. An ICAP device adheres to RFC 3507 specifications and is often used to encapsulate payloads for various services. An ICAP inspection service enables SSL traffic to be processed by an external ICAP server. It can be defined as a load-balanced set of multiple ICAP devices on the same IP subnet. SSL Orchestrator acts as the ICAP client, encapsulating packets and directing the traffic to a listening IP address and port on the ICAP server. An ICAP server can perform various content adaptation services, such as malware scanning, URL filtering, data loss prevention, and encryption.

An ICAP device is defined by the following primary characteristics:

Layer 3: It contains at least one network interface with an assigned IP address as its listening interface for encapsulated ICAP queries.
ICAP-enabled service: It runs at least one service accessible through an ICAP inspection service and adheres to RFC3507.

ICAP inspection service

Procedure¶

Central Manager GUI

To create an ICAP service using Central Manager GUI:

Log in to BIG-IP Next Central Manager as admin, click the Workspace icon, click Security, and then click SSL Orchestrator.
At the top of the screen, click + Create.
In the Inspection Service drop-down list, select Generic ICAP.
If you have not created any inspection service before, click Start Creating or click + Create if you already have some inspection services and want to create more inspection services.
Select the Show Advanced Fields radio button to enter information such as Host, Referer, and so on.
Specify General Properties for the policy.
1. For Name, enter a name for the TAP Service.
2. For Description, add a description for the service, if required.
3. For Request Modification URI path, specify the URL path for request traffic flows (client to server). Type a URL without any leading slash ‘/’. Example: path
4. For Response Modification URI Path, specify the URL path for response traffic flows (server to client).
5. For Preview Max Length, specify the number of bytes you want to use as the maximum length for the ICAP preview. This value defines the amount of the HTTP request or response that the BIG-IP system offers to the ICAP server when sending the request or response to the server for adaptation. This value should not exceed the length of the preview that the ICAP server has indicated it will accept.
6. For Allow HTTP/1.0, specify whether to forward HTTP version 1.0 requests for adaptation. By default only HTTP version 1.1 requests are forwarded. Version 1.0 is not supported. While it should work in most cases, it might be necessary to restrict adaptation on a site-specific basis. The default is disabled.
Specify the Advanced properties for the policy.
1. For Host, specify the hostname or IP address for the ICAP header.
2. For referer, specify the referrer attribute to be used in the ICAP header that may describe the context of the ICAP request.
3. For userAgent, specify the user agent attribute to be used in the ICAP header that may describe the client software or the browser requesting the ICAP server.
4. For From, specify the attribute to be used in the ICAP header that indicates the sender of the message.
Toggle the iRules radio button in the Additional Features section, if you want to include iRules for creating the service. The iRules tab will be added to the left pane.
Specify Network settings for the policy.
1. For VLAN, specify the L1 Network VLAN created during BIG-IP Next Onboarding.
2. For Device Monitor, specify the monitor to track the availability and performance of services on the nodes, pools, or pool members to which you attach them.
3. For Service Down Action, specify the action to be taken when a destination device associated with the service becomes unavailable or goes down.
  1. ignore: Traffic to the service is ignored and is sent to the next service in the chain.
  2. drop: Stops forwarding traffic to the affected service.
  3. reset: Resets the connection to the client.
4. Inspection Service Endpoints: Specify the devices or locations within a network where security inspection or monitoring takes place.
If you selected iRules radio button in previous steps, you will be navigated to the iRules tab. In the iRules tab,
1. Click Start Adding.
2. Select the required iRules from the drop-down list.
3. Click Add to List.
4. Click Save & Continue.
Select Review & Deploy to deploy the configuration.
Verify the details in the Summary section and click Start Adding.
Select the BIG-IP Next Instances to which you want to deploy the service.
Note: Ensure to add the BIG-IP Next instance to Central Manager before you can deploy your changes to the instance.
Click Add to List.
You can select each instance to which you want to deploy the inspection service and click Validate. It will validate whether the VLAN configured for this Inspection Service exists on the Instance and display the relevant status.
If you want to modify the network configuration for an instance or if the VLAN configured for this Inspection Service does not exist on the instances added, you can create VLANs or modify the netowrk configuration on the instances using the respective Configure icon. To create the VLAN:
1. Click the Configure icon.
2. Click the L1networks tab. Skip to Step c if you want to use an existing L1 network.
  1. Click +Create to create a new L1 Network.
  2. Enter a network name and interface name for the L1 network and the number of VLANs associated.
  3. Click Save.
3. Click the VLANs tab.
  1. Click +Create to create a new VLAN.
  2. Enter the VLAN name that you added at step 2a or enter a new VLAN name.
  3. Enter a tag and select the L1 Network from the dropdown.
  Note: You can also use an exisiting L1 Network without creating a new L1 Network.
4. Click the Addresses field or Click IP Addresses tab.
  1. Click + Create.
  2. Add a Device Name. Select the VLAN you created.
  3. Click Save. The VLAN is deployed on the BIG-IP Next Instance.
  Note: You can also use an exisiting VLAN without creating a new VLAN.
  
  Note: When you create and configure a new VLAN for an instance, the respective Vlan column is updated with the new VLAN name.

14.Select the instance(s).
15.Click Deploy Changes.
16. Click Yes, Deploy to deploy to the service to the selected instances.

Central Manager API

To create an ICAP service using Central Manager API:

Configure network objects

Typically, a BIG-IP Next user configures L1-networks objects during BIG-IP Next onboarding, including VLANs and self-IPs. If any additional network configuration objects (Virtual Routing Function (VRFs)) are not available on the instance, they are auto generated when you deploy the service.

You can create a VLAN during the onboarding and specify the VLAN while configuring an inspection service in Central Manager. For more details, see Getting Started with Installation. You can also create the VLAN from Central Manager before deploying the inspection service to an instance. For more details, see How to: Configure Instance Specific Network Settings using CM APIs

Configure an ICAP Service

To configure an ICAP service:

Send a POST request to the v1/spaces/default/security/inspection-services endpoint.
```
POST {{CM}}/api/v1/spaces/default/security/inspection-services
```
For the API body, use the following example, substituting appropriate values for the policy you want to create.

For schema details, refer to the ICAP service section in the Reference: Inspection Service objects

In the following example:

type - For an ICAP service, the value of this property is set to icap .
requestModificationURI - Specifies the URL path for request traffic flows (client to server).
responseModificationURI - Specifies the URL path for response traffic flows (server to client).

For the ICAP inspection service, the minimum requirements for defining are illustrated in the following examples. The resulting ID will be at .id.

Basic

POST {{CM}}/api/v1/spaces/default/security/inspection-services

{
  "name": "my-sslo-icap",
  "description": "My SSLO ICAP Inspection Service",
  "type": "icap",
  "requestModificationURI": "avscan",
  "responseModificationURI": "avscan",
  "oneConnect": { "sourceMask": "0.0.0.0" },
  "serviceDownAction": "ignore",
  "network": {
    "vlan": "sslo-insp-icap",
    "endpoints": [
      {
        "address": "<IP>"
      },
      {
        "address": "<IP>"
      }
    ]
  }
}

Curl

INSP=$(cat <<EOF
{
  "name": "my-sslo-icap",
  "description": "My SSLO ICAP Inspection Service",
  "type": "icap",
  "requestModificationURI": "avscan",
  "responseModificationURI": "avscan",
  "oneConnect": { "sourceMask": "0.0.0.0" },
  "serviceDownAction": "ignore",
  "network": {
    "vlan": "sslo-insp-icap",
    "endpoints": [
      {
        "address": "<IP>"
      },
      {
        "address": "<IP>"
      }
    ]
  }
}
EOF
)
insp_id=$(curl -sk -H "Authorization: Bearer ${token}" -H "Content-Type: application/json" "https://${CM}/api/v1/spaces/default/security/inspection-services" -d "${INSP}" |jq -r '.id')

API Reference

Required	Attribute	Defaults	Notes
*	name
*	description
*	type		string: must be "icap"
*	requestModificationURI
*	responseModificationURI
*	serviceDownAction	none	"ignore", "drop", or "reset"
*	oneConnect	none	{ "sourceMask": "0.0.0.0" }
*	monitor	none	"tcp": { "interval": 10, "timeout": 10 } "http" { "interval": 10, "timeout": 10, "sendString": "", "receiveString": "", "receiveDisableString": "", "username": "", "password": "" }
*	network: vlan		string: vlan-name
*	network: endpoints		array: { "address":"ip-address:port" }
	previewLength	0
	headerFrom		string
	host		string
	referer		string
	userAgent		string
	allowHTTP1.0	false	boolean

For more information on the APIs, refer to Open API documentation https://clouddocs.f5.com/products/bigip-next/mgmt-api/latest/ApiReferences/bigip_public_api_ref/r_openapi-next.html

Note: To configure instance specific network settings, refer to How to: Configure Instance Specific Network Settings using CM APIs

Next Steps

How To: Deploy a service to a BIG-IP Instance using CM APIs

Previous Next