resolv_conf

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with resolv_conf
   • What resolv_conf affects
   • Setup requirements
   • Beginning with resolv_conf
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Development - Guide for contributing to the module

Overview

Manage the /etc/resolv.conf on Linux and FreeBSD.

Module Description

The module manages the DNS resolver configuration file. It allows setting the values for the nameserver, search, sortlist and options configuration settings. The following restrictions are enforced by the module:

• Up to 3 name servers may be listed.
• Up to 6 items may be included in the search list.
• Up to 10 items may be included in the sortlist.

Setup

What resolv_conf affects

The module creates and manages the content of the /etc/resolv.conf file. This affects the way the host is able to map hostname to IP addresses and vice versa.

Setup Requirements

The module uses the Puppet stdlib module.

Beginning with resolv_conf

Declare the class to create a configuration that uses only a local name server on 127.0.0.1.

class { 'resolv_conf': }

Usage

You can use class parameters to use a customized configuration.

class { 'resolv_conf':
  nameservers => [ '9.9.9.9', ],
}

You can also use Hiera to create this configuration.

resolv_conf::nameservers:
  - '9.9.9.9'

Specify a remote name server and use local domain for unqualified hostnames

The following configuration will configure a remote name server and use the name of the local domain when unqualified hostnames are queried.

class { 'resolv_conf':
  nameservers => [ '9.9.9.9', ],
  searchlist  => [ $facts['networking']['domain'] ],
}

If your host is based in the example.net domain, then a lookup for the hostname server will query the name server for server.example.net.

Specify name servers & options

This setup creates a configuration file with the given name servers and will also set additional options to enable name server rotation and set a specific timeout.

class { 'resolv_conf':
  nameservers => [ '8.8.8.8', '8.8.4.4', ],
  options     => [ 'rotate', 'timeout:2', ],
}

Prefer a local name server

The following setup will create a configuration where the name server at 127.0.0.1 is queried first and only then the additional name servers are used.

class { 'resolv_conf':
  nameservers              => [ '8.8.8.8', '8.8.4.4', ],
  prepend_local_nameserver => true,
}

Note: This module does not configure a local name server that will answer queries on 127.0.0.1. You will have to use a different Puppet module to manage the name server.

Reference

See REFERENCE.md

Development

You may open Github issues for this module if you need additional options currently not available.

Feel free to send pull requests for new features.

Reference

Table of Contents

Classes

• resolv_conf: Manage the DNS resolver configuration file /etc/resolv.conf

Classes

resolv_conf

Manage the DNS resolver configuration file /etc/resolv.conf

Examples

Create resolver config file using default parameters

class { resolv_conf': }

Create resolver config file with specific name servers

class { resolv_conf':
  nameservers => [ '8.8.8.8', '8.8.4.4', ],
}

Create resolver config file with specific name servers & options

class { resolv_conf':
  nameservers => [ '8.8.8.8', '8.8.4.4', ],
  options     => [ 'rotate', 'timeout:2, ],
}

Create resolver config file where a local name server is prefered

class { resolv_conf':
  nameservers              => [ '8.8.8.8', '8.8.4.4', ],
  prepend_local_nameserver => true,
}

Parameters

The following parameters are available in the resolv_conf class:

• nameservers
• domainname
• searchlist
• sortlist
• options
• prepend_local_nameserver
• resolv_conf_file
• owner
• group
• mode

nameservers

Data type: Array[String,0,3]

An array of name servers that the resolver should query for hostname lookups. A maximum number of three name servers can be specified. The default value is a single element array containing 127.0.0.1.

domainname

Data type: Optional[String]

A string that is used as a single element searchlist. The parameter is obsolete and will be removed.

Default value: undef

searchlist

Data type: Array[String]

An array of domains that the resolver will search. This parameter cannot be used together with domainname. The old restriction of six entries has been removed. Check your documentation if your operating system release supports more than six items.

Default value: []

sortlist

Data type: Array[String,0,10]

An array of up to 10 IP/netmask items. These are used by the resolver to sort the result in case multiple addresses are returned.

Default value: []

options

Data type: Array[String]

An array of option settings for the resolver. Each array element must be the option to include in the configuration. The following options are recognized: ndots:n, timeout:n, attempts:n, debug, edns0, inet6, ip6-bytestring, ip6-dotint, no-ip6-dotint, no-check-names, rotate, single-request, single-request-reopen. The first three options are expected to use a numeric value for n after the colon. Check the man page resolv.conf(5) for details.

Default value: []

prepend_local_nameserver

Data type: Boolean

A boolean value that determines if a local DNS server should be used first. Setting this parameter to true will add 127.0.0.1 before the servers given as nameservers. The last name server is silently ignored if this would create a configuration with more than three servers. The default value is false.

Default value: false

resolv_conf_file

Data type: Stdlib::Absolutepath

The absolute path of the file to manage. The default is /etc/resolv.conf. In general it does not make sense to change this parameter.

owner

Data type: Optional[String]

The owner of the file /etc/resolv.conf. The default is root.

Default value: undef

group

Data type: Optional[String]

The group of the file /etc/resolv.conf. The default is root on Linux and wheel on FreeBSD.

Default value: undef

mode

Data type: Optional[Stdlib::Filemode]

The file mode of the file /etc/resolv.conf. The default is 0644.

Default value: undef

2023-07-06 - Release 3.0.0

Breaking changes

• Drop Support for Puppet 6

Enhancements

• Add support for Puppet 8
• Add support for Stdlib 9.x

2023-01-31 - Release 2.2.0

Enhancements

• The parameter searchlist allows more than six entries now. The restriction has been removed in glib 2.26. Check the documentation of your operating system release if you can benefit from this enhancement.

Breaking changes

• The domain directive has been obsoleted. A single item search list will be used if the class parameter domainname is set. The parameter will be removed in a future release of the module.

2021-08-27 - Release 2.1.2

Enhancements

• Allow stdlib 8.0.0

2021-07-09 - Release 2.1.1

Enhancements

• Fixed typos.

2021-03-04 - Release 2.1.0

Enhancements

• Add support for Puppet 7.
• Add support for Stdlib 7.x.

2019-09-27 - Release 2.0.0

Breaking changes

• Remove support for Puppet 4.

Enhancements

• Add support for Stdlib 6.x.

2019-02-23 - Release 1.2.0

Add documentation in the REFERENCE.md file.

2018-10-14 - Release 1.1.0

Summary

Support Puppet 6 and Stdlib 5.x

2018-06-28 - Release 1.0.2

Summary

Convert to Puppet PDK and update README.

2018-04-08 - Release 1.0.1

Summary

Update version requirements.

2018-03-24 - Release 1.0.0

Summary

Initial release.