# Hidden replicas

TECH PREVIEW

## Overview

A hidden replica is an IPA master server that is not advertised to clients or other masters. Hidden replicas have all services running and available, but none of the services has any DNS SRV records or enabled LDAP server roles. This makes hidden replicas invisible for service discovery.

- IPA clients and SSSD ignore hidden replicas and don’t consider them during installation or daily operations.

- Kerberos clients with `dns_lookup_kdc = True` do not auto-discover hidden replicas.

- Certmonger does not use a hidden replica to renew certificates.

- Masters without a CA or KRA instance never use CA or KRA services of a hidden replica.

By default, only services on a hidden replica use other services on the same machine, e.g. local LDAP and Kerberos services.

## Limitations

It’s critical to understand that hidden replicas have limitations. Most importantly, hidden replicas are just concealed, but not isolated and secluded. Other machines merely don’t see hidden replicas, when they use standard mechanisms to discover IPA servers. Other machines are able to find hidden replicas if they know what to look for. Any machine is able to use services on a hidden replica, when they are explicitly configured to do so.

- Hidden replicas are neither firewalled nor do they have any ACLs in place to prevent connections from other machines. All IPA TCP and UDP ports must be open for at least all other IPA servers.

- There must be at least one regular, non-hidden server available and online for each service (IPA master, DNS, CA, KRA). If DNS locations are used, there should be at least one regular replica in each location.

- As of now, a hidden replica cannot be a CA renewal master or a DNSSEC key master. The restriction may be lifted in the future.

- Hard-coded server names and explicit configurations like `ipa-client-install --server=$HOST`, SSSD config, or `ca_host` setting in `/etc/ipa/default.conf` override auto-discovery.

- The process of demoting a regular replica to hidden replica or promotion from hidden to regular replica is not instantaneous. It takes a while until the changes have been replicated and cached settings are refreshed.

## Use Cases

Hidden replicas are primarily designed for dedicated services that may otherwise disrupt clients. For example a full backup requires a complete shutdown of all IPA services. Since a hidden replica is not used by any clients by default, a temporary shutdown does not affect clients.

Other use cases include operations that put a high load on the IPA API or LDAP server, like mass imports or extensive queries.

## How to Use

### installation of a hidden replica

A new hidden replica can be installed with `ipa-replica-install --hidden-replica`.

### demotion / promotion of hidden replicas

A new command `ipa server-state` can be used to modify the state of a replica. An existing replica can be demoted to a hidden replica by executing `ipa server-state $HOST --state=hidden`. The command `ipa server-state $HOST --state=enabled` turns a hidden replica into an enabled, visible replica.

A CA renewal master or DNSSEC key master can’t be demoted to hidden replica. First the services must be moved to another replica with `ipa-dns-install --dnssec-master` and `ipa config-mod --ca-renewal-master-server=$HOST`.

### query status

The `ipa config-show` command now shows additional information about DNS and KRA as well as hidden servers:

    $ ipa config-show
      ...
      IPA masters: server1.ipa.example
      Hidden IPA masters: hidden1.ipa.example
      IPA master capable of PKINIT: hidden1.ipa.example, server1.ipa.example
      IPA CA servers: server1.ipa.example
      Hidden IPA CA servers: hidden1.ipa.example
      IPA CA renewal master: server1.ipa.example
      IPA KRA servers: server1.ipa.example
      Hidden IPA KRA servers: hidden1.ipa.example
      IPA DNS servers: server1.ipa.example
      Hidden IPA DNS servers: hidden1.ipa.example
      IPA DNSSec key master: server1.ipa.example
    $ ipa server-role-find --server=hidden1.ipa.example --include-master
    ----------------------
    6 server roles matched
    ----------------------
      Server name: hidden1.ipa.example
      Role name: AD trust agent
      Role status: absent

      Server name: hidden1.ipa.example
      Role name: AD trust controller
      Role status: absent

      Server name: hidden1.ipa.example
      Role name: CA server
      Role status: hidden

      Server name: hidden1.ipa.example
      Role name: DNS server
      Role status: hidden

      Server name: hidden1.ipa.example
      Role name: IPA master
      Role status: hidden

      Server name: hidden1.ipa.example
      Role name: KRA server
      Role status: hidden
    ----------------------------
    Number of entries returned 6
    ----------------------------

## Implementation

The status of a service is stored in LDAP inside the `cn=masters,cn=ipa,cn=etc,$SUFFIX` subtree. The subtree contains entries for each IPA master. Each entry holds a bunch of sub entries for services. For example `cn=CA,cn=hidden1.ipa.example,cn=masters,cn=ipa,cn=etc,$SUFFIX` is the container for the CA service on the IPA master hidden1.ipa.example. During the installation process the service entries are created with multi-valued attribute `ipaConfigString` set to `configuredService`. At the end of the installation, `configuredService` is either replaced with `enabledService` for a standard, enabled, and visible replica. Or it is set to `hiddenService` for hidden, unadvertised replicas.

Auto-discovery ignores any and all hidden services. The `dns-update-system-records` does not create SRV records for hidden services. The `find_providing_servers` API ignores hidden services except for preferred hosts. CA and KRA service discovery use the current host or explicit `ca_host` option from `/etc/ipa/default.conf` as preferred host.