Proxmox Postfix – Sender Rewrite for Alerts (Gmail Relay)

proxmox-postfix-sender-rewrite.md

Proxmox Postfix – Sender Rewrite for Alerts (Gmail Relay)

This document describes, in a fully reproducible and platform‑correct way, how the sender of locally generated emails (e.g. Proxmox alerts) is rewritten to a clean, consistent identity such as:

Proxmox <alerts@example.com>

with delivery via Gmail as smart relay (smtp.gmail.com:587).

The solution is native Postfix, requires no milters, no OpenDKIM, and is fully supported on Debian 12 / Proxmox VE.

---

1. Context and goal

Problem

• Proxmox sends alerts as root@<hostname>
• Mail clients (Gmail) show root as sender name
• SPF / DKIM / DMARC must remain valid
• The solution must be upgrade‑safe and simple

Goal

• Rewrite the visible sender to a fixed, human‑friendly identity
• Normalize the SMTP envelope sender
• Relay mail securely via Gmail
• Avoid unsupported or deprecated tooling

---

2. What does NOT work on Debian 12 / Proxmox

The following approaches were explicitly tested and rejected:

❌ OpenDKIM header rewriting

• Debian/Proxmox OpenDKIM builds do not reliably support header rewriting
• conf.d includes fail
• Service startup is inconsistent

❌ milter‑regex

• Not available in Debian 12 (bookworm)
• Not present in main, contrib, or Proxmox repositories

❌ Custom milters

• Unnecessary complexity
• Harder to maintain

---

3. Final solution overview

The final working solution consists of two clearly separated parts:

1. Mail relay via Gmail (SMTP + authentication)
2. Sender normalization using native Postfix mechanisms

Both parts are required for a correct and reliable result.

---

4. Installed packages

4.1 Mail relay (Gmail)

apt install postfix libsasl2-modules ca-certificates

• postfix – Mail Transfer Agent
• libsasl2-modules – SASL authentication support
• ca-certificates – TLS certificate validation

4.2 Header / envelope rewriting

apt install postfix-pcre

This package enables the pcre: dictionary type in Postfix.

Without it, Postfix logs errors such as:

unsupported dictionary type: pcre

---

5. Configuration changes

5.1 Hostname normalization (important)

The system hostname must be correct and consistent, otherwise Postfix will embed legacy hostnames in headers.

Executed:

hostnamectl set-hostname proxmox.example.local

Verified in:

• /etc/hostname
• /etc/hosts

This prevents old or unintended hostnames from appearing in generated mail.

---

5.2 Gmail relay configuration

The Proxmox host does not deliver mail directly to the internet. All outbound mail is relayed via Gmail.

/etc/postfix/main.cf (relevant options)

relayhost = [smtp.gmail.com]:587

smtp_use_tls = yes
smtp_tls_security_level = encrypt
smtp_tls_CAfile = /etc/ssl/certs/ca-certificates.crt

smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_sasl_tls_security_options = noanonymous

/etc/postfix/sasl_passwd

[smtp.gmail.com]:587 alerts@example.com:APP_PASSWORD_OR_OAUTH_TOKEN

Notes:

• This is not the account password
• Use either a Gmail App Password or an OAuth2 / API token

Then:

postmap /etc/postfix/sasl_passwd
chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db

---

5.3 Header rewrite (visible sender)

/etc/postfix/header_rewrite.pcre

/^From:\s*root\b.*$/    REPLACE From: "Proxmox" <alerts@example.com>

This rewrites the visible From header (display name + address).

---

5.4 Envelope sender normalization

/etc/postfix/sender_canonical

/^root(@.*)?$/    alerts@example.com

This rewrites the SMTP envelope sender (MAIL FROM) so that root@hostname is never exposed at SMTP level.

---

5.5 /etc/postfix/main.cf – rewrite configuration

# Allow rewriting for locally generated mail
local_header_rewrite_clients = static:all

# Header rewriting
header_checks = pcre:/etc/postfix/header_rewrite.pcre
smtp_header_checks = pcre:/etc/postfix/header_rewrite.pcre

# Envelope sender rewriting
sender_canonical_maps = regexp:/etc/postfix/sender_canonical

---

6. Actions performed

postmap /etc/postfix/sasl_passwd
systemctl restart postfix

Verification:

postconf -m | grep pcre

Expected output:

pcre

---

7. Testing

echo "rewrite test" | mail -s "Proxmox alert test" admin@example.com

Expected result in Gmail:

From: Proxmox <alerts@example.com>

No:

• deferred mail
• root as sender
• SMTP errors

---

8. Cleanup

The following components were deliberately removed:

apt purge -y opendkim opendkim-tools
rm -rf /etc/opendkim
rm -rf /run/opendkim

Reason:

• Not supported for this use case on Debian 12
• Avoids future confusion

---

9. Summary

This setup provides:

• Native Postfix solution
• Gmail relay with secure authentication
• Clean sender identity for Proxmox alerts
• Full compatibility with Debian 12 / Proxmox VE
• Minimal moving parts

The configuration is upgrade‑safe, auditable, and production‑ready.

---

End of document.