API実装について

APIバージョン、認証、リクエスト形式、サポートされているリクエストおよびサンプルの対話について学習します。

認証

Uptrack APIサーバーへの認証では、カスタムHTTPヘッダーで指定されているユーザー名およびAPIキーを使用します。

すべてのリクエストには、次のHTTPヘッダーが含まれている必要があります:

X-Uptrack-User: リクエストを作成しているユーザーのAPIユーザー名。
X-Uptrack-Key: リクエストを作成しているユーザーのAPIキー。

APIリクエスト形式

APIリクエストまたはレスポンスには、JSONエンコード・データがリクエスト本体に含まれます。

すべてのリクエストに次のHTTPヘッダーを設定します:

Content-Type: application/json
Accept:: application/json

APIはJSONエンコード・データのみを使用するため、これらのヘッダーは必要ありませんが、将来のバージョンのAPIで他のデータ・エンコード形式が使用される可能性があります。

APIエンドポイント

このドキュメントでは、APIのバージョン1について説明します。すべてのリクエストは、https://uptrack.api.ksplice.com/api/1/から始まるパスに送られます。次のエンドポイントを使用できます:

サンプルの対話

次の例は、参照用としてのみ提供されており、APIを使用してKspliceアカウント用に管理されているシステムをリストする方法を示しています。

curl -X GET "https://uptrack.api.ksplice.com/api/1/machines" \
  -H "Accept: application/json" \
  -H "X-Uptrack-User: jo.admin@example.com" \
  -H "X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c"

サーバーは、リクエストを認証して、次のようにシステムのリストで応答します:

[
  {
    "status": "uptodate",
    "autoinstall": true,
    "uuid": "00086980-47cb-4486-81c0-4fe3299bad90",
    "mmap_min_addr": 65536,
    "ip": "192.168.248.238",
    "hostname": "host1.example.com",
    "uptrack_client_version": "1.2.80",
    "active": true,
    "authorization": "allowed",
    "last_seen": "2025-05-12T11:19:21Z"
  }
]

GET /api/1/machines

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

[
  {
    "status": "uptodate",
    "autoinstall": true,
    "uuid": "00086980-47cb-4486-81c0-4fe3299bad90",
    "mmap_min_addr": 65536,
    "ip": "192.168.248.238",
    "hostname": "host1.example.com",
    "uptrack_client_version": "1.2.80",
    "active": true,
    "authorization": "allowed",
    "last_seen": "2025-05-12T11:19:21Z"
  }
]

レスポンスには次のフィールドがあります。

status

次の値のいずれかが含まれています。

outofdate - システムにインストールするために更新を使用できます。
unsupported - システムのカーネルがKsplice Uptrackでサポートされていません。
uptodate - 使用可能なすべての更新がシステムにインストールされています。

authorization

次の値のいずれかが含まれています。

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

autoinstall

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

mmap_min_addr

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

uptrack_client_version

システムが実行されているUptrackクライアントのバージョンです。

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を指定できます。既存の更新は新しいバージョンで置き換えられた場合には削除されることに注意してください。

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

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

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

{authorized: boolean}

boolean引数をtrue (システムを認可する)またはfalse (認可を取り消す)に指定します。

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

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

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

{group_name: string}

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

システムをグループから削除する場合は、グループを別の名前に設定するか、グループなしの空の文字列を指定できます。