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

第4章 WS-APIに公開されている追加ユーティリティ

コアOracle VM Managerの動作に直接関係しないユーティリティ・メソッドは、WebサービスAPI経由で利用可能な第2のエンドポイントを通じて公開されます。オラクルVMのWebサービスAPIのユーティリティはOracle VM Manager内の情報を取得するためおよび構成するか、特定のOracle VM Manager機能をトリガーするための両方の追加のメソッドを提供します。典型的な例には、どのOracle VM Serversが新しい「サーバー・プール」に追加できるかを判断すること、「ローカル記憶域」上にあるすべてのファイル・システムのリストを取得します。統計収集の頻度とその保存期間の構成に使用する統計収集属性の構成。バックアップ処理を開始します。

完全に実装されたRESTクライアントを提供するJavaの例がSDKに含まれています。これはcom.oracle.ovm.mgr.ws.clientで利用できます:

OvmWsRestUtilitiesClient.javaには、ユーティリティ・クライアントのREST実装のソース・コードが含まれています。

4.1 認証

Web Services Utilities APIへのRESTインタフェースの認証は、Oracle VM Manager REST APIに対する認証に使用されているのと同じ方法に従います。詳細については、3.2項、「認証方法」を参照してください。クライアントがすでに認証されている場合は、ユーティリティAPIにアクセスするために認証を再度実行する必要はありません。

ユーティリティAPIは、"/Utilities""をURIに追加することでアクセスできます。したがって、RESTインタフェースを介してユーティリティにアクセスするためのベースURIは次のとおりです:

https://hostname:port/ovm/core/wsapi/rest/Utilities

このURIでは、hostnameをOracle VM Managerのホスト名またはIPアドレスに置き換え、portをREST Webサービスが使用可能なポート番号に置き換えます - デフォルトは7002 (SSL)です。

4.2 ユーティリティのパスと例

Web Services Utilities APIへのRESTインタフェースに関して、APIによって公開されるさまざまなメソッドは、Oracle VM Managerとの機能的関係に基づいてグループ化され、別々のユーティリティを作成します。各ユーティリティは、そのユーティリティで使用可能なメソッドへのアクセスを提供するベースURIを超える独自の相対パスを持ちます。ユーティリティの相対パスと説明は以下のとおりです:

/ArchiveManagement: イベントおよびジョブ・ログのハウスキーピング・スケジュールを制御するユーティリティ
/BackupManagement: Oracle VM Managerバックアップ構成にアクセスし、オンデマンドでバックアップ操作を開始する機能を提供するユーティリティ
/BusinessManagement: コアAPIによって提供される機能を拡張するためのツールを提供するユーティリティ
/Certificate: 証明書ベース認証の証明書登録を管理するユーティリティ
/EventManagement: Oracle VM Manager内の内部イベントを管理するユーティリティ
/JobManagement: Oracle VM Manager内で実行中または完了したジョブを管理するユーティリティ
/LogManagement: ユーティリティを使用して、Javaパッケージ名で識別されるOVMソフトウェア・コンポーネントがシステム・ログ・ファイルに書き込むことができるランタイム選択と、書き込まれたメッセージの詳細レベルを制御します。
/MacManagement: VNICのMACアドレスの生成方法を制御するユーティリティ
/ModelManagement: 内部データベースのオブジェクトを表すためにOracle VM Managerが使用するデータ・モデルをリフレッシュおよびエクスポートするユーティリティ
/StatisticsManagement: 統計情報が収集される頻度やそれらの保存期間など、統計構成を制御するユーティリティ
/UserPreferenceManagement: Oracle VM Manager内の変数を管理するためのユーティリティ。アクセシビリティ設定など、Webベースのユーザー・インタフェース内のユーザー固有の設定を制御

各ユーティリティで使用できるメソッドについては、SDKに付属のマニュアルを参照してください。読者は、このドキュメンテーションを参照して、Web Services Utilities APIによって提供されるあらゆる機能を検出することをお勧めします。

SDKのOvmWsUtilitiesRestClient.javaで提供されるJavaサンプル・ソース・コードは、Jersey Bundleツールを使用してREST APIを通じて公開されるメソッドにアクセスする優れた例を提供します。下記の高度に切り詰められたサンプルでは、上で定義したさまざまなユーティリティ・パスが、各ユーティリティにアクセスするための正しいURIを構築するために組み合わせることができる文字列値として設定されていることが分かります:

...
public class OvmWsUtilitiesRestClient extends RestClient implements OvmWsUtilitiesClient
{
    private static final String ATTRIBUTES_PATH            = "attributes";

    private static final String UTILITIES_PATH             = "Utilities";
    private static final String BUSINESS_MANAGEMENT_PATH   = "BusinessManagement";
    private static final String STATISTICS_MANAGEMENT_PATH = "StatisticsManagement";
    private static final String STATISTICS_ATTRIBUTES_PATH = ATTRIBUTES_PATH;
    private static final String MAC_MANAGEMENT_PATH        = "MacManagement";
    private static final String MAC_ATTRIBUTES_PATH        = ATTRIBUTES_PATH;
    private static final String ARCHIVE_MANAGEMENT_PATH    = "ArchiveManagement";
    private static final String ARCHIVE_ATTRIBUTES_PATH    = ATTRIBUTES_PATH;
    private static final String BACKUP_MANAGEMENT_PATH     = "BackupManagement";
    private static final String BACKUP_ATTRIBUTES_PATH     = ATTRIBUTES_PATH;
    private static final String EVENT_MANAGEMENT_PATH      = "EventManagement";
    private static final String EVENT_ATTRIBUTES_PATH      = ATTRIBUTES_PATH;
    private static final String SVR_EVENT_ATTRIBUTES_PATH  = "serverAttributes";
    private static final String JOB_MANAGEMENT_PATH        = "JobManagement";
    private static final String JOB_ATTRIBUTES_PATH        = ATTRIBUTES_PATH;
    private static final String LOG_MANAGEMENT_PATH        = "LogManagement";
    private static final String LOG_LOGGERATTRIBUTES_PATH  = ATTRIBUTES_PATH;
    private static final String RAS_MANAGEMENT_PATH        = "RasManagement";
    private static final String MODEL_MANAGEMENT_PATH      = "ModelManagement";
    private static final String USER_PREFERENCE_PATH       = "UserPreference";

    private final URI           businessManagementURI;
    private final URI           backupManagementURI;
    private final URI           logManagementURI;
    private final URI           jobManagementURI;
    private final URI           modelManagementURI;

    public OvmWsUtilitiesRestClient(final RestClient parentClient)
    {
        super(parentClient, UTILITIES_PATH);

        businessManagementURI = UriBuilder.fromUri(getBaseURI()).segment(BUSINESS_MANAGEMENT_PATH).build();
        backupManagementURI = UriBuilder.fromUri(getBaseURI()).segment(BACKUP_MANAGEMENT_PATH).build();
        logManagementURI = UriBuilder.fromUri(getBaseURI()).segment(LOG_MANAGEMENT_PATH).build();

        jobManagementURI = UriBuilder.fromUri(getBaseURI()).segment(JOB_MANAGEMENT_PATH).build();
        modelManagementURI = UriBuilder.fromUri(getBaseURI()).segment(MODEL_MANAGEMENT_PATH).build();
    }

    @Override
    public BusinessSelection<EthernetPort> utilGetAvailableEthernetPorts(final Id<Server> serverId, 
               final Id<Network> networkId)
        throws WsException
    {
        try
        {
            final Map<String, Object> queryParameters = createQueryParameterMap("serverId", serverId.getValue());
            if (networkId != null)
            {
                queryParameters.put("networkId", networkId.getValue());
            }
            final Builder b =
                    getResourceFromUriAndPathElementsWithQueryParameters(businessManagementURI, queryParameters,
                                                                         "availableEthernetPorts");

            @SuppressWarnings("unchecked")
            final BusinessSelection<EthernetPort> ethernetPorts = b.get(BusinessSelection.class);

            return ethernetPorts;
        }
        catch (final UniformInterfaceException ex)
        {
            throw convertException(ex);
        }
    }

...
}

上記のコードには、utilGetAvailableEthernetPortsメソッドの定義例も含まれています。ここでは、このクラスはRestClientクラスを拡張しているため、Jersey Builderと組み合わせてgetResourceFromUriAndPathElementsWithQueryParametersメソッドを使用して、使用可能なイーサネット・ポートを返すHTTP GETリクエストを送信できることがわかります。

SDKに付属のドキュメントによれば、Javaコードから外挿すると、Pythonでこの例を簡単に複製できるはずです。以下に示すサンプルは、同様の問合せを作成するために必要なPythonコードの完全な例を示しています:

# import the requests library to handle HTTP requests and session maintenance
import requests
# import the json library for JSON translation (not required for this example)
import json

# instantiate a session object and populate it with authentication credentials
s=requests.Session()
s.auth=('user','password')
s.verify=False #disables SSL certificate verification
# configure the session to always use JSON
s.headers.update({'Accept': 'application/json', 'Content-Type': 'application/json'})

# set up a baseUri object to contain the URI to the Utilities API
baseUri='https://127.0.0.1:7002/ovm/core/wsapi/rest/Utilities'

# construct the URI according to the requirements set out in the documentation
uri='{base}/BusinessManagement/availableEthernetPorts'.format(
    base=baseUri)

# configure the query parameters
params={
    "serverId": "00:e0:81:4d:40:f5:00:e0:81:4d:40:be:00:e0:81:4d",
    "networkId": "0aac4c00"
}

# submit a get request to the uri and store the response
r=s.get(uri,params=params)
# use the requests library's native json parser to obtain a usable python object
availPorts=r.json()

4.3 RESTを使用した証明書ベースの認証のための証明書管理

ユーティリティAPIには、Oracle VM Manager内で証明書の生成と登録を管理するための一連のメソッドが用意されています。これは、WS-APIが証明書ベースの認証も可能にするため重要です。カスタム開発されたアプリケーションがOracle VM Managerを認証したり操作したりする方法をさらに安全にすることができます。この項では、これらのメソッドのいくつかをREST APIのコンテキストで簡単に説明します。

Oracle VM Manager内の証明書管理については、ドキュメント全体で様々な内容で説明しています。 RESTを使用したSSL証明書を使用した認証の詳細については、3.6.2項、「認証」を参照してください。 SSL証明書管理の詳細については、「Oracle VM管理者ガイド」の「SSLの設定」も参照してください。

4.3.1 RESTを使用してCA証明書を取得する方法

既存のSSL証明書を使用するか、HTTP基本認証メカニズムを使用して認証されると、ユーティリティAPIを問合せして、内部Oracle VM Manager CA証明書を取得することができます。これは、HTTP GETリクエストを次のURIに送信するだけで実現されます:

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate/CaCertificate

このメソッドは、単にCA証明書を文字列として返します。

CA証明書を取得して信頼できる証明書またはキーストアに追加すると、Oracle VM ManagerとのSSL相互作用の検証に使用することができます。

4.3.2 RESTを使用して証明書に署名して登録する方法

このAPIは、内部Oracle VM Manager CA証明書を使用してSSL証明書に署名して登録するオプションを提供します。同様に、証明書に署名するか、既に署名した証明書を登録するオプションもあります。これは、信頼できるサード・パーティのCA証明書をOracle VM Manager独自のキーストアに追加し、そのサード・パーティが発行した証明書を使用する場合に便利です。これらの追加のAPIメソッドについては、APIのドキュメントで説明しています。この場合、証明書を内部CAに署名して登録する必要があると想定します。

REST APIを使用すると、次のURIにPOSTリクエストを送信して証明書に署名して登録できます:

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate

POSTリクエストの本文には、loginCertificateオブジェクトのJSONまたはXML表現を含めることができます。オブジェクトの証明書要素のみを移入する必要があります。 POSTリクエスト内でオブジェクトが送信されない場合、APIは認証に使用できる証明書とパスフレーズのないキーを自動的に生成します。セキュリティ上の理由から、通常証明書をローカルで生成し、キーのパスフレーズをあらかじめ設定しておくと、証明書をリクエスト本文に渡すことができます。

重要

デフォルトでは、APIは、このURIに送信されたPOSTリクエストの本文で送信された証明書のみを登録します。これは、すでに第三者によって署名された証明書を使用する可能性を可能にするためです。 APIがこのメソッドを使用して送信された証明書にも署名するようにするには、boolean signパラメータもURI内でtrueに設定する必要があります。したがって、この場合、URIに投稿する必要があります:

https://hostname:port/ovm/core/wsapi/rest/Utilities/Certificate?sign=True

証明書に署名する例は、JavaとPythonでこれを行う方法を示すために、以下に提供されています。

Java

最初にキーと証明書を作成します。 Javaを使用している場合は、Javaのkeytoolコマンドを使用してキーストアを生成することでこれを行うことになります:

$ keytool -genkey

キーストアと証明書を設定したら、keytoolを使用して証明書をPEM形式でエクスポートして、署名用に使用できます:

$ keytool -export -rfc

Webサービス・クライアントでは、新しいLoginCertificateオブジェクトを作成し、新しい証明書を証明書フィールドに配置する必要があります。次に例を示します。

LoginCertificate cert = new LoginCertificate();
cert.setCertificate("-----BEGIN CERTIFICATE-----" +
    "MIIDTzCCAw2gAwIBAgIEIIUUWjALBgcqhkjOOAQDBQAweTELMAkGA1UEBhMCVVMxCzAJBgNVBAgT" +
    "AkNBMRUwEwYDVQQHEwxSZWR3b29kIENpdHkxDzANBgNVBAoTBk9yYWNsZTEaMBgGA1UECxMRT3Jh" +
    "Y2xlIFZNIE1hbmFnZXIxGTAXBgNVBAMTEENlcnRpZmljYXRlIERlbW8wHhcNMTMwODIxMTYzOTUz" +
    "WhcNMTMxMTE5MTYzOTUzWjB5MQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFTATBgNVBAcTDFJl" +
    "ZHdvb2QgQ2l0eTEPMA0GA1UEChMGT3JhY2xlMRowGAYDVQQLExFPcmFjbGUgVk0gTWFuYWdlcjEZ" +
    "MBcGA1UEAxMQQ2VydGlmaWNhdGUgRGVtbzCCAbgwggEsBgcqhkjOOAQBMIIBHwKBgQD9f1OBHXUS" +
    "KVLfSpwu7OTn9hG3UjzvRADDHj+AtlEmaUVdQCJR+1k9jVj6v8X1ujD2y5tVbNeBO4AdNG/yZmC3" +
    "a5lQpaSfn+gEexAiwk+7qdf+t8Yb+DtX58aophUPBPuD9tPFHsMCNVQTWhaRMvZ1864rYdcq7/Ii" +
    "Axmd0UgBxwIVAJdgUI8VIwvMspK5gqLrhAvwWBz1AoGBAPfhoIXWmz3ey7yrXDa4V7l5lK+7+jrq" +
    "gvlXTAs9B4JnUVlXjrrUWU/mcQcQgYC0SRZxI+hMKBYTt88JMozIpuE8FnqLVHyNKOCjrh4rs6Z1" +
    "k$ keytool -import -file newcertW6jfwv6ITVi8ftiegEkO8yk8b6oUZCJqIPf4VrlnwaSi" +
    "6bc9ozDyK1cgNyZWl4kq1efzjsyolIr1i4CiM/MqnEZO43hVVtXex3V+VWd9i/CLn0I/ZC9Lfi5X" +
    "HlQOEzWKK/esvf64Mv96DbZna/XRj6JhTEPGoStizNhXrVJCF4DaiIP+l53qYKJEtrNoR+tToRt8" +
    "OimE3PzLCXILvwwaCaMhMB8wHQYDVR0OBBYEFAtyjCpfkznpsUf2Lj8iBmRS3/0oMAsGByqGSM44" +
    "BAMFAAMvADAsAhRTm5NW8HDcM8jG5a7QIowNLN+fEQIUZXMogTvKbcXu6NN6fh0KY09hokI=" +
    "-----END CERTIFICATE-----");

証明書に署名して登録するメソッドを呼び出すことができます。これにより、証明書の署名付きバージョンが返されます:

LoginCertificate signed = ovmUtil.certificateSignAndRegister(cert);
System.out.println(signed.getCertificate());

返される出力には、新しく署名された証明書が含まれます。この出力をファイルにダンプすると、新しく署名された証明書をキーストアにインポートすることができます:

$ keytool -import -file newcert

証明書を検証できるように、CA証明書をキーストアにインポートする必要があります。新しく署名された証明書とキーを上書きしないように、CA証明書をキーストアにインポートするときは別の別名を使用してください。

Python

Pythonアプリケーションで使用するためにローカルでキーと証明書を生成するには、OpenSSLのようなツールを使用します。

$ openssl genrsa -des3 -out mykey.pem 2048
$ openssl req -new -key mykey.pem -out mycertreq.csr
$ openssl x509 -req -days 365 -in mycertreq.csr -signkey mykey.pem -out mycert.pem

セキュリティ上の理由から、キーのパスフレーズを設定することをお勧めします。これは典型的な自己署名証明書であることに注意してください。最初にCSR (Certificate Signing Request)を生成し、このCSRから生成する証明書に署名するためにキーを使用します。

証明書を作成したら、REST APIを使用して証明書に署名することができます。 Pythonでは、すでにリクエスト・セッションを設定し、3.6.2.2項、「Python」で説明されているように認証されていることを前提として、次のコードを使用できます:

cert=open('/path/to/mycert.pem').read()
body={'certificate': cert}
r=s.post('https://127.0.0.1:7002/ovm/core/wsapi/rest/Utilities/Certificate?sign=True',
          data=json.dumps(body))
signed_cert=r.json()['certificate']
f=open('/path/to/signed.pem','w')
f.write(signed_cert)
f.close()

上記の例では、自己署名証明書の内容を'cert'という名前の変数に読み込み、これを使用してPythonのデータ構造を作成し、APIが本文で想定しているコンテンツと同様のJSON文字列に変換することができますリクエストの。 POSTリクエストを送信し、URIのsignパラメータをTrueに設定します。新しく署名された証明書をレスポンス本文から抽出し、その内容を/path/to/signed.pemのファイルに書き込みます。

この証明書を使用してPythonを使用してREST APIを認証するには、その証明書をそのキーと組み合わせる必要があります。これはコマンドラインで簡単に行うことができます:

$ cat /path/to/signed.pem /path/to/mykey.pem >> /path/to/OVMSignedCertificate.pem

3.6.2.2項、「Python」で説明されているように、この新しい証明書を使用して、任意のプログラム内からREST APIに対して認証することができます。