Product SiteDocumentation Site

2.4. Setting up FreeIPA Replicas

In the FreeIPA domain, there are three types of machines:
A replica is a clone of a specific FreeIPA server. The server and replica share the same internal information about users, machines, certificates, and configured policies. These data are copied from the server to the replica in a process called replication. The two Directory Server instances used by an FreeIPA server — the Directory Server instance used by the FreeIPA server as a data store and the Directory Server instance used by the Dogtag Certificate System to store certificate information — are replicated over to corresponding consumer Directory Server instances used by the FreeIPA replica.


If you are using the integrated Dogtag Certificate System instance as the CA for the FreeIPA domain, then it is possible to make a replica of a replica. It is not possible to make a replica of a replica if you use the --selfsign option for the original FreeIPA server.

2.4.1. Prepping and Installing the Replica Server

Replicas are functionally the same as FreeIPA servers, so they have the same installation requirements and packages.
  • Make sure that the machine meets all of the prerequisites listed in Section 2.1, “Preparing to Install the FreeIPA Server”.
  • Install the server packages as in Section 2.2, “Installing the FreeIPA Server Packages”. For example:
    # yum install freeipa-server bind bind-dyndb-ldap


    Do not run the ipa-server-install script.
    The replica and the master server must be running the same version of FreeIPA.
  • If there is an existing Dogtag Certificate System or Red Hat Certificate System instance on the replica machine, make sure that port 7389 is free. This port is used by the master FreeIPA server to communicate with the replica.
  • Make sure the appropriate ports are open on both the server and the replica machine during and after the replica configuration. Servers and replicas connect to each other over ports 9443, 9444, 9445, and 7389 during the replica configuration. Once the replica is set up, the server and replica communicate over port 7389.

2.4.2. Creating the Replica


Make sure that the replica machine exists in the server's DNS before beginning to configure the replica. If the server cannot contact the replica machine during the configuration process, then the replica configuration fails. If necessary, add a DNS entry, as in Section 8.9, “Adding Records to DNS Zones”.
  1. On the master server, create a replica information file. This contains realm and configuration information taken from the master server which will be used to configure the replica server.
    Run the ipa-replica-prepare command on the master FreeIPA server. The command requires the fully-qualified domain name of the replica machine. Using the --ip-address option automatically creates DNS entries for the replica, including the A and PTR records for the replica to the DNS.
    # ipa-replica-prepare --ip-address
    Determining current realm name
    Getting domain name from LDAP
    Preparing replica for from
    Creating SSL certificate for the Directory Server
    Creating SSL certificate for the Web Server
    Copying additional files
    Finalizing configuration
    Packaging the replica into


    This must be a valid DNS name, which means only numbers, alphabetic characters, and hyphens (-) are allowed. Other characters, like underscores, in the hostname will cause DNS failures.
    For more options with ipa-replica-prepare, see Section B.5.2, “ipa-replica-prepare”.
    Each replica information file is created in the /var/lib/ipa/ directory as a GPG-encrypted file. Each file is named specifically for the replica server for which it is intended, such as


    A replica information file cannot be used to create multiple replicas. It can only be used for the specific replica and machine for which it was created.


    Replica information files contain sensitive information. Take appropriate steps to ensure that they are properly protected.
  2. Copy the replica information file to the replica server:
    # scp /var/lib/ipa/ root@ipareplica:/var/lib/ipa/
  3. On the replica server, run the replica installation script, referencing the replication information file. There are other options for setting up DNS, much like the server installation script. For example:
    # ipa-replica-install --setup-dns /var/lib/ipa/
    Additional options for the replica installation script are listed in Section B.5.1, “ipa-replica-install”.
    The replica installation script runs a test to ensure that the replica file being installed matches the current hostname. If they do not match, the script returns a warning message and asks for confirmation. This could occur on a multi-homed machine, for example, where mismatched hostnames may not be an issue.
  4. Enter the Directory Manager password when prompted. The script then configures a Directory Server instance based on information in the replica information file and initiates a replication process to copy over data from the master server to the replica, a process called initialization.
  5. Once the installation process completes, update the DNS entries so that FreeIPA clients can discover the new server. For example, for a FreeIPA replica with a hostname of
    _ldap._tcp             IN SRV 0 100 389
    _kerberos._tcp         IN SRV 0 100 88
    _kerberos._udp         IN SRV 0 100 88
    _kerberos-master._tcp  IN SRV 0 100 88
    _kerberos-master._udp  IN SRV 0 100 88
    _kpasswd._tcp          IN SRV 0 100 464
    _kpasswd._udp          IN SRV 0 100 464
    _ntp._udp              IN SRV 0 100 123
  6. Optional. Set up DNS services for the replica. These are not configured by the setup script, even if the master server uses DNS.
    Use the ipa-dns-install command to install the DNS manually, then use the ipa dnsrecord-add command to add the required DNS records. For example:
    # ipa-dns-install
    # ipa dnsrecord-add @ --ns-rec


    Use the fully-qualified domain name of the replica, including the final period (.), otherwise BIND will treat the hostname as relative to the domain.

2.4.3. Troubleshooting Replica Installation

If the replica installation fails on step 3 ([3/11]: configuring certificate server instance), that usually means that the required port is not available. This can be verified by checking the debug logs for the CA, /var/log/pki-ca/debug, which may show error messages about being unable to find certain entries. For example:
[04/Feb/2011:22:29:03][http-9445-Processor25]: DatabasePanel
comparetAndWaitEntries ou=people,o=ipaca not found, let's wait
The only resolution is to uninstall the replica:
# ipa-server-install --uninstall
After uninstalling the replica, ensure that port 7389 on the replica is available, and retry the replica installation.