API (v1) ドキュメント

ご注意: API v1 は現在非推奨です。代わりに API v2 を使用してください。

BlueOnyx には、Vsite とユーザーのリモートプロビジョニング、Vsite の停止と削除、パスワード変更、ステータス確認のための API が用意されています。これは特に WHMCS との連携を念頭に設計されたものです。

BlueOnyx サーバーを管理するための WHMCS モジュールは、無償でこちらから入手できます。Tarball には BlueOnyx 5209R 用、5210R 用、5211R 用の 3 つのモジュールが含まれています。ただし、可能であれば API v2 を使ってください。

2 つのモジュールの違い:

両モジュールの主な違いは、Shell アクセスと PHP アクセスの扱いです。

もし製品側で Shell アクセスを許可しており、5209R 用 WHMCS モジュールを使って 5210R または 5211R へデプロイする場合、作成されるアカウントには 5209R のようなフルシェル権限ではなく、'Chrooted (SFTP SCP RSYNC)' が付与されます。また 5211R では suPHP と PHP-FPM のみがサポート対象であり、5209R や 5210R にあった DSO や mod_ruid2 の選択肢はありません。

インストールと設定:

BlueOnyx 5209R、5210R、5211R には、API モジュール（base-api-*）があらかじめインストールされています。ただし、セキュリティ上の理由から既定では API は無効です。利用する場合は GUI 側で明示的に有効化する必要があります。

BlueOnyx サーバーの GUI にログインし、「Server Management」 / 「Maintenance」 / 「API」へ進んでください。

設定可能な項目は 3 つだけです。

Enable API（既定: off）
Force HTTPS（既定: on）
API Host(s)（既定: 空）

'Enable API' にチェックがなければ API は無効です。'Force HTTPS' を有効にすると、API は HTTPS 接続でのみ応答します。'API Host(s)' では、API へアクセスできる IP アドレスを制限できます。セキュリティ上は HTTPS を強制し、アクセス元 IP を制限することを推奨します。なお、この欄に登録した IP は、通常 GUI を保護している CSRF 保護の除外対象にもなります。

基本的な利用情報:

API は AdmServ 上で動作します。BlueOnyx GUI の CCE バックエンドと通信する必要があるためです。使用ポートは HTTP が 444、HTTPS が 81 です。URL は次のとおりです。

BlueOnyx 5209R/5210R/5211R:

https://<server-ip>:81/api/index
http://<server-ip>:444/api/index

API URL は、一定条件を満たす POST リクエストに対してのみ動作します。本ドキュメントでその条件を順に説明します。POST なしでアクセスすると、API の有効/無効、HTTPS 強制、IP 制限の有無に関係なく、'BlueOnyx API: You're not doing this right.' と返します。不正な POST を送った場合も、同じ文言か、それに準ずる一般的なメッセージが返ることがあります。

API へのアクセスはすべて /var/log/admserv/adm_access および /var/log/admserv/adm_error に記録されます。/var/log/admserv/adm_error には、アクセス元 IP と試行されたトランザクションも記録されます。

もっとも実用的な使い方:

WHMCS を使っているなら、BlueOnyx API 用サーバーモジュールをこちらから取得し、Tarball のディレクトリ構成に従って WHMCS サーバー上の適切な場所へ展開してください。

モジュールを導入したら、WHMCS の 'System Settings' から 'Add Servers' を開き、BlueOnyx サーバーを登録します。設定手順は以下のクリップのとおりです。

BlueOnyx サーバーを 1 台以上 WHMCS に追加したら、'Product/Services' で新しい 'Shared Hosting' 製品を作成します。'Module' のプルダウンには 'Blueonyx5209r' と 'Blueonyx5210r' が現れます。プロビジョニング先 BlueOnyx に合うものを選んでください。以下の動画は BlueOnyx 5210R 用の設定例です。

BlueOnyx 5209R、5210R、5211R にはそれぞれ専用の API モジュールがあります。API に細かな差異があるためです。したがって、管理対象 BlueOnyx の種類に応じて正しいモジュールを WHMCS 側へ入れてください。複数世代を管理する場合は、すべて同時に導入しても構いません。

BlueOnyx サーバーを WHMCS に登録したら、以後はサイトやユーザーのプロビジョニングを始められます。

WHMCS でサポートされる機能:

現時点では 'Hosting Account' タイプのアカウントのみ
'admin' とそのパスワードによる認証
siteAdmin ユーザー付き Vsite の作成
各種 Vsite オプションの有効/無効化および設定
Suspend
Unsuspend
Terminate（Vsite、ユーザー、関連データの削除）
ホスティングパッケージ変更
パスワード変更
Active Monitor 状態確認
クライアントおよび WHMCS 管理者の自動 GUI ログイン

WHMCS 側で BlueOnyx をバックエンドに使う 'Product' を作成すると、機能差のある複数ホスティングパッケージを設定できます。以下は BlueOnyx 5210R モジュールで構成したサンプルパッケージの 'Module Settings' 画面です。

ここで管理できる Vsite 機能には、次のようなものがあります。

ディスク容量
自動 DNS の有効/無効
PHP（5209R/5210R: No, Yes, mod_ruid2, suPHP, FPM / 5211R: No, suPHP, FPM）
PHP バージョン（suPHP または FPM を使い、追加 PHP パッケージが入っている場合）
MySQL と、作成・管理を許可するデータベース数
ユーザー所有 /web ディレクトリの有効/無効
Shell Access（5209R: Yes/No、5210R/5211R: None, Chrooted (SFTP, SCP, RSYNC), Chrooted (Shell, SFTP, SCP, RSYNC), Full Shell Access）
Notes
GUI の SSL 利用
最大ユーザー数
Java Servlet Pages (JSP) の有効/無効
Server Side Includes (SSI)
Perl Scripts (CGI)
siteAdmin 以外の FTP 利用の有効/無効
siteAdmin 用メール転送の自動設定
サブドメイン
許可サブドメイン数

複数ホスティングパッケージを用意している場合、WHMCS 管理者や顧客はアップグレード/ダウングレードを行えます。その際、新しい設定が BlueOnyx サーバーへ送られ、対象アカウントへ反映されます。

BlueOnyx ベースの製品がクライアントに割り当てられている場合、WHMCS 管理 GUI の Client Profile では次のように見えます。

ここではディスク使用量や有効機能などの重要情報を一覧できます。ここからホスティングパッケージの suspend、unsuspend、terminate が可能で、別の BlueOnyx パッケージへ切り替えることもできます。関連するクライアント管理者アカウントのパスワード変更も行えます。中央の青い 'Login to Control Panel' ボタンは、そのパッケージが配置されている BlueOnyx の GUI へ直接ログインします。右側の同名ボタンは残念ながら正常動作しませんでした。

suPHP と FPM 利用時の補足: suPHP または FPM を有効にすると、自動作成される siteAdmin がその Vsite の /web フォルダの 'Web Owner' に自動設定されます。これにより、ユーザーはすぐに FTP で Web コンテンツをアップロードできます。後からホスティングパッケージ変更で suPHP や FPM を無効にした場合も、API 側で Web Ownership は自動補正されます。

サーバー状態:

WHMCS のサーバー一覧では、管理対象の BlueOnyx サーバーが Active Monitor の状態も報告します。

この情報は直近の Active Monitor 実行結果であり、最大 15 分程度古い可能性があります。

AM ステータスとして返る値は次のとおりです。

OK - すべての監視項目が緑
Fault - 1 つ以上の監視項目が黄
Problem - 1 つ以上の監視項目が赤
Unknown - ネットワークまたは API の問題で取得不能

詳細な API ドキュメント:

前書き:

BlueOnyx 向け API は、Chris Gebhardt 氏の VIRTBIZ Internet Services からの要望と、かなり大きな '賄賂' の末に実装されました。主目的は、WHMCS と連携し、WHMCS-BlueOnyx-5200R module for WHMCS を通じて共有ホスティングアカウントを自動プロビジョニングできるようにすることです。

とはいえ、この API は他のプロビジョニングソリューションでも使えます。必要なパラメータを正しく渡せば、自分で BlueOnyx サーバーを問い合わせ・管理する独自インターフェースを書くことも可能です。このガイドは、PHP の深い内部に潜らずにそれを実現するための概要を示します。

API の場所:

/usr/sausalito/ui/chorizo/ci/application/modules/base/api/controllers/apiindex.php (5209R)
/usr/sausalito/ui/chorizo/ci/application/modules/base/api/controllers/Apiindex.php (5210R)

PHP に慣れているなら、API の PHP スクリプト本体を直接読むのが早いです。十分に慣れているなら、'API documentation 終了、あとはソースを読んでください' でも済みますが、ここではもう少し実務的に整理します。

サポートされるリクエスト種別:

POST

POST 以外では意味のある応答は得られません。GET はサポートされていません。

サポートされるプロトコル:

HTTP via port 444
HTTPS via port 81

URL:

BlueOnyx 5209R/5210R/5211R:

https://<server-ip>:81/base/api/index
http://<server-ip>:444/base/api/index

認証:

key: 'login' - value: 'admin'
key: 'pass' - value: <サーバー管理者パスワード>

'admin' 以外の serverAdmin アカウントを使える可能性はありますが、完全には想定されていません。serverAdmin は通常の 'admin' より権限差がある場合があるためです。いずれにせよ API を使えるのは serverAdmin のみです。一般ユーザーや siteAdmin が API を使おうとすると、GUI の forbidden エラーページへリダイレクトされます。

API の応答:

success
各種エラーメッセージ

この API は饒舌ではありません。成功なら 'success'、失敗なら比較的ざっくりしたエラーメッセージを返します。丁寧に手を引いてどこが間違っているかを細かく教えてくれるタイプではありません。

サポートされる API 呼び出し:

API v1 が扱う主要アクションは、'create'、'changepass'、'suspend'、'unsuspend'、'destroy'、'modify'、'reboot'、'shutdown'、'statusdetailed'、'status' です。以下では、それぞれの用途と送るべきデータの考え方を整理します。

Sample 'create' transaction:

'POST' で送る内容は、'action=create'、'login'、'pass' に加え、'payload' と 'clientdetails' を JSON エンコードした配列として含む形式です。'payload' には producttype、ipaddr、domain、username、password、disk、users、auto_dns、jsp、php、mysql、cgi、ssi、bwlimit、ftp、userwebs、shell、subdomains、forwardemail、comments などの Vsite/アカウント設定を含めます。'clientdetails' には firstname、lastname、email などの顧客情報を入れます。

Sample 'changepass' transaction:

'POST' データには同様に 'action=changepass'、'login'、'pass'、そして JSON エンコードした 'payload' を含めます。payload には対象 Vsite/ユーザーの識別情報と新しいパスワードを含めます。

Sample 'suspend' transaction:

'POST' データには 'action=suspend'、'login'、'pass'、対象アカウントを示す payload を含めます。目的はホスティングアカウントの停止です。

Sample 'unsuspend' transaction:

'POST' データには 'action=unsuspend'、'login'、'pass'、対象アカウントを示す payload を含めます。停止済みアカウントを復旧するために使います。

Sample 'destroy' transaction:

'POST' データには 'action=destroy'、'login'、'pass'、対象 Vsite/ユーザー情報を含めます。これは Vsite、ユーザー、および関連データを削除する操作です。

Sample 'modify' transaction:

'POST' データの構造は 'create' とほぼ同じですが、'action' が 'modify' になります。既存アカウントの設定変更に使います。言い換えると、'create' の送信内容に近いデータを、更新トランザクションとして送る形です。

Sample 'reboot' transaction:

'POST' データには 'action=reboot'、'login'、'pass' を含めます。payload や JSON エンコードは不要です。

Sample 'shutdown' transaction:

'POST' データには 'action=shutdown'、'login'、'pass' を含めます。こちらも payload や JSON エンコードは不要です。

Sample 'statusdetailed' transaction:

'POST' データには 'action=statusdetailed'、'login'、'pass' を含めます。payload や JSON エンコードは不要です。成功/失敗だけではなく、サーバーの 'Active Monitor' 状態について詳細な最新サマリーを返します。

Sample 'status' transaction:

'POST' データには 'action=status'、'login'、'pass' を含めます。payload や JSON エンコードは不要です。返るのは、最新の 'Active Monitor' 状態を表す 'G'（green）、'Y'（yellow）、'R'（red）のいずれかです。

返り値について:

'statusdetailed' と 'status' を除くほとんどの関数は、成功であれば 'success'、失敗であれば何らかのエラーメッセージを返します。'statusdetailed' は詳細な Active Monitor レポートを、'status' は G/Y/R の状態コードを返します。

実際の WHMCS 運用では、この API を通じて共有ホスティングの作成、変更、停止、削除、パスワード更新、状態確認を一通り自動化できます。ただし、新規実装を始めるのであれば、互換性と保守性の面から API v2 への移行を強く推奨します。