docs(admin): document ICAP antivirus configuration

[miaulalala]

☑️ Resolves

The ICAP section of the antivirus page was a single paragraph plus a screenshot, ending with
"Additional documentation is work in progress". Meanwhile the implementation in
nextcloud/files_antivirus supports two ICAP modes, six ICAP-specific settings, five distinct
response outcomes and TLS, none of which was documented. Anyone integrating an ICAP scanner had to
read the app source.

This came out of a partner conversation where the missing documentation was the blocker, so it is
written for someone configuring a real scanning appliance.

📝 What is documented

Everything below was verified against nextcloud/files_antivirus master, not from memory:

• Settings table with defaults, from lib/AppInfo/ConfigLexicon.php, plus the occ form of each.
  Includes the fact that av_port defaults to 3310, the ClamAV daemon port rather than ICAP's
  1344, so it almost always has to be changed.
• REQMOD versus RESPMOD: use what the scanner supports, RESPMOD if the vendor has no preference.
• The virus response header, which is vendor specific and fails silently in the unsafe
  direction: if av_icap_response_header does not match what the scanner sends, no threat name is
  ever read and infected files are accepted with nothing logged. Documented as a warning.
• Verification via occ files_antivirus:test and --debug, which prints the actual ICAP
  exchange.
• How scanner verdicts are handled — clean, infected, unscannable, not checked and error,
  including that blocked file types and extensions are treated as infected, so ICAP mode also
  enforces file type policy.
• Transport security, noting that av_icap_tls defaults to off.
• What is sent to the scanning service — the file contents, the path (which contains the
  account's user ID), and the uploader's IP. This matters for anyone pointing ICAP at a scanner
  outside their own infrastructure.
• How scanning works, a new general section for all scanner modes: where scanning happens in a
  file's lifecycle, and the three scan limits (av_scan_first_bytes, av_stream_max_length,
  av_max_file_size).

🖼️ Screenshots

No new images. The existing antivirus-icap.png figure is kept in place. Built locally and the
rendered page reviewed; happy to add a screenshot of the rendered section if reviewers would like
one.

⚠️ One known inconsistency, fixed by a companion PR

The new ICAP text gives the real default for av_stream_max_length (26214400, 25 MiB). The older
"Daemon (Socket)" section further up the same page states 10485760, "ten megabytes", which is
wrong against ConfigLexicon. That is a pre-existing error, fixed separately in #15539 to keep
one concern per PR, so the two figures disagree on this page until that lands.

Merge order: none required. I tested this PR merged together with #14810, #15539 and #15541:
zero conflicts in any order, and the combined file is sphinx-lint clean.

✅ Checklist

• I have built the documentation locally and reviewed the output
• sphinx-lint is clean and the build produces no warnings (-W --keep-going)
• Screenshots are included for visual changes (no new images; existing figure retained)
• I have not moved or renamed pages
• I have run codespell — not installed locally, please let CI confirm

[github-actions]

📖 Documentation Preview

🔍 Open preview →

📄 1 changed documentation page

• admin_manual/configuration_server/antivirus_configuration.rst

Last updated: Thu, 24 Sep 2026 11:52:23 GMT

[miaulalala]

/backport to stable35

[miaulalala]

/backport to stable34

[miaulalala]

/backport to stable33

[Antreesy]

Looks legit, but I don't know the app insides and don't want to yolo this. Let's ping an author or a maintainer to verify

[icewind1991]

see comments

stale