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 maintained by George Hawkins.

To enable this functionality, set in the Ansible inventory:

avahi__alias_enabled: True

The role will download the script source code, install it 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 simplier by including the tasks that configure an Avahi service directly in your own role, for example:


- name: Ensure that Avahi directories exist
    path: '/etc/avahi/services'
    state: 'directory'
    owner: 'root'
    group: 'root'
    mode: '0755'

- name: Generate Avahi service configuration
    src: 'etc/avahi/services/application.xml.j2'
    dest: '/etc/avahi/services/application.xml'
    owner: 'root'
    group: 'root'
    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) 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:


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
  hosts: [ 'debops_service_avahi' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'


    - role: debops.ferm
      tags: [ 'role::ferm' ]
        - '{{ avahi__ferm__dependent_rules }}'

    - role: debops.avahi
      tags: [ 'role::avahi' ]

    - role: debops.nsswitch
      tags: [ 'role::nsswitch' ]