From 43215e257d1272cdac05b36410e0ec11a9084003 Mon Sep 17 00:00:00 2001 From: Davide Principi Date: Tue, 20 Oct 2026 11:49:06 +0200 Subject: [PATCH] docs(mail): move bypass rules to own section Bypass rules skip both the antivirus and the antispam checks, but they were described under Antispam only, and the Antivirus section said that infected messages are always discarded. Describe the bypass rules in their own Filter subsection, as a temporary workaround for exceptional cases, and warn that a matching message is not scanned for viruses. Align the sender rules with the Mail module change: they now match the envelope sender and the "From" header. Block lists still match the envelope sender only. Keep a link to the Rspamd web interface in the Antispam section. Assisted-by: Claude Code:claude-opus-5-5 --- .../administrator-manual/applications/mail.md | 44 ++++++++++++++----- .../administrator-manual/applications/mail.md | 44 ++++++++++++++----- 2 files changed, 64 insertions(+), 24 deletions(-) diff --git a/docs/administrator-manual/applications/mail.md b/docs/administrator-manual/applications/mail.md index 558aae6a8..6d705ac8e 100644 --- a/docs/administrator-manual/applications/mail.md +++ b/docs/administrator-manual/applications/mail.md @@ -180,11 +180,13 @@ All transiting email messages are subjected to a list of checks that fall into t - Antivirus - Antispam +[Bypass rules](#bypass-rules) can exclude messages from both kinds of checks. + Navigate to the `Filter` page to adjust their settings. ### Antivirus {#anti-virus} -The ClamAV antivirus component finds email messages containing viruses. Infected messages are discarded. The virus signature database is checked for updates every hour. +The ClamAV antivirus component finds email messages containing viruses. Infected messages are discarded. Messages that match a [bypass rule](#bypass-rules) are not scanned. The virus signature database is checked for updates every hour. The default ClamAV signatures database is normally disabled because it consumes a large amount of memory. Select the `Enable ClamAV official signatures` checkbox if desired. @@ -208,17 +210,7 @@ The spam score thresholds can be configured under the `Antispam` section of the - `Deny message spam threshold` instead regulates the score that is considered too high to accept a message. If the score exceeds this value, the filter rejects the message completely. - Under the `Advanced` section it is possible to enable the `Greylist threshold`. When the message score exceeds this limit the filter asks the sender to try again the message delivery at later time. The *Greylist* spam-fighting method assumes that spammers dislike delivery retries. It is disabled by default because it introduces delivery delays also for legitimate senders. -In some cases an email client, recipient, or sender must bypass the filter checks: the `Bypass rules` section allows to define a set of rules based on the follwing criteria: - -- Sender IP address or network (CIDR format). -- Complete sender email address. -- Sender email domain (exact match). -- Complete recipient email address. -- Recipient email domain (exact match). - -Note that address and domain-based rules match the *envelope sender address*, which may differ from the message's "From" address in some cases (e.g. mailing lists). - -To view message details such as the envelope sender address, access advanced settings, or review recent Rspamd activity, see [Rspamd web interface](#rspamd-web-interface). +To view message details, access advanced settings, or review recent Rspamd activity, see [Rspamd web interface](#rspamd-web-interface). The Bayesian statistical filters can then be trained with any IMAP client by simply moving a message in and out of the Junk folder. As a prerequisite, the Junk folder must be enabled, as explained in [Mailboxes](#mail-mailboxes-settings). @@ -245,6 +237,32 @@ It is important to understand how the Bayesian tests really work: As the system receives that information, the progress of bayesian filter training can be monitored from the Rspamd web UI. +### Bypass rules {#bypass-rules} + +Bypass rules are a temporary workaround for exceptional cases, to receive messages that the filter would otherwise reject, for example because the sender's mail server is misconfigured. A message that matches a bypass rule skips both the antivirus and the antispam checks. + +Needing a bypass rule for a long time is a symptom that something else needs fixing, for example the sender's SPF, DKIM or DMARC records, or the spam thresholds. Remove each rule as soon as the problem is solved. + +Open the `Bypass rules` page from the `Filter` page to define a set of rules based on the following criteria: + +- Sender IP address or network (CIDR format). +- Complete sender email address. +- Sender email domain (exact match). +- Complete recipient email address. +- Recipient email domain (exact match). + +:::warning + +A message that matches a bypass rule is delivered even if it contains a virus. Use bypass rules sparingly, temporarily, and only in exceptional cases. + +::: + +Sender address and domain rules match both the *envelope sender address* and the address in the message's "From" header. The two addresses differ, for example, when a newsletter service or a mailing list sends a message on behalf of the sender. Recipient rules match the envelope recipient addresses. + +Both sender addresses are easy to forge: anybody can send a message that appears to come from a sender listed in a bypass rule. Add only senders you trust, and prefer complete email addresses to whole domains. Never add your own mail domains, or the domains of public email providers. + +To find the envelope sender address of a message, or to check which rule matched it (symbols starting with `BYPASS_`), see the **History** tab of the [Rspamd web interface](#rspamd-web-interface). + ### Rspamd web interface {#rspamd-web-interface} The Rspamd web interface can be opened by clicking the **Open Rspamd** button in the top-right corner of the Filter page or by browsing to `https:///rspamd` or `https:///rspamd`. You will need your cluster-admin credentials to log in. @@ -259,6 +277,8 @@ To reject emails by domain, add for example `domain.tld` to the `/var/lib/rspamd To reject emails by top-level domain or domain suffix, `.tld` or `.domain.tld` may be added to the `/var/lib/rspamd/block_sender_domain_suffix.map` list. +Unlike bypass rules, these lists match only the envelope sender address, not the "From" header. + Do not modify the other lists, as they are preconfigured. ## Queue diff --git a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/applications/mail.md b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/applications/mail.md index f3b7b1c7f..dab74f07f 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/applications/mail.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/applications/mail.md @@ -180,11 +180,13 @@ Tutti i messaggi email in transito sono sottoposti a un elenco di controlli che - Antivirus - Antispam +Le [regole di bypass](#bypass-rules) possono escludere i messaggi da entrambi i tipi di controllo. + Vai alla pagina `Filter` per modificarne le impostazioni. ### Antivirus {#anti-virus} -Il componente antivirus ClamAV individua i messaggi email che contengono virus. I messaggi infetti vengono scartati. Il database delle firme dei virus viene controllato ogni ora per gli aggiornamenti. +Il componente antivirus ClamAV individua i messaggi email che contengono virus. I messaggi infetti vengono scartati. I messaggi che corrispondono a una [regola di bypass](#bypass-rules) non vengono analizzati. Il database delle firme dei virus viene controllato ogni ora per gli aggiornamenti. Il database predefinito delle firme ufficiali di ClamAV è normalmente disabilitato perché consuma molta memoria. Se vuoi usarlo, seleziona la casella `Enable ClamAV official signatures`. @@ -208,17 +210,7 @@ Le soglie del punteggio spam possono essere configurate nella sezione `Antispam` - `Deny message spam threshold` regola invece il punteggio considerato troppo alto per accettare un messaggio. Se il punteggio supera questo valore, il filtro rifiuta completamente il messaggio. - Nella sezione `Advanced` è possibile abilitare `Greylist threshold`. Quando il punteggio del messaggio supera questo limite, il filtro chiede al mittente di ritentare la consegna più tardi. Il metodo antispam *Greylist* presuppone che gli spammer non gradiscano i nuovi tentativi di consegna. È disabilitato per impostazione predefinita perché introduce ritardi di consegna anche per i mittenti legittimi. -In alcuni casi un client email, un destinatario o un mittente devono bypassare i controlli del filtro: la sezione `Bypass rules` consente di definire un insieme di regole basate sui seguenti criteri: - -- indirizzo IP o rete del mittente (formato CIDR) -- indirizzo email completo del mittente -- dominio email del mittente (corrispondenza esatta) -- indirizzo email completo del destinatario -- dominio email del destinatario (corrispondenza esatta) - -Tieni presente che le regole basate su indirizzo e dominio corrispondono all'*envelope sender address*, che in alcuni casi può differire dall'indirizzo "From" del messaggio, ad esempio nelle mailing list. - -Per visualizzare dettagli del messaggio come l'envelope sender address, per accedere alle impostazioni avanzate o per controllare l'attività recente di Rspamd, consulta [Interfaccia web di Rspamd](#rspamd-web-interface). +Per visualizzare i dettagli dei messaggi, accedere alle impostazioni avanzate o controllare l'attività recente di Rspamd, consulta [Interfaccia web di Rspamd](#rspamd-web-interface). I filtri statistici bayesiani possono poi essere addestrati con qualsiasi client IMAP semplicemente spostando un messaggio dentro e fuori dalla cartella Junk. Come prerequisito, la cartella Junk deve essere abilitata, come spiegato in [Caselle di posta](#mail-mailboxes-settings). @@ -245,6 +237,32 @@ L'addestramento del filtro bayesiano si applica a tutti gli utenti del sistema, Man mano che il sistema riceve queste informazioni, l'avanzamento dell'addestramento del filtro bayesiano può essere monitorato dall'interfaccia web di Rspamd. +### Regole di bypass {#bypass-rules} + +Le regole di bypass sono una soluzione temporanea per casi eccezionali, per ricevere messaggi che altrimenti il filtro rifiuterebbe, per esempio perché il server di posta del mittente è configurato in modo errato. Un messaggio che corrisponde a una regola di bypass salta sia i controlli antivirus sia quelli antispam. + +Se una regola di bypass serve a lungo, è il sintomo che c'è qualcos'altro da correggere, per esempio i record SPF, DKIM o DMARC del mittente, oppure le soglie antispam. Rimuovi ogni regola appena il problema è risolto. + +Apri la pagina `Bypass rules` dalla pagina `Filter` per definire un insieme di regole basate sui seguenti criteri: + +- indirizzo IP o rete del mittente (formato CIDR) +- indirizzo email completo del mittente +- dominio email del mittente (corrispondenza esatta) +- indirizzo email completo del destinatario +- dominio email del destinatario (corrispondenza esatta) + +:::warning + +Un messaggio che corrisponde a una regola di bypass viene consegnato anche se contiene un virus. Usa le regole di bypass con moderazione, solo temporaneamente e solo in casi eccezionali. + +::: + +Le regole basate su indirizzo e dominio del mittente corrispondono sia all'*envelope sender address* sia all'indirizzo nell'intestazione "From" del messaggio. I due indirizzi sono diversi, per esempio, quando un servizio di newsletter o una mailing list invia un messaggio per conto del mittente. Le regole del destinatario corrispondono agli indirizzi dei destinatari della busta SMTP. + +Entrambi gli indirizzi del mittente sono facili da falsificare: chiunque può inviare un messaggio che sembra provenire da un mittente presente in una regola di bypass. Aggiungi solo mittenti di cui ti fidi, e preferisci gli indirizzi email completi ai domini interi. Non aggiungere mai i tuoi domini di posta, né i domini dei provider email pubblici. + +Per trovare l'envelope sender address di un messaggio, o per verificare quale regola gli è stata applicata (simboli che iniziano con `BYPASS_`), consulta la scheda **History** dell'[interfaccia web di Rspamd](#rspamd-web-interface). + ### Interfaccia web di Rspamd {#rspamd-web-interface} L'interfaccia web di Rspamd può essere aperta facendo clic sul pulsante **Open Rspamd** nell'angolo in alto a destra della pagina Filter oppure visitando `https:///rspamd` o `https:///rspamd`. Per accedere ti serviranno le credenziali di cluster-admin. @@ -259,6 +277,8 @@ Per rifiutare email in base al dominio, aggiungi per esempio `domain.tld` all'el Per rifiutare email in base al dominio di primo livello o al suffisso del dominio, puoi aggiungere `.tld` oppure `.domain.tld` all'elenco `/var/lib/rspamd/block_sender_domain_suffix.map`. +A differenza delle regole di bypass, questi elenchi corrispondono solo all'envelope sender address, non all'intestazione "From". + Non modificare gli altri elenchi, perché sono preconfigurati. ## Coda