From 451eb489193538c9ead259919669b3ca3658cbd8 Mon Sep 17 00:00:00 2001
From: Christian Heimes <cheimes@redhat.com>
Date: Tue, 26 Mar 2019 16:45:02 +0100
Subject: [PATCH] Add design draft
The design draft explains implementation details, limitations, and API
changes for the new feature.
Fixes: https://pagure.io/freeipa/issue/7892
Signed-off-by: Christian Heimes <cheimes@redhat.com>
Reviewed-By: Thomas Woerner <twoerner@redhat.com>
Reviewed-By: Francois Cami <fcami@redhat.com>
---
doc/designs/hidden-replicas.md | 153 +++++++++++++++++++++++++++++++++
1 file changed, 153 insertions(+)
create mode 100644 doc/designs/hidden-replicas.md
diff --git a/doc/designs/hidden-replicas.md b/doc/designs/hidden-replicas.md
new file mode 100644
index 0000000000000000000000000000000000000000..1abc73612cbf2e5636d7076b5c6f50eb0ecbce4c
--- /dev/null
+++ b/doc/designs/hidden-replicas.md
@@ -0,0 +1,153 @@
+# 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=enable`` 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.
--
2.20.1