ClamAV (clamav)
Antivirus engine (clamd) of the file security pipeline, with signature updates from the internal mirror only and an authenticated HTTPS gateway in front of clamd.
Generated from catalog/services/clamav.yaml: do not edit by hand.
Summary
| Version | 1.4.6 |
| Use | install and configure |
| Layer | functional (AI catalog) |
| Category | Security and policies |
| Installation methods | podman |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | GPL-2.0-only |
| Licence policy | licence exception |
| Licence exception | LEX-022 (pending, awaiting the client) |
| Platform component | clamav |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | docker.io/clamav/clamav | 1.4.6 | GPL-2.0-only | image key clamav, used by freshclam, clamd, digest sha256:8ad6197396974726c35d017e50aaaaf4b91745726a04faec8480c203edd98052 |
| container image | docker.io/library/python | 3.12.12-alpine3.22 | PSF-2.0 | image key gateway, used by gateway, digest sha256:848ba4413eb897e225159b8fc1b02094576cbae4aa73fc13142608ae2c8c0e32 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 3072 MB of memory (blocking,
memory). - at least 2048 MB free for
/var/lib/navin(warning,disk).
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/podman.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
clamd | clamd | 3310/tcp | no |
gateway | api | 3311/tcp | yes |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
podman | yes | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Signature updater (freshclam) | worker | podman | - |
clamd daemon (clamd) | master | podman | 3310/tcp |
Scan gateway (gateway) | master | podman | 3311/tcp |
clamdruns only on a host that also runsfreshclam.gatewayruns only on a host that also runsclamd.
Single scanner (standalone) (default)
One scanner host (clamd, freshclam and the gateway).
What the mode deploys:
| Component | Placement |
|---|---|
freshclam | min 1, max 1 |
clamd | min 1, max 1 |
gateway | min 1, max 1 |
Replicated (replicated)
Two or more independent scanner hosts; the platform fails over between every gateway.
What the mode deploys:
| Component | Placement |
|---|---|
freshclam | min 2, recommended 2 |
clamd | min 2, recommended 2 |
gateway | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select ClamAV. The card shows the licence
GPL-2.0-only. -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
standalone(default),replicated. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities). -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters); the required ones are
mirror_url. Passwords left empty with a generated default are generated and sealed by the Manager. -
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Sends the EICAR test file through the gateway (must be FOUND), then a clean file (must be OK).
High availability
| Cluster | replicas (replication) |
| High availability | external (external) |
| Failover | client side (client) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | static (static) |
| Entry point | client discovery (client-discovery) |
| Official documentation | https://docs.clamav.net/ |
| References | https://docs.clamav.net/manual/Usage/Scanning.html, https://docs.clamav.net/manual/Usage/Configuration.html, https://docs.clamav.net/appendix/CvdPrivateMirror.html |
| Peer TLS parameter | tls_enabled |
| Peer authentication | Clients authenticate to every gateway with the Bearer key; clamd has no network peer. |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
standalone | standalone (standalone) | single (single) | - | 1 | One scanner host, no fault tolerance (uploads are refused in enforce mode while it is down). |
replicated | ha (ha) | active-active (active-active) | - | 2 | Two or more independent scanner hosts, each with clamd, freshclam and its gateway; the platform receives every gateway and fails over to the next one. |
Notes
- Each host loads the full signature database in memory (about 3 GB with a reload): plan the memory of every scanner host.
- Every host updates from the internal mirror on its own: the mirror must stay reachable, the last databases keep serving meanwhile and an offline import is always possible.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Gateway port (gateway_port) | port | 3311 | - | no | no | yes | HTTPS port of the scan gateway (/v1/scan, /readyz, /metrics), the only network entry point of the scanner host. |
clamd loopback port (clamd_port) | port | 3310 | - | no | no | yes | TCP port of clamd, used by the gateway of the same host only: on 127.0.0.1, or in the isolated Podman container a port never published on the host and reached by the gateway container alone (never opened in the firewall). (advanced) |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
TLS (tls_enabled) | bool | true | - | no | no | yes | Serve the gateway over HTTPS with a certificate of the manager CA (required in production). |
API key (api_key) | password | generated | - | no | yes | no | Bearer key of the gateway clients (EAI_CLAMAV_API_KEY of the platform). |
Signatures
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Internal signature mirror (mirror_url) | url | - | ^https:// | yes | no | no | HTTPS address of the internal ClamAV mirror serving main, daily and bytecode (freshclam PrivateMirror). No public update server is ever used. |
Checks per day (checks_per_day) | int | 12 | min 1, max 50 | no | no | no | Number of freshclam checks of the internal mirror per day. |
Scan limits
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Largest file (stream_max_length_mb) | int | 100 | min 1, max 4000, MB | no | no | no | StreamMaxLength of clamd and body limit of the gateway (413 above); keep it at least the platform limit EAI_FILE_SCAN_MAX_BYTES. |
Maximum scanned data (max_scan_size_mb) | int | 400 | min 1, max 4000, MB | no | no | no | MaxScanSize: data scanned per file, archives included (beyond it Heuristics.Limits.Exceeded is reported). |
Maximum inner file (max_file_size_mb) | int | 100 | min 1, max 4000, MB | no | no | no | MaxFileSize: largest file scanned, inner archive members included. |
Archive depth (max_recursion) | int | 16 | min 1, max 64 | no | no | no | MaxRecursion: nesting of archives and embedded objects. |
Files per archive (max_files) | int | 10000 | min 1, max 1000000 | no | no | no | MaxFiles: files scanned inside one archive. |
Scan timeout (scan_timeout_s) | int | 120 | min 5, max 900, s | no | no | no | Longest scan of one file (clamd MaxScanTime and ReadTimeout, gateway timeout towards clamd). |
Scan threads (max_threads) | int | 8 | min 1, max 64 | no | no | no | MaxThreads of clamd: concurrent scans on the host. (recommended clamp(host.cpu_count, 2, 16)) |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
api | http | gateway | 3311 (gateway_port) | - | tls_enabled | max_file_size, max_scan_size, max_files, max_recursion, stream_max_length | api_key | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Signature status (signature_status) | freshclam | every host | Engine version and every signature database of each scanner host, with its digital signature checked by sigtool. |
Update the signatures (update_signatures) | freshclam | every host | Runs freshclam now against the internal mirror on each scanner host; clamd reloads the new databases. |
Import signatures offline (import_signatures) | freshclam | every host | Installs the .cvd and .cld databases of a directory of the host: each one is verified by sigtool first, then installed atomically and clamd reloads locally. Nothing is installed when one database fails. |
clamd logs (logs) | clamd | chosen host | Last lines of the clamd journal. |
Command parameters
| Command | Parameter | Type | Default | Required | Description |
|---|---|---|---|---|---|
import_signatures | Directory (directory) | path | - | yes | Absolute directory of the host holding main, daily and bytecode (.cvd or .cld). |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
freshclam | {{ paths.etc }}/signatures.sh has-db | 90 retries; interval 10 s; timeout 10 s |
clamd | /usr/bin/podman exec navin-{{ service.name }}-clamd clamdscan --config-file=/etc/navin-clamav/clamd.conf --ping=1 | 60 retries; interval 5 s; timeout 10 s |
gateway | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.gateway_port }}/healthz | Expected 200; 30 retries; interval 2 s; timeout 5 s |
Readiness (service check)
| Check | Details |
|---|---|
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.gateway_port }}/readyz | Expected 200; Expected "status": "ready"; 10 retries; interval 5 s; timeout 10 s |
Smoke test
Sends the EICAR test file through the gateway (must be FOUND), then a clean file (must be OK). (gateway: eicar_found, clean_ok)
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
memory | memory_mb {"min": 3072} | at least 3072 MB of memory | blocking | clamd |
disk | disk_free_mb {"path": "/var/lib/navin", "min": 2048} | at least 2048 MB free for /var/lib/navin | warning | freshclam |
gateway_port_free | port_free {"param": "gateway_port"} | port 3311 free on the host | blocking | gateway |
clamd_port_free | port_free {"param": "clamd_port"} | port 3310 free on the host | blocking | clamd |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Quick links
- Gateway metrics:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.gateway_port }}/metrics
Upstream documentation
- Homepage: https://www.clamav.net
- Source: https://github.com/Cisco-Talos/clamav
- High availability: https://docs.clamav.net/
- High availability: https://docs.clamav.net/manual/Usage/Scanning.html
- High availability: https://docs.clamav.net/manual/Usage/Configuration.html
- High availability: https://docs.clamav.net/appendix/CvdPrivateMirror.html