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, using 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, such as generating certificates and rewriting
35 service configuration files.
37 NOTE: We use a Postgres database to store mail filter rules and
38 statistical data. See chapter xref:chapter_pmgdb[Database Management]
42 Configuration files overview
43 ----------------------------
45 `/etc/network/interfaces`::
47 Network setup. We never modify this file directly. Instead, we write
48 changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames
49 the file to `/etc/network/interfaces`, thus applying the changes.
53 DNS search domain and nameserver setup. {pmg} uses the search domain setting
54 to create the FQDN and domain name used in the postfix configuration.
58 The system's hostname. {pmg} uses the hostname to create the FQDN used
59 in the postfix configuration.
63 Static table lookup for hostnames.
67 Stores common administration options, such as the spam and mail proxy
70 `/etc/pmg/cluster.conf`::
76 The list of relay domains.
78 `/etc/pmg/dkim/domains`::
80 The list of domains for outbound DKIM signing.
82 `/etc/pmg/fetchmailrc`::
84 Fetchmail configuration (POP3 and IMAP setup).
86 `/etc/pmg/ldap.conf`::
90 `/etc/pmg/mynetworks`::
92 List of local (trusted) networks.
94 `/etc/pmg/subscription`::
96 Stores your subscription key and status.
98 `/etc/pmg/tls_policy`::
100 TLS policy for outbound connections.
102 `/etc/pmg/transports`::
104 Message delivery transport setup.
106 `/etc/pmg/user.conf`::
108 GUI user configuration.
110 `/etc/mail/spamassassin/custom.cf`::
112 Custom {spamassassin} setup.
114 `/etc/mail/spamassassin/pmg-scores.cf`::
116 Custom {spamassassin} rule scores.
118 Keys and Certificates
119 ---------------------
121 `/etc/pmg/pmg-api.pem`::
123 Key and certificate (combined) used by the HTTPS server (API).
125 `/etc/pmg/pmg-authkey.key`::
127 Private key used to generate authentication tickets.
129 `/etc/pmg/pmg-authkey.pub`::
131 Public key used to verify authentication tickets.
133 `/etc/pmg/pmg-csrf.key`::
135 Internally used to generate CSRF tokens.
137 `/etc/pmg/pmg-tls.pem`::
139 Key and certificate (combined) to encrypt mail traffic (TLS).
141 `/etc/pmg/dkim/<selector>.private`::
143 Key for DKIM signing mails with selector '<selector>'.
146 [[pmgconfig_template_engine]]
147 Service Configuration Templates
148 -------------------------------
150 {pmg} uses various services to implement mail filtering, for example,
151 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
152 engine, and the Apache {spamassassin} project. These services use
153 separate configuration files, so we need to rewrite those files when the
154 configuration is changed.
156 We use a template-based approach to generate these files. The {tts} is
157 a well known, fast and flexible template processing system. You can
158 find the default templates in `/var/lib/pmg/templates/`. Please do not
159 modify these directly, otherwise your modifications will be lost on the
160 next update. Instead, copy the template you wish to change to
161 `/etc/pmg/templates/`, then apply your changes there.
163 Templates can access any configuration settings, and you can use the
164 `pmgconfig dump` command to get a list of all variable names:
169 dns.domain = yourdomain.tld
171 ipconfig.int_ip = 192.168.2.127
172 pmg.admin.advfilter = 1
176 The same tool is used to force the regeneration of all template-based
177 configuration files. You need to run the following after modifying a template,
178 or when you directly edit configuration files:
181 # pmgconfig sync --restart 1
184 The above command also restarts services if the underlying configuration
185 files are changed. Please note that this is automatically done when
186 you change the configuration using the GUI or API.
188 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
189 synced from the master node to all cluster members.
191 [[pmgconfig_whitelist_overview]]
192 White- and Blacklists
193 ---------------------
195 {pmg} has multiple white- and blacklists. It differentiates between the
196 xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist
197 and the user whitelist.
198 In addition to the whitelists, there are two separate blacklists: the rule-based
199 blacklist and the user blacklist.
204 The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling
205 greylisting, as well as SPF and DNSBL checks. These are done during the SMTP
208 Rule-based White-/Blacklist
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
211 The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined
212 rules. They work by checking the attached 'Who' objects, containing, for
213 example, a domain or a mail address for a match. If it matches, the assigned
214 action is used, which by default is 'Accept' for the whitelist rule and 'Block'
215 for the blacklist rule. In the default setup, the blacklist rule has priority
216 over the whitelist rule and spam checks.
218 User White-/Blacklist
219 ~~~~~~~~~~~~~~~~~~~~~
221 The user white- and blacklist are user specific. Every user can add mail addresses
222 to their white- and blacklist. When a user adds a mail address to the whitelist,
223 the result of the spam analysis will be discarded for that recipient. This can
224 help in the mail being accepted, but what happens next still depends on the
225 other rules. In the default setup, this results in the mail being accepted for
228 For mail addresses on a user's blacklist, the spam score will be increased by
229 100. What happens when a high spam score is encountered still depends on the
230 rule system. In the default setup, it will be recognized as spam and quarantined
231 (spam score of 3 or higher).
233 [[pmgconfig_systemconfig]]
241 [thumbnail="pmg-gui-network-config.png", big=1]
244 As network and time are configured in the installer, these generally do not
245 need to be configured again in the GUI.
247 The default setup uses a single Ethernet adapter and static IP
248 assignment. The configuration is stored at '/etc/network/interfaces',
249 and the actual network setup is done the standard Debian way, using the
252 .Example network setup '/etc/network/interfaces'
254 source /etc/network/interfaces.d/*
257 iface lo inet loopback
260 iface ens18 inet static
261 address 192.168.2.127
262 netmask 255.255.240.0
268 Many tests to detect SPAM mails use DNS queries, so it is important to
269 have a fast and reliable DNS server. We also query some publicly
270 available DNS Blacklists. Most of them apply rate limits for clients,
271 so they simply will not work if you use a public DNS server (because
272 they are usually blocked). We recommend to use your own DNS server,
273 which needs to be configured in 'recursive' mode.
280 [thumbnail="pmg-gui-system-options.png", big=1]
284 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
285 using the following configuration keys:
287 include::pmg.admin-conf-opts.adoc[]
290 include::pmg-ssl-certificate.adoc[]
292 Mail Proxy Configuration
293 ------------------------
295 [[pmgconfig_mailproxy_relaying]]
300 [thumbnail="pmg-gui-mailproxy-relaying.png", big=1]
303 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
304 using the following configuration keys:
306 include::pmg.mail-relaying-conf-opts.adoc[]
308 [[pmgconfig_mailproxy_relay_domains]]
313 [thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1]
316 A list of relayed mail domains, that is, what destination domains this
317 system will relay mail to. The system will reject incoming mails to
321 [[pmgconfig_mailproxy_ports]]
326 [thumbnail="pmg-gui-mailproxy-ports.png", big=1]
329 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
330 using the following configuration keys:
332 include::pmg.mail-ports-conf-opts.adoc[]
335 [[pmgconfig_mailproxy_options]]
340 [thumbnail="pmg-gui-mailproxy-options.png", big=1]
343 These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`,
344 using the following configuration keys:
346 include::pmg.mail-options-conf-opts.adoc[]
349 [[pmgconfig_mailproxy_before_after_queue]]
350 Before and After Queue scanning
351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353 Email scanning can happen at two different stages of mail-processing:
355 * Before-queue filtering: During the SMTP session, after the complete message
356 has been received (after the 'DATA' command).
358 * After-queue filtering: After initially accepting the mail and putting it on
359 a queue for further processing.
361 Before-queue filtering has the advantage that the system can reject a mail (by
362 sending a permanent reject code '554'), and leave the task of notifying the
363 original sender to the other mail server. This is of particular advantage if
364 the processed mail is a spam message or contains a virus and has a forged
365 sender address. Sending out a notification in this situation leads to so-called
366 'backscatter' mail, which might cause your server to get listed as spamming on
367 RBLs (Real-time Blackhole List).
369 After-queue filtering has the advantage of providing faster delivery of
370 mails for the sending servers, since queuing emails is much faster than
371 analyzing them for spam and viruses.
373 If a mail is addressed to multiple recipients (for example, when multiple
374 addresses are subscribed to the same mailing list), the situation is more
375 complicated; your mail server can only reject or accept the mail for all
376 recipients, after having received the complete message, while your rule setup
377 might accept the mail for part of the recipients and reject it for others. This
378 can be due to a complicated rule setup, or if your users use the 'User White-
379 and Blacklist' feature.
381 If the resulting action of the rule system is the same for all recipients, {pmg}
382 responds accordingly, if configured for before-queue filtering (sending '554'
383 for a blocked mail and '250' for an accepted or quarantined mail). If some
384 mailboxes accept the mail and some reject it, the system has to accept the mail.
386 Whether {pmg} notifies the sender that delivery failed for some recipients by
387 sending a non-delivery report, depends on the 'ndr_on_block' setting in
388 '/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents
389 NDRs being sent to the (possibly forged) sender and thus minimizes the chance
390 of getting your IP listed on an RBL. However in certain environments, it can be
391 unacceptable not to inform the sender about a rejected mail.
393 The setting has the same effect if after-queue filtering is configured, with
394 the exception that an NDR is always sent out, even if all recipients block the
395 mail, since the mail already got accepted before being analyzed.
397 The details of integrating the mail proxy with {postfix} in both setups are
398 explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
401 [[pmgconfig_mailproxy_greylisting]]
405 Greylisting is a technique for preventing unwanted messages from reaching the
406 resource intensive stages of content analysis (virus detection and spam
407 detection). By initially replying with a temporary failure code ('450') to
408 each new email, {pmg} tells the sending server that it should queue the
409 mail and retry delivery at a later point. Since certain kinds of spam get
410 sent out by software which has no provisioning for queuing, these mails are
411 dropped without reaching {pmg} or your mailbox.
413 The downside of greylisting is the delay introduced by the initial deferral of
414 the email, which usually amounts to less than 30 minutes.
416 In order to prevent unnecessary delays in delivery from known sources, emails
417 coming from a source for a recipient, which have passed greylisting in the
418 past are directly passed on: For each email the triple '<sender network,
419 sender email, recipient email>' is stored in a list, along with the time when
420 delivery was attempted. If an email fits an already existing triple, the
421 timestamp for that triple is updated, and the email is accepted for further
424 As long as a sender and recipient communicate frequently, there is no delay
425 introduced by enabling greylisting. A triple is removed after a longer period
426 of time, if no mail fitting that triple has been seen. The timeouts in {pmg}
429 * 2 days for the retry of the first delivery
431 * 36 days for a known triple
433 Mails with an empty envelope sender are always delayed.
435 Some email service providers send out emails for one domain from multiple
436 servers. To prevent delays due to an email coming in from two separate IPs of
437 the same provider, the triples store a network ('cidr') instead of a single IP.
438 For certain large providers, the default network size might be too small. You
439 can configure the netmask applied to an IP for the greylist lookup in
440 '/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4
441 and 'greylistmask6' for IPv6 respectively.
444 [[pmgconfig_mailproxy_transports]]
449 [thumbnail="pmg-gui-mailproxy-transports.png", big=1]
452 You can use {pmg} to send emails to different internal email servers. For
453 example, you can send emails addressed to domain.com to your first email server
454 and emails addressed to subdomain.domain.com to a second one.
456 You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
457 transport ports and mail domains (or just single email addresses) of your
458 additional email servers. When transport protocol is set to `lmtp`, the option
459 'Use MX' is useless and will automatically be set to 'No'.
462 [[pmgconfig_mailproxy_networks]]
467 [thumbnail="pmg-gui-mailproxy-networks.png", big=1]
470 You can add additional internal (trusted) IP networks or hosts. All hosts in
471 this list are allowed to relay.
473 NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to
474 be added to this list.
477 [[pmgconfig_mailproxy_tls]]
482 [thumbnail="pmg-gui-mailproxy-tls.png", big=1]
485 Transport Layer Security (TLS) provides certificate-based authentication and
486 encrypted sessions. An encrypted session protects the information that is
487 transmitted with SMTP mail. When you activate TLS, {pmg} automatically
488 generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`).
490 {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
491 encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
492 server. Otherwise, messages are sent unencrypted.
494 You can set a different TLS policy per destination. A destination is either a
495 remote domain or a next-hop destination, as specified in `/etc/pmg/transport`.
496 This can be used if you need to prevent email delivery without
497 encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
498 {postfix_tls_readme} for details on the supported policies.
502 To get additional information about SMTP TLS activity, you can enable
503 TLS logging. In this case, information about TLS sessions and used
504 certificates is logged via syslog.
506 Add TLS received header::
508 Set this option to include information about the protocol and cipher
509 used, as well as the client and issuer CommonName into the "Received:"
512 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
513 using the following configuration keys:
515 include::pmg.mail-tls-conf-opts.adoc[]
518 [[pmgconfig_mailproxy_dkim]]
523 [thumbnail="pmg-gui-mailproxy-dkim.png", big=1]
526 DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
527 cryptographically authenticate a mail as originating from a particular domain.
528 Before sending the mail, a hash over certain header fields and the body is
529 computed, signed with a private key and added in the `DKIM-Signature` header of
530 the mail. The 'selector' (a short identifier chosen by you, used to identify
531 which system and private key were used for signing) is also included in the
532 `DKIM-Signature` header.
534 The verification is done by the receiver. The public key is fetched
535 via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
536 for verifying the hash. You can publish multiple selectors for your domain,
537 each used by a system which sends email from your domain, without the need to
538 share the private key.
540 {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
542 Additionally, it supports conditionally signing outbound mail, if configured.
543 It uses one private key and selector per {pmg} deployment (all nodes in a
544 cluster use the same key). The key has a minimal size of 1024 bits and
545 rsa-sha256 is used as the signing algorithm.
547 The headers included in the signature are taken from the list of
548 `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
549 `CC`, `Reply-To` and `Subject` get oversigned.
551 You can either sign all mails received on the internal port using the domain of
552 the envelope sender address or create a list of domains, for which emails
553 should be signed, defaulting to the list of relay domains.
556 Enable DKIM Signing::
558 Controls whether outbound mail should get DKIM signed.
562 The selector used for signing the mail. The private key used for signing is
563 saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
564 record which you need to add to all domains signed by {pmg} by clicking on the
565 'View DNS Record' Button.
567 Sign all Outgoing Mail::
569 Controls whether all outbound mail should get signed or only mails from domains
570 listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains`
573 These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`,
574 using the following configuration keys:
576 include::pmg.admin-dkim-conf-opts.adoc[]
583 [thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
586 All SMTP checks are disabled for those entries (e.g. Greylisting,
589 DNSBL checks are done by `postscreen`, which works on IP addresses and networks.
590 This means it can only make use of the `IP Address` and `IP Network` entries.
592 NOTE: If you use a backup MX server (for example, your ISP offers this service
593 for you) you should always add those servers here.
595 NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in
596 xref:pmgconfig_mailproxy_options[Mail Proxy Options].
598 [[pmgconfig_spamdetector]]
599 Spam Detector Configuration
600 ---------------------------
606 [thumbnail="pmg-gui-spam-options.png", big=1]
609 {pmg} uses a wide variety of local and network tests to identify spam
610 signatures. This makes it harder for spammers to identify one aspect
611 which they can craft their messages to work around the spam filter.
613 Every single email will be analyzed and have a spam score
614 assigned. The system attempts to optimize the efficiency of the rules
615 that are run in terms of minimizing the number of false positives and
618 include::pmg.spam-conf-opts.adoc[]
621 [[pmgconfig_spamdetector_quarantine]]
626 [thumbnail="pmg-gui-spamquar-options.png", big=1]
629 {pmg} analyses all incoming email messages and decides for each
630 email if it is ham or spam (or virus). Good emails are delivered to
631 the inbox and spam messages are moved into the spam quarantine.
633 The system can be configured to send daily reports to inform users
634 about personal spam messages received in the last day. The report is
635 only sent if there are new messages in the quarantine.
637 Some options are only available in the config file `/etc/pmg/pmg.conf`,
638 and not in the web interface.
640 include::pmg.spamquar-conf-opts.adoc[]
643 [[pmgconfig_spamdetector_customscores]]
644 Customization of Rulescores
645 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
648 [thumbnail="pmg-gui-spam-custom-scores.png", big=1]
651 While the default scoring of {spamassassin}'s ruleset provides very good
652 detection rates, sometimes your particular environment can benefit from
653 slightly adjusting the score of a particular rule. Two examples:
655 * Your system receives spam mails which are scored at 4.9 and you have
656 a rule which puts all mails above 5 in the quarantine. The one thing the
657 spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing
658 the score of this rule by 0.2 points the spam mails would all be quarantined
659 instead of being sent to your users
661 * Your system tags many legitimate mails from a partner organization as spam,
662 because the organization has a policy that each mail has to start with
663 'Dear madam or sir' (generating 1.9 points through the rule
664 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable
667 The system logs all the rules which a particular mail hits. Analyzing the logs can
668 lead to finding such a pattern in your environment.
670 You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
673 NOTE: In general, it is strongly recommended not to make large changes to the
678 Virus Detector Configuration
679 ----------------------------
681 [[pmgconfig_clamav_options]]
686 [thumbnail="pmg-gui-virus-options.png", big=1]
689 All mails are automatically passed to the included virus detector
690 ({clamav}). The default settings are considered safe, so it is usually
691 not required to change them.
693 {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
694 using the following configuration keys:
696 include::pmg.clamav-conf-opts.adoc[]
699 [thumbnail="pmg-gui-clamav-database.png", big=1]
702 Please note that the virus signature database is automatically
703 updated. You can see the database status in the GUI, and also
704 trigger manual updates from there.
707 [[pmgconfig_clamav_quarantine]]
712 [thumbnail="pmg-gui-virusquar-options.png", big=1]
715 Identified virus mails are automatically moved to the virus
716 quarantine. The administrator can view these mails from the GUI, and
717 choose to deliver them, in case of false positives. {pmg} does not notify
718 individual users about received virus mails.
720 Virus quarantine related settings are saved to subsection 'virusquar'
721 in `/etc/pmg/pmg.conf`, using the following configuration keys:
723 include::pmg.virusquar-conf-opts.adoc[]
726 Custom SpamAssassin configuration
727 ---------------------------------
729 This is only for advanced users. {spamassassin}'s rules and their associated
730 scores get updated regularly and are trained on a huge corpus, which gets
731 classified by experts. In most cases, adding a rule for matching a particular
732 keyword is the wrong approach, leading to many false positives. Usually bad
733 detection rates are better addressed by properly setting up DNS than by adding
734 a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
735 spam-headers - see the {spamassassin_dnsbl}.
737 To add or change the Proxmox {spamassassin} configuration, log in to the
738 console via SSH and change to the `/etc/mail/spamassassin/` directory. In this
739 directory there are several files (`init.pre`, `local.cf`, ...) - do not change
740 them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
741 the xref:pmgconfig_template_engine[template engine], while the others can
742 get updated by any {spamassassin} package upgrade.
744 To add your custom configuration, you have to create a new file and name it
745 `custom.cf` (in this directory), then add your configuration there. Make sure
746 to use the correct {spamassassin} syntax, and test it with:
749 # spamassassin -D --lint
752 If you run a cluster, the `custom.cf` file is synchronized from the
753 master node to all cluster members automatically.
755 To adjust the score assigned to a particular rule, you
756 can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
760 [[pmgconfig_custom_check]]
761 Custom Check Interface
762 ----------------------
764 For use-cases which are not handled by the {pmg} Virus Detector and
765 {spamassassin} configuration, advanced users can create a custom check
766 executable which, if enabled will be called before the Virus Detector and before
767 passing an email through the Rule System. The custom check API is kept as
768 simple as possible, while still providing a great deal of control over the
769 treatment of an email. Its input is passed via two CLI arguments:
771 * the 'api-version' (currently `v1`) - for potential future change of the
774 * the 'queue-file-name' - a filename, which contains the complete email as
777 The expected output needs to be printed to STDOUT and consists of two lines:
779 * the 'api-version' (currently 'v1') - see above
781 * one of the following 3 results:
782 ** 'OK' - email is OK
783 ** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus
784 (the virus description is logged and added to the email's headers)
785 ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
786 to the email's spamscore
788 The check is run with a 5 minute timeout - if this is exceeded, the check
789 executable is killed and the email is treated as OK.
791 All output written to STDERR by the check is written with priority 'err' to the
794 Below is a simple sample script following the API (and yielding a random result)
800 echo "called with $*" 1>&2
802 if [ "$#" -ne 2 ]; then
803 echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
810 if [ "$apiver" != "v1" ]; then
811 echo "wrong APIVERSION: $apiver" 1>&2
819 choice=$(shuf -i 0-3 -n1)
829 echo VIRUS: Random Virus
832 for i in $(seq 1 7); do
833 echo "custom checking mail: $queue_file - minute $i" 1>&2
842 The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
849 The location of the custom check executable can also be set there with the key
850 `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
856 User management in {pmg} consists of three types of users/accounts:
859 [[pmgconfig_localuser]]
863 [thumbnail="pmg-gui-local-user-config.png", big=1]
865 Local users can manage and audit {pmg}. They can login on the management web
868 There are four roles:
872 Is allowed to manage settings of {pmg}, excluding some tasks like network
873 configuration and upgrading.
877 Is allowed to manage quarantines, blacklists and whitelists, but not other
878 settings. Has no right to view any other data.
882 With this role, the user is only allowed to view data and configuration, but
887 Combines permissions of the 'Auditor' and the 'Quarantine Manager' role.
889 In addition, there is always the 'root' user, which is used to perform special
890 system administrator tasks, such as upgrading a host or changing the network
893 NOTE: Only PAM users are able to log in via the web interface and ssh, while the
894 users created through the web interface are not. Those users are created for
895 {pmg} administration only.
897 Local user related settings are saved in `/etc/pmg/user.conf`.
899 For details on the fields, see xref:pmg_user_configuration_file[user.conf]
902 LDAP/Active Directory
903 ~~~~~~~~~~~~~~~~~~~~~
905 [thumbnail="pmg-gui-ldap-user-config.png", big=1]
907 You can specify multiple LDAP/Active Directory profiles, so that you can
908 create rules matching those users and groups.
910 Creating a profile requires (at least) the following:
913 * protocol (LDAP or LDAPS; LDAPS is recommended)
914 * at least one server
915 * a username and password (if your server does not support anonymous binds)
917 All other fields should work with the defaults for most setups, but can be
918 used to customize the queries.
920 The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
921 can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
926 It is highly recommended that the user which you use for connecting to the
927 LDAP server only has permission to query the server. For LDAP servers
928 (for example OpenLDAP or FreeIPA), the username has to be of a format like
929 'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields
930 depend on your setup. For Active Directory servers, the format should be
931 like 'username@domain' or 'domain\username'.
936 {pmg} synchronizes the relevant user and group information periodically, so that
937 the information is quickly available, even when the LDAP/AD server is
938 temporarily inaccessible.
940 After a successful sync, the groups and users should be visible on the web
941 interface. Following this, you can create rules targeting LDAP users and groups.
944 [[pmgconfig_fetchmail]]
948 [thumbnail="pmg-gui-fetchmail-config.png", big=1]
950 Fetchmail is a utility for polling and forwarding emails. You can define
951 email accounts, which will then be fetched and forwarded to the email
954 You have to add an entry for each account/target combination you want to
955 fetch and forward. These will then be regularly polled and forwarded,
956 according to your configuration.
958 The API and web interface offer the following configuration options:
960 include::fetchmail.conf.5-opts.adoc[]
964 include::pmg-copyright.adoc[]