Merge "DOCS: Configuration section - cleanup"

doc/source/install-guide/configure-ceph.rst

@@ -1,11 +1,11 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
 Configuring the Ceph client (optional)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+======================================
 
 Ceph is a massively scalable, open source, distributed storage system.
 
-These links provide more details around how to use Ceph with OpenStack:
+These links provide details on how to use Ceph with OpenStack:
 
 * `Ceph Block Devices and OpenStack`_
 * `Ceph - The De Facto Storage Backend for OpenStack`_ *(Hong Kong Summit
@@ -19,30 +19,32 @@ These links provide more details around how to use Ceph with OpenStack:
 .. _OpenStack Config Reference - Ceph RADOS Block Device (RBD): http://docs.openstack.org/liberty/config-reference/content/ceph-rados.html
 .. _OpenStack-Ansible and Ceph Working Example: https://www.openstackfaq.com/openstack-ansible-ceph/
 
-Configuring Ceph storage servers is outside the scope of this documentation.
+.. note::
+
+   Configuring Ceph storage servers is outside the scope of this documentation.
 
 Authentication
---------------
+~~~~~~~~~~~~~~
 
-The ``cephx`` authentication method is strongly recommended in the `Ceph
+We recommend the ``cephx`` authentication method in the `Ceph
-config reference`_ and OpenStack-Ansible enables ``cephx`` by default for
+config reference`_. OpenStack-Ansible enables ``cephx`` by default for
-the Ceph client.  Deployers may choose to override this setting by using the
+the Ceph client. You can choose to override this setting by using the
 ``cephx`` Ansible variable:
 
 .. code-block:: yaml
 
     cephx: False
 
-Ceph **must** be deployed on a trusted network if ``cephx`` is disabled.
+Deploy Ceph on a trusted network if disabling ``cephx``.
 
 .. _Ceph config reference: http://docs.ceph.com/docs/master/rados/configuration/auth-config-ref/
 
 Configuration file overrides
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-OpenStack-Ansible provides the ``ceph_conf_file`` variable which allows
+OpenStack-Ansible provides the ``ceph_conf_file`` variable. This allows
-deployers to specify configuration file options to override the default
+you to specify configuration file options to override the default
-Ceph configuration.
+Ceph configuration:
 
 .. code-block:: console
 
@@ -57,7 +59,7 @@ Ceph configuration.
 
 The following minimal example configuration sets nova and glance
 to use ceph pools: ``ephemeral-vms`` and ``images`` respectively.
-The example uses cephx authentication, and requires existing ``glance`` and
+The example uses ``cephx`` authentication, and requires existing ``glance`` and
 ``cinder`` accounts for ``images`` and ``ephemeral-vms`` pools.
 
 .. code-block:: console
@@ -65,9 +67,8 @@ The example uses cephx authentication, and requires existing ``glance`` and
     glance_default_store: rbd
     nova_libvirt_images_rbd_pool: ephemeral-vms
 
-
 Monitors
---------
+~~~~~~~~
 
 The `Ceph Monitor`_ maintains a master copy of the cluster map.
 OpenStack-Ansible provides the ``ceph_mons`` variable and expects a list of

doc/source/install-guide/configure-configurationintegrity.rst

@@ -1,28 +1,29 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
 Checking the integrity of your configuration files
---------------------------------------------------
+==================================================
 
-Here are a few steps to execute before running any playbook:
+Execute the following steps before running any playbook:
 
-#. Make sure all the files edited in ``/etc/`` are ansible
+#. Ensure all files edited in ``/etc/`` are Ansible
    YAML compliant. Guidelines can be found here:
    `<http://docs.ansible.com/ansible/YAMLSyntax.html>`_
 
-#. Check the integrity of your yaml files using a yaml linter.
+#. Check the integrity of your YAML files:
 
    .. note:: Here is an online linter: `<http://www.yamllint.com/>`_
 
-#. Run your command with syntax-check, for example,
+#. Run your command with ``syntax-check``:
-   in the playbooks directory:
 
    .. code-block:: shell-session
 
       # openstack-ansible setup-infrastructure.yml --syntax-check
 
-#. Recheck that all indentation seems correct: the syntax of the
+#. Recheck that all indentation is correct.
-   configuration files can be correct while not being meaningful
+
-   for openstack-ansible.
+   .. note::
+      The syntax of the configuration files can be correct
+      while not being meaningful for OpenStack-Ansible.
 
 --------------
 

doc/source/install-guide/configure-federation-idp-adfs.rst

@@ -1,7 +1,7 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
-Configure Active Directory Federation Services (ADFS) 3.0 as an identity provider
+Configuring Active Directory Federation Services (ADFS) 3.0 as an identity provider
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===================================================================================
 
 To install ADFS:
 
@@ -9,10 +9,10 @@ To install ADFS:
 * `ADFS installation procedure from Microsoft Technet <https://technet.microsoft.com/en-us/library/dn303423>`_
 
 Configuring ADFS
-----------------
+~~~~~~~~~~~~~~~~
 
-#. The ADFS Server must already trust the service provider's (SP) keystone
+#. Ensure the ADFS Server trusts the service provider's (SP) keystone
-   certificate. It is recommended to have the ADFS CA (or a
+   certificate. We recommend to have the ADFS CA (or a
    public CA) sign a certificate request for the keystone service.
 #. In the ADFS Management Console, choose ``Add Relying Party Trust``.
 #. Select ``Import data about the relying party published online or on a
@@ -20,8 +20,9 @@ Configuring ADFS
    for example, ``https://<SP_IP_ADDRESS or DNS_NAME>:5000/Shibboleth.sso/Metadata``)
 
    .. note::
-      ADFS may give a warning message that some of the content gathered from metadata
+
-      was skipped because is not supported by ADFS.
+      ADFS may give a warning message. The message states that ADFS skipped
+      some of the content gathered from metadata because it is not supported by ADFS
 
 #. Continuing the wizard, select ``Permit all users to access this
    relying party``.
@@ -32,10 +33,11 @@ Configuring ADFS
 #. Click :guilabel:`OK` to apply the rule and finalize the setup.
 
 References
-----------
+~~~~~~~~~~
-* http://blogs.technet.com/b/rmilne/archive/2014/04/28/how-to-install-adfs-2012-r2-for-office-365.aspx
+
-* http://blog.kloud.com.au/2013/08/14/powershell-deployment-of-web-application-proxy-and-adfs-in-under-10-minutes/
+* `http://blogs.technet.com/b/rmilne/archive/2014/04/28/how-to-install-adfs-2012-r2-for-office-365.aspx`_
-* https://ethernuno.wordpress.com/2014/04/20/install-adds-on-windows-server-2012-r2-with-powershell/
+* `http://blog.kloud.com.au/2013/08/14/powershell-deployment-of-web-application-proxy-and-adfs-in-under-10-minutes/`_
+* `https://ethernuno.wordpress.com/2014/04/20/install-adds-on-windows-server-2012-r2-with-powershell/`_
 
 --------------
 

doc/source/install-guide/configure-federation-idp.rst

@@ -1,11 +1,13 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
-Configure Identity Service (keystone) as a federated identity provider
+Configure Identity service (keystone) as a federated identity provider
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+======================================================================
 
-The identity provider (IdP) configuration for Keystone must be provided in a
+The Identity Provider (IdP) configuration for keystone provides a
 dictionary attribute with the key ``keystone_idp``. The following is a
-complete example::
+complete example:
+
+.. code::
 
     keystone_idp:
       certfile: "/etc/keystone/ssl/idp_signing_cert.pem"
@@ -29,7 +31,7 @@ complete example::
       contact_telephone: 555-55-5555
       contact_type: technical
 
-The following list is a reference of all the allowed settings:
+The following list is a reference of allowed settings:
 
 * ``certfile`` defines the location and filename of the SSL certificate that
   the IdP uses to sign assertions. This file must be in a location that is
@@ -39,37 +41,37 @@ The following list is a reference of all the allowed settings:
   the IdP uses to sign assertions. This file must be in a location that is
   accessible to the keystone system user.
 
-* ``self_signed_cert_subject`` is the subject used in the SSL signing
+* ``self_signed_cert_subject`` is the subject in the SSL signing
-  certificate. It is important to note that the common name of the certificate
+  certificate. The common name of the certificate
-  must match the hostname that is configured in the service provider(s) for
+  must match the hostname configuration in the service provider(s) for
   this IdP.
 
-* ``regen_cert`` should normally be set to ``False``. When set to ``True``,
+* ``regen_cert`` by default is set to ``False``. When set to ``True``, the
-  the existing signing certificate will be replaced with a new one. This
+  next Ansible run replaces the existing signing certificate with a new one. This
   setting is added as a convenience mechanism to renew a certificate when it
   is close to its expiration date.
 
-* ``idp_entity_id`` is the entity ID. The service providers will
+* ``idp_entity_id`` is the entity ID. The service providers
-  use this as a unique identifier for each IdP. The recommended value for this
+  use this as a unique identifier for each IdP. ``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp``
-  setting is ``<keystone-public-endpoint>/OS-FEDERATION/saml2/idp``
+  is the value we recommend for this setting.
 
-* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP. The
+* ``idp_sso_endpoint`` is the single sign-on endpoint for this IdP.
-  recommended value for this setting is
+  ``<keystone-public-endpoint>/OS-FEDERATION/saml2/sso>`` is the value
-  ``<keystone-public-endpoint>/OS-FEDERATION/saml2/sso>``
+  we recommend for this setting.
 
 * ``idp_metadata_path`` is the location and filename where the metadata for
-  this IdP will be cached. The keystone system user must have access to this
+  this IdP is cached. The keystone system user must have access to this
   location.
 
-* ``service_providers`` is a list of the known service providers that will be
+* ``service_providers`` is a list of the known service providers (SP) that
-  using this keystone instance as identity provider. For each SP there are
+  use the keystone instance as identity provider. For each SP, provide
-  three values that need to be provided: ``id`` is a unique identifier,
+  three values: ``id`` as a unique identifier,
-  ``auth_url`` is the authentication endpoint of the SP, and ``sp_url`` is the
+  ``auth_url`` as the authentication endpoint of the SP, and ``sp_url``
-  endpoint where SAML2 assertions need to be posted.
+  endpoint for posting SAML2 assertions.
 
 * ``organization_name``, ``organization_display_name``, ``organization_url``,
   ``contact_company``, ``contact_name``, ``contact_surname``,
-  ``contact_email``, ``contact_telephone`` and ``contact_type`` are all
+  ``contact_email``, ``contact_telephone`` and ``contact_type`` are
   settings that describe the identity provider. These settings are all optional.
 
 --------------

doc/source/install-guide/configure-federation-mapping.rst

@@ -1,7 +1,7 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
 Configure Identity Service (keystone) Domain-Project-Group-Role mappings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================================
 
 The following is an example service provider (SP) mapping configuration
 for an ADFS identity provider (IdP):
@@ -16,23 +16,21 @@ for an ADFS identity provider (IdP):
 
 Each IdP trusted by an SP must have the following configuration:
 
-#. ``project``: The project which federated users will have access to.
+#. ``project``: The project that federation users have access to.
-   If the project does not already exist then it is created in the
+   If the project does not already exist, create it in the
-   domain with the name specified by ``domain``.
+   domain with the name, ``domain``.
 
-#. ``group``: The Identity (keystone) group to which the federated users
+#. ``group``: The keystone group that federation users
-   will belong. If the group does not already exist then it is created in
+   belong. If the group does not already exist, create it in
-   the domain with the name specified by ``domain``.
+   the domain with the name, ``domain``.
 
-#. ``role``: The role which federated users will assume in that project.
+#. ``role``: The role that federation users use in that project.
-   If the role does not already exist, it is created.
+   Create the role if it does not already exist.
 
-#. ``domain``: The domain in which the ``project`` lives, and in
+#. ``domain``: The domain where the ``project`` lives, and where
-   which the role is assigned. If the domain does not already exist,
+   the you assign roles. Create the domain if it does not already exist.
-   it will be created.
 
-With the above information, Ansible implements the equivalent of the
+Ansible implements the equivalent of the following OpenStack CLI commands:
-following OpenStack CLI commands:
 
 .. code-block:: shell-session
 
@@ -51,8 +49,8 @@ following OpenStack CLI commands:
   # map the role to the project and user group in the domain
   openstack role add --project fedproject --group fedgroup _member_
 
-If the deployer wants to add more mappings, additional options can be added to
+To add more mappings, add options to the list.
-the list, for example:
+For example:
 
 .. code-block:: yaml
 
@@ -66,20 +64,19 @@ the list, for example:
           group: fedgroup2
           role: _member_
 
-Identity Service federation attribute mapping
+Identity service federation attribute mapping
----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Attribute mapping adds a set of rules to map federation attributes to keystone
-users and/or groups. An IdP has exactly one mapping specified per
+users and groups. IdP specifies one mapping per protocol.
-protocol.
 
-Mapping objects can be used multiple times by different combinations of
+Use mapping objects multiple times by different combinations of
 IdP and protocol.
 
-The details of how the mapping engine works, the schema and various rule
+The details of how the mapping engine works, the schema, and various rule
 examples are in the `keystone developer documentation <http://docs.openstack.org/developer/keystone/mapping_combinations.html>`_.
 
-Consider an example SP attribute mapping configuration for an ADFS IdP:
+For example, SP attribute mapping configuration for an ADFS IdP:
 
 .. code-block:: yaml
 
@@ -102,13 +99,12 @@ Consider an example SP attribute mapping configuration for an ADFS IdP:
 Each IdP for an SP needs to be set up with a mapping. This tells the SP how
 to interpret the attributes provided to the SP from the IdP.
 
-In this particular case the IdP is publishing the ``upn`` attribute. As this
+In this example, the IdP publishes the ``upn`` attribute. As this
-is not in the standard Shibboleth attribute attribute map (see
+is not in the standard Shibboleth attribute map (see
-``/etc/shibboleth/attribute-map.xml`` in the keystone containers), this IdP
+``/etc/shibboleth/attribute-map.xml`` in the keystone containers), the configuration
-has been configured with the extra mapping through the ``attributes``
+of the IdP has extra mapping through the ``attributes`` dictionary.
-dictionary.
 
-The ``mapping`` dictionary is a yaml representation very similar to the
+The ``mapping`` dictionary is a YAML representation similar to the
 keystone mapping property which Ansible uploads. The above mapping
 produces the following in keystone.
 
@@ -155,11 +151,11 @@ produces the following in keystone.
       }
   ]
 
-The interpretation of the above mapping rule is that any federated user
+The interpretation of the above mapping rule is that any federation user
-authenticated by the IdP is mapped to an ``ephemeral`` (non-existant) user in
+authenticated by the IdP maps to an ``ephemeral`` (non-existant) user in
-keystone. The user is a member of a group named ``fedgroup``, which in turn is
+keystone. The user is a member of a group named ``fedgroup``. This is
-in a domain called ``Default``. The user's ID and Name (federation always uses
+in a domain called ``Default``. The user's ID and Name (federation uses
-the same value for both properties) for all OpenStack services will be
+the same value for both properties) for all OpenStack services is
 the value of ``upn``.
 
 

doc/source/install-guide/configure-federation-sp-overview.rst

@@ -1,49 +1,52 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
 Identity Service (keystone) service provider background
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=======================================================
 
-In OpenStack-Ansible (OSA) the Identity Service (keystone) is set up to
+In OpenStack-Ansible, the Identity Service (keystone) is set up to
-use Apache with mod_wsgi. The additional configuration of
+use Apache with ``mod_wsgi``. The additional configuration of
-keystone as a federation service provider adds Apache mod_shib
+keystone as a federation service provider adds Apache ``mod_shib``
 and configures it to respond to specific locations requests
 from a client.
 
 .. note::
+
    There are alternative methods of implementing
    federation, but at this time only SAML2-based federation using
    the Shibboleth SP is instrumented in OA.
 
 When requests are sent to those locations, Apache hands off the
-request to the ``shibd`` service. Only requests pertaining to
+request to the ``shibd`` service.
-authentication are handed off.
 
-The ``shibd`` service configuration is primarily handled through
+.. note::
-the following files in ``/etc/shibboleth/`` within the keystone
+   
+   Handing off happens only with requests pertaining to authentication.
+
+Handle the ``shibd`` service configuration through
+the following files in ``/etc/shibboleth/`` in the keystone
 containers:
 
-* ``sp-cert.pem``, ``sp-key.pem``: These files are generated on the
+* ``sp-cert.pem``, ``sp-key.pem``: The ``os-keystone-install.yml`` playbook
-  first keystone container and replicated to the other keystone
+   uses these files generated on the first keystone container to replicate
-  containers by the ``os-keystone-install.yml`` playbook. They are
+   them to the other keystone containers. The SP and the IdP use these files
-  used as signing credentials in communications between the SP
+   as signing credentials in communications.
-  and the IdP.
+* ``shibboleth2.xml``: The ``os-keystone-install.yml`` playbook writes the
-* ``shibboleth2.xml``: This file's contents are written by the
+  file's contents, basing on the structure of the configuration
-  ``os-keystone-install.yml`` playbook based on the configuration
+  of the ``keystone_sp`` attribute in the
-  of the ``keystone_sp`` structured attribute in the
   ``/etc/openstack_deploy/user_variables.yml`` file. It contains
-  the list of trusted IdP's, the entityID by which the SP will
+  the list of trusted IdP's, the entityID by which the SP is known,
-  be known and some other facilitating configuration.
+  and other facilitating configurations.
-* ``attribute-map.xml``: This file's contents are written by the
+* ``attribute-map.xml``: The ``os-keystone-install.yml`` playbook writes
-  ``os-keystone-install.yml`` playbook based on the configuration
+  the file's contents, basing on the structure of the configuration
-  of the ``keystone_sp`` structured attribute in the
+  of the ``keystone_sp`` attribute in the
   ``/etc/openstack_deploy/user_variables.yml`` file. It contains
-  some default attribute mappings which will work for any basic
+  the default attribute mappings that work for any basic
   Shibboleth-type IDP setup, but also contains any additional
-  attribute mappings which were set out in the ``keystone_sp``
+  attribute mappings set out in the structure of the ``keystone_sp``
-  structured attribute.
+  attribute.
-* ``shibd.logger``: This file is left alone by Ansible, but is useful
+* ``shibd.logger``: This file is left alone by Ansible. It is useful
-  when troubleshooting issues with federated authentication or
+  when troubleshooting issues with federated authentication, or
-  when trying to discover what attributes published by an IdP
+  when discovering what attributes published by an IdP
   are not currently being understood by your SP's attribute map.
   To enable debug logging, change ``log4j.rootCategory=INFO`` to
   ``log4j.rootCategory=DEBUG`` at the top of the file. The
@@ -51,9 +54,9 @@ containers:
 
 References
 ----------
-* http://docs.openstack.org/developer/keystone/configure_federation.html
+* `http://docs.openstack.org/developer/keystone/configure_federation.html`_
-* http://docs.openstack.org/developer/keystone/extensions/shibboleth.html
+* `http://docs.openstack.org/developer/keystone/extensions/shibboleth.html`_
-* https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration
+* `https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration`_
 
 --------------
 

doc/source/install-guide/configure-federation-sp.rst

@@ -1,40 +1,35 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
 Configure Identity Service (keystone) as a federated service provider
----------------------------------------------------------------------
+=====================================================================
 
 The following settings must be set to configure a service provider (SP):
 
-#. ``keystone_public_endpoint`` automatically set by default
+#. ``keystone_public_endpoint`` is automatically set by default
-   to the public endpoint's URI. This ensures that
+   to the public endpoint's URI. This performs redirections and
-   the redirections performed and token references all refer to the
+   ensures token references refer to the public endpoint.
-   public endpoint which is accessible to clients and the trusted
-   IDP.
 
-#. ``horizon_keystone_endpoint`` automatically set by default
+#. ``horizon_keystone_endpoint`` is automatically set by default
    to the public v3 API endpoint URL for keystone. Web-based single
    sign-on for horizon requires the use of the keystone v3 API.
-   The value for this must use the same DNS name or IP address which
+   The value for this must use the same DNS name or IP address
-   is registered in the SSL certificate used for the endpoint.
+   registered in the SSL certificate used for the endpoint.
 
-#. If ADFS is to be used as the IdP, the keystone endpoint is
+#. It is a requirement to have a HTTPS public endpoint for the
-   **required** to have an HTTPS public endpoint. The endpoint may
+   keystone endpoint if the IdP is ADFS.
-   either be provided by keystone itself, or by an SSL offloading
+   Keystone or an SSL offloading load balancer provides the endpoint.
-   load balancer.
 
-#. ``keystone_service_publicuri_proto`` must be set to https in order
+#. Set ``keystone_service_publicuri_proto`` to https. 
-   to ensure that the public endpoint is registered with https in the
+   This ensures keystone publishes https in its references
-   URL, to ensure that keystone publishes https in its references
+   and ensures that Shibboleth is configured to know that it
-   and to ensure that Shibboleth is configured to know that it should
+   expects SSL URL's in the assertions (otherwise it will invalidate
-   expect SSL URL's in the assertions (otherwise it will invalidate
    the assertions).
 
-#. ADFS **requires** that a trusted SP have a trusted certificate that
+#. ADFS requires that a trusted SP have a trusted certificate that
-   is not self-signed. This means that the certificate used for
+   is not self-signed.
-   keystone must either be signed by a public CA, or an enterprise CA.
 
-#. When using SSL for the keystone endpoint, the endpoint URI and the
+#. Ensure the endpoint URI and the certificate match when using SSL for the
-   certificate must match. For example, if the certificate does not have
+   keystone endpoint. For example, if the certificate does not have
    the IP address of the endpoint, then the endpoint must be published with
    the appropriate name registered on the certificate. When
    using a DNS name for the keystone endpoint, both
@@ -42,7 +37,7 @@ The following settings must be set to configure a service provider (SP):
    be set to use the DNS name.
 
 #. ``horizon_endpoint_type`` must be set to ``publicURL`` to ensure that
-   Horizon makes use of the public endpoint for all its references and
+   horizon uses the public endpoint for all its references and
    queries.
 
 #. ``keystone_sp`` is a dictionary attribute which contains various
@@ -84,23 +79,23 @@ The following settings must be set to configure a service provider (SP):
 #. ``cert_duration_years`` designates the valid duration for the SP's
    signing certificate (for example, ``/etc/shibboleth/sp-key.pem``).
 
-#. ``trusted_dashboard_list`` designates the list of trusted URLs from which
+#. ``trusted_dashboard_list`` designates the list of trusted URLs that
-   keystone will accept redirects for Web Single-Sign. This
+   keystone accepts redirects for Web Single-Sign. This
-   list should contain all URLs that horizon is presented on,
+   list contains all URLs that horizon is presented on,
-   suffixed by ``/auth/websso/`` which is the path for horizon's WebSSO
+   suffixed by ``/auth/websso/``. This is the path for horizon's WebSSO
    component.
 
 #. ``trusted_idp_list`` is a dictionary attribute containing the list
    of settings which pertain to each trusted IdP for the SP.
 
-#. ``trusted_idp_list.name`` is the name by which the IDP is known, is
+#. ``trusted_idp_list.name`` is IDP's name. Configure this in
-   configured in keystone and is listed in horizon's login selection.
+    in keystone and list in horizon's login selection.
 
-#. ``entity_ids`` is a list of reference entity IDs which specify where
+#. ``entity_ids`` is a list of reference entity IDs. This specify's the
-   the login request to the SP will be redirected to in order to
+    redirection of the login request to the SP when authenticating to
-   authenticate to the IdP.
+    IdP.
 
-#. ``metadata_uri`` is the location of the IdP's metadata which provides
+#. ``metadata_uri`` is the location of the IdP's metadata. This provides
    the SP with the signing key and all the IdP's supported endpoints.
 
 #. ``metadata_file`` is the file name of the local cached version of
@@ -109,12 +104,13 @@ The following settings must be set to configure a service provider (SP):
 #. ``metadata_reload`` is the number of seconds between metadata
    refresh polls.
 
-#. ``federated_identities`` is a list of domain, project, group and users
+#. ``federated_identities`` is a mapping list of domain, project, group, and users.
-   which are to be mapped. See `Configure Identity Service (keystone) Domain-Project-Group-Role mappings <configure-federation-mapping.html>`_ for more information.
+   See `Configure Identity Service (keystone) Domain-Project-Group-Role mappings <configure-federation-mapping.html>`_
+   for more information.
 
 #. ``protocols`` is a list of protocols supported for the IdP and the set
-   of mappings and attributes for each protocol. Only the protocol with the
+   of mappings and attributes for each protocol. This only supports protocols
-   name ``saml2`` is supported at this time.
+   with the name ``saml2``.
 
 #. ``mapping`` is the local to remote mapping configuration for federated
    users. For more information, see `Configure Identity Service (keystone) Domain-Project-Group-Role mappings. <configure-federation-mapping.html>`_

doc/source/install-guide/configure-federation-use-case.rst

@@ -1,9 +1,9 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
 Identity Service to Identity Service federation example use-case
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================================================
 
-This document describes the configuration steps necessary to reproduce the
+The following is the configuration steps necessary to reproduce the
 federation scenario described below:
 
 * Federate Cloud 1 and Cloud 2.
@@ -14,9 +14,11 @@ federation scenario described below:
 * Assign User U to Group B, confirm scope to Role S in Project Y.
 
 Keystone identity provider (IdP) configuration
-----------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The configuration for the keystone IdP instance is as follows::
+The following is the configuration for the keystone IdP instance:
+
+.. code::
 
     keystone_idp:
       certfile: "/etc/keystone/ssl/idp_signing_cert.pem"
@@ -31,21 +33,25 @@ The configuration for the keystone IdP instance is as follows::
           auth_url: https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth
           sp_url: https://cloud2.com:5000/Shibboleth.sso/SAML2/ECP
 
-In the above example, only the last three lines are specific to a particular
+In this example, the last three lines are specific to a particular
 installation, as they reference the service provider cloud (referred to as
-"Cloud 2" in the original scenario). In the example, it is assumed that this
+"Cloud 2" in the original scenario). In the example, the
 cloud is located at https://cloud2.com, and the unique ID for this cloud
 is "cloud2".
 
-Also note that in the ``auth_url`` there is a reference to the IdP cloud (or
+.. note::
-"Cloud 1"), as known by the service provider (SP). The ID used for the IdP
-cloud in this example is "cloud1".
 
-Keystone SP configuration
+   In the ``auth_url`` there is a reference to the IdP cloud (or
--------------------------
+   "Cloud 1"), as known by the service provider (SP). The ID used for the IdP
+   cloud in this example is "cloud1".
 
-The configuration for the Keystone SP is more complex, as it needs to define
+Keystone service provider (SP) configuration
-the remote-to-local user mappings. The complete configuration is as follows::
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The configuration for keystone SP needs to define the remote-to-local user mappings.
+The following is the complete configuration:
+
+.. code::
 
     keystone_sp:
       cert_duration_years: 5
@@ -102,61 +108,62 @@ the remote-to-local user mappings. The complete configuration is as follows::
                 - name: openstack_project_domain
                   id: openstack_project_domain
 
-The ``cert_duration_years`` is used for the self-signed certificate used by
+``cert_duration_years`` is for the self-signed certificate used by
-Shibboleth. The ``trusted_dashboard_list`` is only necessary if Horizon SSO
+Shibboleth. Only implement the ``trusted_dashboard_list`` if horizon SSO
-login is going to be implemented. When given, it works as a security measure,
+login is necessary. When given, it works as a security measure,
 as keystone will only redirect to these URLs.
 
-The ``trusted_idp_list`` is where the IdPs known to the SP are configured. In
+Configure the IdPs known to SP in ``trusted_idp_list``. In
-this example there is only one IdP, the "Cloud 1", which is configured with
+this example there is only one IdP, the "Cloud 1". Configure "Cloud 1" with
-the ID "cloud1", matching the reference in the IdP configuration shown in the
+the ID "cloud1". This matches the reference in the IdP configuration shown in the
 previous section.
 
-The ``entity_ids`` is given the unique URL that represents the "Cloud 1" IdP,
+The ``entity_ids`` is given the unique URL that represents the "Cloud 1" IdP.
-which for this example is assumed to be hosted at https://cloud1.com.
+For this example, it is hosted at: https://cloud1.com.
 
-The three metadata values that follow configure the access to the IdP
+The ``metadata_file`` needs to be different for each IdP. This is
-metadata. The ``metadata_file`` needs to be different for each IdP, as this is
+a filename in the keystone containers of the SP cloud that holds cached
-a filename in the keystone containers of the SP cloud that will hold cached
 metadata for each registered IdP.
 
-The ``federated_identities`` list defines the sets of identities that will be
+The ``federated_identities`` list defines the sets of identities in use
-used for federated users. In this example there are two sets, Project X/Role R
+for federated users. In this example there are two sets, Project X/Role R
-and Project Y/Role S. To keep things organized, a user group is created
+and Project Y/Role S. A user group is created for each set.
-for each set.
 
-The ``protocols`` section is where the federation protocols are specified. At
+The ``protocols`` section is where the federation protocols are specified.
-this time the only supported protocol is ``saml2``.
+The only supported protocol is ``saml2``.
 
-The ``mapping`` dictionary is where the actual assignments of remote to local
+The ``mapping`` dictionary is where the assignments of remote to local
 users is defined. A keystone mapping is given a ``name`` and a set of
 ``rules`` that keystone applies to determine how to map a given user. Each
 mapping rule has a ``remote`` and a ``local`` component.
 
 The ``remote`` part of the mapping rule specifies the criteria for the remote
-user, based on the attributes exposed by the IdP in the SAML2 assertion. The
+user based on the attributes exposed by the IdP in the SAML2 assertion. The
 use case for this scenario calls for mapping users in "Group A" and "Group B",
 but the group or groups a user belongs to are not exported in the SAML2
-assertion. To make the example work, the groups A and B in the use case have
+assertion. To make the example work, the groups A and B in the use case are
-been assumed to be projects, so there are projects A and B, which are exported
+projects. Export projects A and B in the assertion under the ``openstack_project`` attribute.
-in the assertion under the ``openstack_project`` attribute. The two rules
+The two rules above select the corresponding project using the ``any_one_of``
-defined above select the corresponding project using the ``any_one_of``
 selector.
 
-The ``local`` part of the mapping rule specifies how keystone should represent
+The ``local`` part of the mapping rule specifies how keystone represents
-the remote user in the local SP cloud. Since the two federated identities were
+the remote user in the local SP cloud. Configuring the two federated identities
-configured with their own user group, this part simply maps the user to the
+with their own user group maps the user to the
-corresponding group, which in turn will expose the correct domain, project and
+corresponding group. This exposes the correct domain, project, and
-role. Note that a user name is not specified, so keystone creates an
+role. 
-ephemeral user in the specified group.
 
-The final setting of the configuration defines the SAML2 ``attributes`` that
+.. note::
-are exported by the IdP. For a keystone IdP these are the five attributes
+   
-shown above. The attributes given in this section are configured into the
+   Keystone creates a ephemeral user in the specified group as
-Shibboleth service, making them available to use in the mappings.
+   you cannot specify user names.
+
+The IdP exports the final setting of the configuration defines the SAML2 ``attributes``.
+For a keystone IdP, these are the five attributes
+shown above. Configure the attributes above into the Shibboleth service. This
+ensures they are available to use in the mappings.
 
 Reviewing or modifying the configuration with the OpenStack client
-------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Use OpenStack command line client to review or make modifications to an
 existing federation configuration. The following commands can be used for
@@ -165,7 +172,9 @@ the previous configuration.
 Service providers on the identity provider
 ------------------------------------------
 
-To see the list of known SPs::
+To see the list of known SPs:
+
+.. code::
 
     $ openstack service provider list
     +--------+---------+-------------+-----------------------------------------------------------------------------------------+
@@ -174,7 +183,9 @@ To see the list of known SPs::
     | cloud2 | True    | None        | https://cloud2.com:5000/v3/OS-FEDERATION/identity_providers/cloud1/protocols/saml2/auth |
     +--------+---------+-------------+-----------------------------------------------------------------------------------------+
 
-To view the information for a specific SP::
+To view the information for a specific SP:
+
+.. code::
 
     $ openstack service provider show cloud2
     +--------------------+----------------------------------------------------------------------------------------------+
@@ -188,8 +199,10 @@ To view the information for a specific SP::
     | sp_url             | http://cloud2.com:5000/Shibboleth.sso/SAML2/ECP                                              |
     +--------------------+----------------------------------------------------------------------------------------------+
 
-To make modifications, the ``set`` command is used. Below are the available
+To make modifications, use the ``set`` command. The following are the available
-options for this command::
+options for this command:
+
+.. code::
 
     $ openstack service provider set
     usage: openstack service provider set [-h] [--auth-url <auth-url>]
@@ -201,7 +214,9 @@ options for this command::
 Identity providers on the service provider
 ------------------------------------------
 
-To see the list of known IdPs::
+To see the list of known IdPs:
+
+.. code::
 
     $ openstack identity provider list
     +----------------+---------+-------------+
@@ -210,7 +225,9 @@ To see the list of known IdPs::
     | cloud1         | True    | None        |
     +----------------+---------+-------------+
 
-To view the information for a specific IdP::
+To view the information for a specific IdP:
+
+.. code::
 
     $ openstack identity provider show keystone-idp
     +-------------+--------------------------------------------------------+
@@ -222,8 +239,10 @@ To view the information for a specific IdP::
     | remote_ids  | [u'http://cloud1.com:5000/v3/OS-FEDERATION/saml2/idp'] |
     +-------------+--------------------------------------------------------+
 
-To make modifications, the ``set`` command is used. Below are the available
+To make modifications, use the ``set`` command. The following are the available
-options for this command::
+options for this command:
+
+.. code::
 
     $ openstack identity provider set
     usage: openstack identity provider set [-h]
@@ -234,9 +253,11 @@ options for this command::
 Federated identities on the service provider
 --------------------------------------------
 
-The domain, project, role, group and user entities created for the purpose of
+You can use the OpenStack commandline client to view or modify
-federation are regular keystone entities that can be viewed or modified with
+the created domain, project, role, group, and user entities for the
-the OpenStack command client. For example::
+purpose of federation as these are regular keystone entities. For example:
+
+.. code::
 
     $ openstack domain list
     $ openstack project list
@@ -244,14 +265,15 @@ the OpenStack command client. For example::
     $ openstack group list
     $ openstack user list
 
-When using a domain other than the default, the ``--domain`` option must be
+Add the ``--domain`` option when using a domain other than the default.
-added to all the commands above except the first. The ``set`` option is used
+Use the ``set`` option to modify these entities.
-to modify these entities.
 
 Federation mappings
 -------------------
 
-To view the list of mappings::
+To view the list of mappings:
+
+.. code::
 
     $ openstack mapping list
     +------------------+
@@ -260,7 +282,9 @@ To view the list of mappings::
     | cloud1-mapping   |
     +------------------+
 
-To view a mapping in detail::
+To view a mapping in detail:
+
+..code::
 
     $ openstack mapping show cloud1-mapping
     +-------+--------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -273,8 +297,10 @@ To view a mapping in detail::
     +-------+--------------------------------------------------------------------------------------------------------------------------------------------------+
 
 To edit a mapping, use an auxiliary file. Save the JSON mapping shown above
-and make the necessary modifications, then use the``set`` command to trigger
+and make the necessary modifications. Use the``set`` command to trigger
-an update. For example::
+an update. For example:
+
+.. code::
 
     $ openstack mapping show cloud1-mapping -c rules -f value | python -m json.tool > rules.json
     $ vi rules.json  # <--- make any necessary changes
@@ -283,8 +309,10 @@ an update. For example::
 Federation protocols
 --------------------
 
-It is also possible to view or change the association between a federation
+To view or change the association between a federation
-protocol and a mapping::
+protocol and a mapping, use the following command:
+
+.. code::
 
     $ openstack federation protocol list --identity-provider keystone-idp
     +-------+----------------+

doc/source/install-guide/configure-federation-wrapper.rst

@@ -1,77 +1,92 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
-Using Identity Service to Identity Service federation
+Using Identity service to Identity service federation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=====================================================
 
-In Identity Service (keystone) to Identity Service (keystone)
+In Identity service (keystone) to Identity service (keystone)
 federation (K2K) the identity provider (IdP) and service provider (SP)
 keystone instances exchange information securely to enable a user on
 the IdP cloud to access resources of the SP cloud.
 
-This section applies only to federation between Identity Service IdP
+.. important::
-and Identity Service SP. It does not apply to non-keystone IdP.
+
+   This section applies only to federation between keystone IdP
+   and keystone SP. It does not apply to non-keystone IdP.
 
 .. note::
+
    For the Kilo release of OpenStack, K2K is only partially supported.
    It is possible to perform a federated login using command line clients and
-   scripting, but Horizon does not support this functionality.
+   scripting. However, horizon does not support this functionality.
 
 The K2K authentication flow involves the following steps:
 
-#. The client logs in to the IdP with his credentials.
+#. You log in to the IdP with your credentials.
-#. The client sends a request to the IdP to generate an assertion for a given
+#. You sends a request to the IdP to generate an assertion for a given
    SP. An assertion is a cryptographically signed XML document that identifies
    the user to the SP.
-#. The client submits the assertion to the SP on the configured ``sp_url``
+#. You submit the assertion to the SP on the configured ``sp_url``
    endpoint. The Shibboleth service running on the SP receives the assertion
-   and verifies it. If it is valid, it starts a session with the client and
+   and verifies it. If it is valid, a session with the client starts and
    returns the session ID in a cookie.
-#. The client now connects to the SP on the configured ``auth_url`` endpoint,
+#. You now connect to the SP on the configured ``auth_url`` endpoint,
    providing the Shibboleth cookie with the session ID. The SP responds with
-   an unscoped token that the client can use to access the SP.
+   an unscoped token that you use to access the SP.
-#. The client connects to the keystone service on the SP with the unscoped
+#. You connect to the keystone service on the SP with the unscoped
-   token, and the desired domain and/or project, and receives a scoped token
+   token, and the desired domain and project, and receive a scoped token
    and the service catalog.
-#. The client, now in possession of a token, can make API requests to the
+#. You, now in possession of a token, can make API requests to the
    endpoints in the catalog.
 
-Identity Service to Identity Service federation authentication wrapper
+Identity service to Identity service federation authentication wrapper
-----------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Unfortunately, many of the steps above involve manually sending API requests.
+The following steps above involve manually sending API requests.
-The infrastructure for the command line utilities to perform all these steps
-for the user does not yet exist.
 
-To simplify the task of obtaining access to a SP cloud, OpenStack-Ansible provides a script that wraps the above steps. The script is called ``federated-login.sh`` and is
+.. note::
-used as follows::
 
-    # ./scripts/federated-login.sh -p project [-d domain] sp_id
+   The infrastructure for the command line utilities that performs these steps
+   for the user does not exist.
 
-Where ``project`` is the project in the SP cloud that the user wants to access,
+To obtain access to a SP cloud, OpenStack-Ansible provides a script that wraps the
-``domain`` is the domain in which the project lives (the default domain is
+above steps. The script is called ``federated-login.sh`` and is
-used if this argument is not given) and ``sp_id`` is the unique ID of the SP,
+used as follows:
-as given in the IdP configuration.
+
+.. code::
+
+   # ./scripts/federated-login.sh -p project [-d domain] sp_id
+
+* ``project`` is the project in the SP cloud that you want to access.
+* ``domain`` is the domain in which the project lives (the default domain is
+  used if this argument is not given).
+* ``sp_id`` is the unique ID of the SP. This is given in the IdP configuration.
 
 The script outputs the results of all the steps in the authentication flow to
-the console, and at the end prints the available endpoints from the catalog
+the console. At the end, it prints the available endpoints from the catalog
 and the scoped token provided by the SP.
 
-The endpoints and token can be used with the openstack command line client as
+Use the endpoints and token with the openstack command line client as follows:
-follows::
 
-    # openstack --os-token=<token> --os-url=<service-endpoint> [options]
+.. code::
 
-or alternatively::
+   # openstack --os-token=<token> --os-url=<service-endpoint> [options]
 
-    # export OS_TOKEN=<token>
+Or, alternatively:
-    # export OS_URL=<service-endpoint>
-    # openstack [options]
 
-The user must select the appropriate endpoint for the desired
+.. code::
-operation. For example, if the user wants to work with servers, the ``OS_URL``
+
-argument must be set to the compute endpoint. At this time the openstack
+   # export OS_TOKEN=<token>
-client is unable to find endpoints in the service catalog when using a
+   # export OS_URL=<service-endpoint>
-federated login. This is likely to be supported in the near future.
+   # openstack [options]
+
+Ensure you select the appropriate endpoint for your operation.
+For example, if you want to work with servers, the ``OS_URL``
+argument must be set to the compute endpoint.
+
+.. note::
+
+   At this time, the OpenStack client is unable to find endpoints in
+   the service catalog when using a federated login.
 
 --------------
 

doc/source/install-guide/configure-federation.rst

@@ -1,7 +1,7 @@
 `Home <index.html>`__ OpenStack-Ansible Installation Guide
 
-Configuring Identity Service federation (optional)
+Configuring Identity service (keystone) federation (optional)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================================================
 
 .. toctree::
 
@@ -13,16 +13,17 @@ Configuring Identity Service federation (optional)
    configure-federation-mapping.rst
    configure-federation-use-case.rst
 
-In Identity Service federation, the identity provider (IdP) and service
+In keystone federation, the identity provider (IdP) and service
 provider (SP) exchange information securely to enable a user on the IdP cloud
 to access resources of the SP cloud.
 
 .. note::
+
    For the Kilo release of OpenStack, federation is only partially supported.
    It is possible to perform a federated login using command line clients and
    scripting, but Dashboard (horizon) does not support this functionality.
 
-The following procedure describes how set up federation.
+The following procedure describes how to set up federation.
 
 #. `Configure Identity Service (keystone) service providers. <configure-federation-sp.html>`_
 
@@ -38,8 +39,8 @@ The following procedure describes how set up federation.
 
 #. `Run the authentication wrapper to use Identity Service to Identity Service federation. <configure-federation-wrapper.html>`_
 
-   For examples of how to set up Identity Service to Identity
+   For examples of how to set up keystone to keystone federation,
-   Service federation, see the `Identity Service to Identity Service
+   see the `Identity Service to Identity Service
    federation example use-case. <configure-federation-use-case.html>`_
 
 --------------

doc/source/install-guide/configure-network-services-fwaas.rst

@@ -1,53 +0,0 @@
-`Home <index.html>`_ OpenStack-Ansible Installation Guide
-
-Firewall Service (Optional)
----------------------------
-
-The following procedure describes how to modify the
-``/etc/openstack_deploy/user_variables.yml`` file to enable FWaaS.
-
-#. Override the default list of Neutron plugins to include
-   ``firewall``:
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-        - firewall
-        - ...
-
-#. The complete `neutron_plugin_base`, at the time of this writing, is as follows:
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-         - router
-         - firewall
-         - lbaas
-         - vpnaas
-         - metering
-         - qos
-
-#. Execute the Neutron install playbook in order to update the configuration:
-
-   .. code-block:: shell-session
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-neutron-install.yml
-
-#. Execute the Horizon install playbook in order to update the Horizon
-   configuration to show the FWaaS panels:
-
-   .. code-block:: shell-session
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-horizon-install.yml
-
-The FWaaS default configuration options may be changed through the
-`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
-dict.
-
-.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
-
---------------
-
-.. include:: navigation.txt

doc/source/install-guide/configure-network-services-lbaas.rst

@@ -1,94 +0,0 @@
-`Home <index.html>`_ OpenStack-Ansible Installation Guide
-
-Load Balancing Service (Optional)
----------------------------------
-
-OpenStack-Ansible currently provides the OpenStack Neutron LBaaS service using
-HAProxy as the load balancer. LBaaS has two implementations available: v1 and
-v2.
-
-Both implementations use agents that manage `HAProxy`_ daemons. However, LBaaS
-v1 has a limitation of one port per load balancer.  LBaaS v2 allows for multiple
-ports (called *listeners*) per load balancer.
-
-.. note::
-
-   Horizon panels for LBaaS v2 are not yet available.
-
-.. _HAProxy: http://www.haproxy.org/
-
-Deploying LBaaS v1
-~~~~~~~~~~~~~~~~~~
-
-.. note::
-
-    LBaaS v1 was deprecated during the Liberty release and is not recommended
-    for new deployments.
-
-#. Start by adding the LBaaS v1 plugin to the ``neutron_plugin_base`` variable
-   within ``/etc/openstack_deploy/user_variables.yml``.
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-        - router
-        - metering
-        - lbaas
-
-   Ensure that ``neutron_plugin_base`` includes all of the plugins that you
-   want to deploy with Neutron **in addition** to the LBaaS plugin.
-
-#. Run the Neutron and Horizon playbooks to deploy the LBaaS v1 agent and enable
-   the LBaaS panels in Horizon.
-
-   .. code-block:: console
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-neutron-install.yml
-       # openstack-ansible os-horizon-install.yml
-
-Deploying LBaaS v2
-~~~~~~~~~~~~~~~~~~
-
-#. Start by adding the LBaaS v2 plugin to the ``neutron_plugin_base`` variable
-   within ``/etc/openstack_deploy/user_variables.yml``.
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-        - router
-        - metering
-        - neutron_lbaas.services.loadbalancer.plugin.LoadBalancerPluginv2
-
-   Ensure that ``neutron_plugin_base`` includes all of the plugins that you
-   want to deploy with Neutron **in addition** to the LBaaS plugin.
-
-#. Run the Neutron playbook to deploy the LBaaS v2 agent:
-
-   .. code-block:: console
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-neutron-install.yml
-
-Special notes about LBaaS
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The LBaaS default configuration options may be changed through the
-`conf override`_ mechanism using the ``neutron_lbaas_agent_ini_overrides``
-dict.
-
-LBaaS v1 and v2 agents cannot run at the same time. If a deployer switches from
-LBaaS v1 to v2, the v2 agent will be the only agent running. The LBaaS v1 agent
-will be stopped along with any load balancers provisioned under the v1 agent.
-The same is true if a deployer chooses to move from LBaaS v2 to v1.
-
-Load balancers are not migrated between LBaaS v1 and v2 automatically. Each
-implementation has different code paths and database tables. Deployers will need
-to manually delete load balancers, pools, and members before switching LBaaS
-versions. Those objects will need to be re-created afterwards.
-
-.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
-
---------------
-
-.. include:: navigation.txt

doc/source/install-guide/configure-network-services-vpnaas.rst

@@ -1,50 +0,0 @@
-`Home <index.html>`_ OpenStack-Ansible Installation Guide
-
-Virtual Private Network Service (Optional)
-------------------------------------------
-
-The following procedure describes how to modify the
-``/etc/openstack_deploy/user_variables.yml`` file to enable VPNaaS.
-
-#. Override the default list of Neutron plugins to include
-   ``vpnaas``:
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-        - router
-        - metering
-
-#. The complete `neutron_plugin_base`, at the time of this writing, is as follows:
-
-   .. code-block:: yaml
-
-      neutron_plugin_base:
-         - router
-         - metering
-         - vpnaas
-
-#. Execute the Neutron install playbook in order to update the configuration:
-
-   .. code-block:: shell-session
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-neutron-install.yml
-
-#. Execute the Horizon install playbook in order to update the Horizon
-   configuration to show the VPNaaS panels:
-
-   .. code-block:: shell-session
-
-       # cd /opt/openstack-ansible/playbooks
-       # openstack-ansible os-horizon-install.yml
-
-The VPNaaS default configuration options may be changed through the
-`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
-dict.
-
-.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
-
---------------
-
-.. include:: navigation.txt

doc/source/install-guide/configure-network-services.rst

@@ -1,17 +1,191 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
-Configuring the Network Services (Optional)
+Configuring the Networking service (neutron) (optional)
--------------------------------------------
+=======================================================
 
-.. toctree::
+The OpenStack Networking service (neutron) includes the following services:
-   configure-network-services-fwaas.rst
-   configure-network-services-lbaas.rst
-   configure-network-services-vpnaas.rst
 
-The OpenStack Networking Service, Neutron, includes the following services:
+ * Firewall as a Service (FWaaS) allows for the configuration of a firewall
- - Firewall as a Service (FWaaS) allows for the configuration of a firewall that filters traffic from the router.
+   that filters traffic from the router.
- - Load Balancer as a Service (LBaaS) allows for the configuration of a load balancer that directs traffic to the specified instances.
+ * Load Balancer as a Service (LBaaS) allows for the configuration of a
- - VPN as a Service (VPNaaS) allows for the configuration of a virtual private network allowing the extension of the private network across a public network.
+   load balancer that directs traffic to the specified instances.
+ * VPN as a Service (VPNaaS) allows for the configuration of a virtual
+   private network allowing the extension of the private network across a public network.
+
+Firewall service (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following procedure describes how to modify the
+``/etc/openstack_deploy/user_variables.yml`` file to enable FWaaS.
+
+#. Override the default list of neutron plugins to include
+   ``firewall``:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+        - firewall
+        - ...
+
+#. ``neutron_plugin_base`` is as follows:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+         - router
+         - firewall
+         - lbaas
+         - vpnaas
+         - metering
+         - qos
+
+#. Execute the neutron install playbook in order to update the configuration:
+
+   .. code-block:: shell-session
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-neutron-install.yml
+
+#. Execute the horizon install playbook to show the FWaaS panels:
+
+   .. code-block:: shell-session
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-horizon-install.yml
+
+The FWaaS default configuration options may be changed through the
+`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
+dict.
+
+Load balancing service (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenStack-Ansible currently provides the OpenStack neutron LBaaS service using
+HAProxy as the load balancer. LBaaS has two implementations available: v1 and
+v2.
+
+Both implementations use agents that manage `HAProxy`_ daemons. However, LBaaS
+v1 has a limitation of one port per load balancer. LBaaS v2 allows for multiple
+ports (called listeners) per load balancer.
+
+.. note::
+
+   Horizon panels for LBaaS v2 are not yet available.
+
+.. _HAProxy: http://www.haproxy.org/
+
+Deploying LBaaS v1
+------------------
+
+.. note::
+
+   We do not recommend LBaaS v1 for new deployments as it is deprecated as of Liberty. 
+
+#. Add the LBaaS v1 plugin to the ``neutron_plugin_base`` variable
+   in ``/etc/openstack_deploy/user_variables.yml``:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+        - router
+        - metering
+        - lbaas
+
+   Ensure that ``neutron_plugin_base`` includes all of the plugins that you
+   want to deploy with neutron in addition to the LBaaS plugin.
+
+#. Run the neutron and horizon playbooks to deploy the LBaaS v1 agent and enable
+   the LBaaS panels in horizon:
+
+   .. code-block:: console
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-neutron-install.yml
+       # openstack-ansible os-horizon-install.yml
+
+Deploying LBaaS v2
+------------------
+
+#. Add the LBaaS v2 plugin to the ``neutron_plugin_base`` variable
+   in ``/etc/openstack_deploy/user_variables.yml``:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+        - router
+        - metering
+        - neutron_lbaas.services.loadbalancer.plugin.LoadBalancerPluginv2
+
+   Ensure that ``neutron_plugin_base`` includes all of the plugins that you
+   want to deploy with neutron in addition to the LBaaS plugin.
+
+#. Run the neutron playbook to deploy the LBaaS v2 agent:
+
+   .. code-block:: console
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-neutron-install.yml
+
+Special notes about LBaaS
+-------------------------
+
+The LBaaS default configuration options are changed through the
+`conf override`_ mechanism using the ``neutron_lbaas_agent_ini_overrides``
+dict.
+
+LBaaS v1 and v2 agents are unable to run at the same time. If you switch
+LBaaS v1 to v2, the v2 agent is the only agent running. The LBaaS v1 agent
+stops along with any load balancers provisioned under the v1 agent.
+The same is true if you choose to move from LBaaS v2 to v1.
+
+Load balancers are not migrated between LBaaS v1 and v2 automatically. Each
+implementation has different code paths and database tables. You need
+to manually delete load balancers, pools, and members before switching LBaaS
+versions. Recreate these objects afterwards.
+
+Virtual private network service (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following procedure describes how to modify the
+``/etc/openstack_deploy/user_variables.yml`` file to enable VPNaaS.
+
+#. Override the default list of neutron plugins to include
+   ``vpnaas``:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+        - router
+        - metering
+
+#. ````neutron_plugin_base`` is as follows:
+
+   .. code-block:: yaml
+
+      neutron_plugin_base:
+         - router
+         - metering
+         - vpnaas
+
+#. Execute the neutron install playbook in order to update the configuration:
+
+   .. code-block:: shell-session
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-neutron-install.yml
+
+#. Execute the horizon install playbook to show the VPNaaS panels:
+
+   .. code-block:: shell-session
+
+       # cd /opt/openstack-ansible/playbooks
+       # openstack-ansible os-horizon-install.yml
+
+The VPNaaS default configuration options are changed through the
+`conf override`_ mechanism using the ``neutron_neutron_conf_overrides``
+dict.
+
+.. _conf override: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-openstack.html
 
 --------------
 

doc/source/install-guide/configure-openstack.rst

@@ -1,19 +1,22 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
-Overriding OpenStack Configuration Defaults
+Overriding OpenStack configuration defaults
--------------------------------------------
+===========================================
 
 OpenStack has many configuration options available in configuration files
-which take the form of ``.conf`` files (in a standard ``INI`` file format),
+which are in the form of ``.conf`` files (in a standard ``INI`` file format),
-policy files (in a standard ``JSON`` format) and also in ``YAML`` files (only
+policy files (in a standard ``JSON`` format) and also ``YAML`` files.
-in the Ceilometer project at this time).
 
-OpenStack-Ansible provides the facility to include any options referenced in
+.. note::
+
+   ``YAML`` files are only in the ceilometer project at this time.
+
+OpenStack-Ansible provides the facility to include reference to any options in
 the `OpenStack Configuration Reference`_ through the use of a simple set of
 configuration entries in ``/etc/openstack_deploy/user_variables.yml``.
 
 This section provides guidance for how to make use of this facility. Further
-guidance is available in the Developer Documentation in the section titled
+guidance is available in the developer documentation in the section titled
 `Setting overrides in configuration files`_.
 
 .. _OpenStack Configuration Reference: http://docs.openstack.org/draft/config-reference/
@@ -23,11 +26,10 @@ Overriding .conf files
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The most common use-case for implementing overrides are for the
-``<service>.conf`` files (eg: ``nova.conf``). These files use a standard
+``<service>.conf`` files (for example, ``nova.conf``). These files use a standard
 ``INI`` file format.
 
-As an example, if a deployer wishes to add the following parameters
+For example, if you add the following parameters to ``nova.conf``:
-to ``nova.conf``:
 
 .. code-block:: ini
 
@@ -42,7 +44,7 @@ to ``nova.conf``:
     idle_timeout = 300
     max_pool_size = 10
 
-This would be accomplished through the use of the following configuration
+This is accomplished through the use of the following configuration
 entry in ``/etc/openstack_deploy/user_variables.yml``:
 
 .. code-block:: yaml
@@ -76,22 +78,21 @@ configuration in ``/etc/openstack_deploy/openstack_user_config.yml``:
                 idle_timeout: 300
                 max_pool_size: 10
 
-This method may be used for any INI file format for all OpenStack projects
+Use this method for any ``INI`` file format for all OpenStack projects
 deployed in OpenStack-Ansible.
 
-To assist deployers in finding the appropriate variable name to use for
+To assist you in finding the appropriate variable name to use for
 overrides, the general format for the variable name is:
 ``<service>_<filename>_<file extension>_overrides``.
 
 Overriding .json files
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Deployers may wish to adjust the default policies applied by services in order
+You can adjust the default policies applied by services in order
-to implement access controls which are different to the norm. Policy files
+to implement access controls which are different to a standard OpenStack
-are in a JSON format.
+environment. Policy files are in a ``JSON`` format.
 
-As an example, the deployer wishes to add the following policy in
+For example, you can add the following policy in keystone's ``policy.json``:
-Keystone's ``policy.json``:
 
 .. code-block:: json
 
@@ -100,7 +101,7 @@ Keystone's ``policy.json``:
         "identity:bar": "rule:admin_required"
     }
 
-This would be accomplished through the use of the following configuration
+Accomplish this through the use of the following configuration
 entry in ``/etc/openstack_deploy/user_variables.yml``:
 
 .. code-block:: yaml
@@ -109,17 +110,17 @@ entry in ``/etc/openstack_deploy/user_variables.yml``:
       identity:foo: "rule:admin_required"
       identity:bar: "rule:admin_required"
 
-This method may be used for any JSON file format for all OpenStack projects
+Use this method for any ``JSON`` file format for all OpenStack projects
 deployed in OpenStack-Ansible.
 
-To assist deployers in finding the appropriate variable name to use for
+To assist you in finding the appropriate variable name to use for
 overrides, the general format for the variable name is
 ``<service>_policy_overrides``.
 
-Currently Available Overrides
+Currently available overrides
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For convenience, this is a (possibly incomplete) list of overrides available:
+The following is a list of overrides available:
 
 Galera:
     * galera_client_my_cnf_overrides

doc/source/install-guide/configure-sslcertificates.rst

@@ -1,10 +1,10 @@
 `Home <index.html>`_ OpenStack-Ansible Installation Guide
 
 Securing services with SSL certificates
----------------------------------------
+=======================================
 
-Providing secure communication between various services in an OpenStack
+The `OpenStack Security Guide`_ recommends providing secure communication
-deployment is highly recommended in the `OpenStack Security Guide`_.
+between various services in an OpenStack deployment.
 
 .. _OpenStack Security Guide: http://docs.openstack.org/security-guide/secure-communication.html
 
@@ -16,25 +16,27 @@ certificates for secure communication with the following services:
 * Keystone
 * RabbitMQ
 
-For each service, deployers have the option to use self-signed certificates
+For each service, you have the option to use self-signed certificates
-generated during the deployment process or they can provide SSL certificates,
+generated during the deployment process or provide SSL certificates,
-keys and CA certificates from their own trusted certificate authority.  Highly
+keys, and CA certificates from your own trusted certificate authority. Highly
-secured environments should use trusted, user-provided, certificates for as
+secured environments use trusted, user-provided, certificates for as
 many services as possible.
 
-All SSL certificate configuration should be done within
+.. note::
-``/etc/openstack_deploy/user_variables.yml`` and not within the playbook
+
-roles themselves.
+   Conduct all SSL certificate configuration in
+   ``/etc/openstack_deploy/user_variables.yml`` and not in the playbook
+   roles themselves.
 
 Self-signed certificates
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Self-signed certificates make it easy to get started quickly and they ensure
+Self-signed certificates ensure you are able to start quickly and you are able to
-data is encrypted in transit, but they don't provide a high level of trust
+encrypt data in transit. However, they do not provide a high level of trust
-for highly secure environments.  The use of self-signed certificates is
+for highly secure environments. The use of self-signed certificates is
 currently the default in OpenStack-Ansible. When self-signed certificates are
 being used, certificate verification must be disabled using the following
-user variables depending on your configuration. These variables can be added
+user variables depending on your configuration. Add these variables
 in ``/etc/openstack_deploy/user_variables.yml``.
 
 .. code-block:: yaml
@@ -43,12 +45,12 @@ in ``/etc/openstack_deploy/user_variables.yml``.
     keystone_service_internaluri_insecure: true
 
 Setting self-signed certificate subject data
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------------
 
-The subject data of any self-signed certificate can be changed using
+Change the subject data of any self-signed certificate using
-configuration variables.  The configuration variable for each service is
+configuration variables. The configuration variable for each service is
-``<servicename>_ssl_self_signed_subject``.  To change the SSL certificate
+``<servicename>_ssl_self_signed_subject``. To change the SSL certificate
-subject data for HAProxy, simply make this adjustment in ``/etc/openstack_deploy/user_variables.yml``:
+subject data for HAProxy, adjust ``/etc/openstack_deploy/user_variables.yml``:
 
 .. code-block:: yaml
 
@@ -60,23 +62,27 @@ refer to OpenSSL's documentation on the `req subcommand`_.
 .. _req subcommand: https://www.openssl.org/docs/manmaster/apps/req.html
 
 Generating and regenerating self-signed certificates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------------------------
 
-Self-signed certificates for each service are generated during the first run
+Generate self-signed certificates for each service during the first run
-of the playbook.  Subsequent runs of the playbook **will not** generate new SSL
+of the playbook.
-certificates unless the user sets ``<servicename>_ssl_self_signed_regen`` to
-``true``.
 
-To force a self-signed certificate to regenerate you can pass the variable to
+.. note::
+
+   Subsequent runs of the playbook do not generate new SSL
+   certificates unless you set ``<servicename>_ssl_self_signed_regen`` to
+   ``true``.
+
+To force a self-signed certificate to regenerate, you can pass the variable to
 ``openstack-ansible`` on the command line:
 
 .. code-block:: shell-session
 
     # openstack-ansible -e "horizon_ssl_self_signed_regen=true" os-horizon-install.yml
 
-To force a self-signed certificate to regenerate **with every playbook run**,
+To force a self-signed certificate to regenerate with every playbook run,
-simply set the appropriate regeneration option to ``true``.  For example, if
+set the appropriate regeneration option to ``true``.  For example, if
-you've already run the ``os-horizon`` playbook, but you want to regenerate the
+you have already run the ``os-horizon`` playbook, but you want to regenerate the
 self-signed certificate, set the ``horizon_ssl_self_signed_regen`` variable to
 ``true`` in ``/etc/openstack_deploy/user_variables.yml``:
 
@@ -84,31 +90,32 @@ self-signed certificate, set the ``horizon_ssl_self_signed_regen`` variable to
 
     horizon_ssl_self_signed_regen: true
 
-Note that regenerating self-signed certificates will replace the existing
+.. note::
-certificates whether they are self-signed or user-provided.
+
+   Regenerating self-signed certificates replaces the existing
+   certificates whether they are self-signed or user-provided.
 
 
 User-provided certificates
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Deployers can provide their own SSL certificates, keys, and CA certificates
+You can provide your own SSL certificates, keys, and CA certificates
-for added trust in highly secure environments.  Acquiring certificates from a
+for added trust in highly secure environments. Acquiring certificates from a
-trusted certificate authority is outside the scope of this document, but `The
+trusted certificate authority is outside the scope of this document, but the
-Linux Documentation Project`_ has a section called `Certificate Management`_
+ `Certificate Management`_  section of the Linux Documentation Project explains
-that explains to create your own certificate authority and sign certificates.
+how to create your own certificate authority and sign certificates.
 
-.. _The Linux Documentation Project: http://www.tldp.org/
 .. _Certificate Management: http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/c118.html
 
 Deploying user-provided SSL certificates is a three step process:
 
-#. Copy your SSL certificate, key, and CA certificate to the *deployment host*
+#. Copy your SSL certificate, key, and CA certificate to the deployment host.
-#. Specify the path to your SSL certificate, key and CA certificate in
+#. Specify the path to your SSL certificate, key, and CA certificate in
-   ``/etc/openstack_deploy/user_variables.yml``
+   ``/etc/openstack_deploy/user_variables.yml``.
-#. Run the playbook for that service
+#. Run the playbook for that service.
 
-As an example, if you wanted to deploy user-provided certificates for RabbitMQ,
+For example, to deploy user-provided certificates for RabbitMQ,
-start by copying those certificates to the deployment host.  Then, edit
+copy the certificates to the deployment host, edit
 ``/etc/openstack_deploy/user_variables.yml`` and set the following three
 variables:
 
@@ -118,18 +125,18 @@ variables:
     rabbitmq_user_ssl_key:     /tmp/example.com.key
     rabbitmq_user_ssl_ca_cert: /tmp/ExampleCA.crt
 
-Simply run the playbook to apply the certificates:
+Run the playbook to apply the certificates:
 
 .. code-block:: shell-session
 
     # openstack-ansible rabbitmq-install.yml
 
-The playbook will deploy your user-provided SSL certificate, key, and CA
+The playbook deploys your user-provided SSL certificate, key, and CA
 certificate to each RabbitMQ container.
 
-The process is identical with other services as well.  Simply replace
+The process is identical to the other services. Replace
 ``rabbitmq`` in the configuration variables shown above with ``horizon``,
-``haproxy``, or ``keystone``, to deploy user-provided certificates to those
+``haproxy``, or ``keystone`` to deploy user-provided certificates to those
 services.
 
 --------------