1. Make sure 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,123/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-ldap,freeipa-ldaps,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

4. Optional. To verify that the ports are available now, use the nc, telnet, or nmap utilities to connect to a port or run a port scan.

Procedure

1. Enable the idm:DL1 stream:

   # yum module enable idm:DL1

2. Switch to the RPMs delivered through the idm:DL1 stream:

   # yum distro-sync

3. Choose one of the following options, depending on your IdM requirements:

   • To download the packages necessary for installing an IdM server without an integrated DNS:

     # yum module install idm:DL1/server

   • To download the packages necessary for installing an IdM server with an integrated DNS:

     # yum module install idm:DL1/dns

   • To download the packages necessary for installing an IdM server that has a trust agreement with Active Directory:

     # yum module install idm:DL1/adtrust

   • To download the packages from multiple profiles, for example the adtrust and dns profiles:

     # yum module install idm:DL1/{dns,adtrust}

   • To download the packages necessary for installing an IdM client:

     # yum module install idm:DL1/client

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.example.com]:
     Please confirm the domain name [example.com]:
     Please provide a realm name [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 DNS forwarders.

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

   • To configure DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

     • 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, your environment will be isolated, and names from other DNS domains in your infrastructure will not be resolved.

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 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 CA, use also the --external-ca-type option. For details, see the ipa-server-install(1) man page.

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.example.com]:
     Please confirm the domain name [example.com]:
     Please provide a realm name [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 DNS forwarders.

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

   • To configure DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

     • 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, your environment will be isolated, and names from other DNS domains in your infrastructure will not be resolved.

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 Section 4.1, “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 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.example.com]:
     Please confirm the domain name [example.com]:
     Please provide a realm name [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 DNS forwarders.

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

   • To configure DNS forwarders, enter yes, and then follow the instructions on the command line. The installation process will add the forwarder IP addresses to the /etc/named.conf file on the installed IdM server.

     • 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, your environment will be isolated, and names from other DNS domains in your infrastructure will not be resolved.

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.example.com]:
     Please confirm the domain name [example.com]:
     Please provide a realm name [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. The installation script now configures the server. Wait for the operation to complete.

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

   # ipa-server-install --external-ca

   If you are using the Microsoft Certificate Services CA, use also the --external-ca-type option. For details, see the ipa-server-install(1) man page.

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.example.com]:
     Please confirm the domain name [example.com]:
     Please provide a realm name [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 EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended

   If you are using the Microsoft Certificate Services CA, use also the --external-ca-type option. For details, see the ipa-server-install(1) man page.

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

   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

   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
   • If the script fails to obtain some settings automatically, it prompts you for the values.
   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.

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.

Prerequisites

1. On a server in the domain, add the future client system as an IdM host. Use the --random option with the ipa host-add command to generate a one-time random password for the enrollment.

   $ ipa host-add client.example.com --random
    --------------------------------------------------
    Added host "client.example.com"
    --------------------------------------------------
     Host name: client.example.com
     Random password: W5YpARl=7M.n
     Password: True
     Keytab: False
     Managed by: server.example.com

   Note

   The generated password will become invalid after you use it to enroll the machine into the IdM domain. It will be replaced with a proper host keytab after the enrollment is finished.

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

   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

   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
   • If the script fails to obtain some settings automatically, it prompts you for the values.
   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.

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 12.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:

1. Re-create the client machine with the same host name.
2. Copy the keytab file from the backup location to the /etc/ directory on the re-created client machine.

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

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

   Note

   The keytab specified in the --keytab option is only used when authenticating to initiate the 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): yes
   ------------------------
   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:

      # yum 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): yes
   ------------------------
   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:

      # yum 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.

1. On the Identity Management (IdM) server, add a new keytab for every service identified in Section 16.1, “Prerequisites”.

   [root@server ~]# ipa service-add service_name/new-client-name

2. Generate certificates for services that had a certificate assigned in Section 16.1, “Prerequisites”. You can do this:

   • Using the IdM administration tools
   • Using the certmonger utility
3. Re-add the client to the host groups identified in Section 16.1, “Prerequisites”.

Procedure

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

   • --setup-dns to configure the replica as the DNS server
   • --forwarder to specify a forwarder, or --no-forwarder if you do not want to use any forwarders. To specify multiple 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 installed an IdM DNS server.

Procedure

1. Run 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 log files listed above.

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 (ntp is no longer supported in RHEL 8).

   • 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:

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

2. Attempt the IdM replica installation again.

1. Installing the ansible-freeipa package;
2. Deploying an IdM server with an integrated CA using an Ansible playbook;
3. Deploying an IdM server with an external CA using an Ansible-playbook.

1. Enable the required repository:

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

2. Install Ansible:

   # yum install ansible

3. Install the IdM Ansible roles:

   # yum install ansible-freeipa

   The roles are installed to the /usr/share/ansible/roles/ directory.

1. Installing the ansible-freeipa package;

2. Setting the parameters of the IdM replica deployment, namely:

   • Specifying the base, server and client variables for installing the IdM replica;
   • Specifying the credentials for installing the IdM replica using an Ansible playbook;
3. Deploying an IdM replica using an Ansible playbook.

1. Enable the required repository:

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

2. Install Ansible:

   # yum install ansible

3. Install the IdM Ansible roles:

   # yum install ansible-freeipa

   The roles are installed to the /usr/share/ansible/roles/ directory.

1. Installing the ansible-freeipa package;

2. Setting the parameters of the IdM client deployment to correspond to your deployment scenario:

   • Setting the parameters of the inventory file for the autodiscovery client installation mode;
   • Setting the parameters of the inventory file for when autodiscovery is not possible during client installation;
3. Checking the parameters in install-client.yml;
4. Deploying an IdM client using an Ansible playbook;
5. Testing an Identity Management client after installation.

1. Enable the required repository:

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

2. Install Ansible:

   # yum install ansible

3. Install the IdM Ansible roles:

   # yum install ansible-freeipa

   The roles are installed to the /usr/share/ansible/roles/ directory.

Procedure

1. Log in to the IdM Web UI with administrator privileges. For details, see Accessing the IdM Web UI in a web browser.
2. In the IdM Web UI, click the IPA Server tab.
3. In the IPA Server tab, click the Trusts tab.

4. Select the trust you want to remove.

   

5. Click the Delete button.

6. In the Remove trusts dialog box, click Delete.

   

1. Upgrade the system to the latest RHEL 7 version.
2. Ensure that the domain level for your domain is set to 1. For more information, see Displaying and Raising the Domain Level in the Linux Domain Identity, Authentication, and Policy Guide for RHEL 7.

3. Update the ipa-* packages to their latest version:

   [root@rhel7 ~]# dnf update ipa-*

   Warning

   When upgrading multiple Identity Management (IdM) servers, wait at least 10 minutes between each upgrade.

   When two or more servers are upgraded simultaneously or with only short intervals between the upgrades, there is not enough time to replicate the post-upgrade data changes throughout the topology, which can result in conflicting replication events.

1. The latest version of Red Hat Enterprise Linux is installed on the system. For more information, see Performing a standard RHEL installation.
2. Ensure the system is an IdM client enrolled into the domain for which rhel7.example.com IdM server is authoritative. For more information, see Installing an IdM client: Basic scenario.
3. Ensure the system meets the requirements for IdM server installation.

4. Ensure the system uses a time server that is synchronized with rhel7.example.com.

   Note

   In RHEL 8, IdM does not provide its own time server: the installation of IdM on rhel8.example.com does not result in the installation of an NTP server on the host.

5. Ensure the system meets the requirements for installing a replica on an IdM client.

6. Update the ipa-* packages to their latest version:

   [root@rhel7 ~]# dnf update ipa-*

Procedure

1. Optionally, check if rhel7.example.com is generating the CRL:

   [root@rhel7 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2019-10-31 12:00:00
   Last CRL Number: 6
   The ipa-crlgen-manage command was successful

2. Stop generating the CRL on the rhel7.example.com server:

   [root@rhel7 ~]# ipa-crlgen-manage disable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   CRL generation disabled on the local host. Please make sure to configure CRL generation on another master with ipa-crlgen-manage enable.
   The ipa-crlgen-manage command was successful

3. Optionally, check if the rhel7.example.com server stopped generating the CRL:

   [root@rhel7 ~]# ipa-crlgen-manage status

Procedure

1. To start generating CRL on rhel8.example.com, use the ipa-crlgen-manage enable command:

   [root@rhel8 ~]# ipa-crlgen-manage enable
   Stopping pki-tomcatd
   Editing /var/lib/pki/pki-tomcat/conf/ca/CS.cfg
   Starting pki-tomcatd
   Editing /etc/httpd/conf.d/ipa-pki-proxy.conf
   Restarting httpd
   Forcing CRL update
   CRL generation enabled on the local host. Please make sure to have only a single CRL generation master.
   The ipa-crlgen-manage command was successful

2. To check if CRL generation is enabled, use the ipa-crlgen-manage status command:

   [root@rhel8 ~]# ipa-crlgen-manage status
   CRL generation: enabled
   Last CRL update: 2019-10-31 12:10:00
   Last CRL Number: 7
   The ipa-crlgen-manage command was successful