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, 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.

regenerate

Optional, supported since Ansible 2.10. Value passed to regenerate parameter of openssl_privatekey module. It should be set to never or fail when keys are managed externally. If not specified it is set to full_idempotence.

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'