DEBOPS.ETC_ALIASES(5)

NAME
debops.etc_aliases - Manage /etc/aliases database using Ansible

SYNOPSIS

debops run service/etc_aliases [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The /etc/aliases file contains the mail alias database used by the various SMTP daemons to redirect local mail to remote recipients, local files, commands, etc. See the aliases(5) <https://manpages.debian.org/aliases(5)> for more details.

This role can be used to set the contents of the alias database, either using Ansible inventory variables, or as a dependency of another Ansible role.

GETTING STARTED

  Default configuration

The role forwards the root mail to a set of e-mail administrator accounts defined by the debops.core Ansible role (see that role's documentation for more details). If they are not defined, the mail will be forwarded to root@<domain> for convenience.

The role creates the staff mail alias which by default is forwarded to root. If you have separate team for IT Operations and Helpdesk, you might want to consider changing this, or some other aliases to forward mail elsewhere. To do that, you can define in the inventory:

etc_aliases__recipients:
  # Forward staff mail to specific users
  - staff: [ 'example1', 'example2' ]
  - example1: 'user1@example.com'
  - example2: 'user2@example.com'

See the etc_aliases__recipients for more details about the configuration format.

  Support for the RFC 2142

The RFC 2142 <https://datatracker.ietf.org/doc/html/rfc2142.html>: Mailbox Names For Common Services and Functions defines a set of mailboxes (or aliases) that are recommended to exist on any DNS domain to allow easy communication between organizations. This role defines these recommended mail aliases by default for convenience. You can disable this by setting the variable:

etc_aliases__rfc2142_compliant: False

Alternatively, you can change the default mail recipients for the created aliases using the normal configuration mechanism described above.

  Example inventory

To configure debops.etc_aliases on a given remote host, it needs to be added to [debops_service_etc_aliases] Ansible inventory group:

[debops_service_etc_aliases]
hostname

  Example playbook

Here's a minimal example playbook that can be used to manage the /etc/aliases file:

---
- name: Manage /etc/aliases database
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_etc_aliases' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare etc_aliases environment
      ansible.builtin.import_role:
        name: 'etc_aliases'
        tasks_from: 'main_env'
      tags: [ 'role::etc_aliases', 'role::secret' ]
  roles:
    - role: secret
      tags: [ 'role::secret', 'role::etc_aliases' ]
      secret__directories:
        - '{{ etc_aliases__secret__directories }}'
    - role: etc_aliases
      tags: [ 'role::etc_aliases', 'skip::etc_aliases' ]

The playbook is shipped with this role under docs/playbooks/etc_aliases.yml from which you can symlink it to your playbook directory.

USAGE AS A ROLE DEPENDENCY

The debops.etc_aliases role can be used as a dependency by other Ansible roles to manage contents of the /etc/aliases file idempotently. Configuration options from multiple roles can be merged together and included in the alias database, or removed conditionally.

  Dependent role variable

The role exposes the etc_aliases__dependent_recipients variable which can be used to define mail aliases and recipients by other Ansible roles through the role dependent variables.

The variable is a YAML list with YAML dictionaries as entries. A short format of the configuration uses the dictionary key as a name of the dependent role and dictionary value as that role's configuration, in the format defined by etc_aliases__recipients variable (see playbook excerpt below):

roles:
  - role: debops.etc_aliases
    etc_aliases__dependent_recipients:
      - role_name: '{{ role_name__etc_aliases__dependent_recipients }}'

The extended version of the configuration uses a YAML dictionary with specific parameters:

role
    Required. Name of the role, used to save its configuration in a YAML dictionary on the Ansible Controller. Shouldn't be changed once selected, otherwise the configuration will be desynchronized.

config
    Required. YAML list with configuration of the aliases and recipients in the same format defined by etc_aliases__recipients variable.

state
    Optional. If not specified or present, the configuration will be included in the generated alias database. If absent, the configuration will be removed from the alias database. If ignore, a given configuration entries will be skipped during alias evaluation and won't affect any existing entries.

    An example extended configuration (playbook excerpt):

    roles:
      - role: debops.etc_aliases
        etc_aliases__dependent_recipients:
          - role: 'role_name'
            config: '{{ role_name__etc_aliases__dependent_recipients }}'

    The above configuration layout allows for use of the multiple role dependencies in one playbook by providing configuration of each role in a separate configuration entry.

  Dependent configuration storage and retrieval

The dependent configuration from other roles is stored in the secret/ directory on the Ansible Controller (see debops.secret for more details) in a JSON file, with each role configuration in a separate dictionary. The debops.etc_aliases role reads this file when Ansible local facts indicate that the /etc/aliases file is configured, otherwise a new empty file is created. This ensures that the stale configuration is not present on a new or re-installed host.

The YAML dictionaries from different roles are be merged with the main configuration in the etc_aliases__combined_recipients variable that is used to generate the final configuration. The merge order of the different etc_aliases__*_recipients variables allows to further affect the dependent configuration through Ansible inventory if necessary, therefore the Ansible roles that use this method don't need to provide additional variables for this purpose themselves.

  Example role default variables

---
# This is a set of default variables in an example 'application' role that uses
# dependent variables to pass configuration to 'debops.etc_aliases' role.
# /etc/aliases mail recipients defined by the application
application__etc_aliases__dependent_recipients:
  - name: 'application'
    dest: [ 'user1', 'user2' ]

  Example role playbook

---
# This is a playbook for an example 'application' role which uses
# 'debops.etc_aliases' as a dependency and passes its own set of
# configuration options to it.
- name: Manage application
  collections: [ 'debops.debops' ]
  hosts: [ 'debops_service_application' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare etc_aliases environment
      ansible.builtin.import_role:
        name: 'etc_aliases'
        tasks_from: 'main_env'
      tags: [ 'role::etc_aliases', 'role::secret' ]
  roles:
    - role: secret
      tags: [ 'role::secret', 'role::etc_aliases' ]
      secret__directories:
        - '{{ etc_aliases__secret__directories }}'
    - role: etc_aliases
      tags: [ 'role::etc_aliases' ]
      etc_aliases__dependent_recipients:
        # Short form of dependent configuration
        - application: '{{ application__etc_aliases__dependent_recipients }}'
        # Alternavie form of dependent configuration
        - role: 'application'
          config: '{{ application__etc_aliases__dependent_recipients }}'
          state: 'present'
    - role: application
      tags: [ 'role::application' ]

DEFAULT VARIABLE DETAILS

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

  etc_aliases__recipients

The etc_aliases__*_recipients variables define mail aliases and their recipients which should be present in the /etc/aliases file. Each variable is a YAML list with dictionaries as the entries. Multiple entries that define the same mail alias are combined together in order of appearance.

Each entry can be a YAML dictionary with a dictionary key being the alias to define, and dictionary value being a string with one recipient, or a YAML list of recipients to set for a given alias:

etc_aliases__recipients:
  - root: 'admin'
  - admin: [ 'user1', 'user2' ]

The more complex version uses a set of parameters that allow greater control over a particular alias:

name, alias
    The mail alias to configure.

dest, to
    Required. The string or an YAML list of recipients for a given mail alias.

add_dest, add_to, cc, bcc
    Optional. A string or an YAML list of recipients to add to existing list of recipients. This is useful in subsequent entries to modify the list of recipients if necessary.

del_dest, del_to
    Optional. A string or an YAML list of recipients to remove from the existing list of recipients. This is useful in subsequent entries to modify the list of recipients if necessary.

comment
    Optional. A string or YAML text block with a comment added to a particular alias.

state
    Optional. If not specified or present, a given alias entry will be defined in the database file.

    If absent, the alias will not be included in the database file.

    If hidden, the entry itself won't be included, but the optional comment will be in the file.

    If comment, the entry will be present in the database file, but commented out.

section
    Optional. Name of the section in the database file in which a given alias should be included. If not specified, the unknown section is used automatically.

weight
    Optional. A numeric value which is used to sort the entries in the final database file. The entries with higher numbers have bigger "weight" and will be put lower in the file. Negative numbers can be used to put the entries higher than normal. If not specified, a default 0 will be set.

  Examples

Create a set of aliases:

etc_aliases__recipients:
  - name: 'root'
    dest: 'admin'
  - alias: 'admin'
    to: [ 'user1', 'user2' ]
  - alias: 'admin'
    cc: 'user3'

  etc_aliases__sections

The /etc/aliases file is managed using informal "sections", each section groups the common mail aliases. The etc_aliases__sections contains a list of sections defined by YAML dictionaries with specific parameters:

name
    Required. Short name of the section, used in the alias configuration parameters to put the aliases in a particular section.

title
    Optional. A short description of the section included as its header.

state
    Optional. If not specified or present, the section will be added in the database file. If absent, the section will not be included in the file.

  Examples

Define a set of alias sections:

etc_aliases__sections:
  - name: 'general'
    title: 'General-purpose mail aliases'
  - name: 'admin'
    title: 'Administrator mail aliases'
  - name: 'unknown'
    title: 'Other mail aliases'

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others