Proxmox Mail Gateway (PMG) Cheatsheet

Cheatsheet#pmg

Proxmox Mail Gateway (PMG) Cheatsheet

Proxmox Mail Gateway (PMG) is a full-featured open-source mail proxy & security platform. It acts as an inbound/outbound MTA filtering layer in front of internal mail servers (Mailcow, Exchange, cPanel, Postfix).

Service Management

# PMG Core Services
systemctl status pmg-smtp-filter       # Main spam/virus filtering engine
systemctl restart pmg-smtp-filter
 
systemctl status pmgproxy             # PMG Web GUI proxy
systemctl restart pmgproxy
 
systemctl status pmgdaemon            # PMG API management daemon
systemctl restart pmgdaemon
 
# Underlying Postfix MTA
systemctl status postfix
systemctl restart postfix
postfix reload                         # Reload Postfix configuration without dropping connections

PMG Configuration & Template Overrides

PMG dynamically generates /etc/postfix/main.cf and /etc/postfix/master.cf using template files. Direct edits to Postfix configuration files will be overwritten.

Always copy default templates from /var/lib/pmg/templates/ to /etc/pmg/templates/:

# Copy templates for customization
cp /var/lib/pmg/templates/main.cf.in /etc/pmg/templates/main.cf.in
cp /var/lib/pmg/templates/master.cf.in /etc/pmg/templates/master.cf.in
cp /var/lib/pmg/templates/transport.in /etc/pmg/templates/transport.in
 
# Sync configuration to runtime Postfix config & apply changes
pmgconfig sync
 
# Dump active PMG configuration variables
pmgconfig dump

Outbound SMTP HELO / EHLO & TLS Setup

1. Set Outbound HELO Hostname

Edit /etc/pmg/templates/main.cf.in:

# Define custom outbound HELO/EHLO identity
smtp_helo_name = mx1.yourdomain.com

Apply and verify:

pmgconfig sync
postconf smtp_helo_name                # Verify runtime setting

2. Inbound HELO Restrictions

Add strict HELO checks in /etc/pmg/templates/main.cf.in:

smtpd_helo_restrictions =
    permit_mynetworks,
    reject_invalid_helo_hostname,
    reject_non_fqdn_helo_hostname,
    permit

Cluster Management (`pmgcm`)

PMG uses a Master / Node architecture for high availability and centralized configuration management. The Master node replicates rules, user configs, and quarantine status across all nodes.

Cluster Status & Info Commands

# Show current cluster status, node health, and synchronization state
pmgcm status
 
# Display information about current node (Cluster ID, IP, Fingerprint)
pmgcm info
 
# Show local Cluster Node ID
pmgcm cid

Creating & Joining a Cluster

# 1. Initialize cluster on Master Node
pmgcm create
 
# 2. Join a secondary node to Master (Run on secondary node)
# pmgcm join <MASTER_IP> --fingerprint <MASTER_FINGERPRINT>
pmgcm join 10.1.1.10 --fingerprint 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF
 
# 3. Force database/configuration sync across cluster nodes
pmgcm sync
 
# 4. Remove a node from the cluster (Run on Master)
pmgcm delete <NODE_ID>

Rule System & Custom Filters (`pmg`)

PMG utilizes a database-driven Rule System for mail processing (Action, Discard, Accept, Spam/Virus Scoring).

# List all active rule objects
pmg rule list
 
# Dump active rule database configuration
pmgconfig dump

Trusted Networks & Mail Relay (Mailcow / cPanel / Exchange)

Whitelist internal mail servers so outbound mail bypasses spam checks and relays cleanly.

# Add internal server IPs to trusted MyNetworks
pmgconfig set mail --mynetworks "127.0.0.0/8 [::1]/128 10.1.1.0/24 192.168.1.50"
pmgconfig sync
 
# Reload Postfix configuration
postfix reload

DKIM Signing Setup

# 1. Initialize DKIM key pair (Default selector: pmg)
pmgconfig dkim init
 
# 2. Display public key TXT record to add to DNS
pmgconfig dkim get-selector-info
 
# 3. Enable DKIM signing globally
pmgconfig set dkim --selector pmg --sign 1 --sign-subdomains 1
pmgconfig sync

Quarantine Management (`pmgqm`)

# Show quarantine database statistics
pmgqm status
 
# Purge quarantined emails matching retention policy
pmgqm purge
 
# Send quarantine digest notification email to a specific user
pmgqm send --receiver [email protected]

Postfix Mail Queue Operations

# View current mail queue
mailq
 
# Force immediate delivery attempt for queued emails
postfix flush
 
# Delete a specific message from queue by Queue ID
postsuper -d <QUEUE_ID>
 
# Delete ALL queued messages (USE WITH CAUTION)
postsuper -d ALL

Real-Time Log Monitoring & Search

# PMG Integrated Mail Tracker CLI
pmg log view
 
# Search mail flow logs for specific sender or recipient
pmg log view -from [email protected]
pmg log view -to [email protected]
 
# Stream Postfix logs live
journalctl -u postfix -f
 
# Stream PMG SMTP filter engine logs live
journalctl -u pmg-smtp-filter -f

Backup & Restore (`pmgbackup`)

# Create full system & rule configuration backup (Saved to /var/lib/pmg/backup/)
pmgbackup backup
 
# List existing backup archives
ls -lh /var/lib/pmg/backup/
 
# Restore PMG configuration from an archive file
pmgbackup restore /var/lib/pmg/backup/pmg-backup_2026-08-10.tgz

Cheatsheets