diff --git a/doc/source/event_concept.rst b/doc/source/event_concept.rst index 913f174..b2569a9 100644 --- a/doc/source/event_concept.rst +++ b/doc/source/event_concept.rst @@ -33,7 +33,7 @@ perspective of a single RESOURCE called the OBSERVER that is responsible for observing the Actual Event and creating the (initial) CADF Event Record. .. figure:: ./images/observer_cadf.png - :figwidth: 100% + :width: 100% :align: center :alt: Figure 1: Observer perspective of an Event @@ -62,7 +62,7 @@ activities including "logon" attempts against any servers within the provider's infrastructure. .. figure:: ./images/audit_event.png - :figwidth: 100% + :width: 100% :align: center :alt: Figure 2: Conceptually mapping values of an audit event @@ -128,7 +128,7 @@ status of each server's CPU utilisation along with metric data to their operations management software by using the CADF Event Record format. .. figure:: ./images/monitor_event.png - :figwidth: 100% + :width: 100% :align: center :alt: Figure 3: Conceptually mapping values of an monitor event @@ -172,4 +172,4 @@ Event serialisation:: .. note:: - Additional use cases can be found in the Full CADF specification. \ No newline at end of file + Additional use cases can be found in the Full CADF specification. diff --git a/doc/source/index.rst b/doc/source/index.rst index e930d46..5f2ba36 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -42,6 +42,7 @@ Getting Started :maxdepth: 1 event_concept + specification/index middleware Developer Documentation @@ -52,7 +53,6 @@ Developer Documentation contributing debugging - specification/index Code Documentation ================== diff --git a/doc/source/middleware.rst b/doc/source/middleware.rst index 22d7410..fe8f748 100644 --- a/doc/source/middleware.rst +++ b/doc/source/middleware.rst @@ -19,85 +19,8 @@ Audit middleware ================= -The pyCADF library provides an optional WSGI middleware filter which allows -the ability to audit api requests for each component of OpenStack. +pyCADF's version of the audit middleware has been deprecated as of pyCADF +0.8.0. For continued support, the middleware is now maintained under the +Identity (Keystone) umbrella. Related documentation can be found here_. -The audit middleware filter utilises environment variables to build the CADF -event. - -.. figure:: ./images/middleware.png - :figwidth: 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 the audit middleware, the following requirements need to be -satisfied: - -1. pyCADF library must be added to the requirements file of the project to be - audited. - -2. The project should utilise oslo.messaging_ notification system. - -.. note:: - - If the project utilises oslo's `old notification system`_, a compatible - middleware can be synced from oslo-incubator's `middleware code base`_. - -If the above requirements are satisfied, auditing can be enabled by editing -the project's api-paste.ini file to include the following filter definition: - -:: - - [filter:audit] - paste.filter_factory = pycadf.middleware.audit:AuditMiddleware.factory - -or - -:: - - [filter:audit] - paste.filter_factory = .openstack.common.middleware.audit:AuditMiddleware.factory - -The filter should be included after Keystone's auth_token middleware so it can -utilise environment variables set by Keystone's middleware. 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: https://github.com/openstack/oslo.messaging -.. _old notification system: https://github.com/openstack/oslo-incubator -.. _middleware code base: https://github.com/openstack/oslo-incubator/tree/master/openstack/common/middleware - -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`_. - -By default, the audit middleware filter expects the map file to be located in -the same folder as the other conf files related to the project -(ie.'/etc/' folder). This default functionality is to be deprecated -and so the location should be specified explicitly by adding the path to the -'audit_map_file' option of the filter definition:: - - [filter:audit] - paste.filter_factory = pycadf.middleware.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 +.. _here: http://docs.openstack.org/developer/keystonemiddleware/audit.html diff --git a/doc/source/specification/index.rst b/doc/source/specification/index.rst index 56d2e06..9037bf7 100644 --- a/doc/source/specification/index.rst +++ b/doc/source/specification/index.rst @@ -2,14 +2,16 @@ Specification ============== -The following is a high-level description of the CADF specification. The basic -component of the CADF spec are Events. The full CADF specification document -can be found here_. +The following is a high-level description of components in the CADF +specification. The basic component of the CADF specification are Events. The +full CADF specification document can be found here_. Additional details on the +CADF specification are accessible via the `DMTF CADF`_ page. -.. _here: http://www.dmtf.org/standards/cadf +.. _here: http://dmtf.org/sites/default/files/standards/documents/DSP0262_1.0.0.pdf +.. _DMTF CADF: http://www.dmtf.org/standards/cadf .. toctree:: - :maxdepth: 2 + :maxdepth: 1 events attachments