resolvconf

Table of Contents

1. Description
2. Setup - The basics of getting started with resolvconf
   • Beginning with resolvconf
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

Module for managing resolv.conf on RedHat and Ubuntu based systems

Setup

Beginning with resolvconf

include resolvconf is enough to get you up and running with the module if you would like a default setup using Google’s resolvers and the $::domain fact as the search domain.

Usage

All parameters are available in the main resolvconf class. See the common usages below for examples.

Configure a default resolv.conf with Google nameservers as the $::domain fact as the search path

include ::resolvconf

Pass in parameters for which nameservers to use

class { ‘::resolvconf’:
  dns => [‘8.8.8.8’, ‘1.1.1.1’],
}

Pass in nameservers plus domains for the search path

class { ‘::resolvconf’:
  dns     => [‘8.8.8.8’, ‘8.8.4.4’],
  domains => [‘domain.tld’, ‘sub.domain.tld’],
}

Reference

Classes

Public classes

• resolvconf: Main class, includes all other classes

Private classes

• resolvconf::config: Handles the configuration of resolv.conf
• resolvconf::service: Handles the resolvconf service for debian based systems
• resolvconf::install: Handles package installation for debian based systems

Parameters

dns

Optional.

Data type: Array

Allows you to specify an array of nameservers to use in resolv.conf. Default value: [‘8.8.8.8’, ‘1.1.1.1’]

domains

Optional.

Data type: Array

Allows you to specify an array of domains to include in the search path in resolv.conf. Default value: [$::domain]

use_local

Optional.

Data type: Boolean

Allows you to use a local nameserver such as named/bind. Will set a nameserver entry of 127.0.0.1 as the first entry in resolv.conf if not using systemd-resolved. Will set 127.0.0.53 if using systemd-resolved. Default value: true

fallback_dns

Optional.

Data type: Array

Specify additional fallback nameservers to use in systemd-resolved configuration. Default value is an empty array.

options

Optional.

Specify options to place in /etc/resolv.conf such as ndots:5. Default value is an empty array. Only usable when use_systemd_resolved is false as systemd-resolved does not support configuring options.

Limitations

This module has only been tested on the following distros:

• Ubuntu
  • 22.04
  • 24.04
• CentOS 8
• RHEL 9

This module uses a custom Hiera 5 backend and requires at least Puppet 4.9 due to this.

Development

If you would like to contribute to the module, fork it and create a pull request when you're satisfied with your changes.

Reference

Table of Contents

Classes

• resolvconf: Manage resolv.conf configuration
• resolvconf::config: Class to configure the resolv.conf file. This class should not be called directly.
• resolvconf::install: resolvconf::install Class to install resolvconf package on Debian based systems resolvconf::install Class to install resolvconf package on
• resolvconf::service: Class for managing the systemd-resolved service

Classes

resolvconf

resolvconf

Main class for managing resolv.conf

This module configures DNS resolution via systemd-resolvedor directly manages /etc/resolv.conf

Examples

using systemd-resolved and defaults

include resolvconf

Directly managing /etc/resolv.conf

class { 'resolvconf':
  use_systemd_resolved => false,
  use_local            => false,
  dns                  => ['8.8.8.8', '1.1.1.1'],
  domains              => ['example.com'],
  options              => ['ndots:5'],
}

Using hiera configuration

include resolvconf

hiera config:
  resolvconf::use_systemd_resolved: true
  resolvconf::use_local: true
  resolvconf::dns: ['8.8.8.8', '1.1.1.1']

Parameters

The following parameters are available in the resolvconf class:

• dns
• domains
• use_local
• options
• use_systemd_resolved
• fallback_dns
• dns_stub_listener_extra

dns

Data type: Array[Variant[String, Float], 1]

Array containing the nameservers to put in resolv.conf (default: ['8.8.8.8','1.1.1.1'])

domains

Data type: Array[String, 1]

The domains to include in the search line in resolv.conf

use_local

Data type: Boolean

Whether to use a local DNS listener for systemd-resolved or local dns service (default: true)

options

Data type: Array[String]

Array containing the options to put in resolv.conf. Not applicable when use_systemd_resolved is true

use_systemd_resolved

Data type: Boolean

Use systemd-resolved for managing resolv.conf

fallback_dns

Data type: Array[Variant[String, Float]]

allback_dns [Array[Variant[String, Float]] Array containing fallback nameservers to put in resolv.conf Default value is an empty array.

dns_stub_listener_extra

Data type: Array[Variant[String, Float]]

ns_stub_listener_extra [Array[Variant[String, Float]] An array of strings or floats, with at least one element, representing additional DNS stub listener configurations. Default value is an empty array.

resolvconf::config

resolvconf::config

Parameters

The following parameters are available in the resolvconf::config class:

• use_systemd_resolved
• use_local
• dns
• fallback_dns
• dns_stub_listener_extra
• domains
• options

use_systemd_resolved

Data type: Boolean

Use systemd-resolved for managing resolv.conf

Default value: $resolvconf::use_systemd_resolved

use_local

Data type: Boolean

Use local DNS resolver

Default value: $resolvconf::use_local

dns

Data type: Array[Variant[String, Float], 1]

List of DNS servers

Default value: $resolvconf::dns

fallback_dns

Data type: Array[Variant[String, Float]]

allback_dns [Array[Variant[String, Float]] List of fallback DNS servers

Default value: $resolvconf::fallback_dns

dns_stub_listener_extra

Data type: Array[Variant[String, Float]]

ns_stub_listener_extra [Array[Variant[String, Float]] Extra DNS stub listener options

Default value: $resolvconf::dns_stub_listener_extra

domains

Data type: Array[String, 1]

List of search domains

Default value: $resolvconf::domains

options

Data type: Array[String]

List of resolver options to add to resolv.conf

Default value: $resolvconf::options

resolvconf::install

resolvconf::install

Class to install resolvconf package on Debian based systems resolvconf::install

Class to install resolvconf package on Debian based systems

Parameters

The following parameters are available in the resolvconf::install class:

• use_systemd_resolved

use_systemd_resolved

Data type: Boolean

Boolean to determine if systemd-resolved should be used

Default value: $resolvconf::use_systemd_resolved

resolvconf::service

resolvconf::service

A description of what this class does

Parameters

The following parameters are available in the resolvconf::service class:

• use_systemd_resolved

use_systemd_resolved

Data type: Boolean

Determine if systemd-resolved should be used

Default value: $resolvconf::use_systemd_resolved

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.0

Features

• Add support for Puppet 6
• Add support for Ubuntu 18.04 & Ubuntu 20.04

Removed Features

• Remove support for Ubuntu 14.04

Release 0.1.0

Features

• Initial featureset and management of resolv.conf

Bugfixes

Known Issues