ICAP server settings
This page covers ICAP server settings.
For the profile-to-policy mapping applied to a request, see ICAP profiles.
To point a proxy or ICAP client at the server, see the ICAP integration guides.
Licensing
On the Portal, The ICAP tab, and the ICAP reporting and requests entries, appear only when the active license carries the Glasswall Halo: ICAP entitlement.
On the API, a read works whether or not the entitlement is present. However, the API refuses a write with 403 and names the missing entitlement in the response.
Turning the ICAP server on and off
The appliance ships with the ICAP server installed but not running, so nothing answers on the ICAP ports until an administrator turns it on.
- Enable ICAP server starts the server. The appliance answers ICAP requests on its listening ports, and the settings below become editable.
- Disable ICAP server stops the server. The appliance stops answering ICAP requests, and any client pointed at it is refused. The portal asks you to confirm first, because requests may be in progress. Saved settings are kept and apply again when you turn the server back on.
While the server is off, the settings on this tab are inactive and marked Inactive until the ICAP server is turned on.
When the control is unavailable
When the portal cannot offer the control, it shows the control inactive with the reason:
| Reason shown | What it means |
|---|---|
| This installation does not turn the ICAP server on and off from the portal. It is set where the appliance is deployed. | The portal cannot change this on your installation. |
| The ICAP server is not installed on this appliance, so there is nothing to turn on. | The ICAP server is not installed. The tab still appears because it follows the license. |
| Whether the ICAP server runs is managed for this installation, so it cannot be changed from the portal. | The installation manages the ICAP server for you, so a change here would not hold. |
Turning the server on and off needs the Admin role.
The Halo API offers the same control on GET /api/v1/icap/deployment and PUT /api/v1/icap/deployment, which takes {"enabled": true} or {"enabled": false}. After a start, the server takes a short time to become ready.
Starting and stopping the server through the API needs the appliance set up for bearer authentication.
Settings you can change
| Setting | What it controls | When it takes effect |
|---|---|---|
| Console log level | How much the server logs | Applied live |
| Service header | The Service header the server returns, and its IS-Tag | Applied live |
| OPTIONS TTL | How long an ICAP client may cache the server's OPTIONS response | Applied live |
| Maximum cache size | The size of the adapted-file cache. Caching is on whenever this is greater than zero | Applied live |
| Halo processing timeout | How long the server waits for the Halo API to process a file | Applied live |
| Mutual TLS | Whether the server requires client certificates on its TLS port | Next ICAP server restart |
Applied live means the change reaches the running server without a restart. Allow up to about 90 seconds for it to take effect.
Mutual TLS takes effect after the next ICAP server restart. Turning it on needs no change to the deployment. See Deployment and TLS support.
Settings fixed at deployment
The ICAP listening port, the TLS listening port, the listening address and the number of ICAP servers are set when the appliance is deployed. The portal shows them read-only. A write that names any of them is refused with 400, and the response names the field.
Validation
The server checks a write before it stores it:
- The maximum cache size may not be negative, or larger than the volume behind the cache.
- The OPTIONS TTL must be greater than zero.
- The processing timeout must be a duration.
- The log level must be one of the supported levels.
- The service header may not be longer than 255 characters or carry control characters.
- Mutual TLS may not be turned on until the certificates are in place.
The portal applies the same rules in the form, so a refusal appears before you save.
Testing the connection
Test connection sits in the ICAP configuration section, at the foot of the form and beside Edit configuration while the section is collapsed.
It opens a connection to the listening port and sends the OPTIONS request that every ICAP client sends first. It reads no files and makes no outside calls.
It proves the listener is bound and answering. It does not prove that processing behind the listener works.
A server that answers OPTIONS with a failing engine behind it still passes.
The probe always reports a result. Read the outcome:
| Outcome | What it means |
|---|---|
| Passed | The listener answered an OPTIONS request. |
| Unlicensed | The active license carries no ICAP entitlement, so the server refuses every ICAP request. |
| Connection refused | Nothing is listening on the port. The service is not running. |
| Timed out | The connection or the answer did not complete in time. |
| Unreachable | The port could not be reached. |
| No answer | The listener accepted the connection and closed without answering. |
| Not ICAP | Something other than the ICAP server holds the port. |
| Error status | The service is running and refusing the work. |
Through the Halo API
Every portal operation is available on the Halo API, with the same validation and the same refusals. Request and response shapes and the full error responses are in the ICAP API specification.
These roles are enforced when the appliance is deployed with bearer authentication. See API roles to action mapping and Portal roles to action mapping.
Halo keeps an audit app log of every write.