From 451eb489193538c9ead259919669b3ca3658cbd8 Mon Sep 17 00:00:00 2001 From: Christian Heimes 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 Reviewed-By: Thomas Woerner Reviewed-By: Francois Cami --- 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