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:

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.

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.3, “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 CA signing certificate must signed by a root CA, which is the highest CA in the CA hierarchy. The root CA can be the IdM CA itself or an externally-hosted 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 certificates issued within the IdM domain are potentially subject to restrictions set by the external root CA for attributes like the validity period.
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

Managing certificates without the integrated IdM CA presents a significant maintenance burden. Most notably:

Creating, uploading, and renewing certificates is a manual process.
The certmonger service is not used to track certificates. Therefore, it does not warn you of impending certificate expiration.

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:

$ 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

Run the ipa-server-install utility.
```
# ipa-server-install
```
The script prompts to configure an integrated DNS service. Enter yes.
```
Do you want to configure integrated DNS (BIND)? [no]: 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.
```
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.
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:
```
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.
  - 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.
```
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.

Enter yes to confirm the server configuration.

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

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.4, “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.
```
# kinit admin
```

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

Run the ipa-server-install utility.
```
# ipa-server-install
```
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]:
```
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.
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:
```

Enter yes to confirm the server configuration.

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

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

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.
```
# kinit admin
```

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:

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 might be necessary to request the appropriate extensions for the certificate. The CA signing certificate generated for the Identity Management server must be a valid CA certificate. This requires either that the Basic Constraint be set to CA=true or that the Key Usage Extension be set on the signing certificate to allow it to sign certificates.
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:
```
# 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
  The files provided using --dirsrv-cert-file and --http-cert-file must contain exactly one server certificate and exactly one private key. The contents of the files provided using --dirsrv-cert-file and --http-cert-file are often identical.
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

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:
```
# ipa-server-install --realm EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended
```
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.
```
...
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.

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.
```
# kinit admin
```

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.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.

Log in to Your Red Hat Account

Red Hat Account

Customer Portal

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

JBoss Development and Management

JBoss Integration and Automation

Mobile

Services

Tools

Red Hat Product Security Center

Security Updates

Resources

Customer Portal Community

Customer Events

Stories

2.3. Installing an IdM Server: Introduction

2.3.1. Determining Whether to Use Integrated DNS

Maintenance Requirements for Integrated or External DNS

Preventing DNS Amplification Attacks

2.3.2. Determining What CA Configuration to Use

2.3.3. Installing a Server with Integrated DNS

2.3.4. Installing a Server Without Integrated DNS

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

2.3.6. Installing Without a CA

Certificates Required to Install an IdM Server without a CA

2.3.7. Installing a Server Non-Interactively

Where did the comment section go?