Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 28. Managing global DNS configuration in IdM using Ansible playbooks

Configure global DNS settings using the freeipa.ansible_freeipa.dnsconfig Ansible module, including forwarders and forwarding policies that apply to all Identity Management (IdM) DNS servers.

The dnsconfig module supports the following variables:

  • The global forwarders, specifically their IP addresses and the port used for communication.
  • The global forwarding policy: only, first, or none. For more details on these types of DNS forward policies, see DNS forward policies in IdM.

  • The synchronization of forward lookup and reverse lookup zones.

    NOTE
    Global configuration has lower priority than the configuration for a specific IdM DNS zone.

28.1. Prerequisites
Copy link

Understand how Identity Management (IdM) configures NetworkManager to preserve DNS settings in /etc/resolv.conf on DHCP networks.

Installing IdM with integrated DNS configures the /etc/resolv.conf file to point to the 127.0.0.1 localhost address: 

# Generated by NetworkManager
search idm.example.com
nameserver 127.0.0.1
Copy to Clipboard Toggle word wrap

In certain environments, such as networks that use Dynamic Host Configuration Protocol (DHCP), the NetworkManager service may revert changes to the /etc/resolv.conf file. To make the DNS configuration persistent, the IdM DNS installation process also configures the NetworkManager service in the following way:

  1. The DNS installation script creates an /etc/NetworkManager/conf.d/zzz-ipa.conf NetworkManager configuration file to control the search order and DNS server list: 

    # auto-generated by IPA installer
[main]
dns=default

[global-dns]
searches=$DOMAIN

[global-dns-domain-*]
servers=127.0.0.1
    Copy to Clipboard Toggle word wrap
  2. The NetworkManager service is reloaded, which always creates the /etc/resolv.conf file with the settings from the last file in the /etc/NetworkManager/conf.d/ directory. This is in this case the zzz-ipa.conf file.
Important

Do not modify the /etc/resolv.conf file manually.

Add a global DNS forwarder to Identity Management (IdM) using Ansible to resolve queries for domains outside your IdM DNS zones.

In the example below, the IdM administrator ensures the presence of a DNS global forwarder with an Internet Protocol (IP) v4 address of 7.7.9.9 and IP v6 address of 2001:db8::1:0 on port 53.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/
    Copy to Clipboard Toggle word wrap

  2. Make a copy of the forwarders-absent.yml Ansible playbook file from the relevant collections directory and rename it. For example: 

    $ cp /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig/forwarders-absent.yml ensure-presence-of-a-global-forwarder.yml
    Copy to Clipboard Toggle word wrap
  3. Open the ensure-presence-of-a-global-forwarder.yml file for editing.

  4. Adapt the file by setting the following variables:

    1. Change the name variable for the playbook to Playbook to ensure the presence of a global forwarder in IdM DNS.
    2. In the tasks section, change the name of the task to Ensure the presence of a DNS global forwarder to 7.7.9.9 and 2001:db8::1:0 on port 53.

    3. In the forwarders section of the freeipa.ansible_freeipa.ipadnsconfig portion:

      1. Change the first ip_address value to the IPv4 address of the global forwarder: 7.7.9.9.
      2. Change the second ip_address value to the IPv6 address of the global forwarder: 2001:db8::1:0.
      3. Verify the port value is set to 53.

    4. Change the state to present.

      This the modified Ansible playbook file for the current example: 

    ---
- name: Playbook to ensure the presence of a global forwarder in IdM DNS
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure the presence of a DNS global forwarder to 7.7.9.9 and 2001:db8::1:0 on port 53
    freeipa.ansible_freeipa.ipadnsconfig:
      forwarders:
        - ip_address: 7.7.9.9
        - ip_address: 2001:db8::1:0
          port: 53
      state: present
    Copy to Clipboard Toggle word wrap

  5. Save the file.

    For details about all variables used in the playbook, see the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/README-dnsconfig.md file on the control node.

  6. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file ensure-presence-of-a-global-forwarder.yml
    Copy to Clipboard Toggle word wrap

Remove a global DNS forwarder from Identity Management (IdM) using Ansible when decommissioning external DNS servers or changing your forwarding configuration.

In the example procedure below, the IdM administrator ensures the absence of a DNS global forwarder with an Internet Protocol (IP) v4 address of 8.8.6.6 and IP v6 address of 2001:4860:4860::8800 on port 53.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/
    Copy to Clipboard Toggle word wrap

  2. Make a copy of the forwarders-absent.yml Ansible playbook file from the relevant collections directory and rename it. For example: 

    $ cp /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig/forwarders-absent.yml ensure-absence-of-a-global-forwarder.yml
    Copy to Clipboard Toggle word wrap
  3. Open the ensure-absence-of-a-global-forwarder.yml file for editing.

  4. Adapt the file by setting the following variables:

    1. Change the name variable for the playbook to Playbook to ensure the absence of a global forwarder in IdM DNS.
    2. In the tasks section, change the name of the task to Ensure the absence of a DNS global forwarder to 8.8.6.6 and 2001:4860:4860::8800 on port 53.

    3. In the forwarders section of the freeipa.ansible_freeipa.ipadnsconfig portion:

      1. Change the first ip_address value to the IPv4 address of the global forwarder: 8.8.6.6.
      2. Change the second ip_address value to the IPv6 address of the global forwarder: 2001:4860:4860::8800.
      3. Verify the port value is set to 53.
    4. Set the action variable to member.
    5. Verify the state is set to absent.

    This the modified Ansible playbook file for the current example: 

    ---
- name: Playbook to ensure the absence of a global forwarder in IdM DNS
  hosts: ipaserver

  vars_files:
  - /home/user_name/MyPlaybooks/secret.yml
  tasks:
  - name: Ensure the absence of a DNS global forwarder to 8.8.6.6 and 2001:4860:4860::8800 on port 53
    freeipa.ansible_freeipa.ipadnsconfig:
      forwarders:
        - ip_address: 8.8.6.6
        - ip_address: 2001:4860:4860::8800
          port: 53
      action: member
      state: absent
    Copy to Clipboard Toggle word wrap
    Important

    If you only use the state: absent option in your playbook without also using action: member, the playbook fails.

  5. Save the file.

    For details about all variables used in the playbook, see the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/README-dnsconfig.md file on the control node.

  6. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file ensure-absence-of-a-global-forwarder.yml
    Copy to Clipboard Toggle word wrap

Review examples showing when action: member is needed with the ipadnsconfig module for managing global forwarders in Identity Management (IdM) using Ansible.

Excluding global forwarders in IdM by using the ansible-freeipa ipadnsconfig module requires using the action: member option in addition to the state: absent option. If you only use state: absent in your playbook without also using action: member, the playbook fails. Consequently, to remove all global forwarders, you must specify all of them individually in the playbook. In contrast, the state: present option does not require action: member.

The following table provides configuration examples for both adding and removing DNS global forwarders that demonstrate the correct use of the action: member option. The table shows, in each line:

  • The global forwarders configured before executing a playbook
  • An excerpt from the playbook
  • The global forwarders configured after executing the playbook
Expand
Table 28.1. ipadnsconfig management of global forwarders
Forwarders beforePlaybook excerptForwarders after

8.8.6.6 

[...]
tasks:
- name: Ensure the presence of DNS global forwarder 8.8.6.7
  ipadnsconfig:
    forwarders:
      - ip_address: 8.8.6.7
    state: present
Copy to Clipboard Toggle word wrap

8.8.6.7

8.8.6.6 

[...]
tasks:
- name: Ensure the presence of DNS global forwarder 8.8.6.7
  ipadnsconfig:
    forwarders:
      - ip_address: 8.8.6.7
    action: member
    state: present
Copy to Clipboard Toggle word wrap

8.8.6.6, 8.8.6.7

8.8.6.6, 8.8.6.7 

[...]
tasks:
- name: Ensure the absence of DNS global forwarder 8.8.6.7
  ipadnsconfig:
    forwarders:
      - ip_address: 8.8.6.7
    state: absent
Copy to Clipboard Toggle word wrap

Trying to execute the playbook results in an error. The original configuration - 8.8.6.6, 8.8.6.7 - is left unchanged.

8.8.6.6, 8.8.6.7 

[...]
tasks:
- name: Ensure the absence of DNS global forwarder 8.8.6.7
  ipadnsconfig:
    forwarders:
      - ip_address: 8.8.6.7
    action: member
    state: absent
Copy to Clipboard Toggle word wrap

8.8.6.6

28.6. DNS forward policies in IdM
Copy link

Understand the DNS forward policy types in Identity Management (IdM) and how they determine whether queries are forwarded, resolved locally, or treated as non‑existent.

IdM supports the first and only standard BIND forward policies, as well as the none IdM-specific forward policy.

Forward first (default)
The IdM BIND service forwards DNS queries to the configured forwarder. If a query fails because of a server error or timeout, BIND falls back to the recursive resolution using servers on the Internet. The forward first policy is the default policy, and it is suitable for optimizing DNS traffic.
Forward only
The IdM BIND service forwards DNS queries to the configured forwarder. If a query fails because of a server error or timeout, BIND returns an error to the client. The forward only policy is recommended for environments with split DNS configuration.
None (forwarding disabled)
DNS queries are not forwarded with the none forwarding policy. Disabling forwarding is only useful as a zone-specific override for global forwarding configuration. This option is the IdM equivalent of specifying an empty list of forwarders in BIND configuration.
Note

You cannot use forwarding to combine data in IdM with data from other DNS servers. You can only forward queries for specific subzones of the primary zone in IdM DNS.

By default, the BIND service does not forward queries to another server if the queried DNS name belongs to a zone for which the IdM server is authoritative. In such a situation, if the queried DNS name cannot be found in the IdM database, the NXDOMAIN answer is returned. Forwarding is not used.

Example 28.1. Example Scenario

The IdM server is authoritative for the test.example. DNS zone. BIND is configured to forward queries to the DNS server with the 192.0.2.254 IP address.

When a client sends a query for the nonexistent.test.example. DNS name, BIND detects that the IdM server is authoritative for the test.example. zone and does not forward the query to the 192.0.2.254. server. As a result, the DNS client receives the NXDomain error message, informing the user that the queried domain does not exist.

Set the global DNS forwarding policy to forward first in Identity Management (IdM) using Ansible, which tries forwarders first then falls back to recursive resolution.

The forward first policy is the default policy. It is suitable for traffic optimization. If a query fails because of a server error or timeout, BIND falls back to the recursive resolution using servers on the Internet.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • Your IdM environment contains an integrated DNS server.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/
    Copy to Clipboard Toggle word wrap

  2. Make a copy of the set-configuration.yml Ansible playbook file from the relevant collections directory and rename it. For example: 

    $ cp /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig/set-configuration.yml set-forward-policy-to-first.yml
    Copy to Clipboard Toggle word wrap
  3. Open the set-forward-policy-to-first.yml file for editing.

  4. Adapt the file by setting the following variables in the freeipa.ansible_freeipa.ipadnsconfig task section:

    • Indicate that the value of the ipaadmin_password variable is defined in the secret.yml Ansible vault file.

    • Set the forward_policy variable to first.

      Delete all the other lines of the original playbook that are irrelevant. This is the modified Ansible playbook file for the current example: 

    ---
- name: Playbook to set global forwarding policy to first
  hosts: ipaserver
  become: true

  tasks:
  - name: Set global forwarding policy to first.
    freeipa.ansible_freeipa.ipadnsconfig:
      ipaadmin_password: "{{ ipaadmin_password }}"
      forward_policy: first
    Copy to Clipboard Toggle word wrap

  5. Save the file.

    For details about variables and example playbooks in the FreeIPA Ansible collection, see the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/README-dnsconfig.md file and the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig directory on the control node.

  6. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file set-forward-policy-to-first.yml
    Copy to Clipboard Toggle word wrap

Disable global DNS forwarding in Identity Management (IdM) using Ansible to force the server to use recursive resolution instead.

Disabling forwarding is only useful as a zone-specific override for global forwarding configuration. This option is the IdM equivalent of specifying an empty list of forwarders in BIND configuration.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • Your IdM environment contains an integrated DNS server.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/
    Copy to Clipboard Toggle word wrap

  2. Make a copy of the disable-global-forwarders.yml Ansible playbook file from the relevant collections directory. For example: 

    $ cp /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig/disable-global-forwarders.yml disable-global-forwarders-copy.yml
    Copy to Clipboard Toggle word wrap
  3. Open the disable-global-forwarders-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the freeipa.ansible_freeipa.ipadnsconfig task section:

    • Indicate that the value of the ipaadmin_password variable is defined in the secret.yml Ansible vault file.

    • Set the forward_policy variable to none.

      This is the modified Ansible playbook file for the current example: 

    ---
- name: Playbook to disable global DNS forwarders
  hosts: ipaserver
  become: true

  tasks:
  - name: Disable global forwarders.
    freeipa.ansible_freeipa.ipadnsconfig:
      ipaadmin_password: "{{ ipaadmin_password }}"
      forward_policy: none
    Copy to Clipboard Toggle word wrap

  5. Save the file.

    For details about variables and example playbooks in the FreeIPA Ansible collection, see the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/README-dnsconfig.md file and the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig directory on the control node.

  6. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory disable-global-forwarders-copy.yml
    Copy to Clipboard Toggle word wrap

Disable automatic synchronization between forward and reverse DNS zones in Identity Management (IdM) using Ansible for independent zone management.

Prerequisites

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.15 or later.
    • You have installed the ansible-freeipa package.
    • The example assumes that in the ~/MyPlaybooks/ directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server.
    • The example assumes that the secret.yml Ansible vault stores your ipaadmin_password and that you have access to a file that stores the password protecting the secret.yml file.
  • The target node, that is the node on which the freeipa.ansible_freeipa module is executed, is part of the IdM domain as an IdM client, server or replica.
  • Your IdM environment contains an integrated DNS server.

Procedure

  1. Navigate to the ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/
    Copy to Clipboard Toggle word wrap

  2. Make a copy of the disallow-reverse-sync.yml Ansible playbook file from the relevant collections directory. For example: 

    $ cp /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig/disallow-reverse-sync.yml disallow-reverse-sync-copy.yml
    Copy to Clipboard Toggle word wrap
  3. Open the disallow-reverse-sync-copy.yml file for editing.

  4. Adapt the file by setting the following variables in the freeipa.ansible_freeipa.ipadnsconfig task section:

    • Indicate that the value of the ipaadmin_password variable is defined in the secret.yml Ansible vault file.

    • Set the allow_sync_ptr variable to no.

      This is the modified Ansible playbook file for the current example: 

    ---
- name: Playbook to disallow reverse record synchronization
  hosts: ipaserver
  become: true

  tasks:
  - name: Disallow reverse record synchronization.
    freeipa.ansible_freeipa.ipadnsconfig:
      ipaadmin_password: "{{ ipaadmin_password }}"
      allow_sync_ptr: no
    Copy to Clipboard Toggle word wrap

  5. Save the file.

    For details about variables and example playbooks in the FreeIPA Ansible collection, see the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/README-dnsconfig.md file and the /usr/share/ansible/collections/ansible_collections/freeipa/ansible_freeipa/playbooks/dnsconfig directory on the control node.

  6. Run the playbook: 

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file disallow-reverse-sync-copy.yml
    Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top