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.
