Using the Ksplice Uptrack API

5 Using the Ksplice Uptrack API

The Ksplice Uptrack API is a RESTful web API that enables you to query the status of machines that are running Oracle Ksplice Uptrack. The API provides information about the updates that your machines have, as well as status of any out-of-date, inactive, or unsupported machines.

You can use the command-line tools that are included with the Python bindings; or, you can write your own custom scripts by using the bindings. You can also write your own interface by using HTTP requests. The Python bindings include the check_uptrack and check_uptrack_local plugins for Nagios. These plugins enable you to monitor the status of your machines.

Note:

The Ksplice Uptrack API does not currently support user space or Xen updates. However, the online version of the Ksplice Enhanced client can patch shared libraries for user space processes that are running on an Oracle Linux 6, Oracle Linux 7, Oracle Linux 8 or Oracle Linux 9 system.

Note:

You cannot use the Ksplice Uptrack API to monitor machines that are running Ksplice Offline client because these systems are not registered with https://status.ksplice.oracle.com.

For more information about the Ksplice Uptrack API, visit http://www.ksplice.com/.

Installing the API Command-Line Tools

The API command-line tools are included with the Python bindings for the API in the python-ksplice-uptrack package. This package is available in the Ksplice for Oracle repositories on ULN at linux.oracle.com or the Ksplice Uptrack for Oracle Linux repositories at www.ksplice.com.

Ensure that you have a valid Oracle Linux Premier subscription, a Premier Limited subscription, or an Oracle Premier Support for Systems and Operating Systems subscription.

These subscriptions automatically register your system to use Ksplice. See Registering With ULN for more details.
Install the python-ksplice-uptrack package.
```
sudo yum install -y python-ksplice-uptrack 
```
The Python bindings are installed in the Python site-packages directory, which is typically /usr/lib/python2.6/site-packages/ksplice. The API tools are installed in the /usr/bin directory.

The Nagios plugins are installed in /usr/lib/nagios/plugins.

Using the Ksplice Uptrack API Commands

The Python bindings include the following commands, which cover common uses of the Ksplice Uptrack API.

The commands use the API user name and key for authentication.

uptrack-api-authorize

The uptrack-api-authorize command uses the authorize API call to change the authorization for a single machine, as shown in the following example:

                     uptrack-api-authorize -u api_username -k api_key
                        uuid deny
Successfully denied access for uuid.
uptrack-api-authorize -u api_username -k api_key
                        uuid allow
Successfully allowed access for uuid .

Note:

To view your API user name and API key, log in to https://status.ksplice.oracle.com and then select the Settings tab.

The UUID of a registered machine is stored in /var/lib/uptrack/uuid on the system. An example of a UUID is e82ba0ae-ad0a-4b92-a776-62b502bfd29d.

uptrack-api-describe

The uptrack-api-describe command uses the describe API call to get detailed information about a single machine, which is specified by its UUID, for example:

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

Alternatively, you can specify the --this-machine option if you are running the script on the machine you want to check:

                        uptrack-api-describe -u api_username -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-list

The uptrack-api-list command uses the machines API call to return a list of all of your machines and their statuses, for example:

                        uptrack-api-list -u api_username -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

Viewing Your API User Name and API Key

Log in to https://status.ksplice.oracle.com.
Select the Settings tab.

Generating a New API Key

Note:

Generating a new key invalidates your existing key.

Log in to https://status.ksplice.oracle.com.
Select the Settings tab.
On the Settings page, select the Generate a new API key? check box and click Save Changes.

Specifying the username and api_key Variables

If you set the username and api_key variables in the /etc/uptrack-api.conf file, you do not need to supply these variables as command-line arguments to the scripts.

Place the variables under an [uptrack] section heading, for example:

[uptrack]
username = jo.admin@example.com
api_key  = 3af3c2c1ec407feb0fdc9fc1d8c4460c

You can also set the username and api_key variables in the UPTRACK_API_USERNAME and UPTRACK_API_KEY environment variables, for example:

export UPTRACK_API_USERNAME=jo.admin@example.com
export UPTRACK_API_KEY=3af3c2c1ec407feb0fdc9fc1d8c4460c
uptrack-api-describe --this-machine

Specifying a Proxy

If you access the internet by using a proxy, specify the connection information in the [uptrack] section of the /etc/uptrack-api.conf file, as shown in the following example:

https_proxy = [protocol://][username:password@]proxy[:port]

In the previous example, protocol is either specified as http or https, username and password authenticate you with the proxy (if required), and proxy and port are the host name/IP address and port number that you use to connect to the proxy server, respectively.

The following example shows how you might specify this connection information:

https_proxy = http://proxy.example.com:3128/

Note that the proxy must support HTTPS connections.

About the API Implementation

Learn about the API version, authentication, request format, supported requests, and a sample interaction.

API Version

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

API 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 include the API user name and API key of the user who is making the request.

API 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 currently, as the API supports only JSON-encoded data, but future versions of the API might support additional data-encoding formats.

Supported API Requests

The following are descriptions of the API requests that are currently supported.

GET /api/1/machines

The GET /api/1/machines API request returns a list of all of the registered machines. This list includes inactive machines that have uninstalled Uptrack or any machines that have not reported to the Uptrack server recently. The list does not include machines that you have hidden by using the web interface. The response shows a list of machines, which are 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 following fields are provided in the response:

status

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.

authorization

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.

autoinstall

Indicates whether autoinstall is set on the machine.

mmap_min_addr

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

uptrack_client_version

Is the version of the Uptrack client that the machine is running.

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

The GET /api/1/machine/$UUID/describe API request 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 of the machine before any Ksplice updates were applied.
steps: A list of two-element lists of the form [action, {'ID': update_id, 'Name': update_name}],which represent the updates that need to be installed or removed to bring the machine up to date. For the action argument, you can specify Install or Remove. Note that an existing update is removed if it superseded by a more recent version.

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

The POST /api/1/machine/$UUID/authorize API request 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 the boolean argument as true to authorize the machine or false to revoke authorization.

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

The POST /api/1/machine/$UUID/group API request changes the group of the machine with the specified UUID.

The content is a dictionary that uses the following form:

{group_name: string}

In the previous example, string is the name of the new group. The group is created if it does not already exist. Note that 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 a different name, or you can specify an empty string for no group.

Interaction Sample

The following example, which is provided as a reference only, shows an interaction that might take place when using the Uptrack API.

This conversation takes place with the server uptrack.api.ksplice.com over port 443 by using the Secure Sockets Layer (SSL) protocol.

The following is a request for a list of registered machines that 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@example.com
X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c

The server authenticates the request and responds with a list of the machines, for example:

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

Configuring the check_uptrack Nagios Plugin

Note:

The Nagios software does not include the python-ksplice-uptrack package. For information about obtaining and using Nagios, visit the official Nagios website at http://www.nagios.org.

Configure the check_uptrack Nagios plugin as follows:

Set the username and api_key variables in the configuration file /etc/uptrack-api.conf under an [uptrack] section heading, for example:
```
[uptrack]
username = jo.admin@example.com
api_key  = 3af3c2c1ec407feb0fdc9fc1d8c4460c
```
If you access the Internet by using a proxy, specify the connection information in the [uptrack] section of /etc/uptrack-api.conf:
```
https_proxy = [protocol://][username:password@]proxy[:port] 
```
In the previous example, protocol is http or https, username and password authenticate you with the proxy (if required), and proxy and port are host name/IP address and port that you use to connect o the proxy server, respectively. The connection information you specify might be similar to the following:
```
https_proxy = http://proxy.example.com:3128/
```
The proxy must support HTTPS connections.

Configure the check_uptrack plugin in the Nagios configuration file, which is usually /usr/local/nagios/etc/nagios.cfg.

The following minimal configuration enables you to run the plugin:

# Dummy host with which to associate the Uptrack service
define host {
       host_name                       uptrack-service
       notifications_enabled           0
       max_check_attempts              1
       notification_interval           0
       check_period                    never
       contacts                        server-admins
}

define service {
       host_name                       uptrack-service
       service_description             Ksplice Uptrack Update Status
       check_command                   check_uptrack
       notifications_enabled           1
       normal_check_interval           60
       retry_check_interval            15
       max_check_attempts              4
       notification_options            w,c,r
       contacts                        server-admins
}

define command {
       command_name     check_uptrack
       command_line     /usr/lib/nagios/plugins/check_uptrack
}

define command {
       command_name     check_uptrack_opts
       command_line     /usr/lib/nagios/plugins/check_uptrack -w $ARG1$ -c $ARG2$
}

Using the Nagios Plugin

To monitor all of your machines by using the Nagios plugin, run the following command:

sudo /usr/lib/nagios/plugins/check_uptrack

The previous command produces a summary of your machines in the standard Nagios plug-in format, as shown in the following example:

2 machines are OUTOFDATE!|uptodate=1280;outofdate=1;unsupported=0;inactive=3
  prod1.example.com (192.168.1.1) is OUTOFDATE
  prod2.example.com (192.168.1.2) is OUTOFDATE

If you specify the -c or -w options with a comma-separated list of the arguments that also specify the i, o, or u options for inactive, out-of-date, or unsupported machines, the check_uptrack command displays critical or warning notices for machines that match the criteria.

For example, the following command returns warning notices for any machines that are inactive or unsupported, as well as critical notices for any machines that are out of date:

sudo /usr/lib/nagios/plugins/check_uptrack -w u,i -c o

To monitor the local machine, use the check_uptrack_local plugin:

sudo /usr/lib/nagios/plugins/check_uptrack_local

The output from the check_uptrack_local command is similar to the output from the check_uptrack command. However, for out-of-date machines, the command also lists the updates that are required to bring the machine up to date.

Note:

The check_uptrack_local command reads the local uptrack update cache; however, it does not use the settings from the /etc/uptrack-api.conf file.