Merge "[Docs] Make install/usage docs more clear"

doc/source/domains.rst

@@ -1,3 +1,5 @@
+.. _hardening-domains-label:
+
 Hardening Domains
 =================
 

doc/source/getting-started.rst

@@ -1,9 +1,11 @@
 Getting started
 ===============
 
-The ansible-hardening role can be used along with the
-`OpenStack-Ansible`_ project or as a standalone role that can be used along
-with other Ansible playbooks.
+The ansible-hardening role can be used along with the `OpenStack-Ansible`_
+project or as a standalone role that can be used along with other Ansible
+playbooks. This documentation assumes that the reader has completed the steps
+within the
+`Ansible installation guide <http://docs.ansible.com/ansible/intro_installation.html>`_.
 
 .. _OpenStack-Ansible: https://git.openstack.org/cgit/openstack/openstack-ansible/
 
@@ -11,58 +13,88 @@ with other Ansible playbooks.
    :local:
    :backlinks: none
 
-Prepare your system
--------------------
+Installing the ansible-hardening role
+-------------------------------------
 
-Start by installing ansible and then install the role itself using
-``ansible-galaxy``:
+The recommended installation methods for the ansible-hardening role are
+``ansible-galaxy`` (recommended) or ``git``.
+
+Using ``ansible-galaxy``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest installation method is to use the ``ansible-galaxy`` command that
+is provided with your Ansible installation:
 
 .. code-block:: console
 
-   pip install ansible
-   ansible-galaxy install git+https://git.openstack.org/openstack/ansible-hardening
+   ansible-galaxy install git+https://github.com/openstack/ansible-hardening
 
-The role will be installed into
-``/etc/ansible/roles/ansible-hardening``.
+The ``ansible-galaxy`` command will install the role into
+``/etc/ansible/roles/ansible-hardening`` and this makes it easy to use with
+Ansible playbooks.
 
-Initial configuration
----------------------
+Using ``git``
+~~~~~~~~~~~~~
 
-The role's default configuration is suitable for most Linux hosts. Deployers
-should review the :ref:`special_notes` section to learn more about how to
-provide custom configuration for the Ansible tasks in the role.
+Start by cloning the role into a directory of your choice:
 
-Using as a standalone role
---------------------------
+.. code-block:: console
 
-Adding the ansible-hardening role to existing playbooks is
-straightforward. Here is an example of an existing role for deploying web
-servers with the security hardening role added:
+   mkdir -p ~/.ansible/roles/
+   git clone https://github.com/openstack/ansible-hardening ~/.ansible/roles/ansible-hardening
+
+Ansible looks for roles in ``~/.ansible/roles`` by default.
+
+If the role is cloned into a different directory, that directory must be
+provided with the ``roles_path`` option in ``ansible.cfg``. The following is
+an example of a ``ansible.cfg`` file that uses a custom path for roles:
+
+.. code-block:: ini
+
+   [DEFAULTS]
+   roles_path = /etc/ansible/roles:/home/myuser/custom/roles
+
+With this configuration, Ansible looks for roles in ``/etc/ansible/roles`` and
+``~/custom/roles``.
+
+Usage
+-----
+
+The ansible-hardening role works well with existing playbooks. The following
+is an example of a basic playbook that uses the ansible-hardening role:
 
 .. code-block:: yaml
 
-   ---
+    ---
 
-   - name: Deploy web servers
-     hosts: webservers
-     become: yes
-     roles:
-       - common
-       - webserver
-       - ansible-hardening
+    - name: Harden all systems
+      hosts: all
+      become: yes
+      vars:
+        security_enable_firewalld: no
+        security_rhel7_initialize_aide: no
+        security_ntp_servers:
+          - 1.example.com
+          - 2.example.com
+      roles:
+        - ansible-hardening
 
-Using with OpenStack-Ansible
-----------------------------
+The variables provided in the ``vars`` section can enable, disable, or alter
+configuration for various tasks in the ansible-hardening role. For more details
+on the available variables, refer to the :ref:`hardening-domains_label`
+section.
 
-The ansible-hardening role is automatically enabled and applied in the
-Newton release of OpenStack-Ansible. Set the following Ansible variable to
-enable the role in the Mitaka release of OpenStack-Ansible:
+.. note::
 
-.. code-block:: yaml
+    The role must be run as the root user or as a user with ``sudo`` access.
+    The example above uses the ``become`` option, which causes Ansible to use
+    sudo before running tasks. If the role is running as root, this option can
+    be changed to ``user: root``.
 
-     apply_security_hardening: true
+.. warning::
 
-For more information, refer to the OpenStack-Ansible documentation on
-`configuring security hardening`_.
-
-.. _configuring security hardening: http://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/app-advanced-config-security.html#security-hardening
+    It is strongly recommended to run the role in check mode (often called a
+    `dry run`) first before making any modifications. This gives the deployer
+    the opportunity to review all of the proposed changes before applying the
+    role to the system. Use the ``--check`` parameter with ``ansible-playbook``
+    to use check mode.