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:
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 SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/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"
    }
}