From 3bcf6b17a1bd8fbef99e1f8bfc33f4312b40e48b Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jhrozek@redhat.com>
Date: Thu, 29 Jun 2017 16:16:01 +0200
Subject: [PATCH 105/115] MAN: Improve failover documentation by explaining the
 timeout better
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reviewed-by: Pavel Březina <pbrezina@redhat.com>
---
 src/man/include/failover.xml | 56 ++++++++++++++++++++++++++++++++++++++++++++
 src/man/sssd.conf.5.xml      | 14 +++++++----
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/src/man/include/failover.xml b/src/man/include/failover.xml
index 4865ce2be988b58dbd1c0736b6512f378be80d55..9ab74b1e1eca25aa63383ca575b7723ca7744346 100644
--- a/src/man/include/failover.xml
+++ b/src/man/include/failover.xml
@@ -49,4 +49,60 @@
             every 30 seconds.
         </para>
     </refsect2>
+    <refsect2 id='failover_tuning'>
+        <title>Failover time outs and tuning</title>
+        <para>
+            Resolving a server to connect to can be as simple as running
+            a single DNS query or can involve several steps, such as finding
+            the correct site or trying out multiple host names in case some
+            of the configured servers are not reachable. The more complex
+            scenarios can take some time and SSSD needs to balance between
+            providing enough time to finish the resolution process but on
+            the other hand, not trying for too long before falling back
+            to offline mode. If the SSSD debug logs show that the server
+            resolution is timing out before a live server is contacted,
+            you can consider changing the time outs.
+        </para>
+        <para>
+            This section lists the available tunables. Please refer to their
+            description in the
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum>
+            </citerefentry>,
+            manual page.
+            <variablelist>
+                <varlistentry>
+                    <term>
+                        dns_resolver_op_timeout
+                    </term>
+                    <listitem>
+                        <para>
+                            How long would SSSD talk to a single DNS server.
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>
+                        dns_resolver_timeout
+                    </term>
+                    <listitem>
+                        <para>
+                            How long would SSSD try to resolve a failover
+                            service. This service resolution internally might
+                            include several steps, such as resolving DNS SRV
+                            queries or locating the site.
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </para>
+        <para>
+            For LDAP-based providers, the resolve operation is performed
+            as part of an LDAP connection operation. Thefore, also the
+            <quote>ldap_opt_timeout></quote> timeout should be set to
+            a larger value than <quote>dns_resolver_timeout</quote>
+            which in turn should be set to a larger value than
+            <quote>dns_resolver_op_timeout</quote>.
+        </para>
+    </refsect2>
 </refsect1>
diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml
index 11a347d29f47923cb87f6adedbf346bde1c19593..9c9bf894fd725e1406d9217a256e0e13ab49c5f9 100644
--- a/src/man/sssd.conf.5.xml
+++ b/src/man/sssd.conf.5.xml
@@ -2607,10 +2607,16 @@ pam_account_locked_message = Account locked, please contact help desk.
                     <term>dns_resolver_timeout (integer)</term>
                     <listitem>
                         <para>
-                            Defines the amount of time (in seconds) to wait for a reply from
-                            the DNS resolver before assuming that it is unreachable. If this
-                            timeout is reached, the domain will continue to operate in
-                            offline mode.
+                            Defines the amount of time (in seconds) to
+                            wait for a reply from the internal fail over
+                            service before assuming that the service is
+                            unreachable. If this timeout is reached, the
+                            domain will continue to operate in offline mode.
+                        </para>
+                        <para>
+                            Please see the section <quote>FAILOVER</quote>
+                            for more information about the service
+                            resolution.
                         </para>
                         <para>
                             Default: 6
-- 
2.14.1