DEBOPS.AVAHI(5)

NAME
debops.avahi - configure Avahi service using Ansible

SYNOPSIS

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

DESCRIPTION

Avahi <https://www.avahi.org/> is a Linux daemon which can be used to publish information about local or remote services using Multicast DNS <https://en.wikipedia.org/wiki/Multicast_DNS> protocol (mDNS, also used by Bonjour or ZeroConf). This protocol can then be queried by other applications such as DNS clients or those that support DNS Service Discovery <https://en.wikipedia.org/wiki/Zero-configuration_networking#Service_discovery> to find out and access services on the local network.

The debops.avahi Ansible role can be used to configure the Avahi service on Debian or Ubuntu hosts. You can create custom services, publish static host entries that point to other hosts on the local network, or even define and publish CNAME records pointing to the host itself via a custom script.

GETTING STARTED

  Default configuration

By default the debops.avahi role publishes records for the SSH and SFTP services, as well as a special device-info record which marks the server as a "file server" on supported platforms. The workstation and hinfo records are not published to indicate that this host is a server and not a client machine.

  Avahi CNAME (alias) support

Avahi by default does not support CNAME records, i.e. alternative subdomains that point to a given host. To support these records, debops.avahi can install and configure a custom third party script, avahi-alias <https://github.com/george-hawkins/avahi-aliases-notes> maintained by George Hawkins <https://github.com/george-hawkins>.

The script will be installed by default if the Python 2.7 support is enabled on the host. At present (2019), Debian does not include the python3-avahi package, therefore Python 2.7 is required for this functionality to work.

The role will install the script in the /usr/local/sbin/ directory and prepare a systemd service (SysVinit is not supported at this time). The script needs to be restarted to register any changed CNAME records and this is not automatic unlike Avahi daemon itself (role restarts the service on any changes).

The list of CNAME records is stored in the /etc/avahi/aliases file and can be modified by other roles or manually. The file should contain only CNAME FQDN records, each in one line; comments are not supported.

  Avahi services in other Ansible roles

The debops.avahi Ansible role is designed to be used as a role dependency of another Ansible role. By specifying the service configuration using the avahi__dependent_services variable (preferably as a YAML list) you can configure Avahi services as well as CNAME aliases if necessary. See avahi__services for more details about supported parameters.

If advanced control over CNAME aliases published by Avahi is not needed, you can make the process simpler by including the tasks that configure an Avahi service directly in your own role, for example:

---
- name: Ensure that Avahi directories exist
  file:
    path: '/etc/avahi/services'
    state: 'directory'
    mode: '0755'
- name: Generate Avahi service configuration
  template:
    src: 'etc/avahi/services/application.xml.j2'
    dest: '/etc/avahi/services/application.xml'
    mode: '0644'
- name: Add mDNS CNAME resource record for the application
  lineinfile:
    path: '/etc/avahi/aliases'
    regexp: '^application\.local$'
    line: 'application.local'
    state: 'present'
    create: True
    mode: '0644'

Avahi daemon automatically detects changes in the /etc/avahi/services/ directory and reloads all files, therefore service restart is not necessary. The format of the XML service file can be found in the avahi.service(5) <https://manpages.debian.org/avahi.service(5)> manual page.

  Example inventory

The debops.avahi role needs to be enabled to be used in the DebOps playbook. To do that, add the hosts that you want to configure Avahi on to the [debops_service_avahi] Ansible inventory group:

[debops_service_avahi]
hostname

  Example playbook

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

---
- name: Manage Avahi service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_avahi' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::avahi' ]
      python__dependent_packages3:
        - '{{ avahi__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ avahi__python__dependent_packages2 }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ avahi__ferm__dependent_rules }}'
    - role: avahi
      tags: [ 'role::avahi', 'skip::avahi' ]
    - role: nsswitch
      tags: [ 'role::nsswitch', 'skip::nsswitch' ]

DEFAULT VARIABLE DETAILS

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

  avahi__daemon_conf

The avahi__daemon_conf_* variables are used to specify what parameters should be present in the /etc/avahi/avahi-daemon.conf configuration file. Each pair of variables manages one section of the INI file. The "default" variable is combined with the custom variable therefore it's possible to change the value of a parameter without the need to copy the entire variable over to the Ansible inventory.

Each variable is a YAML dictionary with keys representing the available parameters and values representing the parameter values. You can use boolean YAML values (True, False) to specify yes or no values, as well as strings and numbers. if a value is an empty string, the corresponding parameter will be commented out in the finished configuration file.

See the avahi-daemon.conf(5) <https://manpages.debian.org/avahi-daemon.conf(5)> manual page for information about recognized parameters and their meaning.

  avahi__services

The avahi__*_services variables define the services published by Avahi on its .local domain. The variables are either YAML dictionaries or YAML lists of dictionaries that are combined together in the avahi__combined_services in the order they appear in the defaults/main.yml file.

Each entry in the avahi__*_services variables is a YAML dictionary with specific parameters:

filename
    Name of the configuration file that holds the service details. The name will be used in the file path in the format:

    /etc/avahi/services/<filename>.service

    If the filename is not specified and the main variable uses the YAML dictionary format, the dictionary key will be used as the filename. The examples below are equivalent:

    avahi__services:
      'example-service':
        name: 'Example service on %h'
        type: '_example._tcp'
        port: '1234'
    avahi__host_services:
      - filename: 'example-service'
        name: 'Example service on %h'
        type: '_example._tcp'
        port: '1234'

services
    Optional. A YAML list of services defined by this entry and encloses in a service group. Each list item is a YAML dictionary that specifies given service parameters. If the services parameter is not specified, role will automatically generate one based on parameters defined in the main entry. This parameter is only useful in applications that define multiple services, which can be defined together in a service group, otherwise you can use the simpler syntax.

type
    A string similar to DNS SRV Records which defines the service type and protocol (only the service name and protocol are relevant, other parts of the SRV record shouldn't be used). Example service types are _ssh._tcp and _http._tcp.

    If the type is not specified and a given entry has no separate services list defined, the service will not be published. This can be used to define host CNAME entries without an associated service (see below).

subtype
    Optional. Either a string, or a YAML list of additional subtypes to publish for this service. Example subtype definition: _custom._sub._example._tcp.

port
    Optional. Specify the port number on which a given service listens for new connections. If it's not specified, the port number for this service will be set to 0.

name
    Optional. Custom description of a service, displayed in compatible Avahi clients. If not specified, the host's hostname will be used instead.

replace_wildcards
    Optional, boolean. If not defined or True, Avahi will replace the %h wildcard in the service description with the host's hostname. Setting this parameter to False will turn off the replacement.

protocol
    Optional. Specify which network to publish the service on, either IPv4, IPv6 or both (default). Possible values: ipv4, ipv6, any.

domain or domain_name
    Optional. Publish the service on a different domain than the default .local domain used by Avahi.

fqdn or hostname or host_name
    Optional. Specify a different FQDN for a given service. This can be used to publish services on behalf of other hosts on the network that do not support Avahi themselves. You also need to register the host A/AAAA record separately for the Avahi to correctly publish the service record. See avahi__hosts for more details.

txt or txt_record
    Optional. String or YAML list of custom TXT records which should be published for this service. These records are used to provide additional information about the service, configuration options, etc.

    The parameters below are additional and related to the role itself, rather than to the Avahi services:

comment
    Optional. String or YAML text block with additional comments included in the service configuration file.

state
    Optional. If not specified or present, the Avahi service will be configured. If absent, the configuration of a given Avahi service will be removed.

cname
    Optional. Specify a custom CNAME record which will be used to register a host alias using the avahi-alias script. The CNAME record will point to the originating host. See Avahi CNAME (alias) support for more details. You can define avahi__*_services entries that only publish CNAME records by not specifying a type, for example:

    avahi__services:
      - filename: 'custom-cname-of-host'
        cname: 'custom'
    avahi__host_services:
      'other-example':
        cname: 'other.local'

cname_state
    Optional. If the cname parameter is specified, you can use this parameter to control the state of the CNAME record separately from the main state parameter. If not specified or present, the CNAME record will be published. If absent, the CNAME record will be removed.

AUTHOR
Maciej Delmanowski

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