Getting started
===============

Default configuration
---------------------

This role provides a hopefully reasonable Postfix configuration for a SMTP
server on the public Internet. It does not configure Postfix directly; instead,
the configuration variables are passed to the :ref:`debops.postfix` Ansible role
which combines them with the other configuration specified by other Ansible
roles and generates the final Postfix configuration files. You should check the
:ref:`debops.postfix` documentation for explanation of how the configuration is
structured and what are the supported parameters.


.. _postconf__ref_capabilities:

Postfix "capabilities"
----------------------

To allow easier management of different configuration options, they are enabled
conditionally by "capabilities", a list of keywords either autogenerated by the
role conditionally, or set by the user in the Ansible inventory. The list is
inclusive; if you want to disable a particular autogenerated feature, you can
override the :envvar:`postconf__autodetect_capabilities` variable through
Ansible inventory.

Supported Postfix capabilities and their effects:

``auth``
  Autodetected. Enabled, if role finds out Ansible local facts defined by the
  ``debops.dovecot`` or ``debops.saslauthd`` Ansible roles, which indicates
  that the SASL Auth facilities are available on the host.

  This capability will enable SMTP authentication support via either Dovecot or
  Cyrus SASL library, preferred in that order. The ``submission`` and ``smtps``
  Postfix services will be enabled, with corresponding firewall configuration
  that allows access from any host, by default.


``authcleanup``
  When enabled, the ``submission`` and ``smtps`` Postfix services will check
  the headers of incoming mail messages and apply filtering rules specified by
  the :file:`/etc/postfix/auth_header_checks.pcre` lookup table. This can be
  used to sanitize authenticated mail messages before they are sent to the
  external SMTP servers.


``deprecated``
  When enabled, the role will configure Postfix features and services that are
  considered as deprecated.


``overhead``
  Enabled by default. Add a `custom header <http://www.gnuterrypratchett.com/>`_
  to every message that passes through this system.


``public-mx-required``
  Autodetected. Enabled if a host has a public IPv4 or IPv6 address, with
  assumption that the host will receive mail messages from public Internet
  servers.

  This capability will enable HELO and sender checks which will verify that
  a given HELO domain or sender domain MX host has a public IP address.
  Otherwise, mail messages directed to this MX won't be deliverable, therefore
  it's better to reject the messages early.


``unauth-sender``
  Autodetected. Enabled by default when ``auth`` capability is enabled.

  With this capability, Postfix will check the sender e-mail addresses against
  a list of its own domains. If any messages are sent from these domains
  unauthenticated, they will be rejected.

  With auhenticated mail, Postfix will check the sender address against the
  mail user database defined in the ``smtpd_sender_login_maps`` lookup tables.
  If the sender address does not belong to the authenticated user, mail will be
  rejected. This requires configuration of an user database, for example using
  the :ref:`debops.postldap` role.


Example inventory
-----------------

To apply the Postfix configuration provided by the ``debops.postconf`` role on
a host, it needs to be present in the ``[debops_service_postconf]`` Ansible
inventory group. You also need to enable :ref:`debops.postfix` support, as well as
any other additional roles that can be autodetected by ``debops.postconf``
role.

.. code-block:: none

   [debops_service_postfix]
   hostname

   [debops_service_postconf]
   hostname

   [debops_service_saslauthd]
   hostname

   [debops_service_dovecot]
   hostname


Example playbook
----------------

If you are using this role without DebOps, here's an example Ansible playbook
that uses the ``debops.postconf`` role:

.. literalinclude:: ../../../../ansible/playbooks/service/postconf.yml
   :language: yaml
