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_transports]]
309 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
312 You can use {pmg} to send e-mails to different internal
313 e-mail servers. For example you can send e-mails addressed to
314 domain.com to your first e-mail server, and e-mails addressed to
315 subdomain.domain.com to a second one.
317 You can add the IP addresses, hostname and SMTP ports and mail domains (or
318 just single email addresses) of your additional e-mail servers.
321 [[pmgconfig_mailproxy_networks]]
326 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
329 You can add additional internal (trusted) IP networks or hosts.
330 All hosts in this list are allowed to relay.
332 NOTE: Hosts in the same subnet with Proxmox can relay by default and
333 it’s not needed to add them in this list.
336 [[pmgconfig_mailproxy_tls]]
341 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
344 Transport Layer Security (TLS) provides certificate-based
345 authentication and encrypted sessions. An encrypted session protects
346 the information that is transmitted with SMTP mail. When you activate
347 TLS, {pmg} automatically generates a new self signed
348 certificate for you (`/etc/pmg/pmg-tls.pem`).
350 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
351 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
352 server. Otherwise, messages are sent in the clear.
353 You can set a different TLS policy per desitination domain, should you for
354 example need to prevent e-mail delivery without encryption, or to work around
355 a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
356 on the supported policies.
360 To get additional information about SMTP TLS activity you can enable
361 TLS logging. That way information about TLS sessions and used
362 certificate’s is logged via syslog.
364 Add TLS received header::
366 Set this option to include information about the protocol and cipher
367 used as well as the client and issuer CommonName into the "Received:"
370 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
371 using the following configuration keys:
373 include::pmg.mail-tls-conf-opts.adoc[]
376 [[pmgconfig_mailproxy_dkim]]
380 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
381 cryptographically authenticate a mail as originating from a particular domain.
382 Before sending the mail a hash over certain header fields and the body is
383 computed, signed with a private key and added in the `DKIM-Signature` header of
384 the mail. The 'selector' (a short identifier chosen by you, used to identify
385 which system and private key were used for signing) is also included in the
386 `DKIM-Signature` header.
388 The verification is done by the receiver: The public key is fetched
389 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
390 for verifying the hash. You can publish multiple selectors for your domain,
391 each use by a system which sends e-mail from your domain, without the need to
392 share the private key.
394 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
396 Additionally it supports conditionally signing outbound mail if configured.
397 It uses one private key and selector per PMG deployment (all nodes in a cluster
398 use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
399 used as signing algorithm.
401 The headers included in the signature are taken from the list of
402 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
403 `CC`, `Reply-To` and `Subject` get oversigned.
405 You can either sign all mails received on the internal port using the domain of
406 the envelope sender address or create a list of domains, for which e-mails
407 should be signed, defaulting to the list of relay domains.
410 Enable DKIM Signing::
412 Controls whether outbound mail should get DKIM signed.
416 The selector used for signing the mail. The private key used for signing is
417 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
418 record which you need to add to all domains signed by {pmg} by clicking on the
419 'View DNS Record' Button.
421 Sign all Outgoing Mail::
423 Controls whether all outbound mail should get signed or only mails from domains
424 listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
426 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
427 using the following configuration keys:
429 include::pmg.admin-dkim-conf-opts.adoc[]
436 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
439 All SMTP checks are disabled for those entries (e. g. Greylisting,
442 NOTE: If you use a backup MX server (e.g. your ISP offers this service
443 for you) you should always add those servers here.
446 [[pmgconfig_spamdetector]]
447 Spam Detector Configuration
448 ---------------------------
454 image::images/screenshot/pmg-gui-spam-options.png[]
457 {pmg} uses a wide variety of local and network tests to identify spam
458 signatures. This makes it harder for spammers to identify one aspect
459 which they can craft their messages to work around the spam filter.
461 Every single e-mail will be analyzed and gets a spam score
462 assigned. The system attempts to optimize the efficiency of the rules
463 that are run in terms of minimizing the number of false positives and
466 include::pmg.spam-conf-opts.adoc[]
469 [[pmgconfig_spamdetector_quarantine]]
474 image::images/screenshot/pmg-gui-spamquar-options.png[]
477 Proxmox analyses all incoming e-mail messages and decides for each
478 e-mail if its ham or spam (or virus). Good e-mails are delivered to
479 the inbox and spam messages can be moved into the spam quarantine.
481 The system can be configured to send daily reports to inform users
482 about the personal spam messages received the last day. That report is
483 only sent if there are new messages in the quarantine.
485 Some options are only available in the config file `/etc/pmg/pmg.conf`,
486 and not in the webinterface.
488 include::pmg.spamquar-conf-opts.adoc[]
492 Virus Detector Configuration
493 ----------------------------
495 [[pmgconfig_clamav_options]]
500 image::images/screenshot/pmg-gui-virus-options.png[]
503 All mails are automatically passed to the included virus detector
504 ({clamav}). The default setting are considered safe, so it is usually
505 not required to change them.
507 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
508 using the following configuration keys:
510 include::pmg.clamav-conf-opts.adoc[]
513 image::images/screenshot/pmg-gui-clamav-database.png[]
516 Please note that the virus signature database it automatically
517 updated. But you can see the database status on the GUI, and you can
518 trigger manual updates there.
521 [[pmgconfig_clamav_quarantine]]
526 image::images/screenshot/pmg-gui-virusquar-options.png[]
529 Indentified virus mails are automatically moved to the virus
530 quarantine. The administartor can view those mails using the GUI, or
531 deliver them in case of false positives. {pmg} does not notify
532 individual users about received virus mails.
534 Virus quarantine related settings are saved to subsection 'virusquar'
535 in `/etc/pmg/pmg.conf`, using the following configuration keys:
537 include::pmg.virusquar-conf-opts.adoc[]
540 Custom SpamAssassin configuration
541 ---------------------------------
543 This is only for advanced users. {spamassassin}'s rules and their associated
544 scores get updated regularly and are trained on a huge corpus, which gets
545 classified by experts. In most cases adding a rule for matching a particular
546 keyword is the wrong approach, leading to many false positives. Usually bad
547 detection rates are better addressed by properly setting up DNS than by adding
548 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
549 spam-headers - see the {spamassassin_dnsbl}.
551 To add or change the Proxmox {spamassassin} configuration please login to the
552 console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
553 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
554 them, as they will be overwritten by any {spamassassin} rule update.
556 To add your special configuration, you have to create a new file and name it
557 `custom.cf` (in this directory), then add your configuration there. Make sure
558 to use the correct {spamassassin} syntax, and test with
561 # spamassassin -D --lint
564 If you run a cluster, the `custom.cf` file is synchronized from the
565 master node to all cluster members automatically.
568 [[pmgconfig_custom_check]]
569 Custom Check Interface
570 ----------------------
572 For use cases which are not handled by the {pmg} Virus Detector and
573 {spamassassin} configuration, advanced users can create a custom check
574 executable which, if enabled will be called before the Virus Detector and before
575 passing an e-mail through the Rule System. The custom check API is kept as
576 simple as possible, while still providing a great deal of control over the
577 treatment of an e-mail. Its input is passed via two CLI arguments:
579 * the 'api-version' (currently `v1`) - for potential future change of the
582 * the 'queue-file-name' - a filename, which contains the complete e-mail as
585 The expected output need to be printed on STDOUT and consists of two lines:
587 * the 'api-version' (currently 'v1') - see above
589 * one of the following 3 results:
590 ** 'OK' - e-mail is ok
591 ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
592 (the virusdescription is logged and added to the e-mail's headers)
593 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
594 to the e-mail's spamscore
596 The check is run with a 5 minute timeout - if it is exceeded the check
597 executable is killed and the e-mail is treated as OK.
599 All output written to STDERR by the check is written with priority 'err' to the
602 A simple sample script following the API (and yielding a random result) for
608 echo "called with $*" 1>&2
610 if [ "$#" -ne 2 ]; then
611 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
618 if [ "$apiver" != "v1" ]; then
619 echo "wrong APIVERSION: $apiver" 1>&2
627 choice=$(shuf -i 0-3 -n1)
637 echo VIRUS: Random Virus
640 for i in $(seq 1 7); do
641 echo "custom checking mail: $queue_file - minute $i" 1>&2
650 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
657 The location of the custom check executable can also be set there with the key
658 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
664 User management in {pmg} consists of three types of users/accounts:
667 [[pmgconfig_localuser]]
671 image::images/screenshot/pmg-gui-local-user-config.png[]
673 Local users are used to manage and audit {pmg}. Those users can login on the
674 management web interface.
676 There are three roles:
680 Is allowed to manage settings of {pmg}, except some tasks like
681 network configuration and upgrading.
685 Is allowed to manage quarantines, blacklists and whitelists, but not other
686 settings. Has no right to view any other data.
690 With this role, the user is only allowed to view data and configuration, but
693 In addition there is always the 'root' user, which is used to perform special
694 system administrator tasks, such as updgrading a host or changing the
695 network configuration.
697 NOTE: Only pam users are able to login via the webconsole and ssh, which the
698 users created with the web interface are not. Those users are created for
699 {pmg} administration only.
701 Local user related settings are saved in `/etc/pmg/user.conf`.
703 For details of the fields see xref:pmg_user_configuration_file[user.conf]
706 LDAP/Active Directory
707 ~~~~~~~~~~~~~~~~~~~~~
709 image::images/screenshot/pmg-gui-ldap-user-config.png[]
711 You can specify multiple LDAP/Active Directory profiles, so that you can
712 create rules matching those users and groups.
714 Creating a profile requires (at least) the following:
717 * protocol (LDAP or LDAPS; LDAPS is recommended)
718 * at least one server
719 * a user and password (if your server does not support anonymous binds)
721 All other fields should work with the defaults for most setups, but can be
722 used to customize the queries.
724 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
725 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
730 It is highly recommended that the user which you use for connecting to the
731 LDAP server only has the permission to query the server. For LDAP servers
732 (for example OpenLDAP or FreeIPA), the username has to be of a format like
733 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
734 depending on your setup. For Active Directory servers, the format should be
735 like 'username@domain' or 'domain\username'.
740 {pmg} synchronizes the relevant user and group info periodically, so that
741 that information is available in a fast manner, even when the LDAP/AD server
742 is temporarily not accessible.
744 After a successfull sync, the groups and users should be visible on the web
745 interface. After that, you can create rules targeting LDAP users and groups.
748 [[pmgconfig_fetchmail]]
752 image::images/screenshot/pmg-gui-fetchmail-config.png[]
754 Fetchmail is utility for polling and forwarding e-mails. You can define
755 e-mail accounts, which will then be fetched and forwarded to the e-mail
758 You have to add an entry for each account/target combination you want to
759 fetch and forward. Those will then be regularly polled and forwarded,
760 according to your configuration.
762 The API and web interface offer following configuration options:
764 include::fetchmail.conf.5-opts.adoc[]
768 include::pmg-copyright.adoc[]