From 6c1ee2e5831754002707cc28f2ff49440565f409 Mon Sep 17 00:00:00 2001 From: Steve Martinelli Date: Tue, 17 Feb 2015 00:10:10 -0500 Subject: Additional doc clean up 1) Added code-block headers to the JSON examples 2) Formatted the JSON examples 3) Replaced a few instances of double-byte characters with more their usual counter parts ("-" and "'"), these normally originate from the openstack wiki for some reason. Change-Id: I2ca1dbfc5bdf1c50da466b290a6460a42f1b885a --- doc/source/event_concept.rst | 170 ++++++++++++++++++----------- doc/source/specification/attachments.rst | 32 +++--- doc/source/specification/credentials.rst | 33 +++--- doc/source/specification/endpoints.rst | 34 +++--- doc/source/specification/events.rst | 106 ++++++++++-------- doc/source/specification/geolocations.rst | 30 ++--- doc/source/specification/hosts.rst | 17 ++- doc/source/specification/measurements.rst | 44 ++++---- doc/source/specification/reasons.rst | 26 ++--- doc/source/specification/reportersteps.rst | 29 +++-- doc/source/specification/resources.rst | 34 +++--- 11 files changed, 307 insertions(+), 248 deletions(-) diff --git a/doc/source/event_concept.rst b/doc/source/event_concept.rst index b2569a9..0de03b7 100644 --- a/doc/source/event_concept.rst +++ b/doc/source/event_concept.rst @@ -72,7 +72,7 @@ Event Attribute Value Reason eventType activity OBSERVER is required to report any user security activity observer.typeURI service/security/identity Value from the CADF Resource Taxonomy most closely describes an "Identity Manager Service" initiator.typeURI data/security/account/user Value from the CADF Resource Taxonomy most closely describes a "user" -action authenticate/logon Value from the CADF Action Taxonomy most closely describes a user "logon" action. +action authenticate/logon Value from the CADF Action Taxonomy most closely describes a user "logon" action. target.typeURI service/compute/node Value from the CADF Resource Taxonomy most closely describes a target "server" outcome success Any valid CADF Outcome Taxonomy value that describes result of action measurement N/A A MEASUREMENT component is not required for "activity" type events. @@ -80,44 +80,78 @@ REASON N/A A REASON component is not required ================= ========================== ========================================================================================== Event serialisation (including some optional attributes for additional -details):: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "eventTime": "2014-02-27T19:29:30.855665+0000", - "target": { - "typeURI": "service/compute/node", - # optional Endpoints to describe compute node - "addresses": [{"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "admin"}, - {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "private"}, - {"url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", "name": "public"}], - "id": "openstack:06747855d62547d4bfd707f75b8a1c54", - "name": "nova"}, - "observer": {"id": "target"}, # shortform to show Observer Resource is the same as Target - # tags use to query events on - "tags": ["correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2"], - "eventType": "activity", - "initiator": { - "typeURI": "data/security/account/user", - "name": "admin", - # optional Credential to describe resource - "credential": {"token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==", - "identity_status": "Confirmed"}, - # optional Host to describe resource - "host": {"agent": "python-novaclient", "address": "9.26.26.250"}, - "project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6", - "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"}, - # optional Reason for activity event - "reason": {"reasonCode": "200", "reasonType": "HTTP"}, - # list of Resources which edited event - "reporterchain": [{"reporterTime": "2014-02-27T19:29:31.043902+0000", - "role": "modifier", - "reporter": {"id": "target"}}], - "action": "authenticate/logon", - "outcome": "success", - "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007", - # Event model is extensible so additional attributes may be added to describe model - "requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates"} +details): + +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "eventTime": "2014-02-27T19:29:30.855665+0000", + "target": { + "typeURI": "service/compute/node", + # optional Endpoints to describe compute node, + "addresses": [ + { + "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", + "name": "admin" + }, + { + "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", + "name": "private" + }, + { + "url": "http://9.26.26.250:8774/v2/e7e2bcc9c0df4f3eabcd412ae62503f6", + "name": "public" + } + ], + "id": "openstack:06747855d62547d4bfd707f75b8a1c54", + "name": "nova" + }, + "observer": { + "id": "target" # shortform to show Observer Resource is the same as Target, + }, + # tags use to query events on, + "tags": [ + "correlation_id?value=openstack:56cdde6f-6b4e-48a4-94e6-defb40522fb2" + ], + "eventType": "activity", + "initiator": { + "typeURI": "data/security/account/user", + "name": "admin", + # optional Credential to describe resource, + "credential": { + "token": "MIIQzgYJKoZIhvcNAQcCoIIQvzCCELsC xxxxxxxx zqvD9OPWZm7VQpYNK2EvrZi-mTvb5A==", + "identity_status": "Confirmed" + }, + # optional Host to describe resource, + "host": { + "agent": "python-novaclient", + "address": "9.26.26.250" + }, + "project_id": "openstack:e7e2bcc9c0df4f3eabcd412ae62503f6", + "id": "openstack:68a3f50705a54f799ce94380fc02ed8a" + }, + # optional Reason for activity event, + "reason": { + "reasonCode": "200", + "reasonType": "HTTP" + }, + # list of Resources which edited event, + "reporterchain": [ + { + "reporterTime": "2014-02-27T19:29:31.043902+0000", + "role": "modifier", + "reporter": { + "id": "target" + } + } + ], + "action": "authenticate/logon", + "outcome": "success", + "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007", + # Event model is extensible so additional attributes may be added to describe model, + "requestPath": "/v2/e7e2bcc9c0df4f3eabcd412ae62503f6/os-certificates" + } 2. Periodic monitoring resource status @@ -145,30 +179,40 @@ measurement 80% MEASUREMENT component is required and t reason N/A REASON component is not required for "monitor" type events. ================= ====================== ========================================================================================== -Event serialisation:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "eventTime": "2014-02-27T19:29:30.855665+0000", - "target": { - "typeURI": "service/compute/cpu", - "id": "openstack:06747855d62547d4bfd707f75b8a1c54", - "name": "instance"}, - "observer": {"id": "initiator"}, - "eventType": "monitor", - "initiator": { - "typeURI": "service/oss/monitoring", - "name": "ceilometer-pollster", - "id": "openstack:68a3f50705a54f799ce94380fc02ed8a"}, - "measurement": [{ - "result": "80", - "metric": {"metricId": "openstack:", - "unit": "%", - "name": "CPU utilisation metric"} - }] - "action": "monitor", - "outcome": "success", - "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007"} +Event serialisation: + +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "eventTime": "2014-02-27T19:29:30.855665+0000", + "target": { + "typeURI": "service/compute/cpu", + "id": "openstack:06747855d62547d4bfd707f75b8a1c54", + "name": "instance" + }, + "observer": { + "id": "initiator" + }, + "eventType": "monitor", + "initiator": { + "typeURI": "service/oss/monitoring", + "name": "ceilometer-pollster", + "id": "openstack:68a3f50705a54f799ce94380fc02ed8a" + }, + "measurement": [ + { + "result": "80", + "metric": { + "metricId": "openstack:", + "unit": "%", + "name": "CPU utilisation metric" + } + } + ]"action": "monitor", + "outcome": "success", + "id": "openstack:0a196053-95de-48f8-9890-4527b25b5007" + } .. note:: diff --git a/doc/source/specification/attachments.rst b/doc/source/specification/attachments.rst index beba392..3e82306 100644 --- a/doc/source/specification/attachments.rst +++ b/doc/source/specification/attachments.rst @@ -20,9 +20,9 @@ ============ An attachment is a container for data or "content" that may follow any -structure – from an atomic type to a complex hierarchy. However, it is -desirable for processing and interoperability that the type – or -structure – of the content be identified by a simple value. To this end the +structure - from an atomic type to a complex hierarchy. However, it is +desirable for processing and interoperability that the type - or +structure - of the content be identified by a simple value. To this end the attachment also contains a "content type", i.e., a URI that identifies the kind of content. @@ -40,19 +40,19 @@ contentType xs:string Yes An optional name that can be used to provide an i Serialisation ============= -json:: +.. code-block:: javascript - { - ..., - "attachments": [ { - "content": "xs:any", - "contentType": "xs:anyURI" - }, - { - "content": "xs:any", - "contentType": "xs:anyURI" + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "attachments": [ + { + "content": "xs:any", + "contentType": "xs:anyURI" + }, + { + "content": "xs:any", + "contentType": "xs:anyURI" + } + ] } - ] - } - diff --git a/doc/source/specification/credentials.rst b/doc/source/specification/credentials.rst index 0132150..4ec1d5b 100644 --- a/doc/source/specification/credentials.rst +++ b/doc/source/specification/credentials.rst @@ -21,7 +21,7 @@ This type provides a means to describe various credentials along with any information about the authority that is responsible for maintaining them. -This is intended to be associated with a CADF Resource’s identity and reflects +This is intended to be associated with a CADF Resource's identity and reflects any authorizations or identity assertions the resource may use to gain access to other resources. @@ -37,20 +37,19 @@ assertions cadf:Map No Optional list of additional assertions or attribut Serialisation ============= -json:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "action": "authenticate", - ..., - "initiator": { - "id": "joe.user@tenant1.com", - "typeURI": "data/security/account/user", - ..., - "credential": { - "type": "https://mycloud.com/v2/token", - "token": "myuuid:1ef0-abdf-xxxx-xxxx" - } +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "action": "authenticate", + ..., + "initiator": { + "id": "joe.user@example.com", + "typeURI": "data/security/account/user", + ..., + "credential": { + "type": "https://mycloud.com/v2/token", + "token": "myuuid:1ef0-abdf-xxxx-xxxx" + } + } } - } - diff --git a/doc/source/specification/endpoints.rst b/doc/source/specification/endpoints.rst index b64b4b6..5ff330b 100644 --- a/doc/source/specification/endpoints.rst +++ b/doc/source/specification/endpoints.rst @@ -33,21 +33,21 @@ port xs:string No An optional property to provide the port value separ Serialisation ============= -json:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "target": { - "id": "myscheme://mydomain/resource/id/0001", - "name": "server_0001", - "addresses": [{ - "name": "public", - "url": "http://mydomain/mypath/server-0001/" - }, - ... - ], - ... +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + "id": "myscheme://mydomain/resource/id/0001", + "name": "server_0001", + "addresses": [ + { + "name": "public", + "url": "http://mydomain/mypath/server-0001/" + }, + ... + ], + ... + } } - } - diff --git a/doc/source/specification/events.rst b/doc/source/specification/events.rst index 9bcc311..6c411d8 100644 --- a/doc/source/specification/events.rst +++ b/doc/source/specification/events.rst @@ -20,7 +20,7 @@ ======= The CADF Event Model applies semantics to the activities, resources, -information, and changes within a cloud provider’s infrastructure and models +information, and changes within a cloud provider's infrastructure and models these using the concept of an event. ============= =================== ========= ============================================================================================================================================================= @@ -50,47 +50,65 @@ reporterchain cadf:Reporterstep[] No Array of Reporterstep typed data tha Serialisation ============= -json:: +.. code-block:: javascript - { - 'typeURI': 'http://schemas.dmtf.org/cloud/audit/1.0/event', - 'id': 'openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637‘, - 'eventType': 'activity', - 'action': 'read', - 'outcome': 'success', - 'reason': {'reasonCode': '200', 'reasonType': 'HTTP'}, - 'eventTime': '2014-01-17T23:23:38.109989+0000', - 'initiator': { - 'id': 'openstack:95f12d248a234a969f456cd2c794f29a' - 'typeURI': 'service/security/account/user', - 'name': ‘admin', - 'project_id': 'openstack:e55b158759854ea6a7852aa76632c6c1', - 'credential': { - 'token': ‘MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=‘, - 'identity_status': 'Confirmed'}, - 'host': { - 'agent': 'python-novaclient', - 'address': '9.26.27.109'}, - }, - 'target': { - 'id': 'openstack:0f126160203748a5b4923f2eb6e3b7db', - 'typeURI': ‘service/compute/servers', - 'name': 'nova‘ - 'addresses': [ - {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', - 'name': 'admin'}, - {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', - 'name': 'private'}, - {'url': 'http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1', - 'name': 'public'} - ], - }, - 'observer': { 'id': 'target'}, - 'reporterchain': [ - {'reporterTime': '2014-01-17T23:23:38.154152+0000', - 'role': 'modifier', - 'reporter': {'id': 'target'}} - ], - 'requestPath': '/v2/56600971-90f3-4370-807f-ab79339381a9/servers', - 'tags': ['correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a'] - } + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "id": "openstack:a80dc5ee-be83-48ad-ad5e-6577f2217637", + "eventType": "activity", + "action": "read", + "outcome": "success", + "reason": { + "reasonCode": "200", + "reasonType": "HTTP" + }, + "eventTime": "2014-01-17T23:23:38.109989+0000", + "initiator": { + "id": "openstack:95f12d248a234a969f456cd2c794f29a""typeURI": "service/security/account/user", + "name": "admin", + "project_id": "openstack:e55b158759854ea6a7852aa76632c6c1", + "credential": { + "token": "MIIQBgYJKoZIhvcNAQcCoIIP9z xxxxxx KoZIhvcIP9z=", + "identity_status": "Confirmed" + }, + "host": { + "agent": "python-novaclient", + "address": "9.26.27.109" + } + }, + "target": { + "id": "openstack:0f126160203748a5b4923f2eb6e3b7db", + "typeURI": "service/compute/servers", + "name": "nova", + "addresses": [ + { + "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1", + "name": "admin" + }, + { + "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1", + "name": "private" + }, + { + "url": "http://9.26.27.109:8774/v2/e55b158759854ea6a7852aa76632c6c1", + "name": "public" + } + ] + }, + "observer": { + "id": "target" + }, + "reporterchain": [ + { + "reporterTime": "2014-01-17T23:23:38.154152+0000", + "role": "modifier", + "reporter": { + "id": "target" + } + } + ], + "requestPath": "/v2/56600971-90f3-4370-807f-ab79339381a9/servers", + "tags": [ + "correlation_id?value=openstack:bcac04dc-e0be-4110-862c-347088a7836a" + ] + } diff --git a/doc/source/specification/geolocations.rst b/doc/source/specification/geolocations.rst index 43211b3..6bfbdc1 100644 --- a/doc/source/specification/geolocations.rst +++ b/doc/source/specification/geolocations.rst @@ -19,7 +19,7 @@ Geolocations ============= -Geolocation information, which reveals a resource’s physical location, is +Geolocation information, which reveals a resource's physical location, is obtained by using tracking technologies such as global positioning system (GPS) devices, or IP geolocation by using databases that map IP addresses to geographic locations. Geolocation information is widely used in @@ -59,7 +59,7 @@ Usage Requirements :: - Example: ‘latitude’, ‘longitude’ and ‘region’ are all supplied as + Example: 'latitude', 'longitude' and 'region' are all supplied as properties describing the same geolocation, the 'latitude' and 'longitude' properties' coordinate values should resolve to the same geographic location as described by the 'region' @@ -72,17 +72,17 @@ Usage Requirements Serialisation ============= -json:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "target": { - ..., - "geolocation": { - "latitude": "+372207.90", - "longitude": "-1220210.20", - "elevation": "10" - } +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + ..., + "geolocation": { + "latitude": "+372207.90", + "longitude": "-1220210.20", + "elevation": "10" + } + } } - } diff --git a/doc/source/specification/hosts.rst b/doc/source/specification/hosts.rst index f77c130..5c604d8 100644 --- a/doc/source/specification/hosts.rst +++ b/doc/source/specification/hosts.rst @@ -43,12 +43,11 @@ platform xs:string No The optional platform of the host RESOURCE Serialisation ============= -json:: - - { - "id": "myuuid:1234-5678-90abc-defg-0000", - "address": "10.0.2.15", - "agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)", - "platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013" - } - +.. code-block:: javascript + + { + "id": "myuuid:1234-5678-90abc-defg-0000", + "address": "10.0.2.15", + "agent": "Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:18.0)", + "platform": "Linux version 3.5.0-23-generic (gcc version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) ) #35~precise1-Ubuntu SMP Fri Jan 25 17:15:33 UTC 2013" + } diff --git a/doc/source/specification/measurements.rst b/doc/source/specification/measurements.rst index afbea8d..214b555 100644 --- a/doc/source/specification/measurements.rst +++ b/doc/source/specification/measurements.rst @@ -51,27 +51,29 @@ annotations cadf:map No User-defined metric information. Serialisation ============= -json:: +.. code-block:: javascript - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log", - ..., - "metrics": [ { - "metricId": "myuuid://metric.org/1234", - "unit": "GB", - "name": "Storage Capacity in Gigabytes" - }], - ..., - "events": [ - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "measurements": [ - { - "result": "10", - "metricId": "myuuid://metric.org/1234" - }], - ... - }] + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/log", + ..., + "metrics": [ + { + "metricId": "myuuid://metric.org/1234", + "unit": "GB", + "name": "Storage Capacity in Gigabytes" + } + ], + ..., + "events": [ + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "measurements": [ + { + "result": "10", + "metricId": "myuuid://metric.org/1234" + } + ] + } + ] } diff --git a/doc/source/specification/reasons.rst b/doc/source/specification/reasons.rst index aed4e20..705c631 100644 --- a/doc/source/specification/reasons.rst +++ b/doc/source/specification/reasons.rst @@ -34,16 +34,16 @@ policyId xs:string No An optional identifier that indicates which policy Serialisation ============= -json:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "reason": { - "reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml", - "reasonCode": "408", - "policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy", - "policyId": "http://10.0.3.4/firewall-ruleset/rule0012" - }, - ... - } +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "reason": { + "reasonType": "http://www.iana.org/assignments/http-status-codes/http-status-codes.xml", + "reasonCode": "408", + "policyType": "http://schemas.xmlsoap.org/ws/2002/12/policy", + "policyId": "http://10.0.3.4/firewall-ruleset/rule0012" + }, + ... + } diff --git a/doc/source/specification/reportersteps.rst b/doc/source/specification/reportersteps.rst index 40bbf26..e9e80b1 100644 --- a/doc/source/specification/reportersteps.rst +++ b/doc/source/specification/reportersteps.rst @@ -41,20 +41,19 @@ attachments cadf:Attachment[] No An optional array of additional data co Serialisation ============= -json:: +.. code-block:: javascript - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "reporterchain": [ { - "role": "modifier", - "reporterTime": "2012-03-22T13:00:00-04:00", - "reporter": { - "id": "myscheme://mydomain/resource/monitor/id/0002" - } - }, - ... - ] - } - + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "reporterchain": [ + { + "role": "modifier", + "reporterTime": "2012-03-22T13:00:00-04:00", + "reporter": { + "id": "myscheme://mydomain/resource/monitor/id/0002" + } + }, + ... + ] + } \ No newline at end of file diff --git a/doc/source/specification/resources.rst b/doc/source/specification/resources.rst index 9225baa..830f445 100644 --- a/doc/source/specification/resources.rst +++ b/doc/source/specification/resources.rst @@ -43,22 +43,20 @@ attachments cadf:Attachment[] No An optional array of extended or domai Serialisation ============= -json:: - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - ..., - "target": { - "id": "myscheme://mydomain/resource/id/0001", - "typeURI": "service/compute", - "name": "server_0001", - ..., - "geolocation": { - "city": "Austin", - "state": "TX", - "regionICANN": "US" - } +.. code-block:: javascript + + { + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + ..., + "target": { + "id": "myscheme://mydomain/resource/id/0001", + "typeURI": "service/compute", + "name": "server_0001", + ..., + "geolocation": { + "city": "Austin", + "state": "TX", + "regionICANN": "US" + } + } } - } - - -- cgit v1.2.1