NAME

pmgconfig - Proxmox Mail Gateway Configuration Management Toolkit

SYNOPSIS

pmgconfig <COMMAND> [ARGS] [OPTIONS]

pmgconfig apicert [OPTIONS]

Generate /etc/pmg/pmg-api.pem (self signed certificate for GUI and REST API).

--force <boolean> (default = 0)

Overwrite existing certificate.

pmgconfig dump

Print configuration setting which can be used in templates.

pmgconfig help [OPTIONS]

Get help about specified command.

--extra-args <array>

Shows help for a specific command

--verbose <boolean>

Verbose output format.

pmgconfig init

Generate required files in /etc/pmg/

pmgconfig ldapsync

Syncronize the LDAP database.

pmgconfig sync [OPTIONS]

Syncronize Proxmox Mail Gateway configurations with system configuration.

--restart <boolean> (default = 0)

Restart services if necessary.

pmgconfig tlscert [OPTIONS]

Generate /etc/pmg/pmg-tls.pem (self signed certificate for encrypted SMTP traffic).

--force <boolean> (default = 0)

Overwrite existing certificate.

DESCRIPTION

Proxmox Mail Gateway is usually configured using the web-based Graphical User Interface (GUI), but it is also possible to directly edit the configuration files, use the REST API over https or the command line tool pmgsh.

The command line tool pmgconfig is used to simplify some common configuration tasks, i.e. to generate cerificates and to rewrite service configuration files.

Note We use a Postgres database to store mail filter rules and statistic data. See chapter Database Management for more information.

Configuration files overview

/etc/network/interfaces

Network setup. We never modify this files directly. Instead, we write changes to /etc/network/interfaces.new. When you reboot, we rename the file to /etc/network/interfaces, so any changes gets activated on the next reboot.

/etc/resolv.conf

DNS search domain and nameserver setup.

/etc/hostname

The system’s host name.

/etc/hosts

Static table lookup for hostnames.

/etc/pmg/pmg.conf

Stores common administration options, i.e. the spam and mail proxy setup.

/etc/pmg/cluster.conf

The cluster setup.

/etc/pmg/domains

The list of relay domains.

/etc/pmg/fetchmailrc

Fetchmail configuration (POP3 and IMAP setup).

/etc/pmg/ldap.conf

LDAP configuration.

/etc/pmg/mynetworks

List of local (trusted) networks.

/etc/pmg/subscription

Stores your subscription key and status.

/etc/pmg/tls_policy

TLS policy for outbound connections.

/etc/pmg/transports

Message delivery transport setup.

/etc/pmg/user.conf

GUI user configuration.

/etc/mail/spamassassin/custom.cf

Custom SpamAssassin™ setup.

Keys and Certificates

/etc/pmg/pmg-api.pem

Key and certificate (combined) used be the HTTPs server (API).

/etc/pmg/pmg-authkey.key

Privat key use to generate authentication tickets.

/etc/pmg/pmg-authkey.pub

Public key use to verify authentication tickets.

/etc/pmg/pmg-csrf.key

Internally used to generate CSRF tokens.

/etc/pmg/pmg-tls.pem

Key and certificate (combined) to encrypt mail traffic (TLS).

Service Configuration Templates

Proxmox Mail Gateway uses various services to implement mail filtering, for example the Postfix Mail Transport Agent (MTA), the ClamAV® antivirus engine and the Apache SpamAssassin™ project. Those services use separate configuration files, so we need to rewrite those files when configuration is changed.

We use a template based approach to generate those files. The Template Toolkit is 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 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 dump
...
dns.domain = yourdomain.tld
dns.hostname = pmg
ipconfig.int_ip = 192.168.2.127
pmg.admin.advfilter = 1
...

The same tool is used to force regeneration of all template based configuration files. You need to run that after modifying a template, or when you directly edit configuration files

# pmgconfig sync --restart 1

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.

Note Modified templates from /etc/pmg/templates/ are automatically synced from the master node to all cluster members.

System Configuration

Network and Time

Normally the network and time is already configured when you visit the GUI. The installer asks for those settings and sets up the correct values.

The default setup uses a single Ethernet adapter and static IP assignment. The configuration is stored at /etc/network/interfaces, and the actual network setup is done the standard Debian way using package ifupdown.

Example network setup /etc/network/interfaces
source /etc/network/interfaces.d/*

auto lo
iface lo inet loopback

auto ens18
iface ens18 inet static
        address  192.168.2.127
        netmask  255.255.240.0
        gateway  192.168.2.1
DNS recommendations

Many tests to detect SPAM mails use DNS queries, so it is important to have a fast and reliable DNS server. We also query some public available DNS Blacklists. Most of them apply rate limits for clients, so they simply will not work if you use a public DNS server (because they are usually blocked). We recommend to use your own DNS server, which need to be configured in recursive mode.

Options

Those settings are saved to subsection admin in /etc/pmg/pmg.conf, using the following configuration keys:

advfilter: <boolean> (default = 1)

Use advanced filters for statistic.

avast: <boolean> (default = 0)

Use Avast Virus Scanner (/bin/scan). You need to buy and install Avast Core Security before you can enable this feature.

clamav: <boolean> (default = 1)

Use ClamAV Virus Scanner. This is the default virus scanner and is enabled by default.

dailyreport: <boolean> (default = 1)

Send daily reports.

demo: <boolean> (default = 0)

Demo mode - do not start SMTP filter.

email: <string> (default = admin@domain.tld)

Administrator E-Mail address.

http_proxy: http://.*

Specify external http proxy which is used for downloads (example: http://username:password@host:port/)

statlifetime: <integer> (1 - N) (default = 7)

User Statistics Lifetime (days)

Mail Proxy Configuration

Relaying

Those settings are saved to subsection mail in /etc/pmg/pmg.conf, using the following configuration keys:

relay: <string>

The default mail delivery transport (incoming mails).

relaynomx: <boolean> (default = 0)

Disable MX lookups for default relay.

relayport: <integer> (1 - 65535) (default = 25)

SMTP port number for relay host.

smarthost: <string>

When set, all outgoing mails are deliverd to the specified smarthost.

smarthostport: <integer> (1 - 65535) (default = 25)

SMTP port number for smarthost.

Relay Domains

List of relayed mail domains, i.e. what destination domains this system will relay mail to. The system will reject incoming mails to other domains.

Ports

Those settings are saved to subsection mail in /etc/pmg/pmg.conf, using the following configuration keys:

ext_port: <integer> (1 - 65535) (default = 25)

SMTP port number for incoming mail (untrusted). This must be a different number than int_port.

int_port: <integer> (1 - 65535) (default = 26)

SMTP port number for outgoing mail (trusted).

Options

Those settings are saved to subsection mail in /etc/pmg/pmg.conf, using the following configuration keys:

banner: <string> (default = ESMTP Proxmox)

ESMTP banner.

conn_count_limit: <integer> (0 - N) (default = 50)

How many simultaneous connections any client is allowed to make to this service. To disable this feature, specify a limit of 0.

conn_rate_limit: <integer> (0 - N) (default = 0)

The maximal number of connection attempts any client is allowed to make to this service per minute. To disable this feature, specify a limit of 0.

dnsbl_sites: <string>

Optional list of DNS white/blacklist domains (see postscreen_dnsbl_sites parameter).

dnsbl_threshold: <integer> (0 - N) (default = 1)

The inclusive lower bound for blocking a remote SMTP client, based on its combined DNSBL score (see postscreen_dnsbl_threshold parameter).

dwarning: <integer> (0 - N) (default = 4)

SMTP delay warning time (in hours).

greylist: <boolean> (default = 1)

Use Greylisting.

helotests: <boolean> (default = 0)

Use SMTP HELO tests.

hide_received: <boolean> (default = 0)

Hide received header in outgoing mails.

maxsize: <integer> (1024 - N) (default = 10485760)

Maximum email size. Larger mails are rejected.

message_rate_limit: <integer> (0 - N) (default = 0)

The maximal number of message delivery requests that any client is allowed to make to this service per minute.To disable this feature, specify a limit of 0.

rejectunknown: <boolean> (default = 0)

Reject unknown clients.

rejectunknownsender: <boolean> (default = 0)

Reject unknown senders.

spf: <boolean> (default = 1)

Use Sender Policy Framework.

verifyreceivers: <450 | 550>

Enable receiver verification. The value spefifies the numerical reply code when the Postfix SMTP server rejects a recipient address.

Transports

You can use Proxmox Mail Gateway to send e-mails to different internal e-mail servers. For example you can send e-mails addressed to domain.com to your first e-mail server, and e-mails addressed to subdomain.domain.com to a second one.

You can add the IP addresses, hostname and SMTP ports and mail domains (or just single email addresses) of your additional e-mail servers.

Networks

You can add additional internal (trusted) IP networks or hosts. All hosts in this list are allowed to relay.

Note Hosts in the same subnet with Proxmox can relay by default and it’s not needed to add them in this list.

TLS

Transport Layer Security (TLS) provides certificate-based authentication and encrypted sessions. An encrypted session protects the information that is transmitted with SMTP mail. When you activate TLS, Proxmox Mail Gateway automatically generates a new self signed certificate for you (/etc/pmg/pmg-tls.pem).

Proxmox Mail Gateway 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. 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

To get additional information about SMTP TLS activity you can enable TLS logging. That way information about TLS sessions and used certificate’s is logged via syslog.

Add TLS received header

Set this option to include information about the protocol and cipher used as well as the client and issuer CommonName into the "Received:" message header.

Those settings are saved to subsection mail in /etc/pmg/pmg.conf, using the following configuration keys:

tls: <boolean> (default = 0)

Enable TLS.

tlsheader: <boolean> (default = 0)

Add TLS received header.

tlslog: <boolean> (default = 0)

Enable TLS Logging.

Whitelist

All SMTP checks are disabled for those entries (e. g. Greylisting, SPF, RBL, …)

Note If you use a backup MX server (e.g. your ISP offers this service for you) you should always add those servers here.

Spam Detector Configuration

Options

Proxmox Mail Gateway uses a wide variety of local and network tests to identify spam signatures. This makes it harder for spammers to identify one aspect which they can craft their messages to work around the spam filter.

Every single e-mail will be analyzed and gets a spam score assigned. The system attempts to optimize the efficiency of the rules that are run in terms of minimizing the number of false positives and false negatives.

bounce_score: <integer> (0 - 1000) (default = 0)

Additional score for bounce mails.

clamav_heuristic_score: <integer> (0 - 1000) (default = 3)

Score for ClamaAV heuristics (Google Safe Browsing database, PhishingScanURLs, …).

languages: (all|([a-z][a-z])+( ([a-z][a-z])+)*) (default = all)

This option is used to specify which languages are considered OK for incoming mail.

maxspamsize: <integer> (64 - N) (default = 262144)

Maximum size of spam messages in bytes.

rbl_checks: <boolean> (default = 1)

Enable real time blacklists (RBL) checks.

use_awl: <boolean> (default = 1)

Use the Auto-Whitelist plugin.

use_bayes: <boolean> (default = 1)

Whether to use the naive-Bayesian-style classifier.

use_razor: <boolean> (default = 1)

Whether to use Razor2, if it is available.

wl_bounce_relays: <string>

Whitelist legitimate bounce relays.

Quarantine

Proxmox analyses all incoming e-mail messages and decides for each e-mail if its ham or spam (or virus). Good e-mails are delivered to the inbox and spam messages can be moved into the spam quarantine.

The system can be configured to send daily reports to inform users 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.

allowhrefs: <boolean> (default = 1)

Allow to view hyperlinks.

authmode: <ldap | ldapticket | ticket> (default = ticket)

Authentication mode to access the quarantine interface. Mode ticket allows login using tickets sent with the daily spam report. Mode ldap requires to login using an LDAP account. Finally, mode ldapticket allows both ways.

hostname: <string>

Quarantine Host. Useful if you run a Cluster and want users to connect to a specific host.

lifetime: <integer> (1 - N) (default = 7)

Quarantine life time (days)

mailfrom: <string>

Text for From header in daily spam report mails.

port: <integer> (1 - 65535) (default = 8006)

Quarantine Port. Useful if you have a reverse proxy or port forwarding for the webinterface. Only used for the generated Spam report.

protocol: <http | https> (default = https)

Quarantine Webinterface Protocol. Useful if you have a reverse proxy for the webinterface. Only used for the generated Spam report.

reportstyle: <custom | none | short | verbose> (default = verbose)

Spam report style.

viewimages: <boolean> (default = 1)

Allow to view images.

Virus Detector Configuration

Options

All mails are automatically passed to the included virus detector (ClamAV®). The default setting are considered safe, so it is usually not required to change them.

ClamAV® related settings are saved to subsection clamav in /etc/pmg/pmg.conf, using the following configuration keys:

archiveblockencrypted: <boolean> (default = 0)

Wether to block encrypted archives. Mark encrypted archives as viruses.

archivemaxfiles: <integer> (0 - N) (default = 1000)

Number of files to be scanned within an archive, a document, or any other kind of container. Warning: disabling this limit or setting it too high may result in severe damage to the system.

archivemaxrec: <integer> (1 - N) (default = 5)

Nested archives are scanned recursively, e.g. if a ZIP archive contains a TAR file, all files within it will also be scanned. This options specifies how deeply the process should be continued. Warning: setting this limit too high may result in severe damage to the system.

archivemaxsize: <integer> (1000000 - N) (default = 25000000)

Files larger than this limit won’t be scanned.

dbmirror: <string> (default = database.clamav.net)

ClamAV database mirror server.

maxcccount: <integer> (0 - N) (default = 0)

This option sets the lowest number of Credit Card or Social Security numbers found in a file to generate a detect.

maxscansize: <integer> (1000000 - N) (default = 100000000)

Sets the maximum amount of data to be scanned for each input file.

safebrowsing: <boolean> (default = 1)

Enables support for Google Safe Browsing.

Please note that the virus signature database it automatically updated. But you can see the database status on the GUI, and you can trigger manual updates there.

Quarantine

Indentified virus mails are automatically moved to the virus quarantine. The administartor can view those mails using the GUI, or deliver them in case of false positives. Proxmox Mail Gateway does not notify individual users about received virus mails.

Virus quarantine related settings are saved to subsection virusquar in /etc/pmg/pmg.conf, using the following configuration keys:

allowhrefs: <boolean> (default = 1)

Allow to view hyperlinks.

lifetime: <integer> (1 - N) (default = 7)

Quarantine life time (days)

viewimages: <boolean> (default = 1)

Allow to view images.

Custom SpamAssassin configuration

This is only for advanced users. To add or change the Proxmox SpamAssassin™ configuration please login to the console via SSH. Go to directory /etc/mail/spamassassin/. In this directory there are several files (init.pre, local.cf, …) – do not change them.

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. Be aware to use the 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.

Custom Check Interface

For use cases which are not handled by the Proxmox Mail Gateway 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

User management in Proxmox Mail Gateway consists of three types of users/accounts:

Local Users

images/screenshot/pmg-gui-local-user-config.png

Local users are used to manage and audit Proxmox Mail Gateway. Those users can login on the management web interface.

There are three roles:

  • Administrator

    Is allowed to manage settings of Proxmox Mail Gateway, 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 Proxmox Mail Gateway administration only.

Local user related settings are saved in /etc/pmg/user.conf.

For details of the fields see user.conf

LDAP/Active Directory

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: 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

Proxmox Mail Gateway 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.

Fetchmail

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:

enable: <boolean> (default = 0)

Flag to enable or disable polling.

interval: <integer> (1 - 2016)

Only check this site every <interval> poll cycles. A poll cycle is 5 minutes.

keep: <boolean> (default = 0)

Keep retrieved messages on the remote mailserver.

pass: <string>

The password used tfor server login.

port: <integer> (1 - 65535)

Port number.

protocol: <imap | pop3>

Specify the protocol to use when communicating with the remote mailserver

server: <string>

Server address (IP or DNS name).

ssl: <boolean> (default = 0)

Use SSL.

target: (?:|[^\s\/\@]+\@[^\s\/\@]+)

The target email address (where to deliver fetched mails).

user: <string>

The user identification to be used when logging in to the server

Copyright © 2007-2019 Proxmox Server Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/