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.
- What DNS zone types are supported in IdM
- What DNS attributes you can configure in IdM
- How to use an Ansible playbook to create a primary zone in IdM DNS
- How to use an Ansible playbook to ensure the presence of a primary IdM DNS zone with multiple variables
- How to use an Ansible playbook to ensure the presence of a zone for reverse DNS lookup when an IP address is given
Prerequisites
- DNS service is installed on the IdM server. For more information about how to use Red Hat Ansible Engine to install an IdM server with integrated DNS, see Installing an Identity Management server using an Ansible playbook.
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.
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 theipa dnszone-*
commands.In compliance with standard DNS rules, every primary zone must contain
start of authority
(SOA) andnameserver
(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 thesub.test.example.
name. In addition, thetest.example.
zone is configured with the192.0.2.254
forwarder IP address for thesub.text.example
subzone.A client querying the name
nonexistent.test.example.
receives theNXDomain
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 forwarder192.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:
-
The
dnszone-mod
command in the command-line interface (CLI). For more information, see Editing the configuration of a primary DNS zone in IdM CLI. - The IdM Web UI. For more information, see Editing the configuration of a primary DNS zone in IdM Web UI.
-
An Ansible playbook that uses the
ipadnszone
module. For more information, see Managing DNS zones in IdM.
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.
Attribute | ansible-freeipa variable | Description |
---|---|---|
Authoritative 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 |
Administrator e-mail address |
| Sets the email address to use for the zone administrator. This defaults to the root account on the host. |
SOA 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 |
| Sets the interval, in seconds, for a secondary DNS server to wait before requesting updates from the primary DNS server. |
SOA retry |
| Sets the time, in seconds, to wait before retrying a failed refresh operation. |
SOA 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 |
| Sets the time to live (TTL) value in seconds for negative caching according to RFC 2308. |
SOA time to live |
|
Sets TTL in seconds for records at zone apex. In zone |
Default time to live |
|
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 |
BIND update policy |
| Sets the permissions allowed to clients in the DNS zone. |
Dynamic update |
| 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 |
| 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 query |
| Gives a list of IP addresses or network names which are allowed to issue DNS queries, separated by semicolons (;). |
Allow PTR sync |
| Sets whether A or AAAA records (forward records) for the zone will be automatically synchronized with the PTR (reverse) records. |
Zone forwarders |
| 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 |
| 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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica. - You know the IdM administrator password.
Procedure
Navigate to the
/usr/share/doc/ansible-freeipa/playbooks/dnszone
directory:$ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
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
Make a copy of the dnszone-present.yml Ansible playbook file. For example:
$ cp dnszone-present.yml dnszone-present-copy.yml
- Open the dnszone-present-copy.yml file for editing.
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
-
Set the
- Save the file.
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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica. - You know the IdM administrator password.
Procedure
Navigate to the
/usr/share/doc/ansible-freeipa/playbooks/dnszone
directory:$ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
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
Make a copy of the dnszone-all-params.yml Ansible playbook file. For example:
$ cp dnszone-all-params.yml dnszone-all-params-copy.yml
- Open the dnszone-all-params-copy.yml file for editing.
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
, anddefault_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
-
Set the
- Save the file.
Run the playbook:
$ ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-all-params-copy.yml
Additional resources
- See Supported DNS zone types.
- See Configuration attributes of primary IdM DNS zones.
-
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.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
.
-
The target node, that is the node on which the
ansible-freeipa
module is executed, is part of the IdM domain as an IdM client, server or replica. - You know the IdM administrator password.
Procedure
Navigate to the
/usr/share/doc/ansible-freeipa/playbooks/dnszone
directory:$ cd /usr/share/doc/ansible-freeipa/playbooks/dnszone
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
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
- Open the dnszone-reverse-from-ip-copy.yml file for editing.
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.
-
Set the
- Save the file.
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.