Documentation / clamav
ClamAV Helm Chart
Deploys ClamAV as a shared in-cluster malware scanner, with ClamAV’s own
Debian-based image (clamav/clamav-debian), for amd64 and arm64. clamd
serves scans, and freshclam keeps the signatures current and tells clamd
to reload them.
Applications send files to clamd for scanning over its TCP protocol
(INSTREAM, port 3310) before storing them.
Design
A single replica with a persistent volume at /var/lib/clamav caching
the signature database across restarts. The Pod has three parts, sharing that
volume and /run/clamav:
- an init container downloads the database when the volume holds none, because
clamddoes not start without one; - a
clamdcontainer serves scans on port 3310; - a
freshclamcontainer checks for new signaturesfreshclam.checksPerDaytimes a day (12 by default) and tellsclamdto reload through the shared socket. If it stops, the kubelet restarts that container alone.
The signature database is held in memory, and twice for a moment while a new
one is loaded, so budget about 1.5 to 2.5 GiB for clamd. Scale out only if
scan throughput ever demands it.
The image is pinned by digest. Upstream rebuilds under the same tag, so a tag
alone would run whatever was copied last. If you set image.repository or
image.tag to an image of your own, also set image.digest to its digest, or
to "" to pull by tag.
Requirements and outbound traffic
The chart needs Kubernetes 1.20 or later: its container uses a startup probe, generally available from that version, and otherwise only stable APIs.
freshclam downloads the signature database from ClamAV’s servers
(database.clamav.net), so the Pod needs outbound HTTPS to them: on first
start, when the volume holds no signatures, and afterwards for each update.
Where the Pod has no direct route to ClamAV’s servers, set freshclam’s own
directives in freshclam.extraConfig. They apply to the first download and to
the updates. Through a proxy:
freshclam:
extraConfig: |
HTTPProxyServer proxy.example.com
HTTPProxyPort 3128
Or from a mirror of your own:
freshclam:
extraConfig: |
PrivateMirror clamav-mirror.example.com
clamd.extraConfig adds clamd.conf directives in the same way. The image’s
CLAMD_CONF_* and FRESHCLAM_CONF_* environment variables do not apply: they
are read by the image’s own entrypoint, which this chart does not use.
ClamAV 1.4
ClamAV 1.4 is ClamAV’s long-term support line. It receives security fixes until 15 August 2027, and may download signatures until 15 August 2028.
Scan size and disk
clamd.streamMaxLength (100M, ClamAV’s own default) is the largest file
clamd accepts over INSTREAM. A larger stream is refused. An application’s
own size limit must not exceed it.
clamd holds each streamed file in /tmp while it scans it, with up to 10
scans at once, plus the files it unpacks from archives. /tmp is on disk, not
in memory, so these files do not count against the memory limit, and is
limited to clamd.tmpSize (2Gi). Keep clamd.tmpSize at least ten times
clamd.streamMaxLength, with room to unpack, and keep the container’s
ephemeral-storage limit (3Gi) above it.
Connecting an application
Applications reach clamd through the chart’s Service:
<release>-clamav.<namespace>.svc.cluster.local:3310
The Pods carry the label app.kubernetes.io/name: clamav, for a NetworkPolicy
that admits an application to them.
Pod Security and quotas
The chart meets the Kubernetes restricted Pod Security Standard. Every
container runs as the image’s clamav user (uid and gid 1000) with
runAsNonRoot, drops every capability and adds none, disallows privilege
escalation, uses the RuntimeDefault seccomp profile and a read-only root
filesystem. fsGroup: 1000 makes the signature volume writable.
Every container, the init container included, declares CPU, memory and ephemeral-storage requests and limits, so the Pod is admitted in a namespace whose ResourceQuota requires them.
Upgrading from 1.0
Version 1.1 changes the image from clamav/clamav (Alpine) to
clamav/clamav-debian, in which the clamav user is uid 1000 rather than 100,
and runs it as that user rather than as root.
- If you override
securityContext,podSecurityContext,runAsUserorfsGroup, update them for uid and gid 1000, or remove your overrides. - The existing signature volume is taken over through
fsGroup. Withpersistence.existingClaim, or storage that ignoresfsGroup, make its files writable by uid or gid 1000 before upgrading. - Settings made through
CLAMD_CONF_*orFRESHCLAM_CONF_*inextraEnvmove toclamd.extraConfigandfreshclam.extraConfig.
Key values
| Key | Default | Description |
|---|---|---|
replicaCount |
1 |
Number of clamd pods |
image.repository / .tag / .digest |
1x.ax/tersane/core/clamav/clamav-debian / the ClamAV release named in the chart’s appVersion / pinned |
ClamAV’s own Debian-based image, amd64 and arm64 |
imagePullSecrets |
[{name: 1x-ax}] |
Pull secret for 1x.ax, which must exist in the release’s namespace |
service.port |
3310 |
clamd TCP listener |
persistence.enabled |
true |
Cache the signature DB on a PVC |
persistence.size |
2Gi |
Signature DB volume size |
clamd.streamMaxLength |
100M |
Largest file accepted over INSTREAM |
clamd.tmpSize |
2Gi |
clamd’s /tmp, on disk |
clamd.extraConfig |
"" |
Further clamd.conf lines |
freshclam.checksPerDay |
12 |
Signature checks a day |
freshclam.extraConfig |
"" |
Further freshclam.conf lines, such as a proxy or a private mirror |
resources |
250m, 1536Mi, 512Mi requested; 2 CPUs, 2560Mi, 3Gi limits | clamd’s CPU, memory and ephemeral storage |
freshclam.resources |
50m, 256Mi, 64Mi requested; 1 CPU, 1536Mi, 1Gi limits | freshclam’s, and the first download’s |
Render / lint
helm lint charts/clamav
./charts/clamav/tests/render-defaults.sh