JBoss AS7 – Admin Guide – Management Clients
AS7 はサーバの設定、管理のための以下 3 つのアプローチを用意しています。
- web インターフェース( web コンソール)
- コマンドラインインターフェース( CLI )
- XML
上記のどのアプローチを使って設定の更新を行った場合でも、設定値はアプローチ間で同期され最終的には XML ファイルに永続化されます。
Web Management Interface
web インターフェースは、GWT アプリケーションです。このアプリケーションは、HTTP 管理 API を使用して domain および standalone サーバの管理設定を行います。
HTTP Management Endpoint
HTTP API は HTTP プロトコルを使用し AS7 の管理レイヤ に管理クライアントが接続するためのエントリポイントです。管理レイヤは JSON フォーマットを使用した RPC スタイルの API を使用して domain または standalone サーバへの管理オペレーション(設定値の照会や更新等)を提供します。 HTTP API は web コンソールから使用されますが、独自のクライアントを作成し統合することも可能です。
HTTP API は domain コントローラあるいは standalone サーバ共に同じ場所に配置され、デフォルトでは 9990 ポートで稼働します。以下のインターフェース設定を参照して下さい。
<management-interfaces>
[…]
<http-interface interface=”management” port=”9990“/>
<management-interfaces>
( standalone/configuration/standalone.xml または domain/configuration/host.xml を参照して下さい。)
HTTP API は 2 つの異なるコンテキストを提供します。 1 つは管理オペレーション実行用で、もう一方は web インターフェース(コンソール)用となります。次を参照して下さい。
- Domain API: http://<host>:9990/management
- Web Console: http://<host>:9990/console
Accessing the web console
web コンソールは HTTP API と同様のポートを通して提供されます。 web コンソールはブラウザから以下の URL にアクセスすることで使用可能です。
- http://<host>:9990/console
デフォルト URL
デフォルトでは web コンソールは http://localhost:9990/console からアクセス可能です。
Securing the web console
web コンソールは HTTP API を使用してサーバと通信を行います。 web コンソールのセキュア化やデフォルトのセキュリティレルムの有効化についてはこのガイドの次の章(”Securing the Management Interfaces“)を参照して下さい。
Command Line Interface
コマンドラインインターフェース( CLI )は domain あるいは standalone サーバの管理ツールです。 CLI により domain コントローラあるいは standalone サーバにアクセスし管理オペレーションを行うことが可能です。
Native Management Endpoint
ネイティブ API は AS ネイティブなプロトコルを使用し AS7 の管理レイヤに管理クライアントが接続するためのエントリポイントです。管理レイヤはバイナリプロトコルを使用した RPC スタイルの API を使用して domain または standalone サーバへの管理オペレーション(設定値の照会や更新等)を提供します。 ネイティブ API は CLI( Command Line Interface )から使用されますが、独自のクライアントを作成し統合することも可能です。
ネイティブ API はホストコントローラもしくは standalone サーバのプロセスで稼働し CLI を使う場合は有効化する必要があります。デフォルトでは 9999 で稼働します。
以下は standalon.xml または host.xml 中の ネイティブ API インターフェースの設定例です。
<management-interfaces>
<native-interface interface=”management” port=”9999“/>
[…]
<management-interfaces>
( standalone/configuration.xml または domain/configuration/host.xml を参照して下さい。)
Running the CLI
AS7 を稼働させる環境毎に $JBOSS_HOME/bin 中の jboss-admin.sh もしくは jboss-admin.bat を使用して CLI を起動します。ディレクトリ構成に関するより詳細な情報については “Getting Started Guide” を参照して下さい。
CLI を起動したら以下の例を参考に connect コマンドを使用して JBoss AS7 インスタンスに接続してみましょう。
./bin/jboss-admin.sh
You are disconnected at the moment. Type ‘connect’ to connect to the server or ‘help’ for the list of supported commands.
[disconnected /]
[disconnected /] connect
Connected to domain controller at localhost:9999
[domain@localhost:9999 /] quit
Closed connection to localhost:9999
ネイティブ API はデフォルトで localhost:9999 で稼働します。
localhost:9999 をサーバがリスンしていない場合、ホスト/ポートがオプションパラメータで定義されています。
以下の例では 192.168.0.1:9999 で稼働しているホストコントローラに CLI から接続しています。
./bin/jboss-admin.sh
You are disconnected at the moment. Type ‘connect’ to connect to the server
[disconnected /] connect 192.168.0.10:9999
Connected to standalone controller at 192.168.0.1:9999
9999 ポートは CLI がデフォルトで使用するものであって、 AS7 の動作環境において必須のポートではありません。他のポートをネイティブ API 用ポートとしてリスンさせる場合はインターフェース設定を変更して下さい。
CLI セッション(接続)を終了するには quit コマンドを実行して下さい。
jboss-admin スクリプトは ./jboss-admin.sh –connect のように –connect パラメータを使用することが可能です。
–controller パラメータはネイティブ API が稼働するホスト/ポートを ./jboss-admin.sh –connect –controller=192.168.0.1:9999 のように指定することが可能です。
CLI は以下のヘルプが使用可能です。
[domain@localhost:9999 /] help
Supported commands:
cn (or cd) – カレントノードを引数で指定されたものに変更します。
connect – 指定されたホスト/ポートに接続します。
deploy – アプリケーションのデプロイを行います。
help (or h) – ヘルプメッセージを表示します。
history – コマンド履歴の表示/無効化/有効化/クリアを行います。
ls – 指定されたノードに含まれるコンテンツ(リソース)の一覧を表示します。
pwn (or pwd) – カレントノードを表示します。
quit (or q) – CLI を終了します。
undeploy – アプリケーションのアンデプロイを行います。
version – バージョンおよび環境情報( OS, JDK 等)を表示します。
add-jms-queue – JMS キューを作成します。
remove-jms-queue – JMS キューを削除します。
add-jms-topic – JMS トピックを作成します。
remove-jms-topic – JMS トピックを削除します。
add-jms-cf – JMS コネクションファクトリを作成します。
remove-jms-cf – JMS コネクションファクトリを削除します。
data-source – データソースの作成、変更、削除を行います。
xa-data-source – XA データソースの作成、変更、削除を行います。
各々のコマンドの詳細については $command –help を参照して下さい。
Operation Requests
オペレーションリクエストにより AS7 の管理モデルの検索、参照、変更、削除が可能です。オペレーションリクエストは create-jms-queue 等の抽象度の高いコマンドとは異なり、 XML 設定ファイルを直接編集するのと同じようにサーバ設定の照会、編集が可能です。
オペレーションリクエストにおける設定モデルはツリー形式でアドレス指定可能なリソース(ノード)という単位で表現されます。各々のリソース(ノード)は実行可能なオペレーション(属性の照会、変更等)のセットを提供します。
オペレーションリクエストは基本的に アドレス、オペレーション名、オペレーションパラメータ(オプション) の 3 つのパートから構成されます。
オペレーションリクエストの指定形式は次の通りです。
[/node-type=node-name (/node-type=node-name)*] : operation-name [( [parameter-name=parameter-value (,parameter-name=parameter-value)*] )]
オペレーションリクエストの使用例は以下の通りです。
/profile=production/subsystem=threads/bounded-queue-thread-pool=pool1:write-core-threads (count=0, per-cpu=20)
タブ補完
タブ補完は node-type, node-name, operation-name, parameter-name 全てのコマンドとオプションでサポートされます。また、冗長性を軽減し利便性を向上させるためのエイリアスの導入についても検討中です。
オペレーションリクエストにおける空白文字は無視されます。
Addressing resources
オペレーションリクエストではアドレスが省略可能な場合があります。以下の例ではカレントノードに対して :read-resource オペレーションを実行しリソースの照会を行っています。
:read-resource
コマンドとオペレーション間の文法的なあいまいさを排除するために、オペレーションは次のアドレス指定(絶対パス/相対パス)のいずれかを必要とします。
カレントノードに対してオペレーションを実行する例は以下の通りです。
cd subsystem=web
:read-resource(recursive=”true”)
カレントノードの子ノードに対してオペレーションを実行する例は以下の通りです。
cd subsystem=web
./connector=http:read-resource
ルートノードに対してオペレーションを実行する例は以下の通りです。
/subsystem=threads:read-resource
Available Operation Types and Descriptions
オペレーションのタイプは、全てのノードに対して実行可能な共通オペレーションと subsystem 等の特定のノードに対してのみ実行可能な固有オペレーションに分けられます。共通オペレーションは以下の通りです。
- add
- read-attribute
- read-children-names
- read-children-resources
- read-children-types
- read-operation-description
- read-operation-names
- read-resource
- read-resource-description
- remove
- validate-address
- write-attribute
logging サブシステム等の特定のノードで実行可能なオペレーションのリストは対象ノードに対して :read-operation-names オペレーションを実行することで照会可能です。以下の例では logging リソースのオペレーションリストを照会しています。
[[standalone@localhost:9999 /] /subsystem=logging:read-operation-names
{
“outcome” => “success”,
“result” => [
“add”,
“change-root-log-level”,
“read-attribute”,
“read-children-names”,
“read-children-resources”,
“read-children-types”,
“read-operation-description”,
“read-operation-names”,
“read-resource”,
“read-resource-description”,
“remove-root-logger”,
“root-logger-assign-handler”,
“root-logger-unassign-handler”,
“set-root-logger”,
“validate-address”,
“write-attribute”
]
}
このリストに見られるように、 logging リソースは、root-logger-assign-handler, root-logger-unassign-handler , set-root-logger and remove-root-logger の 4 つの追加オペレーションを提供しています。
リソースまたはオペレーションに関するより詳しい解説は :read-operation-description により取得できます。
[standalone@localhost:9999 /] /subsystem=logging:read-operation-description(name=change-root-log-level)
{“outcome” => “success”,
“result” =>{
“operation-name” => “change-root-log-level”,
“description” => “Change the root logger level.”,
“request-properties” => {“level” => {
“type” => STRING,
“description” => “The log level specifying which message levels will be logged by this logger.
Message levels lower than this value will be discarded.”,
“required” => true
}}
}
}
Full model
リソースおよびその子リソースの全てを照会するには :read-resource(recursive=true) を実行して下さい。
Command History
コマンドとオペレーションリクエストの履歴はデフォルトの状態で照会可能です。コマンド履歴はメモリとファイルの両方に保持され、 CLI セッション中は保管されます。履歴のファイル名は .jboss-cli-history でホームディレクトリに自動作成されます。 CLI は起動時に履歴ファイルを詠込み、その内容をメモリ上に展開します。
CLI セッション中は矢印キーを使用してコマンド履歴の前後を辿ることが可能です。
履歴を操作するには history コマンドを使用します。引数無しで同コマンドを実行すると、メモリ上に保持されている全ての履歴(履歴保持件数の最大値のデフォルトは 500 )を表示します。
history コマンドは以下 3 つのオプション引数をサポートします。
- disable – 履歴の記録を無効化しますが、既存の履歴は破棄しません。
- enabled – 履歴の記録を有効化します。(履歴の記録が無効化される前に最後に記録されたコマンドの次に以降のコマンドは記録されます。)
- clear – メモリ上の履歴を破棄します。(ファイル上の履歴は破棄されません)
Batch Processing
バッチモードを使用すると、複数のコマンドやオペレーションをアトミックな処理として実行することが可能です。バッチ中でコマンドあるいはオペレーションの実行が 1 つでも失敗すると、他の全ての成功した処理はロールバックされます。
全てのコマンドがバッチで使用可能ではありません。例えば、 cd, ls, help 等のコマンドはオペレーションリクエストに変換されないためバッチ中で使用できません。オペレーションリクエストに変換されるコマンドのみがバッチ中で使用可能です。実際、バッチはオペレーションリクエストの合成として実行されます。
バッチモードへは batch コマンドを実行することにより移行します。
[standalone@localhost:9999 /] batch
[standalone@localhost:9999 / #] /subsystem=datasources/data-source=”java\:\/H2DS”:enable
[standalone@localhost:9999 / #] /subsystem=messaging/jms-queue=”newQueue”:add
run-batch コマンドを実行することによりバッチの実行が可能です。
[standalone@localhost:9999 / #] run-batch
The batch executed successfully.
バッチへの更新を保持したまたバッチ編集モードを終了するには以下のように holdback-batch コマンドを実行して下さい。
[standalone@localhost:9999 / #] holdback-batch
[standalone@localhost:9999 /]
バッチ編集を再開するには以下のように batch コマンドを実行します。
[standalone@localhost:9999 /] batch
Re-activated batch
#1 /subsystem=datasources/data-source=java:/H2DS:\/H2DS:enable
上記以外の主要なバッチコマンドは以下の通りです。
- clear-batch
- edit-batch-line (例 edit-batch line 3 create-jms-topic name=mytopic)
- remove-batch-line (例 remove-batch-line 3)
- move-batch-line (例 move-batch-line 3 1)
- discard-batch
Configuration Files
domain および standalone サーバの XML 設定ファイルは以下のように configuration ディレクトリに配置されています。
- domain/configuration/domain.xml
- domain/configuration/host.xml
- standalone/configuration/standalone.xml
domain 設定には domain 全体に対する設定( domain.xml )と domain に参加する各々のホスト対する設定( host.xml )の 2 つの異なる設定のタイプがあります。domain セットアップ方法の詳細説明は “Domain Setup” を参照して下さい。
設定は XML ファイルにより 一元管理されます。 web コンソールや CLI を通して行われた設定変更は XML ファイルに永続化されます。 domain/standalone サーバがオフラインの場合でも XML ファイルでの設定変更は可能で、変更は domain/standalone サーバの次回起動時に反映されます。しかし、 XML の直接編集よりも web インターフェースまたは CLI の使用を推奨します。 AS7 プロセス稼働中に行われた外部からの設定変更は反映せれませんしこれらのツールで行った編集に上書きされる可能性があります。