Chapter 3. Using Ansible playbooks to manage IdM DNS zones

As Identity Management (IdM) administrator, you can manage how IdM DNS zones work using the dnszone module available in the ansible-freeipa package.

Prerequisites

3.1. Supported DNS zone types

Identity Management (IdM) supports two types of DNS zones: primary and forward zones. These two types of zones are described here, including an example scenario for DNS forwarding.

Note

This guide uses the BIND terminology for zone types which is different from the terminology used for Microsoft Windows DNS. Primary zones in BIND serve the same purpose as forward lookup zones and reverse lookup zones in Microsoft Windows DNS. Forward zones in BIND serve the same purpose as conditional forwarders in Microsoft Windows DNS.

Primary DNS zones

Primary DNS zones contain authoritative DNS data and can accept dynamic DNS updates. This behavior is equivalent to the type master setting in standard BIND configuration. You can manage primary zones using the ipa dnszone-* commands.

In compliance with standard DNS rules, every primary zone must contain start of authority (SOA) and nameserver (NS) records. IdM generates these records automatically when the DNS zone is created, but you must copy the NS records manually to the parent zone to create proper delegation.

In accordance with standard BIND behavior, queries for names for which the server is not authoritative are forwarded to other DNS servers. These DNS servers, so called forwarders, may or may not be authoritative for the query.

Example 3.1. Example scenario for DNS forwarding

The IdM server contains the test.example. primary zone. This zone contains an NS delegation record for the sub.test.example. name. In addition, the test.example. zone is configured with the 192.0.2.254 forwarder IP address for the sub.text.example subzone.

A client querying the name nonexistent.test.example. receives the NXDomain answer, and no forwarding occurs because the IdM server is authoritative for this name.

On the other hand, querying for the host1.sub.test.example. name is forwarded to the configured forwarder 192.0.2.254 because the IdM server is not authoritative for this name.

Forward DNS zones

From the perspective of IdM, forward DNS zones do not contain any authoritative data. In fact, a forward "zone" usually only contains two pieces of information:

  • A domain name
  • The IP address of a DNS server associated with the domain

All queries for names belonging to the domain defined are forwarded to the specified IP address. This behavior is equivalent to the type forward setting in standard BIND configuration. You can manage forward zones using the ipa dnsforwardzone-* commands.

Forward DNS zones are especially useful in the context of IdM-Active Directory (AD) trusts. If the IdM DNS server is authoritative for the idm.example.com zone and the AD DNS server is authoritative for the ad.example.com zone, then ad.example.com is a DNS forward zone for the idm.example.com primary zone. That means that when a query comes from an IdM client for the IP address of somehost.ad.example.com, the query is forwarded to an AD domain controller specified in the ad.example.com IdM DNS forward zone.

3.2. Configuration attributes of primary IdM DNS zones

Identity Management (IdM) creates a new zone with certain default configuration, such as the refresh periods, transfer settings, or cache settings. In IdM DNS zone attributes, you can find the attributes of the default zone configuration that you can modify using one of the following options:

Along with setting the actual information for the zone, the settings define how the DNS server handles the start of authority (SOA) record entries and how it updates its records from the DNS name server.

Table 3.1. IdM DNS zone attributes

Attributeansible-freeipa variableDescription

Authoritative name server

name_server

Sets the domain name of the primary DNS name server, also known as SOA MNAME.

By default, each IdM server advertises itself in the SOA MNAME field. Consequently, the value stored in LDAP using --name-server is ignored.

Administrator e-mail address

admin_email

Sets the email address to use for the zone administrator. This defaults to the root account on the host.

SOA serial

serial

Sets a serial number in the SOA record. Note that IdM sets the version number automatically and users are not expected to modify it.

SOA refresh

refresh

Sets the interval, in seconds, for a secondary DNS server to wait before requesting updates from the primary DNS server.

SOA retry

retry

Sets the time, in seconds, to wait before retrying a failed refresh operation.

SOA expire

expire

Sets the time, in seconds, that a secondary DNS server will try to perform a refresh update before ending the operation attempt.

SOA minimum

minimum

Sets the time to live (TTL) value in seconds for negative caching according to RFC 2308.

SOA time to live

ttl

Sets TTL in seconds for records at zone apex. In zone example.com, for example, all records (A, NS, or SOA) under name example.com are configured, but no other domain names, like test.example.com, are affected.

Default time to live

default_ttl

Sets the default time to live (TTL) value in seconds for negative caching for all values in a zone that never had an individual TTL value set before. Requires a restart of the named-pkcs11 service on all IdM DNS servers after changes to take effect.

BIND update policy

update_policy

Sets the permissions allowed to clients in the DNS zone.

Dynamic update

dynamic_update=TRUE|FALSE

Enables dynamic updates to DNS records for clients.

Note that if this is set to false, IdM client machines will not be able to add or update their IP address.

Allow transfer

allow_transfer=string

Gives a list of IP addresses or network names which are allowed to transfer the given zone, separated by semicolons (;).

Zone transfers are disabled by default. The default allow_transfer value is none.

Allow query

allow_query

Gives a list of IP addresses or network names which are allowed to issue DNS queries, separated by semicolons (;).

Allow PTR sync

allow_sync_ptr=1|0

Sets whether A or AAAA records (forward records) for the zone will be automatically synchronized with the PTR (reverse) records.

Zone forwarders

forwarder=IP_address

Specifies a forwarder specifically configured for the DNS zone. This is separate from any global forwarders used in the IdM domain.

To specify multiple forwarders, use the option multiple times.

Forward policy

forward_policy=none|only|first

Specifies the forward policy. For information about the supported policies, see DNS forward policies in IdM.

Additional resources

  • See the README-dnszone.md file in the /usr/share/doc/ansible-freeipa/ directory.

3.3. Using Ansible to create a primary zone in IdM DNS

Follow this procedure to use an Ansible playbook to ensure that a primary DNS zone exists. In the example used in the procedure below, you ensure the presence of the zone.idm.example.com DNS zone.

Prerequisites

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

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • 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.
  • You know the IdM administrator password.

Procedure

  1. Navigate to the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory:

    $ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
  2. Open your inventory file and ensure that the IdM server that you want to configure is listed in the [ipaserver] section. For example, to instruct Ansible to configure server.idm.example.com, enter:

    [ipaserver]
    server.idm.example.com
  3. Make a copy of the dnszone-present.yml Ansible playbook file. For example:

    $ cp dnszone-present.yml dnszone-present-copy.yml
  4. Open the dnszone-present-copy.yml file for editing.
  5. Adapt the file by setting the following variables in the ipadnszone task section:

    • Set the ipaadmin_password variable to your IdM administrator password.
    • Set the zone_name variable to zone.idm.example.com.

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

    ---
    - name: Ensure dnszone present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure zone is present.
        ipadnszone:
          ipaadmin_password: "{{ ipaadmin_password }}"
          zone_name: zone.idm.example.com
          state: present
  6. Save the file.
  7. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-present-copy.yml

Additional resources

  • See Supported DNS zone types.
  • See the README-dnszone.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory.

3.4. Using an Ansible playbook to ensure the presence of a primary DNS zone in IdM with multiple variables

Follow this procedure to use an Ansible playbook to ensure that a primary DNS zone exists. In the example used in the procedure below, an IdM administrator ensures the presence of the zone.idm.example.com DNS zone. The Ansible playbook configures multiple parameters of the zone.

Prerequisites

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

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • 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.
  • You know the IdM administrator password.

Procedure

  1. Navigate to the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory:

    $ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
  2. Open your inventory file and ensure that the IdM server that you want to configure is listed in the [ipaserver] section. For example, to instruct Ansible to configure server.idm.example.com, enter:

    [ipaserver]
    server.idm.example.com
  3. Make a copy of the dnszone-all-params.yml Ansible playbook file. For example:

    $ cp dnszone-all-params.yml dnszone-all-params-copy.yml
  4. Open the dnszone-all-params-copy.yml file for editing.
  5. Adapt the file by setting the following variables in the ipadnszone task section:

    • Set the ipaadmin_password variable to your IdM administrator password.
    • Set the zone_name variable to zone.idm.example.com.
    • Set the allow_sync_ptr variable to true if you want to allow the synchronization of forward and reverse records, that is the synchronization of A and AAAA records with PTR records.
    • Set the dynamic_update variable to true to enable IdM client machines to add or update their IP addresses.
    • Set the dnssec variable to true to allow inline DNSSEC signing of records in the zone.
    • Set the allow_transfer variable to the IP addresses of secondary name servers in the zone.
    • Set the allow_query variable to the IP addresses or networks that are allowed to issue queries.
    • Set the forwarders variable to the IP addresses of global forwarders.
    • Set the serial variable to the SOA record serial number.
    • Define the refresh, retry, expire, minimum, ttl, and default_ttl values for DNS records in the zone.
    • Define the NSEC3PARAM record for the zone using the nsec3param_rec variable.
    • Set the skip_overlap_check variable to true to force DNS creation even if it overlaps with an existing zone.
    • Set the skip_nameserver_check to true to force DNS zone creation even if the nameserver is not resolvable.

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

    ---
    - name: Ensure dnszone present
      hosts: ipaserver
      become: true
    
      tasks:
      - name: Ensure zone is present.
        ipadnszone:
          ipaadmin_password: "{{ ipaadmin_password }}"
          zone_name: zone.idm.example.com
          allow_sync_ptr: true
          dynamic_update: true
          dnssec: true
          allow_transfer:
            - 1.1.1.1
            - 2.2.2.2
          allow_query:
            - 1.1.1.1
            - 2.2.2.2
          forwarders:
            - ip_address: 8.8.8.8
            - ip_address: 8.8.4.4
              port: 52
          serial: 1234
          refresh: 3600
          retry: 900
          expire: 1209600
          minimum: 3600
          ttl: 60
          default_ttl: 90
          name_server: server.idm.example.com.
          admin_email: admin.admin@idm.example.com
          nsec3param_rec: "1 7 100 0123456789abcdef"
          skip_overlap_check: true
          skip_nameserver_check: true
          state: present
  6. Save the file.
  7. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-all-params-copy.yml

Additional resources

3.5. Using an Ansible playbook to ensure the presence of a zone for reverse DNS lookup when an IP address is given

Follow this procedure to use an Ansible playbook to ensure that a reverse DNS zone exists. In the example used in the procedure below, an IdM administrator ensures the presence of a reverse DNS lookup zone using the IP address and prefix length of an IdM host.

Providing the prefix length of the IP address of your DNS server using the name_from_ip variable allows you to control the zone name. If you do not state the prefix length, the system queries DNS servers for zones and, based on the name_from_ip value of 192.168.1.2, the query can return any of the following DNS zones:

  • 1.168.192.in-addr.arpa.
  • 168.192.in-addr.arpa.
  • 192.in-addr.arpa.

Because the zone returned by the query might not be what you expect, name_from_ip can only be used with the state option set to present to prevent accidental removals of zones.

Prerequisites

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

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • 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.
  • You know the IdM administrator password.

Procedure

  1. Navigate to the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory:

    $ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
  2. Open your inventory file and ensure that the IdM server that you want to configure is listed in the [ipaserver] section. For example, to instruct Ansible to configure server.idm.example.com, enter:

    [ipaserver]
    server.idm.example.com
  3. Make a copy of the dnszone-reverse-from-ip.yml Ansible playbook file. For example:

    $ cp dnszone-reverse-from-ip.yml dnszone-reverse-from-ip-copy.yml
  4. Open the dnszone-reverse-from-ip-copy.yml file for editing.
  5. Adapt the file by setting the following variables in the ipadnszone task section:

    • Set the ipaadmin_password variable to your IdM administrator password.
    • Set the name_from_ip variable to the IP of your IdM nameserver, and provide its prefix length.

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

      ---
      - name: Ensure dnszone present
        hosts: ipaserver
        become: true
      
        tasks:
        - name: Ensure zone for reverse DNS lookup is present.
          ipadnszone:
            ipaadmin_password: "{{ ipaadmin_password }}"
            name_from_ip: 192.168.1.2/24
            state: present
          register: result
        - name: Display inferred zone name.
          debug:
            msg: "Zone name: {{ result.dnszone.name }}"

    The playbook creates a zone for reverse DNS lookup from the 192.168.1.2 IP address and its prefix length of 24. Next, the playbook displays the resulting zone name.

  6. Save the file.
  7. Run the playbook:

    $ ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-reverse-from-ip-copy.yml

Additional resources

  • See Supported DNS zone types.
  • See the README-dnszone.md file in the /usr/share/doc/ansible-freeipa/ directory.
  • See sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory.