Search
SupportConsoleDevelopersStart a trialContact

2.3. Installing an IdM Server: Introduction

download PDF
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:
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: 
    # dig @IP_address +norecurse +short ipa.example.com. NS
    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: 
acl authorized { 192.0.2.0/24; 198.51.100.0/24; };
options {
  allow-query { any; };
  allow-recursion { authorized; };
};

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
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: 
$ ipa-server-install --auto-reverse --allow-zone-overlap
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
  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.
    • To accept the default values in brackets, press Enter.
    • To provide a value different than the proposed default 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
    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.
  4. Enter the passwords for the Directory Server superuser, cn=Directory Manager, and for the admin IdM system user account. 
    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.
    • If you do not want to use DNS forwarding, enter no.
  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. 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:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: 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
----------------------------

2.3.4. Installing a Server Without Integrated DNS

Note
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
  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.
    • To accept the default values in brackets, press Enter.
    • To provide a value different than the proposed default 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
    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.
  4. Enter the passwords for the Directory Server superuser, cn=Directory Manager, and for the admin IdM system user account. 
    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.
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:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: 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
----------------------------

2.3.5. Installing a Server with an External CA as the Root CA

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

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.
    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.
  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/servercert20110601.pem --external-cert-file=/tmp/cacert.pem
Note
The ipa-server-install --external-ca command can sometimes fail with the following error: 
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
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
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

[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

2.3.7. Installing a Server Non-Interactively

Note
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

  1. 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: 
    # ipa-server-install --realm EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended
  2. The setup script now configures the server. Wait for the operation to complete.
  3. 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.
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:
  1. Authenticate to the Kerberos realm using the admin credentials. This verifies that admin is properly configured and the Kerberos realm is accessible. 
    # kinit admin
  2. Run a command such as ipa user-find. On a new server, the command prints the only configured user: 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
----------------------------

[1] For details, see the DNS Amplification Attacks page.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.