4.5. Creating the Replica: Introduction

The ipa-replica-install utility is used to install a new replica from an existing IdM server.

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

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.

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

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'

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

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

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