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