Oracle Home
Sign In/Register for Account   Help

Using the Uptrack API Tools

Installing the Uptrack API Tools

Package Managers

If you don't already have Ksplice Uptrack installed on this system:

Follow the manual installation instructions on the installation page through this line:

$ rpm -i ksplice-uptrack-release.noarch.rpm

Install python-ksplice-uptrack using your package manager:

$ yum install -y python-ksplice-uptrack

Manually

Download the latest release.

Extract the archive by running:

$ tar xvfz ksplice-uptrack-latest.tar.gz

Follow the installation instructions in the INSTALL file.

The Python bindings will be installed in your Python site-packages directory, typically /usr/lib/python2.6/site-packages/ksplice. The API tools will be installed in /usr/bin/.

Configuring the API Tools

You can get your API username and key from your web interface settings page. API keys can be regenerated on that page at any time, invalidating the previous key.

Your API key is not the same as your 64-character access key.

You can set the username and api_key configuration variables in /etc/uptrack-api.conf so you don't have to supply them as command line arguments to these scripts. Put them under an [uptrack] section heading:

[uptrack]
username = joeuser
api_key  = 3af3c2c1ec407feb0fdc9fc1d8c4460c

You can also set the username and api key in the UPTRACK_API_USERNAME and UPTRACK_API_KEY environment variables, respectively:

$ export UPTRACK_API_USERNAME=joeuser
$ export UPTRACK_API_KEY=3af3c2c1ec407feb0fdc9fc1d8c4460c
$ uptrack-api-describe --this-machine

Using a proxy

If you need to configure internet access through a proxy, you can do so in your /etc/uptrack-api.conf using a line like this in the [uptrack] section:

[uptrack]
https_proxy = http://proxy.example.com:3128/

The proxy string should be of the form [protocol://][username:password@]<host>[:port], where

  • protocol is the protocol to connect to the proxy (http or https)
  • username and password are the authentication information needed to use your proxy (if any).
  • host and port are the hostname/ip address and port number used to connect to the proxy
  • The proxy must support making HTTPS connections.

Using the API Tools

The Python bindings come with several command line utilities that cover common uses of the API and are ready to use right off the shelf:

uptrack-api-list

Uses the machines API call to return a list of all of your machines and their statuses, for example:

$ uptrack-api-list -u api_name -k api_key
- dev1.example.com (192.168.1.102): outofdate
- qa1.example.com (192.168.1.103): outofdate (inactive)
- prod1.example.com (192.168.1.100): uptodate
- prod2.example.com (192.168.1.101): uptodate

uptrack-api-describe

Uses the describe API call to get detailed information on a single machine. You can supply a UUID or pass --this-machine if the script is being run on the machine you want to check:

$ uptrack-api-describe -u api_name -k api_key uuid
prod1.example.com (192.168.1.100)
Effective kernel: 2.6.18-194.11.1.el5xen
This machine is no longer active
Last seen on 2010-09-12T10:19:35Z
OS status: Up to date

$ uptrack-api-describe -u api_name -k api_key --this-machine
qa.example.com (192.168.1.200)
Effective kernel: 2.6.18-194.8.1.el5
This machine is active
Last seen on 2010-09-15T12:43:07Z
OS status: Out of date:
  * Install v8gacfip CVE-2010-2521: Remote buffer overflow in NFSv4 server.
  * Install 3c4sopia CVE-2010-2226: Read access to write-only files in XFS filesystem.
  * Install oiqwvltu CVE-2010-2240: Privilege escalation vulnerability in memory management.

uptrack-api-authorize

Uses the authorize API call to change the authorization for a single machine, for example:

$ uptrack-api-authorize -u api_name -k api_key uuid deny
Successfully denied access for uuid
$ uptrack-api-authorize -u api_name -k api_key uuid allow
Successfully allowed access for uuid

check_uptrack

A Nagios plugin that can monitor all or individual machines, described in detail on our Nagios plugin page.

Python Bindings

In addition to the tools above, we provide a Python API that you can call directly.

To use the API, import ksplice.uptrack.client.Client and initialize it. The default constructor will pull the user name and API key from /etc/uptrack-api.conf.

The Client class includes methods for each API function.

Constructor

from ksplice.uptrack.client import Client

client = Client(
    user=None, api_key=None, api_url=None,
    proxy=None, proxy_port=None, verbose=False)

Accepts an optional username and API key for authentication. You may also give a hostname and port for an HTTP proxy to use for requests.

If the username or api key are not provided, they will be retrieved from the environment variables UPTRACK_API_USERNAME and UPTRACK_API_KEY.

Finally, if a username and API key still cannot be found, the file /etc/uptrack-api.conf will be loaded. This file should be of the form:

[uptrack]
username = joeuser
api_key  = 3af3c2c1ec407feb0fdc9fc1d8c4460c

Your username and API key can be retrieved from your web interface settings page.

Similarly, if proxy is not set, the https_proxy and HTTPS_PROXY environment variables are checked, followed by /etc/uptrack-api.conf. If proxy is set and proxy_port is not set, proxy contains the port information, eg. http://proxy.example.com:3128/.

API Methods

The Client instance supports the following methods and parameters. They all return a dictionary or a list of dictionaries. See the API details below for specifics on the contents of the dictionaries.

list-machines()
Lists all machines known by the Uptrack service that are not hidden (see hide_machine below).
describe_machine(uuid)
Obtains details about a specific machine by its UUID.
authorize_machine(uuid)
Authorizes a specific UUID to access the Uptrack service.
deauthorize_machine(uuid)
Revokes a machine's access to the Uptrack service.
set_machine_group(uuid, group_name)
Sets the group a UUID is associated with.
advisory_check(uuid)
Obtains an audit of the advisories satisfied by the updates the machine has installed, and when they were satisfied.
hide_machine(uuid)
Hides a specific UUID so it doesn't show up on the web interface or in the results of a machines API request.
unhide_machine(uuid)
Unhides a specific UUID.

Using the Uptrack HTTP API Directly

Versioning

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

Authentication

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

You can view your API key on your web interface settings page. API keys can be regenerated on that page at any time.

Regenerating your API key will immediately invalidate the previous API key. Clients attempting to connect with the old API key will be rejected with a 403 error.

Request Format

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

These headers are not currently required, but future versions of the API may add support for communication using additional data-encoding formats and may require these headers.

Response Format

Successful responses will generate an HTTP resonse with a status of 200 OK. They may also include a JSON object as a payload.

If an error occurs, an HTTP status in the 400 or 500 range will be generated. Depending on the type of error, a JSON payload may also be included with the following form:

Sample JSON Resonse:
{
  error: "<error message>"
}

The error message may be helpful in trouble shooting or if you need to contact Ksplice support.

API Endpoints

The API currently supports the following endpoints:

List Machines

Description
Returns a list of all machines.
Request
GET /api/1/machines
Response:
JSON list of Machine objects.

This list includes inactive machines that have uninstalled Uptrack or not reported in to the Uptrack server recently. This list does not include machines that have been hidden using the web interface.

The response is a list of machines, represented as dictionaries with the following form:

Sample JSON Response:
{
  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 will contain one of the following values:

unsupported
This machine's kernel is unsupported by Ksplice Uptrack.
outofdate
There are additional updates available to be installed on this machine.
uptodate
This machine has installed all available updates.

The authorization field will contain one of the following values:

allowed
This machine is allowed to communicate with the Uptrack servers and receive updates.
denied
This machine has been denied access to the Uptrack servers, manually through the web interface, using the uptrack-api-authorize script, or through a custom use of the Authorize API call.
pending
This account has a default deny policy for new machines, and this machine has not yet been authorized.

The autoinstall field is a boolean indicating if autoinstall is enabled on this machine.

The mmap_min_addr field is an integer read out of /proc/sys/vm/mmap_min_addr, or None (clients older than version 1.0.3 did not report this value).

An mmap_min_addr of 0 is a well-documented security problem that should be fixed if possible. For more information, and directions for altering this parameter, please see Red Hat's knowledgebase article on the subject.

Your web interface will warn you about systems with an mmap_min_addr of 0.

The uptrack_client_version field is a string which represents the current version of the Uptrack client a machine is running.

Describe Machine

Description:
Returns information about the machine with the given UUID. The Uptrack UUID of a machine is stored in /var/lib/uptrack/uuid and can also be retrieved using the List Machines query.
Request
GET /api/1/machine/$UUID/describe
Response:
JSON Machine object.

The dictionary is of the same form as returned by GET /api/1/machines (described above), except that it contains several extra fields:

original_kernel is the kernel version the system had before any Ksplice updates were applied. An example original_kernel is 2.6.18-164.9.1.el5xen.

effective_kernel is the kernel version after Ksplice has applied all of the important security and reliability updates needed. An example effective_kernel is 2.6.18-194.11.1.el5xen.

installed_updates is a list of two-element dictionaries of the form {'ID': <update_id>, 'Name': <update_name>}, representing the updates currently installed on the machine.

update_id
The ID code of an update (e.g. diptbg4f).
update_name
A human readable name for the update (e.g. CVE-2010-0415: Information Leak in sys_move_pages).

steps is a list of 2-element lists of the form [<action>, {'ID': <update_id>, 'Name': <update_name>}], representing the steps that need to be taken to bring the machine up to date (i.e. what updates need to be installed or removed).

action
The action to take. It will usually be Install, but may occasionally be Remove, if, for example, an update has been superseded by a newer version.
update_id
The ID code of an update (e.g. diptbg4f).
update_name
A human readable name for the update (e.g. CVE-2010-0415: Information Leak in sys_move_pages).

group is a string indicating the group a machine is assigned to.

Authorize Machine

Description
Changes the authorization of a specific UUID to access the Uptrack service.
Request
POST /api/1/machine/$UUID/authorize
Response
Empty

If you have a default deny policy for new machines, new machines are denied access unless you allow them through the web interface or API. This API call can authorize a machine for the Uptrack service.

You can set your new machine policy using your web interface on the Allow/Deny Policies page.

This API call requires as its content a dictionary of the form:

{
  authorized: BOOL
}

The boolean indicates whether to allow or revoke a machine's authorization. Appropriate values are true or false. If authorized is true, the machine will be granted access; false will deny the machine access.

Change Group

Description
Changes the group of a specific UUID.
Request
POST /api/1/machine/$UUID/group
Response
Empty

This API call requires as its content a dictionary of the form:

{
  group_name: STRING
}

The string indicates the new group to be assigned to the machine. Machine groups can be managed from the web interface. If the group does not exist, it will be created automatically. If the account does not have a machine with the given UUID, the request will result in a 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.

Sample Request/Response

A sample interaction with the Ksplice Uptrack API is listed here for reference. This conversation would take place over port 443 using SSL to the server api-ksplice.oracle.com.

Request to the server

GET /api/1/machines HTTP/1.1
Host: api-ksplice.oracle.com
Accept: application/json
X-Uptrack-User: ksplice
X-Uptrack-Key: 6ecaef35b9f12ef9aeb6fc16cb7ec88a

Server response

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": "184.73.248.238",
    "hostname": "uptrack.example.com",
    "authorization": "allowed",
    "autoinstall": true,
    "last_seen": "2010-04-26T18:03:43Z",
    "mmap_min_addr": 4096,
    "uptrack_client_version": "1.2.1"
  }
]