Default variable details

some of debops.opendkim default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

opendkim__config

Configuration of the opendkim__*_config variables is described in a separate document, Default variable details: opendkim__config.

opendkim__keys

The opendkim__*_keys variables define what DomainKeys are created and used by OpenDKIM. The private keys are generated on the Ansible Controller (the python-openssl package is required), stored in the secret/opendkim/domainkeys/ directory (see debops.secret role for details) and copied to the remote hosts. The role can install the same private key on multiple hosts, which can be useful in environments with multiple SMTP servers handling the same domains.

You can use the secret/opendkim/lib/extract-domainkey-zone Bash script to get the DomainKey public keys which then need to be configured in your DNS zone.

Each list element is either a string that represents the DomainKey selector for the current host domain, or a YAML dictionary with specific parameters:

name or selector
Required. The DomainKey selector used for this DomainKey.
domain
Optional. The DNS domain which will use this DomainKey. If not specified, opendkim__domain will be used by default.
size
Optional. The size of the autogenerated RSA private key. If not specified, opendkim__default_key_size will be used.
type
Optional. The private key style (rsa or dsa) which should be generated by the openssl command. Currently only rsa makes sense.
state
Optional. If not defined or present, the key will be generated on the Ansible Controller and copied to the remote hosts. If absent, key still will be generated, but it will be not copied, and existing private key will be removed from the remote hosts.

Examples

Create two DomainKeys for the current domain:

opendkim__keys:

  - 'selector1'
  - 'selector2'

They will be placed in the DNS database as:

selector1._domainkey.example.com
selector2._domainkey.example.com

Create a DomainKey for a different domain:

opendkim__keys:

  - name: 'mail'
    domain: 'example.org'

opendkim__signing_table

The opendkim__*_signing_table variables define a mapping between the contents of the From: header field in a mail message and the DomainKey used to sign the message. The format of the From: header interpreted by OpenDKIM depends on the type of the table used (see opendkim.conf(5)). The role by default maps the entire domain, without specifying any users.

Each list entry is a YAML dictionary with specific parameters:

name or selector
Required. Specify the DomainKey selector to use for a given signing table entry.
from
Required. Specify the contents of the From: header used to lookup the DomainKey. By default you should use only domain names here, otherwise you need to reconfigure the SigningTable configuration option. See opendkim.conf(5) for details.
domain
Optional. The DNS domain used to lookup the DomainKey for a given signing table entry. If not specified, the opendkim__domain value is used by default.
subdomains
Optional, boolean. If True, the from value will be added again with a leading dot (.), which signifies that subdomains of a given domain should also be signed. By default subdomains are not signed.
state
Optional. if not specified or present, a given entry will be included in the signing table. If absent, a given entry will not be included in the configuration.

Examples

Sign mails from a given domain and its subdomains with the default DomainKey:

opendkim__signing_table:

  - name: 'mail'
    from: 'example.org'
    domain: '{{ ansible_domain }}'
    subdomains: True

opendkim__trusted_hosts

The opendkim__*_trusted_hosts variables are YAML lists which contain IP addresses, CIDR subnets and hostnames of "trusted hosts". These hosts will be stored in the /etc/opendkim/dkimkeys/TrustedHosts file which is by default used in the OpenDKIM configuration by the InternalHosts and ExternalIgnoreList options. Mail messages from these hosts will be automatically signed rather than verified by OpenDKIM.

Examples

Trust localhost and a given subnet:

opendkim__trusted_hosts:

  - 'localhost'
  - '127.0.0.1'
  - '::1'
  - '192.0.2.0/24'
  - '2001:db8::/32'