[deployment-guide/comm-rel: 5/13] trac #492: Purging SSSD cache. Other minor updates
dsilas
dsilas at fedoraproject.org
Sun Jun 20 21:49:06 UTC 2010
commit 40b453284e9adffaf8ee0505a86791082d204c42
Author: David O'Brien <davido at redhat.com>
Date: Wed May 26 22:05:52 2010 +1000
trac #492: Purging SSSD cache. Other minor updates
en-US/SSSD.xml | 330 ++++++++++++++++++++++++++++++++++++--------------------
1 files changed, 213 insertions(+), 117 deletions(-)
---
diff --git a/en-US/SSSD.xml b/en-US/SSSD.xml
index ec949b0..8496191 100644
--- a/en-US/SSSD.xml
+++ b/en-US/SSSD.xml
@@ -4,40 +4,78 @@
<section
id="chap-SSSD_User_Guide-Introduction">
<title>The System Security Services Daemon (SSSD)</title>
- <para>This chapter describes how to install and configure the System Security Services Daemon (SSSD), and how to use the features that it provides. It also provides information on the types of services that it supports and how to configure them, and it introduces and describes the most important configuration options. Sample configuration files are also provided to help you optimize your deployment.</para>
- <section
- id="sect-SSSD_User_Guide-Introduction-What_is_SSSD">
+ <para>This chapter describes how to install and configure the System Security Services Daemon (SSSD), and how to use the features that it provides. It also provides information on the types of services that it supports and how to configure them, and introduces and describes the most important configuration options. Sample configuration files are also provided to help you optimize your deployment.</para>
+
+ <section id="sect-SSSD_User_Guide-Introduction-What_is_SSSD">
<title>What is SSSD?</title>
<para>The System Security Services Daemon (SSSD) is a service which provides access to different identity and authentication providers. You can configure SSSD to use <!--local identity storage for users and groups in an on-disk, LDAP-like database (<abbrev>LDB</abbrev>), rather than the traditional <filename>/etc/passwd</filename> and <filename>/etc/group</filename> file storage mechanisms. You can also configure--> an LDAP identity provider with LDAP authentication, or an LDAP identity provider with Kerberos authentication. SSSD is also extensible; you can configure it to use new identity sources and authentication mechanisms should they arise.</para>
</section>
- <section
- id="sect-SSSD_User_Guide-Introduction-SSSD_Features">
+ <section id="sect-SSSD_User_Guide-Introduction-SSSD_Features">
<title>SSSD Features</title>
- <section
- id="sect-SSSD_User_Guide-SSSD_Features-Performing_Offline_Authentication">
+
+ <section id="sect-SSSD_User_Guide-SSSD_Features-Performing_Offline_Authentication">
<title>Performing Offline Authentication</title>
<para>One of the primary benefits of SSSD is offline authentication. This solves the case of users having a separate corporate account and a local machine account because of the common requirement to implement a Virtual Private Network (<abbrev>VPN</abbrev>).</para>
<para>SSSD can cache remote identities and authentication credentials. This means that you can still authenticate with these remote identities even when a machine is offline. In an SSSD system, you only need to manage one account.</para>
</section>
- <section
- id="sect-SSSD_User_Guide-SSSD_Features-Reducing_Server_Load">
+ <section id="sect-SSSD_User_Guide-SSSD_Features-Reducing_Server_Load">
<title>Reducing Server Load</title>
<para>The use of SSSD also helps to reduce the load on identification servers. For example, using <package>nss_ldap</package>, every client application that needs to request user information opens its own connection to the LDAP server. Managing these multiple connections can lead to a heavy load on the LDAP server. In an SSSD system, only the SSSD Data Provider process actually communicates with the LDAP server, reducing the load to one connection per client system.</para>
</section>
- <section
- id="sect-SSSD_User_Guide-SSSD_Features-Specifying_Multiple_Domains">
+ <section id="sect-SSSD_User_Guide-SSSD_Features-Specifying_Multiple_Domains">
+
<title>Specifying Multiple Domains</title>
- <para>You can use SSSD to specify multiple domains of the same type. Compare this to an <filename>nsswitch.conf</filename> file configuration, with which you can only request user information from a single server of any particular type (LDAP, NIS, etc.). With SSSD, you can create multiple domains of the same, or of different types of identity provider.</para>
- <para>Beginning with version 0.6.0, SSSD maintains a separate database file for each domain. This means that each domain has its own cache, and in the event that problems occur and maintenance is necessary, it is very easy to purge the cache for a single domain, by stopping sssd and deleting the corresponding cache file. These cache files are stored in the <filename>/var/lib/sss/db/</filename> directory.</para>
+ <indexterm>
+ <primary>multiple domains</primary>
+ <secondary>specifying in SSSD</secondary>
+ </indexterm>
+
+ <para>
+ You can use SSSD to specify multiple domains of the same type. Compare this to an <filename>nsswitch.conf</filename> file configuration, with which you can only request user information from a single server of any particular type (LDAP, NIS, etc.). With SSSD, you can create multiple domains of the same, or of different types of identity provider.
+ </para>
+ <para>
+ Beginning with version 0.6.0, SSSD maintains a separate database file for each domain. This means that each domain has its own cache, and in the event that problems occur and maintenance is necessary, it is very easy to purge the cache for a single domain, by stopping <systemitem class="daemon">sssd</systemitem> and deleting the corresponding cache file. These cache files are stored in the <filename>/var/lib/sss/db/</filename> directory.
+ </para>
+
+
+ <para>
+ All cache files are named according to the domain that they represent, for example <filename>cache_<replaceable>DOMAINNAME</replaceable>.ldb</filename>.
+ </para>
+
+ <formalpara>
+ <title>Considerations Associated with Deleting Cache Files</title>
+ <indexterm>
+ <primary>deleting cache files</primary>
+ <secondary>in SSSD</secondary>
+ </indexterm>
+
+ <para>
+ Deleting a domain's cache file can have some unexpected side effects. You should be aware of the following before you proceed:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Deleting the cache file also deletes all user data (both identification and cached credentials). Consequently, you should not proceed unless you are online and can authenticate with your username against the domain's servers, because offline authentication will fail.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you are online and change your configuration to reference a different identity provider, SSSD will recognize users from both providers until the cached entries from the original provider time out.
+ </para>
+ <para>
+ To avoid this situation, you can either purge the cache or use a different domain name for the new provider (this is the recommended practice). Changing the domain name means that when you restart SSSD it will create a new cache file (with the new name) and the old file will be ignored.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
<!-- <para>The local user cache (that is, for a domain where <parameter>id_provider=local</parameter>), is stored in the <filename>sssd.ldb</filename> file.</para> -->
- <para>All cache files are named according to the domain that they represent, for example <filename>cache_<replaceable>DOMAINNAME</replaceable>.ldb</filename>.</para>
+
</section>
- <section
- id="sect-SSSD_User_Guide-SSSD_Features-Differentiating_Like_named_Users">
+ <section id="sect-SSSD_User_Guide-SSSD_Features-Differentiating_Like_named_Users">
<title>Differentiating Like-named Users</title>
<para>SSSD supports the differentiation of like-named users in different domains. For example, you can differentiate the user <systemitem
class="username">kate</systemitem> in the <systemitem
@@ -71,41 +109,41 @@
<para>SSSD also introduces the concept of nested groups. SSSD groups are fully POSIX-compatible, and can contain other groups as members. Any users who are members of child groups are automatically members of parent groups. This can provide significant time savings and reduced administrative overhead for system administrators.</para>
</section>-->
- <section
- id="sect-SSSD_User_Guide-SSSD_Features-Integrating_with_Other_Products">
+ <section id="sect-SSSD_User_Guide-SSSD_Features-Integrating_with_Other_Products">
<title>Integrating with Other Products</title>
<para>Beyond the offline authentication, multiple domain management and other features already described, SSSD is also designed to integrate with and enhance the functionality of IPA clients. In an environment with the latest version of IPA installed, SSSD provides added functionality, including host-based access control, and password migration from an LDAP-only environment into the LDAP/Kerberos 5 environment employed by IPA.</para>
</section>
</section>
- <section
- id="chap-SSSD_User_Guide-Setting_Up_SSSD">
+ <section id="chap-SSSD_User_Guide-Setting_Up_SSSD">
<title>Setting Up SSSD</title>
<para>This section describes how to install SSSD, how to run the service, and how to configure it for each type of supported information provider.</para>
- <section
- id="sect-SSSD_User_Guide-Setting_Up_SSSD-Installing_SSSD">
+
+ <section id="sect-SSSD_User_Guide-Setting_Up_SSSD-Installing_SSSD">
<title>Installing SSSD</title>
<para>Run the following command to install SSSD and any dependencies, including the SSSD Client:</para>
<para>
<command># yum install sssd</command>
</para>
- <para>SSSD requires very few dependencies and should install very quickly, depending on the speed of your network connection.</para>
- <section
- id="sect-SSSD_User_Guide-Installing_SSSD-Upgrading_from_a_Previous_Version">
+ <para>
+ SSSD requires very few dependencies and should install very quickly, depending on the speed of your network connection.
+ </para>
+
+ <section id="sect-SSSD_User_Guide-Installing_SSSD-Upgrading_from_a_Previous_Version">
<title>Upgrading from a Previous Version</title>
<para>Beginning with version 0.6.0, SSSD uses a different and simplified configuration file format, referred to as "Version 2". Consequently, existing configuration files need to be migrated to the new format. SSSD provides a script to automate the migration process.</para>
<para>SSSD checks the value of the <parameter>config_file_version</parameter> parameter during the startup procedure. If this value is correct, the installation continues,otherwise it aborts.</para>
<para>The revised format of the configuration file is described in <xref
linkend="sect-SSSD_User_Guide-SSSD_Example_Configuration_Files-SSSD_Configuration_File_Format"/>
</para>
- <formalpara
- id="form-SSSD_User_Guide-Upgrading_from_a_Previous_Version-Upgrading_Using_RPM_Packages">
+
+ <formalpara id="form-SSSD_User_Guide-Upgrading_from_a_Previous_Version-Upgrading_Using_RPM_Packages">
<title>Upgrading Using RPM Packages</title>
<para>If you are upgrading using RPM packages, the script will run automatically when you upgrade to the new version. This will upgrade the <filename>/etc/sssd/sssd.conf</filename> file to the new format, and copy the existing version to <filename>/etc/sssd/sssd.conf.bak</filename>.</para>
</formalpara>
- <formalpara
- id="form-SSSD_User_Guide-Upgrading_from_a_Previous_Version-Upgrading_Manually">
+
+ <formalpara id="form-SSSD_User_Guide-Upgrading_from_a_Previous_Version-Upgrading_Manually">
<title>Upgrading Manually</title>
<para>It may be necessary to run the upgrade script manually, either because you built SSSD from source files, or because you are using a platform that does not support the use of RPM packages. The synopsis for the script is as follows:</para>
</formalpara>
@@ -147,8 +185,7 @@
</itemizedlist>
</section>
- <section
- id="sect-SSSD_User_Guide-Installing_SSSD-Starting_and_Stopping_SSSD">
+ <section id="sect-SSSD_User_Guide-Installing_SSSD-Starting_and_Stopping_SSSD">
<title>Starting and Stopping SSSD</title>
<note>
<para>Before you start SSSD for the first time, you need to configure at least one domain. Refer to <xref
@@ -166,12 +203,11 @@
</section>
- <section
- id="sect-SSSD_User_Guide-Setting_Up_SSSD-Configuring_SSSD">
+ <section id="sect-SSSD_User_Guide-Setting_Up_SSSD-Configuring_SSSD">
<title>Configuring SSSD</title>
<para>The global configuration of SSSD is stored in the <filename>/etc/sssd/sssd.conf</filename> file. This file consists of various sections, each of which contains a number of key/value pairs. Some keys accept multiple values; use commas to separate multiple values for such keys. This configuration file uses data types of <type>string</type>, <type>integer</type> and <type>Boolean</type> (with values of <literal>TRUE</literal> or <literal>FALSE</literal>). Comments are indicated by either a hash sign (#) or a semicolon (;) in the first column. The following example illustrates some of this syntax:</para>
- <programlisting>[section]
+<programlisting>[section]
# Keys with single values
key1 = value
key2 = val2
@@ -186,26 +222,25 @@ key10 = val10,val11
</note>
<para>Refer to the <citetitle>sssd.conf(5)</citetitle> manual page for more information on global SSSD configuration options.</para>
- <section
- id="sect-SSSD_User_Guide-Configuring_SSSD-Configuring_NSS">
+ <section id="sect-SSSD_User_Guide-Configuring_SSSD-Configuring_NSS">
<title>Configuring NSS</title>
<para>SSSD provides a new NSS module, <systemitem>nss_sss</systemitem>, so that you can configure your system to use SSSD to retrieve user information. Edit the <filename>/etc/nsswitch.conf</filename> file for your system to use the <systemitem>sss</systemitem> name database. For example:</para>
- <programlisting>passwd: files sss
+<programlisting>passwd: files sss
group: files sss
</programlisting>
</section>
- <section
- id="sect-SSSD_User_Guide-Configuring_SSSD-Configuring_PAM">
+ <section id="sect-SSSD_User_Guide-Configuring_SSSD-Configuring_PAM">
<title>Configuring PAM</title>
<warning>
<para>Use extreme care when changing your PAM configuration. A mistake in the PAM configuration file can lock you out of the system completely. Always back up your configuration files before performing any changes, and keep a session open so that you can revert any changes you make should the need arise.</para>
</warning>
- <para>To enable your system to use SSSD for PAM, you need to edit the default PAM configuration file. On &MAJOROS;—based systems, this is the <filename>/etc/pam.d/system-auth</filename> file. Edit this file to reflect the following example, and then restart <systemitem
- class="daemon">sssd</systemitem>:</para>
+ <para>To enable your system to use SSSD for PAM, you need to edit the default PAM configuration file. On &MAJOROS;—based systems, this is the <filename>/etc/pam.d/system-auth</filename> file. Edit this file to reflect the following example, and then restart <systemitem class="daemon">sssd</systemitem>:</para>
+
+ <remark>Validate the following example, especially comments about auto-generation.</remark>
- <programlisting>#%PAM-1.0
+<programlisting>#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth required pam_env.so
@@ -237,8 +272,7 @@ session required pam_unix.so
<para>You can also use <command>authconfig</command> to set up your PAM configuration to use SSSD. Select <guilabel>Use LDAP Authentication</guilabel>, and then replace <filename>pam_ldap.so</filename> with <filename>pam_sss.so</filename> in all files below <filename>/etc/pam.d</filename> or in the <filename>/etc/pam.conf</filename> file.</para>
- <formalpara
- id="form-SSSD_User_Guide-Configuring_PAM-Using_include_Statements_in_PAM_Configurations">
+ <formalpara id="form-SSSD_User_Guide-Configuring_PAM-Using_include_Statements_in_PAM_Configurations">
<title>Using include Statements in PAM Configurations</title>
<para>Recent PAM implementations allow you to use <literal>include</literal> statements in PAM configurations. For example:</para>
</formalpara>
@@ -253,7 +287,8 @@ session optional pam_console.so
</note>
</section>
- <section><title>Configuring Access Control</title>
+ <section>
+ <title>Configuring Access Control</title>
<indexterm>
<primary>Access Control</primary>
<secondary>configuring in SSSD</secondary>
@@ -261,18 +296,30 @@ session optional pam_console.so
<para>SSSD provides a rudimentary access control mechanism based on the implementation of access or deny lists of usernames. This mechanism is known as the <firstterm>Simple Access Provider</firstterm>, and is configured in the <literal>[domain/<<replaceable>NAME</replaceable>>]</literal> sections of the <filename>/etc/sssd/sssd.conf</filename> file. To enable the Simple Access Provider, you need to set the <parameter>access_provider</parameter> parameter to <literal>simple</literal>, and then add usernames as a comma-separated list to either the <parameter>simple_allow_users</parameter> or <parameter>simple_deny_users</parameter> parameters.</para>
- <formalpara><title>Using the Simple Access Provider</title>
- <para>By using the Simple Access Provider, you can continue to support a number of network logins to maintain common network accounts on company or department laptops, but you might want to restrict the use of a particular laptop to one or two users. This means that even if a different user authenticated successfully against the same authentication provider, the Simple Access Provider would prevent that user from gaining access.</para>
+ <formalpara>
+ <title>Using the Simple Access Provider</title>
+ <para>
+ By using the Simple Access Provider, you can continue to support a number of network logins to maintain common network accounts on company or department laptops, but you might want to restrict the use of a particular laptop to one or two users. This means that even if a different user authenticated successfully against the same authentication provider, the Simple Access Provider would prevent that user from gaining access.
+ </para>
</formalpara>
- <para>The Simple Access Provider is also useful if you have two domains configured that have some overlapping users. In this scenario, you can specify <parameter>simple_deny_users</parameter> in one domain for a set of users, thereby guaranteeing that those users will be handled by the other domain.</para>
+ <para>
+ The Simple Access Provider is also useful if you have two domains configured that have some overlapping users. In this scenario, you can specify <parameter>simple_deny_users</parameter> in one domain for a set of users, thereby guaranteeing that those users will be handled by the other domain.
+ </para>
- <para>The following example demonstrates the use of the Simple Access Provider to grant access to two users. This example assumes that SSSD is correctly configured and <systemitem class="domainname">example.com</systemitem> is one of the domains specified in the <literal>[sssd]</literal> section, and only shows the Simple Access Provider-specific options.</para>
+ <para>
+ The following example demonstrates the use of the Simple Access Provider to grant access to two users. This example assumes that SSSD is correctly configured and <systemitem class="domainname">example.com</systemitem> is one of the domains specified in the <literal>[sssd]</literal> section, and only shows the Simple Access Provider-specific options.
+ </para>
<screen>[domain/example.com]
access_provider = simple
simple_allow_users = user1, user2</screen>
- <formalpara><title>Access Control Rules</title>
+ <formalpara>
+ <title>Access Control Rules</title>
+ <indexterm>
+ <primary>Access Control</primary>
+ <secondary>in SSSD, rules</secondary>
+ </indexterm>
<para>The Simple Access Provider adheres to three simple rules to determine which users should or should not be granted access, as follows:
<itemizedlist>
<listitem><para>If both lists are empty, access is granted</para></listitem>
@@ -284,8 +331,7 @@ simple_allow_users = user1, user2</screen>
</formalpara>
</section>
- <section
- id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_Failover">
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_Failover">
<title>Configuring Failover</title>
<para>The failover feature allows back ends to automatically switch to a different server if the primary server fails. These servers are entered as a case-insensitive, comma-separated list in the <literal>[domain/<<replaceable>NAME</replaceable>>]</literal> sections of the <filename>/etc/sssd/sssd.conf</filename> file, and listed in order of preference. This list can contain any number of servers.</para>
@@ -313,30 +359,26 @@ simple_allow_users = user1, user2</screen>
<title>How the Failover Mechanism Works</title>
<para>The failover mechanism distinguishes between machines and services. 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. If there are no more machines to try, the back end as a whole switches to offline mode, and then attempts to reconnect every 30 seconds.</para></section>
+ <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. If there are no more machines to try, the back end as a whole switches to offline mode, and then attempts to reconnect every 30 seconds.</para>
+ </section>
</section>
-
</section>
</section>
- <section
- id="chap-SSSD_User_Guide-Configuring_Services">
+ <section id="chap-SSSD_User_Guide-Configuring_Services">
<title>Configuring Services</title>
- <para>Individual pieces of SSSD functionality are provided by special SSSD services that are started and stopped together with SSSD. The services provided by SSSD have their own configuration sections. The <literal>[sssd]</literal> section also lists the services that are active and should be started when <systemitem
- class="daemon">sssd</systemitem> starts within the <command>services</command> directive.</para>
+ <para>Individual pieces of SSSD functionality are provided by special SSSD services that are started and stopped together with SSSD. The services provided by SSSD have their own configuration sections. The <literal>[sssd]</literal> section also lists the services that are active and should be started when <systemitem class="daemon">sssd</systemitem> starts within the <command>services</command> directive.</para>
<para>SSSD currently provides several services:</para>
<itemizedlist>
<listitem>
<para>
- <systemitem
- class="service">NSS</systemitem> — An NSS provider service that answers NSS requests from the <systemitem>nss_sss</systemitem> module.</para>
+ <systemitem class="service">NSS</systemitem> — An NSS provider service that answers NSS requests from the <systemitem>nss_sss</systemitem> module.</para>
</listitem>
<listitem>
<para>
- <systemitem
- class="service">PAM</systemitem> — A PAM provider service that manages a PAM conversation through the <systemitem>pam_sss</systemitem> PAM module.</para>
+ <systemitem class="service">PAM</systemitem> — A PAM provider service that manages a PAM conversation through the <systemitem>pam_sss</systemitem> PAM module.</para>
</listitem>
<listitem>
<para>
@@ -344,12 +386,10 @@ simple_allow_users = user1, user2</screen>
class="service">monitor</systemitem> — A special service that monitors all other SSSD services, and starts or restarts them as needed. Its options are specified in the <literal>[sssd]</literal> section of the <filename>/etc/sssd/sssd.conf</filename> configuration file.</para>
</listitem>
</itemizedlist>
- <section
- id="sect-SSSD_User_Guide-Configuring_Services-Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Configuring_Services-Configuration_Options">
<title>Configuration Options</title>
<para>The following sections cover the most important SSSD configuration options. Refer to the <citetitle>sssd.conf(5)</citetitle> manual page that ships with SSSD for information on all the available configuration options.</para>
- <section
- id="sect-SSSD_User_Guide-Configuration_Options-General_Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Configuration_Options-General_Configuration_Options">
<title>General Configuration Options</title>
<itemizedlist>
<listitem>
@@ -375,8 +415,7 @@ simple_allow_users = user1, user2</screen>
</itemizedlist>
</section>
- <section
- id="sect-SSSD_User_Guide-Configuration_Options-NSS_Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Configuration_Options-NSS_Configuration_Options">
<title>NSS Configuration Options</title>
<para>Use the following options to configure the Name Service Switch (NSS) service. Refer to the <citetitle>sssd.conf(5)</citetitle> manual page for full details about each option.</para>
<itemizedlist>
@@ -421,8 +460,7 @@ simple_allow_users = user1, user2</screen>
</itemizedlist>
</section>
- <section
- id="sect-SSSD_User_Guide-Configuration_Options-PAM_Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Configuration_Options-PAM_Configuration_Options">
<title>PAM Configuration Options</title>
<para>Use these options to configure the <systemitem role="module">Pluggable Authentication Module</systemitem> (<acronym>PAM</acronym>) service.</para>
<itemizedlist>
@@ -440,8 +478,7 @@ simple_allow_users = user1, user2</screen>
</section>
- <section
- id="chap-SSSD_User_Guide-Configuring_Domains">
+ <section id="chap-SSSD_User_Guide-Configuring_Domains">
<title>Configuring Domains</title>
<para>A domain is a database of user information. SSSD can use more than one domain at the same time, but at least one must be configured for SSSD to start. Using SSSD domains, it is possible to use several LDAP servers providing several unique namespaces. You can specify not only where users' identity information is stored, but how users authenticate against each of the specified domains.</para>
<para>SSSD supports the following identity and authentication combinations:
@@ -451,11 +488,11 @@ simple_allow_users = user1, user2</screen>
<para>This combination uses SSSD's own special identity and authentication provider. Refer to <xref linkend="sect-SSSD_User_Guide-Configuring_Domains-Configuring_the_Local_SSSD_Domain_Database_Provider"/> for information on how to configure SSSD to use this identity and authentication method.</para>
</listitem>-->
<listitem>
- <para>LDAP/LDAP</para>
+ <para><link linkend="sect-SSSD_User_Guide-Configuring_Domains-Configuring_a_Native_LDAP_Domain">LDAP/LDAP</link></para>
<para>This combination uses an LDAP back end as both the identity and authentication provider.</para>
</listitem>
<listitem>
- <para>LDAP/KRB5</para>
+ <para><link linkend="sect-SSSD_User_Guide-Configuring_Domains-Setting_up_Kerberos_Authentication">LDAP/KRB5</link></para>
<para>This combination uses an LDAP back end as the identity provider, and uses Kerberos to provide authentication.</para>
</listitem>
<listitem>
@@ -474,13 +511,11 @@ krb5_kdcip = 192.168.1.1
krb5_realm = EXAMPLE.COM</screen>
- <section
- id="sect-SSSD_User_Guide-Configuring_Domains-Domain_Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Domain_Configuration_Options">
<title>Domain Configuration Options</title>
<para>You can add new domain configurations to the <literal>[domain/<<replaceable>NAME</replaceable>>]</literal> sections of the <filename>/etc/sssd/sssd.conf</filename> file, and then add the list of domains to the <parameter>domains</parameter> attribute of the <literal>[sssd]</literal> section, in the order you want them to be queried.</para>
- <section
- id="sect-SSSD_User_Guide-Domain_Configuration_Options-General_Domain_Configuration_Options">
+ <section id="sect-SSSD_User_Guide-Domain_Configuration_Options-General_Domain_Configuration_Options">
<title>General Domain Configuration Options</title>
<para>You can use the following configuration options in a domain configuration section:</para>
<itemizedlist>
@@ -502,6 +537,9 @@ krb5_realm = EXAMPLE.COM</screen>
<para>Specifies whether or not to enumerate (list) the users and groups of a domain.</para>
<para>Enumeration means that the entire set of available users and groups on the remote source is cached on the local machine. When enumeration is disabled, users and groups are only cached as they are requested. For performance reasons, it is recommended that you disable enumeration for domains with many users and groups.</para>
<para>The default value for this parameter is <literal>FALSE</literal>. Set this value to <literal>TRUE</literal> to enable enumeration of users and groups of a domain.</para>
+ <important>
+ <para>A minor security concern exists when enabling enumeration. With enumeration enabled, users can run the <command>getent passwd</command> command to retrieve the full list of users that could have access to the system. With enumeration disabled, users are required to know individual usernames in advance.</para>
+ </important>
</listitem>
<listitem>
<para>
@@ -534,16 +572,14 @@ krb5_realm = EXAMPLE.COM</screen>
<para>proxy — Support a legacy <systemitem class="service">NSS</systemitem> provider (for example, <package>nss_nis</package>).</para>
<note>
<para>SSSD needs to know which legacy NSS library to load in order to start successfully. If you set <option>id_provider</option> to <literal>proxy</literal>, ensure that you also specify a value for <option>proxy_lib_name</option>. Refer to <xref
- linkend="sect-SSSD_User_Guide-Domain_Configuration_Options-Proxy_Configuration_Options"/> for information on this attribute.</para>
+ linkend="sect-SSSD_User_Guide-Domain_Configuration_Options-Configuring_a_Proxy_Domain"/> for information on this attribute.</para>
</note>
</listitem>
<listitem>
- <para>local — <systemitem
- class="service">SSSD</systemitem> internal local provider.</para>
+ <para>local — <systemitem class="service">SSSD</systemitem> internal local provider.</para>
</listitem>
<listitem>
- <para>ldap — <systemitem
- class="service">LDAP</systemitem> provider.</para>
+ <para>ldap — <systemitem class="service">LDAP</systemitem> provider.</para>
</listitem>
</itemizedlist>
</para>
@@ -582,8 +618,7 @@ ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
</screen>
<note>
<para>With <parameter>use_fully_qualified_names</parameter> set to <literal>FALSE</literal>, you can continue to use the fully-qualified name in your requests, but only the simplified version is displayed in the output.</para>
- <para>SSSD can only parse <systemitem
- class="domainname">name at domain</systemitem>, not <systemitem
+ <para>SSSD can only parse <systemitem class="domainname">name at domain</systemitem>, not <systemitem
class="domainname">name at realm</systemitem>. You can, however, use the same name for both your domain and your realm.</para>
</note>
</listitem>
@@ -609,7 +644,7 @@ ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
</itemizedlist>
</section>
- <section
+ <!--<section
id="sect-SSSD_User_Guide-Domain_Configuration_Options-Proxy_Configuration_Options">
<title>Proxy Configuration Options</title>
<itemizedlist>
@@ -627,12 +662,14 @@ ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
<type>(string)</type>
</para>
<para>This option is only used when the <option>id_provider</option> option is set to <literal>proxy</literal>, and specifies which existing NSS library to proxy identity requests through.</para>
+
<para>This option has no default value. You need to manually specify an existing library to take advantage of this option. For example, set this value to <literal>nis</literal> to use the existing <filename>libnss_nis.so</filename> file.</para>
</listitem>
</itemizedlist>
- <para>The following sections contain examples of how to configure different types of domains.</para>
- </section>
+ </section>-->
+
+<!-- <para>The following sections contain examples of how to configure different types of domains.</para> -->
</section>
<!--
<section
@@ -657,19 +694,16 @@ ipauser01:x:937315651:937315651:ipauser01:/home/ipauser01:/bin/sh
Append <option>‐‐help</option> to any of these commands for details about how to use them.</para>
</section>-->
- <section
- id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_a_Native_LDAP_Domain">
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_a_Native_LDAP_Domain">
<title>Configuring a Native LDAP Domain</title>
<indexterm>
- <primary>LDAP</primary>
- <secondary>SSSD and</secondary>
- <tertiary>Configuring a Native LDAP Domain</tertiary>
+ <primary>SSSD</primary>
+ <secondary>Configuring a Native LDAP Domain for</secondary>
</indexterm>
- <para>A native LDAP domain requires a running LDAP server against which to authenticate. The client configuration is stored in the <filename>/etc/sssd/sssd.conf</filename> file.</para>
- <para>SSSD does not support authentication over an unencrypted channel. Consequently, if you want to authenticate against an LDAP server, <systemitem
- class="protocol">TLS/SSL</systemitem> is required. If the LDAP server is used only as an identity provider, an encrypted channel is not needed.</para>
- <formalpara
- id="form-SSSD_User_Guide-Configuring_a_Native_LDAP_Domain-How_to_Authenticate_Against_a_Native_LDAP_Domain">
+
+ <para>A native LDAP domain is one where the <option>id_provider</option> option is set to <literal>ldap</literal> (<option>id_provider = ldap</option>). Such a domain requires a running LDAP server against which to authenticate. The client configuration is stored in the <filename>/etc/sssd/sssd.conf</filename> file.</para>
+ <para>SSSD does not support authentication over an unencrypted channel. Consequently, if you want to authenticate against an LDAP server, <systemitem class="protocol">TLS/SSL</systemitem> is required. If the LDAP server is used only as an identity provider, an encrypted channel is not needed.</para>
+ <formalpara id="form-SSSD_User_Guide-Configuring_a_Native_LDAP_Domain-How_to_Authenticate_Against_a_Native_LDAP_Domain">
<title>How to Authenticate Against a Native LDAP Domain</title>
<para>Edit your <filename>/etc/sssd/sssd.conf</filename> file to reflect the following example:</para>
</formalpara>
@@ -693,25 +727,39 @@ ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
<formalpara>
<title>Selecting an LDAP Schema</title>
- <indexterm>
- <primary>LDAP</primary>
- <secondary>SSSD and</secondary>
- <tertiary>Selecting an LDAP Schema</tertiary>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Selecting an LDAP Schema for</secondary>
</indexterm>
<para>
- You can set the <parameter>ldap_schema</parameter> attribute to either <literal>rfc2307</literal> or <literal>rfc2307bis</literal>. These schema define how groups in <acronym>LDAP</acronym> are specified. In <citetitle>RFC 2307</citetitle>, group objects use a multi-valued attribute, <parameter>memberuid</parameter>, which lists the names of the users that belong to that group. In <citetitle>RFC 2307bis</citetitle>, instead of the <parameter>memberuid</parameter>, group objects use the <parameter>member</parameter> attribute. Rather than just the name of the user, this attribute contains the full Distinguished Name (DN) of another object in the <acronym>LDAP</acronym> database. This means that groups can have other groups as members. That is, it adds support for nested groups.
+ You can set the <parameter>ldap_schema</parameter> attribute to either <literal>rfc2307</literal> or <literal>rfc2307bis</literal>. These schema define how groups in <acronym>LDAP</acronym> are specified. In <citetitle>RFC 2307</citetitle>, group objects use a multi-valued attribute, <parameter>memberuid</parameter>, which lists the names of the users that belong to that group. In <citetitle>RFC 2307bis</citetitle>, instead of the <parameter>memberuid</parameter>, group objects use the <parameter>member</parameter> attribute. Rather than just the name of the user, this attribute contains the full Distinguished Name (DN) of another object in the LDAP database. This means that groups can have other groups as members. That is, it adds support for nested groups.
</para>
</formalpara>
+
+ <para>
+ SSSD assumes by default that your LDAP server is using <citetitle>RFC 2307</citetitle>. If your LDAP server is using <citetitle>RFC 2307bis</citetitle>, and you do not update the <filename>/etc/sssd/sssd.conf</filename> file accordingly, this can impact how your users and groups are displayed. It also means that some groups will not be available and network resources may be inaccessible even though you have permissions to use them.
+ </para>
+
+ <para>
+ For example, when using <citetitle>RFC 2307bis</citetitle> and you have configured both primary and secondary groups, or are using nested groups, you can us the <command>id</command> command to display these groups:
+ </para>
+ <screen>[f12server at ipaserver ~]$ id
+uid=500(f12server) gid=500(f12server) groups=500(f12server),510(f12tester)
+</screen>
+
+ <para>
+ If instead you have configured your client to use <citetitle>RFC 2307</citetitle> then only the primary group is displayed.
+ </para>
+
<para>
Changes to this setting only affect how SSSD determines the groups to which a user belongs; there is no negative effect on the actual user data. If you do not know the correct value for this attribute, consult your System Administrator.
</para>
<formalpara>
<title>Specifying Timeout Values</title>
- <indexterm>
- <primary>LDAP</primary>
- <secondary>SSSD and</secondary>
- <tertiary>Specifying Timeout Values</tertiary>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Specifying Timeout Values for</secondary>
</indexterm>
<para>
SSSD supports a number of timeout values that apply when configuring an <acronym>LDAP</acronym> domain. These are described below.
@@ -724,7 +772,7 @@ ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
Defaults to five when <option>enumerate</option> = <literal>False</literal>
</para>
<para>
- Defaults to 30 when <option>enumerate</option> = <literal>True</literal>. This option is forced to a minumum of 30 in this case.
+ Defaults to 30 when <option>enumerate</option> = <literal>True</literal>. This option is forced to a minimum of 30 in this case.
</para>
<note>
<para>
@@ -755,17 +803,31 @@ ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
<para>Refer to the <citetitle>sssd-ldap(5)</citetitle> manual page for a full description of all the options that apply to a native <acronym>LDAP</acronym> domain.</para>
</section>
- <section
- id="sect-SSSD_User_Guide-Configuring_Domains-Setting_Up_Authentication_Against_a_Kerberos_Server">
- <title>Setting Up Authentication Against a Kerberos Server</title>
- <para>In order to set up Kerberos authentication, you need to know the address of your KDC and the Kerberos domain. The client configuration is stored in the <filename>/etc/sssd/sssd.conf</filename> file.</para>
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Setting_up_Kerberos_Authentication">
+ <title>Setting up Kerberos Authentication</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Setting up Kerberos authentication for</secondary>
+ </indexterm>
+
+ <para>
+ In order to set up Kerberos authentication, you need to know the address of your <firstterm>key distribution center</firstterm> (KDC) and the Kerberos domain. The client configuration is then stored in the <filename>/etc/sssd/sssd.conf</filename> file.
+ </para>
+
+ <para>
+ The Kerberos 5 authentication back end does not contain an identity provider and must be paired with one in order to function properly (for example, <option>id_provider = ldap</option>). Some information required by the Kerberos 5 authentication back end must be supplied by the identity provider, such as the user's <firstterm>Kerberos Principal Name</firstterm> (UPN). The identity provider configuration should contain an entry to specify this UPN. Refer to the manual page for the applicable identity provider for details on how to configure the UPN.
+ </para>
+ <para>
+ If the UPN is not available in the identity back end, SSSD will construct a UPN using the format <systemitem class="username">username at krb5_realm</systemitem>.
+ </para>
+
<formalpara
- id="form-SSSD_User_Guide-Setting_Up_Authentication_Against_a_Kerberos_Server-How_to_Authenticate_Against_a_Kerberos_Domain">
- <title>How to Authenticate Against a Kerberos Domain</title>
+ id="form-SSSD_User_Guide-Setting_Up_Kerberos_Authentication-How_to_Authenticate_Against_a_Kerberos_Back_End">
+ <title>How to Authenticate Against a Kerberos Back End</title>
<para>Edit your <filename>/etc/sssd/sssd.conf</filename> file to reflect the following example:</para>
</formalpara>
- <screen># A domain with identities provided by LDAP and authentication by Kerberos
+<screen># A domain with identities provided by LDAP and authentication by Kerberos
[domain/KRBDOMAIN]
enumerate = false
id_provider = ldap
@@ -778,13 +840,47 @@ ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
auth_provider = krb5
krb5_kdcip = 192.168.1.1
krb5_realm = EXAMPLE.COM
-krb5_changepw_principle = kadmin/changepw
+krb5_changepw_principal = kadmin/changepw
krb5_ccachedir = /tmp
krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX
krb5_auth_timeout = 15
</screen>
- <para>Refer to the <citetitle>sssd-krb5(5)</citetitle> manual page for a full description of all the parameters that apply to configuring Kerberos authentication.</para>
+
+ <para>This example describes the minimum options that must be configured when using Kerberos authentication. Refer to the <citetitle>sssd-krb5(5)</citetitle> manual page for a full description of all the options that apply to configuring Kerberos authentication.</para>
+ </section>
+
+
+ <section id="sect-SSSD_User_Guide-Domain_Configuration_Options-Configuring_a_Proxy_Domain">
+ <title>Configuring a Proxy Domain</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Configuring a proxy domain for</secondary>
+ </indexterm>
+
+ <para>
+ SSSD currently only supports LDAP and Kerberos as authentication providers. If you prefer to use SSSD (for example, to take advantage of its caching functionality), but SSSD does not support your authentication method natively, you can set up a proxy authentication provider. This could be the case if you use fingerprint scanners or smart cards as part of your authentication process.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>proxy_pam_target</option>
+ <type>(string)</type>
+ </para>
+ <para>This option is only used when the <option>auth_provider</option> option is set to <literal>proxy</literal>, and specifies the proxy target that <acronym>PAM</acronym> proxies to.</para>
+ <para>This option has no default value. If proxy authentication is required, you need to specify your own <acronym>PAM</acronym> target. This corresponds to a file containing <acronym>PAM</acronym> stack information in the system's default <acronym>PAM</acronym> configuration directory. On &MAJOROS;-based systems, this is the <filename>/etc/pam.d/</filename> directory.</para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>proxy_lib_name</option>
+ <type>(string)</type>
+ </para>
+ <para>This option is only used when the <option>id_provider</option> option is set to <literal>proxy</literal>, and specifies which existing NSS library to proxy identity requests through.</para>
+
+ <para>This option has no default value. You need to manually specify an existing library to take advantage of this option. For example, set this value to <literal>nis</literal> to use the existing <filename>libnss_nis.so</filename> file.</para>
+ </listitem>
+ </itemizedlist>
</section>
+
</section>
<!--<section
More information about the docs-commits
mailing list