avahi

Table of Contents

1. Description
2. Setup - The basics of getting started with avahi
   • Beginning with avahi
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module manages Avahi for mDNS/DNS-SD services.

RHEL/CentOS, Ubuntu, Debian and OpenBSD are supported using Puppet 5 or later.

Setup

Beginning with avahi

In the very simplest case, you can just include the following:

include dbus
include avahi

Usage

Install Avahi and add static service definitions for SSH and SFTP:

include dbus
include avahi

avahi::service { 'ssh':
  description       => '%h',
  replace_wildcards => true,
  services          => [
    {
      'type' => '_ssh._tcp',
      'port' => 22,
    },
  ],
}

avahi::service { 'sftp-ssh':
  description       => '%h',
  replace_wildcards => true,
  services          => [
    {
      'type' => '_sftp-ssh._tcp',
      'port' => 22,
    },
  ],
}

Install Avahi and add a static host entry on behalf of an mDNS-unaware router:

include dbus
include avahi

avahi_host { 'router.local':
  ensure => present,
  ip     => '192.0.2.1',
}

Reference

The reference documentation is generated with puppet-strings and the latest version of the documentation is hosted at https://bodgit.github.io/puppet-avahi/ and available also in the REFERENCE.md.

Limitations

This module has been built on and tested against Puppet 5 and higher.

The module has been tested on:

• Red Hat/CentOS Enterprise Linux 6/7/8
• Ubuntu 16.04/18.04/20.04
• Debian 9/10
• OpenBSD 6.9

Development

The module relies on PDK and has both rspec-puppet and Litmus tests. Run them with:

$ bundle exec rake spec
$ bundle exec rake litmus:*

Please log issues or pull requests at github.

Reference

Table of Contents

Classes

• avahi: Installs and configures Avahi.
• avahi::config
• avahi::daemon
• avahi::install
• avahi::params

Defined types

• avahi::service: Statically define a service in Avahi.

Resource types

• avahi_host: Manages an Avahi host entry.

Data types

• Avahi::Domain
• Avahi::Record

Classes

avahi

Installs and configures Avahi.

• See also
  • puppet_defined_types::avahi::service
    • avahi::service

Examples

Declaring the class

include dbus
include avahi

Parameters

The following parameters are available in the avahi class:

• conf_dir
• dtd_dir
• group
• package_name
• policy_group
• service_name
• user
• validate
• xmllint
• add_service_cookie
• allow_interfaces
• allow_point_to_point
• browse_domains
• cache_entries_max
• check_response_ttl
• clients_max
• deny_interfaces
• disable_publishing
• disable_user_service_publishing
• disallow_other_stacks
• domain_name
• enable_dbus
• enable_reflector
• enable_wide_area
• entries_per_entry_group_max
• host_name
• objects_per_client_max
• publish_aaaa_on_ipv4
• publish_a_on_ipv6
• publish_addresses
• publish_dns_servers
• publish_domain
• publish_hinfo
• publish_resolv_conf_dns_servers
• publish_workstation
• ratelimit_burst
• ratelimit_interval_usec
• reflect_ipv
• rlimit_as
• rlimit_core
• rlimit_data
• rlimit_fsize
• rlimit_nofile
• rlimit_nproc
• rlimit_stack
• use_iff_running
• use_ipv4
• use_ipv6

conf_dir

Data type: Stdlib::Absolutepath

The top-level configuration directory, usually /etc/avahi.

Default value: $avahi::params::conf_dir

dtd_dir

Data type: Stdlib::Absolutepath

The directory containing the XML DTD for service validation.

Default value: $avahi::params::dtd_dir

group

Data type: String

The unprivileged group used to run the daemon.

Default value: $avahi::params::group

package_name

Data type: String

The name of the package.

Default value: $avahi::params::package_name

policy_group

Data type: String

The group that is allowed by policy to set the mDNS hostname.

Default value: $avahi::params::policy_group

service_name

Data type: String

The service name.

Default value: $avahi::params::service_name

user

Data type: String

The unprivileged user used to run the daemon.

Default value: $avahi::params::user

validate

Data type: Boolean

Whether to try and validate service files prior to installing them.

Default value: $avahi::params::validate

xmllint

Data type: Stdlib::Absolutepath

The path to the xmllint binary used to validate service files.

Default value: $avahi::params::xmllint

add_service_cookie

Data type: Optional[Boolean]

Whether a unique cookie is added to all locally registered services.

Default value: undef

allow_interfaces

Data type: Optional[Array[String, 1]]

Interfaces to allow mDNS traffic on.

Default value: undef

allow_point_to_point

Data type: Optional[Boolean]

Include Point-to-Point interfaces.

Default value: undef

browse_domains

Data type: Optional[Array[Bodgitlib::Domain, 1]]

Additional browse domains.

Default value: $avahi::params::browse_domains

cache_entries_max

Data type: Optional[Integer[0]]

How many entries are cached per interface.

Default value: undef

check_response_ttl

Data type: Optional[Boolean]

Whether to check the TTL of mDNS packets.

Default value: undef

clients_max

Data type: Optional[Integer[0]]

Maximum number of D-Bus clients permitted.

Default value: undef

deny_interfaces

Data type: Optional[Array[String, 1]]

Interfaces to explicitly deny mDNS traffic on.

Default value: undef

disable_publishing

Data type: Optional[Boolean]

Disable publishing of any records.

Default value: undef

disable_user_service_publishing

Data type: Optional[Boolean]

Disable publishing of records by user applications.

Default value: undef

disallow_other_stacks

Data type: Optional[Boolean]

Whether to allow other mDNS stacks to run on the host.

Default value: undef

domain_name

Data type: Optional[String]

Override the domain name used, .local normally.

Default value: undef

enable_dbus

Data type: Optional[Boolean]

Whether to connect to D-Bus.

Default value: undef

enable_reflector

Data type: Optional[Boolean]

Whether to enable the mDNS reflector.

Default value: undef

enable_wide_area

Data type: Optional[Boolean]

Enable wide-area mDNS.

Default value: $avahi::params::enable_wide_area

entries_per_entry_group_max

Data type: Optional[Integer[0]]

The maximum number of entries to be registered by a single D-Bus client.

Default value: undef

host_name

Data type: Optional[String]

Override the hostname used for the local machine.

Default value: undef

objects_per_client_max

Data type: Optional[Integer[0]]

The maximum number of objects to be registered by a single D-Bus client.

Default value: undef

publish_aaaa_on_ipv4

Data type: Optional[Boolean]

Whether to publish AAAA records via IPv4.

Default value: undef

publish_a_on_ipv6

Data type: Optional[Boolean]

Whether to publish A records via IPv6.

Default value: undef

publish_addresses

Data type: Optional[Boolean]

Whether to publish mDNS address records for all local IP addresses.

Default value: undef

publish_dns_servers

Data type: Optional[Array[Stdlib::IP::Address::NoSubnet, 1]]

List of unicast DNS servers to publish in mDNS.

Default value: undef

publish_domain

Data type: Optional[Boolean]

Whether to announce the local domain name for browsing by other hosts.

Default value: undef

publish_hinfo

Data type: Optional[Boolean]

Whether to publish HINFO records on all interfaces.

Default value: $avahi::params::publish_hinfo

publish_resolv_conf_dns_servers

Data type: Optional[Boolean]

Whether to publish the DNS servers listed in /etc/resolv.conf in addition to any listed in publish_dns_servers.

Default value: undef

publish_workstation

Data type: Optional[Boolean]

Whether to publish a workstation record for the local machine.

Default value: $avahi::params::publish_workstation

ratelimit_burst

Data type: Optional[Integer[0]]

Per-interface packet rate-limiting burst parameter.

Default value: $avahi::params::ratelimit_burst

ratelimit_interval_usec

Data type: Optional[Integer[0]]

Per-interface packet rate-limiting interval parameter.

Default value: $avahi::params::ratelimit_interval_usec

reflect_ipv

Data type: Optional[Boolean]

Whether to reflect between IPv4 and IPv6.

Default value: undef

rlimit_as

Data type: Optional[Integer[0]]

Value in bytes for RLIMIT_AS.

Default value: undef

rlimit_core

Data type: Optional[Integer[0]]

Value in bytes for RLIMIT_CORE.

Default value: $avahi::params::rlimit_core

rlimit_data

Data type: Optional[Integer[0]]

Value in bytes for RLIMIT_DATA.

Default value: $avahi::params::rlimit_data

rlimit_fsize

Data type: Optional[Integer[0]]

Value for RLIMIT_FSIZE.

Default value: $avahi::params::rlimit_fsize

rlimit_nofile

Data type: Optional[Integer[0]]

Value for RLIMIT_NOFILE.

Default value: $avahi::params::rlimit_nofile

rlimit_nproc

Data type: Optional[Integer[2]]

Default value: $avahi::params::rlimit_nproc

rlimit_stack

Data type: Optional[Integer[0]]

Default value: $avahi::params::rlimit_stack

use_iff_running

Data type: Optional[Boolean]

Default value: undef

use_ipv4

Data type: Optional[Boolean]

Default value: $avahi::params::use_ipv4

use_ipv6

Data type: Optional[Boolean]

Default value: $avahi::params::use_ipv6

avahi::config

The avahi::config class.

avahi::daemon

The avahi::daemon class.

avahi::install

The avahi::install class.

avahi::params

The avahi::params class.

Defined types

avahi::service

Statically define a service in Avahi.

• See also
  • puppet_classes::avahi
    • avahi
  • https://linux.die.net/man/5/avahi.service
    • avahi.service(5)

Examples

Add static service definitions for SSH and SFTP

include dbus
include avahi

avahi::service { 'ssh':
  description       => '%h',
  replace_wildcards => true,
  services          => [
    {
      'type' => '_ssh._tcp',
      'port' => 22,
    },
  ],
}

avahi::service { 'sftp-ssh':
  description       => '%h',
  replace_wildcards => true,
  services          => [
    {
      'type' => '_sftp-ssh._tcp',
      'port' => 22,
    },
  ],
}

Add a static service definition for NFS on IPv6 only

include dbus
include avahi

avahi::service { 'nfs':
  description       => 'NFS on %h',
  replace_wildcards => true,
  services          => [
    {
      'type'       => '_nfs._tcp',
      'port'       => 2049,
      'protocol'   => 'ipv6',
      'txt-record' => [
        'path=/export/some/path',
      ],
    },
  ],
}

Advertise an AirPrint printer

include dbus
include avahi

avahi::service { 'printer':
  description => 'An AirPrint printer',
  services    => [
    {
      'type'       => '_ipp._tcp',
      'subtype'    => [
        '_universal._sub._ipp._tcp',
      ],
      'port'       => 631,
      'txt-record' => [
        'txtver=1',
        'qtotal=1',
        'rp=printers/aPrinter',
        'ty=aPrinter',
        'adminurl=http://198.0.2.1:631/printers/aPrinter',
        'note=Office Laserjet 4100n',
        'priority=0',
        'product=(GPL Ghostscript)',
        'printer-state=3',
        'printer-type=0x801046',
        'Transparent=T',
        'Binary=T',
        'Fax=F',
        'Color=T',
        'Duplex=T',
        'Staple=F',
        'Copies=T',
        'Collate=F',
        'Punch=F',
        'Bind=F',
        'Sort=F',
        'Scan=F',
        'pdl=application/octet-stream,application/pdf,application/postscript,image/jpeg,image/png,image/urf',
        'URF=W8,SRGB24,CP1,RS600',
      ],
    },
  ],
}

Parameters

The following parameters are available in the avahi::service defined type:

• description
• services
• replace_wildcards
• service

description

Data type: String

The description of the service, any occurence of %h will be replaced with the hostname if $replace_wildcards is set to true.

services

Data type: Array[Avahi::Record, 1]

An array of hashes which must contain type and port keys and optionally protocol, subtype, domain-name, host-name and txt-record keys.

replace_wildcards

Data type: Optional[Boolean]

Whether any occurence of %h is replaced with the hosname.

Default value: undef

service

Data type: String

The name of the service. It is used to construct the filename, i.e. ${conf_dir}/services/${service}.service.

Default value: $title

Resource types

avahi_host

Manages an Avahi host entry.

Examples

Add a static host entry on behalf of an mDNS-unaware router

include ::dbus
include ::avahi

avahi_host { 'router.local':
  ensure => present,
  ip     => '192.0.2.1',
}

Properties

The following properties are available in the avahi_host type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

ip

The IP address of the host, either IPv4 or IPv6.

Parameters

The following parameters are available in the avahi_host type.

• name
• provider
• target

name

namevar

The host name.

provider

The specific backend to use for this avahi_host resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

target

The file in which to store the settings, defaults to /etc/avahi/hosts.

Default value: /etc/avahi/hosts

Data types

Avahi::Domain

The Avahi::Domain data type.

Alias of

Pattern[/(?x) ^ ( (?= [a-z0-9._-]{2,255} ) ( (?= [a-z0-9_-]{1,63} \. ) _ [a-z0-9]+ ( - [a-z0-9]+ )* \. )+ _ [a-z]{2,62} ) $/]

Avahi::Record

The Avahi::Record data type.

Alias of

Struct[{'type' => Avahi::Domain, 'port' => Integer[0, 65535], Optional['protocol'] => Enum['ipv4', 'ipv6', 'any'], Optional['subtype'] => Array[Avahi::Domain], Optional['domain-name'] => String, Optional['host-name'] => Bodgitlib::Domain, Optional['txt-record'] => Array[String]}]

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v3.0.0 (2021-06-18)

Full Changelog

Changed

• Convert to Litmus #11 (bodgit)
• Bump dependencies and drop old Puppet versions #10 (bodgit)

Added

• Convert to Hiera #12 (bodgit)
• Convert to PDK #9 (bodgit)

v2.0.1 (2017-11-08)

Full Changelog

v2.0.0 (2017-01-26)

Full Changelog

v1.0.0 (2016-08-25)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator