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/fetchmailrc`::
78 Fetchmail configuration (POP3 and IMAP setup).
80 `/etc/pmg/ldap.conf`::
84 `/etc/pmg/mynetworks`::
86 List of local (trusted) networks.
88 `/etc/pmg/subscription`::
90 Stores your subscription key and status.
92 `/etc/pmg/tls_policy`::
94 TLS policy for outbound connections.
96 `/etc/pmg/transports`::
98 Message delivery transport setup.
100 `/etc/pmg/user.conf`::
102 GUI user configuration.
104 `/etc/mail/spamassassin/custom.cf`::
106 Custom {spamassassin} setup.
109 Keys and Certificates
110 ---------------------
112 `/etc/pmg/pmg-api.pem`::
114 Key and certificate (combined) used be the HTTPs server (API).
116 `/etc/pmg/pmg-authkey.key`::
118 Privat key use to generate authentication tickets.
120 `/etc/pmg/pmg-authkey.pub`::
122 Public key use to verify authentication tickets.
124 `/etc/pmg/pmg-csrf.key`::
126 Internally used to generate CSRF tokens.
128 `/etc/pmg/pmg-tls.pem`::
130 Key and certificate (combined) to encrypt mail traffic (TLS).
133 Service Configuration Templates
134 -------------------------------
136 {pmg} uses various services to implement mail filtering, for example
137 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
138 engine and the Apache {spamassassin} project. Those services use
139 separate configuration files, so we need to rewrite those files when
140 configuration is changed.
142 We use a template based approach to generate those files. The {tts} is
143 a well known, fast and flexible template processing system. You can
144 find the default templates in `/var/lib/pmg/templates/`. Please do not
145 modify them directly, because your modification would get lost on the
146 next update. Instead, copy the template you wish to change to
147 `/etc/pmg/templates/`, then apply your changes there.
149 Templates can access any configuration setting, and you can use the
150 `pmgconfig dump` command to get a list of all variable names:
155 dns.domain = yourdomain.tld
157 ipconfig.int_ip = 192.168.2.127
158 pmg.admin.advfilter = 1
162 The same tool is used to force regeneration of all template based
163 configuration files. You need to run that after modifying a template,
164 or when you directly edit configuration files
167 # pmgconfig sync --restart 1
170 The above command also restarts services if the underlying configuration
171 files are changed. Please note that this is automatically done when
172 you change the configuration using the GUI or API.
174 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
175 synced from the master node to all cluster members.
178 [[pmgconfig_systemconfig]]
186 image::images/screenshot/pmg-gui-network-config.png[]
189 Normally the network and time is already configured when you visit the
190 GUI. The installer asks for those settings and sets up the correct
193 The default setup uses a single Ethernet adapter and static IP
194 assignment. The configuration is stored at '/etc/network/interfaces',
195 and the actual network setup is done the standard Debian way using
198 .Example network setup '/etc/network/interfaces'
200 source /etc/network/interfaces.d/*
203 iface lo inet loopback
206 iface ens18 inet static
207 address 192.168.2.127
208 netmask 255.255.240.0
214 Many tests to detect SPAM mails use DNS queries, so it is important to
215 have a fast and reliable DNS server. We also query some public
216 available DNS Blacklists. Most of them apply rate limits for clients,
217 so they simply will not work if you use a public DNS server (because
218 they are usually blocked). We recommend to use your own DNS server,
219 which need to be configured in 'recursive' mode.
226 image::images/screenshot/pmg-gui-system-options.png[]
230 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
231 using the following configuration keys:
233 include::pmg.admin-conf-opts.adoc[]
236 Mail Proxy Configuration
237 ------------------------
239 [[pmgconfig_mailproxy_relaying]]
244 image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
247 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
248 using the following configuration keys:
250 include::pmg.mail-relaying-conf-opts.adoc[]
252 [[pmgconfig_mailproxy_relay_domains]]
257 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
260 List of relayed mail domains, i.e. what destination domains this
261 system will relay mail to. The system will reject incoming mails to
265 [[pmgconfig_mailproxy_ports]]
270 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
273 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
274 using the following configuration keys:
276 include::pmg.mail-ports-conf-opts.adoc[]
279 [[pmgconfig_mailproxy_options]]
284 image::images/screenshot/pmg-gui-mailproxy-options.png[]
287 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
288 using the following configuration keys:
290 include::pmg.mail-options-conf-opts.adoc[]
293 [[pmgconfig_mailproxy_transports]]
298 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
301 You can use {pmg} to send e-mails to different internal
302 e-mail servers. For example you can send e-mails addressed to
303 domain.com to your first e-mail server, and e-mails addressed to
304 subdomain.domain.com to a second one.
306 You can add the IP addresses, hostname and SMTP ports and mail domains (or
307 just single email addresses) of your additional e-mail servers.
310 [[pmgconfig_mailproxy_networks]]
315 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
318 You can add additional internal (trusted) IP networks or hosts.
319 All hosts in this list are allowed to relay.
321 NOTE: Hosts in the same subnet with Proxmox can relay by default and
322 it’s not needed to add them in this list.
325 [[pmgconfig_mailproxy_tls]]
330 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
333 Transport Layer Security (TLS) provides certificate-based
334 authentication and encrypted sessions. An encrypted session protects
335 the information that is transmitted with SMTP mail. When you activate
336 TLS, {pmg} automatically generates a new self signed
337 certificate for you (`/etc/pmg/pmg-tls.pem`).
339 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
340 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
341 server. Otherwise, messages are sent in the clear.
342 You can set a different TLS policy per desitination domain, should you for
343 example need to prevent e-mail delivery without encryption, or to work around
344 a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
345 on the supported policies.
349 To get additional information about SMTP TLS activity you can enable
350 TLS logging. That way information about TLS sessions and used
351 certificate’s is logged via syslog.
353 Add TLS received header::
355 Set this option to include information about the protocol and cipher
356 used as well as the client and issuer CommonName into the "Received:"
359 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
360 using the following configuration keys:
362 include::pmg.mail-tls-conf-opts.adoc[]
365 [[pmgconfig_mailproxy_dkim]]
369 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
370 cryptographically authenticate a mail as originating from a particular domain.
371 Before sending the mail a hash over certain header fields and the body is
372 computed, signed with a private key and added in the `DKIM-Signature` header of
373 the mail. The 'selector' (a short identifier chosen by you, used to identify
374 which system and private key were used for signing) is also included in the
375 `DKIM-Signature` header.
377 The verification is done by the receiver: The public key is fetched
378 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
379 for verifying the hash. You can publish multiple selectors for your domain,
380 each use by a system which sends e-mail from your domain, without the need to
381 share the private key.
383 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
385 Additionally it supports conditionally signing outbound mail if configured.
386 It uses one private key and selector per PMG deployment (all nodes in a cluster
387 use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
388 used as signing algorithm.
390 The headers included in the signature are taken from the list of
391 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
392 `CC`, `Reply-To` and `Subject` get oversigned.
394 You can either sign all mails received on the internal port using the domain of
395 the envelope sender address or create a list of domains, for which e-mails
396 should be signed, defaulting to the list of relay domains.
399 Enable DKIM Signing::
401 Controls whether outbound mail should get DKIM signed.
405 The selector used for signing the mail. The private key used for signing is
406 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
407 record which you need to add to all domains signed by {pmg} by clicking on the
408 'View DNS Record' Button.
410 Sign all Outgoing Mail::
412 Controls whether all outbound mail should get signed or only mails from domains
413 listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
415 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
416 using the following configuration keys:
418 include::pmg.admin-dkim-conf-opts.adoc[]
425 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
428 All SMTP checks are disabled for those entries (e. g. Greylisting,
431 NOTE: If you use a backup MX server (e.g. your ISP offers this service
432 for you) you should always add those servers here.
435 [[pmgconfig_spamdetector]]
436 Spam Detector Configuration
437 ---------------------------
443 image::images/screenshot/pmg-gui-spam-options.png[]
446 {pmg} uses a wide variety of local and network tests to identify spam
447 signatures. This makes it harder for spammers to identify one aspect
448 which they can craft their messages to work around the spam filter.
450 Every single e-mail will be analyzed and gets a spam score
451 assigned. The system attempts to optimize the efficiency of the rules
452 that are run in terms of minimizing the number of false positives and
455 include::pmg.spam-conf-opts.adoc[]
458 [[pmgconfig_spamdetector_quarantine]]
463 image::images/screenshot/pmg-gui-spamquar-options.png[]
466 Proxmox analyses all incoming e-mail messages and decides for each
467 e-mail if its ham or spam (or virus). Good e-mails are delivered to
468 the inbox and spam messages can be moved into the spam quarantine.
470 The system can be configured to send daily reports to inform users
471 about the personal spam messages received the last day. That report is
472 only sent if there are new messages in the quarantine.
474 Some options are only available in the config file `/etc/pmg/pmg.conf`,
475 and not in the webinterface.
477 include::pmg.spamquar-conf-opts.adoc[]
481 Virus Detector Configuration
482 ----------------------------
484 [[pmgconfig_clamav_options]]
489 image::images/screenshot/pmg-gui-virus-options.png[]
492 All mails are automatically passed to the included virus detector
493 ({clamav}). The default setting are considered safe, so it is usually
494 not required to change them.
496 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
497 using the following configuration keys:
499 include::pmg.clamav-conf-opts.adoc[]
502 image::images/screenshot/pmg-gui-clamav-database.png[]
505 Please note that the virus signature database it automatically
506 updated. But you can see the database status on the GUI, and you can
507 trigger manual updates there.
510 [[pmgconfig_clamav_quarantine]]
515 image::images/screenshot/pmg-gui-virusquar-options.png[]
518 Indentified virus mails are automatically moved to the virus
519 quarantine. The administartor can view those mails using the GUI, or
520 deliver them in case of false positives. {pmg} does not notify
521 individual users about received virus mails.
523 Virus quarantine related settings are saved to subsection 'virusquar'
524 in `/etc/pmg/pmg.conf`, using the following configuration keys:
526 include::pmg.virusquar-conf-opts.adoc[]
529 Custom SpamAssassin configuration
530 ---------------------------------
532 This is only for advanced users. To add or change the Proxmox
533 {spamassassin} configuration please login to the console via SSH. Go
534 to directory `/etc/mail/spamassassin/`. In this directory there are several
535 files (`init.pre`, `local.cf`, ...) – do not change them.
537 To add your special configuration, you have to create a new file and
538 name it `custom.cf` (in this directory), then add your
539 configuration there. Be aware to use the {spamassassin}
540 syntax, and test with
543 # spamassassin -D --lint
546 If you run a cluster, the `custom.cf` file is synchronized from the
547 master node to all cluster members.
550 [[pmgconfig_custom_check]]
551 Custom Check Interface
552 ----------------------
554 For use cases which are not handled by the {pmg} Virus Detector and
555 {spamassassin} configuration, advanced users can create a custom check
556 executable which, if enabled will be called before the Virus Detector and before
557 passing an e-mail through the Rule System. The custom check API is kept as
558 simple as possible, while still providing a great deal of control over the
559 treatment of an e-mail. Its input is passed via two CLI arguments:
561 * the 'api-version' (currently `v1`) - for potential future change of the
564 * the 'queue-file-name' - a filename, which contains the complete e-mail as
567 The expected output need to be printed on STDOUT and consists of two lines:
569 * the 'api-version' (currently 'v1') - see above
571 * one of the following 3 results:
572 ** 'OK' - e-mail is ok
573 ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
574 (the virusdescription is logged and added to the e-mail's headers)
575 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
576 to the e-mail's spamscore
578 The check is run with a 5 minute timeout - if it is exceeded the check
579 executable is killed and the e-mail is treated as OK.
581 All output written to STDERR by the check is written with priority 'err' to the
584 A simple sample script following the API (and yielding a random result) for
590 echo "called with $*" 1>&2
592 if [ "$#" -ne 2 ]; then
593 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
600 if [ "$apiver" != "v1" ]; then
601 echo "wrong APIVERSION: $apiver" 1>&2
609 choice=$(shuf -i 0-3 -n1)
619 echo VIRUS: Random Virus
622 for i in $(seq 1 7); do
623 echo "custom checking mail: $queue_file - minute $i" 1>&2
632 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
639 The location of the custom check executable can also be set there with the key
640 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
646 User management in {pmg} consists of three types of users/accounts:
649 [[pmgconfig_localuser]]
653 image::images/screenshot/pmg-gui-local-user-config.png[]
655 Local users are used to manage and audit {pmg}. Those users can login on the
656 management web interface.
658 There are three roles:
662 Is allowed to manage settings of {pmg}, except some tasks like
663 network configuration and upgrading.
667 Is allowed to manage quarantines, blacklists and whitelists, but not other
668 settings. Has no right to view any other data.
672 With this role, the user is only allowed to view data and configuration, but
675 In addition there is always the 'root' user, which is used to perform special
676 system administrator tasks, such as updgrading a host or changing the
677 network configuration.
679 NOTE: Only pam users are able to login via the webconsole and ssh, which the
680 users created with the web interface are not. Those users are created for
681 {pmg} administration only.
683 Local user related settings are saved in `/etc/pmg/user.conf`.
685 For details of the fields see xref:pmg_user_configuration_file[user.conf]
688 LDAP/Active Directory
689 ~~~~~~~~~~~~~~~~~~~~~
691 image::images/screenshot/pmg-gui-ldap-user-config.png[]
693 You can specify multiple LDAP/Active Directory profiles, so that you can
694 create rules matching those users and groups.
696 Creating a profile requires (at least) the following:
699 * protocol (LDAP or LDAPS; LDAPS is recommended)
700 * at least one server
701 * a user and password (if your server does not support anonymous binds)
703 All other fields should work with the defaults for most setups, but can be
704 used to customize the queries.
706 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
707 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
712 It is highly recommended that the user which you use for connecting to the
713 LDAP server only has the permission to query the server. For LDAP servers
714 (for example OpenLDAP or FreeIPA), the username has to be of a format like
715 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
716 depending on your setup. For Active Directory servers, the format should be
717 like 'username@domain' or 'domain\username'.
722 {pmg} synchronizes the relevant user and group info periodically, so that
723 that information is available in a fast manner, even when the LDAP/AD server
724 is temporarily not accessible.
726 After a successfull sync, the groups and users should be visible on the web
727 interface. After that, you can create rules targeting LDAP users and groups.
730 [[pmgconfig_fetchmail]]
734 image::images/screenshot/pmg-gui-fetchmail-config.png[]
736 Fetchmail is utility for polling and forwarding e-mails. You can define
737 e-mail accounts, which will then be fetched and forwarded to the e-mail
740 You have to add an entry for each account/target combination you want to
741 fetch and forward. Those will then be regularly polled and forwarded,
742 according to your configuration.
744 The API and web interface offer following configuration options:
746 include::fetchmail.conf.5-opts.adoc[]
750 include::pmg-copyright.adoc[]