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 dkim_record
Get the public key for the configured selector, prepared as DKIM TXT record
pmgconfig dkim_set --keysize <integer> --selector <string> [OPTIONS]
Generate a new private key for selector. All future mail will be signed with the new key!
- --force <boolean>
-
Overwrite existing key
- --keysize <integer> (1024 - N)
-
Number of bits for the RSA-Key
- --selector <string>
-
DKIM Selector
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.
|
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 file directly. Instead, we write changes to /etc/network/interfaces.new. When you reboot, we rename the file to /etc/network/interfaces, so the changes are applied on the next reboot.
- /etc/resolv.conf
-
DNS search domain and nameserver setup. Proxmox Mail Gateway uses the search domain setting to create the FQDN and domain name used in the postfix configuration.
- /etc/hostname
-
The system’s host name. Proxmox Mail Gateway uses the hostname to create the FQDN used in the postfix configuration.
- /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/dkim/domains
-
The list of domains for outbound DKIM signing.
- /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.
- /etc/mail/spamassassin/pmg-scores.cf
-
Custom SpamAssassin™ rule scores.
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).
- /etc/pmg/dkim/<selector>.private
-
Key for DKIM signing mails with selector <selector>.
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. These 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.
|
Modified templates from /etc/pmg/templates/ are automatically synced from the master node to all cluster members. |
White- and Blacklists
Proxmox Mail Gateway has multiple white- and blacklists. It differentiates between the SMTP Whitelist. The rule-based whitelist and the user whitelist. In addition to the whitelists there are 2 separate blacklists. The rule-based blacklist and the user blacklist.
SMTP Whitelist
The SMTP Whitelist is responsible for disabling greylisting as well as SPF and DNSBL checks. These are done during the SMTP dialogue.
Rule-based White-/Blacklist
The rule-based white- and blacklists are predefined rules. They work by checking the attached Who objects, containing e.g. a domain or a mail address, for a match. If it matches, the assigned action is used which by default is Accept for the whitelist rule and Block for the blacklist rule. In the default setup the blacklist rule has priority over the whitelist rule and spam checks.
User White-/Blacklist
The user white- and blacklist are user specific. Every user can add mail addresses to their white- and blacklist. When a user adds a mail address to the whitelist, the result of the spam analysis will be discarded for that recipient. This can help the mail being accepted, but it still depends on the other rules what happens next. In the default setup this results in the mail being accepted for this recipient.
For mail addresses on a user’s blacklist the spam score will be increased by 100. It still depends on the rule system what happens when a spam score that high is encountered. In the default setup it will be recognized as spam and quarantined (spam score of 3 or higher).
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.
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
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 publicly 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 needs 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 (/usr/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.
- custom_check: <boolean> (default = 0)
-
Use Custom Check Script. The script has to take the defined arguments and can return Virus findings or a Spamscore.
- custom_check_path: ^/([^/\0]+\/)+[^/\0]+$ (default = /usr/local/bin/pmg-custom-check)
-
Absolute Path to the Custom Check Script
- dailyreport: <boolean> (default = 1)
-
Send daily reports.
- demo: <boolean> (default = 0)
-
Demo mode - do not start SMTP filter.
- dkim_selector: <string>
-
Default DKIM selector
- dkim_sign: <boolean> (default = 0)
-
DKIM sign outbound mails with the configured Selector.
- dkim_sign_all_mail: <boolean> (default = 0)
-
DKIM sign all outgoing mails irrespective of the Envelope From domain.
- 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 (SMTP only, ignored for LMTP).
- relayport: <integer> (1 - 65535) (default = 25)
-
SMTP/LMTP port number for relay host.
- relayprotocol: <lmtp | smtp> (default = smtp)
-
Transport protocol 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.
- before_queue_filtering: <boolean> (default = 0)
-
Enable before queue filtering by pmg-smtp-filter
- 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 for IPv4.
- greylist6: <boolean> (default = 0)
-
Use Greylisting for IPv6.
- greylistmask4: <integer> (0 - 32) (default = 24)
-
Netmask to apply for greylisting IPv4 hosts
- greylistmask6: <integer> (0 - 128) (default = 64)
-
Netmask to apply for greylisting IPv6 hosts
- 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.
- ndr_on_block: <boolean> (default = 0)
-
Send out NDR when mail gets blocked
- 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.
Before and After Queue scanning
Scanning email can happen at two different stages of mail-processing:
-
Before-queue filtering: During the SMTP Session, after the complete message has been received (after the DATA command).
-
After-queue filtering: After initially accepting the mail and putting it on a queue for further processing.
Before-queue filtering 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 (Real-time Blackhole List).
After-queue filtering 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 mailing list) 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 Proxmox Mail Gateway 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 Proxmox Mail Gateway 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 Before-Queue Content Filter and Postfix After-Queue Content Filter respectively.
Greylisting
Greylisting is a technique for preventing unwanted messages from reaching the resource intensive stages of content analysis (virus detection and spam detection): By initially replying with a temporary failure code (450) to each new email, the Proxmox Mail Gateway tells the sending server that it should queue the mail and retry delivery at a later moment. Since certain kinds of spam get sent out by software, which has no provisioning for queueing, these mails are dropped without reaching Proxmox Mail Gateway or your mailbox.
The downside of greylisting is the delay introduced by the initial deferral of the email, which usually amounts to less than 30 minutes.
In order to prevent unnecessary delays in delivery from known sources, emails coming from a source for a recipient, which have passed greylisting in the past are directly passed on: For each email the triple <sender network, sender email, recipient email> is stored in a list, along with the time when delivery was attempted. If an email fits an already existing triple, the timestamp for that triple is updated and the email is accepted for further processing.
As long as a sender and recipient do communicate frequently there is no delay introduced by enabling greylisting. A triple is removed after a longer period of time, when no mail fitting that triple has been seen. The timeouts in Proxmox Mail Gateway are:
-
2 days for the retry of the first delivery
-
36 days for known triples
Mails with an empty envelope-sender are always delayed.
Some email service providers send out emails for one domain from multiple servers. To prevent delays due to an email coming in from 2 separate IPs of the same provider the triples store a network (cidr) instead of a single IP. For certain large providers the default network size might be too small. You can configure the netmask applied to an IP for the greylist lookup in /etc/pmg/pmg.conf or in the GUI with the settings greylistmask for IPv4 and greylistmask6 for IPv6 respectively.
Transports
You can use Proxmox Mail Gateway to send emails to different internal email servers. For example you can send emails addressed to domain.com to your first email server, and emails addressed to subdomain.domain.com to a second one.
You can add the IP addresses, hostname, transport protocol (smtp/lmtp), transport ports and mail domains (or just single email addresses) of your additional email servers. When transport protocol is set to lmtp, the option Use MX is useless and will be automatically set to No.
Networks
You can add additional internal (trusted) IP networks or hosts. All hosts in this list are allowed to relay.
|
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 destination. A destination is either a remote domain or a next-hop destination as specified in /etc/pmg/transport. This can be used if you need to prevent email 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 certificates 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.
DKIM Signing
DomainKeys Identified Mail (DKIM) Signatures (see RFC 6376) 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 used by a system which sends email from your domain, without the need to share the private key.
Proxmox Mail Gateway 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 emails 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 Proxmox Mail Gateway 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:
- dkim_selector: <string>
-
Default DKIM selector
- dkim_sign: <boolean> (default = 0)
-
DKIM sign outbound mails with the configured Selector.
- dkim_sign_all_mail: <boolean> (default = 0)
-
DKIM sign all outgoing mails irrespective of the Envelope From domain.
Whitelist
All SMTP checks are disabled for those entries (e.g. Greylisting, SPF, DNSBL, …)
DNSBL checks are done by postscreen which works on IP addresses and networks. This means it can only make use of the IP Address and IP Network entries.
|
If you use a backup MX server (e.g. your ISP offers this service for you) you should always add those servers here. |
|
To disable DNSBL checks entirely, remove any DNSBL Sites entries in Mail Proxy Options. |
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 email 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 ClamAV heuristics (Encrypted Archives/Documents, 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 Mail Gateway analyses all incoming email messages and decides for each email if it is ham or spam (or virus). Good emails are delivered to the inbox and spam messages are 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. The 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 web interface.
- 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.
- quarantinelink: <boolean> (default = 0)
-
Enables user self-service for Quarantine Links. Caution: this is accessible without authentication
- reportstyle: <custom | none | short | verbose> (default = verbose)
-
Spam report style.
- viewimages: <boolean> (default = 1)
-
Allow to view images.
Customization of Rulescores
While the default scoring of SpamAssassin™'s ruleset provides very good detection rates, sometimes your particular environment can benefit from slightly adjusting the score of a particular rule. Two examples:
-
Your system receives spam mails which are scored at 4.9 and you have a rule which puts all mails above 5 in the quarantine. The one thing the spam mails have in common is that they all hit URIBL_BLACK. By increasing the score of this rule by 0.2 points the spam mails would all be quarantined instead of being sent to your users
-
Your system tags many legitimate mails from a partner organization as spam, because the organization has a policy that each mail has to start with Dear madam or sir (generating 1.9 points through the rule DEAR_SOMETHING). By setting the score of this rule to 0 you can disable it completely.
The system logs all the rules which a particular mail hits. Analyzing the logs can lead to finding such a pattern in your environment.
You can adjust the score of a rule by creating a new Custom Rule Score entry in the GUI.
|
In general it is strongly recommended to not make large changes to the default scores. |
Virus Detector Configuration
Options
All mails are automatically passed to the included virus detector (ClamAV®). The default settings 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)
-
Whether to mark encrypted archives and documents as heuristic virus match. A match does not necessarily result in an immediate block, it just raises the Spam Score by clamav_heuristic_score.
- 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 (in bytes) 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 (in bytes) to be scanned for each input file.
- safebrowsing: <boolean> (default = 1)
-
Enables support for Google Safe Browsing.
- scriptedupdates: <boolean> (default = 0)
-
Enables ScriptedUpdates (incremental download of signatures)
Please note that the virus signature database is automatically updated. You can see the database status in the GUI, and also trigger manual updates there.
Quarantine
Indentified virus mails are automatically moved to the virus quarantine. The administrator can view these mails using the GUI, and choose to 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. 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 documentation.
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 template engine, while the others can get updated by any SpamAssassin™ package upgrade.
To add your custom 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 it with:
# spamassassin -D --lint
If you run a cluster, the custom.cf file is synchronized from the master node to all cluster members automatically.
To adjust the score assigned to a particular rule you can also use the Custom Rule Score settings in the GUI.
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 email 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 email. 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 email 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 - email is ok
-
VIRUS: <virusdescription> - email is treated as if it contained a virus (the virus description is logged and added to the email’s headers)
-
SCORE: <number> - <number> is added (negative numbers are also possible) to the email’s spamscore
-
The check is run with a 5 minute timeout - if it is exceeded the check executable is killed and the email 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

Local users can manage and audit Proxmox Mail Gateway. They can login on the management web interface.
There are four 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.
- Helpdesk
-
Combines permissions of the Auditor and the Quarantine Manager role.
In addition there is always the root user, which is used to perform special system administrator tasks, such as upgrading a host or changing the network configuration.
|
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

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 the information is available in a fast manner, even when the LDAP/AD server is temporarily not accessible.
After a successful sync, the groups and users should be visible on the web interface. After that, you can create rules targeting LDAP users and groups.
Fetchmail

Fetchmail is utility for polling and forwarding emails. You can define email accounts, which will then be fetched and forwarded to the email 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 and Disclaimer
Copyright © 2007-2020 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 https://www.gnu.org/licenses/