Chapter 31. Installing an Identity Management server using an Ansible playbook

1. If your system is running on RHEL 8.5 and earlier, enable the required repository:

   # subscription-manager repos --enable ansible-2.8-for-rhel-8-x86_64-rpms

2. If your system is running on RHEL 8.5 and earlier, install the ansible package:

   # yum install ansible

3. Install the ansible-freeipa package:

   # yum install ansible-freeipa

   The roles and modules are installed into the /usr/share/ansible/roles/ and /usr/share/ansible/plugins/modules directories.

Procedure

1. Create a ~/MyPlaybooks/ directory:

   $ mkdir MyPlaybooks

2. Create a ~/MyPlaybooks/inventory file.

3. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

   • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case.
4. Specify the IdM domain and realm information.

5. Specify that you want to use integrated DNS by adding the following option:

   ipaserver_setup_dns=true

6. Specify the DNS forwarding settings. Choose one of the following options:

   • Use the ipaserver_auto_forwarders=true option if you want the installer to use forwarders from the /etc/resolv.conf file. Do not use this option if the nameserver specified in the /etc/resolv.conf file is the localhost 127.0.0.1 address or if you are on a virtual private network and the DNS servers you are using are normally unreachable from the public internet.
   • Use the ipaserver_forwarders option to specify your forwarders manually. The installation process adds the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

   • Use the ipaserver_no_forwarders=true option to configure root DNS servers to be used instead.

     Note

     With no DNS forwarders, your environment is isolated, and names from other DNS domains in your infrastructure are not resolved.

7. Specify the DNS reverse record and zone settings. Choose from the following options:

   • Use the ipaserver_allow_zone_overlap=true option to allow the creation of a (reverse) zone even if the zone is already resolvable.
   • Use the ipaserver_reverse_zones option to specify your reverse zones manually.

   • Use the ipaserver_no_reverse=true option if you do not want the installer to create a reverse DNS zone.

     Note

     Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead.

8. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

9. Optional: Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

   Important

   The specified firewalld zone must exist and be permanent.

   Example of an inventory file with the required server information (excluding the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   [...]

   Example of an inventory file with the required server information (including the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   
   [...]

   Example of an inventory file with a custom firewalld zone

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   ipaserver_firewalld_zone=custom zone

   Example playbook to set up an IdM server using admin and Directory Manager passwords stored in an Ansible Vault file

   ---
   - name: Playbook to configure IPA server
     hosts: ipaserver
     become: true
     vars_files:
     - playbook_sensitive_data.yml
   
     roles:
     - role: ipaserver
       state: present

   Example playbook to set up an IdM server using admin and Directory Manager passwords from an inventory file

   ---
   - name: Playbook to configure IPA server
     hosts: ipaserver
     become: true
   
     roles:
     - role: ipaserver
       state: present

Procedure

1. Create a ~/MyPlaybooks/ directory:

   $ mkdir MyPlaybooks

2. Create a ~/MyPlaybooks/inventory file.

3. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

   • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case.
4. Specify the IdM domain and realm information.
5. Make sure that the ipaserver_setup_dns option is set to no or that it is absent.
6. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

7. Optional: Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

   Important

   The specified firewalld zone must exist and be permanent.

   Example of an inventory file with the required server information (excluding the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   [...]

   Example of an inventory file with the required server information (including the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   
   [...]

   Example of an inventory file with a custom firewalld zone

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   ipaserver_firewalld_zone=custom zone

   Example playbook to set up an IdM server using admin and Directory Manager passwords stored in an Ansible Vault file

   ---
   - name: Playbook to configure IPA server
     hosts: ipaserver
     become: true
     vars_files:
     - playbook_sensitive_data.yml
   
     roles:
     - role: ipaserver
       state: present

   Example playbook to set up an IdM server using admin and Directory Manager passwords from an inventory file

   ---
   - name: Playbook to configure IPA server
     hosts: ipaserver
     become: true
   
     roles:
     - role: ipaserver
       state: present

Procedure

1. Run the Ansible playbook:

   $ ansible-playbook -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-server.yml

2. Choose one of the following options:

   • If your IdM deployment uses external DNS: add the DNS resource records contained in the /tmp/ipa.system.records.UFRPto.db file to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution.

     ...
     Restarting the KDC
     Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
     Restarting the web server
     ...

   Important

   The server installation is not complete until you add the DNS records to the existing DNS servers.

   • If your IdM deployment uses integrated DNS:

     • Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is idm.example.com, add a name server (NS) record to the example.com parent domain.

       Important

       Repeat this step each time after an IdM DNS server is installed.

     • Add an _ntp._udp service (SRV) record for your time server to your IdM DNS. The presence of the SRV record for the time server of the newly-installed IdM server in IdM DNS ensures that future replica and client installations are automatically configured to synchronize with the time server used by this primary IdM server.

Procedure

1. Create a ~/MyPlaybooks/ directory:

   $ mkdir MyPlaybooks

2. Create a ~/MyPlaybooks/inventory file.

3. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

   • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case.
4. Specify the IdM domain and realm information.

5. Specify that you want to use integrated DNS by adding the following option:

   ipaserver_setup_dns=true

6. Specify the DNS forwarding settings. Choose one of the following options:

   • Use the ipaserver_auto_forwarders=true option if you want the installation process to use forwarders from the /etc/resolv.conf file. This option is not recommended if the nameserver specified in the /etc/resolv.conf file is the localhost 127.0.0.1 address or if you are on a virtual private network and the DNS servers you are using are normally unreachable from the public internet.
   • Use the ipaserver_forwarders option to specify your forwarders manually. The installation process adds the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

   • Use the ipaserver_no_forwarders=true option to configure root DNS servers to be used instead.

     Note

     With no DNS forwarders, your environment is isolated, and names from other DNS domains in your infrastructure are not resolved.

7. Specify the DNS reverse record and zone settings. Choose from the following options:

   • Use the ipaserver_allow_zone_overlap=true option to allow the creation of a (reverse) zone even if the zone is already resolvable.
   • Use the ipaserver_reverse_zones option to specify your reverse zones manually.

   • Use the ipaserver_no_reverse=true option if you do not want the installation process to create a reverse DNS zone.

     Note

     Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead.

8. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

9. Optional: Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM adds its services to the default firewalld zone. The predefined default zone is public.

   Important

   The specified firewalld zone must exist and be permanent.

   Example of an inventory file with the required server information (excluding the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   [...]

   Example of an inventory file with the required server information (including the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   
   [...]

   Example of an inventory file with a custom firewalld zone

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=true
   ipaserver_auto_forwarders=true
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   ipaserver_firewalld_zone=custom zone
   
   [...]

10. Create a playbook for the first step of the installation. Enter instructions for generating the certificate signing request (CSR) and copying it from the controller to the managed node.

    ---
    - name: Playbook to configure IPA server Step 1
      hosts: ipaserver
      become: true
      vars_files:
      - playbook_sensitive_data.yml
      vars:
        ipaserver_external_ca: true
    
      roles:
      - role: ipaserver
        state: present
    
      post_tasks:
      - name: Copy CSR /root/ipa.csr from node to "{{ groups.ipaserver[0] + '-ipa.csr' }}"
        fetch:
          src: /root/ipa.csr
          dest: "{{ groups.ipaserver[0] + '-ipa.csr' }}"
          flat: true

11. Create another playbook for the final step of the installation.

    ---
    - name: Playbook to configure IPA server Step 2
      hosts: ipaserver
      become: true
      vars_files:
      - playbook_sensitive_data.yml
      vars:
        ipaserver_external_cert_files:
          - "/root/servercert20240601.pem"
          - "/root/cacert.pem"
    
      pre_tasks:
      - name: Copy "{{ groups.ipaserver[0] }}-{{ item }}" to "/root/{{ item }}" on node
        ansible.builtin.copy:
          src: "{{ groups.ipaserver[0] }}-{{ item }}"
          dest: "/root/{{ item }}"
          force: true
        with_items:
        - servercert20240601.pem
        - cacert.pem
    
      roles:
      - role: ipaserver
        state: present

Procedure

1. Create a ~/MyPlaybooks/ directory:

   $ mkdir MyPlaybooks

2. Create a ~/MyPlaybooks/inventory file.

3. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the host you want to use as an IdM server. Ensure that the FQDN meets the following criteria:

   • Only alphanumeric characters and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case.
4. Specify the IdM domain and realm information.
5. Make sure that the ipaserver_setup_dns option is set to no or that it is absent.
6. Specify the passwords for admin and for the Directory Manager. Use the Ansible Vault to store the password, and reference the Vault file from the playbook file. Alternatively and less securely, specify the passwords directly in the inventory file.

7. Optional: Specify a custom firewalld zone to be used by the IdM server. If you do not set a custom zone, IdM will add its services to the default firewalld zone. The predefined default zone is public.

   Important

   The specified firewalld zone must exist and be permanent.

   Example of an inventory file with the required server information (excluding the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   [...]

   Example of an inventory file with the required server information (including the passwords)

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   
   [...]

   Example of an inventory file with a custom firewalld zone

   [ipaserver]
   server.idm.example.com
   
   [ipaserver:vars]
   ipaserver_domain=idm.example.com
   ipaserver_realm=IDM.EXAMPLE.COM
   ipaserver_setup_dns=no
   ipaadmin_password=MySecretPassword123
   ipadm_password=MySecretPassword234
   ipaserver_firewalld_zone=custom zone
   
   [...]

8. Create a playbook for the first step of the installation. Enter instructions for generating the certificate signing request (CSR) and copying it from the controller to the managed node.

   ---
   - name: Playbook to configure IPA server Step 1
     hosts: ipaserver
     become: true
     vars_files:
     - playbook_sensitive_data.yml
     vars:
       ipaserver_external_ca: true
   
     roles:
     - role: ipaserver
       state: present
   
     post_tasks:
     - name: Copy CSR /root/ipa.csr from node to "{{ groups.ipaserver[0] + '-ipa.csr' }}"
       fetch:
         src: /root/ipa.csr
         dest: "{{ groups.ipaserver[0] + '-ipa.csr' }}"
         flat: true

9. Create another playbook for the final step of the installation.

   ---
   - name: Playbook to configure IPA server Step 2
     hosts: ipaserver
     become: true
     vars_files:
     - playbook_sensitive_data.yml
     vars:
       ipaserver_external_cert_files:
         - "/root/servercert20240601.pem"
         - "/root/cacert.pem"
   
     pre_tasks:
     - name: Copy "{{ groups.ipaserver[0] }}-{{ item }}" to "/root/{{ item }}" on node
       ansible.builtin.copy:
         src: "{{ groups.ipaserver[0] }}-{{ item }}"
         dest: "/root/{{ item }}"
         force: true
       with_items:
       - servercert20240601.pem
       - cacert.pem
   
     roles:
     - role: ipaserver
       state: present

Procedure

1. Run the Ansible playbook with the instructions for the first step of the installation, for example install-server-step1.yml:

   $ ansible-playbook --vault-password-file=password_file -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-server-step1.yml

2. Locate the ipa.csr certificate signing request file on the controller and submit it to the external CA.
3. Place the IdM CA certificate signed by the external CA in the controller file system so that the playbook in the next step can find it.

4. Run the Ansible playbook with the instructions for the final step of the installation, for example install-server-step2.yml:

   $ ansible-playbook -v -i ~/MyPlaybooks/inventory ~/MyPlaybooks/install-server-step2.yml

5. Choose one of the following options:

   • If your IdM deployment uses external DNS: add the DNS resource records contained in the /tmp/ipa.system.records.UFRPto.db file to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution.

     ...
     Restarting the KDC
     Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
     Restarting the web server
     ...

   Important

   The server installation is not complete until you add the DNS records to the existing DNS servers.

   • If your IdM deployment uses integrated DNS:

     • Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is idm.example.com, add a name server (NS) record to the example.com parent domain.

       Important

       Repeat this step each time after an IdM DNS server is installed.

     • Add an _ntp._udp service (SRV) record for your time server to your IdM DNS. The presence of the SRV record for the time server of the newly-installed IdM server in IdM DNS ensures that future replica and client installations are automatically configured to synchronize with the time server used by this primary IdM server.

Procedure

1. Create your Ansible playbook file uninstall-server.yml with the following content:

   ---
   - name: Playbook to uninstall an IdM replica
     hosts: ipaserver
     become: true
   
     roles:
     - role: ipaserver
       ipaserver_remove_from_domain: true
       state: absent

   The ipaserver_remove_from_domain option unenrolls the host from the IdM topology.

   Note

   If the removal of server123.idm.example.com should lead to a disconnected topology, the removal will be aborted. For more information, see Using an Ansible playbook to uninstall an IdM server even if this leads to a disconnected topology.

2. Uninstall the replica:

   $ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/inventory <path_to_playbooks_directory>/uninstall-server.yml

3. Ensure that all name server (NS) DNS records pointing to server123.idm.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS. For more information on how to delete DNS records from IdM, see Deleting DNS records in the IdM CLI.

Procedure

1. Create your Ansible playbook file uninstall-server.yml with the following content:

   ---
   - name: Playbook to uninstall an IdM replica
     hosts: ipaserver
     become: true
   
     roles:
     - role: ipaserver
       ipaserver_remove_from_domain: true
       ipaserver_remove_on_server: server456.idm.example.com
       ipaserver_ignore_topology_disconnect: true
       state: absent

   Note

   Under normal circumstances, if the removal of server123 does not result in a disconnected topology: if the value for ipaserver_remove_on_server is not set, the replica on which server123 is removed is automatically determined using the replication agreements of server123.

2. Uninstall the replica:

   $ ansible-playbook --vault-password-file=password_file -v -i <path_to_inventory_directory>/hosts <path_to_playbooks_directory>/uninstall-server.yml

3. Ensure that all name server (NS) DNS records pointing to server123.idm.example.com are deleted from your DNS zones. This applies regardless of whether you use integrated DNS managed by IdM or external DNS. For more information on how to delete DNS records from IdM, see Deleting DNS records in the IdM CLI.