Ksplice

Uptrack API Overview

The Ksplice Uptrack API is a RESTful web API for users to programmatically query the status of their machines running Ksplice Uptrack. You can use the command line tools that come with our Python bindings, write your own custom scripts using the bindings, or write your own interface to the HTTP requests.

The API can tell you what updates machines have, if you have out of date, inactive, or unsupported machines, and more. The Python bindings also come with a Nagios plugin that uses the API to check the status of all your machines at once. See the API tools section below for more information.

Getting and using the command line API tools

The command line API tools ship with the Python bindings for the API.

Installation

Through your package manager

  1. If you don't already have Ksplice Uptrack installed on this system:
    Follow the installation instructions for your distribution on the manual installation page up through the line where you set up the Ksplice Uptrack repository. That line is rpm -i ksplice-uptrack-release.noarch.rpm for rpm-based systems and apt-key add ksplice-archive.asc for dpkg-based systems.
  2. Install python-ksplice-uptrack using your package manager: 
        yum install -y python-ksplice-uptrack
    or 
        apt-get install python-ksplice-uptrack

By hand

  1. Download the latest release.
  2. To extract the archive, run 
        tar xvfz ksplice-uptrack-latest.tar.gz
  3. Follow the installation instructions in the INSTALL file.

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

Your API username and key

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

Note that your API key is not the same as your 64-character access key!

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.foobar.com (192.168.1.102): outofdate
    - qa1.foobar.com (192.168.1.103): outofdate (inactive)
    - prod1.foobar.com (192.168.1.100): uptodate
    - prod2.foobar.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.foobar.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.foobar.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.

Configuration options

You can set the username and api_key configuration variables in your /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: 

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.

API implementation details

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.

Users can view their API key online on their web interface settings page. API keys can be regenerated on that page at any time, invalidating the previous key.

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.

Supported requests

The API currently supports the following requests:

GET /api/1/machines

Returns a list of all machines.

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: 

   {
      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.


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

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 machines query.

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

original_kernel
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
Ksplice has applied all of the important security and reliability updates needed to bring your system in line with this kernel version. An example effective_kernel is "2.6.18-194.11.1.el5xen".
installed_updates
A list of 2-element dictionaries of the form {'ID': update_id, 'Name': update_name}, representing the updates currently installed on the machine.

update_id is the ID code of an update (e.g. "diptbg4f"), and update_name is a human readable name for the update (e.g. "CVE-2010-0415: Information Leak in sys_move_pages").
steps
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 will usually be "Install", but may occasionally be "Remove", if, for example, an update has been superseded by a newer version. update_id is the ID code of an update (e.g. "diptbg4f"), and update_name is a human readable name for the update (e.g. "CVE-2010-0415: Information Leak in sys_move_pages").
group
A string indicating the group a machine is assigned to.

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

Changes the authorization of a specific UUID to access the Uptrack service.

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 at https://uptrack.ksplice.com/settings/.

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. If authorized is true, the machine will be granted access; false will deny the machine access.


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

Changes the group of a specific UUID.

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 Interaction

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 uptrack.api.ksplice.com.

Request to the server

GET /api/1/machines HTTP/1.1
Host: uptrack.api.ksplice.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"}]

Copyright © 2012, Oracle Corporation and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. | Legal