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 them to `/etc/pmg/templates/`, then apply
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 Above commands also restarts services if 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.
185 image::images/screenshot/pmg-gui-network-config.png[]
188 Normally the network and time is already configured when you visit the
189 GUI. The installer asks for those setting and sets up the correct
192 The default setup uses a single Ethernet adapter and static IP
193 assignment. The configuration is stored at '/etc/network/interfaces',
194 and the actual network setup is done the standard Debian way using
197 .Example network setup '/etc/network/interfaces'
199 source /etc/network/interfaces.d/*
202 iface lo inet loopback
205 iface ens18 inet static
206 address 192.168.2.127
207 netmask 255.255.240.0
213 Many tests to detect SPAM mails use DNS queries, so it is important to
214 have a fast and reliable DNS server. We also query some public
215 available DNS Blacklists. Most of them apply rate limits for clients,
216 so they simply will not work if you use a public DNS server (because
217 they are usually blocked). We recommend to use your own DNS server,
218 which need to be configured in 'recursive' mode.
225 image::images/screenshot/pmg-gui-system-options.png[]
229 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
230 using the following configuration keys:
232 include::pmg.admin-conf-opts.adoc[]
235 Mail Proxy Configuration
236 ------------------------
242 image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
245 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
246 using the following configuration keys:
248 include::pmg.mail-relaying-conf-opts.adoc[]
254 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
257 List of relayed mail domains, i.e. what destination domains this
258 system will relay mail to. The system will reject incoming mails to
266 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
269 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
270 using the following configuration keys:
272 include::pmg.mail-ports-conf-opts.adoc[]
279 image::images/screenshot/pmg-gui-mailproxy-options.png[]
282 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
283 using the following configuration keys:
285 include::pmg.mail-options-conf-opts.adoc[]
292 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
295 You can use {pmg} to send e-mails to different internal
296 e-mail servers. For example you can send e-mails addressed to
297 domain.com to your first e-mail server, and e-mails addressed to
298 subdomain.domain.com to a second one.
300 You can add the IP addresses, hostname and SMTP ports and mail domains (or
301 just single email addresses) of your additional e-mail servers.
308 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
311 You can add additional internal (trusted) IP networks or hosts.
312 All hosts in this list are allowed to relay.
314 NOTE: Hosts in the same subnet with Proxmox can relay by default and
315 it’s not needed to add them in this list.
322 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
325 Transport Layer Security (TLS) provides certificate-based
326 authentication and encrypted sessions. An encrypted session protects
327 the information that is transmitted with SMTP mail. When you activate
328 TLS, {pmg} automatically generates a new self signed
329 certificate for you (`/etc/pmg/pmg-tls.pem`).
331 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
332 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
333 server. Otherwise, messages are sent in the clear.
334 You can set a different TLS policy per desitination domain, should you for
335 example need to prevent e-mail delivery without encryption, or to work around
336 a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
337 on the supported policies.
341 To get additional information about SMTP TLS activity you can enable
342 TLS logging. That way information about TLS sessions and used
343 certificate’s is logged via syslog.
345 Add TLS received header::
347 Set this option to include information about the protocol and cipher
348 used as well as the client and issuer CommonName into the "Received:"
351 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
352 using the following configuration keys:
354 include::pmg.mail-tls-conf-opts.adoc[]
361 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
364 All SMTP checks are disabled for those entries (e. g. Greylisting,
367 NOTE: If you use a backup MX server (e.g. your ISP offers this service
368 for you) you should always add those servers here.
371 Spam Detector Configuration
372 ---------------------------
378 image::images/screenshot/pmg-gui-spam-options.png[]
381 {pmg} uses a wide variety of local and network tests to identify spam
382 signatures. This makes it harder for spammers to identify one aspect
383 which they can craft their messages to work around the spam filter.
385 Every single e-mail will be analyzed and gets a spam score
386 assigned. The system attempts to optimize the efficiency of the rules
387 that are run in terms of minimizing the number of false positives and
390 include::pmg.spam-conf-opts.adoc[]
397 image::images/screenshot/pmg-gui-spamquar-options.png[]
400 Proxmox analyses all incoming e-mail messages and decides for each
401 e-mail if its ham or spam (or virus). Good e-mails are delivered to
402 the inbox and spam messages can be moved into the spam quarantine.
404 The system can be configured to send daily reports to inform users
405 about the personal spam messages received the last day. That report is
406 only sent if there are new messages in the quarantine.
408 Some options are only available in the config file `/etc/pmg/pmg.conf`,
409 and not in the webinterface.
411 include::pmg.spamquar-conf-opts.adoc[]
414 Virus Detector Configuration
415 ----------------------------
421 image::images/screenshot/pmg-gui-virus-options.png[]
424 All mails are automatically passed to the included virus detector
425 ({clamav}). The default setting are considered safe, so it is usually
426 not required to change them.
428 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
429 using the following configuration keys:
431 include::pmg.clamav-conf-opts.adoc[]
434 image::images/screenshot/pmg-gui-clamav-database.png[]
437 Please note that the virus signature database it automatically
438 updated. But you can see the database status on the GUI, and you can
439 trigger manual updates there.
446 image::images/screenshot/pmg-gui-virusquar-options.png[]
449 Indentified virus mails are automatically moved to the virus
450 quarantine. The administartor can view those mails using the GUI, or
451 deliver them in case of false positives. {pmg} does not notify
452 individual users about received virus mails.
454 Virus quarantine related settings are saved to subsection 'virusquar'
455 in `/etc/pmg/pmg.conf`, using the following configuration keys:
457 include::pmg.virusquar-conf-opts.adoc[]
460 Custom SpamAssassin configuration
461 ---------------------------------
463 This is only for advanced users. To add or change the Proxmox
464 {spamassassin} configuration please login to the console via SSH. Go
465 to directory `/etc/mail/spamassasin/`. In this directory there are several
466 files (`init.pre`, `local.cf`, ...) – do not change them.
468 To add your special configuration, you have to create a new file and
469 name it `custom.cf` (in this directory), then add your
470 configuration there. Be aware to use the {spamassassin}
471 syntax, and test with
474 # spamassassin -D --lint
477 If you run a cluster, the `custom.cf` file is synchronized from the
478 master node to all cluster members.
484 User management in {pmg} consists of three types of users/accounts:
490 image::images/screenshot/pmg-gui-local-user-config.png[]
492 Local users are used to manage and audit {pmg}. Those users can login on the
493 management web interface.
495 There are three roles:
499 Is allowed to manage settings of {pmg}, except some tasks like
500 network configuration and upgrading.
504 Is allowed to manage quarantines, blacklists and whitelists, but not other
505 settings. Has no right to view any other data.
509 With this role, the user is only allowed to view data and configuration, but
512 In addition there is always the 'root' user, which is used to perform special
513 system administrator tasks, such as updgrading a host or changing the
514 network configuration.
516 NOTE: Only pam users are able to login via the webconsole and ssh, which the
517 users created with the web interface are not. Those users are created for
518 {pmg} administration only.
520 Local user related settings are saved in `/etc/pmg/user.conf`.
522 For details of the fields see xref:pmg_user_configuration_file[user.conf]
524 LDAP/Active Directory
525 ~~~~~~~~~~~~~~~~~~~~~
527 image::images/screenshot/pmg-gui-ldap-user-config.png[]
529 You can specify multiple LDAP/Active Directory profiles, so that you can
530 create rules matching those users and groups.
532 Creating a profile requires (at least) the following:
535 * protocol (LDAP or LDAPS; LDAPS is recommended)
536 * at least one server
537 * a user and password (if your server does not support anonymous binds)
539 All other fields should work with the defaults for most setups, but can be
540 used to customize the queries.
542 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
543 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
548 It is highly recommended that the user which you use for connecting to the
549 LDAP server only has the permission to query the server. For LDAP servers
550 (for example OpenLDAP or FreeIPA), the username has to be of a format like
551 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
552 depending on your setup. For Active Directory servers, the format should be
553 like 'username@domain' or 'domain\username'.
558 {pmg} synchronizes the relevant user and group info periodically, so that
559 that information is available in a fast manner, even when the LDAP/AD server
560 is temporarily not accessible.
562 After a successfull sync, the groups and users should be visible on the web
563 interface. After that, you can create rules targeting LDAP users and groups.
569 image::images/screenshot/pmg-gui-fetchmail-config.png[]
571 Fetchmail is utility for polling and forwarding e-mails. You can define
572 e-mail accounts, which will then be fetched and forwarded to the e-mail
575 You have to add an entry for each account/target combination you want to
576 fetch and forward. Those will then be regularly polled and forwarded,
577 according to your configuration.
579 The API and web interface offer following configuration options:
581 include::fetchmail.conf.5-opts.adoc[]
585 include::pmg-copyright.adoc[]