3.5. 設定データ

スタンドアロン設定ファイルは EAP_HOME/standalone/configuration/ ディレクトリーにあります。事前定義されたプロファイルは 5 つあり (default、ha、full、full-ha、および load-balancer)、それぞれに個別のファイルが存在します。これらは、JBoss EAP の起動時に管理 CLI を使用して変更できる設定ファイルの例です。

デフォルトでは、スタンドアロンサーバーとして JBoss EAP を起動すると standalone.xml ファイルが使用されます。他の設定で JBoss EAP を起動するには --server-config 引数を使用します。以下に例を示します。

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml

YAML ファイルを使用したスタンドアロンサーバーの更新

YAML ファイルを使用してスタンドアロンサーバーを設定すると、カスタマイズプロセスが外部化され、サーバーのアップグレード速度が向上します。この機能を使用すると、サーバーが読み取り専用モードで起動します。つまり、サーバーの再起動後に設定の変更が保持されません。

ユーザーは YAML ファイル内のさまざまなリソースを変更できます。YAML ファイルでは次の要素がサポートされています。

次の要素は YAML ファイルではサポートされて いません。

YAML ルートノードは wildfly-configuration です。モデルツリーに従ってリソースを変更できます。リソースがすでに存在する場合 (XML 設定ファイルまたは以前の YAML ファイルによって作成されている場合)、モデルツリーを使用してそのリソースを更新できます。リソースが存在しない場合は、モデルツリーを使用して作成できます。

wildfly-configuration:
  subsystem:
    datasources:
      jdbc-driver:
        postgresql:
          driver-name: postgresql
          driver-xa-datasource-class-name: org.postgresql.xa.PGXADataSource
          driver-module-name: org.postgresql.jdbc
      data-source:
        PostgreSQLDS:
          enabled: true
          exception-sorter-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
          jndi-name: java:jboss/datasources/PostgreSQLDS
          jta: true
          max-pool-size: 20
          min-pool-size: 0
          connection-url: "jdbc:postgresql://localhost:5432}/demo"
          driver-name: postgresql
          user-name: postgres
          password: postgres
          validate-on-match: true
          background-validation: false
          background-validation-millis: 10000
          flush-strategy: FailingConnectionOnly
          statistics-enable: false
          stale-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
          valid-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
          transaction-isolation: TRANSACTION_READ_COMMITTED

上記の例では、postgresql という jdbc-driver と PostgreSQLDS という data-source を定義しています。

マネージドドメインの設定ファイルは EAP_HOME/domain/configuration/ ディレクトリーにあります。これらは、JBoss EAP の起動時に管理 CLI を使用して変更できる設定ファイルの例です。

デフォルトでは、JBoss EAP をマネージドドメインで起動すると host.xml ファイルが使用されます。他の設定で JBoss EAP を起動するには --host-config 引数を使用します。以下に例を示します。

$ EAP_HOME/bin/domain.sh --host-config=host-primary.xml

JBoss EAP サーバー設定を復元するには、以下の場所にデータをバックアップする必要があります。

サーバーの保守や管理をしやすくするため、JBoss EAP は起動時に元の設定ファイルにタイムスタンプを付けたものを作成します。

管理操作によってその他の設定変更が行われると、元のファイルが自動的にバックアップされ、インスタンスの作業用コピーが参照およびロールバック用に保持されます。さらに、現在のサーバー設定の現時点のコピーである設定スナップショットを撮ることができます。これらのスナップショットは管理者によって保存およびロードされます。

以下の例では、standalone.xml ファイルが使用されますが、同じプロセスが domain.xml および host.xml にも適用されます。

スナップショットの作成

管理 CLI を使用して、現在の設定のスナップショットを作成します。

:take-snapshot
{
    "outcome" => "success",
    "result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}

スナップショットのリスト

管理 CLI を使用してすべてのスナップショットを一覧表示します。

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}

スナップショットの削除

管理 CLI を使用して、スナップショットを削除します。

:delete-snapshot(name=20151022-133109702standalone.xml)

スナップショットまたは設定の自動保存バージョンを使用してサーバーを起動できます。

JBoss EAP では、稼働中のシステムに加えられた設定の変更を追跡できます。この機能を使用すると、管理者は他の許可されたユーザーが追加した設定変更の履歴を確認することができます。

管理 CLI または 管理コンソール から設定変更の追跡と表示を有効にできます。

管理 CLI からの設定変更の追跡および表示

設定変更の追跡を有効にするには、以下の管理 CLI コマンドを使用します。max-history 属性を使用すると保存するエントリーの数を指定できます。

/subsystem=core-management/service=configuration-changes:add(max-history=20)

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:add(max-history=20)

最近行われた設定変更のリストを表示するには、以下の管理 CLI コマンドを使用します。

/subsystem=core-management/service=configuration-changes:list-changes

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:list-changes

/host=HOST_NAME/server=SERVER_NAME/subsystem=core-management/service=configuration-changes:list-changes

このコマンドは、各設定変更とその変更日、変更元、結果、および操作の詳細をリストで表示します。たとえば、以下の list-changes コマンドの出力は、変更日が新しい順に設定変更を表示しています。

{
    "outcome" => "success",
    "result" => [
        {
            "operation-date" => "2016-02-12T18:37:00.354Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [],
                "operation" => "reload",
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:34:16.859Z",
            "access-mechanism" => "NATIVE",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "address" => [
                    ("subsystem" => "datasources"),
                    ("data-source" => "ExampleDS")
                ],
                "operation" => "write-attribute",
                "name" => "enabled",
                "value" => false,
                "operation-headers" => {
                    "caller-type" => "user",
                    "access-mechanism" => "NATIVE"
                }
            }]
        },
        {
            "operation-date" => "2016-02-12T18:24:11.670Z",
            "access-mechanism" => "HTTP",
            "remote-address" => "127.0.0.1/127.0.0.1",
            "outcome" => "success",
            "operations" => [{
                "operation" => "remove",
                "address" => [
                    ("subsystem" => "messaging-activemq"),
                    ("server" => "default"),
                    ("jms-queue" => "ExpiryQueue")
                ],
                "operation-headers" => {"access-mechanism" => "HTTP"}
            }]
        }
    ]
}

この例は、設定に影響した以下 3 つの操作の詳細を表しています。

管理コンソールからの設定変更の追跡および表示

管理コンソールからの設定変更の追跡を有効にするには、Runtime タブを選択して、変更を追跡するサーバーまたはホストに移動し、ドロップダウンメニューで 設定変更 を選択します。Enable Configuration Changes をクリックし、最大の履歴値を指定します。

そのページの表に変更された設定が日付、変更元、結果、および操作詳細とともに表示されます。

JBoss EAP で式を使用して、設定のリテラル値の代わりに置き換え可能なプロパティーを定義できます。

standalone*.xml または domain.xml 設定ファイルでプロパティー置換を使用すると、プロパティーがシステムプロパティーで見つかった値に置き換えられます。システムプロパティーは、EAP プロファイル xml ファイルで定義するか、コマンドラインターミナルから -D コマンドを入力して定義します。

特定のサブシステムでプロパティーの置換が許可されているかどうかを判断するには、次のコマンドを使用して、サブシステム設定の説明を表示します。

/subsystem=datasources:read-resource-description(recursive=true)

expressions-allowed 属性が true に設定されている場合には、プロパティーを置換できます。

式の形式は ${PARAMETER:DEFAULT_VALUE} になります。指定のパラメーターが設定されると、パラメーターの値が使用されます。設定されない場合は、デフォルト値が使用されます。

式の解決でサポートされているソースは、システムプロパティーと環境変数です。環境変数を使用して式を解決する場合は、${env.LANG} の形式を使用します。

以下の例では、jboss.bind.address パラメーターが設定されていなければ、standalone.xml 設定ファイルによって public インターフェイスの inet-address が 127.0.0.1 に設定されます。

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

次のコマンドを使用して、EAP をスタンドアロンサーバーとして起動するときに jboss.bind.address パラメーターを設定できます。

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS

式はネストできるため、固定値の代わりにさらに高度な式を使用できます。

ネストされた式の書式は、通常の式の場合と同様ですが、ある式が別の式に組み込まれます。例を以下に示します。

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}

JBoss EAP はネストされた式を再帰的に評価するため、最初に 内部 の式を、次に 外部 の式を評価します。式が別の式へ解決する場合は式も再帰的になることがあり、その後解決されます。ネストされた式は式が許可された場所ならどこでも許可されます (ただし、管理 CLI コマンドを除く)。

たとえば、データソース定義のパスワードがマスクされている場合は、ネストされた式を使用できます。

デプロイメント記述子ベースのプロパティー置換は、記述子に基づいてプロパティーを置換するため、アプリケーションとビルドチェーンから環境に関する仮定を除外できます。

環境固有の設定は、アノテーションやビルドシステムスクリプトでなく、デプロイメント記述子に指定できます。設定はファイルに指定したり、パラメーターとしてコマンドラインで提供したりできます。

データソース接続パラメーターなどのアプリケーションの設定は、通常は開発デプロイメント、テストデプロイメント、および本番環境によって異なります。Jakarta EE 仕様にはこれらの設定を外部化するメソッドが含まれていないため、このような違いはビルドシステムスクリプトで対応することがあります。JBoss EAP では、記述子ベースのプロパティー置換を使用して設定を外部的に管理できます。

spec-descriptor-property-replacement フラグは Jakarta EE 記述子の置換を制御し、JBoss EAP はデフォルトでこれを 無効 にします。有効にすると、次のデプロイメント記述子のプロパティーを置き換えることができます。

以下の管理 CLI コマンドを使用すると、Jakarta EE の記述子でプロパティー置換を有効または無効にできます。

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)

jboss-descriptor-property-replacement フラグは JBoss 固有の記述子の置換を制御し、JBoss EAP はデフォルトでこれを有効にします。有効にすると、次のデプロイメント記述子のプロパティーを置き換えることができます。

以下の管理 CLI コマンドを使用して、JBoss EAP 固有の記述子でプロパティー置換を有効または無効にします。

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

annotation-property-replacement フラグは、アノテーション内のプロパティーの置換を制御します。デフォルトでは有効になっていません。有効にすると、アプリケーションクラス内のアノテーション属性のプロパティーを置き換えることができます。

以下の管理 CLI コマンドを使用して、アノテーションのプロパティー置換を有効または無効にします。

/subsystem=ee:write-attribute(name="annotation-property-replacement",value=VALUE)

annotation-property-replacement を true に設定すると、システムプロパティー値が設定されている場合にアノテーションのプロパティー置換を有効にできます。たとえば、システムプロパティーを設定して、Message Driven Bean の maxSession 値を置き換えることができます。

@MessageDriven(mappedName="jms/Queue", activationConfig =  {
        @ActivationConfigProperty(propertyName = "acknowledgeMode",
                                  propertyValue = "Auto-acknowledge"),
        @ActivationConfigProperty(propertyName = "destinationType",
                                  propertyValue = "javax.jms.Queue")
@ActivationConfigProperty(propertyName = "maxSession", propertyValue = "${exampleMDB.maxSession:20}")})
    })
public class ExampleMessageDrivenBean implements MessageListener {
...
}

-DexampleMDB.maxSession システムプロパティーは、100 に設定することもできます。このシステムプロパティーが設定されていない場合、値はデフォルトで 20 になります。

Git を使用して、サーバー設定データ、プロパティーファイル、およびデプロイメントを管理および永続化できます。これにより、これらのファイルのバージョン履歴を管理できるだけでなく、1 つ以上の Git リポジトリーを使用して複数のサーバーおよびノード全体でサーバーやアプリケーションの設定を共有することができます。この機能は、デフォルトの設定ディレクトリーレイアウトを使用するスタンドアロンサーバーでのみ動作します。

ローカル Git リポジトリー 内の設定データを使用することも、リモート Git リポジトリー からデータをプルすることもできます。Git リポジトリーは、スタンドアロンサーバーコンテンツのベースディレクトリーである jboss.server.base.dir ディレクトリーで設定されます。jboss.server.base.dir ディレクトリーが Git を使用するよう設定されると、JBoss EAP は管理 CLI または管理コンソールを使用して設定へ加えられた各更新を自動的にコミットします。設定ファイルを手作業で編集してサーバー外部で追加された変更は、コミットおよび永続化されません。しかし、Git CLI を使用して手作業の変更を追加およびコミットすることができます。また、Git CLI を使用してコミット履歴の表示、ブランチの管理、およびコンテンツの管理を行うこともできます。

この機能を使用するには、サーバーの起動時に以下の引数を 1 つ以上コマンドラインに渡します。

ローカル Git リポジトリーの使用

ローカル Git リポジトリーを使用するには、--git-repo=local 引数を使用してサーバーを起動します。サーバーの起動時に --git-branch=GIT_BRANCH_NAME 引数を追加して、オプションのブランチまたはタグ名をリモートリポジトリーで指定することもできます。ブランチまたはタグ名が存在 しない と作成されないため、この引数には既存のブランチまたはタグ名を指定する必要があります。タグ名を使用する場合、リポジトリーを detached HEAD 状態にし、今後のコミットがブランチにアタッチされないようにします。

以下のコマンド例は、local リポジトリーの 1.0.x ブランチを使用して、サーバーを起動します。

$ EAP_HOME/bin/standalone.sh --git-repo=local --git-branch=1.0.x

local Git リポジトリーを使用する引数を使用してサーバーを起動した場合、JBoss EAP は jboss.server.base.dir ディレクトリーがすでに Git に対して設定されているかどうかを確認します。設定されていない場合、JBoss EAP は既存の設定コンテンツを使用して jboss.server.base.dir ディレクトリーに Git リポジトリーを作成し、初期化します。JBoss EAP は --git-branch 引数によって渡されたブランチ名をチェックアウトします。引数が渡されていない場合は master ブランチをチェックアウトします。初期化後、スタンドアロンサーバーコンテンツのベースディレクトリーに .git/ ディレクトリーと .gitignore ファイルがあることを確認できるはずです。

リモート Git リポジトリーの使用

Git リポジトリーを使用するには、--git-repo=REMOTE_REPO 引数を使用してサーバーを起動します。引数の値は、ローカル Git 設定に手作業で追加した URL またはリモートエイリアスになります。

サーバーの起動時に --git-branch=GIT_BRANCH_NAME 引数を追加して、オプションのブランチまたはタグ名をリモートリポジトリーで指定することもできます。ブランチまたはタグ名が存在 しない と作成されないため、この引数には既存のブランチまたはタグ名を指定する必要があります。タグ名を使用する場合、リポジトリーを detached HEAD 状態にし、今後のコミットがブランチにアタッチされないようにします。

Git リポジトリーに認証が必要な場合は、サーバーの起動時に --git-auth=AUTH_FILE_URL 引数も追加する必要があります。この引数は、Git リポジトリーへの接続に必要な認証情報が含まれる Elytron 設定ファイルへの URL になります。以下は、認証に使用できる Elytron 設定を指定する WildFly クライアント設定ファイルの例です。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <authentication-client xmlns="{ElytronAuthClientNamespace}">
    <authentication-rules>
      <rule use-configuration="test-login">
      </rule>
    </authentication-rules>
    <authentication-configurations>
      <configuration name="test-login">
        <sasl-mechanism-selector selector="BASIC" />
        <set-user-name name="eap-user" />
        <credentials>
          <clear-password password="my_api_key" />
        </credentials>
        <set-mechanism-realm name="testRealm" />
      </configuration>
    </authentication-configurations>
  </authentication-client>
</configuration>

以下は、リモート eap-configuration リポジトリーの 1.0.x ブランチを使用し、認証情報が含まれる Elytron 設定ファイルに URL を渡して、フルプロファイルでサーバーを起動するコマンドの例になります。

$ EAP_HOME/bin/standalone.sh --git-repo=https://github.com/MY_GIT_ID/eap-configuration.git --git-branch=1.0.x --git-auth=file:///home/USER_NAME/github-wildfly-config.xml --server-config=standalone-full.xml

リモート Git リポジトリーを使用する引数を使用してサーバーを起動した場合、JBoss EAP は jboss.server.base.dir ディレクトリーがすでに Git に対して設定されているかどうかを確認します。設定されていない場合、JBoss EAP は jboss.server.base.dir ディレクトリーにある既存の設定ファイルを削除し、代わりにリモート Git 設定データを置きます。JBoss EAP は --git-branch 引数によって渡されたブランチ名をチェックアウトします。引数が渡されていない場合は master ブランチをチェックアウトします。この処理の完了後、スタンドアロンサーバーコンテンツのベースディレクトリーに .git/ ディレクトリーと .gitignore ファイルがあることを確認できるはずです。

Git 使用時のリモート設定データの公開

管理 CLI の publish-configuration 操作を使用すると、Git リポジトリーの変更をリモートリポジトリーにプッシュすることができます。JBoss EAP は、サーバー起動時のブート処理中にリモート Git リポジトリーから設定をプルするため、複数のサーバー間で設定データを共有できます。この操作はリモートリポジトリーにのみ使用できます。ローカルリポジトリーでは動作しません。

以下の管理 CLI 操作は、設定データをリモート eap-configuration リポジトリーに公開します。

:publish-configuration(location="=https://github.com/MY_GIT_ID/eap-configuration.git")
{"outcome" => "success"}

Git でのスナップショットの使用

Git のコミット履歴を使用して設定の変更を追跡する他に、スナップショットを作成して特定時の設定を保持することもできます。スナップショットをリスト表示し、削除することができます。

Git 使用時のスナップショットの作成

スナップショットは、Git にタグとして保存されます。take-snapshot 操作で、スナップショットタグ名とコミットメッセージを引数として指定します。

以下の管理 CLI 操作は、スナップショットを作成し、タグに "snapshot-01" という名前を付けます。

:take-snapshot(name="snapshot-01", comment="1st snapshot")
{
    "outcome" => "success",
    "result" => "1st snapshot"
}

Git 使用時のスナップショットのリスト表示

list-snapshots 操作を使用すると、スナップショットタグをすべてリスト表示できます。

以下の管理 CLI 操作は、スナップショットタグをリスト表示します。

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "",
        "names" => [
            "snapshot : 1st snapshot",
            "refs/tags/snapshot-01",
            "snapshot2 : 2nd snapshot",
            "refs/tags/snapshot-02"
        ]
    }
}

Git 使用時のスナップショットの削除

delete-snapshot 操作にタグ名を渡すと特定のスナップショットを削除できます。

以下の管理 CLI 操作は、タグ名が "snapshot-01" のスナップショットを削除します。

:delete-snapshot(name="snapshot-01")
{"outcome" => "success"}