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 Service Configuration Templates
145 -------------------------------
147 {pmg} uses various services to implement mail filtering, for example
148 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
149 engine and the Apache {spamassassin} project. Those services use
150 separate configuration files, so we need to rewrite those files when
151 configuration is changed.
153 We use a template based approach to generate those files. The {tts} is
154 a well known, fast and flexible template processing system. You can
155 find the default templates in `/var/lib/pmg/templates/`. Please do not
156 modify them directly, because your modification would get lost on the
157 next update. Instead, copy the template you wish to change to
158 `/etc/pmg/templates/`, then apply your changes there.
160 Templates can access any configuration setting, and you can use the
161 `pmgconfig dump` command to get a list of all variable names:
166 dns.domain = yourdomain.tld
168 ipconfig.int_ip = 192.168.2.127
169 pmg.admin.advfilter = 1
173 The same tool is used to force regeneration of all template based
174 configuration files. You need to run that after modifying a template,
175 or when you directly edit configuration files
178 # pmgconfig sync --restart 1
181 The above command also restarts services if the underlying configuration
182 files are changed. Please note that this is automatically done when
183 you change the configuration using the GUI or API.
185 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
186 synced from the master node to all cluster members.
189 [[pmgconfig_systemconfig]]
197 image::images/screenshot/pmg-gui-network-config.png[]
200 Normally the network and time is already configured when you visit the
201 GUI. The installer asks for those settings and sets up the correct
204 The default setup uses a single Ethernet adapter and static IP
205 assignment. The configuration is stored at '/etc/network/interfaces',
206 and the actual network setup is done the standard Debian way using
209 .Example network setup '/etc/network/interfaces'
211 source /etc/network/interfaces.d/*
214 iface lo inet loopback
217 iface ens18 inet static
218 address 192.168.2.127
219 netmask 255.255.240.0
225 Many tests to detect SPAM mails use DNS queries, so it is important to
226 have a fast and reliable DNS server. We also query some public
227 available DNS Blacklists. Most of them apply rate limits for clients,
228 so they simply will not work if you use a public DNS server (because
229 they are usually blocked). We recommend to use your own DNS server,
230 which need to be configured in 'recursive' mode.
237 image::images/screenshot/pmg-gui-system-options.png[]
241 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
242 using the following configuration keys:
244 include::pmg.admin-conf-opts.adoc[]
247 Mail Proxy Configuration
248 ------------------------
250 [[pmgconfig_mailproxy_relaying]]
255 image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
258 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
259 using the following configuration keys:
261 include::pmg.mail-relaying-conf-opts.adoc[]
263 [[pmgconfig_mailproxy_relay_domains]]
268 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
271 List of relayed mail domains, i.e. what destination domains this
272 system will relay mail to. The system will reject incoming mails to
276 [[pmgconfig_mailproxy_ports]]
281 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
284 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
285 using the following configuration keys:
287 include::pmg.mail-ports-conf-opts.adoc[]
290 [[pmgconfig_mailproxy_options]]
295 image::images/screenshot/pmg-gui-mailproxy-options.png[]
298 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
299 using the following configuration keys:
301 include::pmg.mail-options-conf-opts.adoc[]
304 [[pmgconfig_mailproxy_before_after_queue]]
305 Before and After Queue scanning
306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
308 Scanning email can happen at two different stages of mail-processing:
310 * During the SMTP Session after the complete message has been received (after
311 the 'DATA' command), known as 'before queue filtering'.
313 * After intially accepting the mail and putting it on a queue for further
314 processing, known as 'after queue filtering'.
316 The former has the advantage that the system can reject a mail (by sending a
317 permanent reject code '554'), and leave the task of notifying the original
318 sender to the other mailserver. This is of particular advantage if the
319 processed mail is a spam message or contains a virus and has a forged
320 sender-address. Sending out a notification in this situation leads so-called
321 'backscatter' mail, which might cause your server to get listed as spamming on
324 The latter has the advantage of providing faster delivery of mails for the
325 sending servers, since queueing mails is much faster than analyzing it for
328 If a mail is addressed to multiple recipients (e.g. when multiple addresses are
329 subscribed to the same mailinglist) the situation is more complicated: Your
330 mailserver can only reject or accept the mail for all recipients, after having
331 received the complete message, while your rule setup might accept the mail for
332 part of the recipients and reject it for others. This can be due to a
333 complicated rule setup, or if your users use the 'User White- and Blacklist'
336 If the resulting action of the rule system is the same for all recipients {pmg}
337 responds accordingly if configured for before queue filtering (sending '554'
338 for a blocked mail and '250' for an accepted or quarantined mail). If some
339 mailboxes accept the mail and some reject it the system has to accept the mail.
341 Whether {pmg} notifies the sender that delivery failed for some recipients by
342 sending a non-delivery report, depends on the 'ndr_on_block' setting in
343 '/etc/pmg/pmg.conf'. If enabled an NDR is sent. Keeping it disabled prevents
344 NDRs being sent to the (possibly forged) sender and thus minimizes the chance
345 of getting your IP listed on a RBL. However in certain environments it can be
346 unacceptable not to inform the sender about a rejected mail.
348 The setting has the same effect if after queue filtering is configured, with
349 the exception that an NDR is always sent out, even if all recipients block the
350 mail, since the mail already got accepted before being analyzed.
352 The details of integrating the mail proxy with {postfix} in both setups are
353 explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
355 NOTE: Since before queue filtering is currently incompatible with the
356 'Tracking Center' you need to enable it by manually
357 editing '/etc/pmg/pmg.conf'.
360 [[pmgconfig_mailproxy_transports]]
365 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
368 You can use {pmg} to send e-mails to different internal
369 e-mail servers. For example you can send e-mails addressed to
370 domain.com to your first e-mail server, and e-mails addressed to
371 subdomain.domain.com to a second one.
373 You can add the IP addresses, hostname and SMTP ports and mail domains (or
374 just single email addresses) of your additional e-mail servers.
377 [[pmgconfig_mailproxy_networks]]
382 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
385 You can add additional internal (trusted) IP networks or hosts.
386 All hosts in this list are allowed to relay.
388 NOTE: Hosts in the same subnet with Proxmox can relay by default and
389 it’s not needed to add them in this list.
392 [[pmgconfig_mailproxy_tls]]
397 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
400 Transport Layer Security (TLS) provides certificate-based
401 authentication and encrypted sessions. An encrypted session protects
402 the information that is transmitted with SMTP mail. When you activate
403 TLS, {pmg} automatically generates a new self signed
404 certificate for you (`/etc/pmg/pmg-tls.pem`).
406 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
407 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
408 server. Otherwise, messages are sent in the clear.
409 You can set a different TLS policy per desitination domain, should you for
410 example need to prevent e-mail delivery without encryption, or to work around
411 a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
412 on the supported policies.
416 To get additional information about SMTP TLS activity you can enable
417 TLS logging. That way information about TLS sessions and used
418 certificate’s is logged via syslog.
420 Add TLS received header::
422 Set this option to include information about the protocol and cipher
423 used as well as the client and issuer CommonName into the "Received:"
426 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
427 using the following configuration keys:
429 include::pmg.mail-tls-conf-opts.adoc[]
432 [[pmgconfig_mailproxy_dkim]]
436 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
437 cryptographically authenticate a mail as originating from a particular domain.
438 Before sending the mail a hash over certain header fields and the body is
439 computed, signed with a private key and added in the `DKIM-Signature` header of
440 the mail. The 'selector' (a short identifier chosen by you, used to identify
441 which system and private key were used for signing) is also included in the
442 `DKIM-Signature` header.
444 The verification is done by the receiver: The public key is fetched
445 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
446 for verifying the hash. You can publish multiple selectors for your domain,
447 each use by a system which sends e-mail from your domain, without the need to
448 share the private key.
450 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
452 Additionally it supports conditionally signing outbound mail if configured.
453 It uses one private key and selector per PMG deployment (all nodes in a cluster
454 use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
455 used as signing algorithm.
457 The headers included in the signature are taken from the list of
458 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
459 `CC`, `Reply-To` and `Subject` get oversigned.
461 You can either sign all mails received on the internal port using the domain of
462 the envelope sender address or create a list of domains, for which e-mails
463 should be signed, defaulting to the list of relay domains.
466 Enable DKIM Signing::
468 Controls whether outbound mail should get DKIM signed.
472 The selector used for signing the mail. The private key used for signing is
473 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
474 record which you need to add to all domains signed by {pmg} by clicking on the
475 'View DNS Record' Button.
477 Sign all Outgoing Mail::
479 Controls whether all outbound mail should get signed or only mails from domains
480 listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
482 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
483 using the following configuration keys:
485 include::pmg.admin-dkim-conf-opts.adoc[]
492 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
495 All SMTP checks are disabled for those entries (e. g. Greylisting,
498 NOTE: If you use a backup MX server (e.g. your ISP offers this service
499 for you) you should always add those servers here.
502 [[pmgconfig_spamdetector]]
503 Spam Detector Configuration
504 ---------------------------
510 image::images/screenshot/pmg-gui-spam-options.png[]
513 {pmg} uses a wide variety of local and network tests to identify spam
514 signatures. This makes it harder for spammers to identify one aspect
515 which they can craft their messages to work around the spam filter.
517 Every single e-mail will be analyzed and gets a spam score
518 assigned. The system attempts to optimize the efficiency of the rules
519 that are run in terms of minimizing the number of false positives and
522 include::pmg.spam-conf-opts.adoc[]
525 [[pmgconfig_spamdetector_quarantine]]
530 image::images/screenshot/pmg-gui-spamquar-options.png[]
533 Proxmox analyses all incoming e-mail messages and decides for each
534 e-mail if its ham or spam (or virus). Good e-mails are delivered to
535 the inbox and spam messages can be moved into the spam quarantine.
537 The system can be configured to send daily reports to inform users
538 about the personal spam messages received the last day. That report is
539 only sent if there are new messages in the quarantine.
541 Some options are only available in the config file `/etc/pmg/pmg.conf`,
542 and not in the webinterface.
544 include::pmg.spamquar-conf-opts.adoc[]
548 Virus Detector Configuration
549 ----------------------------
551 [[pmgconfig_clamav_options]]
556 image::images/screenshot/pmg-gui-virus-options.png[]
559 All mails are automatically passed to the included virus detector
560 ({clamav}). The default setting are considered safe, so it is usually
561 not required to change them.
563 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
564 using the following configuration keys:
566 include::pmg.clamav-conf-opts.adoc[]
569 image::images/screenshot/pmg-gui-clamav-database.png[]
572 Please note that the virus signature database it automatically
573 updated. But you can see the database status on the GUI, and you can
574 trigger manual updates there.
577 [[pmgconfig_clamav_quarantine]]
582 image::images/screenshot/pmg-gui-virusquar-options.png[]
585 Indentified virus mails are automatically moved to the virus
586 quarantine. The administartor can view those mails using the GUI, or
587 deliver them in case of false positives. {pmg} does not notify
588 individual users about received virus mails.
590 Virus quarantine related settings are saved to subsection 'virusquar'
591 in `/etc/pmg/pmg.conf`, using the following configuration keys:
593 include::pmg.virusquar-conf-opts.adoc[]
596 Custom SpamAssassin configuration
597 ---------------------------------
599 This is only for advanced users. {spamassassin}'s rules and their associated
600 scores get updated regularly and are trained on a huge corpus, which gets
601 classified by experts. In most cases adding a rule for matching a particular
602 keyword is the wrong approach, leading to many false positives. Usually bad
603 detection rates are better addressed by properly setting up DNS than by adding
604 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
605 spam-headers - see the {spamassassin_dnsbl}.
607 To add or change the Proxmox {spamassassin} configuration please login to the
608 console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
609 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
610 them, as they will be overwritten by any {spamassassin} rule update.
612 To add your special configuration, you have to create a new file and name it
613 `custom.cf` (in this directory), then add your configuration there. Make sure
614 to use the correct {spamassassin} syntax, and test with
617 # spamassassin -D --lint
620 If you run a cluster, the `custom.cf` file is synchronized from the
621 master node to all cluster members automatically.
624 [[pmgconfig_custom_check]]
625 Custom Check Interface
626 ----------------------
628 For use cases which are not handled by the {pmg} Virus Detector and
629 {spamassassin} configuration, advanced users can create a custom check
630 executable which, if enabled will be called before the Virus Detector and before
631 passing an e-mail through the Rule System. The custom check API is kept as
632 simple as possible, while still providing a great deal of control over the
633 treatment of an e-mail. Its input is passed via two CLI arguments:
635 * the 'api-version' (currently `v1`) - for potential future change of the
638 * the 'queue-file-name' - a filename, which contains the complete e-mail as
641 The expected output need to be printed on STDOUT and consists of two lines:
643 * the 'api-version' (currently 'v1') - see above
645 * one of the following 3 results:
646 ** 'OK' - e-mail is ok
647 ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
648 (the virusdescription is logged and added to the e-mail's headers)
649 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
650 to the e-mail's spamscore
652 The check is run with a 5 minute timeout - if it is exceeded the check
653 executable is killed and the e-mail is treated as OK.
655 All output written to STDERR by the check is written with priority 'err' to the
658 A simple sample script following the API (and yielding a random result) for
664 echo "called with $*" 1>&2
666 if [ "$#" -ne 2 ]; then
667 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
674 if [ "$apiver" != "v1" ]; then
675 echo "wrong APIVERSION: $apiver" 1>&2
683 choice=$(shuf -i 0-3 -n1)
693 echo VIRUS: Random Virus
696 for i in $(seq 1 7); do
697 echo "custom checking mail: $queue_file - minute $i" 1>&2
706 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
713 The location of the custom check executable can also be set there with the key
714 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
720 User management in {pmg} consists of three types of users/accounts:
723 [[pmgconfig_localuser]]
727 image::images/screenshot/pmg-gui-local-user-config.png[]
729 Local users are used to manage and audit {pmg}. Those users can login on the
730 management web interface.
732 There are three roles:
736 Is allowed to manage settings of {pmg}, except some tasks like
737 network configuration and upgrading.
741 Is allowed to manage quarantines, blacklists and whitelists, but not other
742 settings. Has no right to view any other data.
746 With this role, the user is only allowed to view data and configuration, but
749 In addition there is always the 'root' user, which is used to perform special
750 system administrator tasks, such as updgrading a host or changing the
751 network configuration.
753 NOTE: Only pam users are able to login via the webconsole and ssh, which the
754 users created with the web interface are not. Those users are created for
755 {pmg} administration only.
757 Local user related settings are saved in `/etc/pmg/user.conf`.
759 For details of the fields see xref:pmg_user_configuration_file[user.conf]
762 LDAP/Active Directory
763 ~~~~~~~~~~~~~~~~~~~~~
765 image::images/screenshot/pmg-gui-ldap-user-config.png[]
767 You can specify multiple LDAP/Active Directory profiles, so that you can
768 create rules matching those users and groups.
770 Creating a profile requires (at least) the following:
773 * protocol (LDAP or LDAPS; LDAPS is recommended)
774 * at least one server
775 * a user and password (if your server does not support anonymous binds)
777 All other fields should work with the defaults for most setups, but can be
778 used to customize the queries.
780 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
781 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
786 It is highly recommended that the user which you use for connecting to the
787 LDAP server only has the permission to query the server. For LDAP servers
788 (for example OpenLDAP or FreeIPA), the username has to be of a format like
789 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
790 depending on your setup. For Active Directory servers, the format should be
791 like 'username@domain' or 'domain\username'.
796 {pmg} synchronizes the relevant user and group info periodically, so that
797 that information is available in a fast manner, even when the LDAP/AD server
798 is temporarily not accessible.
800 After a successfull sync, the groups and users should be visible on the web
801 interface. After that, you can create rules targeting LDAP users and groups.
804 [[pmgconfig_fetchmail]]
808 image::images/screenshot/pmg-gui-fetchmail-config.png[]
810 Fetchmail is utility for polling and forwarding e-mails. You can define
811 e-mail accounts, which will then be fetched and forwarded to the e-mail
814 You have to add an entry for each account/target combination you want to
815 fetch and forward. Those will then be regularly polled and forwarded,
816 according to your configuration.
818 The API and web interface offer following configuration options:
820 include::fetchmail.conf.5-opts.adoc[]
824 include::pmg-copyright.adoc[]