The list of relay domains.
+`/etc/pmg/dkim/domains`::
+
+The list of domains for outbound DKIM signing.
+
`/etc/pmg/fetchmailrc`::
Fetchmail configuration (POP3 and IMAP setup).
Stores your subscription key and status.
+`/etc/pmg/tls_policy`::
+
+TLS policy for outbound connections.
+
`/etc/pmg/transports`::
Message delivery transport setup.
Custom {spamassassin} setup.
+`/etc/mail/spamassassin/pmg-scores.cf`::
+
+Custom {spamassassin} rule scores.
Keys and Certificates
---------------------
Key and certificate (combined) to encrypt mail traffic (TLS).
+`/etc/pmg/dkim/<selector>.private`::
+
+Key for DKIM signing mails with selector '<selector>'.
+
+[[pmgconfig_template_engine]]
Service Configuration Templates
-------------------------------
a well known, fast and flexible template processing system. You can
find the default templates in `/var/lib/pmg/templates/`. Please do not
modify them directly, because your modification would get lost on the
-next update. Instead, copy them to `/etc/pmg/templates/`, then apply
-your changes there.
+next update. Instead, copy the template you wish to change to
+`/etc/pmg/templates/`, then apply your changes there.
Templates can access any configuration setting, and you can use the
`pmgconfig dump` command to get a list of all variable names:
# pmgconfig sync --restart 1
----
-Above commands also restarts services if underlying configuration
+The above command also restarts services if the underlying configuration
files are changed. Please note that this is automatically done when
you change the configuration using the GUI or API.
synced from the master node to all cluster members.
+[[pmgconfig_systemconfig]]
System Configuration
--------------------
endif::manvolnum[]
Normally the network and time is already configured when you visit the
-GUI. The installer asks for those setting and sets up the correct
+GUI. The installer asks for those settings and sets up the correct
values.
The default setup uses a single Ethernet adapter and static IP
Mail Proxy Configuration
------------------------
+[[pmgconfig_mailproxy_relaying]]
Relaying
~~~~~~~~
include::pmg.mail-relaying-conf-opts.adoc[]
+[[pmgconfig_mailproxy_relay_domains]]
Relay Domains
~~~~~~~~~~~~~
other domains.
+[[pmgconfig_mailproxy_ports]]
Ports
~~~~~
include::pmg.mail-ports-conf-opts.adoc[]
+[[pmgconfig_mailproxy_options]]
Options
~~~~~~~
include::pmg.mail-options-conf-opts.adoc[]
+[[pmgconfig_mailproxy_before_after_queue]]
+Before and After Queue scanning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Scanning email can happen at two different stages of mail-processing:
+
+* During the SMTP Session after the complete message has been received (after
+ the 'DATA' command), known as 'before queue filtering'.
+
+* After intially accepting the mail and putting it on a queue for further
+ processing, known as 'after queue filtering'.
+
+The former has the advantage that the system can reject a mail (by sending a
+permanent reject code '554'), and leave the task of notifying the original
+sender to the other mailserver. This is of particular advantage if the
+processed mail is a spam message or contains a virus and has a forged
+sender-address. Sending out a notification in this situation leads so-called
+'backscatter' mail, which might cause your server to get listed as spamming on
+RBLs.
+
+The latter has the advantage of providing faster delivery of mails for the
+sending servers, since queueing mails is much faster than analyzing it for
+spam and viruses.
+
+If a mail is addressed to multiple recipients (e.g. when multiple addresses are
+subscribed to the same mailinglist) the situation is more complicated: Your
+mailserver can only reject or accept the mail for all recipients, after having
+received the complete message, while your rule setup might accept the mail for
+part of the recipients and reject it for others. This can be due to a
+complicated rule setup, or if your users use the 'User White- and Blacklist'
+feature.
+
+If the resulting action of the rule system is the same for all recipients {pmg}
+responds accordingly if configured for before queue filtering (sending '554'
+for a blocked mail and '250' for an accepted or quarantined mail). If some
+mailboxes accept the mail and some reject it the system has to accept the mail.
+
+Whether {pmg} notifies the sender that delivery failed for some recipients by
+sending a non-delivery report, depends on the 'ndr_on_block' setting in
+'/etc/pmg/pmg.conf'. If enabled an NDR is sent. Keeping it disabled prevents
+NDRs being sent to the (possibly forged) sender and thus minimizes the chance
+of getting your IP listed on a RBL. However in certain environments it can be
+unacceptable not to inform the sender about a rejected mail.
+
+The setting has the same effect if after queue filtering is configured, with
+the exception that an NDR is always sent out, even if all recipients block the
+mail, since the mail already got accepted before being analyzed.
+
+The details of integrating the mail proxy with {postfix} in both setups are
+explained in {postfix_beforequeue} and {postfix_afterqueue} respectively.
+
+NOTE: Since before queue filtering is currently incompatible with the
+'Tracking Center' you need to enable it by manually
+editing '/etc/pmg/pmg.conf'.
+
+
+[[pmgconfig_mailproxy_transports]]
Transports
~~~~~~~~~~
just single email addresses) of your additional e-mail servers.
+[[pmgconfig_mailproxy_networks]]
Networks
~~~~~~~~
it’s not needed to add them in this list.
+[[pmgconfig_mailproxy_tls]]
TLS
~~~
TLS, {pmg} automatically generates a new self signed
certificate for you (`/etc/pmg/pmg-tls.pem`).
-{pmg} uses opportunistic TLS encryption. The SMTP transaction is
+{pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
-server. Otherwise, messages are sent in the clear.
+server. Otherwise, messages are sent in the clear.
+You can set a different TLS policy per desitination domain, should you for
+example need to prevent e-mail delivery without encryption, or to work around
+a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details
+on the supported policies.
Enable TLS logging::
include::pmg.mail-tls-conf-opts.adoc[]
+[[pmgconfig_mailproxy_dkim]]
+DKIM Signing
+~~~~~~~~~~~~
+
+DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to
+cryptographically authenticate a mail as originating from a particular domain.
+Before sending the mail a hash over certain header fields and the body is
+computed, signed with a private key and added in the `DKIM-Signature` header of
+the mail. The 'selector' (a short identifier chosen by you, used to identify
+which system and private key were used for signing) is also included in the
+`DKIM-Signature` header.
+
+The verification is done by the receiver: The public key is fetched
+via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
+for verifying the hash. You can publish multiple selectors for your domain,
+each use by a system which sends e-mail from your domain, without the need to
+share the private key.
+
+{pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
+
+Additionally it supports conditionally signing outbound mail if configured.
+It uses one private key and selector per PMG deployment (all nodes in a cluster
+use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is
+used as signing algorithm.
+
+The headers included in the signature are taken from the list of
+`Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`,
+`CC`, `Reply-To` and `Subject` get oversigned.
+
+You can either sign all mails received on the internal port using the domain of
+the envelope sender address or create a list of domains, for which e-mails
+should be signed, defaulting to the list of relay domains.
+
+
+Enable DKIM Signing::
+
+Controls whether outbound mail should get DKIM signed.
+
+Selector::
+
+The selector used for signing the mail. The private key used for signing is
+saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT
+record which you need to add to all domains signed by {pmg} by clicking on the
+'View DNS Record' Button.
+
+Sign all Outgoing Mail::
+
+Controls whether all outbound mail should get signed or only mails from domains
+listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise.
+
+Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`,
+using the following configuration keys:
+
+include::pmg.admin-dkim-conf-opts.adoc[]
+
+
Whitelist
~~~~~~~~~
for you) you should always add those servers here.
+[[pmgconfig_spamdetector]]
Spam Detector Configuration
---------------------------
+Options
+~~~~~~~
+
ifndef::manvolnum[]
image::images/screenshot/pmg-gui-spam-options.png[]
endif::manvolnum[]
include::pmg.spam-conf-opts.adoc[]
-Spam Quarantine Configuration
------------------------------
+[[pmgconfig_spamdetector_quarantine]]
+Quarantine
+~~~~~~~~~~
ifndef::manvolnum[]
image::images/screenshot/pmg-gui-spamquar-options.png[]
about the personal spam messages received the last day. That report is
only sent if there are new messages in the quarantine.
+Some options are only available in the config file `/etc/pmg/pmg.conf`,
+and not in the webinterface.
+
include::pmg.spamquar-conf-opts.adoc[]
+[[pmgconfig_clamav]]
Virus Detector Configuration
----------------------------
+[[pmgconfig_clamav_options]]
+Options
+~~~~~~~
+
ifndef::manvolnum[]
image::images/screenshot/pmg-gui-virus-options.png[]
endif::manvolnum[]
trigger manual updates there.
-Virus Quarantine Configuration
-------------------------------
+[[pmgconfig_clamav_quarantine]]
+Quarantine
+~~~~~~~~~~
ifndef::manvolnum[]
image::images/screenshot/pmg-gui-virusquar-options.png[]
include::pmg.virusquar-conf-opts.adoc[]
+Custom SpamAssassin configuration
+---------------------------------
+
+This is only for advanced users. {spamassassin}'s rules and their associated
+scores get updated regularly and are trained on a huge corpus, which gets
+classified by experts. In most cases adding a rule for matching a particular
+keyword is the wrong approach, leading to many false positives. Usually bad
+detection rates are better addressed by properly setting up DNS than by adding
+a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or
+spam-headers - see the {spamassassin_dnsbl}.
+
+To add or change the Proxmox {spamassassin} configuration please login to the
+console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this
+directory there are several files (`init.pre`, `local.cf`, ...) - do not change
+them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
+the xref:pmgconfig_template_engine[template engine], while the others can
+get updated by any {spamassassin} package upgrade.
+
+To add your special configuration, you have to create a new file and name it
+`custom.cf` (in this directory), then add your configuration there. Make sure
+to use the correct {spamassassin} syntax, and test with
+
+----
+# spamassassin -D --lint
+----
+
+If you run a cluster, the `custom.cf` file is synchronized from the
+master node to all cluster members automatically.
+
+
+[[pmgconfig_custom_check]]
+Custom Check Interface
+----------------------
+
+For use cases which are not handled by the {pmg} Virus Detector and
+{spamassassin} configuration, advanced users can create a custom check
+executable which, if enabled will be called before the Virus Detector and before
+passing an e-mail through the Rule System. The custom check API is kept as
+simple as possible, while still providing a great deal of control over the
+treatment of an e-mail. Its input is passed via two CLI arguments:
+
+* the 'api-version' (currently `v1`) - for potential future change of the
+ invocation
+
+* the 'queue-file-name' - a filename, which contains the complete e-mail as
+ rfc822/eml file
+
+The expected output need to be printed on STDOUT and consists of two lines:
+
+* the 'api-version' (currently 'v1') - see above
+
+* one of the following 3 results:
+** 'OK' - e-mail is ok
+** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
+ (the virusdescription is logged and added to the e-mail's headers)
+** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
+ to the e-mail's spamscore
+
+The check is run with a 5 minute timeout - if it is exceeded the check
+executable is killed and the e-mail is treated as OK.
+
+All output written to STDERR by the check is written with priority 'err' to the
+journal/mail.log.
+
+A simple sample script following the API (and yielding a random result) for
+reference:
+
+----
+#!/bin/sh
+
+echo "called with $*" 1>&2
+
+if [ "$#" -ne 2 ]; then
+ echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2
+ exit 1
+fi
+
+apiver="$1"
+shift
+
+if [ "$apiver" != "v1" ]; then
+ echo "wrong APIVERSION: $apiver" 1>&2
+ exit 2
+fi
+
+queue_file="$1"
+
+echo "v1"
+
+choice=$(shuf -i 0-3 -n1)
+
+case "$choice" in
+ 0)
+ echo OK
+ ;;
+ 1)
+ echo SCORE: 4
+ ;;
+ 2)
+ echo VIRUS: Random Virus
+ ;;
+ 3) #timeout-test
+ for i in $(seq 1 7); do
+ echo "custom checking mail: $queue_file - minute $i" 1>&2
+ sleep 60
+ done
+ ;;
+esac
+
+exit 0
+----
+
+The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf`
+
+----
+section: admin
+ custom_check 1
+----
+
+The location of the custom check executable can also be set there with the key
+`custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`.
+
+
User Management
---------------
-TODO
+User management in {pmg} consists of three types of users/accounts:
+
+
+[[pmgconfig_localuser]]
+Local Users
+~~~~~~~~~~~
+
+image::images/screenshot/pmg-gui-local-user-config.png[]
+
+Local users are used to manage and audit {pmg}. Those users can login on the
+management web interface.
+
+There are three roles:
+
+* Administrator
++
+Is allowed to manage settings of {pmg}, except some tasks like
+network configuration and upgrading.
+
+* Quarantine manager
++
+Is allowed to manage quarantines, blacklists and whitelists, but not other
+settings. Has no right to view any other data.
+
+* Auditor
++
+With this role, the user is only allowed to view data and configuration, but
+not to edit it.
+
+In addition there is always the 'root' user, which is used to perform special
+system administrator tasks, such as updgrading a host or changing the
+network configuration.
+
+NOTE: Only pam users are able to login via the webconsole and ssh, which the
+users created with the web interface are not. Those users are created for
+{pmg} administration only.
+
+Local user related settings are saved in `/etc/pmg/user.conf`.
+
+For details of the fields see xref:pmg_user_configuration_file[user.conf]
+
+[[pmgconfig_ldap]]
+LDAP/Active Directory
+~~~~~~~~~~~~~~~~~~~~~
+
+image::images/screenshot/pmg-gui-ldap-user-config.png[]
+
+You can specify multiple LDAP/Active Directory profiles, so that you can
+create rules matching those users and groups.
+
+Creating a profile requires (at least) the following:
+
+* profile name
+* protocol (LDAP or LDAPS; LDAPS is recommended)
+* at least one server
+* a user and password (if your server does not support anonymous binds)
+
+All other fields should work with the defaults for most setups, but can be
+used to customize the queries.
+
+The settings are saved to `/etc/pmg/ldap.conf`. Details for the options
+can be found here: xref:pmg_ldap_configuration_file[ldap.conf]
+
+Bind user
+^^^^^^^^^
+
+It is highly recommended that the user which you use for connecting to the
+LDAP server only has the permission to query the server. For LDAP servers
+(for example OpenLDAP or FreeIPA), the username has to be of a format like
+'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are
+depending on your setup. For Active Directory servers, the format should be
+like 'username@domain' or 'domain\username'.
+
+Sync
+^^^^
+
+{pmg} synchronizes the relevant user and group info periodically, so that
+that information is available in a fast manner, even when the LDAP/AD server
+is temporarily not accessible.
+
+After a successfull sync, the groups and users should be visible on the web
+interface. After that, you can create rules targeting LDAP users and groups.
+
+
+[[pmgconfig_fetchmail]]
+Fetchmail
+~~~~~~~~~
+
+image::images/screenshot/pmg-gui-fetchmail-config.png[]
+
+Fetchmail is utility for polling and forwarding e-mails. You can define
+e-mail accounts, which will then be fetched and forwarded to the e-mail
+address you defined.
+
+You have to add an entry for each account/target combination you want to
+fetch and forward. Those will then be regularly polled and forwarded,
+according to your configuration.
+
+The API and web interface offer following configuration options:
+
+include::fetchmail.conf.5-opts.adoc[]
ifdef::manvolnum[]
projects / pmg-docs.git / blobdiff