このコンテンツを正しく表示するには、JavaScriptが有効になっている必要があります

第 4 章 Ksplice Uptrack APIの使用

この章では、Ksplice Uptrackのプログラミング・インタフェースについて説明します。 Ksplice Uptrack APIの詳細は、http://www.ksplice.com/を参照してください。

4.1 Ksplice Uptrack APIについて

Ksplice Uptrack APIは、Ksplice Uptrackを実行しているマシンのステータスを問い合せることができるRESTful web APIです。 APIは、マシンの更新に関する情報と、最新でないマシン、非アクティブなマシンまたはサポートされていないマシンのステータスを提供します。

Pythonバインディングに含まれるコマンドライン・ツールを使用することも、バインディングを使用して独自のカスタム・スクリプトを記述することもできます。 HTTPリクエストを使用して独自のインタフェースを作成することもできます。 Pythonバインディングには、Nagios用のcheck_uptrackおよびcheck_uptrack_localプラグインが含まれています。これらのプラグインを使用すると、マシンのステータスをモニターできます。

ノート

Ksplice Uptrack APIを使用して、Ksplice Offlineクライアントを実行しているマシンを監視することはできません。これらのシステムはhttps://uptrack.ksplice.comに登録されていないためです。

4.2 APIユーザー名およびAPIキーの表示

APIユーザー名およびAPIキーを表示するには、https://uptrack.ksplice.comにログインして「設定」タブを選択します。

4.3 新しいAPIキーの生成

新しいAPIキーを生成するには、次のようにします:

https://uptrack.ksplice.comにログインし、「設定」タブを選択します。
「設定」ページで、新しいAPIキーを生成するチェック・ボックスを選択し、「変更の保存」をクリックします。

ノート

このアクションにより、既存のキーが無効になります。

4.4 APIコマンドライン・ツールのインストール

APIコマンドライン・ツールは、python-ksplice-uptrackパッケージのAPIのPythonバインディングに含まれています。このパッケージは、ULNのKsplice for Oracleリポジトリ(linux.oracle.com)またはKsplice Uptrack for Oracle Linuxのリポジトリ(www.ksplice.com)から入手できます。

次の手順で、コマンドラインAPIツールをインストールします。

有効なOracle Linux Premierサブスクリプション、Premier LimitedサブスクリプションまたはOracle Premier Support for SystemsとOperating Systemsサブスクリプションがあることを確認してください。

以前にリストされたサブスクリプションは、Oracle Kspliceを使用するようにシステムを自動的に登録します。詳細は、第1.3.2項、「Oracle KspliceおよびULNの登録について」を参照してください。
python-ksplice-uptrackパッケージをインストールします。
```
sudo yum install -y python-ksplice-uptrack 
```
PythonバインディングはPython site-packagesディレクトリ(通常は/usr/lib/python2.6/site-packages/ksplice)にインストールされます。 APIツールは、/usr/binディレクトリにインストールされます。

Nagiosプラグインは/usr/lib/nagios/pluginsにインストールされます。

4.5 Ksplice Uptrack APIコマンド

Pythonバインディングには、Ksplice Uptrack APIの一般的な使用について説明する次のコマンドが含まれています。

4.5.1 uptrack-api-authorizeコマンドについて

uptrack-api-authorizeコマンドは、次の例に示すように、authorize APIコールを使用して単一マシンの認可を変更します:

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 .

ノート

APIユーザー名およびAPIキーを表示するには、https://uptrack.ksplice.comにログインし、「設定」タブを選択します。

登録済マシンのUUIDは、システムの/var/lib/uptrack/uuidに格納されます。 UUIDの例は、e82ba0ae-ad0a-4b92-a776-62b502bfd29dです。

4.5.2 uptrack-api-describeコマンドについて

uptrack-api-describeコマンドは、describe APIコールを使用して、UUIDで指定された単一のマシンに関する詳細情報を取得します。次に例を示します:

uptrack-api-describe -u api_username -k api_key uuid
    prod1.mydom.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

また、チェックするマシン上でスクリプトを実行する場合は、--this-machineオプションを指定できます:

uptrack-api-describe -u api_username -k api_key --this-machine
    qa.mydom.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.

4.5.3 uptrack-api-listコマンドについて

uptrack-api-listコマンドは、次の例のようにmachines APIコールを使用して、すべてのマシンおよびそのステータスのリストを返します。

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

4.5.4 usernameとapi_key変数の指定

/etc/uptrack-api.confファイルでusername変数およびapi_key変数を設定する場合は、これらの変数をスクリプトへのコマンドライン引数として指定する必要はありません。

次の例のように、変数を[uptrack]セクション見出しに置きます。

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

次の例のように、UPTRACK_API_USERNAMEおよびUPTRACK_API_KEY環境変数にusernameおよびapi_key変数を設定することもできます:

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

4.5.5 プロキシの指定

プロキシを使用してインターネットにアクセスする場合は、次の例に示すように、/etc/uptrack-api.confファイルの[uptrack]セクションに接続情報を指定します:

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

前の例では、protocolはhttpまたはhttpsとして指定され、usernameとpasswordはプロキシで認証され(必要な場合)、proxyとportはそれぞれ、プロキシ・サーバーへの接続に使用するホスト名/IPアドレスとポート番号です。

次の例は、この接続情報を指定する方法を示しています:

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

プロキシはHTTPS接続をサポートしている必要があることに注意してください。

4.6 API実装について

次の情報は、Ksplice Uptrack APIの実装に関連します。

4.6.1 APIバージョン

このドキュメントでは、APIのバージョン1について説明します。すべてのリクエストは、/api/1/から始まるパスに移動します。

4.6.2 API認証

Uptrack APIサーバーへの認証では、カスタムHTTPヘッダーで指定されているユーザー名およびAPIキーを使用します。具体的には、すべてのリクエストに、リクエストを実行するユーザーのAPIユーザー名とAPIキーを含むX-Uptrack-UserおよびX-Uptrack-Key HTTPヘッダーを含める必要があります。

4.6.3 APIリクエスト形式

APIリクエストまたはレスポンスには、JSONエンコード・データがリクエスト本体に含まれます。リクエストでは、application/jsonのContent-Typeヘッダーを設定する必要があります。同様に、コンテンツを含むレスポンスを要求するリクエストには、値application/jsonを含むAccept:ヘッダーが含まれている必要があります。

APIはjsonでエンコードされたデータのみをサポートするため、現在これらのヘッダーは必要ありませんが、将来のバージョンのAPIでは、追加のデータ・エンコーディング形式がサポートされる場合があります。

4.6.4 サポートされているAPIリクエスト

次に、現在サポートされているAPIリクエストの説明を示します。

4.6.4.1 GET /api/1/machines

GET /api/1/machines APIリクエストは、登録されているすべてのマシンのリストを返します。このリストには、アップトラックをアンインストールした非アクティブなマシンや、最近アップ・サーバーに報告されなかったマシンが含まれます。リストには、Webインタフェースを使用して非表示にしたマシンは含まれません。レスポンスには、次の例に示すように、ディクショナリとして表されるマシンのリストが表示されます:

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

レスポンスには次のフィールドが表示されます:

status

次のいずれかの値が含まれます:

outofdate: マシンのインストールに追加の更新を使用できます。
unsupported: マシンのカーネルはKsplice Uptrackでサポートされていません。
uptodate: 使用可能なすべての更新がマシンにインストールされています。

認可

次のいずれかの値が含まれます:

allowed: マシンは、Uptrackサーバーとの通信および更新の受信が可能です。
denied: マシンは、Webインタフェース、uptrack-api-authorizeまたはauthorize APIコールを介したUptrackサーバーへのアクセスが拒否されています。
pending: このアカウントには、新規マシンのデフォルトの拒否ポリシー・セットがあり、マシンはまだ認可されていません。

autoinstall

マシンにautoinstallが設定されているかどうかを示します。

mmap_min_addr

バージョン1.0.3より前のクライアントの/proc/sys/vm/mmap_min_addrまたはNoneの値です。

uptrack_client_version

マシンが実行中であるUptrackクライアントのバージョンです。

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

GET /api/1/machine/ $UUID /describe APIリクエストは、指定されたUUIDのマシンに関する情報を返します。マシンのUUIDは、/var/lib/uptrack/uuidに保存されており、machines問合せを使用して取得できます。レスポンスは、次の追加フィールドを含む点を除き、GET /api/1/machinesが返すのと同じ形式のディクショナリです。

effective_kernel: Kspliceでは、マシンとこのカーネル・バージョンを一致させるのに必要とされる、重要なセキュリティおよび信頼性に関するすべての更新が適用されています。
group: マシンが割り当てられるグループ。 Webインタフェースを使用してマシン・グループを管理することもできます。
installed_updates: マシンに現在インストールされている更新を表す、{'ID': update_id, 'Name': update_name}という形式の2要素ディクショナリのリスト。update_idは、更新のIDコード(例: diptbg4f)、update_nameは、更新の短い説明の名前(例: CVE-2010-0415: Information Leak in sys_move_pages)です。
original_kernel: Kspliceの更新が適用される前のマシンのカーネル・バージョン。
steps: [action, {'ID'-update_id, 'Name': update_name}]という形式の2要素のリストで、マシンを最新の状態にするためにインストールまたは削除する必要がある更新を表します。 action引数には、InstallまたはRemoveを指定できます。既存の更新がより新しいバージョンで置き換えられた場合、その更新は削除されることに注意してください。

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

新しいマシンへのアクセスを拒否するようにアカウントを構成している場合、POST /api/1/machine/ $UUID /authorize APIリクエストは、指定されたUUIDのマシンにUptrackサービスへのアクセスを認可します。

ディクショナリのコンテンツの形式は次のとおりです。

{authorized: boolean}

マシンを認可する場合はboolean引数をtrueに指定し、認可を取り消す場合はfalseを指定します。

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

POST /api/1/machine/ $UUID /group APIリクエストは、指定されたUUIDを持つマシンのグループを変更します。

コンテンツは、次の形式を使用するディクショナリです:

{group_name: string}

前述の例では、stringは新しいグループの名前です。まだ存在しない場合、グループを作成します。指定されたUUIDのマシンがアカウントに存在しない場合、リクエストはHTTP 404エラーになります。

グループからマシンを削除するには、グループを別の名前に設定するか、空の文字列をグループなしに指定します。

4.6.5 相互作用のサンプル

参照のみとして提供されている次の例は、Uptrack APIの使用時に発生する可能性のある相互作用を示しています。

この対話は、Secure Sockets Layer (SSL)プロトコルを使用して、ポート443を介してサーバーuptrack.api.ksplice.comと行われます。

次に、サーバーに対して行われる登録済マシンのリストに対するリクエストを示します:

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

サーバーはリクエストを認証し、マシンのリストで応答します。次に例を示します:

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"}]

4.7 check_uptrack Nagiosプラグインの構成

ノート

Nagiosソフトウェアにはpython-ksplice-uptrackパッケージは含まれていません。 Nagiosの入手および使用の詳細は、http://www.nagios.orgの公式Nagios webサイトを参照してください。

次の手順でcheck_uptrack Nagiosブラグインを構成します。

次の例のように、構成ファイル/etc/uptrack-api.confの[uptrack]セクション見出しの下に、usernameおよびapi_keyを設定します。
```
[uptrack]
username = jo.admin@mydom.com
api_key  = 3af3c2c1ec407feb0fdc9fc1d8c4460c
```
プロキシを使用してインターネットにアクセスする場合は、/etc/uptrack-api.confの[uptrack]セクションで接続情報を指定します:
```
https_proxy = [protocol://][username:password@]proxy[:port] 
```
前述の例では、protocolはhttpまたはhttps、usernameおよびpasswordでプロキシを使用して認証し(必要な場合)、proxyおよびportは、プロキシ・サーバーへの接続にそれぞれ使用するホスト名/IPアドレスおよびポートです。指定する接続情報は次のようになります:
```
https_proxy = http://proxy.example.com:3128/
```
プロキシはHTTPS接続をサポートしている必要があります。

check_uptrackプラグインをNagiosの構成ファイルに構成します(通常は/usr/local/nagios/etc/nagios.cfg)。

次の最小構成でも、プラグインを実行できます。

# 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$
}

4.8 Nagiosプラグインの使用

Nagiosプラグインを使用してすべてのマシンを監視するには、次のコマンドを実行します:

sudo /usr/lib/nagios/plugins/check_uptrack

前述のコマンドでは、次の例に示すように、標準のNagiosプラグイン形式でマシンのサマリーが生成されます:

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

-cまたは-wオプションを引数のカンマ区切りリストとともに指定し、非アクティブ、最新でない、またはサポートされていないマシンのi、oまたはuオプションも指定した場合、check_uptrackコマンドは、基準に一致するマシンのクリティカルまたは警告の通知を表示します。

たとえば、次のコマンドを実行すると、非アクティブまたはサポートされていないマシンに関する警告通知と、最新でないマシンに関するクリティカルな通知が返されます:

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

ローカル・マシンを監視するには、check_uptrack_localプラグインを使用します:

sudo /usr/lib/nagios/plugins/check_uptrack_local

check_uptrack_localコマンドからの出力は、check_uptrackコマンドからの出力に似ています。ただし、最新ではないマシンの場合、マシンを最新の状態にするために必要な更新も表示されます。

ノート

check_uptrack_localコマンドはローカルのuptrack更新キャッシュを読み取りますが、/etc/uptrack-api.confファイルの設定は使用しません。