Audit logs
Note
See RFC 2616#section-9 for more details on HTTP methods semantics
General
Audit logs are used to track changes made on your resources, either by you or by other parties, like CloudSigma staff or people that have permission to access you resources.
Querying is done as follows:
- GET /logs/
- Status Codes:
200 OK – no error
GET /api/2.0/logs/?limit=5 HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "meta": { "limit": 5, "offset": 0, "total_count": 3193934 }, "objects": [ { "action": "delete", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:41:29.378194+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" }, { "action": "stop", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:41:26.864672+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" }, { "action": "stop_send", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:41:24.811553+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" }, { "action": "boot", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:40:48.789732+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" }, { "action": "start_send", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:40:47.897876+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" } ] }
Actions
Actions give information about the operation that created the log. They go in a few categories.
- General actions - related to most resource types like servers, drives and snapshots:
create: During resource creation
update: During resource update
delete: During resource deletion
change_owner: The ownership of the resource has changed. Currently only CloudSigma staff can change ownership of a resource.
clone_src: Resource is used as a cloning source
clone_dst: Resource is a cloning destination - the newly cloned drive.
- Drive specific actions - these only relate to drives:
move: Drive is moved to another physical storage. Only staff members can move drives.
convert_to_library: Drive is converted to a library drive. Only staff members can convert drives.
converted_from_library: Drive is converted to a regular drive from a library drive. Only staff members can convert drives.
init_upload: Drive upload is initialized.
- Server specific actions - these only relate to servers:
start_send: An attempt to start a server
boot: The result of a start operation.
stop_send: An attempt to stop a server.
stop: The result of a stop operation
open_vnc: Open VNC channel to a server
close_vnc: Close VNC channel to a server
shutdown_ACPI_send: An ACPI shutdown request is send to the server.
heal: Server got healed, because its recorded state did not match the physical infrastructure. For example, a server is marked as unavailable, but it is actually running fine.
Errors
If the field success is marked as False, that means that an error occurred during the operation. The error details are saved in the following fields:
error_type - States the type of the error
error_point - Points to cause of the error and is mainly used for validation errors
error_message - Human readable message associated with the error
Example
The following example will show all the logged information during a server’s lifecycle.
First we create a server:
POST /api/2.0/servers/ HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop { "objects": [ { "cpu": 1000, "mem": 536870912, "name": "test_server", "vnc_password": "testserver" } ] }HTTP/1.1 201 CREATED Content-Type: application/json; charset=utf-8 { "objects": [ { "context": true, "cpu": 1000, "cpu_model": null, "cpu_type": "amd", "cpus_instead_of_cores": false, "drives": [], "enable_numa": false, "grantees": [], "hv_relaxed": false, "hv_tsc": false, "hypervisor": "kvm", "jobs": [], "mem": 536870912, "meta": {}, "name": "test_server", "nics": [], "owner": { "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/", "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00" }, "permissions": [], "pubkeys": [], "requirements": [], "resource_uri": "/api/2.0/servers/973a1039-8014-4622-9a6a-8caf21e08e7e/", "runtime": null, "smp": 1, "status": "stopped", "tags": [], "uuid": "973a1039-8014-4622-9a6a-8caf21e08e7e", "vnc_password": "testserver" } ] }
Upon completion you will see the following log at the top of the audit log list:
GET /api/2.0/logs/?limit=1 HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDopHTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "meta": { "limit": 1, "offset": 0, "total_count": 3193929 }, "objects": [ { "action": "create", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "{\"name\": \"test_server\", \"tags\": [], \"mem\": 536870912, \"smp\": 1, \"cpu\": 1000, \"vnc_password\": \"testserver\"}", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:40:29.833850+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" } ] }
action states that we wanted to create a server
details state the parameters of the create call
actor states the user which executed the operation
success is true, so the operation completed successfully.
uuid matches the server’s uuid
Then we start the server:
POST /api/2.0/servers/4002da8d-94d7-4093-ab7a-a78d976a9efc/action/?do=start HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop {}HTTP/1.1 202 ACCEPTED Content-Type: application/json; charset=utf-8 { "action": "start", "result": "success", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" }
We check the logs again. We see that the action is start_send and success is true:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "meta": { "limit": 1, "offset": 0, "total_count": 3193930 }, "objects": [ { "action": "start_send", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:40:47.897876+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" } ] }
If the server is fully booted and operational, its status will change to running. If it failed to boot for some reason, the error_type, error_point and error_message fields will explain why that happened. In this particular case, we had a successful start, so the audit log looks like this:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "meta": { "limit": 1, "offset": 0, "total_count": 3193931 }, "objects": [ { "action": "boot", "actor": { "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/", "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23" }, "category": "Servers", "details": "", "error_message": "", "error_point": null, "error_type": null, "success": true, "timestamp": "2014-06-05 09:40:48.789732+00:00", "uuid": "4002da8d-94d7-4093-ab7a-a78d976a9efc" } ] }
- The pattern is the same when stopping a server:
an audit log with action stop_send is saved, representing the status of the request to stop a server.
If that succeeded i.e. the request to stop a server is successfully send, you can expect a log with action stop, representing the status of the stop operation i.e. the server actually stopped.
Note
If you stop a server from inside, only a log entry with stop action will be added. This way, you can figure out if the server got stopped from the API or not:
If there are 2 logs stop_send and stop, it is stopped via an API request
If only stop is present ( no stop_send ), it means that the server is stopped by other means (stopped from inside, crashed, etc).
Schema
- GET /logs/schema/
GET /api/2.0/logs/schema/ HTTP/1.1 Content-Type: application/json Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "allowed_detail_http_methods": [], "allowed_list_http_methods": [ "get" ], "default_format": "application/json", "default_limit": 20, "fields": { "action": { "default": null, "help_text": "Name of the executed action", "readonly": false, "required": true, "type": "string" }, "actor": { "default": null, "help_text": "User who executed action.", "readonly": false, "required": false, "type": "related" }, "category": { "default": null, "help_text": "Category the action belongs to.", "readonly": false, "required": true, "type": "string" }, "details": { "default": null, "help_text": "Details about the executed action.", "readonly": false, "required": false, "type": "string" }, "error_message": { "default": null, "help_text": "Error message, if applicable.", "readonly": false, "required": false, "type": "string" }, "error_point": { "default": null, "help_text": "The field that caused the error, if applicable.", "readonly": false, "required": false, "type": "string" }, "error_type": { "default": null, "help_text": "Type of error, if applicable.", "readonly": false, "required": false, "type": "string" }, "success": { "default": true, "help_text": "Whether the action was successful.", "readonly": false, "required": true, "type": "boolean" }, "timestamp": { "default": null, "help_text": "Time when entry was added.", "readonly": false, "required": true, "type": "string" }, "uuid": { "default": null, "help_text": "The uuid of resource the action is executed on. Can be empty, meaning no resource is referenced.", "readonly": false, "required": false, "type": "string" } }, "filtering": { "name": "exact", "name__contains": "exact", "tag": "exact", "uuid": "exact" } }