JBoss AS7 – Admin Guide – Management tasks – Subsystem configuration – JMX subsystem configuration

JMX subsystem configuration

リモーティングエンドポイントに JMX サブシステムのサービスが登録されているため Remoting connector 経由での JMX アクセスが可能です。 

standalone モードではデフォルトで 9999 ポートでの JMX アクセスが可能ですが domain モードでは Remoting connector の有効化が必要です。 

下記のように service:jmx URL を使用した標準的な方法で Remoting connector にアクセスすることが可能です。

import javax.management.MBeanServerConnection;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
 
public class JMXExample {
 
    public static void main(String[] args) throws Exception {
        //Get a connection to the JBoss AS MBean server on localhost
        String host = “localhost”;
        int port = 9999;  // management-native port
        String urlString =
            System.getProperty(“jmx.service.url”,”service:jmx:remoting-jmx://” + host + “:” + port);
        JMXServiceURL serviceURL = new JMXServiceURL(urlString);
        JMXConnector jmxConnector = JMXConnectorFactory.connect(serviceURL, null);
        MBeanServerConnection connection = jmxConnector.getMBeanServerConnection();
 
        //Invoke on the JBoss AS MBean server
        int count = connection.getMBeanCount();
        System.out.println(count);
        jmxConnector.close();
    }
}

上記のサンプルを実行するには下記のスクリプトで行っているようにクラスパスを設定する必要があります。

!/bin/bash
# specify your AS7 folder
export YOUR_AS7_HOME=~/as7
java -classpath $YOUR_AS7_HOME/bin/client/jboss-client.jar:./ JMXExample

また、 jconsole を使用して接続することも可能です。

 jconsole を使う場合 $JBOSS_HOME/bin 中の jconsole.sh もしくは jconsole.bat スクリプトを使用するとリモート接続に必要なライブラリをクラスパスに設定可能です。

 

上記のコードを以下の観点で改良したものが https://github.com/duke4j/java/tree/master/jmx に置いてあります。

  • JMX 接続時の認証情報(管理者名/パスワード)の設定
  • JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES の設定
  • Maven でビルドできるようにしたい!
  • ちょっとだけ MBean をみてみよう!

コードはこんな感じ。

import java.util.HashMap;
import java.util.Map;
import javax.management.MBeanInfo;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
public class Main {

    public static void main(String[] args) throws Exception {
        String urlString = “service:jmx:remoting-jmx://”
                + System.getProperty(“jmx.service.url”, “localhost:9999”);

        String[] credentials = {
                System.getProperty(“jboss.admin.name”, “admin”),
                System.getProperty(“jboss.admin.password”, “jboss”) };

        String[] objectNames = {
                System.getProperty(“jmx.object.name0”,
                        “jboss.msc:type=container,name=jboss-as”),
                System.getProperty(“jmx.object.name1”,
                        “jboss.as:subsystem=datasources,jdbc-driver=h2”),
                System.getProperty(“jmx.object.name2”,
                        “jboss.modules:type=ModuleLoader,name=ServiceModuleLoader-5”) };
        Map<String, Object> env = new HashMap<String, Object>();
        env.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES,
                “org.jboss.remotingjmx.RemotingConnectorProvider”);
        env.put(JMXConnector.CREDENTIALS, credentials);

        JMXServiceURL serviceURL = new JMXServiceURL(urlString);
        JMXConnector jmxConnector = JMXConnectorFactory
                .connect(serviceURL, env);
        try {
            MBeanServerConnection connection = jmxConnector
                    .getMBeanServerConnection();
            int count = connection.getMBeanCount();
            System.out.println(“A long time ago in a galaxy far, far away…. “
                    + count + ” MBeans on the AS7….”);
            for (String objectName : objectNames) {
                MBeanInfo beanInfo = connection.getMBeanInfo(new ObjectName(
                        objectName));
                System.out.println(beanInfo);
            }
        } finally {
            jmxConnector.close();
        }
    }
}

Connecting JMX on JBoss AS7 – 1

今回は JMX 経由で JBoss AS7 に接続してみよう!のエントリです。

JMX connector (JSR-160 connector) on JBoss AS7

CLI の接続先となる AS7 の Native I/F (デフォルトでは 9999 ポートを使用します。) は JBoss Remoting (Remoting Connector)により実装されています。JBoss Remoting は JSR-160 に準拠しているため、 Native I/F 経由の JMX のリモートアクセスが可能です。

JBoss Remoting の起動は AS7 の起動ログの以下の部分から確認できます。

01:46:42,899 INFO  [org.jboss.as.remoting] (MSC service thread 1-10) JBAS017100: Listening on 127.0.0.1:9999
01:46:42,899 INFO  [org.jboss.as.remoting] (MSC service thread 1-15) JBAS017100: Listening on 127.0.0.1:4447

前者のログは管理用の Native I/F で後者のログはリモート EJB で使用されるポートになります。

※ JSR-160 は JMX によるリモート管理・監視のための API 仕様です。

※ JSR-160 準拠のコネクタが実装されているのは JBoss AS 7.1.0.Final 以降のリリースです。

Using jconsole to connect to JMX on JBoss AS7

jconsole を使用して AS7 上の JMX connector に接続する場合 $JBOSS_HOME/bin/jconsole.sh を使用しましょう。 jconsole.sh は jconsole をラッピングするスクリプトで、 CLASSPATH に JBoss Remoting 等のライブラリを設定しています。

$JBOSS_HOME/bin/jconsole.sh を使用して jconsole を起動するとウィンドウ中に CLI GUI が表示されます。 を起動すると jconsole ウィンドウ中に CLI GUI が表示されます。

ローカルで起動する AS7 への JConsole 接続手順は以下の通り。

※ 下記の手順はローカル接続の手順になります。リモート接続を行う場合は “Remote Process” に service:jmx:remoting-jmx://{host_name}:{port}  を設定しましょう。

1. $JBOSS_HOME/bin/jconsole.sh の実行
2. JConsole : New Connection 画面にて AS7 プロセス (jboss-module.jar) を選択し Connect ボタンをクリック

JConsole: New Connection

3. 以下の jconsole 画面が表示されます。

Java Monitering & Management Console

CLI GUI では Command Builder 画面で特定のリソースを参照・変更する

際の CLI コマンドが画面上部 (cmd>) に出力されます。下図の例では web サブシステムの http コネクタの max-connections を 500 に設定しています。

CLI GUI - selecting write/attribute context menu

CLI GUI - writing attribute

CLI GUI - cmd

JBoss AS 7 Admin Guide – Management tasks – Interfaces and ports

Interface declarations 

AS7 は名前付きインターフェースを使用し、論理名を与えられたインターフェースは設定 (ファイル) 内で参照されます。 

ネットワークインターフェースは論理名と物理インターフェースへのクライテリアにより宣言されます。:

[standalone@localhost:9999 /] :read-children-resources(child-type=interface)
{
    “outcome” => “success”,
    “result” => {
         “management” => {
            “any” => undefined,
            “any-address” => undefined,
            “any-ipv4-address” => undefined,
            “any-ipv6-address” => undefined,
            “inet-address” => expression “${jboss.bind.address.management:127.0.0.1}”,
            “link-local-address” => undefined,
            “loopback” => undefined,
            “loopback-address” => undefined,
            “multicast” => undefined,
            “name” => “management”,
            “nic” => undefined,
            “nic-match” => undefined,
            “not” => undefined,
            “point-to-point” => undefined,
            “public-address” => undefined,
            “site-local-address” => undefined,
            “subnet-match” => undefined,
            “up” => undefined,
            “virtual” => undefined
         },
         “public” => {
            “any” => undefined,
            “any-address” => undefined,
            “any-ipv4-address” => undefined,
            “any-ipv6-address” => undefined,
            “inet-address” => expression “${jboss.bind.address:127.0.0.1}”,
            “link-local-address” => undefined,
            “loopback” => undefined,
            “loopback-address” => undefined,
            “multicast” => undefined,
            “name” => “public”,
            “nic” => undefined,
            “nic-match” => undefined,
            “not” => undefined,
            “point-to-point” => undefined,
            “public-address” => undefined,
            “site-local-address” => undefined,
            “subnet-match” => undefined,
            “up” => undefined,
            “virtual” => undefined
         },
         “unsecure” => {
            “any” => undefined,
            “any-address” => undefined,
            “any-ipv4-address” => undefined,
            “any-ipv6-address” => undefined,
            “inet-address” => expression “${jboss.bind.address.unsecure:127.0.0.1}”,
            “link-local-address” => undefined,
            “loopback” => undefined,
            “loopback-address” => undefined,
            “multicast” => undefined,
            “name” => “unsecure”,
            “nic” => undefined,
            “nic-match” => undefined,
            “not” => undefined,
            “point-to-point” => undefined,
            “public-address” => undefined,
            “site-local-address” => undefined,
            “subnet-match” => undefined,
            “up” => undefined,
            “virtual” => undefined
         }
      }
}

これは 2 つのインターフェースを宣言することを意味しています。 1 つは “management” として参照され、他方は “public” として参照されます。

“management” インターフェースは管理レイヤから必要とされる全てのコンポーネントやサービス( HTTP I/F, Native  管理 I/F )から使用されます。

[standalone@localhost:9999 /] /core-service=management:read-children-resources(child-type=management-interface)
{
    “outcome” => “success”,
    “result” => {
         “http-interface” => {
             “console-enabled” => true,
             “interface” => undefined,
             “port” => undefined,
             “secure-port” => undefined,
             “secure-socket-binding” => undefined,
             “security-realm” => “ManagementRealm”,
             “socket-binding” => “management-http”
         },
         “native-interface” => {
             “interface” => undefined,
             “port” => undefined,
             “security-realm” => “ManagementRealm”,
             “socket-binding” => “management-native”
         }
    }
}

“public” インターフェースはネットワーク通信に関連するいくつかのアプリケーション( Web, Messaging 等)から使用されます。

これらの名前は特別なものではなく、インターフェースはどんな名前でも宣言可能です。設定ファイルの他のセクションはこれらのインターフェースの(物理的な)全ての詳細を含むよりも論理名で参照します(管理ドメイン内の server は別のマシンで動作する可能性があります)。

domain.xml, host.xml, standalone.xml の設定ファイルは全てインターフェースを宣言可能なセクションを含みます。

インターフェースに関する XML 宣言を見ると、いくつかのインターフェース/アドレスの指定にいくつかの記述方式があることが分ります。

記述方式には 2 つのタイプがあり、単一の要素を用いてインターフェースをワイルドカードアドレスにバインドする方式 または、 1 つ以上の特徴を指定してインターフェースもしくはアドレスを完全にマッチさせる方式です。

次のサンプルでは各々のインターフェースに特定の IP アドレスを指定しています。:

<interfaces>
    <interface name=”management“>
        <inet-address value=”127.0.0.1″/>
    </interface>
    <interface name=”public“>
        <inet-address value=”127.0.0.1″/>
    </interface>
</interfaces>

他の指定方式は以下の通りです。:

<interface name=”global”>
    <!– ワイルドカードアドレスの使用 –>
    <any-address/>
</interface>
<interface name=”ipv4-global”>
    <!– IPv4 ワイルドカードアドレスの使用 –>
    <any-ipv4-address/>
</interface>
<interface name=”ipv6-global”>
    <!– IPv6 ワイルドカードアドレスの使用 –>
    <any-ipv6-address/>
</interface>
<interface name=”external”>
    <nic name=”eth0″/>
</interface>
<interface name=”default”>
    <!– 指定されたサブネットの全てのアドレスにマッチします。ポイント・ツー・ポイントではなくマルチキャストをサポートします。 –>
    <subnet-match value=”192.168.0.0/16″/>
    <up/>
    <multicast/>
    <not>
        <point-to-point/>
    </not>
</interface>

Socket Binding Groups

AS7 におけるソケット設定はインターフェース宣言に似ています。ソケットは論理名を使用して宣言され、論理名は他の設定から参照されます。

ソケットの宣言は特定の名前でグルーピング(ソケットバインディンググループ)されます。これによりサーバグループ(ドメイン管理)を設定する際に特定のソケットバインディンググループを容易に参照することができます。

ソケットバインディンググループは論理名を使用してインターフェースを参照します。

<socket-binding-group name=”standard-sockets” default-interface=”public”>
    <socket-binding name=”jndi”port=”1099″/>
    <socket-binding name=”jmx-connector-registry”port=”1090″/>
    <socket-binding name=”jmx-connector-server”port=”1091″/>
    <socket-binding name=”http”port=”8080″/>
    <socket-binding name=”https”port=”8443″/>
    <socket-binding name=”jacorb”port=”3528″/>
    <socket-binding name=”jacorb-ssl”port=”3529″/>
    <socket-binding name=”osgi-http”port=”8090″/>
    <socket-binding name=”remoting”port=”4447″/>
    <socket-binding name=”txn-recovery-environment”port=”4712″/>
    <socket-binding name=”txn-status-manager”port=”4713″/>
    <socket-binding name=”messaging”port=”5445″/>
    <socket-binding name=”messaging-throughput”port=”5455″/>
</socket-binding-group>

ソケットバインディングは以下の情報を含みます:

  • name – 他の設定から参照する際に使用されるソケット設定の論理名
  • port – この設定をベースにしたソケットがバインドされるベース(基本)ポート番号( server はこのベースポート番号を上書きできることに注意して下さい。)
  • interface (optional) – この設定をベースにしたソケットがバインドされるインターフェースの論理名
  • multicast-address (optional) – ソケットがマルチキャストに使用される場合のマルチキャストアドレス
  • multicast-port (optional) – ソケットがマルチキャストに使用される場合のマルチキャストポート番号
  • fixed-port (optional, defaults to false) – true の場合、指定されたソケット番号を必ず使用し上書きさせないことを宣言します。

IPv4 versus IPv6

AS7 は IPv4 と IPv6 の両アドレスをサポートします。デフォルトでは IPv4 を使用した設定が有効化されるため IPv4 ネットワーク上で AS7 を稼働させる場合、設定変更は不要です。AS7 を IPv6 ネットワークで稼働させる場合、JVM ネットワークプロパティの変更と設定ファイル中 (standalone.xml もしくは domain.xml) の IP アドレス値の変更が必要です。

Stack and address preference

java.net.preferIPv4Stack および java.net.preferIPv6Addresses システムプロパティは JVM が IPv4 または IPv6 のどちらを使用するかを設定するために使用します。 AS7 では IPv4 を使用する場合 java.net.preferIPv4Stack=true を指定し、 IPv6 を使用する場合 java.net.preferIPv4Stack=false (JVM デフォルト) および java.net.preferIPv6Addresses=true を指定します。

※ JVM のネットワークシステムプロパティについての詳細は Java SE Document を参照して下さい。

システムプロパティは JAVA_OPTS 環境変数により設定するのが適切です。 JAVA_OPTS は standalone.conf または domain.conf ファイル中で定義されています。JVM システムプロパティの IP スタック設定を IPv4 から IPv6 に変更するには standalone.conf または domain.conf ファイルの以下のデフォルト設定を編集します。

if [ "x$JAVA_OPTS" = "x" ]; then
    JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=true ..."
...

IPv6 に対応させるにはシステムプロパティを以下の通りに変更します。

if [ "x$JAVA_OPTS" = "x" ]; then
    JAVA_OPTS=" ... -Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true ..."
...

IP address literals

standalone.xml または domain.xml 中の IP アドレス設定を変更するには interface 宣言において妥当な IPv6 アドレスを指定する必要があります。デフォルトで指定されているループバックインターフェース設定を IPv4 から変更する場合、変更対象個所は以下の通りです。

<interfaces>
    <interface name=”management”>
        <inet-address value=”${jboss.bind.address.management:127.0.0.1}”/>
    </interface>
    <interface name=”public”>
        <inet-address value=”${jboss.bind.address:127.0.0.1}”/>
    </interface>
</interfaces>

上記の設定の IPv6 への設定変更例は以下の通りです。

<interfaces>
   <interface name=”management”>
       <inet-address value=”${jboss.bind.address.management:[::1]}”/>
   </interface>
   <interface name=”public”>
       <inet-address value=”${jboss.bind.address:[::1]}”/>
   </interface>
</interfaces>

IPv6 アドレスの省略表現では [] を使用し曖昧さを避けるようにして下さい。これは URL 中で使用させる IPv6 表現の慣例に従います。

interface 定義に上述の変更を行った場合、設定ファイルの他の部分の IP アドレスを IPv4 から IPv6 に変更して下さい。

タグ: ,

JBoss AS7 – add-user.sh による管理ユーザの追加

かなり間があいちゃいましたが、しばらくぶりのエントリです。 ここからは心を入れ替えて頑張っていきたいと思います。

今回はリハビリのエントリとなるので、軽めの話題を書きま〜す。

AS7 をダウンロードして解凍して起動して、管理コンソール(http://localhost:8080/console)にアクセスしようとすると以下の画面が表示されます。

この画面は、『あなたの JBoss AS 7 はちゃんと動いてるけど管理コンソールにアクセスするためのユーザがまだ登録されてないぞ!管理ユーザの登録には $JBOSS_HOME/bin/add-user.sh を使用してね!デフォルトでは “ManagementRealm” というセキュリティレルムが 管理コンソールのアクセス制限には使用されていてそれは登録済みだぞ!』と主張しています。

セキュリティレルムとは、直訳すると『セキュリティ領域』あるいは『セキュリティ範囲』といった感じでしょうかね。具体的には名前付きの認証データのセットです。認証データとはユーザ ID とパスワードの定義です。
セキュリティレルムの定義と管理コンソール(および CLI )へのセキュリティレルムの定義は設定ファイル( standalone.xml, host.xml )で行われています。

<management>
<security-realms>
<security-realm name=”ManagementRealm“>
<authentication>
<properties path=”mgmt-users.properties” relative-to=”jboss.domain.config.dir“/>
</authentication>
</security-realm>

</security-realms>
<management-interfaces>
<native-interface security-realm=”ManagementRealm“>
<socket interface=”management” port=”${jboss.management.native.port:9999}”/>
</native-interface>
<http-interface security-realm=”ManagementRealm“>
<socket interface=”management” port=”${jboss.management.http.port:9990}”/>
</http-interface>
</management-interfaces>
</management>

設定ファイルでは <security-realm> タグで “ManagementRealm” を定義しています。このセキュリティレルムではシステムプロパティ “jboss.domain.config.dir” (もしくは “jboss.server.config.dir” )が指すディレクトリ中の “mgmt-users.properties” ファイルで認証データ( ID=PASSWORD )を定義しています。

インストール直後の $JBOSS_HOME/standalone/configuration/mgmt-users.properties ファイルもしくは $JBOSS_HOME/domain/configuration/mgmt-users.properties ファイルでは以下の定義が行われています。

#admin=2a0923285184943425d1f53ddd58ec7a

インストール直後のユーザ定義プロパティファイルでは admin ユーザがコメントアウトされているためコメントを外すか新規ユーザを追加してやる必要があります。

新規ユーザの追加には $JBOSS_HOME/bin/add-user.sh を使用します。同スクリプトを使って新規ユーザを追加する手順は以下の通りです。

# $JBOSS_HOME/bin/add-user.sh
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.
Realm (ManagementRealm) :
Username : admin
Password :
Re-enter Password :
The username ‘admin’ is easy to guess
Are you sure you want to add user ‘admin’ yes/no? yes
About to add user ‘admin’ for realm ‘ManagementRealm’
Is this correct yes/no? yes
Added user ‘admin’ to file ‘/Users/yoshikazu/java/as/7.1.1/standalone/configuration/mgmt-users.properties’
Added user ‘admin’ to file ‘/Users/yoshikazu/java/as/7.1.1/domain/configuration/mgmt-users.properties’

以上の手順が成功すると mgmt-users.properties ファイルにユーザが追加されているはずです。(パスワードは暗号化されてます。)管理コンソールに再度アクセスして作成したユーザで管理コンソールにアクセスできることを確認してみて下さい。

ちなみに、 add-user.sh のユーザタイプ選択画面で登場する Application User はセキュリティレルム ApplicationRealm のユーザです。 ApplicationRealm はリモーティングサブシステムで使用されます。

タグ: ,

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 インターフェース(コンソール)用となります。次を参照して下さい。

Accessing the web console

web コンソールは HTTP API と同様のポートを通して提供されます。 web コンソールはブラウザから以下の URL にアクセスすることで使用可能です。

   デフォルト 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 プロセス稼働中に行われた外部からの設定変更は反映せれませんしこれらのツールで行った編集に上書きされる可能性があります。

タグ: ,

JBoss AS 7 Admin Guide – High Availability Guide – Apache httpd

Apache httpd

フロントエンドモジュールとしては mod_cluster が推奨されますが、 mod_jk もしくは mod_proxy の使用も可能です。

AJP プロトコルを使用するためには socket-binding 要素を使用して AJP プロトコルをリスンするソケットを定義し、 web サブシステム( subsystem=web )にそのソケットを使用するコネクタを追加定義して下さい。

以下は web サブシステムの定義です。 AJP プロトコル用の ajp コネクタが定義され ajp という名前のソケットバインディングを参照しています。

<subsystem xmlns=”urn:jboss:domain:web:1.0“>
            <connector name=”http” protocol=”HTTP/1.1″ socket-binding=”http”/>
            <connector name=”ajp” protocol=”AJP/1.3″ socket-binding=”ajp“/>
            …
</subsystem>

以下はソケットバインディングの定義です。 ajp は 8009 ポートを使用します。下記のソケットバインディングは指定がないかぎり public インターフェースで指定されたネットワークインターフェース(IP, NIC)にバインドされます。

<socket-binding-group name=”standard-sockets” default-interface=”public“>

….

          <socket-binding name=”http” port=”8080″/>

          <socket-binding name=”ajp” port=”8009″/>

          <socket-binding name=”https” port=”8443″/>

</socket-binding-group>

タグ: ,

JBoss AS 7 Admin Guide – Management tasks – Subsystem configuration – Deployment Scanner configuration

今回はデプロイメントスキャナのお話です。デプロイメントスキャナとは何か?。。。デプロイディレクトリをスキャン(デフォルトだと 5 秒間隔)し jar, war, ear 等のファイルあるいはディレクトリが存在したらデプロイしてくれるサービスです。

この開発時は非常に便利なデプロイメントスキャナですが、頻繁にデプロイを行わないあるいはデプロイのタイミングを制御する手順のあるプロダクション環境だと邪魔だったりスキャンインターバルを変更したくなります。

AS7 ではデプロイメントスキャナがサブシステム( /subsystem=deployment-scanner )として提供されています。なので、 server 設定ファイルである standalone.xml 中にデプロイメントスキャナが宣言されており、設定変更もその部分で行います。もちろん CLI を使った動的な設定変更も可能です。

重要な点として、domain.xml にはデプロイメントスキャナは含まれていません。なぜなら domain モードではファイルシステムを使用した(デプロイディレクトリにデプロイしたいファイル/ディレクトリを配置することで行うデプロイ)がサポートされないのでデプロイメントスキャナも domain モードでは動いていません。

それではマニュアルを読んでみましょう!

Deployment Scanner configuration

デプロイメントスキャナは standalone モードのみで使用されます。

デプロイメントスキャナの仕事はデプロイメントディレクトリに新たなデプロイ対象ファイルがあるかをスキャンしデプロイ対象ファイルがある場合はそれをデプロイします。
デプロイメントスキャナは standalone[-XXX].xml 中に以下の形式で設定されます。

<subsystem xmlns=”urn:jboss:domain:deployment-scanner:1.0“>
<deployment-scanner scan-interval=”5000” relative-to=”jboss.server.base.dir” path=”deployments” />
</subsystem>

より多くのデプロイメントディレクトリをスキャンするために <deployment-scanner /> 要素を追加することも可能です。上記の設定例は $JBOSS_HOME/standalone/deployments ディレクトリを 5 秒間隔でスキャンすることを表しています。

上記のデプロイメントスキャナ設定について CLI を使用して実行時の設定照会を行った例は以下の通りです。XML において明示的に指定していない <deployment-scanner /> 要素の属性のデフォルト値を照会することが可能です。

[standalone@localhost:9999 /] /subsystem=deployment-scanner:read-resource(recursive=true)
{
     “outcome” => “success”,
     “result” => {“scanner” => {“default” => {
         “auto-deploy-exploded” => false,
         “auto-deploy-zipped” => true,
         “deployment-timeout” => 60L,
         “name” => “default”,
         “path” => “deployments”,
         “relative-to” => “jboss.server.base.dir”,
         “scan-enabled” => true,
         “scan-interval” => 5000
     }}}
}

<deployment-scanner /> 要素の属性は以下の通りです。

Name Type Description
name STRING スキャナ名です。指定しない場合 “default” が適用されます。
path STRING スキャンするパスを指定します。’relative-to’ 属性が指定されない限り絶対パスとして扱われ、指定された場合は ‘relative-to’ からの相対パスとして扱われます。
relative-to STRING ‘path’ 属性で指定された値が相対パスとして参照するファイルパスまはた起動時のシステムプロパティを指定します。上記の例では システムプロパティ “jboss.server.base.dir” が指定され $JBOSS_HOME/standalone として解決されます。
scan-enabled BOOLEAN スキャンの有効/無効を true/false で指定します。
scan-interval INT スキャンのインターバルをミリ秒で指定します。 1 以下の値を指定した場合起動時のみスキャンが実行されます。
auto-deploy-zipped BOOLEAN zip にアーカイブされたデプロイコンテンツを .dodeploy マーカーファイルの追加無しでデプロイするか否かを true/false で指定します。

※ false に設定した場合 sample.war は sample.war.dodeploy ファイルの作成をトリガーにデプロイ処理が実行されます。

auto-deploy-exploded BOOLEAN zip にアーカイブされたデプロイコンテンツを .dodeploy マーカーファイルの追加無しでデプロイするか否かを true/false で指定します。デプロイコンテンツの修正中にデプロイが発生しないことを保証できないため、同項目を ‘true’ に設定することは通常推奨されません。

※ true に設定した場合、展開デプロイ形式もオートデプロイの対象になります。デフォルトでは展開形式のアプリケーションをデプロイするためには $アプリケーション名.dodeploy ファイルをデプロイディレクトリに配置する必要があります。

deployment-timeout LONG デプロイ処理のタイムアウトを秒単位で指定します。デフォルトは 60 秒です。

デプロイメントスキャナは server の起動前に standalone[-XXX].xml を修正するもしくは server 実行時に CLI を使用して設定を追加/変更/削除することが可能です。

[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=new:add(scan-interval=10000,relative-to=”jboss.server.base.dir”,path=”other-deployments”)
{“outcome” => “success”}
[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=new:remove
{“outcome” => “success”}

server 実行時に CLI を使用してスキャンを無効化する例は以下の通りです。

[standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=default:write-attribute(name=”scan-enabled”,value=false)
{“outcome” => “success”}
[standalone@localhost:9999 /] /subsystem=deployment-scanne:read-resource(recursive=true)
     “outcome” => “success”,
     “result” => {“scanner” => {“default” => {
         “auto-deploy-exploded” => false,
         “auto-deploy-zipped” => true,
         “deployment-timeout” => 60L,
         “name” => “default”,
         “path” => “deployments”,
         “relative-to” => “jboss.server.base.dir”,
         “scan-enabled” => false,
         “scan-interval” => 5000
     }}}

タグ: ,