postfix-image/README.md

Postfix container

• Guide
  • Create new postfix server
• Supported environment variables
  • Generic variables
  • SMTP related variables
  • Activate additional checks
  • Virtual mailbox related variables
  • LDAP related variables
• Data persistence volumes
• Virtual domains and virtual users
  • Environment Variables
  • Files
• Mail delivery via LMTP

Guide

Create new postfix server

By default, a simple relayhost postfix instance is started.

The command to run this container is:

podman run -d --rm --name postfix -p 25:25 -e SMTP_RELAYHOST=smtp.example.com registry.opensuse.org/opensuse/postfix:%%postfix_version%%

In all examples, podman can be replaced directly with docker.

Supported environment variables

Generic variables

• DEBUG=[0|1] Enables "set -x" in the entrypoint script.
• TZ Timezone to use in the container.

SMTP related variables

• SERVER_HOSTNAME Server hostname. Emails will appear to come from the hostname's domain.
• SERVER_DOMAIN If not set, the domain part of SERVER_HOSTNAME will be used.
• SMTP_RELAYHOST Name of the SMTP relay server to use.
• SMTP_PORT=587 The relayhost port.
• SMTP_USERNAME Username to authenticate with on the relayserver.
• SMTP_PASSWORD Password of the SMTP user, alternative SMTP_PASSWORD_FILE could be used to point to a file with the password
• SMTP_NETWORKS Comma separated subnets who are allowed to use the relay. E.g. SMTP_NETWORKS='xxx.xxx.xxx.xxx/xx, xxx.xxx.xxx.xxx/xx'. 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 are preset.
• INET_PROTOCOLS The network interface protocols used for connections. Valid values are "all", "ipv4", "ipv6" or "ipv4,ipv6". The default value is "ipv4".
• MASQUERADE_DOMAINS Comma separated list of domains that must have their subdomain structure stripped off.
• MYDESTINATION List of domains for which mails are delivered locally instead of forwarding to another machine.
• NULLCLIENT=[0|1] Don't accept any mails locally but relay them to a remote host. Ignored if MYDESTINATION is set. The default is 1.
• SMTP_TLS_SECURITY_LEVEL SMTP TLS security level. The default is may.
• LMTP=host Host on which the lmtp service is running. This will disable the usage of the vmail user account.

Accepting mails on port 587 (submission) and 465 (submissions/smtps)

• ENABLE_SUBMISSION=[0|1] Enable submission port. The default is 0.
• ENABLE_SUBMISSIONS=[0|1] Enable submissions/smtps port. This requires SMTPD_USE_TLS=1. The default is 0.
• SMTPD_USE_TLS=[0|1] Enforce TLS. The default is 0.
• SMTPD_TLS_CRT= Path to certificate, default /etc/postfix/ssl/certs/tls.crt
• SMTPD_TLS_KEY= Path to public key, default /etc/postfix/ssl/certs/tls.key

Virtual mailbox related variables

• VIRTUAL_MBOX=[0|1] Create virtual mail boxes in /var/spool/vmail owned by user vmail.
• VMAIL_UID=5000 User ID and group ID of the vmail user for virtual domains and mailboxes.
• VIRTUAL_DOMAINS= Whitespace separated list of virtual domains, will be written to /etc/postfix/vhosts.
• VIRTUAL_USERS= Whitespace separated list of virtual users email addresses.

LDAP related variables

• USE_LDAP=[0|1] Use LDAP for virtual mail box user accounts.
• LDAP_BASE_DN LDAP base DN, defaults to dc=example,dc=org.
• LDAP_SERVER_URL LDAP Server URL, defaults to ldap://localhost.
• LDAP_BIND_DN DN to bind, defaults to cn=mailAccountReader,ou=Manager,dc=example,dc=org
• LDAP_BIND_PASSWORD The password for the distinguished name to bind (LDAP_BIND_DN)
• LDAP_USE_TLS=[1|0] Use TLS for LDAP queries, by default enabled.
• LDAP_TLS_CA_CRT LDAP SSL CA certificate.

Data persistence volumes

• /var/spool/postfix Postfix mail queues. A data volume should be used in order to save the queue content if the container restarts.
• /var/spool/vmail Virtual user mboxes. This directory contains the mails stored in Maildir format of the virtual users of the virtual domains. Everything is owned by the vmail user.
• /etc/pki PKI directories for CA certificates

Virtual domains and virtual users

The environment variable VIRTUAL_MBOX=1 will enable support for virtual domains and virtual users. It can be used in conjunction with a relay host.

Mails for virtual domains and users are stored in Maildir format in /var/spool/vmail inside the container. To not loose the mail, this directory should be a persistence volume. VMAIL_UID specifies the UID and GID which owns all files below this directory. This ensures that the container is using the same UID/GID as the container host OS for the files and no regular users own these files and can read or modify them. The default UID/GID is 5000.

There are three ways to provide the data for virtual domains and users: via environment variables, files or LDAP.

Environment Variables

Besides the already mentioned environment variables, two further variables define the virtual domains and the virtual users. VIRTUAL_DOMAINS="example.com example2.com example3.com" is a whitespace separated list which can contain one or more virtual domains. For every domain, an own directory below /var/spool/vmail will be created. VIRTUAL_USERS="user1@example.com user@example3.com user2@example.com" Whitespace separated list of virtual users email addresses.

The example call:

podman run -d --rm --name postfix -p "25:25" \
    -e VIRTUAL_MBOX=1 \
    -e VMAIL_UID=5000 \
    -e VIRTUAL_DOMAINS="example.com example1.com" \
    -e VIRTUAL_USERS="user1@example.com user2@example.com user@example1.com" \
    -e SERVER_HOSTNAME=smtp.example.com \
    -e SMTP_RELAYHOST=relay.example.com \
    -e SMTP_USERNAME=mailer \
    -e SMTP_PASSWORD='XXX' \
    -v "/srv/postfix/vmail:/var/spool/vmail:Z" \
    registry.opensuse.org/opensuse/postfix:%%postfix_version%%

Will store the mails for the users user1@example.com, user2@example.com, user@example1.com into the directories inside of the container:

• /var/spool/vmail/example.com/user1/
• /var/spool/vmail/example.com/user2/
• /var/spool/vmail/example1.com/user/

and outside the container:

• /srv/postfix/vmail/example.com/user1/
• /srv/postfix/vmail/example.com/user2/
• /srv/postfix/vmail/example1.com/user/

owned by the user vmail with UID and GID 5000. All other mails are forwarded to the relay relay.example.com with the account mailer and the password XXX.

Files

Instead of maintaining a long list of environment variables, the configuration files could also be provided and mapped into /etc/postfix of the container.

/etc/postfix/vhosts contains the list of virtual domains separated by newlines:

example.com
example1.com

/etc/postfix/vmaps contains the list of the virtual users, where to store them below the vmail directory and if mbox format or Maildir should be used. For Maildir, the configuration file for the above example would look like:

user1@example.com example.com/user1/
user2@example.com example.com/user2/
user@example1.com example1.com/user/

For mbox format, the trailing '/' needs to be removed.

Additionally, a /etc/postfix/vquota file is required, which contains the quota of the virtual users mailbox. To disable it, the file would look like:

user1@example.com 0
user2@example.com 0
user@example1.com 0

The example call:

podman run -d --rm --name postfix -p 25:25 \
    -e VIRTUAL_MBOX=1 \
    -e VMAIL_UID=5000 \
    -e SERVER_HOSTNAME=smtp.example.com \
    -e SMTP_RELAYHOST=relay.example.com \
    -e SMTP_USERNAME=mailer \
    -e SMTP_PASSWORD='XXX' \
    -v "/srv/postfix/vmail:/var/spool/vmail:z" \
    -v "/srv/postfix/etc/vhosts:/etc/postfix/vhosts:z,ro" \
    -v "/srv/postfix/etc/vmaps:/etc/postfix/vmaps:z,ro" \
    -v "/srv/postfix/etc/vquota:/etc/postfix/vquota:z,ro" \
    registry.opensuse.org/opensuse/postfix:%%postfix_version%%

LDAP

With LDAP (use VIRTUAL_MBOX=1 and USE_LDAP=1) the postfix schema is used: maildrop is the real email address, while mailacceptinggeneralid are aliases. If the VIRTUAL_DOMAINS environment variable is not set, the virtual domains are take from the email addresses used in mailacceptinggeneralid. In this case, the email domains of the aliases must be different then the one of maildrop. If the virtual domains are specified with VIRTUAL_DOMAINS, mailacceptinggeneralid are handled as normal mail aliases and the domain could be the same as for maildrop.

Mail delivery via LMTP

To deliver the mails via a LMTP service, the container needs to know the host on which such a service is running:

podman run -d --rm --name postfix -p 25:25 -e MYDESTINATION=example.com -e LMTP=lmtp.example.com registry.opensuse.org/opensuse/postfix:%%postfix_version%%

Licensing

SPDX-License-Identifier: (EPL-2.0 OR IPL-1.0) AND MIT

This documentation and the build recipe are licensed as (EPL-2.0 OR IPL-1.0) AND MIT. The container itself contains various software components under various open source licenses listed in the associated Software Bill of Materials (SBOM).

This image is based on openSUSE Tumbleweed.