====== AV-SPAM (Anti-Spam) ======

The **AV-SPAM** module provides advanced spam and virus filtering for your BlueOnyx mail server using **Rspamd**, a modern, high-performance spam filtering engine. This replaces the older SpamAssassin-based solution with a faster, more accurate, and easier-to-configure system.

===== Overview =====

The AV-SPAM settings page is found under **Server Management > AV-SPAM**. It consists of several tabs that control different aspects of spam filtering.

===== Tabs =====

==== General ====

The **General** tab contains the main on/off switch:

  * **Enable AV-SPAM** — Master toggle to enable or disable the entire spam filtering system.

When disabled, all spam filtering is bypassed and mail flows through without scanning.

==== Scoring ====

The **Scoring** tab configures the spam score thresholds and subject line modifications:

  * **Spam subject tag** — Format string for modified subject lines. Use ``%d`` for the spam score and ``%s`` for the original subject. Default: ``***SPAM(%d)*** %s``
  * **Add header score** — Score at which an ``X-Spam: YES`` header is added to the message. Default: 5.0
  * **Reject score** — Score at which incoming mail is rejected outright. Default: 15.0
  * **Greylist score** — Score at which greylisting is temporarily applied. Default: 4.0
  * **Enable X-Spam-Report** — Adds a detailed ``X-Spam-Report`` header showing all matching rules and their scores.

**Note:** Scoring is inherited from server defaults at the Vsite and User level. SiteAdmins can override Vsite scores, and users can override their personal scores.

==== Sender Lists ====

The **Sender Lists** tab manages allow/block lists at the server scope:

  * **Sender IP blacklist / whitelist** — Block or allow specific IP addresses or CIDR ranges.
  * **Sender domain blacklist / whitelist** — Block or allow entire sender domains.
  * **Sender email blacklist / whitelist** — Block or allow specific email addresses.

**Important:** These rules match the **SMTP envelope sender** (the ``MAIL FROM`` address), not the visible ``From:`` header in the message body. Services like Zoom may send from bounce hosts (e.g., ``bounce-sg.zoom.us``) even though the visible ``From`` shows ``no-reply@zoom.us``.

Sender lists also exist at the **Vsite** and **User** scope, allowing SiteAdmins and end users to manage their own allow/block lists.

==== GeoIP ====

The **GeoIP** tab controls country-based filtering:

  * **Banned countries** — Check countries to block all incoming mail from those regions. Default banned countries include high-spam-volume regions.
  * **Whitelisted countries** — Countries that are always allowed, bypassing GeoIP checks.
  * **GeoIP limits** — Server-wide, Vsite-level, and User-level mail volume limits based on geographic origin.
  * **Enforce limits** — Enable automatic suspension when limits are exceeded.

GeoIP data is provided by the Milter-GeoIP component, which tracks country-of-origin for every incoming connection.

==== Custom Rules ====

The **Custom Rules** tab provides a scope-aware rule editor:

  * **Scope** — Choose between Server, Vsite, or User scope.
  * **Rule List** — View existing rules with Symbol, Target, Pattern, Score, Description, and Actions columns.
  * **Rule Editor** — Create or edit custom Rspamd rules using multimap expressions or SpamAssassin-style syntax.

Rules are stored in plain text files:
  * Server: ``/etc/mail/rspamd/custom_rules.rules``
  * Vsite: ``/home/.sites/siteN/wwwroot/rspamd/custom_rules.rules``
  * User: ``~username/.rspamd/custom_rules.rules``

User custom rules inherit Vsite enablement, so SiteAdmins can manage user-scoped rules.

==== Services ====

The **Services** tab configures optional Rspamd modules:

  * **ClamAV integration** — Enable virus scanning via ClamAV. Configure host, port, and max scan size.
  * **Greylisting** — Temporarily defer mail from unknown senders.
  * **SPF** — Verify Sender Policy Framework records.
  * **DMARC** — Enforce Domain-based Message Authentication.
  * **ARC** — Authenticate Received Chain for forwarded mail.
  * **Bayes** — Machine learning based on Redis/Valkey backend.
  * **Neural** — Neural network classification (disabled by default).
  * **Fuzzy checks** — Fuzzy hash matching against known spam.
  * **RBL / SURBL / URIBL** — Real-time blacklist lookups.
  * **Ratelimiting** — Connection and message rate limiting with configurable burst, window, and daily maximums.
  * **Redis/Valkey history** — Configure history row count (default: 1000) and expiration (default: 7 days).
  * **Max message size** — Upper limit for scanned messages.
  * **Scan outbound** — Also scan outgoing mail for spam/viruses.

===== Inheritance Model =====

Settings flow from Server → Vsite → User:

  * **Server defaults** apply to all sites and users unless overridden.
  * **Vsite overrides** allow SiteAdmins to customize settings for their site.
  * **User overrides** allow end users to set personal thresholds and delivery actions.

Empty Vsite/User override objects are expected and correct when nothing has been changed from the server default.

===== User Delivery Actions =====

At the user level, the following SPAM delivery actions are available:

  * **DISABLE** — No spam filtering (deliver all mail normally).
  * **DELIVER** — Deliver spam to inbox (with modified subject).
  * **FILE** — Deliver spam to a dedicated folder (requires Procmail).
  * **DELETE** — Discard spam silently.

The system automatically writes or removes ``~user/.procmailrc`` based on the selected action.

===== See Also =====

  * [[userguide:email:avspamstats|AV-SPAM Stats]] — View filtering statistics and history

----