:pmg-toplevel:
endif::manvolnum[]
-{pmg} is usually configured using the web-based Graphical User
-Interface (GUI), but it is also possible to directly edit the
-configuration files, use the REST API over 'https'
-or the command line tool `pmgsh`.
+{pmg} is usually configured using the web-based Graphical User Interface (GUI),
+but it is also possible to directly edit the configuration files, using the
+REST API over 'https' or the command line tool `pmgsh`.
-The command line tool `pmgconfig` is used to simplify some common
-configuration tasks, i.e. to generate cerificates and to rewrite
-service configuration files.
+The command line tool `pmgconfig` is used to simplify some common configuration
+tasks, such as generating certificates and rewriting service configuration
+files.
-NOTE: We use a Postgres database to store mail filter rules and
-statistic data. See chapter xref:chapter_pmgdb[Database Management]
-for more information.
+NOTE: We use a Postgres database to store mail filter rules and statistical
+data. See chapter xref:chapter_pmgdb[Database Management] for more information.
Configuration files overview
`/etc/network/interfaces`::
-Network setup. We never modify this files directly. Instead, we write
-changes to `/etc/network/interfaces.new`. When you reboot, we rename
-the file to `/etc/network/interfaces`, so any changes gets activated
-on the next reboot.
+Network setup. We never modify this file directly. Instead, we write
+changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
+the file to `/etc/network/interfaces`, thus applying the changes.
+
+`/etc/resolv.conf`::
+
+DNS search domain and nameserver setup. {pmg} uses the search domain setting
+to create the FQDN and domain name used in the postfix configuration.
+
+`/etc/hostname`::
+
+The system's hostname. {pmg} uses the hostname to create the FQDN used
+in the postfix configuration.
+
+`/etc/hosts`::
+
+Static table lookup for hostnames.
`/etc/pmg/pmg.conf`::
-Stores common administration options, i.e. the spam and mail proxy setup.
+Stores common administration options, such as the spam and mail proxy
+configuration.
`/etc/pmg/cluster.conf`::
The list of relay domains.
+`/etc/pmg/dkim/domains`::
+
+The list of domains for outbound DKIM signing.
+
`/etc/pmg/fetchmailrc`::
Fetchmail configuration (POP3 and IMAP setup).
Stores your subscription key and status.
+`/etc/pmg/tls_policy`::
+
+TLS policy for outbound connections.
+
+`/etc/pmg/tls_inbound_domains`::
+
+Sender domains for which TLS is enforced on inbound connections.
+
`/etc/pmg/transports`::
Message delivery transport setup.
GUI user configuration.
+`/etc/mail/spamassassin/custom.cf`::
+
+Custom {spamassassin} setup.
+
+`/etc/mail/spamassassin/pmg-scores.cf`::
+
+Custom {spamassassin} rule scores.
Keys and Certificates
---------------------
`/etc/pmg/pmg-api.pem`::
-Key and certificate (combined) used be the HTTPs server (API).
+Key and certificate (combined) used by the HTTPS server (API).
`/etc/pmg/pmg-authkey.key`::
-Privat key use to generate authentication tickets.
+Private key used to generate authentication tickets.
`/etc/pmg/pmg-authkey.pub`::
-Public key use to verify authentication tickets.
+Public key used to verify authentication tickets.
`/etc/pmg/pmg-csrf.key`::
Key and certificate (combined) to encrypt mail traffic (TLS).
+`/etc/pmg/dkim/<selector>.private`::
+Key for DKIM signing mails with selector '<selector>'.
+
+
+[[pmgconfig_template_engine]]
Service Configuration Templates
-------------------------------
-{pmg}
+{pmg} uses various services to implement mail filtering, for example,
+the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
+engine, and the Apache {spamassassin} project. These services use
+separate configuration files, so we need to rewrite those files when the
+configuration is changed.
+We use a template-based approach to generate these files. The {tts} is
+a well known, fast and flexible template processing system. You can
+find the default templates in `/var/lib/pmg/templates/`. Please do not
+modify these directly, otherwise your modifications will be lost on the
+next update. Instead, copy the template you wish to change to
+`/etc/pmg/templates/`, then apply your changes there.
+Templates can access any configuration settings, and you can use the
+`pmgconfig dump` command to get a list of all variable names:
+
+----
+# pmgconfig dump
+...
+dns.domain = yourdomain.tld
+dns.hostname = pmg
+ipconfig.int_ip = 192.168.2.127
+pmg.admin.advfilter = 1
+...
+----
+
+The same tool is used to force the regeneration of all template-based
+configuration files. You need to run the following after modifying a template,
+or when you directly edit configuration files:
+
+----
+# pmgconfig sync --restart 1
+----
+
+The above command also restarts services if the underlying configuration
+files are changed. Please note that this is automatically done when
+you change the configuration using the GUI or API.
+
+NOTE: Modified templates from `/etc/pmg/templates/` are automatically
+synced from the master node to all cluster members.
+
+[[pmgconfig_whitelist_overview]]
+White- and Blacklists
+---------------------
+
+{pmg} has multiple white- and blacklists. It differentiates between the
+xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
+and the user whitelist.
+In addition to the whitelists, there are two separate blacklists: the rule-based
+blacklist and the user blacklist.
+
+SMTP Whitelist
+~~~~~~~~~~~~~~
+
+The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
+greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
+dialogue.
+
+Rule-based White-/Blacklist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
+rules. They work by checking the attached 'Who' objects, containing, for
+example, a domain or a mail address for a match. If it matches, the assigned
+action is used, which by default is 'Accept' for the whitelist rule and 'Block'
+for the blacklist rule. In the default setup, the blacklist rule has priority
+over the whitelist rule and spam checks.
+
+User White-/Blacklist
+~~~~~~~~~~~~~~~~~~~~~
+
+The user white- and blacklist are user specific. Every user can add mail addresses
+to their white- and blacklist. When a user adds a mail address to the whitelist,
+the result of the spam analysis will be discarded for that recipient. This can
+help in the mail being accepted, but what happens next still depends on the
+other rules. In the default setup, this results in the mail being accepted for
+this recipient.
+
+For mail addresses on a user's blacklist, the spam score will be increased by
+100. What happens when a high spam score is encountered still depends on the
+rule system. In the default setup, it will be recognized as spam and quarantined
+(spam score of 3 or higher).
+
+[[pmgconfig_systemconfig]]
System Configuration
--------------------
~~~~~~~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-network-config.png[]
+[thumbnail="pmg-gui-network-config.png", big=1]
endif::manvolnum[]
-Normally the network and time is already configured when you visit the
-GUI. The installer asks for those setting and sets up the correct
-values.
+As network and time are configured in the installer, these generally do not
+need to be configured again in the GUI.
The default setup uses a single Ethernet adapter and static IP
assignment. The configuration is stored at '/etc/network/interfaces',
-and the actual network setup is done the standard Debian way using
+and the actual network setup is done the standard Debian way, using the
package 'ifupdown'.
.Example network setup '/etc/network/interfaces'
.DNS recommendations
Many tests to detect SPAM mails use DNS queries, so it is important to
-have a fast and reliable DNS server. We also query some public
+have a fast and reliable DNS server. We also query some publicly
available DNS Blacklists. Most of them apply rate limits for clients,
so they simply will not work if you use a public DNS server (because
they are usually blocked). We recommend to use your own DNS server,
-which need to be configured in 'recursive' mode.
+which needs to be configured in 'recursive' mode.
Options
~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-system-options.png[]
+[thumbnail="pmg-gui-system-options.png", big=1]
endif::manvolnum[]
+
+These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
include::pmg.admin-conf-opts.adoc[]
-Backup and Restore
-~~~~~~~~~~~~~~~~~~
+include::pmg-ssl-certificate.adoc[]
+
+Mail Proxy Configuration
+------------------------
+
+[[pmgconfig_mailproxy_relaying]]
+Relaying
+~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
+endif::manvolnum[]
+
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`. Some of these correspond
+to postfix options in the `main.cf` (see the
+https://www.postfix.org/postconf.5.html[postconf documentation]).
+
+They use the following configuration keys:
+
+include::pmg.mail-relaying-conf-opts.adoc[]
+
+[[pmgconfig_mailproxy_relay_domains]]
+Relay Domains
+~~~~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
+endif::manvolnum[]
+
+A list of relayed mail domains, that is, what destination domains this
+system will relay mail to. The system will reject incoming mails to
+other domains.
+
+
+[[pmgconfig_mailproxy_ports]]
+Ports
+~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-ports.png", big=1]
+endif::manvolnum[]
+
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`. Many of these correspond
+to postfix options in the `main.cf` (see the
+https://www.postfix.org/postconf.5.html[postconf documentation]).
+
+They use the following configuration keys:
+
+include::pmg.mail-ports-conf-opts.adoc[]
+
+
+[[pmgconfig_mailproxy_options]]
+Options
+~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-options.png", big=1]
+endif::manvolnum[]
+
+These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.mail-options-conf-opts.adoc[]
+
+
+[[pmgconfig_mailproxy_before_after_queue]]
+Before and After Queue scanning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Email scanning can happen at two different stages of mail-processing:
+
+* Before-queue filtering: During the SMTP session, after the complete message
+ has been received (after the 'DATA' command).
+
+* After-queue filtering: After initially accepting the mail and putting it on
+ a queue for further processing.
+
+Before-queue filtering has the advantage that the system can reject a mail (by
+sending a permanent reject code '554'), and leave the task of notifying the
+original sender to the other mail server. This is of particular advantage if
+the processed mail is a spam message or contains a virus and has a forged
+sender address. Sending out a notification in this situation leads to so-called
+'backscatter' mail, which might cause your server to get listed as spamming on
+RBLs (Real-time Blackhole List).
+
+After-queue filtering has the advantage of providing faster delivery of
+mails for the sending servers, since queuing emails is much faster than
+analyzing them for spam and viruses.
+
+If a mail is addressed to multiple recipients (for example, when multiple
+addresses are subscribed to the same mailing list), the situation is more
+complicated; your mail server can only reject or accept the mail for all
+recipients, after having received the complete message, while your rule setup
+might accept the mail for part of the recipients and reject it for others. This
+can be due to a complicated rule setup, or if your users use the 'User White-
+and Blacklist' feature.
+
+If the resulting action of the rule system is the same for all recipients, {pmg}
+responds accordingly, if configured for before-queue filtering (sending '554'
+for a blocked mail and '250' for an accepted or quarantined mail). If some
+mailboxes accept the mail and some reject it, the system has to accept the mail.
+
+Whether {pmg} notifies the sender that delivery failed for some recipients by
+sending a non-delivery report, depends on the 'ndr_on_block' setting in
+'/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
+NDRs being sent to the (possibly forged) sender and thus minimizes the chance
+of getting your IP listed on an RBL. However in certain environments, it can be
+unacceptable not to inform the sender about a rejected mail.
+
+The setting has the same effect if after-queue filtering is configured, with
+the exception that an NDR is always sent out, even if all recipients block the
+mail, since the mail already got accepted before being analyzed.
+
+The details of integrating the mail proxy with {postfix} in both setups are
+explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
+
+
+[[pmgconfig_mailproxy_greylisting]]
+Greylisting
+~~~~~~~~~~~
+
+Greylisting is a technique for preventing unwanted messages from reaching the
+resource intensive stages of content analysis (virus detection and spam
+detection). By initially replying with a temporary failure code ('450') to
+each new email, {pmg} tells the sending server that it should queue the
+mail and retry delivery at a later point. Since certain kinds of spam get
+sent out by software which has no provisioning for queuing, these mails are
+dropped without reaching {pmg} or your mailbox.
+
+The downside of greylisting is the delay introduced by the initial deferral of
+the email, which usually amounts to less than 30 minutes.
+
+In order to prevent unnecessary delays in delivery from known sources, emails
+coming from a source for a recipient, which have passed greylisting in the
+past are directly passed on: For each email the triple '<sender network,
+sender email, recipient email>' is stored in a list, along with the time when
+delivery was attempted. If an email fits an already existing triple, the
+timestamp for that triple is updated, and the email is accepted for further
+processing.
+
+As long as a sender and recipient communicate frequently, there is no delay
+introduced by enabling greylisting. A triple is removed after a longer period
+of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
+are:
+
+* 2 days for the retry of the first delivery
+
+* 36 days for a known triple
+
+Mails with an empty envelope sender are always delayed.
+
+Some email service providers send out emails for one domain from multiple
+servers. To prevent delays due to an email coming in from two separate IPs of
+the same provider, the triples store a network ('cidr') instead of a single IP.
+For certain large providers, the default network size might be too small. You
+can configure the netmask applied to an IP for the greylist lookup in
+'/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
+and 'greylistmask6' for IPv6 respectively.
+
+
+[[pmgconfig_mailproxy_transports]]
+Transports
+~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-transports.png", big=1]
+endif::manvolnum[]
+
+You can use {pmg} to send emails to different internal email servers. For
+example, you can send emails addressed to domain.com to your first email server
+and emails addressed to subdomain.domain.com to a second one.
+
+You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
+transport ports and mail domains (or just single email addresses) of your
+additional email servers. When transport protocol is set to `lmtp`, the option
+'Use MX' is useless and will automatically be set to 'No'.
+
+
+[[pmgconfig_mailproxy_networks]]
+Networks
+~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-networks.png", big=1]
+endif::manvolnum[]
+
+You can add additional internal (trusted) IP networks or hosts. All hosts in
+this list are allowed to relay.
+
+NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
+be added to this list.
+
+
+[[pmgconfig_mailproxy_tls]]
+TLS
+~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-tls.png", big=1]
+endif::manvolnum[]
+
+Transport Layer Security (TLS) provides certificate-based authentication and
+encrypted sessions. An encrypted session protects the information that is
+transmitted with SMTP mail. When you activate TLS, {pmg} automatically
+generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
+
+{pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
+encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
+server. Otherwise, messages are sent unencrypted.
+
+You can set a different TLS policy per destination. A destination is either a
+remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
+This can be used if you need to prevent email delivery without
+encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
+{postfix_tls_readme} for details on the supported policies.
+
+Additionally, TLS can also be enforced on incoming connections on the external
+port for specific sender domains by creating a TLS inbound domains entry. Mails
+with matching domains must use a encrypted SMTP session, otherwise they are
+rejected. All domains on this list have and entry of
+https://www.postfix.org/postconf.5.html#reject_plaintext_session[`reject_plaintext_session`]
+in a `check_sender_access` table.
+
+Enable TLS logging::
+
+To get additional information about SMTP TLS activity, you can enable
+TLS logging. In this case, information about TLS sessions and used
+certificates is logged via syslog.
+
+Add TLS received header::
+
+Set this option to include information about the protocol and cipher
+used, as well as the client and issuer CommonName into the "Received:"
+message header.
+
+Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.mail-tls-conf-opts.adoc[]
+
+
+[[pmgconfig_mailproxy_dkim]]
+DKIM Signing
+~~~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-dkim.png", big=1]
+endif::manvolnum[]
+
+DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
+cryptographically authenticate a mail as originating from a particular domain.
+Before sending the mail, a hash over certain header fields and the body is
+computed, signed with a private key and added in the `DKIM-Signature` header of
+the mail. The 'selector' (a short identifier chosen by you, used to identify
+which system and private key were used for signing) is also included in the
+`DKIM-Signature` header.
+
+The verification is done by the receiver. The public key is fetched
+via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
+for verifying the hash. You can publish multiple selectors for your domain,
+each used by a system which sends email from your domain, without the need to
+share the private key.
+
+{pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
+
+Additionally, it supports conditionally signing outbound mail, if configured.
+It uses one private key and selector per {pmg} deployment (all nodes in a
+cluster use the same key). The key has a minimal size of 1024 bits and
+rsa-sha256 is used as the signing algorithm.
+
+The headers included in the signature are taken from the list of
+`Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
+`CC`, `Reply-To` and `Subject` get oversigned.
+
+You can either sign all mails received on the internal port using the domain of
+the envelope sender address or create a list of domains, for which emails
+should be signed, defaulting to the list of relay domains.
+
+
+Enable DKIM Signing::
+
+Controls whether outbound mail should get DKIM signed.
+
+Selector::
+
+The selector used for signing the mail. The private key used for signing is
+saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
+record which you need to add to all domains signed by {pmg} by clicking on the
+'View DNS Record' Button.
+
+Sign all Outgoing Mail::
+
+Controls whether all outbound mail should get signed or only mails from domains
+listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
+otherwise.
+
+These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.admin-dkim-conf-opts.adoc[]
+
+
+Whitelist
+~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
+endif::manvolnum[]
+
+All SMTP checks are disabled for those entries (e.g. Greylisting,
+SPF, DNSBL, ...)
+
+DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
+This means it can only make use of the `IP Address` and `IP Network` entries.
+
+NOTE: If you use a backup MX server (for example, your ISP offers this service
+for you) you should always add those servers here.
+
+NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
+xref:pmgconfig_mailproxy_options[Mail Proxy Options].
+
+[[pmgconfig_spamdetector]]
+Spam Detector Configuration
+---------------------------
+
+Options
+~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-spam-options.png", big=1]
+endif::manvolnum[]
+
+{pmg} uses a wide variety of local and network tests to identify spam
+signatures. This makes it harder for spammers to identify one aspect
+which they can craft their messages to work around the spam filter.
+
+Every single email will be analyzed and have a spam score
+assigned. The system attempts to optimize the efficiency of the rules
+that are run in terms of minimizing the number of false positives and
+false negatives.
+
+include::pmg.spam-conf-opts.adoc[]
+
+
+[[pmgconfig_spamdetector_quarantine]]
+Quarantine
+~~~~~~~~~~
ifndef::manvolnum[]
-image::images/screenshot/pmg-gui-backup.png[]
+[thumbnail="pmg-gui-spamquar-options.png", big=1]
endif::manvolnum[]
-TODO
+{pmg} analyses all incoming email messages and decides for each
+email if it is ham or spam (or virus). Good emails are delivered to
+the inbox and spam messages are moved into the spam quarantine.
+
+The system can be configured to send daily reports to inform users
+about personal spam messages received in the last day. The report is
+only sent if there are new messages in the quarantine.
+
+Some options are only available in the config file `/etc/pmg/pmg.conf`,
+and not in the web interface.
+
+include::pmg.spamquar-conf-opts.adoc[]
+
+
+[[pmgconfig_spamdetector_customscores]]
+Customization of Rulescores
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-spam-custom-scores.png", big=1]
+endif::manvolnum[]
+
+While the default scoring of {spamassassin}'s ruleset provides very good
+detection rates, sometimes your particular environment can benefit from
+slightly adjusting the score of a particular rule. Two examples:
+
+* Your system receives spam mails which are scored at 4.9 and you have
+ a rule which puts all mails above 5 in the quarantine. The one thing the
+ spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing
+ the score of this rule by 0.2 points the spam mails would all be quarantined
+ instead of being sent to your users
+
+* Your system tags many legitimate mails from a partner organization as spam,
+ because the organization has a policy that each mail has to start with
+ 'Dear madam or sir' (generating 1.9 points through the rule
+ 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
+ it completely.
+
+The system logs all the rules which a particular mail hits. Analyzing the logs can
+lead to finding such a pattern in your environment.
+
+You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
+in the GUI and entering a {spamassassin} rule as the name.
+
+NOTE: In general, it is strongly recommended not to make large changes to the
+default scores.
+
+
+[[pmgconfig_clamav]]
+Virus Detector Configuration
+----------------------------
+
+[[pmgconfig_clamav_options]]
+Options
+~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-virus-options.png", big=1]
+endif::manvolnum[]
+
+All mails are automatically passed to the included virus detector
+({clamav}). The default settings are considered safe, so it is usually
+not required to change them.
+
+{clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.clamav-conf-opts.adoc[]
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-clamav-database.png", big=1]
+endif::manvolnum[]
+Please note that the virus signature database is automatically
+updated. You can see the database status in the GUI, and also
+trigger manual updates from there.
+
+
+[[pmgconfig_clamav_quarantine]]
+Quarantine
+~~~~~~~~~~
+
+ifndef::manvolnum[]
+[thumbnail="pmg-gui-virusquar-options.png", big=1]
+endif::manvolnum[]
+
+Identified virus mails are automatically moved to the virus
+quarantine. The administrator can view these mails from the GUI, and
+choose to deliver them, in case of false positives. {pmg} does not notify
+individual users about received virus mails.
+
+Virus quarantine related settings are saved to subsection 'virusquar'
+in `/etc/pmg/pmg.conf`, using the following configuration keys:
+
+include::pmg.virusquar-conf-opts.adoc[]
+
+
+Custom SpamAssassin configuration
+---------------------------------
+
+This is only for advanced users. {spamassassin}'s rules and their associated
+scores get updated regularly and are trained on a huge corpus, which gets
+classified by experts. In most cases, adding a rule for matching a particular
+keyword is the wrong approach, leading to many false positives. Usually bad
+detection rates are better addressed by properly setting up DNS than by adding
+a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
+spam-headers - see the {spamassassin_dnsbl}.
+
+To add or change the Proxmox {spamassassin} configuration, log in to the
+console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
+directory there are several files (`init.pre`, `local.cf`, ...) - do not change
+them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
+the xref:pmgconfig_template_engine[template engine], while the others can
+get updated by any {spamassassin} package upgrade.
+
+To add your custom configuration, you have to create a new file named
+`custom.cf` (in `/etc/mail/spamassassin/`), then add your configuration there.
+Make sure to use the correct {spamassassin_rule_syntax} and test it with:
+
+----
+# spamassassin -D --lint
+----
+
+If you run a cluster, the `custom.cf` file is synchronized from the
+master node to all cluster members automatically.
+
+To adjust the score assigned to a particular rule, you
+can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
+settings in the GUI.
+
+
+[[pmgconfig_custom_check]]
+Custom Check Interface
+----------------------
+
+For use-cases which are not handled by the {pmg} Virus Detector and
+{spamassassin} configuration, advanced users can create a custom check
+executable which, if enabled will be called before the Virus Detector and before
+passing an email through the Rule System. The custom check API is kept as
+simple as possible, while still providing a great deal of control over the
+treatment of an email. Its input is passed via two CLI arguments:
+
+* the 'api-version' (currently `v1`) - for potential future change of the
+ invocation
+
+* the 'queue-file-name' - a filename, which contains the complete email as
+ rfc822/eml file
+
+The expected output needs to be printed to STDOUT and consists of two lines:
+
+* the 'api-version' (currently 'v1') - see above
+
+* one of the following 3 results:
+** 'OK' - email is OK
+** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
+ (the virus description is logged and added to the email's headers)
+** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
+ to the email's spamscore
+
+The check is run with a 5 minute timeout - if this is exceeded, the check
+executable is killed and the email is treated as OK.
+
+All output written to STDERR by the check is written with priority 'err' to the
+journal/mail.log.
+
+Below is a simple sample script following the API (and yielding a random result)
+for reference:
+
+----
+#!/bin/sh
+
+echo "called with $*" 1>&2
+
+if [ "$#" -ne 2 ]; then
+ echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
+ exit 1
+fi
+
+apiver="$1"
+shift
+
+if [ "$apiver" != "v1" ]; then
+ echo "wrong APIVERSION: $apiver" 1>&2
+ exit 2
+fi
+
+queue_file="$1"
+
+echo "v1"
+
+choice=$(shuf -i 0-3 -n1)
+
+case "$choice" in
+ 0)
+ echo OK
+ ;;
+ 1)
+ echo SCORE: 4
+ ;;
+ 2)
+ echo VIRUS: Random Virus
+ ;;
+ 3) #timeout-test
+ for i in $(seq 1 7); do
+ echo "custom checking mail: $queue_file - minute $i" 1>&2
+ sleep 60
+ done
+ ;;
+esac
+
+exit 0
+----
+
+The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
+
+----
+section: admin
+ custom_check 1
+----
+The location of the custom check executable can also be set there with the key
+`custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
+
+
+User Management
+---------------
+
+User management in {pmg} consists of three types of users/accounts:
+
+
+[[pmgconfig_localuser]]
+Local Users
+~~~~~~~~~~~
+
+[thumbnail="pmg-gui-local-user-config.png", big=1]
+
+Local users can manage and audit {pmg}. They can login on the management web
+interface.
+
+There are four roles:
+
+Administrator::
+
+Is allowed to manage settings of {pmg}, excluding some tasks like network
+configuration and upgrading.
+
+Quarantine manager::
+
+Is allowed to manage quarantines, blacklists and whitelists, but not other
+settings. Has no right to view any other data.
+
+Auditor::
+
+With this role, the user is only allowed to view data and configuration, but
+not to edit it.
+
+Helpdesk::
+
+Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
+
+In addition, there is always the 'root' user, which is used to perform special
+system administrator tasks, such as upgrading a host or changing the network
+configuration.
+
+NOTE: Only PAM users are able to log in via the web interface and ssh, while the
+users created through the web interface are not. Those users are created for
+{pmg} administration only.
+
+Local user related settings are saved in `/etc/pmg/user.conf`.
+
+For details on the fields, see xref:pmg_user_configuration_file[user.conf]
+
+[[pmgconfig_ldap]]
+LDAP/Active Directory
+~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="pmg-gui-ldap-user-config.png", big=1]
+
+With {pmg}, users can use LDAP and Active directory as authentication methods to
+access their individual xref:pmgadministration_spam_quarantine[Spam Quarantine].
+Additionally, if users have extra email aliases defined in the LDAP directory,
+they will have a single spam quarantine for all of these.
+
+NOTE: Authentication via LDAP must first be enabled using the `Authentication
+mode` (`authmode`) parameter in the
+xref:pmgconfig_spamdetector_quarantine[Spam Detector's Quarantine configuration settings].
+
+You can specify multiple LDAP/Active Directory profiles, so that you can
+create rules matching particular users and groups.
+
+Creating a profile requires (at least) the following:
+
+* `Profile Name`: The name assigned to the LDAP profile.
+* `Protocol`: LDAP, LDAPS, or LDAP+STARTTLS (LDAP+STARTTLS is recommended).
+* `Server`: The domain name/IP address of the LDAP server. A fallback can also
+ be configured using the second field.
+* `User name`: The Bind DN for authentication on the LDAP server.
+ This is required if your server does not support anonymous binds.
+* `Password`: Password for the Bind DN user.
+* `Base DN`: The directory which users are searched under.
+
+All other fields should work with the defaults for most setups, but can be
+used to customize the queries.
+
+The settings are saved to `/etc/pmg/ldap.conf`. Details about the options
+can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
+
+Bind user
+^^^^^^^^^
+
+It is highly recommended that the user which you use for connecting to the
+LDAP server only has permission to query the server. For LDAP servers
+(for example OpenLDAP or FreeIPA), the username has to be of a format like
+'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
+depend on your setup. For Active Directory servers, the format should be
+'username@domain' or 'domain\username'.
+
+Sync
+^^^^
+
+{pmg} synchronizes the relevant user and group information periodically, so that
+the information is quickly available, even when the LDAP/AD server is
+temporarily inaccessible.
+
+After a successful sync, the groups and users should be visible on the web
+interface. Following this, you can create rules targeting LDAP users and groups.
+
+
+[[pmgconfig_fetchmail]]
+Fetchmail
+~~~~~~~~~
+
+[thumbnail="pmg-gui-fetchmail-config.png", big=1]
+
+Fetchmail is a utility for polling and forwarding emails. You can define
+email accounts, which will then be fetched and forwarded to the email
+address you defined.
+
+You have to add an entry for each account/target combination you want to
+fetch and forward. These will then be regularly polled and forwarded,
+according to your configuration.
+
+The API and web interface offer the following configuration options:
+
+include::fetchmail.conf.5-opts.adoc[]
+
+[[user_tfa_auth]]
+Two-Factor Authentication
+-------------------------
+
+Users of the admin interface can configure two-factor authentication to
+increase protection of their accounts.
+
+NOTE: Joining a cluster with two-factor authentication enabled for the `root`
+user is not supported. Remove the second factor when joining the cluster.
+
+Available Second Factors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set up multiple second factors, in order to avoid a situation in which
+losing your smartphone or security key locks you out of your account
+permanently.
+
+The following two-factor authentication methods are available:
+
+* User configured TOTP
+ (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
+ A short code derived from a shared secret and the current time, it changes
+ every 30 seconds.
+* WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
+ A general standard for authentication. It is implemented by various security
+ devices, like hardware keys or trusted platform modules (TPM) from a computer
+ or smart phone.
+* Single use Recovery Keys. A list of keys which should either be
+ printed out and locked in a secure place or saved digitally in an electronic
+ vault. Each key can be used only once. These are perfect for ensuring that
+ you are not locked out, even if all of your other second factors are lost or
+ corrupt.
+
+Configuration of Two-Factor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login,
+via the 'TFA' button in the user list.
+
+Users can always add and use one time 'Recovery Keys'.
+
+//[thumbnail="screenshot/gui-datacenter-two-factor.png"]//TODO
+
+[[user_tfa_setup_totp]]
+=== TOTP
+
+//[thumbnail="screenshot/pve-gui-tfa-add-totp.png"]//TODO
+
+There is no server setup required. Simply install a TOTP app on your
+smartphone (for example, https://github.com/andOTP/andOTP#downloads[andOTP])
+and use the Proxmox Backup Server web-interface to add a TOTP factor.
+
+After opening the 'TOTP' window, the user is presented with a dialog to set up
+'TOTP' authentication. The 'Secret' field contains the key, which can be
+randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
+added to provide information to the 'TOTP' app about what the key belongs to.
+Most 'TOTP' apps will show the issuer name together with the corresponding
+'OTP' values. The username is also included in the QR code for the 'TOTP' app.
+
+After generating a key, a QR code will be displayed, which can be used with most
+OTP apps such as FreeOTP. The user then needs to verify the current user
+password (unless logged in as 'root'), as well as the ability to correctly use
+the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
+field and pressing the 'Apply' button.
+
+
+[[user_tfa_setup_webauthn]]
+=== WebAuthn
+
+For WebAuthn to work, you need to have two things:
+
+* A trusted HTTPS certificate (for example, by using
+ xref:sysadmin_certs_get_trusted_acme_cert[Let's Encrypt]).
+ While it probably works with an untrusted certificate, some browsers may
+ warn or refuse WebAuthn operations if it is not trusted.
+* Setup the WebAuthn configuration (see *User Management -> Two Factor ->
+ WebAuthn* in the {pmg} web interface). This can be
+ auto-filled in most setups.
+
+Once you have fulfilled both of these requirements, you can add a WebAuthn
+configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
+Factor*.
+
+[[user_tfa_setup_recovery_keys]]
+=== Recovery Keys
+
+//[thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]//TODO
+
+Recovery key codes do not need any preparation; you can simply create a
+set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
+-> Two Factor*.
+
+NOTE: There can only be one set of single-use recovery keys per user at any
+time.
+
+WebAuthn Configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+//[thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]//TODO
+
+To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
+domain with a valid SSL certificate, otherwise some browsers may warn or refuse
+to authenticate altogether.
+
+NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
+registrations unusable!
+
+You can configure WebAuthn directly in the 'Two Factor' panel, there's an
+auto-fill button that will set the correct values for most setups.
ifdef::manvolnum[]
include::pmg-copyright.adoc[]
endif::manvolnum[]
-
projects / pmg-docs.git / blobdiff