: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 file directly. Instead, we write
-changes to `/etc/network/interfaces.new`. When you reboot, we rename
-the file to `/etc/network/interfaces`, so the changes are applied
-on the next reboot.
+changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
+the file to `/etc/network/interfaces`, thus applying the changes.
`/etc/resolv.conf`::
`/etc/hostname`::
-The system's host name. {pmg} uses the hostname to create the FQDN used
+The system's hostname. {pmg} uses the hostname to create the FQDN used
in the postfix configuration.
`/etc/hosts`::
`/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`::
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.
`/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`::
Service Configuration Templates
-------------------------------
-{pmg} uses various services to implement mail filtering, for example
+{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
+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 those files. The {tts} is
+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 them directly, because your modification would get lost on the
+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 setting, and you can use the
+Templates can access any configuration settings, and you can use the
`pmgconfig dump` command to get a list of all variable names:
----
...
----
-The same tool is used to force regeneration of all template based
-configuration files. You need to run that after modifying a template,
-or when you directly edit configuration files
+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
White- and Blacklists
---------------------
-{pmg} has multiple white- and blacklists. It differentiates between the
-xref:pmgconfig_mailproxy_options[SMTP Whitelist]. The rule-based whitelist
+{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 2 separate blacklists. The rule-based
+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
+The xref:pmgconfig_mailproxy_whitelist[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 e.g. 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.
+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 the mail being accepted, but it still depends on the other rules what
-happens next. In the default setup this results in the mail being accepted for
+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.
-It still depends on the rule system what happens when a spam score that high is
-encountered. In the default setup it will be recognized as spam and quarantined
+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]]
[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 settings 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'
endif::manvolnum[]
-Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
using the following configuration keys:
include::pmg.admin-conf-opts.adoc[]
+include::pmg-ssl-certificate.adoc[]
+
Mail Proxy Configuration
------------------------
[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
-using the following configuration keys:
+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[]
[thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
endif::manvolnum[]
-List of relayed mail domains, i.e. what destination domains this
+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.
[thumbnail="pmg-gui-mailproxy-ports.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
-using the following configuration keys:
+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[]
[thumbnail="pmg-gui-mailproxy-options.png", big=1]
endif::manvolnum[]
-Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
+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[]
Before and After Queue scanning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Scanning email can happen at two different stages of mail-processing:
+Email scanning can happen at two different stages of mail-processing:
-* Before-queue filtering: During the SMTP Session, after the complete message
+* 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
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 mailserver. This is of particular advantage if
+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 so-called
+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 queueing mails is much faster than
-analyzing it for spam and viruses.
-
-If a mail is addressed to multiple recipients (e.g. when multiple addresses are
-subscribed to the same mailing list) the situation is more complicated: Your
-mailserver 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'
+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 it disabled prevents
+'/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 a RBL. However in certain environments it can be
+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 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.
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, the {pmg} tells the sending server that it should queue the
-mail and retry delivery at a later moment. Since certain kinds of spam get
-sent out by software, which has no provisioning for queueing, these mails are
+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
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
+timestamp for that triple is updated, and the email is accepted for further
processing.
-As long as a sender and recipient do communicate frequently there is no delay
+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, when no mail fitting that triple has been seen. The timeouts in {pmg}
+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 known triples
+* 36 days for a known triple
-Mails with an empty envelope-sender are always delayed.
+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 2 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
+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.
[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 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 be automatically set to 'No'.
+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]]
[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.
+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 with Proxmox can relay by default and
-it’s not needed to add them in this list.
+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]]
[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`).
+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 in the clear.
+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`.
+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. That way information about TLS sessions and used
+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:"
+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`,
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
+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
+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
{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 signing algorithm.
+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`,
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.
+listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
+otherwise.
-Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+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[]
+[[pmgconfig_mailproxy_whitelist]]
Whitelist
~~~~~~~~~
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.
+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 (e.g. your ISP offers this service
+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
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 gets a spam score
+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.
the inbox and spam messages are moved into the spam quarantine.
The system can be configured to send daily reports to inform users
-about the personal spam messages received the last day. The report is
+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`,
* 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
+ '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.
+in the GUI and entering a {spamassassin} rule as the name.
-NOTE: In general it is strongly recommended to not make large changes to the
+NOTE: In general, it is strongly recommended not to make large changes to the
default scores.
Please note that the virus signature database is automatically
updated. You can see the database status in the GUI, and also
-trigger manual updates there.
+trigger manual updates from there.
[[pmgconfig_clamav_quarantine]]
[thumbnail="pmg-gui-virusquar-options.png", big=1]
endif::manvolnum[]
-Indentified virus mails are automatically moved to the virus
-quarantine. The administrator can view these mails using the GUI, and
-choose to deliver them in case of false positives. {pmg} does not notify
+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'
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
+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 please login to the
-console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
+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 and name it
-`custom.cf` (in this directory), then add your configuration there. Make sure
-to use the correct {spamassassin} syntax, and test it with:
+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
+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.
* the 'queue-file-name' - a filename, which contains the complete email as
rfc822/eml file
-The expected output need to be printed on STDOUT and consists of two lines:
+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
+** '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 it is exceeded the check
+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.
-A simple sample script following the API (and yielding a random result) for
-reference:
+Below is a simple sample script following the API (and yielding a random result)
+for reference:
----
#!/bin/sh
Administrator::
-Is allowed to manage settings of {pmg}, except some tasks like network
+Is allowed to manage settings of {pmg}, excluding some tasks like network
configuration and upgrading.
Quarantine manager::
Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
-In addition there is always the 'root' user, which is used to perform special
+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 login via the webconsole and ssh, which the
-users created with the web interface are not. Those users are created for {pmg}
-administration only.
+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 of the fields see xref:pmg_user_configuration_file[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 those users and groups.
+create rules matching particular users and groups.
Creating a profile requires (at least) the following:
-* profile name
-* protocol (LDAP or LDAPS; LDAPS is recommended)
-* at least one server
-* a user and password (if your server does not support anonymous binds)
+* `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 for the options
+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 the permission to query the server. For LDAP servers
+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 are
-depending on your setup. For Active Directory servers, the format should be
-like 'username@domain' or 'domain\username'.
+'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 info periodically, so that
-the information is available in a fast manner, even when the LDAP/AD server
-is temporarily not accessible.
+{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. After that, you can create rules targeting LDAP users and groups.
+interface. Following this, you can create rules targeting LDAP users and groups.
[[pmgconfig_fetchmail]]
[thumbnail="pmg-gui-fetchmail-config.png", big=1]
-Fetchmail is utility for polling and forwarding emails. You can define
+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. Those will then be regularly polled and forwarded,
+fetch and forward. These will then be regularly polled and forwarded,
according to your configuration.
-The API and web interface offer following configuration options:
+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