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
29 Interface (GUI), but it is also possible to directly edit the
30 configuration files, use the REST API over 'https'
31 or the command line tool `pmgsh`.
33 The command line tool `pmgconfig` is used to simplify some common
34 configuration tasks, i.e. to generate cerificates and to rewrite
35 service configuration files.
37 NOTE: We use a Postgres database to store mail filter rules and
38 statistic data. See chapter xref:chapter_pmgdb[Database Management]
42 Configuration files overview
43 ----------------------------
45 `/etc/network/interfaces`::
47 Network setup. We never modify this files directly. Instead, we write
48 changes to `/etc/network/interfaces.new`. When you reboot, we rename
49 the file to `/etc/network/interfaces`, so any changes gets activated
54 DNS search domain and nameserver setup.
58 The system's host name.
62 Static table lookup for hostnames.
66 Stores common administration options, i.e. the spam and mail proxy setup.
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 be the HTTPs server (API).
123 `/etc/pmg/pmg-authkey.key`::
125 Privat key use to generate authentication tickets.
127 `/etc/pmg/pmg-authkey.pub`::
129 Public key use 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. Those services use
151 separate configuration files, so we need to rewrite those files when
152 configuration is changed.
154 We use a template based approach to generate those 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 them directly, because your modification would get 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 setting, 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 regeneration of all template based
175 configuration files. You need to run that 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.
190 [[pmgconfig_systemconfig]]
198 image::images/screenshot/pmg-gui-network-config.png[]
201 Normally the network and time is already configured when you visit the
202 GUI. The installer asks for those settings and sets up the correct
205 The default setup uses a single Ethernet adapter and static IP
206 assignment. The configuration is stored at '/etc/network/interfaces',
207 and the actual network setup is done the standard Debian way using
210 .Example network setup '/etc/network/interfaces'
212 source /etc/network/interfaces.d/*
215 iface lo inet loopback
218 iface ens18 inet static
219 address 192.168.2.127
220 netmask 255.255.240.0
226 Many tests to detect SPAM mails use DNS queries, so it is important to
227 have a fast and reliable DNS server. We also query some public
228 available DNS Blacklists. Most of them apply rate limits for clients,
229 so they simply will not work if you use a public DNS server (because
230 they are usually blocked). We recommend to use your own DNS server,
231 which need to be configured in 'recursive' mode.
238 image::images/screenshot/pmg-gui-system-options.png[]
242 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
243 using the following configuration keys:
245 include::pmg.admin-conf-opts.adoc[]
248 Mail Proxy Configuration
249 ------------------------
251 [[pmgconfig_mailproxy_relaying]]
256 image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
259 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
260 using the following configuration keys:
262 include::pmg.mail-relaying-conf-opts.adoc[]
264 [[pmgconfig_mailproxy_relay_domains]]
269 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
272 List of relayed mail domains, i.e. what destination domains this
273 system will relay mail to. The system will reject incoming mails to
277 [[pmgconfig_mailproxy_ports]]
282 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
285 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
286 using the following configuration keys:
288 include::pmg.mail-ports-conf-opts.adoc[]
291 [[pmgconfig_mailproxy_options]]
296 image::images/screenshot/pmg-gui-mailproxy-options.png[]
299 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
300 using the following configuration keys:
302 include::pmg.mail-options-conf-opts.adoc[]
305 [[pmgconfig_mailproxy_before_after_queue]]
306 Before and After Queue scanning
307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309 Scanning email can happen at two different stages of mail-processing:
311 * During the SMTP Session after the complete message has been received (after
312 the 'DATA' command), known as 'before queue filtering'.
314 * After intially accepting the mail and putting it on a queue for further
315 processing, known as 'after queue filtering'.
317 The former has the advantage that the system can reject a mail (by sending a
318 permanent reject code '554'), and leave the task of notifying the original
319 sender to the other mailserver. This is of particular advantage if the
320 processed mail is a spam message or contains a virus and has a forged
321 sender-address. Sending out a notification in this situation leads so-called
322 'backscatter' mail, which might cause your server to get listed as spamming on
325 The latter has the advantage of providing faster delivery of mails for the
326 sending servers, since queueing mails is much faster than analyzing it for
329 If a mail is addressed to multiple recipients (e.g. when multiple addresses are
330 subscribed to the same mailinglist) the situation is more complicated: Your
331 mailserver can only reject or accept the mail for all recipients, after having
332 received the complete message, while your rule setup might accept the mail for
333 part of the recipients and reject it for others. This can be due to a
334 complicated rule setup, or if your users use the 'User White- and Blacklist'
337 If the resulting action of the rule system is the same for all recipients {pmg}
338 responds accordingly if configured for before queue filtering (sending '554'
339 for a blocked mail and '250' for an accepted or quarantined mail). If some
340 mailboxes accept the mail and some reject it the system has to accept the mail.
342 Whether {pmg} notifies the sender that delivery failed for some recipients by
343 sending a non-delivery report, depends on the 'ndr_on_block' setting in
344 '/etc/pmg/pmg.conf'. If enabled an NDR is sent. Keeping it disabled prevents
345 NDRs being sent to the (possibly forged) sender and thus minimizes the chance
346 of getting your IP listed on a RBL. However in certain environments it can be
347 unacceptable not to inform the sender about a rejected mail.
349 The setting has the same effect if after queue filtering is configured, with
350 the exception that an NDR is always sent out, even if all recipients block the
351 mail, since the mail already got accepted before being analyzed.
353 The details of integrating the mail proxy with {postfix} in both setups are
354 explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
356 NOTE: Since before queue filtering is currently incompatible with the
357 'Tracking Center' you need to enable it by manually
358 editing '/etc/pmg/pmg.conf'.
361 [[pmgconfig_mailproxy_transports]]
366 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
369 You can use {pmg} to send e-mails to different internal
370 e-mail servers. For example you can send e-mails addressed to
371 domain.com to your first e-mail server, and e-mails addressed to
372 subdomain.domain.com to a second one.
374 You can add the IP addresses, hostname and SMTP ports and mail domains (or
375 just single email addresses) of your additional e-mail servers.
378 [[pmgconfig_mailproxy_networks]]
383 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
386 You can add additional internal (trusted) IP networks or hosts.
387 All hosts in this list are allowed to relay.
389 NOTE: Hosts in the same subnet with Proxmox can relay by default and
390 it’s not needed to add them in this list.
393 [[pmgconfig_mailproxy_tls]]
398 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
401 Transport Layer Security (TLS) provides certificate-based
402 authentication and encrypted sessions. An encrypted session protects
403 the information that is transmitted with SMTP mail. When you activate
404 TLS, {pmg} automatically generates a new self signed
405 certificate for you (`/etc/pmg/pmg-tls.pem`).
407 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
408 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
409 server. Otherwise, messages are sent in the clear.
410 You can set a different TLS policy per desitination domain, should you for
411 example need to prevent e-mail delivery without encryption, or to work around
412 a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
413 on the supported policies.
417 To get additional information about SMTP TLS activity you can enable
418 TLS logging. That way information about TLS sessions and used
419 certificate’s is logged via syslog.
421 Add TLS received header::
423 Set this option to include information about the protocol and cipher
424 used as well as the client and issuer CommonName into the "Received:"
427 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
428 using the following configuration keys:
430 include::pmg.mail-tls-conf-opts.adoc[]
433 [[pmgconfig_mailproxy_dkim]]
437 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
438 cryptographically authenticate a mail as originating from a particular domain.
439 Before sending the mail a hash over certain header fields and the body is
440 computed, signed with a private key and added in the `DKIM-Signature` header of
441 the mail. The 'selector' (a short identifier chosen by you, used to identify
442 which system and private key were used for signing) is also included in the
443 `DKIM-Signature` header.
445 The verification is done by the receiver: The public key is fetched
446 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
447 for verifying the hash. You can publish multiple selectors for your domain,
448 each use by a system which sends e-mail from your domain, without the need to
449 share the private key.
451 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
453 Additionally it supports conditionally signing outbound mail if configured.
454 It uses one private key and selector per PMG deployment (all nodes in a cluster
455 use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
456 used as signing algorithm.
458 The headers included in the signature are taken from the list of
459 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
460 `CC`, `Reply-To` and `Subject` get oversigned.
462 You can either sign all mails received on the internal port using the domain of
463 the envelope sender address or create a list of domains, for which e-mails
464 should be signed, defaulting to the list of relay domains.
467 Enable DKIM Signing::
469 Controls whether outbound mail should get DKIM signed.
473 The selector used for signing the mail. The private key used for signing is
474 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
475 record which you need to add to all domains signed by {pmg} by clicking on the
476 'View DNS Record' Button.
478 Sign all Outgoing Mail::
480 Controls whether all outbound mail should get signed or only mails from domains
481 listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
483 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
484 using the following configuration keys:
486 include::pmg.admin-dkim-conf-opts.adoc[]
493 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
496 All SMTP checks are disabled for those entries (e. g. Greylisting,
499 NOTE: If you use a backup MX server (e.g. your ISP offers this service
500 for you) you should always add those servers here.
503 [[pmgconfig_spamdetector]]
504 Spam Detector Configuration
505 ---------------------------
511 image::images/screenshot/pmg-gui-spam-options.png[]
514 {pmg} uses a wide variety of local and network tests to identify spam
515 signatures. This makes it harder for spammers to identify one aspect
516 which they can craft their messages to work around the spam filter.
518 Every single e-mail will be analyzed and gets a spam score
519 assigned. The system attempts to optimize the efficiency of the rules
520 that are run in terms of minimizing the number of false positives and
523 include::pmg.spam-conf-opts.adoc[]
526 [[pmgconfig_spamdetector_quarantine]]
531 image::images/screenshot/pmg-gui-spamquar-options.png[]
534 Proxmox analyses all incoming e-mail messages and decides for each
535 e-mail if its ham or spam (or virus). Good e-mails are delivered to
536 the inbox and spam messages can be moved into the spam quarantine.
538 The system can be configured to send daily reports to inform users
539 about the personal spam messages received the last day. That report is
540 only sent if there are new messages in the quarantine.
542 Some options are only available in the config file `/etc/pmg/pmg.conf`,
543 and not in the webinterface.
545 include::pmg.spamquar-conf-opts.adoc[]
549 Virus Detector Configuration
550 ----------------------------
552 [[pmgconfig_clamav_options]]
557 image::images/screenshot/pmg-gui-virus-options.png[]
560 All mails are automatically passed to the included virus detector
561 ({clamav}). The default setting are considered safe, so it is usually
562 not required to change them.
564 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
565 using the following configuration keys:
567 include::pmg.clamav-conf-opts.adoc[]
570 image::images/screenshot/pmg-gui-clamav-database.png[]
573 Please note that the virus signature database it automatically
574 updated. But you can see the database status on the GUI, and you can
575 trigger manual updates there.
578 [[pmgconfig_clamav_quarantine]]
583 image::images/screenshot/pmg-gui-virusquar-options.png[]
586 Indentified virus mails are automatically moved to the virus
587 quarantine. The administartor can view those mails using the GUI, or
588 deliver them in case of false positives. {pmg} does not notify
589 individual users about received virus mails.
591 Virus quarantine related settings are saved to subsection 'virusquar'
592 in `/etc/pmg/pmg.conf`, using the following configuration keys:
594 include::pmg.virusquar-conf-opts.adoc[]
597 Custom SpamAssassin configuration
598 ---------------------------------
600 This is only for advanced users. {spamassassin}'s rules and their associated
601 scores get updated regularly and are trained on a huge corpus, which gets
602 classified by experts. In most cases adding a rule for matching a particular
603 keyword is the wrong approach, leading to many false positives. Usually bad
604 detection rates are better addressed by properly setting up DNS than by adding
605 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
606 spam-headers - see the {spamassassin_dnsbl}.
608 To add or change the Proxmox {spamassassin} configuration please login to the
609 console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
610 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
611 them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
612 the xref:pmgconfig_template_engine[template engine], while the others can
613 get updated by any {spamassassin} package upgrade.
615 To add your special configuration, you have to create a new file and name it
616 `custom.cf` (in this directory), then add your configuration there. Make sure
617 to use the correct {spamassassin} syntax, and test with
620 # spamassassin -D --lint
623 If you run a cluster, the `custom.cf` file is synchronized from the
624 master node to all cluster members automatically.
627 [[pmgconfig_custom_check]]
628 Custom Check Interface
629 ----------------------
631 For use cases which are not handled by the {pmg} Virus Detector and
632 {spamassassin} configuration, advanced users can create a custom check
633 executable which, if enabled will be called before the Virus Detector and before
634 passing an e-mail through the Rule System. The custom check API is kept as
635 simple as possible, while still providing a great deal of control over the
636 treatment of an e-mail. Its input is passed via two CLI arguments:
638 * the 'api-version' (currently `v1`) - for potential future change of the
641 * the 'queue-file-name' - a filename, which contains the complete e-mail as
644 The expected output need to be printed on STDOUT and consists of two lines:
646 * the 'api-version' (currently 'v1') - see above
648 * one of the following 3 results:
649 ** 'OK' - e-mail is ok
650 ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
651 (the virusdescription is logged and added to the e-mail's headers)
652 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
653 to the e-mail's spamscore
655 The check is run with a 5 minute timeout - if it is exceeded the check
656 executable is killed and the e-mail is treated as OK.
658 All output written to STDERR by the check is written with priority 'err' to the
661 A simple sample script following the API (and yielding a random result) for
667 echo "called with $*" 1>&2
669 if [ "$#" -ne 2 ]; then
670 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
677 if [ "$apiver" != "v1" ]; then
678 echo "wrong APIVERSION: $apiver" 1>&2
686 choice=$(shuf -i 0-3 -n1)
696 echo VIRUS: Random Virus
699 for i in $(seq 1 7); do
700 echo "custom checking mail: $queue_file - minute $i" 1>&2
709 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
716 The location of the custom check executable can also be set there with the key
717 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
723 User management in {pmg} consists of three types of users/accounts:
726 [[pmgconfig_localuser]]
730 image::images/screenshot/pmg-gui-local-user-config.png[]
732 Local users are used to manage and audit {pmg}. Those users can login on the
733 management web interface.
735 There are three roles:
739 Is allowed to manage settings of {pmg}, except some tasks like
740 network configuration and upgrading.
744 Is allowed to manage quarantines, blacklists and whitelists, but not other
745 settings. Has no right to view any other data.
749 With this role, the user is only allowed to view data and configuration, but
752 In addition there is always the 'root' user, which is used to perform special
753 system administrator tasks, such as updgrading a host or changing the
754 network configuration.
756 NOTE: Only pam users are able to login via the webconsole and ssh, which the
757 users created with the web interface are not. Those users are created for
758 {pmg} administration only.
760 Local user related settings are saved in `/etc/pmg/user.conf`.
762 For details of the fields see xref:pmg_user_configuration_file[user.conf]
765 LDAP/Active Directory
766 ~~~~~~~~~~~~~~~~~~~~~
768 image::images/screenshot/pmg-gui-ldap-user-config.png[]
770 You can specify multiple LDAP/Active Directory profiles, so that you can
771 create rules matching those users and groups.
773 Creating a profile requires (at least) the following:
776 * protocol (LDAP or LDAPS; LDAPS is recommended)
777 * at least one server
778 * a user and password (if your server does not support anonymous binds)
780 All other fields should work with the defaults for most setups, but can be
781 used to customize the queries.
783 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
784 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
789 It is highly recommended that the user which you use for connecting to the
790 LDAP server only has the permission to query the server. For LDAP servers
791 (for example OpenLDAP or FreeIPA), the username has to be of a format like
792 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
793 depending on your setup. For Active Directory servers, the format should be
794 like 'username@domain' or 'domain\username'.
799 {pmg} synchronizes the relevant user and group info periodically, so that
800 that information is available in a fast manner, even when the LDAP/AD server
801 is temporarily not accessible.
803 After a successfull sync, the groups and users should be visible on the web
804 interface. After that, you can create rules targeting LDAP users and groups.
807 [[pmgconfig_fetchmail]]
811 image::images/screenshot/pmg-gui-fetchmail-config.png[]
813 Fetchmail is utility for polling and forwarding e-mails. You can define
814 e-mail accounts, which will then be fetched and forwarded to the e-mail
817 You have to add an entry for each account/target combination you want to
818 fetch and forward. Those will then be regularly polled and forwarded,
819 according to your configuration.
821 The API and web interface offer following configuration options:
823 include::fetchmail.conf.5-opts.adoc[]
827 include::pmg-copyright.adoc[]