[deployment-guide/comm-rel: 36/74] last minute changes from tech review
dsilas
dsilas at fedoraproject.org
Tue Jul 6 21:12:16 UTC 2010
commit ae4fe644dd55d90a860170f693c3520f228629db
Author: David O'Brien <davido at redhat.com>
Date: Fri Jun 25 11:51:09 2010 +1000
last minute changes from tech review
en-US/SSSD.xml | 223 ++++++++++++++++++++++++++++++--------------------------
1 files changed, 121 insertions(+), 102 deletions(-)
---
diff --git a/en-US/SSSD.xml b/en-US/SSSD.xml
index 05e73fb..dc1099d 100644
--- a/en-US/SSSD.xml
+++ b/en-US/SSSD.xml
@@ -15,7 +15,7 @@
<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 a native LDAP domain (that is, an LDAP identity provider with LDAP authentication), or an LDAP identity provider with Kerberos authentication. It provides an NSS and PAM interface to the system, a pluggable back-end system to connect to multiple different account sources, as well as a D-Bus interface.
+ The System Security Services Daemon (SSSD) is a service which provides access to different identity and authentication providers. You can configure SSSD to use a native LDAP domain (that is, an LDAP identity provider with LDAP authentication), or an LDAP identity provider with Kerberos authentication. It provides an NSS and PAM interface to the system, a pluggable back-end system to connect to multiple different account sources.
</para>
<para>
SSSD is also extensible; you can configure it to use new identity sources and authentication mechanisms should they arise.
@@ -145,9 +145,9 @@
<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
+
+
+ <para>The format of the configuration file is described in <xref
linkend="sect-SSSD_User_Guide-SSSD_Example_Configuration_Files-SSSD_Configuration_File_Format"/>
</para>
@@ -251,7 +251,6 @@ group: files sss
</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>
- <remark>Validate the following example, especially comments about auto-generation.</remark>
<programlisting>#%PAM-1.0
# This file is auto-generated.
@@ -281,9 +280,7 @@ session sufficient pam_sss.so
session required pam_unix.so
</programlisting>
-<remark>Need to validate the following para.</remark>
- <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">
<title>Using include Statements in PAM Configurations</title>
@@ -315,9 +312,7 @@ session optional pam_console.so
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 <option>simple_deny_users</option> 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.
@@ -368,11 +363,13 @@ simple_allow_users = user1, user2</screen>
<para>For example, if you have configured a native LDAP domain, you could specify the following as your <parameter>ldap_uri</parameter> values:</para>
<screen>ldap_uri = ldap://ldap0.mydomain.org, ldap://ldap1.mydomain.org, ldap://ldap2.mydomain.org</screen>
- <para>In this configuration, <uri>ldap://ldap0.mydomain.org</uri> functions as the primary server. If this server fails, the SSSD failover mechanism first attempts to connect to <uri>ldap1.mydomain.org</uri>, and if that is unavailable, it then attempts to connect to <uri>ldap2.mydomain.org</uri>. If the primary server is restored, the failover mechanism automatically restores operations to use that server instead of any failover servers.</para>
+ <para>In this configuration, <uri>ldap://ldap0.mydomain.org</uri> functions as the primary server. If this server fails, the SSSD failover mechanism first attempts to connect to <uri>ldap1.mydomain.org</uri>, and if that is unavailable, it then attempts to connect to <uri>ldap2.mydomain.org</uri>.</para>
<para>If the parameter that specifies which server to connect to for the specific domain (for example, <parameter>ldap_uri</parameter>, <parameter>krb5_kdcip</parameter>, …) is not specified, the back end defaults to using <replaceable>Use service discovery</replaceable>. Refer to <xref linkend="sect-SSSD_User_Guide-Configuring_Domains-Configuring_Failover-Using_SRV_Records_with_Failover"/> for more information on service discovery.</para>
- <important><para>Do not use multiple <parameter>ldap_uri</parameter> parameters to specify your failover servers. The failover servers must be entered as a comma-separated list of values for a single <parameter>ldap_uri</parameter> parameter. If you enter multiple <parameter>ldap_uri</parameter> parameters, SSSD only recognizes the last entry.</para></important>
+ <important><para>Do not use multiple <parameter>ldap_uri</parameter> parameters to specify your failover servers. The failover servers must be entered as a comma-separated list of values for a single <parameter>ldap_uri</parameter> parameter. If you enter multiple <parameter>ldap_uri</parameter> parameters, SSSD only recognizes the last entry.</para>
+ <para>Future versions of SSSD will throw an error upon receiving additional ldap_uri entries.</para>
+ </important>
<section id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_Failover-Using_SRV_Records_with_Failover">
<title>Using SRV Records with Failover</title>
@@ -383,7 +380,10 @@ simple_allow_users = user1, user2</screen>
<para>A typical configuration would contain multiple such records, each with a different priority (for failover) and different weights (for load balancing).</para>
- <para>The client then makes an SRV DNS query to retrieve a list of host names, their priorities, and weights. These queries are of the form _<replaceable>service</replaceable>._<replaceable>protocol</replaceable>._<replaceable>domain</replaceable>, for example, <literal>_ldap._tcp._redhat.com</literal>. The client then sorts this list according to the priorities and weights, and connects to the first server in this sorted list.</para></section>
+ <para>The client then makes an SRV DNS query to retrieve a list of host names, their priorities, and weights. These queries are of the form _<replaceable>service</replaceable>._<replaceable>protocol</replaceable>._<replaceable>domain</replaceable>, for example, <literal>_ldap._tcp._redhat.com</literal>. The client then sorts this list according to the priorities and weights, and connects to the first server in this sorted list.</para>
+
+ <para>For more information on SRV records, refer to the <ulink url="http://tools.ietf.org/html/rfc2782">RFC</ulink>.</para>
+ </section>
<section>
<title>How the Failover Mechanism Works</title>
@@ -571,9 +571,6 @@ 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>
@@ -731,23 +728,24 @@ 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">
- <title>Configuring a Native LDAP Domain</title>
- <indexterm>
- <primary>SSSD</primary>
- <secondary>Configuring a Native LDAP Domain for</secondary>
- </indexterm>
- <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. This can be an open source LDAP server such as OpenLDAP or Microsoft Active Directory. SSSD currently supports Microsoft Active Directory 2003 (+Services For UNIX) and Active Directory 2008. In all cases, 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>
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_a_Native_LDAP_Domain">
+ <title>Configuring an LDAP Domain</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Configuring an LDAP domain for</secondary>
+ </indexterm>
+ <para>
+ An 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. This can be an open source LDAP server such as OpenLDAP or Microsoft Active Directory. SSSD currently supports Microsoft Active Directory 2003 (+Services For UNIX) and Active Directory 2008. In all cases, the client configuration is stored in the <filename>/etc/sssd/sssd.conf</filename> file.
+ </para>
+
+ <formalpara id="form-SSSD_User_Guide-Configuring_a_Native_LDAP_Domain-How_to_Authenticate_Against_an_LDAP_Server">
+ <title>How to Authenticate Against an LDAP Server</title>
+ <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>
+ <para>Edit your <filename>/etc/sssd/sssd.conf</filename> file to reflect the following example:</para>
<screen># A native LDAP domain
[domain/LDAP]
@@ -765,19 +763,12 @@ tls_reqcert = demand
ldap_tls_cacert = /etc/pki/tls/certs/ca-bundle.crt
</screen>
- <formalpara><title>How to Authenticate Against a Microsoft Active Directory LDAP Domain</title>
- <indexterm>
- <primary>SSSD</primary>
- <secondary>Authenticating against Microsoft Active Directory</secondary>
- </indexterm>
- <para>dummy text</para>
- </formalpara>
- <formalpara>
+ <formalpara id="form-SSSD_User_Guide-Configuring_a_Native_LDAP_Domain-Selecting_an_LDAP_Schema">
<title>Selecting an LDAP Schema</title>
<indexterm>
<primary>SSSD</primary>
- <secondary>Selecting an LDAP Schema for</secondary>
+ <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 LDAP database. This means that groups can have other groups as members. That is, it adds support for nested groups.
@@ -803,11 +794,11 @@ uid=500(f12server) gid=500(f12server) groups=500(f12server),510(f12tester)
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>
+ <formalpara id="form-SSSD_User_Guide-Configuring_a_Native_LDAP_Domain-Specifying_Timeout_Values">
<title>Specifying Timeout Values</title>
<indexterm>
<primary>SSSD</primary>
- <secondary>Specifying Timeout Values for</secondary>
+ <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.
@@ -855,72 +846,43 @@ uid=500(f12server) gid=500(f12server) groups=500(f12server),510(f12tester)
</formalpara>
</section>
- <section id="sect-SSSD_User_Guide-Configuring_Domains-Setting_up_Kerberos_Authentication">
- <title>Setting up Kerberos Authentication</title>
+ <section id="sect-SSSD_User_Guide-Configuring_Domains-Configuring_a_Microsoft_Active_Directory_Domain">
+ <title>Configuring a Microsoft Active Directory Domain</title>
<indexterm>
<primary>SSSD</primary>
- <secondary>Setting up Kerberos authentication for</secondary>
+ <secondary>Configuring a Microsoft Active Directory Domain 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>
+ <remark>https://bugzilla.redhat.com/show_bug.cgi?id=601870</remark>
- <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>
+ <para>Edit your <filename>/etc/sssd/sssd.conf</filename> file to reflect the following example:</para>
- <formalpara
- 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># Example LDAP domain where the LDAP server is an Active Directory server.
-<screen># A domain with identities provided by LDAP and authentication by Kerberos
-[domain/KRBDOMAIN]
+[domain/AD]
+description = LDAP domain with AD server
enumerate = false
+min_id = 1000
+;
id_provider = ldap
-chpass_provider = krb5
-ldap_uri = ldap://ldap.mydomain.org
-ldap_user_search_base = dc=mydomain,dc=org
-tls_reqcert = demand
-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_principal = kadmin/changepw
-krb5_ccachedir = /tmp
-krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX
-krb5_auth_timeout = 15
-</screen>
-
- <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-Configuring_Domains-Setting_up_SASL_GSSAPI_Authentication">
- <title>Setting up SASL/GSSAPI Authentication</title>
- <indexterm>
- <primary>SSSD</primary>
- <secondary>Setting up SASL/GSSAPI Authentication for</secondary>
- </indexterm>
- <para>dummy text</para>
- <remark>https://bugzilla.redhat.com/show_bug.cgi?id=601870</remark>
-
- </section>
-
- <section><title>Configuring a Microsoft Active Directory Domain</title>
- <indexterm>
- <primary>SSSD</primary>
- <secondary>Configuring a Microsoft Active Directory Domain for</secondary>
- </indexterm>
- <para>dummy text</para>
- <remark>https://bugzilla.redhat.com/show_bug.cgi?id=601870</remark>
-
-
+auth_provider = ldap
+ldap_uri = ldap://your.ad.server.com
+ldap_schema = rfc2307bis
+ldap_user_search_base = cn=users,dc=example,dc=com
+ldap_group_search_base = cn=users,dc=example,dc=com
+ldap_default_bind_dn = cn=Administrator,cn=Users,dc=example,dc=com
+ldap_default_authtok_type = password
+ldap_default_authtok = YOUR_PASSWORD
+ldap_user_object_class = person
+ldap_user_name = msSFU30Name
+ldap_user_uid_number = msSFU30UidNumber
+ldap_user_gid_number = msSFU30GidNumber
+ldap_user_home_directory = msSFU30HomeDirectory
+ldap_user_shell = msSFU30LoginShell
+ldap_user_principal = userPrincipalName
+ldap_group_object_class = group
+ldap_group_name = msSFU30Name
+ldap_group_gid_number = msSFU30GidNumber</screen>
</section>
@@ -958,6 +920,63 @@ krb5_auth_timeout = 15
</section>
+
+ <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_Kerberos_Authentication-How_to_Set_up_Kerberos_Authentication">
+ <title>How to Set up Kerberos Authentication</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
+[domain/KRBDOMAIN]
+enumerate = false
+id_provider = ldap
+chpass_provider = krb5
+ldap_uri = ldap://ldap.mydomain.org
+ldap_user_search_base = dc=mydomain,dc=org
+tls_reqcert = demand
+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_principal = kadmin/changepw
+krb5_ccachedir = /tmp
+krb5_ccname_template = FILE:%d/krb5cc_%U_XXXXXX
+krb5_auth_timeout = 15
+</screen>
+
+ <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-Configuring_Domains-Setting_up_SASL_GSSAPI_Authentication">
+ <title>Setting up SASL/GSSAPI Authentication</title>
+ <indexterm>
+ <primary>SSSD</primary>
+ <secondary>Setting up SASL/GSSAPI authentication for</secondary>
+ </indexterm>
+ <para>dummy text</para>
+ <remark>https://bugzilla.redhat.com/show_bug.cgi?id=601870</remark>
+ </section>
+
<!--<section
id="chap-SSSD_User_Guide-Using_the_SSSD_Management_Tools">
<title>Using the SSSD Management Tools</title>
@@ -1093,9 +1112,9 @@ GroupE:*:518:UserE
<title>Producing More Verbose Log Files</title>
<para>If you are unable to identify and resolve any problems with SSSD after inspection of the default log files, you can configure SSSD to produce more verbose files. You can set the <option>debug_level</option> option in the <filename>/etc/sssd/sssd.conf</filename> for the domain that is causing concern, and then restart SSSD. Refer to the <citetitle>sssd.conf(5)</citetitle> manual page for more information on how to set the <option>debug_level</option> for a specfic domain.</para>
</formalpara>
- <para>All log files include timestamps on debug messages by default. This can make it easier to understand any errors that may occur, why they occurred, and how to address them. If necessary, you can disable these timestamps by setting the appropriate parameter to <literal>0</literal> in the <filename>/etc/sssd/sssd.conf</filename> file:</para>
+ <para>All log files include timestamps on debug messages by default. This can make it easier to understand any errors that may occur, why they occurred, and how to address them. If necessary, you can disable these timestamps by setting the appropriate parameter to <literal>FALSE</literal> in the <filename>/etc/sssd/sssd.conf</filename> file:</para>
- <screen>--debug-timestamps=0
+ <screen>--debug-timestamps=FALSE
</screen>
</section>
More information about the docs-commits
mailing list