Consistency Editing LDAP section of Cloud Admin Guide

Improving consistency and brevity in the Cloud Admin Guide
keystone section, specifically the LDAP chapters, with consistent
procedures, lists, and descriptions of additional config
options.

Change-Id: If4815ee4ac3248c3efff936893f336ccca638fa6
Implements: blueprint user-guides-reorganised

doc/admin-guide-cloud/source/keystone_integrate_assignment_backend_ldap.rst

@@ -6,18 +6,17 @@ Integrate assignment back end with LDAP
 
 When you configure the OpenStack Identity service to use LDAP servers,
 you can split authentication and authorization using the *assignment*
-feature. Integrating the assignment back end with LDAP allows
+feature. Integrating the *assignment* back end with LDAP allows
 administrators to use projects (tenant), roles, domains, and role
 assignments in LDAP.
 
 .. note::
 
-   Using LDAP as an assignment back end is not recommended.
-
-.. note::
-
-   The OpenStack Identity service does not support domain-specific
-   assignment back ends.
+   Be aware of domain-specific back end limitations when configuring
+   OpenStack Identity. The OpenStack Identity service
+   does not support domain-specific assignment back ends.
+   Using LDAP as an assignment back end is not
+   recommended.
 
 .. important::
 
@@ -25,7 +24,7 @@ assignments in LDAP.
    define the destination LDAP server in the :file:`keystone.conf` file.
    For more information, see :ref:`integrate-identity-with-ldap`.
 
-**Integrating assignment back ends with LDAP**
+**To integrate assignment back ends with LDAP**
 
 #. Enable the assignment driver. In the ``[assignment]`` section, set the
    ``driver`` configuration key to

doc/admin-guide-cloud/source/keystone_integrate_identity_backend_ldap.rst

@@ -14,7 +14,7 @@ administrators to use users and groups in LDAP.
    define the destination LDAP server in the ``keystone.conf`` file.
    For more information, see :ref:`integrate-identity-with-ldap`.
 
-**Integrating an Identity back end with LDAP**
+**To integrate one Identity back end with LDAP**
 
 #. Enable the LDAP Identity driver in the ``keystone.conf`` file. This
    allows LDAP as an identity back end:
@@ -73,7 +73,7 @@ administrators to use users and groups in LDAP.
       During service restart, authentication and authorization are
       unavailable.
 
-**Integrating Identity with multiple back ends**
+**To integrate multiple Identity back ends with LDAP**
 
 #. Set the following options in the :file:`/etc/keystone/keystone.conf` file:
 
@@ -181,7 +181,8 @@ administrators to use users and groups in LDAP.
 
 Set these options in the :file:`/etc/keystone/keystone.conf` file for a
 single LDAP server, or :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf`
-files for multiple back ends.
+files for multiple back ends. Example configurations appear below each
+setting summary:
 
 Filters
    Use filters to control the scope of data presented through LDAP.
@@ -240,3 +241,13 @@ Enabled emulation
       [ldap]
       user_enabled_emulation = false
       user_enabled_emulation_dn = false
+
+When you have finished configuration, restart the OpenStack Identity
+service::
+
+   # service keystone restart
+
+.. warning::
+
+   During service restart, authentication and authorization are
+   unavailable.

doc/admin-guide-cloud/source/keystone_integrate_with_ldap.rst

@@ -30,7 +30,8 @@ providing user authentication through the LDAP directory.
    For the OpenStack Identity service to access LDAP servers, you must
    enable the ``authlogin_nsswitch_use_ldap`` boolean value for SELinux
    on the Openstack Identity server. To enable and make the option
-   persistent across reboots:
+   persistent across reboots, set the following boolean value as the
+   root user:
 
 .. code-block:: console
 
@@ -55,22 +56,21 @@ end configuration examples. Modify these examples as needed.
 
 **To define the destination LDAP server**
 
-Define the destination LDAP server in the  :file:`keystone.conf` file:
+#. Define the destination LDAP server in the  :file:`keystone.conf` file:
 
-.. code-block:: ini
-   :linenos:
+   .. code-block:: ini
+      :linenos:
 
-   [ldap]
-   url = ldap://localhost
-   user = dc=Manager,dc=example,dc=org
-   password = samplepassword
-   suffix = dc=example,dc=org
-   use_dumb_member = False
-   allow_subtree_delete = False
+      [ldap]
+      url = ldap://localhost
+      user = dc=Manager,dc=example,dc=org
+      password = samplepassword
+      suffix = dc=example,dc=org
+      use_dumb_member = False
+      allow_subtree_delete = False
 
-.. note::
-
-   Configure ``dumb_member`` if you set ``use_dumb_member`` to true.
+#. Configure ``dumb_member`` to true if your environment requires
+   the ``use_dumb_member`` variable.
 
    .. code-block:: ini
       :linenos:
@@ -82,21 +82,23 @@ Define the destination LDAP server in the  :file:`keystone.conf` file:
 
 Set these options in the :file:`/etc/keystone/keystone.conf` file for a
 single LDAP server, or :file:`/etc/keystone/domains/keystone.DOMAIN_NAME.conf`
-files for multiple back ends.
+files for multiple back ends. Example configurations appear below each
+setting summary:
 
 **Query option**
 
-Use ``query_scope`` to control the scope level of data presented
-(search only the first level or search an entire sub-tree) through LDAP.
+.. hlist::
+   :columns: 1
 
-Use ``page_size`` to control the maximum results per page. A value of zero
-disables paging.
-
-Use ``alias_dereferencing`` to control the LDAP dereferencing option for
-queries.
-
-Use ``chase_referrals`` to override the system's default referral chasing
-behavior for queries.
+   * Use ``query_scope`` to control the scope level of data presented
+     (search only the first level or search an entire sub-tree)
+     through LDAP.
+   * Use ``page_size`` to control the maximum results per page. A value
+     of zero disables paging.
+   * Use ``alias_dereferencing`` to control the LDAP dereferencing
+     option for queries.
+   * Use ``chase_referrals`` to override the system's default referral
+     chasing behavior for queries.
 
 .. code-block:: ini
    :linenos:

doc/admin-guide-cloud/source/keystone_secure_identity_to_ldap_backend.rst

@@ -3,14 +3,13 @@ Secure the OpenStack Identity service connection to an LDAP back end
 
 The Identity service supports the use of TLS to encrypt LDAP traffic.
 Before configuring this, you must first verify where your certificate
-authority file is located. For more information, see ?.
-
-.. TODO (DC) figure out how to reference
-   keystone_integrate_identity_with_ldap.rst with orphan tag
+authority file is located. For more information, see the
+`OpenStack Security Guide SSL introduction <http://docs.openstack.org/
+security-guide/secure-communication/introduction-to-ssl-and-tls.html>`_.
 
 Once you verify the location of your certificate authority file:
 
-**Configuring TLS encryption on LDAP traffic**
+**To configure TLS encryption on LDAP traffic**
 
 #. Open the :file:`/etc/keystone/keystone.conf` configuration file.
 
@@ -35,21 +34,20 @@ Once you verify the location of your certificate authority file:
    configuration key in the ``[ldap]`` section to ``demand``, ``allow``, or
    ``never``:
 
-   - ``demand``
-        A certificate will always be requested from the LDAP
-        server. The session will be terminated if no certificate is provided,
-        or if the certificate provided cannot be verified against the
-        existing certificate authorities file.
+   .. hlist::
+      :columns: 1
 
-   - ``allow``
-        A certificate will always be requested from the LDAP
-        server. The session will proceed as normal even if a certificate is
-        not provided. If a certificate is provided but it cannot be verified
-        against the existing certificate authorities file, the certificate
-        will be ignored and the session will proceed as normal.
-
-   -  ``never``
-         A certificate will never be requested.
+      * ``demand`` - The LDAP server always recieves certificate
+        requests. The session terminates if no certificate
+        is provided, or if the certificate provided cannot be verified
+        against the existing certificate authorities file.
+      * ``allow`` - The LDAP server always recieves certificate
+        requests. The session will proceed as normal even if a certificate
+        is not provided. If a certificate is provided but it cannot be
+        verified against the existing certificate authorities file, the
+        certificate will be ignored and the session will proceed as
+        normal.
+      * ``never`` - A certificate will never be requested.
 
 On distributions that include openstack-config, you can configure TLS
 encryption on LDAP traffic by running the following commands instead::