2.6 About the API Implementation

2.6.1 Versioning
2.6.2 Authentication
2.6.3 Request Format
2.6.4 Supported Requests
2.6.5 Sample Interaction

The following sections describe the implementation of the Ksplice Uptrack API.

2.6.1 Versioning

This document describes version 1 of the API. All requests go to paths that begin with /api/1/.

2.6.2 Authentication

Authentication to the Uptrack API server uses a user name and an API key that are specified in custom HTTP headers. Specifically, all requests must include X-Uptrack-User and X-Uptrack-Key HTTP headers that specify the API user name and API key of the user making the request.

2.6.3 Request Format

API requests or responses include JSON-encoded data in the request body. Requests should set a Content-Type header of application/json. Similarly, any requests that expect a response containing content should include an Accept: header that contains the value application/json.

These headers are not required at present as the API supports only JSON-encoded data, but future versions of the API might support additional data-encoding formats.

2.6.4 Supported Requests

The following sections describe the requests that the API currently supports.

2.6.4.1 GET /api/1/machines

GET /api/1/machines returns a list of all registered machines. The list includes inactive machines that have uninstalled Uptrack or that have not reported in to the Uptrack server recently. The list does not include machines that you have hidden by using the web interface. The response is a list of machines, represented as dictionaries, as shown in the following example:

 {
      hostname: uptrack.example.com,
      ip: 184.73.248.238,
      last_seen: '2010-04-26T18:03:43Z',
      uuid: e82ba0ae-ad0a-4b92-a776-62b502bfd29d,
      active: true,
      status: uptodate,
      authorization: allowed,
      autoinstall: true,
      mmap_min_addr: 4096,
      uptrack_client_version: 1.2.1
   }

The status field contains one of the following values:

outofdate

Additional updates are available for installation on the machine.

unsupported

The machine's kernel is not supported by Ksplice Uptrack.

uptodate

All available updates have been installed on the machine.

The authorization field contains one of the following values:

allowed

The machine is allowed to communicate with the Uptrack servers and to receive updates.

denied

The machine has been denied access to the Uptrack servers via the web interface, uptrack-api-authorize, or the authorize API call.

pending

This account has the default deny policy set for new machines, and the machine has not yet been authorized.

The autoinstall field indicates if autoinstall is set on the machine.

The mmap_min_addr field is the value of /proc/sys/vm/mmap_min_addr or None for clients prior to version 1.0.3.

The uptrack_client_version field is the version of the Uptrack client that the machine is running.

2.6.4.2 GET /api/1/machine/$UUID/describe

GET /api/1/machine/$UUID/describe returns information about the machine with the specified UUID. The UUID of a machine is stored in /var/lib/uptrack/uuid and can be retrieved by using the machines query. The response is a dictionary of the same form that GET /api/1/machines returns, except that it includes the following additional fields:

effective_kernel

Ksplice has applied all of the important security and reliability updates that are needed to bring the machine into line with this kernel version.

group

The group to which the machine is assigned. You can also use the web interface to manage machine groups.

installed_updates

A list of 2-element dictionaries of the form {'ID': update_id, 'Name': update_name} that represent the updates currently installed on the machine. update_id is the ID code of an update (for example, diptbg4f) and update_name is a short descriptive name for the update (for example, CVE-2010-0415: Information Leak in sys_move_pages).

original_kernel

The kernel version that the system had before any Ksplice updates were applied.

steps

A list of 2-element lists of the form [action, {'ID': update_id, 'Name': update_name}], representing the updates that need to be installed or removed to bring the machine up to date. action can be Install or Remove. A existing update is removed if it superseded by a newer version.

2.6.4.3 POST /api/1/machine/$UUID/authorize

POST /api/1/machine/$UUID/authorize authorizes the machine with the specified UUID to access the Uptrack service if you have configured your account to deny access to new machines. The content is a dictionary of the following form:

{authorized: boolean}

Specify boolean as true to authorize the machine or false to revoke authorization.

2.6.4.4 POST /api/1/machine/$UUID/group

POST /api/1/machine/$UUID/group changes the group of the machine with the specified UUID. The content is a dictionary of the following form:

{group_name: string}

where string is the name of the new group. The group is created if it does not already exist. If the account does not have a machine with the specified UUID, the request results in an HTTP 404 error.

To remove a machine from a group, you can set the group to something else, or an empty string for no group.

2.6.5 Sample Interaction

A sample interaction using the Ksplice Uptrack API is shown here for reference. This conversation takes place with the server uptrack.api.ksplice.com over port 443 using SSL.

The following request for a list of registered machines is made to the server:

GET /api/1/machines HTTP/1.1
Host: uptrack.api.ksplice.com
Accept: application/json
X-Uptrack-User: jo.admin@mydom.com
X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c

The server authenticates the request and responds with the list of machines:

HTTP/1.0 200 OK
Date: Mon, 03 May 2010 21:09:48 GMT
Content-Type: application/json

[{"status": "uptodate", "uuid": "e82ba0ae-ad0a-4b92-a776-62b502bfd29d",
  "active": true, "ip": "192.168.248.238", "hostname": "utclient.mydom.com",
  "authorization": "allowed", "autoinstall": true,
  "last_seen": "2010-04-26T18:03:43Z", "mmap_min_addr": 4096,
  "uptrack_client_version": "1.2.1"}]