Adding upstream version 2.9.4.upstream/2.9.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 950 insertions, 0 deletions

diff --git a/src/man/sssd-ipa.5.xml b/src/man/sssd-ipa.5.xml
new file mode 100644
index 0000000..4802ce8
--- /dev/null
+++ b/src/man/sssd-ipa.5.xml
@@ -0,0 +1,950 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
+
+    <refmeta>
+        <refentrytitle>sssd-ipa</refentrytitle>
+        <manvolnum>5</manvolnum>
+        <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>sssd-ipa</refname>
+        <refpurpose>SSSD IPA provider</refpurpose>
+    </refnamediv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            This manual page describes the configuration of the IPA provider
+            for
+            <citerefentry>
+                <refentrytitle>sssd</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry>.
+            For a detailed syntax reference, refer to the <quote>FILE FORMAT</quote> section of the
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> manual page.
+        </para>
+        <para>
+            The IPA provider is a back end used to connect to an IPA server.
+            (Refer to the freeipa.org web site for information about IPA servers.)
+            This provider requires that the machine be joined to the IPA domain;
+            configuration is almost entirely self-discovered and obtained
+            directly from the server.
+        </para>
+        <para>
+            The IPA provider enables SSSD to use the
+            <citerefentry>
+                <refentrytitle>sssd-ldap</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> identity provider and the
+            <citerefentry>
+                <refentrytitle>sssd-krb5</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> authentication provider with optimizations for IPA
+            environments. The IPA provider accepts the same options used by the
+            sssd-ldap and sssd-krb5 providers with some exceptions. However, it is
+            neither necessary nor recommended to set these options.
+        </para>
+        <para>
+            The IPA provider primarily copies the traditional ldap and krb5 provider
+            default options with some exceptions, the differences are listed in the
+            <quote>MODIFIED DEFAULT OPTIONS</quote> section.
+        </para>
+        <para>
+            As an access provider, the IPA provider has a minimal configuration
+            (see <quote>ipa_access_order</quote>) as it mainly uses HBAC
+            (host-based access control) rules. Please refer to freeipa.org for
+            more information about HBAC.
+        </para>
+        <para>
+            If <quote>auth_provider=ipa</quote> or
+            <quote>access_provider=ipa</quote> is configured
+            in sssd.conf then the id_provider must also be set to
+            <quote>ipa</quote>.
+        </para>
+        <para>
+            The IPA provider will use the PAC responder if the Kerberos tickets
+            of users from trusted realms contain a PAC. To make configuration
+            easier the PAC responder is started automatically if the IPA ID
+            provider is configured.
+        </para>
+    </refsect1>
+
+    <refsect1 id='configuration-options'>
+        <title>CONFIGURATION OPTIONS</title>
+        <para>Refer to the section <quote>DOMAIN SECTIONS</quote> of the
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> manual page for details on the configuration of an SSSD domain.
+            <variablelist>
+                <varlistentry>
+                    <term>ipa_domain (string)</term>
+                    <listitem>
+                        <para>
+                            Specifies the name of the IPA domain.
+                            This is optional. If not provided, the configuration
+                            domain name is used.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_server, ipa_backup_server (string)</term>
+                    <listitem>
+                        <para>
+                            The comma-separated 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.
+                            For more information on service discovery, refer
+                            to the <quote>SERVICE DISCOVERY</quote> section.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_hostname (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. May be set on machines where the
+                            hostname(5) does not reflect the fully qualified
+                            name used in the IPA domain to identify this host.
+                            The hostname must be fully qualified.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_update (boolean)</term>
+                    <listitem>
+                        <para>
+                            Optional. This option tells SSSD to automatically
+                            update the DNS server built into FreeIPA with
+                            the IP address of this client. The update is
+                            secured using GSS-TSIG. The IP address of the IPA
+                            LDAP connection is used for the updates, if it is
+                            not otherwise specified by using the
+                            <quote>dyndns_iface</quote> option.
+                        </para>
+                        <para>
+                            NOTE: On older systems (such as RHEL 5), for this
+                            behavior to work reliably, the default Kerberos
+                            realm must be set properly in /etc/krb5.conf
+                        </para>
+                        <para>
+                            NOTE: While it is still possible to use the old
+                            <emphasis>ipa_dyndns_update</emphasis> option, users
+                            should migrate to using <emphasis>dyndns_update</emphasis>
+                            in their config file.
+                        </para>
+                        <para>
+                            Default: false
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_ttl (integer)</term>
+                    <listitem>
+                        <para>
+                            The TTL to apply to the client DNS record when updating it.
+                            If dyndns_update is false this has no effect. This will
+                            override the TTL serverside if set by an administrator.
+                        </para>
+                        <para>
+                            NOTE: While it is still possible to use the old
+                            <emphasis>ipa_dyndns_ttl</emphasis> option, users
+                            should migrate to using <emphasis>dyndns_ttl</emphasis>
+                            in their config file.
+                        </para>
+                        <para>
+                            Default: 1200 (seconds)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_iface (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Applicable only when dyndns_update
+                            is true. Choose the interface or a list of interfaces
+                            whose IP addresses should be used for dynamic DNS
+                            updates. Special value <quote>*</quote> implies that
+                            IPs from all interfaces should be used.
+                        </para>
+                        <para>
+                            NOTE: While it is still possible to use the old
+                            <emphasis>ipa_dyndns_iface</emphasis> option, users
+                            should migrate to using <emphasis>dyndns_iface</emphasis>
+                            in their config file.
+                        </para>
+                        <para>
+                            Default: Use the IP addresses of the interface which
+                            is used for IPA LDAP connection
+                        </para>
+                        <para>
+                            Example: dyndns_iface = em1, vnet1, vnet2
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_auth (string)</term>
+                    <listitem>
+                        <para>
+                            Whether the nsupdate utility should use GSS-TSIG
+                            authentication for secure updates with the DNS
+                            server, insecure updates can be sent by setting
+                            this option to 'none'.
+                        </para>
+                        <para>
+                            Default: GSS-TSIG
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_auth_ptr (string)</term>
+                    <listitem>
+                        <para>
+                            Whether the nsupdate utility should use GSS-TSIG
+                            authentication for secure PTR updates with the DNS
+                            server, insecure updates can be sent by setting
+                            this option to 'none'.
+                        </para>
+                        <para>
+                            Default: Same as dyndns_auth
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_enable_dns_sites (boolean)</term>
+                    <listitem>
+                        <para>
+                            Enables DNS sites - location based
+                            service discovery.
+                        </para>
+                        <para>
+                            If true and service discovery (see Service
+                            Discovery paragraph at the bottom of the man page)
+                            is enabled, then the SSSD will first attempt
+                            location based discovery using a query that contains
+                            "_location.hostname.example.com" and then fall back
+                            to traditional SRV discovery. If the location based
+                            discovery succeeds, the IPA servers located with
+                            the location based discovery are treated as primary
+                            servers and the IPA servers located using the
+                            traditional SRV discovery are used as back up
+                            servers
+                        </para>
+                        <para>
+                            Default: false
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_refresh_interval (integer)</term>
+                    <listitem>
+                        <para>
+                            How often should the back end perform periodic DNS update in
+                            addition to the automatic update performed when the back end
+                            goes online.
+                            This option is optional and applicable only when dyndns_update
+                            is true.
+                        </para>
+                        <para>
+                            Default: 0 (disabled)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_update_ptr (bool)</term>
+                    <listitem>
+                        <para>
+                            Whether the PTR record should also be explicitly
+                            updated when updating the client's DNS records.
+                            Applicable only when dyndns_update is true.
+                        </para>
+                        <para>
+                            This option should be False in most IPA
+                            deployments as the IPA server generates the
+                            PTR records automatically when forward records
+                            are changed.
+                        </para>
+                        <para>
+                            Note that <emphasis>dyndns_update_per_family</emphasis>
+                            parameter does not apply for PTR record updates.
+                            Those updates are always sent separately.
+                        </para>
+                        <para>
+                            Default: False (disabled)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_force_tcp (bool)</term>
+                    <listitem>
+                        <para>
+                            Whether the nsupdate utility should default to using
+                            TCP for communicating with the DNS server.
+                        </para>
+                        <para>
+                            Default: False (let nsupdate choose the protocol)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_server (string)</term>
+                    <listitem>
+                        <para>
+                            The DNS server to use when performing a DNS
+                            update. In most setups, it's recommended to leave
+                            this option unset.
+                        </para>
+                        <para>
+                            Setting this option makes sense for environments
+                            where the DNS server is different from the identity
+                            server.
+                        </para>
+                        <para>
+                            Please note that this option will be only used in
+                            fallback attempt when previous attempt using
+                            autodetected settings failed.
+                        </para>
+                        <para>
+                            Default: None (let nsupdate choose the server)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>dyndns_update_per_family (boolean)</term>
+                    <listitem>
+                        <para>
+                            DNS update is by default performed in two steps -
+                            IPv4 update and then IPv6 update. In some cases
+                            it might be desirable to perform IPv4 and IPv6
+                            update in single step.
+                        </para>
+                        <para>
+                            Default: true
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_access_order (string)</term>
+                    <listitem>
+                        <para>
+                            Comma separated list of access control options.
+                            Allowed values are:
+                        </para>
+                        <para>
+                            <emphasis>expire</emphasis>: use
+                            IPA's account expiration policy.
+                        </para>
+                        <para>
+                            <emphasis>pwd_expire_policy_reject,
+                                      pwd_expire_policy_warn,
+                                      pwd_expire_policy_renew:
+                            </emphasis>
+                            These options are useful if users are interested
+                            in being warned that password is about to expire
+                            and authentication is based on using a different
+                            method than passwords - for example SSH keys.
+                       </para>
+                       <para>
+                            The difference between these options is the action
+                            taken if user password is expired:
+                            <itemizedlist>
+                                <listitem>
+                                    <para>
+                                    pwd_expire_policy_reject -
+                                    user is denied to log in,
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    <para>
+                                    pwd_expire_policy_warn -
+                                    user is still able to log in,
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    <para>
+                                    pwd_expire_policy_renew -
+                                    user is prompted to change their
+                                    password immediately.
+                                    </para>
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                        <para>
+                            Please note that 'access_provider = ipa' must
+                            be set for this feature to work.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_deskprofile_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            Desktop Profile related objects.
+                        </para>
+                        <para>
+                            Default: Use base DN
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry condition="with_subid">
+                    <term>ipa_subid_ranges_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            subordinate ranges related objects.
+                        </para>
+                        <para>
+                            Default: the value of
+                            <emphasis>cn=subids,%basedn</emphasis>
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_hbac_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            HBAC related objects.
+                        </para>
+                        <para>
+                            Default: Use base DN
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_host_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Deprecated. Use ldap_host_search_base instead.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_selinux_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            SELinux user maps.
+                        </para>
+                        <para>
+                            See <quote>ldap_search_base</quote> for
+                            information about configuring multiple search
+                            bases.
+                        </para>
+                        <para>
+                            Default: the value of
+                            <emphasis>ldap_search_base</emphasis>
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_subdomains_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            trusted domains.
+                        </para>
+                        <para>
+                            See <quote>ldap_search_base</quote> for
+                            information about configuring multiple search
+                            bases.
+                        </para>
+                        <para>
+                            Default: the value of
+                            <emphasis>cn=trusts,%basedn</emphasis>
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_master_domain_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            master domain object.
+                        </para>
+                        <para>
+                            See <quote>ldap_search_base</quote> for
+                            information about configuring multiple search
+                            bases.
+                        </para>
+                        <para>
+                            Default: the value of
+                            <emphasis>cn=ad,cn=etc,%basedn</emphasis>
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_views_search_base (string)</term>
+                    <listitem>
+                        <para>
+                            Optional. Use the given string as search base for
+                            views containers.
+                        </para>
+                        <para>
+                            See <quote>ldap_search_base</quote> for
+                            information about configuring multiple search
+                            bases.
+                        </para>
+                        <para>
+                            Default: the value of
+                            <emphasis>cn=views,cn=accounts,%basedn</emphasis>
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>krb5_realm (string)</term>
+                    <listitem>
+                        <para>
+                            The name of the Kerberos realm. This is optional and
+                            defaults to the value of <quote>ipa_domain</quote>.
+                        </para>
+                        <para>
+                            The name of the Kerberos realm has a special
+                            meaning in IPA - it is converted into the base
+                            DN to use for performing LDAP operations.
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>krb5_confd_path (string)</term>
+                    <listitem>
+                        <para>
+                            Absolute path of a directory where SSSD should place
+                            Kerberos configuration snippets.
+                        </para>
+                        <para>
+                            To disable the creation of the configuration
+                            snippets set the parameter to 'none'.
+                        </para>
+                        <para>
+                            Default: not set (krb5.include.d subdirectory of
+                            SSSD's pubconf directory)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_deskprofile_refresh (integer)</term>
+                    <listitem>
+                        <para>
+                            The amount of time between lookups of the Desktop
+                            Profile rules against the IPA server. This will
+                            reduce the latency and load on the IPA server if
+                            there are many desktop profiles requests made in a
+                            short period.
+                        </para>
+                        <para>
+                            Default: 5 (seconds)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_deskprofile_request_interval (integer)</term>
+                    <listitem>
+                        <para>
+                            The amount of time between lookups of the Desktop
+                            Profile rules against the IPA server in case the
+                            last request did not return any rule.
+                        </para>
+                        <para>
+                            Default: 60 (minutes)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_hbac_refresh (integer)</term>
+                    <listitem>
+                        <para>
+                            The amount of time between lookups of the HBAC
+                            rules against the IPA server. This will reduce the
+                            latency and load on the IPA server if there are
+                            many access-control requests made in a short
+                            period.
+                        </para>
+                        <para>
+                            Default: 5 (seconds)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_hbac_selinux (integer)</term>
+                    <listitem>
+                        <para>
+                            The amount of time between lookups of the SELinux
+                            maps against the IPA server. This will reduce the
+                            latency and load on the IPA server if there are
+                            many user login requests made in a short
+                            period.
+                        </para>
+                        <para>
+                            Default: 5 (seconds)
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry>
+                    <term>ipa_server_mode (boolean)</term>
+                    <listitem>
+			<para>
+                            This option will be set by the IPA installer
+                            (ipa-server-install) automatically and denotes
+                            if SSSD is running on an IPA server or not.
+                        </para>
+			<para>
+                            On an IPA server SSSD will lookup users and groups
+                            from trusted domains directly while on a client
+                            it will ask an IPA server.
+                        </para>
+                        <para>
+                            NOTE: There are currently some assumptions that
+                            must be met when SSSD is running on an IPA server.
+                            <itemizedlist>
+                                <listitem>
+                                    <para>
+                                        The <quote>ipa_server</quote> option
+                                        must be configured to point to the
+                                        IPA server itself. This is already
+                                        the default set by the IPA installer,
+                                        so no manual change is required.
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    <para>
+                                        The <quote>full_name_format</quote>
+                                        option must not be tweaked to only
+                                        print short names for users from
+                                        trusted domains.
+                                    </para>
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                        <para>
+                            Default: false
+                        </para>
+                    </listitem>
+                </varlistentry>
+
+                <varlistentry condition="with_autofs">
+                    <term>ipa_automount_location (string)</term>
+                    <listitem>
+                        <para>
+                            The automounter location this IPA client will be using
+                        </para>
+                        <para>
+                            Default: The location named "default"
+                        </para>
+                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/autofs_restart.xml" />
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </para>
+        <refsect2 id='views'>
+            <title>VIEWS AND OVERRIDES</title>
+            <para>
+                SSSD can handle views and overrides which are offered by
+                FreeIPA 4.1 and later version. Since all paths and objectclasses
+                are fixed on the server side there is basically no need to
+                configure anything. For completeness the related options are
+                listed here with their default values.
+                <variablelist>
+                    <varlistentry>
+                        <term>ipa_view_class (string)</term>
+                        <listitem>
+                            <para>
+                                Objectclass of the view container.
+                            </para>
+                            <para>
+                                Default: nsContainer
+                            </para>
+                        </listitem>
+                    </varlistentry>
+
+                    <varlistentry>
+                        <term>ipa_view_name (string)</term>
+                        <listitem>
+                            <para>
+                                Name of the attribute holding the name of the
+                                view.
+                            </para>
+                            <para>
+                                Default: cn
+                            </para>
+                        </listitem>
+                    </varlistentry>
+
+                    <varlistentry>
+                        <term>ipa_override_object_class (string)</term>
+                        <listitem>
+                            <para>
+                                Objectclass of the override objects.
+                            </para>
+                            <para>
+                                Default: ipaOverrideAnchor
+                            </para>
+                        </listitem>
+                    </varlistentry>
+
+                    <varlistentry>
+                        <term>ipa_anchor_uuid (string)</term>
+                        <listitem>
+                            <para>
+                                Name of the attribute containing the reference
+                                to the original object in a remote domain.
+                            </para>
+                            <para>
+                                Default: ipaAnchorUUID
+                            </para>
+                        </listitem>
+                    </varlistentry>
+
+                    <varlistentry>
+                        <term>ipa_user_override_object_class (string)</term>
+                        <listitem>
+                            <para>
+                                Name of the objectclass for user overrides. It
+                                is used to determine if the found override
+                                object is related to a user or a group.
+                            </para>
+                            <para>
+                                User overrides can contain attributes given by
+                                <itemizedlist>
+                                    <listitem>
+                                        <para>ldap_user_name</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_uid_number</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_gid_number</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_gecos</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_home_directory</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_shell</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_user_ssh_public_key</para>
+                                    </listitem>
+                                </itemizedlist>
+                            </para>
+                            <para>
+                                Default: ipaUserOverride
+                            </para>
+                        </listitem>
+                    </varlistentry>
+
+                    <varlistentry>
+                        <term>ipa_group_override_object_class (string)</term>
+                        <listitem>
+                            <para>
+                                Name of the objectclass for group overrides. It
+                                is used to determine if the found override
+                                object is related to a user or a group.
+                            </para>
+                            <para>
+                                Group overrides can contain attributes given by
+                                <itemizedlist>
+                                    <listitem>
+                                        <para>ldap_group_name</para>
+                                    </listitem>
+                                    <listitem>
+                                        <para>ldap_group_gid_number</para>
+                                    </listitem>
+                                </itemizedlist>
+                            </para>
+                            <para>
+                                Default: ipaGroupOverride
+                            </para>
+                        </listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </refsect2>
+    </refsect1>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/ipa_modified_defaults.xml" />
+
+    <refsect1 id='subdomains_provider'>
+        <title>SUBDOMAINS PROVIDER</title>
+        <para>
+            The IPA subdomains provider behaves slightly differently
+            if it is configured explicitly or implicitly.
+        </para>
+        <para>
+            If the option 'subdomains_provider = ipa' is found in the
+            domain section of sssd.conf, the IPA subdomains provider is
+            configured explicitly, and all subdomain requests are sent to the
+            IPA server if necessary.
+        </para>
+        <para>
+            If the option 'subdomains_provider' is not set in the domain
+            section of sssd.conf but there is the option 'id_provider = ipa',
+            the IPA subdomains provider is configured implicitly. In this case,
+            if a subdomain request fails and indicates that the server does not
+            support subdomains, i.e. is not configured for trusts, the IPA
+            subdomains provider is disabled. After an hour or after the IPA
+            provider goes online, the subdomains provider is enabled again.
+        </para>
+    </refsect1>
+
+    <refsect1 id='trusted_domains'>
+        <title>TRUSTED DOMAINS CONFIGURATION</title>
+        <para>
+            Some configuration options can also be set for a trusted domain.
+            A trusted domain configuration can be set using the trusted domain
+            subsection as shown in the example below. Alternatively,
+            the <quote>subdomain_inherit</quote> option can be used in the
+            parent domain.
+<programlisting>
+[domain/ipa.domain.com/ad.domain.com]
+ad_server = dc.ad.domain.com
+</programlisting>
+        </para>
+        <para>
+            For more details, see the
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> manual page.
+        </para>
+        <para>
+            Different configuration options are tunable for a trusted
+            domain depending on whether you are configuring SSSD on an
+            IPA server or an IPA client.
+        </para>
+        <refsect2 id='server_configuration'>
+            <title>OPTIONS TUNABLE ON IPA MASTERS</title>
+            <para>
+                The following options can be set in a subdomain
+                section on an IPA master:
+                <itemizedlist>
+                    <listitem>
+                        <para>ad_server</para>
+                    </listitem>
+                    <listitem>
+                        <para>ad_backup_server</para>
+                    </listitem>
+                    <listitem>
+                        <para>ad_site</para>
+                    </listitem>
+                    <listitem>
+                        <para>ldap_search_base</para>
+                    </listitem>
+                    <listitem>
+                        <para>ldap_user_search_base</para>
+                    </listitem>
+                    <listitem>
+                        <para>ldap_group_search_base</para>
+                    </listitem>
+                    <listitem>
+                        <para>use_fully_qualified_names</para>
+                    </listitem>
+                </itemizedlist>
+            </para>
+        </refsect2>
+        <refsect2 id='client_configuration'>
+            <title>OPTIONS TUNABLE ON IPA CLIENTS</title>
+            <para>
+                The following options can be set in a subdomain
+                section on an IPA client:
+                <itemizedlist>
+                    <listitem>
+                        <para>ad_server</para>
+                    </listitem>
+                    <listitem>
+                        <para>ad_site</para>
+                    </listitem>
+                </itemizedlist>
+            </para>
+            <para>
+                Note that if both options are set, only
+                <quote>ad_server</quote> is evaluated.
+            </para>
+            <para>
+                Since any request for a user or a group identity from a
+                trusted domain triggered from an IPA client is resolved
+                by the IPA server, the <quote>ad_server</quote> and
+                <quote>ad_site</quote> options only affect which AD DC will
+                the authentication be performed against. In particular,
+                the addresses resolved from these lists will be written to
+                <quote>kdcinfo</quote> files read by the Kerberos locator
+                plugin. Please refer to the
+                <citerefentry>
+                    <refentrytitle>sssd_krb5_locator_plugin</refentrytitle>
+                    <manvolnum>8</manvolnum>
+                </citerefentry> manual page for more details on the Kerberos
+                locator plugin.
+            </para>
+        </refsect2>
+    </refsect1>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/failover.xml" />
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/service_discovery.xml" />
+
+    <refsect1 id='example'>
+        <title>EXAMPLE</title>
+        <para>
+            The following example assumes that SSSD is correctly
+            configured and example.com is one of the domains in the
+            <replaceable>[sssd]</replaceable> section. This examples shows only
+            the ipa provider-specific options.
+        </para>
+        <para>
+<programlisting>
+[domain/example.com]
+id_provider = ipa
+ipa_server = ipaserver.example.com
+ipa_hostname = myhost.example.com
+</programlisting>
+        </para>
+    </refsect1>
+
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
+
+</refentry>
+</reference>