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 a Dogtag Certificate System instance as the CA for the FreeIPA domain, then it is possible to make a replica of a replica.

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”.
  • The replica must be the same version as the original master server. If the master server is running on Red Hat Enterprise Linux 6.3, FreeIPA version 2.2.x, then the replica must also run on Red Hat Enterprise Linux 6.3 and use the FreeIPA 2.2.x packages.


    Creating a replica of a different version than the master is not supported. Attempting to create a replica using a different version fails when attempting to configure the 389 Directory Server instance.
  • Install the server packages as in Section 2.2, “Installing the FreeIPA Server Packages”. For example:
    [root@server ~]# 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

  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.
    [root@server ~]# 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.
    Additionally, the hostname must all be lower-case. No capital letters are allowed.
    For more options with ipa-replica-prepare, see Section C.5.3, “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:
    [root@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. Additionally, there is an option to configure a CA for the replica; while CA's are installed by default for servers, they are optional for replicas.
    For example:
    [root@ipareplica ~]# ipa-replica-install --setup-ca --setup-dns /var/lib/ipa/
    Directory Manager (existing master) password:
    Warning: Hostname ( not found in DNS
    Run connection check to master
    Check connection from replica to remote master 'ipareplica.':
       Directory Service: Unsecure port (389): OK
       Directory Service: Secure port (636): OK
       Kerberos KDC: TCP (88): OK
       Kerberos Kpasswd: TCP (464): OK
       HTTP Server: Unsecure port (80): OK
       HTTP Server: Secure port (443): OK
    The following list of ports use UDP protocol and would need to be
    checked manually:
       Kerberos KDC: UDP (88): SKIPPED
       Kerberos Kpasswd: UDP (464): SKIPPED
    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@EXAMPLE.COM password:
    Execute check on remote master's password:
    Check connection from master to remote replica 'ipareplica.':
       Directory Service: Unsecure port (389): OK
       Directory Service: Secure port (636): OK
       Kerberos KDC: TCP (88): OK
       Kerberos KDC: UDP (88): OK
       Kerberos Kpasswd: TCP (464): OK
       Kerberos Kpasswd: UDP (464): OK
       HTTP Server: Unsecure port (80): OK
       HTTP Server: Secure port (443): OK
    Connection from master to replica is OK.
    Connection check OK
    Additional options for the replica installation script are listed in Section C.5.2, “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. Verify that the proper DNS entries were created so that FreeIPA clients can discover the new server. DNS entries are required for required domain services:
    • ldap._tcp
    • _kerberos._tcp
    • _kerberos._udp
    • _kerberos-master._tcp
    • _kerberos-master._udp
    • _kpasswd._tcp
    • _kpasswd._udp
    • _ntp._udp
    If the initial FreeIPA server was created with DNS enabled, then the replica is created with the proper DNS entries. For example:
    [root@ipareplica ~]#
    [root@ipareplica ~]# NAMESERVER=ipareplica
    [root@ipareplica ~]# for i in _ldap._tcp _kerberos._tcp _kerberos._udp _kerberos-master._tcp _kerberos-master._udp _kpasswd._tcp _kpasswd._udp _ntp._udp; do echo ""; dig @${NAMESERVER} ${i}.${DOMAIN} srv +nocmd +noquestion +nocomments +nostats +noaa +noadditional +noauthority; done | egrep -v "^;" | egrep _ 86400   IN      SRV     0 100 389 86400   IN      SRV     0 100 389 86400 IN    SRV     0 100 88
    If the initial FreeIPA server was created without DNS enabled, then each DNS entry, including both TCP and UPD entries for some services, should be added manually. For example:
    [root@ipareplica ~]# kinit admin
    [root@ipareplica ~]# ipa dnsrecord-add _ldap._tcp --srv-rec="0 100 389"
  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:
    [root@ipareplica ~]# ipa-dns-install
    [root@ipareplica ~]# 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

Certificate System setup failed.
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/2012: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:
[root@ipareplica ~]# ipa-server-install --uninstall
After uninstalling the replica, ensure that port 7389 on the replica is available, and retry the replica installation.
There are SASL, GSS-API, and Kerberos errors in the 389 Directory Server logs when the replica starts.
When the replica starts, there can be a series of SASL bind errors recorded in the 389 Directory Server logs stating that the GSS-API connection failed because it could not find a credentials cache:
slapd_ldap_sasl_interactive_bind - Error: could not perform interactive bind for id [] mech [GSSAPI]: error -2 (Local error) (SASL(-1): generic failure: GSSAPI Error: Unspecified GSS failure. Minor code may provide more information (Credentials cache file '/tmp/krb5cc_496' not found)) ...
The replica is looking for a credentials cache in /tmp/krb5cc_496 (where 496 is the 389 Directory Server user ID) and cannot find it.
There may also be messages that the server could not obtain Kerberos credentials for the host principal:
set_krb5_creds - Could not get initial credentials for principal [ldap/] in keytab [WRFILE:/etc/dirsrv/ds.keytab]: -1765328324 (Generic error)
These errors are both related to how and when the 389 Directory Server instance loads its Kerberos credentials cache.
While 389 Directory Server itself supports multiple different authentication mechanisms, FreeIPA only uses GSS-API for Kerberos connections. The 389 Directory Server instance for FreeIPA keeps its Kerberos credentials cache in memory. When the 389 Directory Server process ends — like when the FreeIPA replica is stopped — the credentials cache is destroyed.
Also, the 389 Directory Server is used as the backend storage for the principal information for the KDC.
When the replica then restarts, the 389 Directory Server instance starts first, since it supplies information for the KDC, and then the KDC server starts. This start order is what causes the GSS-API and Kerberos connection errors.
The 389 Directory Server attempts to open a GSS-API connection, but since there is no credentials cache yet and the KDC is not started, the GSS connection fails. Likewise, any attempt to obtain the host credentials also fails.
These errors are transient. The 389 Directory Server re-attempts the GSS-API connection after the KDC starts and it has a credentials cache. The 389 Directory Server logs then record a bind resumed message.
These startup GSS-API connection failures can be ignored as long as that connection is successfully established.