Ansible collection: foundata.postfix

The ansible collection foundata.postfix provides resources to manage and use the Postfix mail transfer agent (MTA) that routes and delivers electronic mail (email) via SMTP and LMTP.

The following lists the README.md files of the most important included contents (e.g. roles). You might browse the source code repositories for a better overview.

Ansible role: foundata.postfix.run

The foundata.postfix.run Ansible role (part of the foundata.postfix Ansible collection).

It provides automated configuration management of Postfix across major platforms. It does not explain how to create a good Postfix configuration that suits your requirements; that task remains for you to accomplish. However, the examples playbooks may help you a bit with that.

Features

Main features:

• Full support for managing all main.cf and master.cf settings.
• Automatic detection and installation of required backend packages for map types (e.g., LMDB, MySQL, PostgreSQL) based on your configuration.
• Specialized parameters for simplified management of commonly needed Postfix settings, such as:
  • Lookup tables for virtual, transport, and other mappings.
  • Management of relay_domains for fine-grained control over relaying behavior.
• Provides sensible, production-ready defaults, tuned for recent Postfix versions, including support for modern map types like LMDB.
• Designed for cross-platform compatibility, working seamlessly across major Linux distributions.

Example playbooks, using this role

Installation with automatic upgrade:

---

- name: "Initialize the foundata.postfix.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.postfix.run role"
      ansible.builtin.include_role:
        name: "foundata.postfix.run"
      vars:
        run_postfix_autoupgrade: true

Install and do some basic and common configuration:

---

- name: "Initialize the foundata.postfix.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.postfix.run role"
      ansible.builtin.include_role:
        name: "foundata.postfix.run"
      vars:
        run_postfix_autoupgrade: true
        run_postfix_maincf_settings:
          myhostname: "smtp.example.com"
          mydomain: "example.com"
          inet_interfaces: "all"
          inet_protocols: "all"
          smtp_tls_security_level: "may"
          smtpd_tls_security_level: "may"
          smtp_tls_note_starttls_offer: "yes"
          smtpd_tls_cert_file: "/etc/ssl/certs/smtp.example.com/fullchain.cer"
          smtpd_tls_key_file: "/etc/ssl/private/smtp.example.com/cert.key"
          smtpd_tls_dh1024_param_file: "/etc/ssl/certs/dhparam_ffdhe2048.pem" # see https://www.postfix.org/postconf.5.html#smtpd_tls_dh1024_param_file
          message_size_limit: 52428800 # 50 MiB; max size of a incoming email
          mailbox_size_limit: 0 # 0 == unlimited; max mailbox size should be controlled by the mailserver
          relayhost: "[relay.example.org]:25"
          header_size_limit: 4096000
        run_postfix_mastercf_settings:
          smtps:
            type: "inet"
            private: "n"
            unpriv: "-"
            chroot: "n"
            wakeup: "-"
            maxproc: "-"
            command_args: "smtpd"
        run_postfix_relay_domains_manage: true
        run_postfix_relay_domains_list:
          - "example.com"
        run_postfix_transport_manage: true
        run_postfix_transport_map:
          "example.com": "lmtp:unix:/var/spool/postfix/private/lmtp-dovecot"
          "example.net": "lmtp:127.0.0.1:24"
          "example.org": "[192.168.0.1]"
          "foo.example.org": "[mailrelay.foo.example.org]:123"
        run_postfix_virtual_manage: true
        run_postfix_virtual_aliasdomains_list:
          - "example.com"
          - "example.net"
          - "example.org"
        run_postfix_virtual_alias_map:
          "admin@example.com":
            - "admin@actual-destination.example.com"
          "distribution@example.com":
            - "user1@example.com"
            - "user2@example.com"
            - "user3@example.com"
            - "user3@@example.com"
          "@example.com": # catch-all for example.com
            - "office@example.com"
          "@example.net": # catch-all for example.net, rewrite all to @example.com
            - "example.com"

Uninstall:

---

- name: "Initialize the foundata.postfix.run role"
  hosts: localhost
  gather_facts: false
  tasks:

    - name: "Trigger invocation of the foundata.postfix.run role"
      ansible.builtin.include_role:
        name: "foundata.postfix.run"
      vars:
        run_postfix_state: "absent"

Supported tags

It might be useful and faster to only call parts of the role by using tags:

• run_postfix_setup: Manage basic resources, such as packages or service users.
• run_postfix_config: Manage settings, such as adapting or creating configuration files.
• run_postfix_service: Manage services and daemons, such as running states and service boot configurations.

There are also tags that are generally not intended to be called directly but are included for completeness and to cover edge cases:

• run_postfix_always, always: Tasks needed by the role itself for internal role setup and the Ansible environment.

Role variables

Main entry point for the foundata.postfix.run role

The following variables can be configured for this role:

run_postfix_state

⇑ Back to ToC ⇑

Determines whether the managed resources should be present or absent.

present ensures that required components, such as software packages, are installed and configured.

absent reverts changes as much as possible, such as removing packages, deleting created users, stopping services, restoring modified settings, …

• Type: str
• Required: No
• Default: "present"
• Choices: present, absent

run_postfix_autoupgrade

⇑ Back to ToC ⇑

If set to true, all managed packages will be upgraded during each Ansible run (e.g., when the package provider detects a newer version than the currently installed one).

• Type: bool
• Required: No
• Default: false

run_postfix_service_state

⇑ Back to ToC ⇑

Defines the status of the service(s). Possible values:

• enabled: Service is running and will start automatically at boot.
• disabled: Service is stopped and will not start automatically at boot.
• running: Service is running but will not start automatically at boot. This can be used to start a service on the first Ansible run without enabling it for boot.
• unmanaged: Ansible does not manage the service at all: both the running state and the boot (enablement) state are left exactly as they are. This is primarily useful when services are monitored and managed by systems other than Ansible.

The singular form (“service”) is used for simplicity. However, the defined status applies to all services if multiple are being managed by this role.

• Type: str
• Required: No
• Default: "enabled"
• Choices: enabled, disabled, running, unmanaged

run_postfix_maincf_settings

⇑ Back to ToC ⇑

Additional configuration for Postfix daemon (additional config values or to overwrite defaults from __run_postfix_maincf_settings_defaults in vars/main.yml).

Use standard Postfix option names as keys with their corresponding values.

Dictionary structure:

• Keys: Standard Postfix option names (as defined in postconf documentation)
• Values: Corresponding configuration values. Common options include:
  • myhostname: FQDN of the mail system
  • mydomain: Domain part of the FQDN
  • myorigin: Domain to append to locally posted mail
  • inet_interfaces: Network interfaces to listen on
  • inet_protocols: IP protocols to use (ipv4, ipv6, all)
  • mynetworks: Trusted SMTP clients for relay
  • If a value is a list (which can be whitespace or comma-separated in Postfix), it can also be passed as YAML list and will be converted into a comma-separated value string automatically. So all three variants are valid here to define a list as value:

    mynetworks:
    - "127.0.0.0/8"
    - "[::ffff:127.0.0.0]/104"
    - "[::1]/128"
    mynetworks: "127.0.0.0/8, [::ffff:127.0.0.0]/104, [::1]/128"
    mynetworks: "127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128"
    

Reference commands:

• postconf: print all current active values
• postconf -n: print all active, explicitly set options
• postconf -d: print all options with their default

Please note that you do not need own handler for postmap when using hash|btree|dbm: somewhere. The role’s handler is intelligent enough to scan the config for hash|btree|dbm:/path values. Just notify run_postfix: update lookup tables on changes when writing additional, own tasks.

For a complete list of options, see https://www.postfix.org/postconf.5.html

• Type: dict
• Required: No
• Default: {}

run_postfix_mastercf_settings

⇑ Back to ToC ⇑

Additional configuration for Postfix master process (master.cf). For details on the syntax of the fields/values, see the master(5) manual page (command: man 5 master or online: http://www.postfix.org/master.5.html).

Dictionary structure:

• Keys: service names (e.g., smtp, submission, 127.0.0.1:smtp, 12345)
• Values: configuration parameters for that service

By default the role only manages the standard SMTP receiving service (port 25) and the anvil helper. The message submission services submission (port 587, STARTTLS) and smtps (port 465, implicit TLS per RFC 8314) are NOT enabled by default: both require a working TLS setup (configured via run_postfix_maincf_settings, e.g. smtpd_tls_security_level, smtpd_tls_cert_file and smtpd_tls_key_file) and should enforce TLS and client authentication. Opt in to them here and pass the required per-service overrides through command_args (the daemon name followed by any -o options), as shown below. Enabling smtps without smtpd_tls_wrappermode=yes leaves port 465 unusable for conforming clients.

Example:

smtp: # Service for standard SMTP (Port 25)
  type: "inet" # Network socket type
  private: "n" # Private service
  unpriv: "-" # Unprivileged service
  chroot: "n" # Run in chroot, usually n for Postfix > v3.0.0
  wakeup: "-" # Wakeup time
  maxproc: "-" # Max processes
  command_args: "smtpd" # Command and arguments
submission: # Message submission (Port 587, STARTTLS); enforce TLS and auth:
  type: "inet"
  private: "n"
  unpriv: "-"
  chroot: "n"
  wakeup: "-"
  maxproc: "-"
  command_args: "smtpd -o smtpd_tls_security_level=encrypt -o smtpd_sasl_auth_enable=yes"
smtps: # Implicit-TLS submission (Port 465); wrappermode is mandatory here:
  type: "inet"
  private: "n"
  unpriv: "-"
  chroot: "n"
  wakeup: "-"
  maxproc: "-"
  command_args: "smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes"

• Type: dict
• Required: No
• Default: {}

run_postfix_relay_domains_manage

⇑ Back to ToC ⇑

Switch to control if relay domains settings are handled by this role.

When set to true (the default is false), the role will:

1. Create and manage a config file for relay domains using the run_postfix_relay_domains_list variable for the contents
2. Set (or override) main.cf settings for the relay_domains option accordingly.

When false, you’ll need to configure these settings manually through run_postfix_maincf_settings or through other means.

• Type: bool
• Required: No
• Default: false

run_postfix_relay_domains_list_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_relay_domains_list Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp. Will be ignored if run_postfix_relay_domains_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_relay_domains_list

⇑ Back to ToC ⇑

Relay domains for Postfix. This list of relay domains for which Postfix will accept mail for relaying to their final destinations.

Example:

- "example.com"
- "example.net"
- "example.org"
- "foo.example.org"

Will be ignored if run_postfix_relay_domains_manage is set to false.

• Type: list
• Required: No
• Default: []
• List Elements: str

run_postfix_access_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table access is controlled by dedicated settings and tasks of this role.

More information:

• https://www.postfix.org/access.5.html
• https://www.postfix.org/SMTPD_ACCESS_README.html
• https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_access_recipient_map
   • run_postfix_access_sender_map
2. Set or change main.cf settings accordingly:
   • smtpd_relay_restrictions: The role will introduce two new smtpd_restriction_classes and prepend them before all other smtpd_relay_restrictions rules:
     • recipient_access: check_recipient_access {{ run_postfix_access_recipient_map_tabletype }}:/etc/postfix/access_recipient
     • sender_access: check_sender_access {{ run_postfix_access_sender_map_tabletype }}:/etc/postfix/access_sender The explicit check_recipient_access / check_sender_access are required: a bare <type>:<path> in a restriction class inherits the recipient context of smtpd_relay_restrictions, so a sender table would be looked up by the recipient address and never match.

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_access_recipient_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the table defined by run_postfix_access_recipient_map.

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. hash and btree are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_access_manage is set to false.

• Type: str
• Required: No
• Default: "pcre"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_access_recipient_map

⇑ Back to ToC ⇑

Lookup-table access: Recipient address restriction rules.

The action values follow access(5): REJECT, DISCARD, a numeric reply, DUNNO (no decision, keep evaluating) and OK (accept now).

Security note on OK: this class is prepended before reject_unauth_destination, so an OK accepts the mail immediately and bypasses the relay guard. An OK on an unscoped pattern (e.g. /^abuse@.+/) therefore turns the server into an open relay for that pattern on ANY domain. Prefer DUNNO to allow-list without forcing acceptance (RFC 2142/5321 addresses such as postmaster@ and abuse@ are delivered as normal valid destinations anyway). Only use OK to force acceptance past other checks (RBLs, HELO checks, …), and then scope the key to the domains you actually host so it can never relay.

Examples:

## Force-accept RFC 2142 service addresses for your OWN domains, past any
## anti-spam checks, without relaying (note the anchored, domain-scoped
## pattern; requires the pcre/regexp table type):
"/^(abuse|postmaster|hostmaster)@(example\.com|example\.net)$/i": "OK"
## Do NOT do this: "/^abuse@.+/i": "OK" would relay to abuse@ on any domain.
"burned@example.com": "REJECT" # User is gone, address gets mass of spam

Will be ignored if run_postfix_access_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_access_sender_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the table defined by run_postfix_access_sender_map.

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. hash and btree are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_access_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_access_sender_map

⇑ Back to ToC ⇑

Lookup-table access: Sender address restriction rules.

More information:

• https://www.postfix.org/access.5.html
• https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes

Security note on OK: as with the recipient map, this class is prepended before reject_unauth_destination, so an OK on a sender accepts the mail regardless of destination and turns the server into an open relay for that sender. Prefer DUNNO unless you deliberately want that sender to bypass the relay guard.

Examples:

"@microsoft.com": "500 Deal with it"
"spammy@example.com": "REJECT"
"spammy2@example.com": "DISCARD" # Attention: silent drop
"important@example.net": "DUNNO" # allow-list without bypassing relay control

Will be ignored if run_postfix_access_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_aliases_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table aliases is controlled by dedicated settings and tasks of this role.

aliases can rewrite local(!) addresses (no domain part) and redirect mails to other mailboxes, files or commands:

• https://www.postfix.org/aliases.5.html
• https://www.postfix.org/local.8.html
• https://www.postfix.org/postconf.5.html#alias_database
• https://www.postfix.org/postconf.5.html#alias_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_aliases_map
2. Set (or extend) main.cf settings accordingly:
   • alias_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_aliases_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_aliases_map Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp. Will be ignored if run_postfix_aliases_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_aliases_map

⇑ Back to ToC ⇑

Lookup-table alias: address mappings.

More information:

• https://www.postfix.org/access.5.html
• https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes

Examples:

abuse: "root"
deamon123: "root, tux"
foo: "/var/spool/mail/foo"
bar: "| my_mail_script.sh"
baz: "/dev/null"
tux: "tux@example.com"
root: "admin-info@example.com, admin2@example.net"

Will be ignored if run_postfix_aliases_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_canonical_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table canonical is controlled by dedicated settings and tasks of this role.

canonical can rewrite mail addresses before mail is stored into the queue:

• https://www.postfix.org/canonical.5.html
• https://www.postfix.org/postconf.5.html#sender_canonical_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_canonical_recipient_map
   • run_postfix_canonical_sender_map
2. Set (or extend) main.cf settings accordingly:
   • sender_canonical_maps
   • recipient_canonical_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_canonical_recipient_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_canonical_recipient_map Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp. Will be ignored if run_postfix_canonical_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_canonical_recipient_map

⇑ Back to ToC ⇑

Lookup-table canonical: Recipient address mappings / rewrite rules.

Examples:

"old.name@example.com": "new.name@example.com"
"root": "user123@example.com"
"@example.com": "@example.net"

Will be ignored if run_postfix_canonical_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_canonical_sender_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_canonical_sender_map Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp. Will be ignored if run_postfix_canonical_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_canonical_sender_map

⇑ Back to ToC ⇑

Lookup-table canonical: Sender address mappings / rewrite rules.

Examples:

"old.name@example.com": "new.name@example.com"
"root": "user123@example.com"
"/.+/": "do-not-reply@example.com" # rewrite all outgoing mail addresses
"@example.com": "@example.net"

Will be ignored if run_postfix_canonical_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_generic_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table generic is controlled by dedicated settings and tasks of this role.

generic is used to rewrite sender addresses in emails leaving the system via SMTP/LMTP only:

• https://www.postfix.org/generic.5.html
• https://www.postfix.org/postconf.5.html#lmtp_generic_maps
• https://www.postfix.org/postconf.5.html#smtp_generic_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_generic_map
2. Set (or extend) main.cf settings accordingly:
   • lmtp_generic_maps
   • smtp_generic_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_generic_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_generic_map

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_generic_manage is set to false.

• Type: str
• Required: No
• Default: "pcre"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_generic_map

⇑ Back to ToC ⇑

Lookup-table ‘generic’: Sender address mappings / rewrite rules.

Examples:

"john.doe@example.local": "john.doe@example.com"
"@example.local": "contact@example.net"

Will be ignored if run_postfix_generic_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_relocated_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table relocated is controlled by dedicated settings and tasks of this role.

relocated is used to tell senders that a recipient’s address has changed. If someone tries to send email to an old address, Postfix generates a non-delivery report (NDR) with the new address (“user has moved to <new_location>” bounce messages):

• https://www.postfix.org/relocated.5.html
• https://www.postfix.org/postconf.5.html#relocated_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_relocated_map
2. Set (or extend) main.cf settings accordingly:
   • relocated_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_relocated_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_relocated_map

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_relocated_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_relocated_map

⇑ Back to ToC ⇑

Lookup-table relocated: old-address new-address-info mappings / rules.

Dictionary structure:

• Keys: Criterions / pattern to describe old addresses.
• Values: The new location, usually email addresses (or phone or other address or location strings; Postfix’s default template starts with “User has moved to " so use a fitting string). Example:

"user@example.com": "new@example.net"
"@example.com": "Sorry, all mail has to be sent to example.net"

Will be ignored if run_postfix_relocated_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_transport_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table transport is controlled by dedicated settings and tasks of this role.

transport defines the mail transport routes for Postfix, mapping domains or email addresses to specific mail delivery methods and destinations:

• https://www.postfix.org/transport.5.html
• https://www.postfix.org/postconf.5.html#transport_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_transport_map
2. Set (or extend) main.cf settings accordingly:
   • transport_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_transport_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_transport_map

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_transport_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_transport_map

⇑ Back to ToC ⇑

Domain transport mapping for Postfix. This defines where to send emails to for the listed domains in a structured format.

Dictionary structure:

• Keys: Criterions / pattern to describe domains.
• Values: Lists of destinations, usually email servers or relays. Attention: Do not forget to use square brackets to force DNS A record instead of MX record lookups. Examples:

"example.com": "lmtp:unix:/var/spool/postfix/private/lmtp-dovecot"
"example.net": "lmtp:127.0.0.1:24"
"example.org": "[192.168.0.1]"
"foo.example.org": "[mailrelay.foo.example.org]:123"
## dedicated relay for Microsoft
"/.*@(outlook|hotmail|live|msn)\..*/i": "[relay.example.com]:587"

Will be ignored if run_postfix_transport_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_virtual_manage

⇑ Back to ToC ⇑

Switch to control whether the lookup table “virtual” is controlled by dedicated settings and tasks of this role.

“virtual” defines the address mappings used by Postfix to redirect email addresses in virtual alias domains to other local or remote addresses:

• http://www.postfix.org/VIRTUAL_README.html
• https://www.postfix.org/virtual.5.html
• https://www.postfix.org/postconf.5.html#virtual_alias_domains
• https://www.postfix.org/postconf.5.html#virtual_alias_maps
• https://serverfault.com/questions/644306/confused-about-alias-maps-and-virtual-alias-maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_virtual_aliasdomains_list
   • run_postfix_virtual_alias_map
2. Set (or override or extend) main.cf settings accordingly:
   • virtual_alias_domains
   • virtual_alias_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_virtual_aliasdomains_list_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_virtual_aliasdomains_list

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_virtual_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_virtual_aliasdomains_list

⇑ Back to ToC ⇑

Virtual alias domains for Postfix. This tells Postfix to accept incoming emails for a list of virtual domains. Mappings for them are defined via run_postfix_virtual_alias_map.

Example:
  - "example.com"
  - "example.net"

Will be ignored if run_postfix_virtual_manage is set to false.

• Type: list
• Required: No
• Default: []
• List Elements: str

run_postfix_virtual_alias_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_virtual_alias_map

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_virtual_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_virtual_alias_map

⇑ Back to ToC ⇑

Virtual alias mappings for Postfix. This defines email forwarding rules in a structured format.

Dictionary structure:

• Keys: Criterions / pattern to describe the virtual address(es) Attention: Do not forget to list handled domains in run_postfix_virtual_aliasdomains_list
• Values: Lists of destinations, usually email addresses

Example:

"admin@example.com":
  - "admin@actual-destination.example.com"
"distribution@example.com":
  - "user1@actual-destination.example.com"
  - "user2@actual-destination.example.com"
  - "user3@actual-destination.example.com"
  - "user3@actual-destination.example.com"
"@example.com": # catch-all for example.com
  - "office@example.com"
"@example.net": # catch-all for example.net, rewrite all to @example.com
  - "example.com"

Will be ignored if run_postfix_virtual_manage is set to false.

• Type: dict
• Required: No
• Default: {}

run_postfix_smtp_sasl_password_manage

⇑ Back to ToC ⇑

Switch to control whether SMTP SASL password credentials are controlled by dedicated settings and tasks of this role.

They are used to authenticate Postfix when sending emails through a relay server that requires authentication:

• https://www.postfix.org/SASL_README.html#client_sasl
• https://www.postfix.org/postconf.5.html#smtp_sasl_password_maps

When set to true (the default is false), the role will:

1. Create and manage table file(s) to manage mappings. It uses variables for the contents:
   • run_postfix_smtp_sasl_password_map
2. Set (or extend) main.cf settings accordingly:
   • smtp_sasl_password_maps

When false, you’ll need to configure these settings or functionality manually through run_postfix_maincf_settings or other means.

• Type: bool
• Required: No
• Default: false

run_postfix_smtp_sasl_password_map_tabletype

⇑ Back to ToC ⇑

The lookup table type to use if for the list defined by run_postfix_smtp_sasl_password_map

Most distributions and builds dropped support for Berkeley DB with Postfix ≥ 3.9 and switched to lmdb (OpenLDAP LMDB database) which should be the best default. “hash” and “btree” are available on systems with support for Berkeley DB (and therefore deprecated / legacy now). pcre is usually faster than regexp.

Will be ignored if run_postfix_smtp_sasl_password_manage is set to false.

• Type: str
• Required: No
• Default: "lmdb"
• Choices: btree, cdb, cidr, dbm, environ, fail, hash, inline, internal, lmdb, ldap, memcache, mongodb, mysql, netinfo, nis, nisplus, pcre, pipemap, pgsql, proxy, randmap, regexp, sdbm, socketmap, sqlite, static, tcp, texthash, unionmap, unix

run_postfix_smtp_sasl_password_map

⇑ Back to ToC ⇑

SMTP SASL password credentials for Postfix. Each entry maps a remote SMTP server (and optionally a port) to a username and password.

Dictionary structure:

• Keys: Criterions, the destination to specify credentials for. Attention: If the relayhost destination is enclosed in [ and ], then you must use the same form here.
• Values: The credentials in the username:password format. Note: The main.cf setting smtp_sasl_password_result_delimiter (which defaults to :) can be used to specify an alternative separator between username and password.

Example:

"[relay.example.com]": "user:password_superSecret-c0e-400a-b683-7ae5"
"[relay.example.com]:587": "johndoe:password-69f7d34-4c-123"

will be ignored if run_postfix_smtp_sasl_password_manage is set to false.

• Type: dict
• Required: No
• Sensitive: Yes (no_log, values are masked in logs)
• Default: {}

Dependencies

See dependencies in meta/main.yml.

Compatibility

See min_ansible_version in meta/main.yml and __run_postfix_supported_platforms in vars/main.yml.

External requirements

There are no special requirements not covered by Ansible itself.