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
orselector
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 ofopenssl_privatekey
module. It should be set tonever
orfail
when keys are managed externally. If not specified it is set tofull_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
ordsa
) which should be generated by the openssl command. Currently onlyrsa
makes sense.state
Optional. If not defined or
present
, the key will be generated on the Ansible Controller and copied to the remote hosts. Ifabsent
, 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
orselector
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 theSigningTable
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
, thefrom
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. Ifabsent
, 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'