Merge "Updating getting started docs"

doc/source/getting-started.rst

@@ -4,5 +4,120 @@
 Getting started
 ===============
 
-Content coming soon.  It's a bit difficult to add in this role into
-openstack-ansible at the moment but that's being fixed soon.
+`This role is still a work in progress.  These instructions are subject to
+change frequently until the development work is feature complete.`
+
+The openstack-ansible-security role can be used along with the
+`openstack-ansible`_ project or as a standalone role that can be used along
+with other Ansible playbooks.
+
+Using with openstack-ansible
+----------------------------
+
+This portion of the guide assumes that openstack-ansible is already cloned
+into ``/opt/openstack-ansible`` and it has been properly configured.  Start by
+cloning openstack-ansible-security into Ansible's default role location::
+
+    git clone https://github.com/openstack/openstack-ansible-security \
+        /etc/ansible/roles/openstack-ansible-security
+
+Before getting started, review the ``defaults/main.yml`` file from the
+openstack-ansible-security repository.  There are some documented options there
+for changes which may require opt-in or opt-out configuration.  Some options
+can be adjusted depending on the security level of a particular environment.
+
+Create a directory to hold an Ansible configuration file and a small playbook::
+
+    mkdir /opt/openstack-ansible-security
+    cd /opt/openstack-ansible-security
+
+Create a small Ansible playbook at
+``/opt/openstack-ansible-security/os-security.yml``:
+
+.. code-block:: yaml
+
+    ---
+
+    - name: Run openstack-ansible-security
+      hosts: "{{ host_group|default('hosts') }}"
+      user: root
+      roles:
+        - openstack-ansible-security
+
+Add an Ansible configuration file so that your playbook can use
+openstack-ansible's dynamic inventory.  Create a new file at
+``/opt/openstack-ansible-security/ansible.cfg``::
+
+    [defaults]
+    gathering = smart
+    host_key_checking = False
+
+    # SSH timeout
+    timeout = 120
+
+    # Set the path to the folder in openstack-ansible which holds the dynamic
+    # inventory script - new config setting for ansible v1.9 and above
+    inventory = ../openstack-ansible/playbooks/inventory/
+
+    # Set the path to the folder in openstack-ansible which holds the dynamic
+    # inventory script - uncomment if using ansible below v1.9
+    #hostfile = ../openstack-ansible/playbooks/inventory/
+
+    # Set the path to the folder in openstack-ansible which holds the
+    # libraries required
+    library = ../openstack-ansible/playbooks/library/
+
+    # Set the path to the folder in openstack-ansible which holds the
+    # lookup plugins required
+    lookup_plugins = ../openstack-ansible/playbooks/plugins/lookups/
+
+    # Set the path to the folder in openstack-ansible which holds the filter
+    # plugins required
+    filter_plugins = ../openstack-ansible/playbooks/plugins/filters/
+
+    # Set the path to the folder in openstack-ansible which holds the action
+    # plugins required
+    action_plugins = ../openstack-ansible/playbooks/plugins/actions/
+
+    [ssh_connection]
+    pipelining = True
+
+Run the playbook::
+
+    cd /opt/openstack-ansible-security/
+    openstack-ansible os-security.yml
+
+There are lots of tags throughout the tasks in the role that will allow
+deployers to select certain tasks or groups of tasks to run.  For example, just
+the ``auditd`` improvements can be deployed by using the appropriate tag::
+
+    openstack-ansible os-security.yml -t auditd
+
+.. _openstack-ansible: https://github.com/openstack/openstack-ansible/
+
+Using as a standalone role
+--------------------------
+
+There are several options for using openstack-ansible-security as a standalone
+role or along with another existing project. Here are two fairly easy methods:
+
+* Add openstack-ansible-security as a git submodule in the roles directory
+  of an existing Ansible project
+* Clone the role into ``/etc/ansible/roles/`` on any system and write a custom
+  playbook and hosts inventory file
+
+The playbook for openstack-ansible-security can be fairly simple, depending
+on the configuration of the systems:
+
+.. code-block:: yaml
+
+    ---
+
+    - name: Run openstack-ansible-security
+      hosts: webservers
+      user: root
+      roles:
+        - openstack-ansible-security
+
+This playbook will run the tasks in the openstack-ansible-security role against
+all hosts in the ``webservers`` group (as defined in an inventory file).

doc/source/index.rst

@@ -1,6 +1,8 @@
 Security hardening for openstack-ansible
 ========================================
 
+`Work in progress -- this role is in the early stages of development.`
+
 The openstack-ansible-security role provides security hardening for `OpenStack`_
 environments deployed with `openstack-ansible`_.  The role has multiple goals: