2.3. Installing an IdM Server: Introduction
2.3. Installing an IdM Server: Introduction Note The installation procedures and examples in the following sections are not mutually exclusive: you can combine them to achieve the required result. For example, you can install a server with integrated DNS and with an externally hosted root CA. The ipa-server-install utility installs and configures an IdM server. Before installing a server, see these sections: Section 2.3.1, "Determining Whether to Use Integrated DNS" Section 2.3.2, "Determining What CA Configuration to Use" The ipa-server-install utility provides a non-interactive installation mode which allows automated and unattended server setup. For details, see Section 2.3.7, "Installing a Server Non-Interactively" The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log . If the installation fails, the log can help you identify the problem. 2.3.1. Determining Whether to Use Integrated DNS IdM supports installing a server with integrated DNS or without integrated DNS. An IdM server with integrated DNS services The integrated DNS server provided by IdM is not designed to be used as a general-purpose DNS server. It only supports features related to IdM deployment and maintenance. It does not support some of the advanced DNS features. Red Hat strongly recommends IdM-integrated DNS for basic usage within the IdM deployment: When the IdM server also manages DNS, there is tight integration between DNS and native IdM tools which enables automating some of the DNS record management. Note that even if an IdM server is used as a master DNS server, other external DNS servers can still be used as slave servers. For example, if your environment is already using another DNS server, such as an Active Directory-integrated DNS server, you can delegate only the IdM primary domain to the IdM-integrated DNS. You are not required to migrate DNS zones over to the IdM-integrated DNS. Note If you need to issue certificates for IdM clients with an IP address in the Subject Alternative Name (SAN) extension, you must use the IdM integrated DNS service. To install a server with integrated DNS, see Section 2.3.3, "Installing a Server with Integrated DNS" An IdM server without integrated DNS services An external DNS server is used to provide the DNS services. Consider installing an IdM server without DNS in these situations: If you require advanced DNS features beyond the scope of the IdM DNS In environments with a well-established DNS infrastructure which allows you to use external DNS servers To install a server without integrated DNS, see Section 2.3.4, "Installing a Server Without Integrated DNS" Important Make sure your system meets the DNS requirements described in Section 2.1.5, "Host Name and DNS Configuration" . Maintenance Requirements for Integrated or External DNS When using an integrated DNS server, most of the DNS record maintenance is automated. You only must: set up correct delegation from the parent domain to the IdM servers For example, if the IdM domain name is ipa.example.com , it must be properly delegated from the example.com domain. Note You can verify the delegation using the following command: IP_address is the IP address of the server that manages the example.com DNS domain. If the delegation is correct, the command lists the IdM servers that have a DNS server installed. When using an external DNS server, you must: manually create the new domain on the DNS server fill the new domain manually with records from the zone file that is generated by the IdM installer manually update the records after installing or removing a replica, as well as after any changes in the service configuration, such as after an Active Directory trust is configured Preventing DNS Amplification Attacks The default configuration of the IdM-integrated DNS server allows all clients to issue recursive queries to the DNS server. If your server is deployed in a network with an untrusted client, change the server's configuration to limit recursion to authorized clients only. [1] To ensure that only authorized clients are allowed to issue recursive queries, add the appropriate access control list (ACL) statements to the /etc/named.conf file on your server. For example: 2.3.2. Determining What CA Configuration to Use IdM supports installing a server with an integrated IdM certificate authority (CA) or without a CA. Server with an integrated IdM CA This is the default configuration suitable for most deployments. Certificate System uses a CA signing certificate to create and sign the certificates in the IdM domain. Warning Red Hat strongly recommends to keep the CA services installed on more than one server. For information on installing a replica of the initial server including the CA services, see Section 4.5.4, "Installing a Replica with a CA" . If you install the CA on only one server, you risk losing the CA configuration without a chance of recovery if the CA server fails. See Section B.2.6, "Recovering a Lost CA Server" for details. The IdM CA signing certificate can be a root CA, which is also called self-signed , or it can be signed by an external CA. The IdM CA is the root CA This is the default configuration. To install a server with this configuration, see Section 2.3.3, "Installing a Server with Integrated DNS" and Section 2.3.4, "Installing a Server Without Integrated DNS" . An external CA is the root CA The IdM CA is subordinate to an external CA. However, all certificates for the IdM domain are still issued by the Certificate System instance. The external CA can be a corporate CA or a third-party CA, such as Verisign or Thawte. The external CA can be a root CA or a subordinate CA. The certificates issued within the IdM domain are potentially subject to restrictions set by the external root CA or intermediate CA certificates for attributes, such as the validity period, or domains for which certificates can be issued. To install a server with an externally-hosted root CA, see Section 2.3.5, "Installing a Server with an External CA as the Root CA" Server without a CA This configuration option is suitable for very rare cases when restrictions within the infrastructure do not allow to install certificate services with the server. You must request these certificates from a third-party authority prior to the installation: An LDAP server certificate and a private key An Apache server certificate and a private key Full CA certificate chain of the CA that issued the LDAP and Apache server certificates Warning Managing certificates without the integrated IdM CA presents a significant maintenance burden. For example, you must manually manage the Apache web server and LDAP server certificates of the IdM server. This includes: Creating and uploading certificates. Monitoring the expiration date of certificates. Note that the certmonger service does not track certificates if you installed IdM without the integrated CA. Renewing certificates before they expire to avoid outages. To install a server without an integrated CA, see Section 2.3.6, "Installing Without a CA" Note If you install an IdM domain without a CA, you can install the CA services afterwards. To install a CA to already existing IdM domain, see Section 26.8, "Installing a CA Into an Existing IdM Domain" . 2.3.3. Installing a Server with Integrated DNS Note If you are unsure what DNS or CA configuration is appropriate for you, see Section 2.3.1, "Determining Whether to Use Integrated DNS" and Section 2.3.2, "Determining What CA Configuration to Use" . To install a server with integrated DNS, provide the following information during the installation process: DNS forwarders The following DNS forwarder settings are supported: one or more forwarders (the --forwarder option in non-interactive installation) no forwarders (the --no-forwarders option in non-interactive installation) If you are unsure whether to use DNS forwarding, see Section 33.6, "Managing DNS Forwarding" . Reverse DNS zones The following reverse DNS zone settings are supported: automatic detection of the reverse zones that need to be created in IdM DNS (the default setting in interactive installation, the --auto-reverse option in non-interactive installation) no reverse zone auto-detection (the --no-reverse option in interactive installation) Note that the --allow-zone-overlap option is ignored if the --auto-reverse option is set. Using the combination of options: thus does not create reverse zones which would overlap with already existing DNS zones, for example on another DNS server. For non-interactive installation, add the --setup-dns option as well. Example 2.1. Installing a Server with Integrated DNS This procedure installs a server: with integrated DNS with integrated IdM CA as the root CA, which is the default CA configuration Run the ipa-server-install utility. The script prompts to configure an integrated DNS service. Enter yes . The script prompts for several required settings. To accept the default values in brackets, press Enter . To provide a value different than the proposed default value, enter the required value. Warning Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com , use IPA.EXAMPLE.COM for the Kerberos realm name. Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences. Enter the passwords for the Directory Server superuser, cn=Directory Manager , and for the admin IdM system user account. The script prompts for DNS forwarders. 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. See also the section called "Forward Policies" for details. If you do not want to use DNS forwarding, enter no . The script prompts to check if any DNS reverse (PTR) records for the IP addresses associated with the server need to be configured. 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. Note Using IdM to manage reverse zones is optional. You can use an external DNS service for this purpose instead. Enter yes to confirm the server configuration. The installation script now configures the server. Wait for the operation to complete. Add DNS delegation from the parent domain to the IdM DNS domain. For example, if the IdM DNS domain is ipa.example.com , add a name server (NS) record to the example.com parent domain. Important This step must be repeated each time an IdM DNS server is installed. The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, "Port Requirements" . To test the new server: Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. Run a command such as ipa user-find . On a new server, the command prints the only configured user: admin . 2.3.4. Installing a Server Without Integrated DNS Note If you are unsure what DNS or CA configuration is appropriate for you, see Section 2.3.1, "Determining Whether to Use Integrated DNS" and Section 2.3.2, "Determining What CA Configuration to Use" . To install a server without integrated DNS, run the ipa-server-install utility without any DNS-related options. Example 2.2. Installing a Server Without Integrated DNS This procedure installs a server: without integrated DNS with integrated IdM CA as the root CA, which is the default CA configuration Run the ipa-server-install utility. The script prompts to configure an integrated DNS service. Press Enter to select the default no option. The script prompts for several required settings. To accept the default values in brackets, press Enter . To provide a value different than the proposed default value, enter the required value. Warning Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com , use IPA.EXAMPLE.COM for the Kerberos realm name. Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences. Enter the passwords for the Directory Server superuser, cn=Directory Manager , and for the admin IdM system user account. Enter yes to confirm the server configuration. The installation script now configures the server. Wait for the operation to complete. 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. Important The server installation is not complete until you add the DNS records to the existing DNS servers. The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, "Port Requirements" . To test the new server: Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. Run a command such as ipa user-find . On a new server, the command prints the only configured user: admin . 2.3.5. Installing a Server with an External CA as the Root CA Note If you are unsure what DNS or CA configuration is appropriate for you, see Section 2.3.1, "Determining Whether to Use Integrated DNS" and Section 2.3.2, "Determining What CA Configuration to Use" . To install a server and chain it with an external CA as the root CA, pass these options with the ipa-server-install utility: --external-ca specifies that you want to use an external CA. --external-ca-type specifies the type of the external CA. See the ipa-server-install (1) man page for details. Otherwise, most of the installation procedure is the same as in Section 2.3.3, "Installing a Server with Integrated DNS" or Section 2.3.4, "Installing a Server Without Integrated DNS" . During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr : When this happens: 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. Important It can be necessary to request the appropriate extensions for the certificate. The CA signing certificate generated for Identity Management must be a valid CA certificate. This requires that you set the CA parameter in the basic constraints extension true . For further details, see the Basic Constraints section in RFC 5280 . 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. 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: Note The ipa-server-install --external-ca command can sometimes fail with the following error: This failure occurs when the *_proxy environmental variables are set. For a solution on how to fix this problem, see Section B.1.1, "External CA Installation Fails" 2.3.6. Installing Without a CA Note If you are unsure what DNS or CA configuration is appropriate for you, see Section 2.3.1, "Determining Whether to Use Integrated DNS" and Section 2.3.2, "Determining What CA Configuration to Use" . To install a server without a CA, you must provide the required certificates manually by adding options to the ipa-server-install utility. Other than that, most of the installation procedure is the same as in Section 2.3.3, "Installing a Server with Integrated DNS" or Section 2.3.4, "Installing a Server Without Integrated DNS" . Important You cannot install a server or replica using self-signed third-party server certificates. Certificates Required to Install an IdM Server without a CA For a successful CA-less IdM server installation, you must provide the following certificates: The LDAP server certificate and private key, supplied using these options: --dirsrv-cert-file for the certificate and private key files for the LDAP server certificate --dirsrv-pin for the password to access the private key in the files specified in --dirsrv-cert-file The Apache server certificate and private key, supplied using these options: --http-cert-file for the certificate and private key files for the Apache server certificate --http-pin for the password to access the private key in the files specified in --http-cert-file The full CA certificate chain of the CA that issued the LDAP and Apache server certificates, supplied using these options: --dirsrv-cert-file and --http-cert-file for the certificate files with the full CA certificate chain or a part of it You can provide the files specified in the --dirsrv-cert-file and --http-cert-file options in the following formats: Privacy-Enhanced Mail (PEM) encoded certificate (RFC 7468). Note that the IdM installer accepts concatenated PEM-encoded objects. Distinguished Encoding Rules (DER) PKCS #7 certificate chain objects PKCS #8 private key objects PKCS #12 archives You can specify the --dirsrv-cert-file and --http-cert-file options multiple times to specify multiple files. If necessary, the certificate files to complete the full CA certificate chain, supplied using this option: --ca-cert-file , which you can add this option multiple times Optionally, the certificate files to provide an external Kerberos key distribution center (KDC) PKINIT certificate, supplied using these options: --pkinit-cert-file for the Kerberos KDC SSL certificate and private key --pkinit-pin for the password to unlock the Kerberos KDC private key If you do not provide the PKINIT certificate, ipa-server-install configures the IdM server with a local KDC with a self-signed certificate. For details, see Chapter 27, Kerberos PKINIT Authentication in IdM . The files provided using --dirsrv-cert-file and --http-cert-file combined with the files provided using --ca-cert-file must contain the full CA certificate chain of the CA that issued the LDAP and Apache server certificates. For details on what the certificate file formats these options accept, see the ipa-server-install (1) man page. Note The listed command-line options are incompatible with the --external-ca option. Note Earlier versions of Identity Management used the --root-ca-file option to specify the PEM file of the root CA certificate. This is no longer necessary because the trusted CA is always the issuer of the DS and HTTP server certificates. IdM now automatically recognizes the root CA certificate from the certificates specified by --dirsrv-cert-file , --http-cert-file , and --ca-cert-file . Example 2.3. Command example for installing an IdM server without a CA 2.3.7. Installing a Server Non-Interactively Note If you are unsure what DNS or CA configuration is appropriate for you, see Section 2.3.1, "Determining Whether to Use Integrated DNS" and Section 2.3.2, "Determining What CA Configuration to Use" . The minimum required options for a non-interactive installation are: --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 --realm to provide the Kerberos realm name --unattended to let the installation process select default options for the host name and domain name Optionally, you can provide custom values for these settings: --hostname for the server host name --domain for the domain name You can also use the --dirsrv-config-file parameter to change default Directory Server settings, by specifying the path to a LDIF file with custom values. For more information, see IdM now supports setting individual Directory Server options during server or replica installation in the Release Notes for Red Hat Enterprise Linux 7.3 . Warning Red Hat strongly recommends that the Kerberos realm name is the same as the primary DNS domain name, with all letters uppercase. For example, if the primary DNS domain is ipa.example.com , use IPA.EXAMPLE.COM for the Kerberos realm name. Different naming practices will prevent you from using Active Directory trusts and can have other negative consequences. For a complete list of options accepted by ipa-server-install , run the ipa-server-install --help command. Example 2.4. Basic Installation without Interaction Run the ipa-server-install utility, providing the required settings. For example, the following installs a server without integrated DNS and with an integrated CA: The setup script now configures the server. Wait for the operation to complete. 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. Important The server installation is not complete until you add the DNS records to the existing DNS servers. The script recommends you to back up the CA certificate and to make sure the required network ports are open. For information about IdM port requirements and instructions on how to open these ports, see Section 2.1.6, "Port Requirements" . To test the new server: Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. Run a command such as ipa user-find . On a new server, the command prints the only configured user: admin . [1] For details, see the DNS Amplification Attacks page.
dig @ IP_address +norecurse +short ipa.example.com. NS acl authorized { 192.0.2.0/24 ; 198.51.100.0/24 ; }; options { allow-query { any; }; allow-recursion { authorized ; }; }; ipa-server-install --auto-reverse --allow-zone-overlap ipa-server-install Do you want to configure integrated DNS (BIND)? [no]: yes Server host name [server.example.com]: Please confirm the domain name [example.com]: Please provide a realm name [EXAMPLE.COM]: Directory Manager password: IPA admin password: Do you want to configure DNS forwarders? [yes]: Do you want to search for missing reverse zones? [yes]: 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. Continue to configure the system with these values? [no]: yes kinit admin ipa user-find admin -------------- 1 user matched -------------- User login: admin Last name: Administrator Home directory: /home/admin Login shell: /bin/bash UID: 939000000 GID: 939000000 Account disabled: False Password: True Kerberos keys available: True ---------------------------- Number of entries returned 1 ---------------------------- ipa-server-install Do you want to configure integrated DNS (BIND)? [no]: Server host name [server.example.com]: Please confirm the domain name [example.com]: Please provide a realm name [EXAMPLE.COM]: Directory Manager password: IPA admin password: Continue to configure the system with these values? [no]: yes Restarting the KDC Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db Restarting the web server kinit admin ipa user-find admin -------------- 1 user matched -------------- User login: admin Last name: Administrator Home directory: /home/admin Login shell: /bin/bash UID: 939000000 GID: 939000000 Account disabled: False Password: True Kerberos keys available: True ---------------------------- Number of entries returned 1 ---------------------------- 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 ipa-server-install --external-cert-file= /tmp/servercert20110601.pem --external-cert-file= /tmp/cacert.pem ipa : CRITICAL failed to configure ca instance Command '/usr/sbin/pkispawn -s CA -f /tmp/ configuration_file ' returned non-zero exit status 1 Configuration of CA failed 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 ipa-server-install --realm EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended Restarting the KDC Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db Restarting the web server kinit admin ipa user-find admin -------------- 1 user matched -------------- User login: admin Last name: Administrator Home directory: /home/admin Login shell: /bin/bash UID: 939000000 GID: 939000000 Account disabled: False Password: True Kerberos keys available: True ---------------------------- Number of entries returned 1 ----------------------------