DEBOPS.RESOLVCONF(5)

NAME
debops.resolvconf - Configure systemw-wide DNS resolver via Ansible

SYNOPSIS

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

DESCRIPTION

The /etc/resolv.conf configuration file defines the system-wide DNS resolver configuration. It is a central location to configure the DNS nameservers, search domains and other options. In modern Linux systems, many services might want to change that configuration file to enable their functionality - NetworkManager <https://wiki.debian.org/NetworkManager>, ifupdown, dnsmasq <https://wiki.debian.org/HowTo/dnsmasq>, unbound being several examples of that.

To avoid clashes between various software packages modifying the /etc/resolv.conf file, the resolvconf package provides a stable API to the /etc/resolv.conf that combines information from other services and creates a consistent resolver configuration.

The debops.resolvconf Ansible role further updates the resolvconf configuration to fix issues with outdated defaults on modern Debian/Ubuntu hosts. By default the role will update the interface order list to include the Predictable Network Interface Names <https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/> as well as clarify the order of the NetworkManager interfaces. The role will also automatically rearrange the configuration of VPN tunnels if a local DNS resolver is detected.

Contrary to its name, the debops.resolvconf role does not configure the /etc/resolv.conf file directly. You should consult the documentation of various DNS-related services to see how you can modify the contents of this file through them.

GETTING STARTED

  Support for static configuration

In addition to handling DNS configuration from multiple sources, the role supports "static" DNS configuration created via a script. To use it, set the resolvconf__static_enabled variable to True, and specify the resolv.conf(5) <https://manpages.debian.org/resolv.conf(5)> configuration as a string or YAML text block:

resolvconf__static_content: |
  nameserver 192.0.2.1
  search example.org example.net

The script will create a file in the resolvconf runtime directory, by default named lo.static, which will merge the specified configuration with other DNS sources. The role will also configure systemd to apply the static configuration on system boot.

  Example inventory

The debops.resolvconf role is included by default in the common.yml DebOps playbook; you don't need to add hosts to any Ansible groups to enable it.

  Example playbook

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

---
- name: Manage system-wide DNS resolver configuration
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_resolvconf' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: resolvconf
      tags: [ 'role::resolvconf', 'skip::resolvconf' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::resolvconf
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.resolvconf Ansible role:

•   Manual pages: resolvconf(8) <https://manpages.debian.org/resolvconf(8)>, resolv.conf(5) <https://manpages.debian.org/resolv.conf(5)>

•   The resolv.conf <https://wiki.debian.org/resolv.conf> Debian Wiki page

•   Local DNS resolvers available in DebOps: debops.dnsmasq, debops.unbound

DEFAULT VARIABLE DETAILS

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

  resolvconf__interface_order

The resolvconf__*_interface_order variables define the contents of the /etc/resolvconf/interface-order configuration file - see the interface-order(5) <https://manpages.debian.org/interface-order(5)> manual page for details about this file.

  Examples

See the resolvconf__original_interface_order default variable to see the original contents of the configuration file represented in the role. The resolvconf__default_interface_order variable contains the modifications to the original configuration file defined in the role by default and enabled conditionally.

  Syntax

The contents of the resolvconf__*_interface_order variables are a list of YAML dictionaries, each dictionary defines a section of the configuration file using specific parameters:

name
    Required. A name of a given section, used only as a handle for a given configuration entry. Multiple entries with the same name parameter are merged together and can affect a given entry in order of appearance.

value
    Required. A string or a YAML text block which will be inserted in the generated configuration file. See the interface-order(5) <https://manpages.debian.org/interface-order(5)> for details about what can be defined here.

comment
    Optional. A string or YAML text block with additional comments about a given configuration entry.

state
    Optional. If not specified or present, a given configuration section will be included in the generated configuration file. If absent, a configuration section will be removed from the generated configuration file. If ignore, a given configuration entry will not be evaluated by the role during its execution.

copy_id_from
    Optional. Name of a configuration entry (its name parameter) from which a given entry should copy its internal "id" value. This can be used to roughly place a given configuration entry near the specified configuration section without the need to modify the order of all of the other entries.

weight
    Optional. A positive or negative number which defines an additional "weight" of a given entry relative to other configuration entries. This parameter can be used to fine-tune the order of the configuration sections in the generated configuration file.

AUTHOR
Maciej Delmanowski

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