Chapter 28. Using Ansible playbooks to manage IdM DNS zones
Chapter 28. 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 . 28.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 28.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. 28.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 on the command line (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. Table 28.1. IdM DNS zone attributes Attribute ansible-freeipa variable Description 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. 28.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. 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: 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: Make a copy of the dnszone-present.yml Ansible playbook file. For example: 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: Save the file. Run the playbook: Additional resources Supported DNS zone types The README-dnszone.md file in the /usr/share/doc/ansible-freeipa/ directory Sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory 28.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. 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: 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: Make a copy of the dnszone-all-params.yml Ansible playbook file. For example: 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. Warning DNSSEC is only available as Technology Preview in IdM. 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: Save the file. Run the playbook: 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. 28.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. 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: 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: Make a copy of the dnszone-reverse-from-ip.yml Ansible playbook file. For example: 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: The playbook creates a zone for reverse DNS lookup from the 192.168.1.2 IP address and its prefix length of 24. , the playbook displays the resulting zone name. Save the file. Run the playbook: Additional resources Supported DNS zone types The README-dnszone.md file in the /usr/share/doc/ansible-freeipa/ directory. Sample Ansible playbooks in the /usr/share/doc/ansible-freeipa/playbooks/dnszone directory
cd /usr/share/doc/ansible-freeipa/playbooks/dnszone [ipaserver] server.idm.example.com cp dnszone-present.yml dnszone-present-copy.yml --- - 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 ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-present-copy.yml cd /usr/share/doc/ansible-freeipa/playbooks/dnszone [ipaserver] server.idm.example.com cp dnszone-all-params.yml dnszone-all-params-copy.yml --- - 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 ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-all-params-copy.yml cd /usr/share/doc/ansible-freeipa/playbooks/dnszone [ipaserver] server.idm.example.com cp dnszone-reverse-from-ip.yml dnszone-reverse-from-ip-copy.yml --- - 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 }}" ansible-playbook --vault-password-file=password_file -v -i inventory.file dnszone-reverse-from-ip-copy.yml