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/transports`::
94 Message delivery transport setup.
96 `/etc/pmg/user.conf`::
98 GUI user configuration.
100 `/etc/mail/spamassassin/custom.cf`::
102 Custom {spamassassin} setup.
105 Keys and Certificates
106 ---------------------
108 `/etc/pmg/pmg-api.pem`::
110 Key and certificate (combined) used be the HTTPs server (API).
112 `/etc/pmg/pmg-authkey.key`::
114 Privat key use to generate authentication tickets.
116 `/etc/pmg/pmg-authkey.pub`::
118 Public key use to verify authentication tickets.
120 `/etc/pmg/pmg-csrf.key`::
122 Internally used to generate CSRF tokens.
124 `/etc/pmg/pmg-tls.pem`::
126 Key and certificate (combined) to encrypt mail traffic (TLS).
129 Service Configuration Templates
130 -------------------------------
132 {pmg} uses various services to implement mail filtering, for example
133 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
134 engine and the Apache {spamassassin} project. Those services use
135 separate configuration files, so we need to rewrite those files when
136 configuration is changed.
138 We use a template based approach to generate those files. The {tts} is
139 a well known, fast and flexible template processing system. You can
140 find the default templates in `/var/lib/pmg/templates/`. Please do not
141 modify them directly, because your modification would get lost on the
142 next update. Instead, copy them to `/etc/pmg/templates/`, then apply
145 Templates can access any configuration setting, and you can use the
146 `pmgconfig dump` command to get a list of all variable names:
151 dns.domain = yourdomain.tld
153 ipconfig.int_ip = 192.168.2.127
154 pmg.admin.advfilter = 1
158 The same tool is used to force regeneration of all template based
159 configuration files. You need to run that after modifying a template,
160 or when you directly edit configuration files
163 # pmgconfig sync --restart 1
166 Above commands also restarts services if underlying configuration
167 files are changed. Please note that this is automatically done when
168 you change the configuration using the GUI or API.
170 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
171 synced from the master node to all cluster members.
181 image::images/screenshot/pmg-gui-network-config.png[]
184 Normally the network and time is already configured when you visit the
185 GUI. The installer asks for those setting and sets up the correct
188 The default setup uses a single Ethernet adapter and static IP
189 assignment. The configuration is stored at '/etc/network/interfaces',
190 and the actual network setup is done the standard Debian way using
193 .Example network setup '/etc/network/interfaces'
195 source /etc/network/interfaces.d/*
198 iface lo inet loopback
201 iface ens18 inet static
202 address 192.168.2.127
203 netmask 255.255.240.0
209 Many tests to detect SPAM mails use DNS queries, so it is important to
210 have a fast and reliable DNS server. We also query some public
211 available DNS Blacklists. Most of them apply rate limits for clients,
212 so they simply will not work if you use a public DNS server (because
213 they are usually blocked). We recommend to use your own DNS server,
214 which need to be configured in 'recursive' mode.
221 image::images/screenshot/pmg-gui-system-options.png[]
225 Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
226 using the following configuration keys:
228 include::pmg.admin-conf-opts.adoc[]
231 Mail Proxy Configuration
232 ------------------------
238 image::images/screenshot/pmg-gui-mailproxy-relaying.png[]
241 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
242 using the following configuration keys:
244 include::pmg.mail-relaying-conf-opts.adoc[]
250 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
253 List of relayed mail domains, i.e. what destination domains this
254 system will relay mail to. The system will reject incoming mails to
262 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
265 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
266 using the following configuration keys:
268 include::pmg.mail-ports-conf-opts.adoc[]
275 image::images/screenshot/pmg-gui-mailproxy-options.png[]
278 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
279 using the following configuration keys:
281 include::pmg.mail-options-conf-opts.adoc[]
288 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
291 You can use {pmg} to send e-mails to different internal
292 e-mail servers. For example you can send e-mails addressed to
293 domain.com to your first e-mail server, and e-mails addressed to
294 subdomain.domain.com to a second one.
296 You can add the IP addresses, hostname and SMTP ports and mail domains (or
297 just single email addresses) of your additional e-mail servers.
304 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
307 You can add additional internal (trusted) IP networks or hosts.
308 All hosts in this list are allowed to relay.
310 NOTE: Hosts in the same subnet with Proxmox can relay by default and
311 it’s not needed to add them in this list.
318 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
321 Transport Layer Security (TLS) provides certificate-based
322 authentication and encrypted sessions. An encrypted session protects
323 the information that is transmitted with SMTP mail. When you activate
324 TLS, {pmg} automatically generates a new self signed
325 certificate for you (`/etc/pmg/pmg-tls.pem`).
327 {pmg} uses opportunistic TLS encryption. The SMTP transaction is
328 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
329 server. Otherwise, messages are sent in the clear.
333 To get additional information about SMTP TLS activity you can enable
334 TLS logging. That way information about TLS sessions and used
335 certificate’s is logged via syslog.
337 Add TLS received header::
339 Set this option to include information about the protocol and cipher
340 used as well as the client and issuer CommonName into the "Received:"
343 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
344 using the following configuration keys:
346 include::pmg.mail-tls-conf-opts.adoc[]
353 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
356 All SMTP checks are disabled for those entries (e. g. Greylisting,
359 NOTE: If you use a backup MX server (e.g. your ISP offers this service
360 for you) you should always add those servers here.
363 Spam Detector Configuration
364 ---------------------------
370 image::images/screenshot/pmg-gui-spam-options.png[]
373 {pmg} uses a wide variety of local and network tests to identify spam
374 signatures. This makes it harder for spammers to identify one aspect
375 which they can craft their messages to work around the spam filter.
377 Every single e-mail will be analyzed and gets a spam score
378 assigned. The system attempts to optimize the efficiency of the rules
379 that are run in terms of minimizing the number of false positives and
382 include::pmg.spam-conf-opts.adoc[]
389 image::images/screenshot/pmg-gui-spamquar-options.png[]
392 Proxmox analyses all incoming e-mail messages and decides for each
393 e-mail if its ham or spam (or virus). Good e-mails are delivered to
394 the inbox and spam messages can be moved into the spam quarantine.
396 The system can be configured to send daily reports to inform users
397 about the personal spam messages received the last day. That report is
398 only sent if there are new messages in the quarantine.
400 Some options are only available in the config file `/etc/pmg/pmg.conf`,
401 and not in the webinterface.
403 include::pmg.spamquar-conf-opts.adoc[]
406 Virus Detector Configuration
407 ----------------------------
413 image::images/screenshot/pmg-gui-virus-options.png[]
416 All mails are automatically passed to the included virus detector
417 ({clamav}). The default setting are considered safe, so it is usually
418 not required to change them.
420 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
421 using the following configuration keys:
423 include::pmg.clamav-conf-opts.adoc[]
426 image::images/screenshot/pmg-gui-clamav-database.png[]
429 Please note that the virus signature database it automatically
430 updated. But you can see the database status on the GUI, and you can
431 trigger manual updates there.
438 image::images/screenshot/pmg-gui-virusquar-options.png[]
441 Indentified virus mails are automatically moved to the virus
442 quarantine. The administartor can view those mails using the GUI, or
443 deliver them in case of false positives. {pmg} does not notify
444 individual users about received virus mails.
446 Virus quarantine related settings are saved to subsection 'virusquar'
447 in `/etc/pmg/pmg.conf`, using the following configuration keys:
449 include::pmg.virusquar-conf-opts.adoc[]
452 Custom SpamAssassin configuration
453 ---------------------------------
455 This is only for advanced users. To add or change the Proxmox
456 {spamassassin} configuration please login to the console via SSH. Go
457 to directory `/etc/mail/spamassasin/`. In this directory there are several
458 files (`init.pre`, `local.cf`, ...) – do not change them.
460 To add your special configuration, you have to create a new file and
461 name it `custom.cf` (in this directory), then add your
462 configuration there. Be aware to use the {spamassassin}
463 syntax, and test with
466 # spamassassin -D --lint
469 If you run a cluster, the `custom.cf` file is synchronized from the
470 master node to all cluster members.
476 User management in {pmg} consists of three types of users/accounts:
482 image::images/screenshot/pmg-gui-local-user-config.png[]
484 Local users are used to manage and audit {pmg}. Those users can login on the
485 management web interface.
487 There are three roles:
491 Is allowed to manage settings of {pmg}, except some tasks like
492 network configuration and upgrading.
496 Is allowed to manage quarantines, blacklists and whitelists, but not other
497 settings. Has no right to view any other data.
501 With this role, the user is only allowed to view data and configuration, but
504 In addition there is always the 'root' user, which is used to perform special
505 system administrator tasks, such as updgrading a host or changing the
506 network configuration.
508 NOTE: Only pam users are able to login via the webconsole and ssh, which the
509 users created with the web interface are not. Those users are created for
510 {pmg} administration only.
512 Local user related settings are saved in `/etc/pmg/user.conf`.
514 For details of the fields see xref:pmg_user_configuration_file[user.conf]
516 LDAP/Active Directory
517 ~~~~~~~~~~~~~~~~~~~~~
519 image::images/screenshot/pmg-gui-ldap-user-config.png[]
521 You can specify multiple LDAP/Active Directory profiles, so that you can
522 create rules matching those users and groups.
524 Creating a profile requires (at least) the following:
527 * protocol (LDAP or LDAPS; LDAPS is recommended)
528 * at least one server
529 * a user and password (if your server does not support anonymous binds)
531 All other fields should work with the defaults for most setups, but can be
532 used to customize the queries.
534 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
535 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
540 It is highly recommended that the user which you use for connecting to the
541 LDAP server only has the permission to query the server. For LDAP servers
542 (for example OpenLDAP or FreeIPA), the username has to be of a format like
543 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
544 depending on your setup. For Active Directory servers, the format should be
545 like 'username@domain' or 'domain\username'.
550 {pmg} synchronizes the relevant user and group info periodically, so that
551 that information is available in a fast manner, even when the LDAP/AD server
552 is temporarily not accessible.
554 After a successfull sync, the groups and users should be visible on the web
555 interface. After that, you can create rules targeting LDAP users and groups.
561 image::images/screenshot/pmg-gui-fetchmail-config.png[]
563 Fetchmail is utility for polling and forwarding e-mails. You can define
564 e-mail accounts, which will then be fetched and forwarded to the e-mail
567 You have to add an entry for each account/target combination you want to
568 fetch and forward. Those will then be regularly polled and forwarded,
569 according to your configuration.
571 The API and web interface offer following configuration options:
573 include::fetchmail.conf.5-opts.adoc[]
577 include::pmg-copyright.adoc[]