.. _opendkim__ref_defaults_detailed:

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.

.. contents::
   :local:
   :depth: 1


opendkim__config
----------------

Configuration of the ``opendkim__*_config`` variables is described in a separate
document, :ref:`opendkim__ref_config`.


.. _opendkim__ref_keys:

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
:file:`secret/opendkim/domainkeys/` directory (see :ref:`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 :file:`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,
  :envvar:`opendkim__domain` will be used by default.

``size``
  Optional. The size of the autogenerated RSA private key. If not specified,
  :envvar:`opendkim__default_key_size` will be used.

``type``
  Optional. The private key style (``rsa`` or ``dsa``) which should be generated
  by the :command:`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:

.. code-block:: yaml

   opendkim__keys:

     - 'selector1'
     - 'selector2'

They will be placed in the DNS database as:

.. code-block:: none

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

Create a DomainKey for a different domain:

.. code-block:: yaml

   opendkim__keys:

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


.. _opendkim__ref_signing_table:

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 :man:`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
  :man:`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 :envvar:`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:

.. code-block:: yaml

   opendkim__signing_table:

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


.. _opendkim__ref_trusted_hosts:

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 :file:`/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:

.. code-block:: yaml

   opendkim__trusted_hosts:

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