10 pmgconfig - Proxmox Mail Gateway Configuration Management Toolkit
16 include::pmgconfig.1-synopsis.adoc[]
23 Configuration Management
24 ========================
28 {pmg} is usually configured using the web-based Graphical User Interface (GUI),
29 but it is also possible to directly edit the configuration files, using the
30 REST API over 'https' or the command line tool `pmgsh`.
32 The command line tool `pmgconfig` is used to simplify some common configuration
33 tasks, such as generating certificates and rewriting service configuration
36 NOTE: We use a Postgres database to store mail filter rules and statistical
37 data. See chapter xref:chapter_pmgdb[Database Management] for more information.
40 Configuration files overview
41 ----------------------------
43 `/etc/network/interfaces`::
45 Network setup. We never modify this file directly. Instead, we write
46 changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
47 the file to `/etc/network/interfaces`, thus applying the changes.
51 DNS search domain and nameserver setup. {pmg} uses the search domain setting
52 to create the FQDN and domain name used in the postfix configuration.
56 The system's hostname. {pmg} uses the hostname to create the FQDN used
57 in the postfix configuration.
61 Static table lookup for hostnames.
65 Stores common administration options, such as the spam and mail proxy
68 `/etc/pmg/cluster.conf`::
74 The list of relay domains.
76 `/etc/pmg/dkim/domains`::
78 The list of domains for outbound DKIM signing.
80 `/etc/pmg/fetchmailrc`::
82 Fetchmail configuration (POP3 and IMAP setup).
84 `/etc/pmg/ldap.conf`::
88 `/etc/pmg/mynetworks`::
90 List of local (trusted) networks.
92 `/etc/pmg/subscription`::
94 Stores your subscription key and status.
96 `/etc/pmg/tls_policy`::
98 TLS policy for outbound connections.
100 `/etc/pmg/transports`::
102 Message delivery transport setup.
104 `/etc/pmg/user.conf`::
106 GUI user configuration.
108 `/etc/mail/spamassassin/custom.cf`::
110 Custom {spamassassin} setup.
112 `/etc/mail/spamassassin/pmg-scores.cf`::
114 Custom {spamassassin} rule scores.
116 Keys and Certificates
117 ---------------------
119 `/etc/pmg/pmg-api.pem`::
121 Key and certificate (combined) used by the HTTPS server (API).
123 `/etc/pmg/pmg-authkey.key`::
125 Private key used to generate authentication tickets.
127 `/etc/pmg/pmg-authkey.pub`::
129 Public key used to verify authentication tickets.
131 `/etc/pmg/pmg-csrf.key`::
133 Internally used to generate CSRF tokens.
135 `/etc/pmg/pmg-tls.pem`::
137 Key and certificate (combined) to encrypt mail traffic (TLS).
139 `/etc/pmg/dkim/<selector>.private`::
141 Key for DKIM signing mails with selector '<selector>'.
144 [[pmgconfig_template_engine]]
145 Service Configuration Templates
146 -------------------------------
148 {pmg} uses various services to implement mail filtering, for example,
149 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
150 engine, and the Apache {spamassassin} project. These services use
151 separate configuration files, so we need to rewrite those files when the
152 configuration is changed.
154 We use a template-based approach to generate these files. The {tts} is
155 a well known, fast and flexible template processing system. You can
156 find the default templates in `/var/lib/pmg/templates/`. Please do not
157 modify these directly, otherwise your modifications will be lost on the
158 next update. Instead, copy the template you wish to change to
159 `/etc/pmg/templates/`, then apply your changes there.
161 Templates can access any configuration settings, and you can use the
162 `pmgconfig dump` command to get a list of all variable names:
167 dns.domain = yourdomain.tld
169 ipconfig.int_ip = 192.168.2.127
170 pmg.admin.advfilter = 1
174 The same tool is used to force the regeneration of all template-based
175 configuration files. You need to run the following after modifying a template,
176 or when you directly edit configuration files:
179 # pmgconfig sync --restart 1
182 The above command also restarts services if the underlying configuration
183 files are changed. Please note that this is automatically done when
184 you change the configuration using the GUI or API.
186 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
187 synced from the master node to all cluster members.
189 [[pmgconfig_whitelist_overview]]
190 White- and Blacklists
191 ---------------------
193 {pmg} has multiple white- and blacklists. It differentiates between the
194 xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
195 and the user whitelist.
196 In addition to the whitelists, there are two separate blacklists: the rule-based
197 blacklist and the user blacklist.
202 The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
203 greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
206 Rule-based White-/Blacklist
207 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
209 The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
210 rules. They work by checking the attached 'Who' objects, containing, for
211 example, a domain or a mail address for a match. If it matches, the assigned
212 action is used, which by default is 'Accept' for the whitelist rule and 'Block'
213 for the blacklist rule. In the default setup, the blacklist rule has priority
214 over the whitelist rule and spam checks.
216 User White-/Blacklist
217 ~~~~~~~~~~~~~~~~~~~~~
219 The user white- and blacklist are user specific. Every user can add mail addresses
220 to their white- and blacklist. When a user adds a mail address to the whitelist,
221 the result of the spam analysis will be discarded for that recipient. This can
222 help in the mail being accepted, but what happens next still depends on the
223 other rules. In the default setup, this results in the mail being accepted for
226 For mail addresses on a user's blacklist, the spam score will be increased by
227 100. What happens when a high spam score is encountered still depends on the
228 rule system. In the default setup, it will be recognized as spam and quarantined
229 (spam score of 3 or higher).
231 [[pmgconfig_systemconfig]]
239 [thumbnail="pmg-gui-network-config.png", big=1]
242 As network and time are configured in the installer, these generally do not
243 need to be configured again in the GUI.
245 The default setup uses a single Ethernet adapter and static IP
246 assignment. The configuration is stored at '/etc/network/interfaces',
247 and the actual network setup is done the standard Debian way, using the
250 .Example network setup '/etc/network/interfaces'
252 source /etc/network/interfaces.d/*
255 iface lo inet loopback
258 iface ens18 inet static
259 address 192.168.2.127
260 netmask 255.255.240.0
266 Many tests to detect SPAM mails use DNS queries, so it is important to
267 have a fast and reliable DNS server. We also query some publicly
268 available DNS Blacklists. Most of them apply rate limits for clients,
269 so they simply will not work if you use a public DNS server (because
270 they are usually blocked). We recommend to use your own DNS server,
271 which needs to be configured in 'recursive' mode.
278 [thumbnail="pmg-gui-system-options.png", big=1]
282 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
283 using the following configuration keys:
285 include::pmg.admin-conf-opts.adoc[]
288 include::pmg-ssl-certificate.adoc[]
290 Mail Proxy Configuration
291 ------------------------
293 [[pmgconfig_mailproxy_relaying]]
298 [thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
301 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
302 using the following configuration keys:
304 include::pmg.mail-relaying-conf-opts.adoc[]
306 [[pmgconfig_mailproxy_relay_domains]]
311 [thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
314 A list of relayed mail domains, that is, what destination domains this
315 system will relay mail to. The system will reject incoming mails to
319 [[pmgconfig_mailproxy_ports]]
324 [thumbnail="pmg-gui-mailproxy-ports.png", big=1]
327 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
328 using the following configuration keys:
330 include::pmg.mail-ports-conf-opts.adoc[]
333 [[pmgconfig_mailproxy_options]]
338 [thumbnail="pmg-gui-mailproxy-options.png", big=1]
341 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
342 using the following configuration keys:
344 include::pmg.mail-options-conf-opts.adoc[]
347 [[pmgconfig_mailproxy_before_after_queue]]
348 Before and After Queue scanning
349 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
351 Email scanning can happen at two different stages of mail-processing:
353 * Before-queue filtering: During the SMTP session, after the complete message
354 has been received (after the 'DATA' command).
356 * After-queue filtering: After initially accepting the mail and putting it on
357 a queue for further processing.
359 Before-queue filtering has the advantage that the system can reject a mail (by
360 sending a permanent reject code '554'), and leave the task of notifying the
361 original sender to the other mail server. This is of particular advantage if
362 the processed mail is a spam message or contains a virus and has a forged
363 sender address. Sending out a notification in this situation leads to so-called
364 'backscatter' mail, which might cause your server to get listed as spamming on
365 RBLs (Real-time Blackhole List).
367 After-queue filtering has the advantage of providing faster delivery of
368 mails for the sending servers, since queuing emails is much faster than
369 analyzing them for spam and viruses.
371 If a mail is addressed to multiple recipients (for example, when multiple
372 addresses are subscribed to the same mailing list), the situation is more
373 complicated; your mail server can only reject or accept the mail for all
374 recipients, after having received the complete message, while your rule setup
375 might accept the mail for part of the recipients and reject it for others. This
376 can be due to a complicated rule setup, or if your users use the 'User White-
377 and Blacklist' feature.
379 If the resulting action of the rule system is the same for all recipients, {pmg}
380 responds accordingly, if configured for before-queue filtering (sending '554'
381 for a blocked mail and '250' for an accepted or quarantined mail). If some
382 mailboxes accept the mail and some reject it, the system has to accept the mail.
384 Whether {pmg} notifies the sender that delivery failed for some recipients by
385 sending a non-delivery report, depends on the 'ndr_on_block' setting in
386 '/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
387 NDRs being sent to the (possibly forged) sender and thus minimizes the chance
388 of getting your IP listed on an RBL. However in certain environments, it can be
389 unacceptable not to inform the sender about a rejected mail.
391 The setting has the same effect if after-queue filtering is configured, with
392 the exception that an NDR is always sent out, even if all recipients block the
393 mail, since the mail already got accepted before being analyzed.
395 The details of integrating the mail proxy with {postfix} in both setups are
396 explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
399 [[pmgconfig_mailproxy_greylisting]]
403 Greylisting is a technique for preventing unwanted messages from reaching the
404 resource intensive stages of content analysis (virus detection and spam
405 detection). By initially replying with a temporary failure code ('450') to
406 each new email, {pmg} tells the sending server that it should queue the
407 mail and retry delivery at a later point. Since certain kinds of spam get
408 sent out by software which has no provisioning for queuing, these mails are
409 dropped without reaching {pmg} or your mailbox.
411 The downside of greylisting is the delay introduced by the initial deferral of
412 the email, which usually amounts to less than 30 minutes.
414 In order to prevent unnecessary delays in delivery from known sources, emails
415 coming from a source for a recipient, which have passed greylisting in the
416 past are directly passed on: For each email the triple '<sender network,
417 sender email, recipient email>' is stored in a list, along with the time when
418 delivery was attempted. If an email fits an already existing triple, the
419 timestamp for that triple is updated, and the email is accepted for further
422 As long as a sender and recipient communicate frequently, there is no delay
423 introduced by enabling greylisting. A triple is removed after a longer period
424 of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
427 * 2 days for the retry of the first delivery
429 * 36 days for a known triple
431 Mails with an empty envelope sender are always delayed.
433 Some email service providers send out emails for one domain from multiple
434 servers. To prevent delays due to an email coming in from two separate IPs of
435 the same provider, the triples store a network ('cidr') instead of a single IP.
436 For certain large providers, the default network size might be too small. You
437 can configure the netmask applied to an IP for the greylist lookup in
438 '/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
439 and 'greylistmask6' for IPv6 respectively.
442 [[pmgconfig_mailproxy_transports]]
447 [thumbnail="pmg-gui-mailproxy-transports.png", big=1]
450 You can use {pmg} to send emails to different internal email servers. For
451 example, you can send emails addressed to domain.com to your first email server
452 and emails addressed to subdomain.domain.com to a second one.
454 You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
455 transport ports and mail domains (or just single email addresses) of your
456 additional email servers. When transport protocol is set to `lmtp`, the option
457 'Use MX' is useless and will automatically be set to 'No'.
460 [[pmgconfig_mailproxy_networks]]
465 [thumbnail="pmg-gui-mailproxy-networks.png", big=1]
468 You can add additional internal (trusted) IP networks or hosts. All hosts in
469 this list are allowed to relay.
471 NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
472 be added to this list.
475 [[pmgconfig_mailproxy_tls]]
480 [thumbnail="pmg-gui-mailproxy-tls.png", big=1]
483 Transport Layer Security (TLS) provides certificate-based authentication and
484 encrypted sessions. An encrypted session protects the information that is
485 transmitted with SMTP mail. When you activate TLS, {pmg} automatically
486 generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
488 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
489 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
490 server. Otherwise, messages are sent unencrypted.
492 You can set a different TLS policy per destination. A destination is either a
493 remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
494 This can be used if you need to prevent email delivery without
495 encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
496 {postfix_tls_readme} for details on the supported policies.
500 To get additional information about SMTP TLS activity, you can enable
501 TLS logging. In this case, information about TLS sessions and used
502 certificates is logged via syslog.
504 Add TLS received header::
506 Set this option to include information about the protocol and cipher
507 used, as well as the client and issuer CommonName into the "Received:"
510 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
511 using the following configuration keys:
513 include::pmg.mail-tls-conf-opts.adoc[]
516 [[pmgconfig_mailproxy_dkim]]
521 [thumbnail="pmg-gui-mailproxy-dkim.png", big=1]
524 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
525 cryptographically authenticate a mail as originating from a particular domain.
526 Before sending the mail, a hash over certain header fields and the body is
527 computed, signed with a private key and added in the `DKIM-Signature` header of
528 the mail. The 'selector' (a short identifier chosen by you, used to identify
529 which system and private key were used for signing) is also included in the
530 `DKIM-Signature` header.
532 The verification is done by the receiver. The public key is fetched
533 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
534 for verifying the hash. You can publish multiple selectors for your domain,
535 each used by a system which sends email from your domain, without the need to
536 share the private key.
538 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
540 Additionally, it supports conditionally signing outbound mail, if configured.
541 It uses one private key and selector per {pmg} deployment (all nodes in a
542 cluster use the same key). The key has a minimal size of 1024 bits and
543 rsa-sha256 is used as the signing algorithm.
545 The headers included in the signature are taken from the list of
546 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
547 `CC`, `Reply-To` and `Subject` get oversigned.
549 You can either sign all mails received on the internal port using the domain of
550 the envelope sender address or create a list of domains, for which emails
551 should be signed, defaulting to the list of relay domains.
554 Enable DKIM Signing::
556 Controls whether outbound mail should get DKIM signed.
560 The selector used for signing the mail. The private key used for signing is
561 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
562 record which you need to add to all domains signed by {pmg} by clicking on the
563 'View DNS Record' Button.
565 Sign all Outgoing Mail::
567 Controls whether all outbound mail should get signed or only mails from domains
568 listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
571 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
572 using the following configuration keys:
574 include::pmg.admin-dkim-conf-opts.adoc[]
581 [thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
584 All SMTP checks are disabled for those entries (e.g. Greylisting,
587 DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
588 This means it can only make use of the `IP Address` and `IP Network` entries.
590 NOTE: If you use a backup MX server (for example, your ISP offers this service
591 for you) you should always add those servers here.
593 NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
594 xref:pmgconfig_mailproxy_options[Mail Proxy Options].
596 [[pmgconfig_spamdetector]]
597 Spam Detector Configuration
598 ---------------------------
604 [thumbnail="pmg-gui-spam-options.png", big=1]
607 {pmg} uses a wide variety of local and network tests to identify spam
608 signatures. This makes it harder for spammers to identify one aspect
609 which they can craft their messages to work around the spam filter.
611 Every single email will be analyzed and have a spam score
612 assigned. The system attempts to optimize the efficiency of the rules
613 that are run in terms of minimizing the number of false positives and
616 include::pmg.spam-conf-opts.adoc[]
619 [[pmgconfig_spamdetector_quarantine]]
624 [thumbnail="pmg-gui-spamquar-options.png", big=1]
627 {pmg} analyses all incoming email messages and decides for each
628 email if it is ham or spam (or virus). Good emails are delivered to
629 the inbox and spam messages are moved into the spam quarantine.
631 The system can be configured to send daily reports to inform users
632 about personal spam messages received in the last day. The report is
633 only sent if there are new messages in the quarantine.
635 Some options are only available in the config file `/etc/pmg/pmg.conf`,
636 and not in the web interface.
638 include::pmg.spamquar-conf-opts.adoc[]
641 [[pmgconfig_spamdetector_customscores]]
642 Customization of Rulescores
643 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
646 [thumbnail="pmg-gui-spam-custom-scores.png", big=1]
649 While the default scoring of {spamassassin}'s ruleset provides very good
650 detection rates, sometimes your particular environment can benefit from
651 slightly adjusting the score of a particular rule. Two examples:
653 * Your system receives spam mails which are scored at 4.9 and you have
654 a rule which puts all mails above 5 in the quarantine. The one thing the
655 spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing
656 the score of this rule by 0.2 points the spam mails would all be quarantined
657 instead of being sent to your users
659 * Your system tags many legitimate mails from a partner organization as spam,
660 because the organization has a policy that each mail has to start with
661 'Dear madam or sir' (generating 1.9 points through the rule
662 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
665 The system logs all the rules which a particular mail hits. Analyzing the logs can
666 lead to finding such a pattern in your environment.
668 You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
669 in the GUI and entering a {spamassassin} rule as the name.
671 NOTE: In general, it is strongly recommended not to make large changes to the
676 Virus Detector Configuration
677 ----------------------------
679 [[pmgconfig_clamav_options]]
684 [thumbnail="pmg-gui-virus-options.png", big=1]
687 All mails are automatically passed to the included virus detector
688 ({clamav}). The default settings are considered safe, so it is usually
689 not required to change them.
691 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
692 using the following configuration keys:
694 include::pmg.clamav-conf-opts.adoc[]
697 [thumbnail="pmg-gui-clamav-database.png", big=1]
700 Please note that the virus signature database is automatically
701 updated. You can see the database status in the GUI, and also
702 trigger manual updates from there.
705 [[pmgconfig_clamav_quarantine]]
710 [thumbnail="pmg-gui-virusquar-options.png", big=1]
713 Identified virus mails are automatically moved to the virus
714 quarantine. The administrator can view these mails from the GUI, and
715 choose to deliver them, in case of false positives. {pmg} does not notify
716 individual users about received virus mails.
718 Virus quarantine related settings are saved to subsection 'virusquar'
719 in `/etc/pmg/pmg.conf`, using the following configuration keys:
721 include::pmg.virusquar-conf-opts.adoc[]
724 Custom SpamAssassin configuration
725 ---------------------------------
727 This is only for advanced users. {spamassassin}'s rules and their associated
728 scores get updated regularly and are trained on a huge corpus, which gets
729 classified by experts. In most cases, adding a rule for matching a particular
730 keyword is the wrong approach, leading to many false positives. Usually bad
731 detection rates are better addressed by properly setting up DNS than by adding
732 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
733 spam-headers - see the {spamassassin_dnsbl}.
735 To add or change the Proxmox {spamassassin} configuration, log in to the
736 console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
737 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
738 them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
739 the xref:pmgconfig_template_engine[template engine], while the others can
740 get updated by any {spamassassin} package upgrade.
742 To add your custom configuration, you have to create a new file named
743 `custom.cf` (in `/etc/mail/spamassassin/`), then add your configuration there.
744 Make sure to use the correct {spamassassin_rule_syntax} and test it with:
747 # spamassassin -D --lint
750 If you run a cluster, the `custom.cf` file is synchronized from the
751 master node to all cluster members automatically.
753 To adjust the score assigned to a particular rule, you
754 can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
758 [[pmgconfig_custom_check]]
759 Custom Check Interface
760 ----------------------
762 For use-cases which are not handled by the {pmg} Virus Detector and
763 {spamassassin} configuration, advanced users can create a custom check
764 executable which, if enabled will be called before the Virus Detector and before
765 passing an email through the Rule System. The custom check API is kept as
766 simple as possible, while still providing a great deal of control over the
767 treatment of an email. Its input is passed via two CLI arguments:
769 * the 'api-version' (currently `v1`) - for potential future change of the
772 * the 'queue-file-name' - a filename, which contains the complete email as
775 The expected output needs to be printed to STDOUT and consists of two lines:
777 * the 'api-version' (currently 'v1') - see above
779 * one of the following 3 results:
780 ** 'OK' - email is OK
781 ** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
782 (the virus description is logged and added to the email's headers)
783 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
784 to the email's spamscore
786 The check is run with a 5 minute timeout - if this is exceeded, the check
787 executable is killed and the email is treated as OK.
789 All output written to STDERR by the check is written with priority 'err' to the
792 Below is a simple sample script following the API (and yielding a random result)
798 echo "called with $*" 1>&2
800 if [ "$#" -ne 2 ]; then
801 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
808 if [ "$apiver" != "v1" ]; then
809 echo "wrong APIVERSION: $apiver" 1>&2
817 choice=$(shuf -i 0-3 -n1)
827 echo VIRUS: Random Virus
830 for i in $(seq 1 7); do
831 echo "custom checking mail: $queue_file - minute $i" 1>&2
840 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
847 The location of the custom check executable can also be set there with the key
848 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
854 User management in {pmg} consists of three types of users/accounts:
857 [[pmgconfig_localuser]]
861 [thumbnail="pmg-gui-local-user-config.png", big=1]
863 Local users can manage and audit {pmg}. They can login on the management web
866 There are four roles:
870 Is allowed to manage settings of {pmg}, excluding some tasks like network
871 configuration and upgrading.
875 Is allowed to manage quarantines, blacklists and whitelists, but not other
876 settings. Has no right to view any other data.
880 With this role, the user is only allowed to view data and configuration, but
885 Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
887 In addition, there is always the 'root' user, which is used to perform special
888 system administrator tasks, such as upgrading a host or changing the network
891 NOTE: Only PAM users are able to log in via the web interface and ssh, while the
892 users created through the web interface are not. Those users are created for
893 {pmg} administration only.
895 Local user related settings are saved in `/etc/pmg/user.conf`.
897 For details on the fields, see xref:pmg_user_configuration_file[user.conf]
900 LDAP/Active Directory
901 ~~~~~~~~~~~~~~~~~~~~~
903 [thumbnail="pmg-gui-ldap-user-config.png", big=1]
905 With {pmg}, users can use LDAP and Active directory as authentication methods to
906 access their individual xref:pmgadministration_spam_quarantine[Spam Quarantine].
907 Additionally, if users have extra email aliases defined in the LDAP directory,
908 they will have a single spam quarantine for all of these.
910 NOTE: Authentication via LDAP must first be enabled using the `Authentication
911 mode` (`authmode`) parameter in the
912 xref:pmgconfig_spamdetector_quarantine[Spam Detector's Quarantine configuration settings].
914 You can specify multiple LDAP/Active Directory profiles, so that you can
915 create rules matching particular users and groups.
917 Creating a profile requires (at least) the following:
919 * `Profile Name`: The name assigned to the LDAP profile.
920 * `Protocol`: LDAP, LDAPS, or LDAP+STARTTLS (LDAP+STARTTLS is recommended).
921 * `Server`: The domain name/IP address of the LDAP server. A fallback can also
922 be configured using the second field.
923 * `User name`: The Bind DN for authentication on the LDAP server.
924 This is required if your server does not support anonymous binds.
925 * `Password`: Password for the Bind DN user.
926 * `Base DN`: The directory which users are searched under.
928 All other fields should work with the defaults for most setups, but can be
929 used to customize the queries.
931 The settings are saved to `/etc/pmg/ldap.conf`. Details about the options
932 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
937 It is highly recommended that the user which you use for connecting to the
938 LDAP server only has permission to query the server. For LDAP servers
939 (for example OpenLDAP or FreeIPA), the username has to be of a format like
940 'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
941 depend on your setup. For Active Directory servers, the format should be
942 'username@domain' or 'domain\username'.
947 {pmg} synchronizes the relevant user and group information periodically, so that
948 the information is quickly available, even when the LDAP/AD server is
949 temporarily inaccessible.
951 After a successful sync, the groups and users should be visible on the web
952 interface. Following this, you can create rules targeting LDAP users and groups.
955 [[pmgconfig_fetchmail]]
959 [thumbnail="pmg-gui-fetchmail-config.png", big=1]
961 Fetchmail is a utility for polling and forwarding emails. You can define
962 email accounts, which will then be fetched and forwarded to the email
965 You have to add an entry for each account/target combination you want to
966 fetch and forward. These will then be regularly polled and forwarded,
967 according to your configuration.
969 The API and web interface offer the following configuration options:
971 include::fetchmail.conf.5-opts.adoc[]
974 Two-Factor Authentication
975 -------------------------
977 Users of the admin interface can configure two-factor authentication to
978 increase protection of their accounts.
980 NOTE: Joining a cluster with two-factor authentication enabled for the `root`
981 user is not supported. Remove the second factor when joining the cluster.
983 Available Second Factors
984 ~~~~~~~~~~~~~~~~~~~~~~~~
986 You can set up multiple second factors, in order to avoid a situation in which
987 losing your smartphone or security key locks you out of your account
990 The following two-factor authentication methods are available:
992 * User configured TOTP
993 (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
994 A short code derived from a shared secret and the current time, it changes
996 * WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
997 A general standard for authentication. It is implemented by various security
998 devices, like hardware keys or trusted platform modules (TPM) from a computer
1000 * Single use Recovery Keys. A list of keys which should either be
1001 printed out and locked in a secure place or saved digitally in an electronic
1002 vault. Each key can be used only once. These are perfect for ensuring that
1003 you are not locked out, even if all of your other second factors are lost or
1006 Configuration of Two-Factor
1007 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1009 Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login,
1010 via the 'TFA' button in the user list.
1012 Users can always add and use one time 'Recovery Keys'.
1014 //[thumbnail="screenshot/gui-datacenter-two-factor.png"]//TODO
1016 [[user_tfa_setup_totp]]
1019 //[thumbnail="screenshot/pve-gui-tfa-add-totp.png"]//TODO
1021 There is no server setup required. Simply install a TOTP app on your
1022 smartphone (for example, https://github.com/andOTP/andOTP#downloads[andOTP])
1023 and use the Proxmox Backup Server web-interface to add a TOTP factor.
1025 After opening the 'TOTP' window, the user is presented with a dialog to set up
1026 'TOTP' authentication. The 'Secret' field contains the key, which can be
1027 randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
1028 added to provide information to the 'TOTP' app about what the key belongs to.
1029 Most 'TOTP' apps will show the issuer name together with the corresponding
1030 'OTP' values. The username is also included in the QR code for the 'TOTP' app.
1032 After generating a key, a QR code will be displayed, which can be used with most
1033 OTP apps such as FreeOTP. The user then needs to verify the current user
1034 password (unless logged in as 'root'), as well as the ability to correctly use
1035 the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
1036 field and pressing the 'Apply' button.
1039 [[user_tfa_setup_webauthn]]
1042 For WebAuthn to work, you need to have two things:
1044 * A trusted HTTPS certificate (for example, by using
1045 xref:sysadmin_certs_get_trusted_acme_cert[Let's Encrypt]).
1046 While it probably works with an untrusted certificate, some browsers may
1047 warn or refuse WebAuthn operations if it is not trusted.
1048 * Setup the WebAuthn configuration (see *User Management -> Two Factor ->
1049 WebAuthn* in the {pmg} web interface). This can be
1050 auto-filled in most setups.
1052 Once you have fulfilled both of these requirements, you can add a WebAuthn
1053 configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
1056 [[user_tfa_setup_recovery_keys]]
1059 //[thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]//TODO
1061 Recovery key codes do not need any preparation; you can simply create a
1062 set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
1065 NOTE: There can only be one set of single-use recovery keys per user at any
1068 WebAuthn Configuration
1069 ~~~~~~~~~~~~~~~~~~~~~~
1071 //[thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]//TODO
1073 To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
1074 domain with a valid SSL certificate, otherwise some browsers may warn or refuse
1075 to authenticate altogether.
1077 NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
1078 registrations unusable!
1080 You can configure WebAuthn directly in the 'Two Factor' panel, there's an
1081 auto-fill button that will set the correct values for most setups.
1084 include::pmg-copyright.adoc[]