Document the failover feature in manpages

Fixes: #309

4 files changed, 61 insertions, 4 deletions

diff --git a/server/man/include/failover.xml b/server/man/include/failover.xml
new file mode 100644
index 00000000..7c37bb40
--- /dev/null
+++ b/server/man/include/failover.xml
@@ -0,0 +1,41 @@
+<refsect1 id='failover'>
+    <title>FAILOVER</title>
+    <para>
+        The failover feature allows back ends to automatically switch to
+        a different server if the primary server fails.
+    </para>
+    <refsect2 id='failover_syntax'>
+        <title>Failover Syntax</title>
+        <para>
+            The list of servers is given as a comma-separated list; any
+            number of spaces is allowed around the comma. The servers are
+            listed in order of preference. The list can contain any number
+            of servers.
+        </para>
+    </refsect2>
+    <refsect2 id='failover_mechanism'>
+        <title>The Failover Mechanism</title>
+        <para>
+            The failover mechanism distinguishes between a machine and a
+            service. The back end first tries to resolve the hostname of a
+            given machine; if this resolution attempt fails, the machine is
+            considered offline. No further attempts are made to connect
+            to this machine for any other service. If the resolution
+            attempt succeeds, the back end tries to connect to a service
+            on this machine. If the service connection attempt fails,
+            then only this particular service is considered offline and
+            the back end automatically switches over to the next service.
+            The machine is still considered online and might still be tried
+            for another service.
+        </para>
+        <para>
+            Further connection attempts are made to machines or services
+            marked as offline after a specified period of time; this is
+            currently hard coded to 30 seconds.
+        </para>
+        <para>
+            If there are no more servers to try, the back end as a whole
+            switches to offline mode for a certain period of time.
+        </para>
+    </refsect2>
+</refsect1>
diff --git a/server/man/sssd-ipa.5.xml b/server/man/sssd-ipa.5.xml
index f0fbf639..d1ba1c52 100644
--- a/server/man/sssd-ipa.5.xml
+++ b/server/man/sssd-ipa.5.xml
@@ -76,7 +76,11 @@
                     <term>ipa_server (string)</term>
                     <listitem>
                         <para>
-                            The name of the IPA server.
+                            The list of IP addresses or hostnames of the
+                            IPA servers to which SSSD should connect in
+                            the order of preference. For more information
+                            on failover and server redundancy, see the
+                            <quote>FAILOVER</quote> section.
                             This is optional if autodiscovery is enabled.
                         </para>
                     </listitem>
@@ -114,6 +118,8 @@
         </para>
     </refsect1>
 
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/failover.xml" />
+
     <refsect1 id='example'>
         <title>EXAMPLE</title>
         <para>
diff --git a/server/man/sssd-krb5.5.xml b/server/man/sssd-krb5.5.xml
index 1ca28314..e73e106a 100644
--- a/server/man/sssd-krb5.5.xml
+++ b/server/man/sssd-krb5.5.xml
@@ -65,7 +65,11 @@
                     <term>krb5_kdcip (string)</term>
                     <listitem>
                         <para>
-                            Specifies the IP address of the Kerberos server.
+                            Specifies the list of IP addresses or hostnames
+                            of the Kerberos servers to which SSSD should
+                            connect in the order of preference. For more
+                            information on failover and server redundancy,
+                            see the <quote>FAILOVER</quote> section.
                         </para>
                     </listitem>
                 </varlistentry>
@@ -207,6 +211,8 @@
         </para>
     </refsect1>
 
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/failover.xml" />
+
     <refsect1 id='example'>
         <title>EXAMPLE</title>
         <para>
diff --git a/server/man/sssd-ldap.5.xml b/server/man/sssd-ldap.5.xml
index 9172fa25..dc146ea2 100644
--- a/server/man/sssd-ldap.5.xml
+++ b/server/man/sssd-ldap.5.xml
@@ -59,8 +59,10 @@
                     <term>ldap_uri (string)</term>
                     <listitem>
                         <para>
-                            Specifies the URI of the LDAP server to which
-                            SSSD should connect.
+                            Specifies the list of URIs of the LDAP servers to which
+                            SSSD should connect in the order of preference. For more
+                            information on failover and server redundancy, see the
+                            <quote>FAILOVER</quote> section.
                         </para>
                         <para>
                             Default: ldap://localhost
@@ -620,6 +622,8 @@
         </para>
     </refsect1>
 
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/failover.xml" />
+
     <refsect1 id='example'>
         <title>EXAMPLE</title>
         <para>