Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

4.5. Creating the Replica: Introduction

The ipa-replica-install utility is used to install a new replica from an existing IdM server. Install Identity Management replicas one at a time. The installation of multiple replicas at the same time is not supported.
Note
This chapter describes the simplified replica installation introduced in Red Hat Enterprise Linux 7.3. The procedures require domain level 1 (see Chapter 7, Displaying and Raising the Domain Level).
For documentation on installing a replica at domain level 0, see Appendix D, Managing Replicas at Domain Level 0.
You can install a new replica:
In both of these situations, you can customize your replica by adding options to ipa-replica-install: see the section called “Using ipa-replica-install to Configure the Replica for Your Use Case”.
To install the replica as hidden, pass the --hidden-replica parameter to ipa-replica-install. For further details about hidden replicas, see Section 4.2.3, “The Hidden Replica Mode”.
Important
If the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent after running ipa-replica-install. See Trust Controllers and Trust Agents in the Windows Integration Guide.

Promoting an Existing Client to a Replica

To install the replica on an existing client, you must make sure the client is authorized to be promoted. To achieve this, choose one of the following:
Provide a privileged user's credentials
The default privileged user is admin. There are multiple ways to provide the user's credentials. You can:
  • let IdM prompt you to get the credentials interactively
    Note
    This is the default way to provide the privileged user's credentials. If no credentials are available when ipa-replica-install runs, the installation automatically prompts you.
  • log in as the user before running ipa-replica-install on the client: 
    $ kinit admin
  • add the user's principal name and password to ipa-replica-install directly: 
    # ipa-replica-install --principal admin --admin-password admin_password
Add the client to the ipaservers host group
Membership in ipaservers grants the machine elevated privileges analogous to a privileged user's credentials. You will not be required to provide the user's credentials.
Example: Section 4.5.1, “Promoting a Client to a Replica Using a Host Keytab”

Installing a Replica on a Machine That Is Not a Client

When run on a machine that has not yet been enrolled in the IdM domain, ipa-replica-install first enrolls the machine as a client and then installs the replica components.
To install a replica in this situation, choose one of the following:
Provide a privileged user's credentials
The default privileged user is admin. To provide the credentials, add the principal name and password to ipa-replica-install directly: 
# ipa-replica-install --principal admin --admin-password admin_password
Provide a random password for the client
You must generate the random password on a server before installing the replica. You will not be required to provide the user's credentials during the installation.
Example: Section 4.5.2, “Installing a Replica Using a Random Password”
By default, the replica is installed against the first IdM server discovered by the client installer. To install the replica against a particular server, add the following options to ipa-replica-install:
  • --server for the server's fully qualified domain name (FQDN)
  • --domain for the IdM DNS domain

Using ipa-replica-install to Configure the Replica for Your Use Case

When run without any options, ipa-replica-install only sets up basic server services. To install additional services, such as DNS or a certificate authority (CA), add options to ipa-replica-install.
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.
For example scenarios of installing a replica with the most notable options, see:
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.
For a complete list of the options used to configure the replica, see the ipa-replica-install(1) man page.

4.5.1. Promoting a Client to a Replica Using a Host Keytab

In this procedure, an existing IdM client is promoted to a replica using its own host keytab to authorize the promotion.
The procedure does not require you to provide the administrator or Directory Manager (DM) credentials. It is therefore more secure because no sensitive information is exposed on the command line.
  1. On an existing server:
    1. Log in as the administrator. 
      $ kinit admin
    2. Add the client machine to the ipaservers host group. 
      $ ipa hostgroup-add-member ipaservers --hosts client.example.com
  Host-group: ipaservers
  Description: IPA server hosts
  Member hosts: server.example.com, client.example.com
-------------------------
Number of members added 1
-------------------------
      Membership in ipaservers grants the machine elevated privileges analogous to the administrator's credentials.
  2. On the client, run the ipa-replica-install utility. 
    # ipa-replica-install
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.2. Installing a Replica Using a Random Password

In this procedure, a replica is installed from scratch on a machine that is not yet an IdM client. To authorize the enrollment, a client-specific random password valid for one client enrollment only is used.
The procedure does not require you to provide the administrator or Directory Manager (DM) credentials. It is therefore more secure because no sensitive information is exposed on the command line.
  1. On an existing server:
    1. Log in as the administrator. 
      $ kinit admin
    2. Add the new machine as an IdM host. Use the --random option with the ipa host-add command to generate a random one-time password to be used for the replica installation. 
      $ 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
      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.
    3. Add the machine to the ipaservers host group. 
      $ ipa hostgroup-add-member ipaservers --hosts client.example.com
  Host-group: ipaservers
  Description: IPA server hosts
  Member hosts: server.example.com, client.example.com
-------------------------
Number of members added 1
-------------------------
      Membership in ipaservers grants the machine elevated privileges required to set up the necessary server services.
  2. On the machine where you want to install the replica, run ipa-replica-install, and provide the random password using the --password option. Enclose the password in single quotes (') because it often contains special characters: 
    # ipa-replica-install --password 'W5YpARl=7M.n'
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.3. Installing a Replica with DNS

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
  1. Run ipa-replica-install with these options:
    • --setup-dns to create a DNS zone if it does not exist already and 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: 
    # 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. If the initial server was created with DNS enabled, the replica is automatically created with the proper DNS entries. The entries ensure that IdM clients will be able to discover the new server.
    If the initial server did not have DNS enabled, add the DNS records manually. The following DNS records are necessary for the domain services:
    • _ldap._tcp
    • _kerberos._tcp
    • _kerberos._udp
    • _kerberos-master._tcp
    • _kerberos-master._udp
    • _ntp._udp
    • _kpasswd._tcp
    • _kpasswd._udp
    This example shows how to verify that the entries are present:
    1. Set the appropriate values for the DOMAIN and NAMESERVER variables: 
      # DOMAIN=example.com
# NAMESERVER=replica
    2. Use the following command to check for the DNS entries: 
      # for i in _ldap._tcp _kerberos._tcp _kerberos._udp _kerberos-master._tcp _kerberos-master._udp _ntp._udp ; do
dig @${NAMESERVER} ${i}.${DOMAIN} srv +nocmd +noquestion +nocomments +nostats +noaa +noadditional +noauthority
done | egrep "^_"

_ldap._tcp.example.com. 86400     IN    SRV     0 100 389 server1.example.com.
_ldap._tcp.example.com. 86400     IN    SRV     0 100 389 server2.example.com.
_kerberos._tcp.example.com. 86400 IN    SRV     0 100 88  server1.example.com.
...
  3. 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.
  4. Optional, but recommended. Manually add other DNS servers as backup servers in case the replica becomes unavailable. See Section 33.11.1, “Setting up Additional Name Servers”. This is recommended especially for situations when the new replica is your first DNS server in the IdM domain.
  5. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.4. Installing a Replica with a CA

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
  1. Run ipa-replica-install with the --setup-ca option. 
    [root@replica ~]# ipa-replica-install --setup-ca
  2. The --setup-ca option copies the CA configuration from the initial server's configuration, regardless of whether the IdM CA on the server is a root CA or whether it is subordinated to an external CA.
    Note
    For details on the supported CA configurations, see Section 2.3.2, “Determining What CA Configuration to Use”.
  3. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.

4.5.5. Installing a Replica from a Server without a CA

This procedure works for installing a replica on a client as well as on a machine that is not part of the IdM domain yet. See Section 4.5, “Creating the Replica: Introduction” for details.
Important
You cannot install a server or replica using self-signed third-party server certificates.
  1. Run ipa-replica-install, and provide the required certificate files by adding these options:
    • --dirsrv-cert-file
    • --dirsrv-pin
    • --http-cert-file
    • --http-pin
    For details about the files that are provided using these options, see Section 2.3.6, “Installing Without a CA”.
    For example: 
    [root@replica ~]# ipa-replica-install \
    --dirsrv-cert-file /tmp/server.crt \
    --dirsrv-cert-file /tmp/server.key \
    --dirsrv-pin secret \
    --http-cert-file /tmp/server.crt \
    --http-cert-file /tmp/server.key \
    --http-pin secret
    Note
    Do not add the --ca-cert-file option. The ipa-replica-install utility takes this part of the certificate information automatically from the master server.
  2. Optionally, if the IdM server you are replicating has a trust with Active Directory, set up the replica as a trust agent or trust controller. For details, see Trust Controllers and Trust Agents in the Windows Integration Guide.