D.2. Creating Replicas

The following sections describe the most notable replica installation scenarios.
  • The procedures and examples are not mutually exclusive; it is possible to use the CA, DNS, and other command-line options simultaneously. Examples in the following sections are called out separately to make it clearer what each configuration area requires.
  • The ipa-replica-install utility accepts a number of other options as well. For a complete list, the ipa-replica-install(1) man page.

D.2.1. Installing a Replica without DNS

  1. On the master IdM server, run the ipa-replica-prepare utility and add the fully qualified domain name (FQDN) of the replica machine. Note that the ipa-replica-prepare script does not validate the IP address or verify if the IP address of the replica is reachable by other servers.

    Important

    The fully qualified domain name must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the host name cause DNS failures. Additionally, the host name must be all lower-case; no capital letters are allowed.
    For other recommended naming practices, see the Red Hat Enterprise Linux Security Guide.
    If the master server is configured with integrated DNS, specify the IP address of the replica machine using the --ip-address option. The installation script then asks if you want to configure the reverse zone for the replica. Only pass --ip-address if the IdM server was configured with integrated DNS. Otherwise, there is no DNS record to update, and the attempt to create the replica fails when the DNS record operation fails.
    Enter the initial master server's Directory Manager (DM) password when prompted. The output of ipa-replica-prepare displays the location of the replica information file. For example:
    [root@server ~]# ipa-replica-prepare replica.example.com --ip-address 192.0.2.2
    Directory Manager (existing master) password:
    
    Do you want to configure the reverse zone? [yes]: no
    Preparing replica for replica.example.com from server.example.com
    Creating SSL certificate for the Directory Server
    Creating SSL certificate for the dogtag Directory Server
    Saving dogtag Directory Server port
    Creating SSL certificate for the Web Server
    Exporting RA certificate
    Copying additional files
    Finalizing configuration
    Packaging replica information into /var/lib/ipa/replica-info-replica.example.com.gpg
    Adding DNS records for replica.example.com
    Waiting for replica.example.com. A or AAAA record to be resolvable
    This can be safely interrupted (Ctrl+C)
    The ipa-replica-prepare command was successful
    

    Warning

    Replica information files contain sensitive information. Take appropriate steps to ensure that they are properly protected.
    For other options that can be added to ipa-replica-prepare, see the ipa-replica-prepare(1) man page.
  2. On the replica machine, install the ipa-server package.
    [root@replica ~]# yum install ipa-server
  3. Copy the replica information file from the initial server to the replica machine:
    [root@server ~]# scp /var/lib/ipa/replica-info-replica.example.com.gpg root@replica:/var/lib/ipa/
  4. On the replica machine, run the ipa-replica-install utility and add the location of the replication information file to start the replica initialization process. Enter the original master server's Directory Manager and admin passwords when prompted, and wait for the replica installation script to complete.
    [root@replica ~]# ipa-replica-install /var/lib/ipa/replica-info-replica.example.com.gpg
    Directory Manager (existing master) password:
    
    Run connection check to master
    Check connection from replica to remote master 'server.example.com':
    
    ...
    
    Connection from replica to master is OK.
    Start listening on required ports for remote master check
    Get credentials to log in to remote master
    admin@MASTER.EXAMPLE.COM password:
    
    Check SSH connection to remote master
    
    ...
    
    Connection from master to replica is OK.
    
    ...
    
    Configuring NTP daemon (ntpd)
      [1/4]: stopping ntpd
      [2/4]: writing configuration
    
    ...
    
    Restarting Directory server to apply updates
      [1/2]: stopping directory server
      [2/2]: starting directory server
    Done.
    Restarting the directory server
    Restarting the KDC
    Restarting the web server
    

    Note

    If the replica file being installed does not match the current host name, the replica installation script displays a warning message and asks for confirmation. In some cases, such as on multi-homed machines, you can confirm to continue with the mismatched host names.
    For command-line options that can be added to ipa-replica-install, see the ipa-replica-prepare(1) man page. Note that one of the options ipa-replica-install accepts is the --ip-address option. When added to ipa-replica-install, --ip-address only accepts IP addresses associated with the local interface.

D.2.2. Installing a Replica with DNS

To install a replica with integrated DNS, follow the procedure for installing without DNS described in Section D.2.1, “Installing a Replica without DNS”, but add these options to ipa-replica-install:
  • --setup-dns
  • --forwarder
For example:
[root@replica ~]# ipa-replica-install /var/lib/ipa/replica-info-replica.example.com.gpg --setup-dns --forwarder 198.51.100.0
After running ipa-replica-install, make sure proper DNS entries were created, and optionally add other DNS servers as backup servers. See Section 4.5.3, “Installing a Replica with DNS” for details.

D.2.3. Installing a Replica with Various CA Configurations

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.

Installing a Replica from a Server with a Certificate System CA Installed

To set up a CA on the replica when the initial server was configured with an integrated Red Hat Certificate System instance (regardless of whether it was a root CA or whether it was subordinate to an external CA), follow the basic installation procedure described in Section D.2.1, “Installing a Replica without DNS”, but add the --setup-ca option to the ipa-replica-install utility. The --setup-ca option copies the CA configuration from the initial server's configuration.
[root@replica ~]# ipa-replica-install /var/lib/ipa/replica-info-replica.example.com.gpg --setup-ca

Installing a Replica from a Server without a Certificate System CA Installed

For a CA-less replica installation, follow the basic procedure described in Section D.2.1, “Installing a Replica without DNS”, but add the following options when running the ipa-replica-prepare utility on the initial server:
  • --dirsrv-cert-file
  • --dirsrv-pin
  • --http-cert-file
  • --http-pin
For example:
[root@server ~]# ipa-replica-prepare replica.example.com --dirsrv-cert-file /tmp/server.key --dirsrv-pin secret --http-cert-file /tmp/server.crt --http-cert-file /tmp/server.key --http-pin secret --dirsrv-cert-file /tmp/server.crt

D.2.4. Adding Additional Replication Agreements

Installing a replica using ipa-replica-install creates an initial replication agreement between the master server and the replica. To connect the replica to other servers or replicas, add additional agreements using the ipa-replica-manage utility.
If the master server and the new replica have a CA installed, a replication agreement for CA is also created. To add additional CA replication agreements to other servers or replicas, use the ipa-csreplica-manage utility.
For more information on adding additional replication agreements, see Section D.3, “Managing Replicas and Replication Agreements”.