ICAP Scanner
UDMG supports the Internet Content Adaptation Protocol (ICAP), allowing inbound files to be scanned for viruses and other content threats before reaching their destination.
ICAP is a lightweight, HTTP-like protocol defined in RFC 3507 and widely used for virus scanning and content filtering in transparent HTTP proxy caches.
In UDMG, ICAP integration is managed through ICAP Scanners configured at the Domain level via the UDMG Admin UI. This design enables each Domain to customize scanning settings according to specific business needs.
UDMG does not support ICAPS (ICAP over TLS) in the current version.
Before You Begin
Know Your ICAP Server
Before configuring ICAP integration in UDMG, it is essential to gather key information about the ICAP server. Having this information in advance helps ensure correct configuration of ICAP Scanners and prevents common setup issues:
- ICAP Server URI: You need the full URI of the ICAP server, including the hostname or IP address, port number, and service name (it typically follows the format:
icap://hostname:port/service). - Security Requirements: Determine if the ICAP server requires secure connections over TLS (ICAPS). Currently, UDMG only supports ICAP and does not support ICAPS.
- Connection Testing: Ensure that the network allows UDMG to reach the ICAP server endpoint on the specified port. Firewall or routing issues can prevent successful communication.
Scan Results Handling
When a file is scanned by the ICAP server, UDMG evaluates the response and applies one of several configurable actions depending on whether a violation or an error is detected:
- Clean Files: Files that pass the scan without any detected threats are allowed to proceed normally and are forwarded to their intended destination.
- Violations Detected: If the ICAP server flags a file as violating security policies (e.g., containing malware or disallowed content), UDMG can be configured to do one of the following actions:
- Reject: The file is deleted immediately and a failure response is sent to the connected client.
- Quarantine: The file is kept in the
TMPfolder with a renamed extension for later review or manual intervention.
- Scanning Failures or Errors: In cases where the scan cannot be completed due to network issues, timeouts, or other errors, UDMG allows configurable fallback actions:
- Reject: The file is deleted to prevent potential risk.
- Quarantine: The file is quarantined similarly to violation cases.
- Flag: The file is renamed but allowed to continue to the target destination.
- Bypass: The file bypasses scanning and proceeds to the destination (not recommended).
Advanced Settings
Preview Mode
Preview mode is a feature supported by many ICAP servers that allows scanning only a portion of a file initially, rather than sending the entire file at once. Using Preview mode is recommended whenever supported, as it significantly speeds up scanning—especially for large files—and improves overall efficiency.
With Preview mode, UDMG sends an initial chunk of the file to the ICAP server for scanning (the size of this chunk is determined by the ICAP server). If the ICAP server determines that further data is needed for a thorough scan, it requests the remaining bytes, and the rest of the file is sent up to the configured Max bytes to Scan.
If the ICAP server does not support Preview mode, UDMG automatically disables Preview mode for that file, and sends the entire file or the specified maximum bytes.
| Scenario | UDMG Behavior |
|---|---|
| Preview mode is enabled in UDMG and the ICAP server supports it. | Sends the configured preview size of bytes; if the ICAP server requests more data, sends remaining bytes up to max scan size. |
| Preview mode is enabled in UDMG, but the ICAP server does not support it. | UDMG disables Preview mode automatically and sends the full file or max bytes in a single scan request. |
| Preview mode is disabled in UDMG settings. | Sends the entire file or max bytes in one scan request without using Preview. |
| Preview mode is enabled in UDMG and the ICAP server supports it, but the file size is smaller than the expected preview size. | Sends the entire file in a single scan without preview. |
File Extension Exclusion
UDMG allows administrators to specify a list of file extensions to exclude from ICAP scanning. This feature helps optimize system performance by preventing unnecessary scans of file types that are typically ineligible for scanning—such as encrypted files or compressed archives—or otherwise deemed irrelevant to security policies.
Files matching any of the configured extensions will bypass ICAP scanning and proceed directly to their destination.
Logging
UDMG provides logging for all ICAP scanning operations, enabling administrators to monitor scanning activity, troubleshoot issues, and maintain audit trails.
When integrated with Universal Automation Center (UAC), relevant ICAP scan events can trigger automation workflows, with logging capturing event details and file status (e.g., a file was quarantined, deleted, or allowed).
The log level for ICAP scanning corresponds to the setting configured in the log block of UDMG's HCL configuration file. For more details on log configuration and management, refer to Logging.
Configuring ICAP
ICAP Scanners are configured at the Domain level. To configure an ICAP Scanner, follow these steps:
- From the Sidebar, click General > Domain.
- Click ICAP Scanner.
- Complete the fields for the ICAP Scanner settings, using the Field Descriptions table as a guide.
- Click Save.
For the ICAP Scanner to participate in file transfers, the involved Local Filesystem Endpoint must have its ICAP Scanning - Inbound field enabled.
Field Descriptions
| Name | Description | Specifications | Required |
|---|---|---|---|
| Name | The name of the ICAP Scanner. |
| Yes |
| Description | The description of the ICAP Scanner. | No | |
| ICAP service URI | The standard or secure ICAP Hostname or IP Address, Port, and optional service name. | Format: icap://example.com:port/service | Yes |
| Use Preview if Supported by the ICAP Server | A toggle switch to enable or disable the ICAP Preview mode. If disabled, UDMG sends Max bytes to Scan value. | No | |
| Max bytes to Scan | If using Preview, then you should specify a value that matches your ICAP vendor's recommended settings, or leave blank to send the whole file. Max bytes is only sent if the Preview results is more bytes than what was asked for. | No | |
| Skip Files Matching Extension(s) | Enter a comma-separated list of file extensions that should be excluded from scanning. Do not include the leading period (dot). | Example: pgp, zip, gz | Optional |
| ICAP violations | Behavior if a violation is detected. Options:
| Yes | |
| ICAP Failures (Errors) | Behavior if a file targeted to be scanned could not be scanned for any reason (network or other faults). Options:
| Yes | |
| Extension for Flagged (Renamed) Files | Extension added to quarantined or flagged files for subsequent identification. | Example: FLAGGED | Yes, if ICAP Violations or ICAP Failures (Errors) are set to Quarantine or Flag |
Validating your ICAP Connection
The ICAP server connection can be validated to confirm if the service is correctly configured.
To validate the ICAP server, follow these steps:
- From the Sidebar, click General > Domain.
- Click ICAP Scanner.
- Click the Validate button above the ICAP Scanner details. This action performs an
OPTIONStest using the provided ICAP service URI.
You can also check the ICAP Scanner status in the UDMG Status modal.
Responses
| Scenarios | Message |
|---|---|
| Good response! | The ICAP test connection was successful! Response details:
|
| Unable to connect | The ICAP test was unable to connect to: [URI]. Please verify the address, port, and service name, and that there is a valid route to the ICAP server, and try again. |
| Timeout on response | The ICAP test made a connection, but no response was received, or a timeout occurred. Please verify that the ICAP server is operational, is configured correctly, and that there are no limitations on the network route, and try again. |
| Bad response | The ICAP test made a connection, but was unable to validate the response. You may continue as is or try a different configuration. Please review logs for the detailed response message received. |
Enabling and Disabling ICAP
ICAP Scanners can be Enabled or Disabled to control their active status and ability to participate in file transfers. The status is defaulted to Enabled and can be changed after creation.
- Enabled (default): The ICAP Scanner is active and participates in file transfers.
- Disabled: The ICAP Scanner is inactive and does not participate in file transfers.
To enable or disable ICAP, follow these steps:
- From the Sidebar, click General > Domain.
- Click ICAP Scanner.
- Click the Disable button above the ICAP Scanner details.
- If the ICAP Scanner is Disabled, then the button displays Enabled. If the ICAP Scanner is Enabled, then the button displays Disabled.