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/tls_inbound_domains`::
102 Sender domains for which TLS is enforced on inbound connections.
104 `/etc/pmg/transports`::
106 Message delivery transport setup.
108 `/etc/pmg/user.conf`::
110 GUI user configuration.
112 `/etc/mail/spamassassin/custom.cf`::
114 Custom {spamassassin} setup.
116 `/etc/mail/spamassassin/pmg-scores.cf`::
118 Custom {spamassassin} rule scores.
120 Keys and Certificates
121 ---------------------
123 `/etc/pmg/pmg-api.pem`::
125 Key and certificate (combined) used by the HTTPS server (API).
127 `/etc/pmg/pmg-authkey.key`::
129 Private key used to generate authentication tickets.
131 `/etc/pmg/pmg-authkey.pub`::
133 Public key used to verify authentication tickets.
135 `/etc/pmg/pmg-csrf.key`::
137 Internally used to generate CSRF tokens.
139 `/etc/pmg/pmg-tls.pem`::
141 Key and certificate (combined) to encrypt mail traffic (TLS).
143 `/etc/pmg/dkim/<selector>.private`::
145 Key for DKIM signing mails with selector '<selector>'.
148 [[pmgconfig_template_engine]]
149 Service Configuration Templates
150 -------------------------------
152 {pmg} uses various services to implement mail filtering, for example,
153 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
154 engine, and the Apache {spamassassin} project. These services use
155 separate configuration files, so we need to rewrite those files when the
156 configuration is changed.
158 We use a template-based approach to generate these files. The {tts} is
159 a well known, fast and flexible template processing system. You can
160 find the default templates in `/var/lib/pmg/templates/`. Please do not
161 modify these directly, otherwise your modifications will be lost on the
162 next update. Instead, copy the template you wish to change to
163 `/etc/pmg/templates/`, then apply your changes there.
165 Templates can access any configuration settings, and you can use the
166 `pmgconfig dump` command to get a list of all variable names:
171 dns.domain = yourdomain.tld
173 ipconfig.int_ip = 192.168.2.127
174 pmg.admin.advfilter = 1
178 The same tool is used to force the regeneration of all template-based
179 configuration files. You need to run the following after modifying a template,
180 or when you directly edit configuration files:
183 # pmgconfig sync --restart 1
186 The above command also restarts services if the underlying configuration
187 files are changed. Please note that this is automatically done when
188 you change the configuration using the GUI or API.
190 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
191 synced from the master node to all cluster members.
193 [[pmgconfig_whitelist_overview]]
194 White- and Blacklists
195 ---------------------
197 {pmg} has multiple white- and blacklists. It differentiates between the
198 xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
199 and the user whitelist.
200 In addition to the whitelists, there are two separate blacklists: the rule-based
201 blacklist and the user blacklist.
206 The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
207 greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
210 Rule-based White-/Blacklist
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
213 The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
214 rules. They work by checking the attached 'Who' objects, containing, for
215 example, a domain or a mail address for a match. If it matches, the assigned
216 action is used, which by default is 'Accept' for the whitelist rule and 'Block'
217 for the blacklist rule. In the default setup, the blacklist rule has priority
218 over the whitelist rule and spam checks.
220 User White-/Blacklist
221 ~~~~~~~~~~~~~~~~~~~~~
223 The user white- and blacklist are user specific. Every user can add mail addresses
224 to their white- and blacklist. When a user adds a mail address to the whitelist,
225 the result of the spam analysis will be discarded for that recipient. This can
226 help in the mail being accepted, but what happens next still depends on the
227 other rules. In the default setup, this results in the mail being accepted for
230 For mail addresses on a user's blacklist, the spam score will be increased by
231 100. What happens when a high spam score is encountered still depends on the
232 rule system. In the default setup, it will be recognized as spam and quarantined
233 (spam score of 3 or higher).
235 [[pmgconfig_systemconfig]]
243 [thumbnail="pmg-gui-network-config.png", big=1]
246 As network and time are configured in the installer, these generally do not
247 need to be configured again in the GUI.
249 The default setup uses a single Ethernet adapter and static IP
250 assignment. The configuration is stored at '/etc/network/interfaces',
251 and the actual network setup is done the standard Debian way, using the
254 .Example network setup '/etc/network/interfaces'
256 source /etc/network/interfaces.d/*
259 iface lo inet loopback
262 iface ens18 inet static
263 address 192.168.2.127
264 netmask 255.255.240.0
270 Many tests to detect SPAM mails use DNS queries, so it is important to
271 have a fast and reliable DNS server. We also query some publicly
272 available DNS Blacklists. Most of them apply rate limits for clients,
273 so they simply will not work if you use a public DNS server (because
274 they are usually blocked). We recommend to use your own DNS server,
275 which needs to be configured in 'recursive' mode.
282 [thumbnail="pmg-gui-system-options.png", big=1]
286 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
287 using the following configuration keys:
289 include::pmg.admin-conf-opts.adoc[]
292 include::pmg-ssl-certificate.adoc[]
294 Mail Proxy Configuration
295 ------------------------
297 [[pmgconfig_mailproxy_relaying]]
302 [thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
305 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
306 using the following configuration keys:
308 include::pmg.mail-relaying-conf-opts.adoc[]
310 [[pmgconfig_mailproxy_relay_domains]]
315 [thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
318 A list of relayed mail domains, that is, what destination domains this
319 system will relay mail to. The system will reject incoming mails to
323 [[pmgconfig_mailproxy_ports]]
328 [thumbnail="pmg-gui-mailproxy-ports.png", big=1]
331 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
332 using the following configuration keys:
334 include::pmg.mail-ports-conf-opts.adoc[]
337 [[pmgconfig_mailproxy_options]]
342 [thumbnail="pmg-gui-mailproxy-options.png", big=1]
345 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
346 using the following configuration keys:
348 include::pmg.mail-options-conf-opts.adoc[]
351 [[pmgconfig_mailproxy_before_after_queue]]
352 Before and After Queue scanning
353 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
355 Email scanning can happen at two different stages of mail-processing:
357 * Before-queue filtering: During the SMTP session, after the complete message
358 has been received (after the 'DATA' command).
360 * After-queue filtering: After initially accepting the mail and putting it on
361 a queue for further processing.
363 Before-queue filtering has the advantage that the system can reject a mail (by
364 sending a permanent reject code '554'), and leave the task of notifying the
365 original sender to the other mail server. This is of particular advantage if
366 the processed mail is a spam message or contains a virus and has a forged
367 sender address. Sending out a notification in this situation leads to so-called
368 'backscatter' mail, which might cause your server to get listed as spamming on
369 RBLs (Real-time Blackhole List).
371 After-queue filtering has the advantage of providing faster delivery of
372 mails for the sending servers, since queuing emails is much faster than
373 analyzing them for spam and viruses.
375 If a mail is addressed to multiple recipients (for example, when multiple
376 addresses are subscribed to the same mailing list), the situation is more
377 complicated; your mail server can only reject or accept the mail for all
378 recipients, after having received the complete message, while your rule setup
379 might accept the mail for part of the recipients and reject it for others. This
380 can be due to a complicated rule setup, or if your users use the 'User White-
381 and Blacklist' feature.
383 If the resulting action of the rule system is the same for all recipients, {pmg}
384 responds accordingly, if configured for before-queue filtering (sending '554'
385 for a blocked mail and '250' for an accepted or quarantined mail). If some
386 mailboxes accept the mail and some reject it, the system has to accept the mail.
388 Whether {pmg} notifies the sender that delivery failed for some recipients by
389 sending a non-delivery report, depends on the 'ndr_on_block' setting in
390 '/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
391 NDRs being sent to the (possibly forged) sender and thus minimizes the chance
392 of getting your IP listed on an RBL. However in certain environments, it can be
393 unacceptable not to inform the sender about a rejected mail.
395 The setting has the same effect if after-queue filtering is configured, with
396 the exception that an NDR is always sent out, even if all recipients block the
397 mail, since the mail already got accepted before being analyzed.
399 The details of integrating the mail proxy with {postfix} in both setups are
400 explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
403 [[pmgconfig_mailproxy_greylisting]]
407 Greylisting is a technique for preventing unwanted messages from reaching the
408 resource intensive stages of content analysis (virus detection and spam
409 detection). By initially replying with a temporary failure code ('450') to
410 each new email, {pmg} tells the sending server that it should queue the
411 mail and retry delivery at a later point. Since certain kinds of spam get
412 sent out by software which has no provisioning for queuing, these mails are
413 dropped without reaching {pmg} or your mailbox.
415 The downside of greylisting is the delay introduced by the initial deferral of
416 the email, which usually amounts to less than 30 minutes.
418 In order to prevent unnecessary delays in delivery from known sources, emails
419 coming from a source for a recipient, which have passed greylisting in the
420 past are directly passed on: For each email the triple '<sender network,
421 sender email, recipient email>' is stored in a list, along with the time when
422 delivery was attempted. If an email fits an already existing triple, the
423 timestamp for that triple is updated, and the email is accepted for further
426 As long as a sender and recipient communicate frequently, there is no delay
427 introduced by enabling greylisting. A triple is removed after a longer period
428 of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
431 * 2 days for the retry of the first delivery
433 * 36 days for a known triple
435 Mails with an empty envelope sender are always delayed.
437 Some email service providers send out emails for one domain from multiple
438 servers. To prevent delays due to an email coming in from two separate IPs of
439 the same provider, the triples store a network ('cidr') instead of a single IP.
440 For certain large providers, the default network size might be too small. You
441 can configure the netmask applied to an IP for the greylist lookup in
442 '/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
443 and 'greylistmask6' for IPv6 respectively.
446 [[pmgconfig_mailproxy_transports]]
451 [thumbnail="pmg-gui-mailproxy-transports.png", big=1]
454 You can use {pmg} to send emails to different internal email servers. For
455 example, you can send emails addressed to domain.com to your first email server
456 and emails addressed to subdomain.domain.com to a second one.
458 You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
459 transport ports and mail domains (or just single email addresses) of your
460 additional email servers. When transport protocol is set to `lmtp`, the option
461 'Use MX' is useless and will automatically be set to 'No'.
464 [[pmgconfig_mailproxy_networks]]
469 [thumbnail="pmg-gui-mailproxy-networks.png", big=1]
472 You can add additional internal (trusted) IP networks or hosts. All hosts in
473 this list are allowed to relay.
475 NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
476 be added to this list.
479 [[pmgconfig_mailproxy_tls]]
484 [thumbnail="pmg-gui-mailproxy-tls.png", big=1]
487 Transport Layer Security (TLS) provides certificate-based authentication and
488 encrypted sessions. An encrypted session protects the information that is
489 transmitted with SMTP mail. When you activate TLS, {pmg} automatically
490 generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
492 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
493 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
494 server. Otherwise, messages are sent unencrypted.
496 You can set a different TLS policy per destination. A destination is either a
497 remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
498 This can be used if you need to prevent email delivery without
499 encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
500 {postfix_tls_readme} for details on the supported policies.
502 Additionally, TLS can also be enforced on incoming connections on the external
503 port for specific sender domains by creating a TLS inbound domains entry. Mails
504 with matching domains must use a encrypted SMTP session, otherwise they are
505 rejected. All domains on this list have and entry of
506 https://www.postfix.org/postconf.5.html#reject_plaintext_session[`reject_plaintext_session`]
507 in a `check_sender_access` table.
511 To get additional information about SMTP TLS activity, you can enable
512 TLS logging. In this case, information about TLS sessions and used
513 certificates is logged via syslog.
515 Add TLS received header::
517 Set this option to include information about the protocol and cipher
518 used, as well as the client and issuer CommonName into the "Received:"
521 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
522 using the following configuration keys:
524 include::pmg.mail-tls-conf-opts.adoc[]
527 [[pmgconfig_mailproxy_dkim]]
532 [thumbnail="pmg-gui-mailproxy-dkim.png", big=1]
535 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
536 cryptographically authenticate a mail as originating from a particular domain.
537 Before sending the mail, a hash over certain header fields and the body is
538 computed, signed with a private key and added in the `DKIM-Signature` header of
539 the mail. The 'selector' (a short identifier chosen by you, used to identify
540 which system and private key were used for signing) is also included in the
541 `DKIM-Signature` header.
543 The verification is done by the receiver. The public key is fetched
544 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
545 for verifying the hash. You can publish multiple selectors for your domain,
546 each used by a system which sends email from your domain, without the need to
547 share the private key.
549 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
551 Additionally, it supports conditionally signing outbound mail, if configured.
552 It uses one private key and selector per {pmg} deployment (all nodes in a
553 cluster use the same key). The key has a minimal size of 1024 bits and
554 rsa-sha256 is used as the signing algorithm.
556 The headers included in the signature are taken from the list of
557 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
558 `CC`, `Reply-To` and `Subject` get oversigned.
560 You can either sign all mails received on the internal port using the domain of
561 the envelope sender address or create a list of domains, for which emails
562 should be signed, defaulting to the list of relay domains.
565 Enable DKIM Signing::
567 Controls whether outbound mail should get DKIM signed.
571 The selector used for signing the mail. The private key used for signing is
572 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
573 record which you need to add to all domains signed by {pmg} by clicking on the
574 'View DNS Record' Button.
576 Sign all Outgoing Mail::
578 Controls whether all outbound mail should get signed or only mails from domains
579 listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
582 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
583 using the following configuration keys:
585 include::pmg.admin-dkim-conf-opts.adoc[]
592 [thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
595 All SMTP checks are disabled for those entries (e.g. Greylisting,
598 DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
599 This means it can only make use of the `IP Address` and `IP Network` entries.
601 NOTE: If you use a backup MX server (for example, your ISP offers this service
602 for you) you should always add those servers here.
604 NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
605 xref:pmgconfig_mailproxy_options[Mail Proxy Options].
607 [[pmgconfig_spamdetector]]
608 Spam Detector Configuration
609 ---------------------------
615 [thumbnail="pmg-gui-spam-options.png", big=1]
618 {pmg} uses a wide variety of local and network tests to identify spam
619 signatures. This makes it harder for spammers to identify one aspect
620 which they can craft their messages to work around the spam filter.
622 Every single email will be analyzed and have a spam score
623 assigned. The system attempts to optimize the efficiency of the rules
624 that are run in terms of minimizing the number of false positives and
627 include::pmg.spam-conf-opts.adoc[]
630 [[pmgconfig_spamdetector_quarantine]]
635 [thumbnail="pmg-gui-spamquar-options.png", big=1]
638 {pmg} analyses all incoming email messages and decides for each
639 email if it is ham or spam (or virus). Good emails are delivered to
640 the inbox and spam messages are moved into the spam quarantine.
642 The system can be configured to send daily reports to inform users
643 about personal spam messages received in the last day. The report is
644 only sent if there are new messages in the quarantine.
646 Some options are only available in the config file `/etc/pmg/pmg.conf`,
647 and not in the web interface.
649 include::pmg.spamquar-conf-opts.adoc[]
652 [[pmgconfig_spamdetector_customscores]]
653 Customization of Rulescores
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
657 [thumbnail="pmg-gui-spam-custom-scores.png", big=1]
660 While the default scoring of {spamassassin}'s ruleset provides very good
661 detection rates, sometimes your particular environment can benefit from
662 slightly adjusting the score of a particular rule. Two examples:
664 * Your system receives spam mails which are scored at 4.9 and you have
665 a rule which puts all mails above 5 in the quarantine. The one thing the
666 spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing
667 the score of this rule by 0.2 points the spam mails would all be quarantined
668 instead of being sent to your users
670 * Your system tags many legitimate mails from a partner organization as spam,
671 because the organization has a policy that each mail has to start with
672 'Dear madam or sir' (generating 1.9 points through the rule
673 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
676 The system logs all the rules which a particular mail hits. Analyzing the logs can
677 lead to finding such a pattern in your environment.
679 You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
680 in the GUI and entering a {spamassassin} rule as the name.
682 NOTE: In general, it is strongly recommended not to make large changes to the
687 Virus Detector Configuration
688 ----------------------------
690 [[pmgconfig_clamav_options]]
695 [thumbnail="pmg-gui-virus-options.png", big=1]
698 All mails are automatically passed to the included virus detector
699 ({clamav}). The default settings are considered safe, so it is usually
700 not required to change them.
702 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
703 using the following configuration keys:
705 include::pmg.clamav-conf-opts.adoc[]
708 [thumbnail="pmg-gui-clamav-database.png", big=1]
711 Please note that the virus signature database is automatically
712 updated. You can see the database status in the GUI, and also
713 trigger manual updates from there.
716 [[pmgconfig_clamav_quarantine]]
721 [thumbnail="pmg-gui-virusquar-options.png", big=1]
724 Identified virus mails are automatically moved to the virus
725 quarantine. The administrator can view these mails from the GUI, and
726 choose to deliver them, in case of false positives. {pmg} does not notify
727 individual users about received virus mails.
729 Virus quarantine related settings are saved to subsection 'virusquar'
730 in `/etc/pmg/pmg.conf`, using the following configuration keys:
732 include::pmg.virusquar-conf-opts.adoc[]
735 Custom SpamAssassin configuration
736 ---------------------------------
738 This is only for advanced users. {spamassassin}'s rules and their associated
739 scores get updated regularly and are trained on a huge corpus, which gets
740 classified by experts. In most cases, adding a rule for matching a particular
741 keyword is the wrong approach, leading to many false positives. Usually bad
742 detection rates are better addressed by properly setting up DNS than by adding
743 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
744 spam-headers - see the {spamassassin_dnsbl}.
746 To add or change the Proxmox {spamassassin} configuration, log in to the
747 console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
748 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
749 them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
750 the xref:pmgconfig_template_engine[template engine], while the others can
751 get updated by any {spamassassin} package upgrade.
753 To add your custom configuration, you have to create a new file named
754 `custom.cf` (in `/etc/mail/spamassassin/`), then add your configuration there.
755 Make sure to use the correct {spamassassin_rule_syntax} and test it with:
758 # spamassassin -D --lint
761 If you run a cluster, the `custom.cf` file is synchronized from the
762 master node to all cluster members automatically.
764 To adjust the score assigned to a particular rule, you
765 can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
769 [[pmgconfig_custom_check]]
770 Custom Check Interface
771 ----------------------
773 For use-cases which are not handled by the {pmg} Virus Detector and
774 {spamassassin} configuration, advanced users can create a custom check
775 executable which, if enabled will be called before the Virus Detector and before
776 passing an email through the Rule System. The custom check API is kept as
777 simple as possible, while still providing a great deal of control over the
778 treatment of an email. Its input is passed via two CLI arguments:
780 * the 'api-version' (currently `v1`) - for potential future change of the
783 * the 'queue-file-name' - a filename, which contains the complete email as
786 The expected output needs to be printed to STDOUT and consists of two lines:
788 * the 'api-version' (currently 'v1') - see above
790 * one of the following 3 results:
791 ** 'OK' - email is OK
792 ** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
793 (the virus description is logged and added to the email's headers)
794 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
795 to the email's spamscore
797 The check is run with a 5 minute timeout - if this is exceeded, the check
798 executable is killed and the email is treated as OK.
800 All output written to STDERR by the check is written with priority 'err' to the
803 Below is a simple sample script following the API (and yielding a random result)
809 echo "called with $*" 1>&2
811 if [ "$#" -ne 2 ]; then
812 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
819 if [ "$apiver" != "v1" ]; then
820 echo "wrong APIVERSION: $apiver" 1>&2
828 choice=$(shuf -i 0-3 -n1)
838 echo VIRUS: Random Virus
841 for i in $(seq 1 7); do
842 echo "custom checking mail: $queue_file - minute $i" 1>&2
851 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
858 The location of the custom check executable can also be set there with the key
859 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
865 User management in {pmg} consists of three types of users/accounts:
868 [[pmgconfig_localuser]]
872 [thumbnail="pmg-gui-local-user-config.png", big=1]
874 Local users can manage and audit {pmg}. They can login on the management web
877 There are four roles:
881 Is allowed to manage settings of {pmg}, excluding some tasks like network
882 configuration and upgrading.
886 Is allowed to manage quarantines, blacklists and whitelists, but not other
887 settings. Has no right to view any other data.
891 With this role, the user is only allowed to view data and configuration, but
896 Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
898 In addition, there is always the 'root' user, which is used to perform special
899 system administrator tasks, such as upgrading a host or changing the network
902 NOTE: Only PAM users are able to log in via the web interface and ssh, while the
903 users created through the web interface are not. Those users are created for
904 {pmg} administration only.
906 Local user related settings are saved in `/etc/pmg/user.conf`.
908 For details on the fields, see xref:pmg_user_configuration_file[user.conf]
911 LDAP/Active Directory
912 ~~~~~~~~~~~~~~~~~~~~~
914 [thumbnail="pmg-gui-ldap-user-config.png", big=1]
916 With {pmg}, users can use LDAP and Active directory as authentication methods to
917 access their individual xref:pmgadministration_spam_quarantine[Spam Quarantine].
918 Additionally, if users have extra email aliases defined in the LDAP directory,
919 they will have a single spam quarantine for all of these.
921 NOTE: Authentication via LDAP must first be enabled using the `Authentication
922 mode` (`authmode`) parameter in the
923 xref:pmgconfig_spamdetector_quarantine[Spam Detector's Quarantine configuration settings].
925 You can specify multiple LDAP/Active Directory profiles, so that you can
926 create rules matching particular users and groups.
928 Creating a profile requires (at least) the following:
930 * `Profile Name`: The name assigned to the LDAP profile.
931 * `Protocol`: LDAP, LDAPS, or LDAP+STARTTLS (LDAP+STARTTLS is recommended).
932 * `Server`: The domain name/IP address of the LDAP server. A fallback can also
933 be configured using the second field.
934 * `User name`: The Bind DN for authentication on the LDAP server.
935 This is required if your server does not support anonymous binds.
936 * `Password`: Password for the Bind DN user.
937 * `Base DN`: The directory which users are searched under.
939 All other fields should work with the defaults for most setups, but can be
940 used to customize the queries.
942 The settings are saved to `/etc/pmg/ldap.conf`. Details about the options
943 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
948 It is highly recommended that the user which you use for connecting to the
949 LDAP server only has permission to query the server. For LDAP servers
950 (for example OpenLDAP or FreeIPA), the username has to be of a format like
951 'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
952 depend on your setup. For Active Directory servers, the format should be
953 'username@domain' or 'domain\username'.
958 {pmg} synchronizes the relevant user and group information periodically, so that
959 the information is quickly available, even when the LDAP/AD server is
960 temporarily inaccessible.
962 After a successful sync, the groups and users should be visible on the web
963 interface. Following this, you can create rules targeting LDAP users and groups.
966 [[pmgconfig_fetchmail]]
970 [thumbnail="pmg-gui-fetchmail-config.png", big=1]
972 Fetchmail is a utility for polling and forwarding emails. You can define
973 email accounts, which will then be fetched and forwarded to the email
976 You have to add an entry for each account/target combination you want to
977 fetch and forward. These will then be regularly polled and forwarded,
978 according to your configuration.
980 The API and web interface offer the following configuration options:
982 include::fetchmail.conf.5-opts.adoc[]
985 Two-Factor Authentication
986 -------------------------
988 Users of the admin interface can configure two-factor authentication to
989 increase protection of their accounts.
991 NOTE: Joining a cluster with two-factor authentication enabled for the `root`
992 user is not supported. Remove the second factor when joining the cluster.
994 Available Second Factors
995 ~~~~~~~~~~~~~~~~~~~~~~~~
997 You can set up multiple second factors, in order to avoid a situation in which
998 losing your smartphone or security key locks you out of your account
1001 The following two-factor authentication methods are available:
1003 * User configured TOTP
1004 (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
1005 A short code derived from a shared secret and the current time, it changes
1007 * WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
1008 A general standard for authentication. It is implemented by various security
1009 devices, like hardware keys or trusted platform modules (TPM) from a computer
1011 * Single use Recovery Keys. A list of keys which should either be
1012 printed out and locked in a secure place or saved digitally in an electronic
1013 vault. Each key can be used only once. These are perfect for ensuring that
1014 you are not locked out, even if all of your other second factors are lost or
1017 Configuration of Two-Factor
1018 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1020 Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login,
1021 via the 'TFA' button in the user list.
1023 Users can always add and use one time 'Recovery Keys'.
1025 //[thumbnail="screenshot/gui-datacenter-two-factor.png"]//TODO
1027 [[user_tfa_setup_totp]]
1030 //[thumbnail="screenshot/pve-gui-tfa-add-totp.png"]//TODO
1032 There is no server setup required. Simply install a TOTP app on your
1033 smartphone (for example, https://github.com/andOTP/andOTP#downloads[andOTP])
1034 and use the Proxmox Backup Server web-interface to add a TOTP factor.
1036 After opening the 'TOTP' window, the user is presented with a dialog to set up
1037 'TOTP' authentication. The 'Secret' field contains the key, which can be
1038 randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
1039 added to provide information to the 'TOTP' app about what the key belongs to.
1040 Most 'TOTP' apps will show the issuer name together with the corresponding
1041 'OTP' values. The username is also included in the QR code for the 'TOTP' app.
1043 After generating a key, a QR code will be displayed, which can be used with most
1044 OTP apps such as FreeOTP. The user then needs to verify the current user
1045 password (unless logged in as 'root'), as well as the ability to correctly use
1046 the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
1047 field and pressing the 'Apply' button.
1050 [[user_tfa_setup_webauthn]]
1053 For WebAuthn to work, you need to have two things:
1055 * A trusted HTTPS certificate (for example, by using
1056 xref:sysadmin_certs_get_trusted_acme_cert[Let's Encrypt]).
1057 While it probably works with an untrusted certificate, some browsers may
1058 warn or refuse WebAuthn operations if it is not trusted.
1059 * Setup the WebAuthn configuration (see *User Management -> Two Factor ->
1060 WebAuthn* in the {pmg} web interface). This can be
1061 auto-filled in most setups.
1063 Once you have fulfilled both of these requirements, you can add a WebAuthn
1064 configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
1067 [[user_tfa_setup_recovery_keys]]
1070 //[thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]//TODO
1072 Recovery key codes do not need any preparation; you can simply create a
1073 set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
1076 NOTE: There can only be one set of single-use recovery keys per user at any
1079 WebAuthn Configuration
1080 ~~~~~~~~~~~~~~~~~~~~~~
1082 //[thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]//TODO
1084 To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
1085 domain with a valid SSL certificate, otherwise some browsers may warn or refuse
1086 to authenticate altogether.
1088 NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
1089 registrations unusable!
1091 You can configure WebAuthn directly in the 'Two Factor' panel, there's an
1092 auto-fill button that will set the correct values for most setups.
1095 include::pmg-copyright.adoc[]