Installing Identity Management

Procedure

1. Verify that the firewalld service is running.

   • To find out if firewalld is currently running:

     # systemctl status firewalld.service

   • To start firewalld and configure it to start automatically when the system boots:

     # systemctl start firewalld.service
     # systemctl enable firewalld.service

2. Open the required ports using the firewall-cmd utility. Choose one of the following options:

   1. Add the individual ports to the firewall by using the firewall-cmd --add-port command. For example, to open the ports in the default zone:

      # firewall-cmd --permanent --add-port={80/tcp,443/tcp,389/tcp,636/tcp,88/tcp,88/udp,464/tcp,464/udp,53/tcp,53/udp}

   2. Add the firewalld services to the firewall by using the firewall-cmd --add-service command. For example, to open the ports in the default zone:

      # firewall-cmd --permanent --add-service={freeipa-4,dns}

      For details on using firewall-cmd to open ports on a system, see the firewall-cmd(1) man page.

3. Reload the firewall-cmd configuration to ensure that the change takes place immediately:

   # firewall-cmd --reload

   Note that reloading firewalld on a system in production can cause DNS connection time outs. If required, to avoid the risk of time outs and to make the changes persistent on the running system, use the --runtime-to-permanent option of the firewall-cmd command, for example:

   # firewall-cmd --runtime-to-permanent

Procedure

1. Optional: Display the current umask:

   # umask
   0027

2. Set the umask to 0022:

   # umask 0022

3. Optional: After the IdM installation is complete, set the umask back to its original value:

   # umask 0027

Procedure

1. Run the ipa-server-install utility.

   # ipa-server-install

2. The script prompts to configure an integrated DNS service. Enter yes.

   Do you want to configure integrated DNS (BIND)? [no]: yes

3. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     Server host name [server.idm.example.com]:
     Please confirm the domain name [idm.example.com]:
     Please provide a realm name [IDM.EXAMPLE.COM]:

     Warning

     Plan these names carefully. You will not be able to change them after the installation is complete.

4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the Identity Management (IdM) administration system user account (admin).

   Directory Manager password:
   IPA admin password:

5. The script prompts for per-server DNS forwarders.

   Do you want to configure DNS forwarders? [yes]:

   • To configure per-server DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the IdM LDAP.

     • For the forwarding policy default settings, see the --forward-policy description in the ipa-dns-install(1) man page.

   • If you do not want to use DNS forwarding, enter no.

     With no DNS forwarders, hosts in your IdM domain will not be able to resolve names from other, internal, DNS domains in your infrastructure. The hosts will only be left with public DNS servers to resolve their DNS queries.

6. The script prompts to check if any DNS reverse (PTR) records for the IP addresses associated with the server need to be configured.

   Do you want to search for missing reverse zones? [yes]:

   If you run the search and missing reverse zones are discovered, the script asks you whether to create the reverse zones along with the PTR records.

   Do you want to create reverse zone for IP 192.0.2.1 [yes]:
   Please specify the reverse zone name [2.0.192.in-addr.arpa.]:
   Using reverse zone(s) 2.0.192.in-addr.arpa.

   Note

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

7. Enter yes to confirm the server configuration.

   Continue to configure the system with these values? [no]: yes

8. The installation script now configures the server. Wait for the operation to complete.

9. After the installation script completes, update your DNS records in the following way:

   1. 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.

   2. 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. Run the ipa-server-install utility with the options to supply all the required information. The minimum required options for non-interactive installation are:

   • --realm to provide the Kerberos realm name
   • --ds-password to provide the password for the Directory Manager (DM), the Directory Server super user
   • --admin-password to provide the password for admin, the Identity Management (IdM) administrator
   • --unattended to let the installation process select default options for the host name and domain name

   To install a server with integrated DNS, add also these options:

   • --setup-dns to configure integrated DNS
   • --forwarder or --no-forwarders, depending on whether you want to configure DNS forwarders or not
   • --auto-reverse or --no-reverse, depending on whether you want to configure automatic detection of the reverse DNS zones that must be created in the IdM DNS or no reverse zone auto-detection

   For example:

   # ipa-server-install --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended --setup-dns --forwarder 192.0.2.1 --no-reverse

2. After the installation script completes, update your DNS records in the following way:

   1. 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.

   2. 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. Run the ipa-server-install utility with the --external-ca option.

   # ipa-server-install --external-ca

   • If you are using the Microsoft Certificate Services (MS CS) CA, also use the --external-ca-type option and, optionally, the --external-ca-profile option:

     [root@server ~]# ipa-server-install --external-ca --external-ca-type=ms-cs --external-ca-profile=<oid>/<name>/default

   • If you are not using MS CS to generate the signing certificate for your IdM CA, no other option may be necessary:

     # ipa-server-install --external-ca

2. The script prompts to configure an integrated DNS service. Enter yes or no. In this procedure, we are installing a server with integrated DNS.

   Do you want to configure integrated DNS (BIND)? [no]: yes

   Note

   If you want to install a server without integrated DNS, the installation script will not prompt you for DNS configuration as described in the steps below. See Chapter 5, Installing an IdM server: Without integrated DNS, with an integrated CA as the root CA for details on the steps for installing a server without DNS.

3. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     Server host name [server.idm.example.com]:
     Please confirm the domain name [idm.example.com]:
     Please provide a realm name [IDM.EXAMPLE.COM]:

     Warning

     Plan these names carefully. You will not be able to change them after the installation is complete.

4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the Identity Management (IdM) administration system user account (admin).

   Directory Manager password:
   IPA admin password:

5. The script prompts for per-server DNS forwarders.

   Do you want to configure DNS forwarders? [yes]:

   • To configure per-server DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the IdM LDAP.

     • For the forwarding policy default settings, see the --forward-policy description in the ipa-dns-install(1) man page.

   • If you do not want to use DNS forwarding, enter no.

     With no DNS forwarders, hosts in your IdM domain will not be able to resolve names from other, internal, DNS domains in your infrastructure. The hosts will only be left with public DNS servers to resolve their DNS queries.

6. The script prompts to check if any DNS reverse (PTR) records for the IP addresses associated with the server need to be configured.

   Do you want to search for missing reverse zones? [yes]:

   If you run the search and missing reverse zones are discovered, the script asks you whether to create the reverse zones along with the PTR records.

   Do you want to create reverse zone for IP 192.0.2.1 [yes]:
   Please specify the reverse zone name [2.0.192.in-addr.arpa.]:
   Using reverse zone(s) 2.0.192.in-addr.arpa.

   Note

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

7. Enter yes to confirm the server configuration.

   Continue to configure the system with these values? [no]: yes

8. During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr:

   ...
   
   Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
     [1/8]: creating certificate server user
     [2/8]: configuring certificate server instance
   The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
   /sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate

   When this happens:

   1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

   2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Be sure to get the full certificate chain for the CA, not just the CA certificate.

   3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example:

      # ipa-server-install --external-cert-file=/tmp/servercert20170601.pem --external-cert-file=/tmp/cacert.pem

9. The installation script now configures the server. Wait for the operation to complete.

10. After the installation script completes, update your DNS records in the following way:

    1. 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.

    2. 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.

1. Use the following shell script to unset the *_proxy environmental variables:

   # for i in ftp http https; do unset ${i}_proxy; done

2. Run the pkidestroy utility to remove the unsuccessful certificate authority (CA) subsystem installation:

   # pkidestroy -s CA -i pki-tomcat; rm -rf /var/log/pki/pki-tomcat /etc/sysconfig/pki-tomcat /etc/sysconfig/pki/tomcat/pki-tomcat /var/lib/pki/pki-tomcat /etc/pki/pki-tomcat /root/ipa.csr

3. Remove the failed Identity Management (IdM) server installation:

   # ipa-server-install --uninstall

4. Retry running ipa-server-install --external-ca.

Procedure

1. Run the ipa-server-install utility and provide all the required certificates. For example:

   [root@server ~]# ipa-server-install \
       --http-cert-file /tmp/server.crt \
       --http-cert-file /tmp/server.key \
       --http-pin secret \
       --dirsrv-cert-file /tmp/server.crt \
       --dirsrv-cert-file /tmp/server.key \
       --dirsrv-pin secret \
       --ca-cert-file ca.crt

   See Certificates required to install an IdM server without a CA for details on the provided certificates.

2. The script prompts to configure an integrated DNS service. Enter yes or no. In this procedure, we are installing a server with integrated DNS.

   Do you want to configure integrated DNS (BIND)? [no]: yes

   Note

   If you want to install a server without integrated DNS, the installation script will not prompt you for DNS configuration as described in the steps below. See Installing an IdM server: Without integrated DNS, with an integrated CA as the root CA for details on the steps for installing a server without DNS.

3. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     Server host name [server.idm.example.com]:
     Please confirm the domain name [idm.example.com]:
     Please provide a realm name [IDM.EXAMPLE.COM]:

     Warning

     Plan these names carefully. You will not be able to change them after the installation is complete.

4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the Identity Management (IdM) administration system user account (admin).

   Directory Manager password:
   IPA admin password:

5. The script prompts for per-server DNS forwarders.

   Do you want to configure DNS forwarders? [yes]:

   • To configure per-server DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the IdM LDAP.

     • For the forwarding policy default settings, see the --forward-policy description in the ipa-dns-install(1) man page.

   • If you do not want to use DNS forwarding, enter no.

     With no DNS forwarders, hosts in your IdM domain will not be able to resolve names from other, internal, DNS domains in your infrastructure. The hosts will only be left with public DNS servers to resolve their DNS queries.

6. The script prompts to check if any DNS reverse (PTR) records for the IP addresses associated with the server need to be configured.

   Do you want to search for missing reverse zones? [yes]:

   If you run the search and missing reverse zones are discovered, the script asks you whether to create the reverse zones along with the PTR records.

   Do you want to create reverse zone for IP 192.0.2.1 [yes]:
   Please specify the reverse zone name [2.0.192.in-addr.arpa.]:
   Using reverse zone(s) 2.0.192.in-addr.arpa.

   Note

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

7. Enter yes to confirm the server configuration.

   Continue to configure the system with these values? [no]: yes

8. The installation script now configures the server. Wait for the operation to complete.

9. After the installation script completes, update your DNS records in the following way:

   1. 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.

   2. 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. Run the ipa-server-install utility.

   # ipa-server-install

2. The script prompts to configure an integrated DNS service. Press Enter to select the default no option.

   Do you want to configure integrated DNS (BIND)? [no]:

3. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     Server host name [server.idm.example.com]:
     Please confirm the domain name [idm.example.com]:
     Please provide a realm name [IDM.EXAMPLE.COM]:

     Warning

     Plan these names carefully. You will not be able to change them after the installation is complete.

4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the IdM administration system user account (admin).

   Directory Manager password:
   IPA admin password:

5. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     NetBIOS domain name [EXAMPLE]:
     Do you want to configure chrony with NTP server or pool address? [no]:

6. Enter yes to confirm the server configuration.

   Continue to configure the system with these values? [no]: yes

7. The installation script now configures the server. Wait for the operation to complete.

8. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records 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.

Procedure

1. Run the ipa-server-install utility with the options to supply all the required information. The minimum required options for non-interactive installation are:

   • --realm to provide the Kerberos realm name
   • --ds-password to provide the password for the Directory Manager (DM), the Directory Server super user
   • --admin-password to provide the password for admin, the IdM administrator
   • --unattended to let the installation process select default options for the host name and domain name

   For example:

   # ipa-server-install --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended

2. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records 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.

Procedure

1. Run the ipa-server-install utility with the --external-ca option.

   • If you are using the Microsoft Certificate Services (MS CS) CA, also use the --external-ca-type option and, optionally, the --external-ca-profile option:

     [root@server ~]# ipa-server-install --external-ca --external-ca-type=ms-cs --external-ca-profile=<oid>/<name>/default

   • If you are not using MS CS to generate the signing certificate for your IdM CA, no other option may be necessary:

     # ipa-server-install --external-ca

2. The script prompts to configure an integrated DNS service. Press Enter to select the default no option.

   Do you want to configure integrated DNS (BIND)? [no]:

3. The script prompts for several required settings and offers recommended default values in brackets.

   • To accept a default value, press Enter.

   • To provide a custom value, enter the required value.

     Server host name [server.idm.example.com]:
     Please confirm the domain name [idm.example.com]:
     Please provide a realm name [IDM.EXAMPLE.COM]:

     Warning

     Plan these names carefully. You will not be able to change them after the installation is complete.

4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the IdM administration system user account (admin).

   Directory Manager password:
   IPA admin password:

5. Enter yes to confirm the server configuration.

   Continue to configure the system with these values? [no]: yes

6. During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr:

   ...
   
   Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
     [1/8]: creating certificate server user
     [2/8]: configuring certificate server instance
   The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
   /sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate

   When this happens:

   1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

   2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Be sure to get the full certificate chain for the CA, not just the CA certificate.

   3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example:

      # ipa-server-install --external-cert-file=/tmp/servercert20170601.pem --external-cert-file=/tmp/cacert.pem

7. The installation script now configures the server. Wait for the operation to complete.

8. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records 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.

Procedure

1. Run the ipa-server-install utility with the options to supply all the required information. The minimum required options for non-interactive installation of an IdM server with an external CA as the root CA are:

   • --external-ca to specify an external CA is the root CA
   • --realm to provide the Kerberos realm name
   • --ds-password to provide the password for the Directory Manager (DM), the Directory Server super user
   • --admin-password to provide the password for admin, the IdM administrator

   • --unattended to let the installation process select default options for the host name and domain name

     For example:

     # ipa-server-install --external-ca --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended

   If you are using a Microsoft Certificate Services (MS CS) CA, also use the --external-ca-type option and, optionally, the --external-ca-profile option. For more information, see Options used when installing an IdM CA with an external CA as the root CA.

2. During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr:

   ...
   
   Configuring certificate server (pki-tomcatd). Estimated time: 3 minutes
     [1/11]: configuring certificate server instance
   The next step is to get /root/ipa.csr signed by your CA and re-run /usr/sbin/ipa-server-install as:
   /usr/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
   The ipa-server-install command was successful

   When this happens:

   1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

   2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Be sure to get the full certificate chain for the CA, not just the CA certificate.

   3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example:

      # ipa-server-install --external-cert-file=/tmp/servercert20170601.pem --external-cert-file=/tmp/cacert.pem --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended

3. The installation script now configures the server. Wait for the operation to complete.

4. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records 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
   ...

Procedure

1. Use the tail command to display the last lines of a log file. The following example displays the last 10 lines of /var/log/ipaserver-install.log.

   [user@server ~]$ sudo tail -n 10 /var/log/ipaserver-install.log
   [sudo] password for user:
   value = gen.send(prev_value)
   File "/usr/lib/python3.6/site-packages/ipapython/install/common.py", line 65, in _install
   for unused in self._installer(self.parent):
   File "/usr/lib/python3.6/site-packages/ipaserver/install/server/init.py", line 564, in main
   master_install(self)
   File "/usr/lib/python3.6/site-packages/ipaserver/install/server/install.py", line 291, in decorated
   raise ScriptError()
   
   2020-05-27T22:59:41Z DEBUG The ipa-server-install command failed, exception: ScriptError:
   2020-05-27T22:59:41Z ERROR The ipa-server-install command failed. See /var/log/ipaserver-install.log for more information

2. To review a log file interactively, open the end of the log file using the less utility and use the ↑ and ↓ arrow keys to navigate. The following example opens the /var/log/ipaserver-install.log file interactively.

   [user@server ~]$ sudo less -N +G /var/log/ipaserver-install.log

3. Gather additional troubleshooting information by repeating this review process with the remaining log files.

   [user@server ~]$ sudo less -N +G /var/log/httpd/error_log
   
   [user@server ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/access
   
   [user@server ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/errors

Procedure

1. To review a log file interactively, open the end of the log file using the less utility and use the ↑ and ↓ arrow keys to navigate, while searching for ScriptError entries. The following example opens /var/log/pki/pki-ca-spawn.$TIME_OF_INSTALLATION.log.

   [user@server ~]$ sudo less -N +G /var/log/pki/pki-ca-spawn.20200527185902.log

2. Gather additional troubleshooting information by repeating this review process with all the log files listed above.

Procedure

1. Uninstall the IdM server software from the host you are trying to configure as an IdM server.

   [root@server ~]# ipa-server-install --uninstall

2. If you continue to experience difficulty installing an IdM server because of repeated failed installations, reinstall the operating system.

   One of the requirements for installing an IdM server is a clean system without any customization. Failed installations may have compromised the integrity of the host by unexpectedly modifying system files.

Procedure

1. Run the ipa-client-install utility on the system that you want to configure as an IdM client.

   # ipa-client-install --mkhomedir

   Add the --enable-dns-updates option to update the DNS records with the IP address of the client system if either of the following conditions applies:

   • The IdM server the client will be enrolled with was installed with integrated DNS
   • The DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol

   # ipa-client-install --enable-dns-updates --mkhomedir

   Enabling DNS updates is useful if your client:

   • has a dynamic IP address issued using the Dynamic Host Configuration Protocol
   • has a static IP address but it has just been allocated and the IdM server does not know about it

2. The installation script attempts to obtain all the required settings, such as DNS records, automatically.

   • If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values and displays them. Enter yes to confirm.

     Client hostname: client.example.com
     Realm: EXAMPLE.COM
     DNS Domain: example.com
     IPA Server: server.example.com
     BaseDN: dc=example,dc=com
     
     Continue to configure the system with these values? [no]: yes

   • To install the system with different values, enter no. Then run ipa-client-install again, and specify the required values by adding command-line options to ipa-client-install, for example:

     • --hostname
     • --realm
     • --domain
     • --server
     • --mkhomedir
     Important

     The fully qualified domain name must be a valid DNS name:

     • Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
     • The host name must be all lower-case. No capital letters are allowed.
   • If the script fails to obtain some settings automatically, it prompts you for the values.

3. The script prompts for a user whose identity will be used to enroll the client. This could be, for example, a hostadmin user with the Enrollment Administrator role:

   User authorized to enroll computers: hostadmin
   Password for hostadmin@EXAMPLE.COM:

4. The installation script now configures the client. Wait for the operation to complete.

   Client configuration complete.

Procedure

1. Run the ipa-client-install utility on the system that you want to configure as an IdM client.

   Use the --password option to provide the one-time random password. Because the password often contains special characters, enclose it in single quotes (').

   # ipa-client-install --mkhomedir --password=password

   Add the --enable-dns-updates option to update the DNS records with the IP address of the client system if either of the following conditions applies:

   • The IdM server the client will be enrolled with was installed with integrated DNS
   • The DNS server on the network accepts DNS entry updates with the GSS-TSIG protocol

   # ipa-client-install --password 'W5YpARl=7M.n' --enable-dns-updates --mkhomedir

   Enabling DNS updates is useful if your client:

   • has a dynamic IP address issued using the Dynamic Host Configuration Protocol
   • has a static IP address but it has just been allocated and the IdM server does not know about it

2. The installation script attempts to obtain all the required settings, such as DNS records, automatically.

   • If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values and displays them. Enter yes to confirm.

     Client hostname: client.example.com
     Realm: EXAMPLE.COM
     DNS Domain: example.com
     IPA Server: server.example.com
     BaseDN: dc=example,dc=com
     
     Continue to configure the system with these values? [no]: yes

   • To install the system with different values, enter no. Then run ipa-client-install again, and specify the required values by adding command-line options to ipa-client-install, for example:

     • --hostname
     • --realm
     • --domain
     • --server
     • --mkhomedir
     Important

     The fully qualified domain name must be a valid DNS name:

     • Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
     • The host name must be all lower-case. No capital letters are allowed.
   • If the script fails to obtain some settings automatically, it prompts you for the values.

3. The installation script now configures the client. Wait for the operation to complete.

   Client configuration complete.

1. Open /etc/openldap/ldap.conf and /etc/sssd/sssd.conf.
2. Delete the previous configuration.
3. Uncomment the new IdM configuration.
4. Server processes that rely on system-wide LDAP configuration might require a restart to apply the changes. Applications that use openldap libraries typically import the configuration when started.

Procedure

1. Pre-create the host entry on the IdM server, and set a temporary password for the entry:

   $ ipa host-add client.example.com --password=secret

   The password is used by Kickstart to authenticate during the client installation and expires after the first authentication attempt. After the client is successfully installed, it authenticates using its keytab.

2. Create a Kickstart file with the contents described in Section 14.2, “Kickstart file for client installation”. Make sure that network is configured properly in the Kickstart file using the network command.
3. Use the Kickstart file to install the IdM client.

Procedure

1. Use the grep utility to retrieve any occurrences of the keyword ScriptError from the /var/log/ipaserver-install.log file.

   [user@server ~]$ sudo grep ScriptError /var/log/ipaclient-install.log
   [sudo] password for user:
   2020-05-28T18:24:50Z DEBUG The ipa-client-install command failed, exception: ScriptError: One of password / principal / keytab is required.

2. To review a log file interactively, open the end of the log file using the less utility and use the ↑ and ↓ arrow keys to navigate.

   [user@server ~]$ sudo less -N +G /var/log/ipaclient-install.log

Procedure

1. Ensure that dynamic updates for the DNS zone the client is in are enabled:

   [user@server ~]$ ipa dnszone-mod idm.example.com. --dynamic-update=TRUE

2. Ensure that the IdM server running the DNS service has port 53 opened for both TCP and UDP protocols.

   [user@server ~]$ sudo firewall-cmd --permanent --add-port=53/tcp --add-port=53/udp
   [sudo] password for user:
   success
   [user@server ~]$ firewall-cmd --runtime-to-permanent
   success

3. Use the grep utility to retrieve the contents of nsupdate commands from /var/log/client-install.log to see which DNS record updates are failing.

   [user@server ~]$ sudo grep nsupdate /var/log/ipaclient-install.log

Procedure

1. Remove /etc/krb5.keytab.

   [user@client ~]$ sudo rm /etc/krb5.keytab
   [sudo] password for user:
   [user@client ~]$ ls /etc/krb5.keytab
   ls: cannot access '/etc/krb5.keytab': No such file or directory

2. Retry the IdM client installation.

1. Re-create the client machine with the same host name.

2. Run the ipa-client-install --force-join command on the client machine:

   # ipa-client-install --force-join

3. The script prompts for a user whose identity will be used to re-enroll the client. This could be, for example, a hostadmin user with the Enrollment Administrator role:

   User authorized to enroll computers: hostadmin
   Password for hostadmin@EXAMPLE.COM:

Procedure

1. Re-create the client machine with the same host name.

2. Copy the keytab file from the backup location to the re-created client machine, for example its /tmp/ directory.

   Important

   Do not put the keytab in the /etc/krb5.keytab file as old keys are removed from this location during the execution of the ipa-client-install installation script.

3. Use the ipa-client-install utility to re-enroll the client. Specify the keytab location with the --keytab option:

   # ipa-client-install --keytab /tmp/krb5.keytab

   Note

   The keytab specified in the --keytab option is only used when authenticating to initiate the re-enrollment. During the re-enrollment, IdM generates a new keytab for the client.

Procedure

1. Enter the ipa-client-install --uninstall command:

   [root@client ~]# ipa-client-install --uninstall

2. Optional: Check that you cannot obtain a Kerberos ticket-granting ticket (TGT) for an IdM user:

   [root@client ~]# kinit admin
   kinit: Client 'admin@EXAMPLE.COM' not found in Kerberos database while getting initial credentials
   [root@client ~]#

   If a Kerberos TGT ticket has been returned successfully, follow the additional uninstallation steps in Uninstalling an IdM client: additional steps after multiple past installations.

3. On the client, remove old Kerberos principals from each identified keytab other than /etc/krb5.keytab:

   [root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM

4. On an IdM server, remove all DNS entries for the client host from IdM:

   [root@server ~]# ipa dnsrecord-del
   Record name: old-client-name
   Zone name: idm.example.com
   No option to delete specific record provided.
   Delete all? Yes/No (default No): true
   ------------------------
   Deleted record "old-client-name"

5. On the IdM server, remove the client host entry from the IdM LDAP server. This removes all services and revokes all certificates issued for that host:

   [root@server ~]# ipa host-del client.idm.example.com

   Important

   Removing the client host entry from the IdM LDAP server is crucial if you think you might re-enroll the client in the future, with a different IP address or a different hostname.

Procedure

1. Check the /etc/krb5.conf.ipa file:

   • If the contents of the /etc/krb5.conf.ipa file are the same as the contents of the krb5.conf file prior to the installation of the IdM client, you can:

     1. Remove the /etc/krb5.conf file:

        # rm /etc/krb5.conf

     2. Rename the /etc/krb5.conf.ipa file into /etc/krb5.conf:

        # mv /etc/krb5.conf.ipa /etc/krb5.conf

   • If the contents of the /etc/krb5.conf.ipa file are not the same as the contents of the krb5.conf file prior to the installation of the IdM client, you can at least restore the Kerberos configuration to the state directly after the installation of the operating system:

   1. Re-install the krb5-libs package:

      # dnf reinstall krb5-libs

      As a dependency, this command will also re-install the krb5-workstation package and the original version of the /etc/krb5.conf file.

2. Remove the var/log/ipaclient-install.log file if present.

Procedure

1. Enter the ipa-client-install --uninstall command:

   [root@client ~]# ipa-client-install --uninstall

2. Optional: Check that you cannot obtain a Kerberos ticket-granting ticket (TGT) for an IdM user:

   [root@client ~]# kinit admin
   kinit: Client 'admin@EXAMPLE.COM' not found in Kerberos database while getting initial credentials
   [root@client ~]#

   If a Kerberos TGT ticket has been returned successfully, follow the additional uninstallation steps in Uninstalling an IdM client: additional steps after multiple past installations.

3. On the client, remove old Kerberos principals from each identified keytab other than /etc/krb5.keytab:

   [root@client ~]# ipa-rmkeytab -k /path/to/keytab -r EXAMPLE.COM

4. On an IdM server, remove all DNS entries for the client host from IdM:

   [root@server ~]# ipa dnsrecord-del
   Record name: old-client-name
   Zone name: idm.example.com
   No option to delete specific record provided.
   Delete all? Yes/No (default No): true
   ------------------------
   Deleted record "old-client-name"

5. On the IdM server, remove the client host entry from the IdM LDAP server. This removes all services and revokes all certificates issued for that host:

   [root@server ~]# ipa host-del client.idm.example.com

   Important

   Removing the client host entry from the IdM LDAP server is crucial if you think you might re-enroll the client in the future, with a different IP address or a different hostname.

Procedure

1. Check the /etc/krb5.conf.ipa file:

   • If the contents of the /etc/krb5.conf.ipa file are the same as the contents of the krb5.conf file prior to the installation of the IdM client, you can:

     1. Remove the /etc/krb5.conf file:

        # rm /etc/krb5.conf

     2. Rename the /etc/krb5.conf.ipa file into /etc/krb5.conf:

        # mv /etc/krb5.conf.ipa /etc/krb5.conf

   • If the contents of the /etc/krb5.conf.ipa file are not the same as the contents of the krb5.conf file prior to the installation of the IdM client, you can at least restore the Kerberos configuration to the state directly after the installation of the operating system:

   1. Re-install the krb5-libs package:

      # dnf reinstall krb5-libs

      As a dependency, this command will also re-install the krb5-workstation package and the original version of the /etc/krb5.conf file.

2. Remove the var/log/ipaclient-install.log file if present.

Procedure

1. Enter ipa-replica-install with these options:

   • --setup-dns to configure the replica as a DNS server

   • --forwarder to specify a per-server forwarder, or --no-forwarder if you do not want to use any per-server forwarders. To specify multiple per-server forwarders for failover reasons, use --forwarder multiple times.

     Note

     The ipa-replica-install utility accepts a number of other options related to DNS settings, such as --no-reverse or --no-host-dns. For more information about them, see the ipa-replica-install(1) man page.

   • --setup-ca to include a CA on the replica

   For example, to set up a replica with an integrated DNS server and a CA that forwards all DNS requests not managed by the IdM servers to the DNS server running on IP 192.0.2.1:

   # ipa-replica-install --setup-dns --forwarder 192.0.2.1 --setup-ca

2. After the installation completes, add a 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 you install an IdM DNS server.

Procedure

1. Enter ipa-replica-install with these options:

   • --setup-dns to configure the replica as a DNS server
   • --forwarder to specify a per-server forwarder, or --no-forwarder if you do not want to use any per-server forwarders. To specify multiple per-server forwarders for failover reasons, use --forwarder multiple times.

   For example, to set up a replica with an integrated DNS server that forwards all DNS requests not managed by the IdM servers to the DNS server running on IP 192.0.2.1:

   # ipa-replica-install --setup-dns --forwarder 192.0.2.1

   Note

   The ipa-replica-install utility accepts a number of other options related to DNS settings, such as --no-reverse or --no-host-dns. For more information about them, see the ipa-replica-install(1) man page.

2. After the installation completes, add a 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 you install an IdM DNS server.

Procedure

1. Enter ipa-replica-install with the --setup-ca option.

   # ipa-replica-install --setup-ca

2. Add the newly created IdM DNS service records to your DNS server:

   1. Export the IdM DNS service records into a file in the nsupdate format:

      $ ipa dns-update-system-records --dry-run --out dns_records_file.nsupdate

   2. Submit a DNS update request to your DNS server using the nsupdate utility and the dns_records_file.nsupdate file. For more information, see Updating External DNS Records Using nsupdate in RHEL 7 documentation. Alternatively, refer to your DNS server documentation for adding DNS records.

Procedure

1. Create a user on the new replica:

   [admin@new_replica ~]$ ipa user-add test_user

2. Make sure the user is visible on another replica:

   [admin@another_replica ~]$ ipa user-show test_user

Procedure

1. Use the tail command to display the latest errors from the primary log file /var/log/ipareplica-install.log. The following example displays the last 10 lines.

   [user@replica ~]$ sudo tail -n 10 /var/log/ipareplica-install.log
   [sudo] password for user:
     func(installer)
   File "/usr/lib/python3.6/site-packages/ipaserver/install/server/replicainstall.py", line 424, in decorated
     func(installer)
   File "/usr/lib/python3.6/site-packages/ipaserver/install/server/replicainstall.py", line 785, in promote_check
     ensure_enrolled(installer)
   File "/usr/lib/python3.6/site-packages/ipaserver/install/server/replicainstall.py", line 740, in ensure_enrolled
     raise ScriptError("Configuration of client side components failed!")
   
   2020-05-28T18:24:51Z DEBUG The ipa-replica-install command failed, exception: ScriptError: Configuration of client side components failed!
   2020-05-28T18:24:51Z ERROR Configuration of client side components failed!
   2020-05-28T18:24:51Z ERROR The ipa-replica-install command failed. See /var/log/ipareplica-install.log for more information

2. To review the log file interactively, open the end of the log file using the less utility and use the ↑ and ↓ arrow keys to navigate.

   [user@replica ~]$ sudo less -N +G /var/log/ipareplica-install.log

3. Optional: While /var/log/ipareplica-install.log is the primary log file for a replica installation, you can gather additional troubleshooting information by repeating this review process with additional files on the replica and the server.

   On the replica:

   [user@replica ~]$ sudo less -N +G /var/log/ipareplica-conncheck.log
   [user@replica ~]$ sudo less -N +G /var/log/ipaclient-install.log
   [user@replica ~]$ sudo less -N +G /var/log/httpd/error_log
   [user@replica ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/access
   [user@replica ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/errors
   [user@replica ~]$ sudo less -N +G /var/log/ipaserver-install.log

   On the server:

   [user@server ~]$ sudo less -N +G /var/log/httpd/error_log
   [user@server ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/access
   [user@server ~]$ sudo less -N +G /var/log/dirsrv/slapd-INSTANCE-NAME/errors

Procedure

1. To review a log file interactively, open the end of the log file using the less utility and use the ↑ and ↓ arrow keys to navigate, while searching for ScriptError entries. The following example opens /var/log/pki/pki-ca-spawn.$TIME_OF_INSTALLATION.log.

   [user@server ~]$ sudo less -N +G /var/log/pki/pki-ca-spawn.20200527185902.log

2. Gather additional troubleshooting information by repeating this review process with all the CA installation error log files.

Procedure

1. Uninstall the IdM server software on the host you are trying to configure as an IdM replica.

   [root@replica ~]# ipa-server-install --uninstall

2. On all other servers in the topology, use the ipa server-del command to delete any references to the replica that did not install properly.

   [root@other-replica ~]# ipa server-del replica.idm.example.com

3. Attempt installing the replica.

4. If you continue to experience difficulty installing an IdM replica because of repeated failed installations, reinstall the operating system.

   One of the requirements for installing an IdM replica is a clean system without any customization. Failed installations may have compromised the integrity of the host by unexpectedly modifying system files.

Procedure

1. Synchronize the system clocks manually or with chronyd.

   Synchronizing manually

   Display the system time on the server and set the replica’s time to match.

   [user@server ~]$ date
   Thu May 28 21:03:57 EDT 2020
   
   [user@replica ~]$ sudo timedatectl set-time '2020-05-28 21:04:00'

   • Synchronizing with chronyd:

     See Using the Chrony suite to configure NTP to configure and set system time with chrony tools.

2. Attempt the IdM replica installation again.

1. Select IPA Server → Topology → Topology Graph.
2. If you make any changes to the topology that are not immediately reflected in the graph, click Refresh.

Procedure

1. In the topology graph, hover your mouse over one of the server nodes.

   Figure 23.9. Domain or CA options

   
2. Click on the domain or the ca part of the circle depending on what type of topology segment you want to create.

3. A new arrow representing the new replication agreement appears under your mouse pointer. Move your mouse to the other server node, and click on it.

   Figure 23.10. Creating a new segment

   
4. In the Add topology segment window, click Add to confirm the properties of the new segment.

Procedure

1. Click on an arrow representing the replication agreement you want to remove. This highlights the arrow.

   Figure 23.12. Topology segment highlighted

   
2. Click Delete.

3. In the Confirmation window, click OK.

   IdM removes the topology segment between the two servers, which deletes their replication agreement. The topology graph now shows the updated replication topology:

   Figure 23.13. Topology segment deleted

   

Procedure

1. [Optional] If you do not know the name of the specific replication segment that you want to remove, display all segments available. Use the ipa topologysegment-find command. When prompted, provide the required topology suffix: domain or ca. For example:

   $ ipa topologysegment-find
   Suffix name: domain
   ------------------
   8 segments matched
   ------------------
     Segment name: new_segment
     Left node: server1.example.com
     Right node: server2.example.com
     Connectivity: both
   
   ...
   
   ----------------------------
   Number of entries returned 8
   ----------------------------

   Locate the required segment in the output.

2. Remove the topology segment joining the two servers:

   $ ipa topologysegment-del
   Suffix name: domain
   Segment name: new_segment
   -----------------------------
   Deleted segment "new_segment"
   -----------------------------

   Deleting the segment removes the replication agreement.

Procedure

1. Select IPA Server → Topology → IPA Servers.

2. Click on the name of the server you want to delete.

   Figure 23.14. Selecting a server

   
3. Click Delete Server.

1. Enable the required repository:

   # subscription-manager repos --enable rhel-9-for-x86_64-appstream-rpms

2. Install the IdM Ansible roles:

   # dnf install ansible-freeipa

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.

Procedure

1. Open the inventory file for editing. Specify the fully-qualified domain names (FQDN) of the hosts to become IdM replicas. The FQDNs must be valid DNS names:

   • Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.

   • The host name must be all lower-case.

     Example of a simple inventory hosts file with only the replicas' FQDN defined

     [ipareplicas]
     replica1.idm.example.com
     replica2.idm.example.com
     replica3.idm.example.com
     [...]

     If the IdM server is already deployed and the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values.

2. Optional: Provide additional information in the inventory file based on how you have designed your topology:

   Scenario 1

   If you want to avoid autodiscovery and have all replicas listed in the [ipareplicas] section use a specific IdM server, set the server in the [ipaservers] section of the inventory file.

   Example inventory hosts file with the FQDN of the IdM server and replicas defined

   [ipaservers]
   server.idm.example.com
   
   [ipareplicas]
   replica1.idm.example.com
   replica2.idm.example.com
   replica3.idm.example.com
   [...]

   Scenario 2

   Alternatively, if you want to avoid autodiscovery but want to deploy specific replicas with specific servers, set the servers for specific replicas individually in the [ipareplicas] section in the inventory file.

   Example inventory file with a specific IdM server defined for a specific replica

   [ipaservers]
   server.idm.example.com
   replica1.idm.example.com
   
   [ipareplicas]
   replica2.idm.example.com
   replica3.idm.example.com ipareplica_servers=replica1.idm.example.com

   In the example above, replica3.idm.example.com uses the already deployed replica1.idm.example.com as its replication source.

   Scenario 3

   If you are deploying several replicas in one batch and time is a concern to you, multitier replica deployment can be useful for you. Define specific groups of replicas in the inventory file, for example [ipareplicas_tier1] and [ipareplicas_tier2], and design separate plays for each group in the install-replica.yml playbook.

   Example inventory file with replica tiers defined

   [ipaservers]
   server.idm.example.com
   
   [ipareplicas_tier1]
   replica1.idm.example.com
   
   [ipareplicas_tier2]
   replica2.idm.example.com \ ipareplica_servers=replica1.idm.example.com,server.idm.example.com

   The first entry in ipareplica_servers will be used. The second entry will be used as a fallback option. When using multiple tiers for deploying IdM replicas, you must have separate tasks in the playbook to first deploy replicas from tier1 and then replicas from tier2:

   Example of a playbook file with different plays for different replica groups

   ---
   - name: Playbook to configure IPA replicas (tier1)
     hosts: ipareplicas_tier1
     become: true
   
     roles:
     - role: ipareplica
       state: present
   
   - name: Playbook to configure IPA replicas (tier2)
     hosts: ipareplicas_tier2
     become: true
   
     roles:
     - role: ipareplica
       state: present

3. Optional: Provide additional information regarding firewalld and DNS:

   Scenario 1

   If you want the replica to use a specified firewalld zone, for example an internal one, you can specify it in the inventory file. 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 a simple inventory hosts file with a custom firewalld zone

   [ipaservers]
   server.idm.example.com
   
   [ipareplicas]
   replica1.idm.example.com
   replica2.idm.example.com
   replica3.idm.example.com
   [...]
   
   [ipareplicas:vars]
   ipareplica_firewalld_zone=custom zone

   Scenario 2

   If you want the replica to host the IdM DNS service, add the ipareplica_setup_dns=true line to the [ipareplicas:vars] section. Additionally, specify if you want to use per-server DNS forwarders:

   • To configure per-server forwarders, add the ipareplica_forwarders variable and a list of strings to the [ipareplicas:vars] section, for example: ipareplica_forwarders=192.0.2.1,192.0.2.2
   • To configure no per-server forwarders, add the following line to the [ipareplicas:vars] section: ipareplica_no_forwarders=true.
   • To configure per-server forwarders based on the forwarders listed in the /etc/resolv.conf file of the replica, add the ipareplica_auto_forwarders variable to the [ipareplicas:vars] section.

   Example inventory file with instructions to set up DNS and per-server forwarders on the replicas

   [ipaservers]
   server.idm.example.com
   
   [ipareplicas]
   replica1.idm.example.com
   replica2.idm.example.com
   replica3.idm.example.com
   [...]
   
   [ipareplicas:vars]
   ipareplica_setup_dns=true
   ipareplica_forwarders=192.0.2.1,192.0.2.2

   Scenario 3

   Specify the DNS resolver using the ipaclient_configure_dns_resolve and ipaclient_dns_servers options (if available) to simplify cluster deployments. This is especially useful if your IdM deployment is using integrated DNS:

   An inventory file snippet specifying a DNS resolver:

   [...]
   [ipaclient:vars]
   ipaclient_configure_dns_resolver=true
   ipaclient_dns_servers=192.168.100.1

   Note

   The ipaclient_dns_servers list must contain only IP addresses. Host names are not allowed.

Procedure

1. Specify the password of a user authorized to deploy replicas, for example the IdM admin.

   • Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example install-replica.yml:

     Example playbook file using principal from inventory file and password from an Ansible Vault file

     - name: Playbook to configure IPA replicas
       hosts: ipareplicas
       become: true
       vars_files:
       - playbook_sensitive_data.yml
     
       roles:
       - role: ipareplica
         state: present

     For details how to use Ansible Vault, see the official Ansible Vault documentation.

   • Less securely, provide the credentials of admin directly in the inventory file. Use the ipaadmin_password option in the [ipareplicas:vars] section of the inventory file. The inventory file and the install-replica.yml playbook file can then look as follows:

     Example inventory hosts.replica file

     [...]
     [ipareplicas:vars]
     ipaadmin_password=Secret123

     Example playbook using principal and password from inventory file

     - name: Playbook to configure IPA replicas
       hosts: ipareplicas
       become: true
     
       roles:
       - role: ipareplica
         state: present

   • Alternatively but also less securely, provide the credentials of another user authorized to deploy a replica directly in the inventory file. To specify a different authorized user, use the ipaadmin_principal option for the user name, and the ipaadmin_password option for the password. The inventory file and the install-replica.yml playbook file can then look as follows:

     Example inventory hosts.replica file

     [...]
     [ipareplicas:vars]
     ipaadmin_principal=my_admin
     ipaadmin_password=my_admin_secret123

     Example playbook using principal and password from inventory file

     - name: Playbook to configure IPA replicas
       hosts: ipareplicas
       become: true
     
       roles:
       - role: ipareplica
         state: present

Procedure

1. Open your inventory file for editing.

2. Specify the fully-qualified hostname (FQDN) of the host to become an IdM client. The fully qualified domain name must be a valid DNS name:

   • Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case. No capital letters are allowed.

   If the SRV records are set properly in the IdM DNS zone, the script automatically discovers all the other required values.

   Example of a simple inventory hosts file with only the client FQDN defined

   [ipaclients]
   client.idm.example.com
   [...]

3. Specify the credentials for enrolling the client. The following authentication methods are available:

   • The password of a user authorized to enroll clients. This is the default option.

     • Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example install-client.yml, directly:

       Example playbook file using principal from inventory file and password from an Ansible Vault file

       - name: Playbook to configure IPA clients with username/password
         hosts: ipaclients
         become: true
         vars_files:
         - playbook_sensitive_data.yml
       
         roles:
         - role: ipaclient
           state: present

     • Less securely, provide the credentials of admin using the ipaadmin_password option in the [ipaclients:vars] section of the inventory/hosts file. Alternatively, to specify a different authorized user, use the ipaadmin_principal option for the user name, and the ipaadmin_password option for the password. The inventory/hosts inventory file and the install-client.yml playbook file can then look as follows:

       Example inventory hosts file

       [...]
       [ipaclients:vars]
       ipaadmin_principal=my_admin
       ipaadmin_password=Secret123

       Example Playbook using principal and password from inventory file

       - name: Playbook to unconfigure IPA clients
         hosts: ipaclients
         become: true
       
         roles:
         - role: ipaclient
           state: true

   • The client keytab from the previous enrollment if it is still available.

     This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the #ipaclient_keytab option, specifying the path to the file storing the keytab, for example in the [ipaclient:vars] section of inventory/hosts.

   • A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the ipaclient_use_otp=true option in your inventory file. For example, you can uncomment the ipaclient_use_otp=true option in the [ipaclients:vars] section of the inventory/hosts file. Note that with OTP you must also specify one of the following options:

     • The password of a user authorized to enroll clients, for example by providing a value for ipaadmin_password in the [ipaclients:vars] section of the inventory/hosts file.
     • The admin keytab, for example by providing a value for ipaadmin_keytab in the [ipaclients:vars] section of inventory/hosts.

4. Optional: Specify the DNS resolver using the ipaclient_configure_dns_resolve and ipaclient_dns_servers options (if available) to simplify cluster deployments. This is especially useful if your IdM deployment is using integrated DNS:

   An inventory file snippet specifying a DNS resolver:

   [...]
   [ipaclients:vars]
   ipaadmin_password: "{{ ipaadmin_password }}"
   ipaclient_domain=idm.example.com
   ipaclient_configure_dns_resolver=true
   ipaclient_dns_servers=192.168.100.1

   Note

   The ipaclient_dns_servers list must contain only IP addresses. Host names are not allowed.

5. Starting with RHEL 9.3, you can also specify the ipaclient_subid: true option to have subid ranges configured for IdM users on the IdM level.

Procedure

1. Specify the fully-qualified hostname (FQDN) of the host to become an IdM client. The fully qualified domain name must be a valid DNS name:

   • Only numbers, alphabetic characters, and hyphens (-) are allowed. For example, underscores are not allowed and can cause DNS failures.
   • The host name must be all lower-case. No capital letters are allowed.

2. Specify other options in the relevant sections of the inventory/hosts file:

   • The FQDN of the servers in the [ipaservers] section to indicate which IdM server the client will be enrolled with

   • One of the two following options:

     • The ipaclient_domain option in the [ipaclients:vars] section to indicate the DNS domain name of the IdM server the client will be enrolled with

     • The ipaclient_realm option in the [ipaclients:vars] section to indicate the name of the Kerberos realm controlled by the IdM server

       Example of an inventory hosts file with the client FQDN, the server FQDN and the domain defined

       [ipaclients]
       client.idm.example.com
       
       [ipaservers]
       server.idm.example.com
       
       [ipaclients:vars]
       ipaclient_domain=idm.example.com
       [...]

3. Specify the credentials for enrolling the client. The following authentication methods are available:

   • The password of a user authorized to enroll clients. This is the default option.

     • Red Hat recommends using the Ansible Vault to store the password, and referencing the Vault file from the playbook file, for example install-client.yml, directly:

       Example playbook file using principal from inventory file and password from an Ansible Vault file

       - name: Playbook to configure IPA clients with username/password
         hosts: ipaclients
         become: true
         vars_files:
         - playbook_sensitive_data.yml
       
         roles:
         - role: ipaclient
           state: present

   • Less securely, the credentials of admin to be provided using the ipaadmin_password option in the [ipaclients:vars] section of the inventory/hosts file. Alternatively, to specify a different authorized user, use the ipaadmin_principal option for the user name, and the ipaadmin_password option for the password. The install-client.yml playbook file can then look as follows:

     Example inventory hosts file

     [...]
     [ipaclients:vars]
     ipaadmin_principal=my_admin
     ipaadmin_password=Secret123

     Example Playbook using principal and password from inventory file

     - name: Playbook to unconfigure IPA clients
       hosts: ipaclients
       become: true
     
       roles:
       - role: ipaclient
         state: true

   • The client keytab from the previous enrollment if it is still available:

     This option is available if the system was previously enrolled as an Identity Management client. To use this authentication method, uncomment the ipaclient_keytab option, specifying the path to the file storing the keytab, for example in the [ipaclient:vars] section of inventory/hosts.

   • A random, one-time password (OTP) to be generated during the enrollment. To use this authentication method, use the ipaclient_use_otp=true option in your inventory file. For example, you can uncomment the #ipaclient_use_otp=true option in the [ipaclients:vars] section of the inventory/hosts file. Note that with OTP you must also specify one of the following options:

     • The password of a user authorized to enroll clients, for example by providing a value for ipaadmin_password in the [ipaclients:vars] section of the inventory/hosts file.
     • The admin keytab, for example by providing a value for ipaadmin_keytab in the [ipaclients:vars] section of inventory/hosts.
4. Starting with RHEL 9.3, you can also specify the ipaclient_subid: true option to have subid ranges configured for IdM users on the IdM level.

Procedure

1. SSH to an IdM host as an IdM user with a role that has the Host Enrollment privilege and a permission to add DNS records:

   $ ssh admin@server.idm.example.com

2. Generate an OTP for the new client:

   [admin@server ~]$ ipa host-add client.idm.example.com --ip-address=172.25.250.11 --random
    --------------------------------------------------
    Added host "client.idm.example.com"
    --------------------------------------------------
     Host name: client.idm.example.com
     Random password: W5YpARl=7M.n
     Password: True
     Keytab: False
     Managed by: server.idm.example.com

   The --ip-address=<your_host_ip_address> option adds the host to IdM DNS with the specified IP address.

3. Exit the IdM host:

   $ exit
   logout
   Connection to server.idm.example.com closed.

4. On the ansible controller, update the inventory file to include the random password:

   [...]
   [ipaclients]
   client.idm.example.com
   
   [ipaclients:vars]
   ipaclient_domain=idm.example.com
   ipaclient_otp=W5YpARl=7M.n
   [...]

5. If your ansible controller is running RHEL ⇐ 9.1, install the kinit utility provided by the krb5-workstation package:

   $ sudo dnf install krb5-workstation

6. Run the playbook to install the client:

   $ ansible-playbook -i inventory install-client.yml

Procedure

1. On idmserver, install the IdM Certificate Server CA:

   [root@idmserver ~] ipa-ca-install

2. On each IdM host in the topology, run the ipa-certupdate utility to update the host with the information about the new certificate from the IdM LDAP.

   Important

   If you do not run ipa-certupdate after generating the IdM CA certificate, the certificate will not be distributed to the other IdM machines.

Procedure

1. Start the installation:

   [root@idmserver ~] ipa-ca-install --external-ca

2. Wait till the command-line interface informs you that a certificate signing request (CSR) has been saved.
3. Submit the CSR to the external CA.
4. Copy the issued certificate to the IdM server.

5. Continue the installation by adding the certificates and full path to the external CA files to ipa-ca-install:

   [root@idmserver ~]# ipa-ca-install --external-cert-file=/root/master.crt --external-cert-file=/root/ca.crt

6. On each IdM host in the topology, run the ipa-certupdate utility to update the host with the information about the new certificate from the IdM LDAP.

   Important

   Failing to run ipa-certupdate after generating the IdM CA certificate means that the certificate will not be distributed to the other IdM machines.