: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, using 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, such as generating certificates and rewriting
-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
-statistical 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
TLS policy for outbound connections.
-`/etc/pmg/transports`::
+`/etc/pmg/tls_inbound_domains`::
+
+Sender domains for which TLS is enforced on inbound connections.
+
+`/etc/pmg/transport`::
Message delivery transport setup.
SMTP Whitelist
~~~~~~~~~~~~~~
-The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
+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.
~~~~~~~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-network-config.png", big=1]
+[thumbnail="screenshot/pmg-gui-network-config.png", big=1]
endif::manvolnum[]
As network and time are configured in the installer, these generally do not
~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-system-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-system-options.png", big=1]
endif::manvolnum[]
~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-relaying.png", big=1]
endif::manvolnum[]
-These settings are saved to the 'mail' subsection 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[]
~~~~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-relaydomains.png", big=1]
endif::manvolnum[]
A list of relayed mail domains, that is, what destination domains this
~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-ports.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-ports.png", big=1]
endif::manvolnum[]
-These settings are saved to the 'mail' subsection 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[]
~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-options.png", big=1]
endif::manvolnum[]
These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-transports.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-transports.png", big=1]
endif::manvolnum[]
You can use {pmg} to send emails to different internal email servers. For
~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-networks.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-networks.png", big=1]
endif::manvolnum[]
You can add additional internal (trusted) IP networks or hosts. All hosts in
~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-tls.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-tls.png", big=1]
endif::manvolnum[]
Transport Layer Security (TLS) provides certificate-based authentication and
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
~~~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-dkim.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-dkim.png", big=1]
endif::manvolnum[]
DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
include::pmg.admin-dkim-conf-opts.adoc[]
+[[pmgconfig_mailproxy_whitelist]]
Whitelist
~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
+[thumbnail="screenshot/pmg-gui-mailproxy-whitelist.png", big=1]
endif::manvolnum[]
All SMTP checks are disabled for those entries (e.g. Greylisting,
~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-spam-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-spam-options.png", big=1]
endif::manvolnum[]
{pmg} uses a wide variety of local and network tests to identify spam
~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-spamquar-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-spamquar-options.png", big=1]
endif::manvolnum[]
{pmg} analyses all incoming email messages and decides for each
~~~~~~~~~~~~~~~~~~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-spam-custom-scores.png", big=1]
+[thumbnail="screenshot/pmg-gui-spam-custom-scores.png", big=1]
endif::manvolnum[]
While the default scoring of {spamassassin}'s ruleset provides very good
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 not to make large changes to the
default scores.
~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-virus-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-virus-options.png", big=1]
endif::manvolnum[]
All mails are automatically passed to the included virus detector
include::pmg.clamav-conf-opts.adoc[]
ifndef::manvolnum[]
-[thumbnail="pmg-gui-clamav-database.png", big=1]
+[thumbnail="screenshot/pmg-gui-clamav-database.png", big=1]
endif::manvolnum[]
Please note that the virus signature database is automatically
~~~~~~~~~~
ifndef::manvolnum[]
-[thumbnail="pmg-gui-virusquar-options.png", big=1]
+[thumbnail="screenshot/pmg-gui-virusquar-options.png", big=1]
endif::manvolnum[]
Identified virus mails are automatically moved to the virus
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
Local Users
~~~~~~~~~~~
-[thumbnail="pmg-gui-local-user-config.png", big=1]
+[thumbnail="screenshot/pmg-gui-local-user-config.png", big=1]
Local users can manage and audit {pmg}. They can login on the management web
interface.
LDAP/Active Directory
~~~~~~~~~~~~~~~~~~~~~
-[thumbnail="pmg-gui-ldap-user-config.png", big=1]
+[thumbnail="screenshot/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 username 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
(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
-like 'username@domain' or 'domain\username'.
+'username@domain' or 'domain\username'.
Sync
^^^^
Fetchmail
~~~~~~~~~
-[thumbnail="pmg-gui-fetchmail-config.png", big=1]
+[thumbnail="screenshot/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
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