documentation for audit middleware

this moves (and edits) audit middleware documentation from pycadf
library to keystonemiddleware

pycadf doc: https://github.com/openstack/pycadf/blob/master/doc/source/middleware.rst

Implements: blueprint audit-middleware
Change-Id: I068f312d8927010fd209eab5c22910c4d1d343a1

doc/source/audit.rst

@@ -0,0 +1,81 @@
+..
+      Copyright 2014 IBM Corp
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _middleware:
+
+=================
+ Audit middleware
+=================
+
+The Keystone middleware library provides an optional WSGI middleware filter
+which allows the ability to audit API requests for each component of OpenStack.
+
+The audit middleware filter utilises environment variables to build the CADF
+event.
+
+.. figure:: ./images/audit.png
+   :width: 100%
+   :align: center
+   :alt: Figure 1: Audit middleware in Nova pipeline
+
+The figure above shows the middleware in Nova's pipeline.
+
+Enabling audit middleware
+=========================
+To enable auditing, oslo.messaging_ should be installed. If not, the middleware
+will log the audit event instead. Auditing can be enabled for a specific
+project by editing the project's api-paste.ini file to include the following
+filter definition:
+
+::
+
+   [filter:audit]
+   paste.filter_factory = keystonemiddleware.audit:AuditMiddleware.factory
+   audit_map_file = /etc/nova/api_audit_map.conf
+
+The filter should be included after Keystone middleware's auth_token middleware
+so it can utilise environment variables set by auth_token. Below is an example
+using Nova's WSGI pipeline::
+
+   [composite:openstack_compute_api_v2]
+   use = call:nova.api.auth:pipeline_factory
+   noauth = faultwrap sizelimit noauth ratelimit osapi_compute_app_v2
+   keystone = faultwrap sizelimit authtoken keystonecontext ratelimit audit osapi_compute_app_v2
+   keystone_nolimit = faultwrap sizelimit authtoken keystonecontext audit osapi_compute_app_v2
+
+.. _oslo.messaging: http://www.github.com/openstack/oslo.messaging
+
+Configure audit middleware
+==========================
+To properly audit api requests, the audit middleware requires an
+api_audit_map.conf to be defined. The project's corresponding
+api_audit_map.conf file is included in the `pyCADF library`_.
+
+The location of the mapping file should be specified explicitly by adding the
+path to the 'audit_map_file' option of the filter definition::
+
+   [filter:audit]
+   paste.filter_factory = keystonemiddleware.audit:AuditMiddleware.factory
+   audit_map_file = /etc/nova/api_audit_map.conf
+
+Additional options can be set::
+
+   [filter:audit]
+   paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory
+   audit_map_file = /etc/nova/api_audit_map.conf
+   service_name = test # opt to set HTTP_X_SERVICE_NAME environ variable
+   ignore_req_list = GET,POST # opt to ignore specific requests
+
+.. _pyCADF library: https://github.com/openstack/pycadf/tree/master/etc/pycadf

doc/source/index.rst

@@ -1,9 +1,10 @@
 Python Middleware for OpenStack Identity API (Keystone)
 =======================================================
 
-This is the middleware provided for integrating with the OpenStack 
+This is the middleware provided for integrating with the OpenStack
 Identity API and handling authorization enforcement based upon the
-data within the OpenStack Identity tokens.
+data within the OpenStack Identity tokens. Also included is middleware that
+provides the ability to create audit events based on API requests.
 
 Contents:
 
@@ -11,6 +12,7 @@ Contents:
    :maxdepth: 1
 
    middlewarearchitecture
+   audit
 
 Contributing
 ============

keystonemiddleware/audit.py

@@ -53,7 +53,13 @@ def _log_and_ignore_error(fn):
 
 
 class AuditMiddleware(object):
-    """Create an audit event based on request/response."""
+    """Create an audit event based on request/response.
+
+    The audit middleware takes in various configuration options such as the
+    ability to skip audit of certain requests. The full list of options can
+    be discovered here:
+    http://docs.openstack.org/developer/keystonemiddleware/audit.html
+    """
 
     @staticmethod
     def _get_aliases(proj):