設定ガイド


Red Hat JBoss Enterprise Application Platform 8.0

アプリケーションおよびサービスの実行を含む、Red Hat JBoss Enterprise Application Platform の設定およびメンテナンス手順

Red Hat Customer Content Services

概要

このガイドは、JBoss EAP の設定や維持に必要な設定タスクと、JBoss EAP でアプリケーションやその他のサービスを稼働するために必要な設定タスクの多くを取り上げることを目的としています。

JBoss EAP ドキュメントへのフィードバック (英語のみ)

エラーを報告したり、ドキュメントを改善したりするには、Red Hat Jira アカウントにログインし、課題を送信してください。Red Hat Jira アカウントをお持ちでない場合は、アカウントを作成するように求められます。

手順

  1. このリンクをクリック してチケットを作成します。
  2. Summary に課題の簡単な説明を入力します。
  3. Description に課題や機能拡張の詳細な説明を入力します。問題があるドキュメントのセクションへの URL も記載してください。
  4. Submit をクリックすると、課題が作成され、適切なドキュメントチームに転送されます。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。

第1章 はじめに

このガイドを使用して JBoss EAP を設定する前に、最新バージョンの JBoss EAP がダウンロードされ、インストールされていることを確認してください。インストール手順は、Red Hat JBoss Enterprise Application Platform のインストール方法 を参照してください。

重要

ホストマシンによって JBoss EAP をインストールする場所が異なるため、このガイドではインストール場所を EAP_HOME と示しています。管理タスクを行う際には、EAP_HOME を実際の JBoss EAP のインストール場所に置き換えてください。

第2章 JBoss EAP の開始および停止

2.1. JBoss EAP の開始および停止

JBoss EAP を開始する方法は、JBoss EAP をスタンドアロンサーバーとして実行しているか、マネージドドメイン内のサーバーで実行しているかによって異なります。

JBoss EAP を停止する方法は、JBoss EAP のインタラクティブインスタンスとバックグラウンドインスタンスのどちらを実行しているかによって異なります。

2.1.1. JBoss EAP のスタンドアロンサーバーとしての起動

JBoss EAP をスタンドアロンサーバーとして実行して、JBoss EAP の単一インスタンスを管理できます。

サーバーは一時停止状態で起動し、必要なすべてのサービスが開始されるまで要求を受け入れません。必要なサービスが開始されると、サーバーは通常の実行状態に移行し、要求の受け入れを開始できます。

この起動スクリプトは、EAP_HOME/bin/standalone.conf ファイル (Windows Server の場合は standalone.conf.bat) を使用して、JVM オプションなどのデフォルト設定を指定します。このファイルで設定をカスタマイズできます。

注記

ターミナルで起動スクリプトの引数のリストを表示するには、-help 引数を使用します。

JBoss EAP はデフォルトで standalone.xml 設定ファイルを使用しますが、別の設定ファイルを使用して起動することもできます。

前提条件

  • JBoss EAP のインストール

手順

  1. 端末を開きます。
  2. 次のスクリプトを使用して、JBoss EAP をスタンドアロンサーバーとして起動します。

    $ EAP_HOME/bin/standalone.sh
    Copy to Clipboard Toggle word wrap
    1. Windows Server の場合は、EAP_HOME\bin\standalone.bat スクリプトを使用します。

2.1.2. マネージドドメインでのサーバー用の JBoss EAP の起動

マネージドドメインオペレーティングモードで JBoss EAP を実行し、単一のドメインコントローラーを使用して複数の JBoss EAP インスタンスを管理できます。

サーバーは一時停止状態で起動し、必要なすべてのサービスが開始されるまで要求を受け入れません。必要なサービスが開始されると、サーバーは通常の実行状態に移行して、要求の受け入れを開始できます。

ドメイン内のサーバーグループのサーバーを起動する前にドメインコントローラーを起動する必要があります。

前提条件

  • JBoss EAP のインストール

手順

  1. 端末を開きます。
  2. 最初にドメインコントローラーを起動してから、次のスクリプトを使用して、関連付けられている各ホストコントローラーを起動します。

    $ EAP_HOME/bin/domain.sh
    Copy to Clipboard Toggle word wrap
    • Windows Server の場合は EAP_HOME\bin\domain.bat スクリプトを使用します。

この起動スクリプトは、EAP_HOME/bin/domain.conf ファイル (Windows Server の場合は domain.conf.bat) を使用して、JVM オプションなどのデフォルト設定を指定します。このファイルで設定をカスタマイズできます。

JBoss EAP はデフォルトで host.xml ホスト設定ファイルを使用しますが、別の設定ファイルを使用して開始できます。

マネージドドメインの設定時には、起動スクリプトに追加の引数を渡す必要があります。

注記

使用可能なすべての起動スクリプト引数とその目的の完全なリストは、--help 引数を使用してください。

2.1.3. JBoss EAP の対話的なインスタンスの停止

スタンドアロンサーバーまたはドメインコントローラーのインタラクティブインスタンスは、起動した端末から停止できます。

前提条件

  • JBoss EAP の実行中のインスタンスを用意しておく。

手順

  • JBoss EAP を開始したターミナルで Ctrl + C を押します。

2.1.4. JBoss EAP のバックグラウンドインスタンスの停止

管理 CLI に接続して、スタンドアロンサーバーの実行中のインスタンスまたはマネージドドメイン内のサーバーをシャットダウンできます。

前提条件

  • ターミナルで実行されている JBoss EAP のインスタンスがある。

手順

  1. 次のスクリプトを使用して、管理 CLI を起動します。

    $ EAP_HOME/bin/jboss-cli.sh --connect
    Copy to Clipboard Toggle word wrap
  2. shutdown コマンドを実行します。

    shutdown
    Copy to Clipboard Toggle word wrap

マネージドドメインのサーバーで JBoss EAP のインスタンスを実行する場合は、shutdown コマンドで --host 引数を使用して、シャットダウンするホスト名を指定する必要があります。

2.2. JBoss EAP の管理専用モードでの実行

JBoss EAP は管理者専用モードで起動できます。このモードでは、JBoss EAP は他のランタイムサービスを起動したり、エンドユーザーのリクエストを処理したりすることなく、管理リクエストを実行および許可できます。管理専用モードは スタンドアロンサーバーマネージドドメイン の両方で使用できます。

2.2.1. 管理専用モードでのスタンドアロンサーバーの実行

スタンドアロンサーバーを使用して、JBoss EAP インスタンスを管理専用モードで実行できます。

前提条件

  • JBoss EAP がインストールされている。

手順

  1. ターミナルを開きます。
  2. JBoss EAP インスタンスを管理専用モードで起動するには、JBoss EAP インスタンスの起動時に --start-mode=admin-only ランタイム引数を使用します。

    $ EAP_HOME/bin/standalone.sh --start-mode=admin-only
    Copy to Clipboard Toggle word wrap
    1. 以下のコマンドを実行して、サーバーの実行モードを確認します。サーバーが管理専用モードで実行されている場合は、結果が ADMIN_ONLY になります。

      :read-attribute(name=running-mode)
      {
        "outcome" => "success",
        "result" => "ADMIN_ONLY"
      }
      Copy to Clipboard Toggle word wrap
      注記

      さらに、以下のコマンドを使用すると、JBoss EAP が起動された最初の実行モードを確認することもできます。

      /core-service=server-environment:read-attribute(name=initial-running-mode)
      Copy to Clipboard Toggle word wrap
    2. 異なるランタイムスイッチを使用して JBoss EAP インスタンスを停止および起動する他に、管理 CLI を使用して異なるモードでリロードすることもできます。

      1. サーバーを管理専用モードでリロードするには、以下を実行します。

        reload --start-mode=admin-only
        Copy to Clipboard Toggle word wrap
      2. サーバーを通常モードでリロードするには、以下を実行します。

        reload --start-mode=normal
        Copy to Clipboard Toggle word wrap
        注記

        サーバーが管理専用モードで起動し、reload コマンドに --start-mode 引数が指定されていない場合、サーバーは通常モードで起動します。

2.2.2. 管理専用モードでのマネージドドメインの実行

マネージドドメインの場合、ドメインコントローラーが管理専用モードで起動すると、ドメインコントローラーはセカンダリーホストコントローラーからの受信接続を許可しません。管理専用モードで起動したホストコントローラーは、サーバーを起動しません。

前提条件

  • JBoss EAP がインストールされている。

手順

  1. ターミナルを開きます。
  2. --admin-only ランタイム引数を渡してホストコントローラーを管理専用モードで起動します。

    $ EAP_HOME/bin/domain.sh --admin-only
    Copy to Clipboard Toggle word wrap
    1. 以下のコマンドを実行して、ホストコントローラーの実行モードを確認します。ホストコントローラーが管理専用モードで実行されている場合は、結果が ADMIN_ONLY になります。

      /host=HOST_NAME:read-attribute(name=running-mode)
      {
        "outcome" => "success",
        "result" => "ADMIN_ONLY"
      }
      Copy to Clipboard Toggle word wrap
    2. 異なるランタイムスイッチを使用してホストコントローラーを停止および起動する他に、管理 CLI を使用して異なるモードでリロードすることもできます。

      1. ホストコントローラーを管理専用モードでリロードするには、以下を実行します。

        reload --host=HOST_NAME --admin-only=true
        Copy to Clipboard Toggle word wrap
      2. ホストコントローラーを通常モードでリロードするには、以下を実行します。

        reload --host=HOST_NAME --admin-only=false
        Copy to Clipboard Toggle word wrap
        注記

        ホストコントローラーが管理専用モードで起動し、reload コマンドに --admin-only 引数が指定されていない場合、ホストコントローラーは通常モードで起動します。

2.3. JBoss EAP の正常な一時停止およびシャットダウン

JBoss EAP は正常に一時停止およびシャットダウンできます。これにより、新しいリクエストを許可せずにアクティブなリクエストを正常に完了できます。タイムアウト値を指定すると、アクティブなリクエストが完了するまでに、一時停止またはシャットダウン操作が待機します。サーバーが一時停止しても管理リクエストは処理されます。

一時停止と正常なシャットダウンは、リクエストがサーバーに入るエントリーポイントに重点を置きながら、サーバー全体で調整されます。次のサブシステムは、一時停止と正常なシャットダウンをサポートしています。

Undertow
undertow サブシステムはすべてのリクエストが終了するまで待機します。
mod_cluster
modcluster サブシステムは PRE_SUSPEND フェーズでサーバーが一時停止することをロードバランサーに通知します。
Jakarta Enterprise Beans
ejb3 サブシステムは、すべてのリモートセッション Bean リクエストおよび MDB メッセージ配信が完了するまで待機します。MDB への配信は PRE_SUSPEND フェーズ中に停止します。Jakarta Enterprise Bean タイマーが中断されます。サーバーが再開すると、見落とされたタイマーがアクティブ化されます。
トランザクション

サーバーは一時停止されると、新しいリクエストを受け入れなくなります。ただし、進行中のトランザクションとリクエストは、完了するか、タイムアウト期間が経過するまで続行できます。たとえば、サーバーは、一時停止中のサーバーにおけるアクティブなトランザクションに関連する受信リモート呼び出しを受け入れます。

これは、XTS トランザクションに関連する Web サービスリクエストにも適用されます。

正常なシャットダウンの前にトランザクションを開始し、それが失敗した場合 (必要なデータベースが使用できないなど)、そのトランザクションは自動的に回復されません。正常なシャットダウン処理により、リカバリーマネージャーが機能しない可能性があるためです。リカバリーマネージャーを利用して失敗したトランザクションを完了するには、JBoss EAP インスタンスを再開する必要があります。

デフォルトでは、ejb3 サブシステムでのトランザクションの正常なシャットダウンは無効になっています。Jakarta Enterprise Beans 関連のトランザクションが完了してからサーバーを一時停止する場合は、トランザクションの正常シャットダウンを有効にする必要があります。以下に例を示します。

/subsystem=ejb3:write-attribute(name=enable-graceful-txn-shutdown,value=true)
Copy to Clipboard Toggle word wrap

この動作はデフォルトでは無効になっています。正常なシャットダウン中に Jakarta Enterprise Beans クライアントがクラスターノードを呼び出す可能性があるためです。クラスター環境では、トランザクションが完了した 、サーバーがリモートクライアントに、ノードがリモート呼び出しに使用できなくなったことを通知します。クライアントがこの時間枠内 (トランザクションが完了する前) にシャットダウン中のノードに新しいリクエストを送信すると、ノードはそのリクエストを拒否します。

Jakarta Concurrency

サーバーはすべてのアクティブなジョブが終了するまで待機します。キューに置かれたジョブはすべてスキップされます。Jakarta Concurrency には永続性がないため、スキップされたキュー内のジョブはすべて失われます。

サーバーが一時停止状態である間、スケジュールされたタスクはスケジュールどおりの時間に実行されますが、java.lang.IllegalStateException が発生します。サーバーが再開すると、スケジュールされたタスクは引き続き正常に実行されます。ほとんどの場合、タスクを再スケジュールする必要はありません。

Batch
サーバーはタイムアウト期間内の実行中のジョブをすべて停止し、スケジュール済みのジョブをすべて延期します。
注記

現在、正常なシャットダウンは、新しい受信 Jakarta Messaging メッセージを拒否しません。インフライトアクティビティーによってスケジュールされた Jakarta Batch ジョブおよび Jakarta Concurrency タスクは、現在実行の継続が許可されます。しかし、タイムアウトウインドウを渡す Jakarta Concurrency タスクが提出されると、実行時にエラーが発生します。

リクエストは request-controller サブシステムによって追跡されます。このサブシステムがないと、一時停止および再開の機能が制限され、一時停止またはシャットダウンする前に、サーバーがリクエストの完了を待機しません。この機能が必要ない場合は、request-controller サブシステムを削除すると、パフォーマンスを若干向上できます。

2.3.1. サーバーの一時停止

JBoss EAP 8.0 は、サーバーの操作を正常に一時停止する suspend モードを備えています。このモードでは、アクティブなリクエストがすべて正常に完了されますが、新しいリクエストは許可されません。サーバーが中断されたら、シャットダウンすることができます。さらに、元の実行状態に戻ったり、中断状態のままメンテナンスを実行することができます。

注記

サーバーの一時停止によって管理インターフェイスが影響を受けることはありません。

管理コンソールまたは管理 CLI を使用するとサーバーを一時停止および再開できます。

サーバーの一時停止状態のチェック

以下の管理 CLI コマンドを使用するとサーバーの中断状態を表示できます。結果の値は、RUNNINGPRE_SUSPENDSUSPENDING、または SUSPENDED のいずれかになります。

  • スタンドアロンサーバーの中断状態をチェックします。

    :read-attribute(name=suspend-state)
    Copy to Clipboard Toggle word wrap
  • マネージドドメインのサーバーの中断状態をチェックします。

    /host=primary/server=server-one:read-attribute(name=suspend-state)
    Copy to Clipboard Toggle word wrap

中断

アクティブなリクエストが完了するまでサーバーが待機するタイムアウト値を秒単位で指定し、以下の管理 CLI コマンドを使用してサーバーを中断します。デフォルト値は 0 で、即座に中断します。-1 を値として指定すると、サーバーはアクティブなリクエストがすべて完了するまで無期限に待機します。

以下の各例は、リクエストが完了するまで最大 60 秒待機した後、一時停止します。

  • スタンドアロンサーバーを一時停止します。

    :suspend(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • マネージドドメインのすべてのサーバーを一時停止します。

    :suspend-servers(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • マネージドドメインの単一のサーバーを一時停止します。

    /host=primary/server-config=server-one:suspend(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • サーバーグループのすべてのサーバーを一時停止します。

    /server-group=main-server-group:suspend-servers(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • 特定のホストコントローラーによって管理されているサーバーをすべて一時停止します。

    /host=primary:suspend-servers(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap

再開

resume コマンドは、新しいリクエストを受け入れるために、サーバーを通常の実行状態に戻します。ホスト、サーバー、サーバーグループ、またはドメインレベルでコマンドを起動できます。以下に例を示します。

:resume
Copy to Clipboard Toggle word wrap

サーバーを一時停止状態で起動

サーバーを一時停止状態で起動し、サーバーが再開するまでリクエストを受け入れないようにすることができます。

  • スタンドアロンサーバーを一時停止状態で起動するには、JBoss EAP インスタンスの起動時に --start-mode=suspend ランタイム引数を使用します。

    $ EAP_HOME/bin/standalone.sh --start-mode=suspend
    Copy to Clipboard Toggle word wrap
  • マネージドドメインサーバーを一時停止モードで起動するには、管理 CLI コマンドで start-mode=suspend 引数を start 操作に渡します。

    /host=HOST_NAME/server-config=SERVER_NAME:start(start-mode=suspend)
    Copy to Clipboard Toggle word wrap
    注記

    start-mode 引数をサーバーの reload および restart 操作に渡すこともできます。

  • マネージドドメインサーバーグループのすべてのサーバーを一時停止モードで起動するには、管理 CLI コマンドで start-mode=suspend 引数を start-servers 操作に渡します。

    /server-group=SERVER_GROUP_NAME:start-servers(start-mode=suspend)
    Copy to Clipboard Toggle word wrap
    注記

    start-mode 引数をサーバーグループの reload-servers および restart-servers 操作に渡すこともできます。

2.3.2. 管理 CLI を使用したサーバーの正常なシャットダウン

サーバーの停止時に適切なタイムアウト値を指定すると、サーバーは正常にシャットダウンされます。コマンドを実行するとサーバーが一時停止され、すべてのリクエストが完了するまで最大で指定のタイムアウトの期間待機し、その後シャットダウンします。

以下の管理 CLI コマンドを使用してサーバーを正常にシャットダウンします。アクティブなリクエストが完了するまでサーバーが待機するタイムアウト値を秒単位で指定します。デフォルトは 0 で、サーバーを即座にシャットダウンします。-1 を値として指定すると、アクティブなリクエストがすべて完了するまで無期限に待機した後、シャットダウンします。

以下の各例は、リクエストが完了するまで最大 60 秒待機した後、シャットダウンします。

  • スタンドアロンサーバーを正常にシャットダウンします。

    shutdown --suspend-timeout=60
    Copy to Clipboard Toggle word wrap
  • マネージドドメインのすべてのサーバーを停止します。

    :stop-servers(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • マネージドドメインの単一のサーバーを停止します。

    /host=primary/server-config=server-one:stop(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • サーバーグループのすべてのサーバーを正常に停止します。

    /server-group=main-server-group:stop-servers(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap
  • ホストコントローラーとそれが管理するサーバーをすべてシャットダウンします。

    /host=primary:shutdown(suspend-timeout=60)
    Copy to Clipboard Toggle word wrap

suspend-timeout 属性は、ホストコントローラー自体ではなく、ホストコントローラーが管理するサーバーにのみ適用されます。

OS シグナルを使用したサーバーの正常なシャットダウン

org.wildfly.sigterm.suspend.timeout システムプロパティーを設定し、kill -15 PID などの OS TERM シグナルを送信することで、サーバーを正常にシャットダウンできます。デフォルトでは、この動作は管理 CLI の shutdown --suspend-timeout=0 コマンドと同じであるため、現在処理中のリクエストを即座に終了できます。org.wildfly.sigterm.suspend.timeout システムプロパティーでタイムアウトを設定できます。このプロパティーは、サーバーのシャットダウン前にリクエストの完了を待機する最大秒数を示します。-1 を値として指定すると、サーバーは永久に待機します。

重要

マネージドドメインでは、OS シグナルを使用してサーバーをシャットダウンしないでください。代わりに、管理ホストコントローラーから 管理 CLI または管理コンソールを使用してサーバーをシャットダウン する必要があります。

JVM がシグナル処理を無効にするように設定されている場合 (JVM オプションに -Xrs java 引数が渡される場合など)、または送信されたシグナルがプロセスが応答できるものではない場合 (KILL シグナルが送信された場合など)、OS シグナルを使用した正常なシャットダウンは機能しません。

2.4. JBoss EAP の起動および停止 (RPM インストール)

RPM インストールの場合、JBoss EAP の起動と停止が ZIP またはインストーラーインストールの場合とは異なります。

2.4.1. JBoss EAP の RPM インストールの開始

コマンドを使用して、スタンドアロンサーバーまたはマネージドドメインの動作モードで JBoss EAP の RPM インストールを開始できます。次のコマンドは、Red Hat Enterprise Linux (RHEL) 8 以降のバージョンにのみ対応していることに注意してください。

JBoss EAP をスタンドアロンサーバーとして起動する (RPM インストール)

$ sudo systemctl start eap8-standalone.service
Copy to Clipboard Toggle word wrap

これにより、standalone.xml 設定ファイルをデフォルトで使用して JBoss EAP が起動されます。JBoss EAP を別の スタンドアロンサーバー設定ファイル で起動するには、RPM サービス設定ファイル にプロパティーを設定します。詳細は、以下の RPM サービスプロパティーの設定 セクションを参照してください。

マネージドドメインで JBoss EAP を起動する (RPM インストール)

$ sudo systemctl start eap8-domain.service
Copy to Clipboard Toggle word wrap

これにより、host.xml 設定ファイルをデフォルトで使用して JBoss EAP が起動されます。JBoss EAP を別の マネージドドメイン設定ファイル で起動するには、RPM サービス設定ファイル にプロパティーを設定します。詳細は、以下の RPM サービスプロパティーの設定 セクションを参照してください。

2.4.2. RPM サービスプロパティーの設定

このセクションでは、RPM サービスプロパティーと JBoss EAP インストールのその他の起動オプションを設定する方法を説明します。変更を行う前に設定ファイルをバックアップすることが推奨されます。

RPM インストールで使用可能なすべての起動オプションのリストは、RPM サービス設定プロパティー セクションを参照してください。

重要

Red Hat Enterprise Linux 7 以降では、RPM サービス設定ファイルは systemd を使用してロードされるため、変数式は拡張されません。

  • サーバー設定ファイルを指定します。

    スタンドアロンサーバーを起動する場合、デフォルトで standalone.xml ファイルが使用されます。マネージドドメインで実行する場合、デフォルトで host.xml ファイルが使用されます。他の設定ファイルを使用して JBoss EAP を起動するには、適切な RPM 設定ファイル (例: eap8-standalone.conf) に WILDFLY_SERVER_CONFIG プロパティーを設定します。

    WILDFLY_SERVER_CONFIG=standalone-full.xml
    Copy to Clipboard Toggle word wrap
  • 特定の IP アドレスにバインドします。

    デフォルトでは、JBoss EAP RPM インストールは 0.0.0.0 にバインドします。JBoss EAP を特定の IP アドレスにバインドするには、適切な RPM 設定ファイル (例: eap8-standalone.conf) に WILDFLY_BIND プロパティーを設定します。

    WILDFLY_BIND=192.168.0.1
    Copy to Clipboard Toggle word wrap
    注記

    管理インターフェイスを特定の IP アドレスにバインドする場合は、次の例のように JBoss EAP 起動設定ファイルに設定を追加します。

  • JVM オプションまたは Java プロパティーを設定します。

    JBoss EAP の起動スクリプトに渡す JVM オプションまたは Java プロパティーを指定するには、起動設定ファイルを編集します。スタンドアロンサーバーの場合、このファイルは EAP_HOME/bin/standalone.conf になります。マネージドドメインの場合、このファイルは EAP_HOME/bin/domain.conf になります。以下の例は、ヒープサイズを設定し、JBoss EAP 管理インターフェイスを指定の IP アドレスにバインドします。

    JAVA_OPTS="$JAVA_OPTS -Xms2048m -Xmx2048m"
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address.management=192.168.0.1"
    Copy to Clipboard Toggle word wrap
    注記

    場合によっては、標準の jboss.bind.address プロパティーを使用せずに WILDFLY_BIND プロパティーを使用して JBoss EAP バインドアドレスを設定する必要があります。

注記

同じ名前のプロパティーが RPM サービス設定ファイル (例: /usr/lib/systemd/system/eap8-standalone.service:) と JBoss EAP 起動設定ファイル (例:EAP_HOME/bin/standalone.conf) にある場合、JBoss EAP 起動設定ファイルのプロパティーの値が優先されます。このようなプロパティーの 1 つが JAVA_HOME です。

2.4.3. JBoss EAP の RPM インストールの停止

コマンドを使用して、スタンドアロンサーバーまたはマネージドドメインの動作モードで JBoss EAP の RPM インストールを停止できます。次のコマンドは、Red Hat Enterprise Linux (RHEL) 8 以降のバージョンにのみ対応していることに注意してください。

スタンドアロンサーバーの JBoss EAP を停止する (RPM インストール)

$ sudo systemctl stop eap8-standalone.service
Copy to Clipboard Toggle word wrap

マネージドドメインで JBoss EAP を停止する (RPM インストール)

$ sudo systemctl stop eap8-domain.service
Copy to Clipboard Toggle word wrap

RPM インストールで使用可能なすべての起動オプションのリストは、RPM サービス設定ファイル セクションを参照してください。

2.5. Windows Server 用の PowerShell スクリプト

重要

複数の PowerShell スクリプトはテクノロジープレビューとしてのみ提供されます。テクノロジープレビュー機能は、実稼働環境での Red Hat サービスレベルアグリーメント (SLA) ではサポートされておらず、機能的に完全ではない可能性があるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

JBoss EAP には、ほとんどの JBoss EAP 管理スクリプトに相当する PowerShell スクリプトが含まれています。これには、Microsoft Windows Server で JBoss EAP を起動する PowerShell スクリプトが含まれます。

JBoss EAP PowerShell スクリプトは、テストされた Windows Server バージョンで実行される PowerShell バージョン 2 以上で動作することを目的としています。

JBoss EAP PowerShell スクリプトは EAP_HOME\bin にあり、JBoss EAP のバッチスクリプトとほぼ同様に使用されます。

たとえば、standalone-full.xml 設定ファイルを使用してスタンドアロン JBoss EAP サーバーを起動するには、以下の PowerShell コマンドを使用します。

.\standalone.ps1 "-c=standalone-full.xml"
Copy to Clipboard Toggle word wrap
注記

JBoss EAP PowerShell スクリプトの引数は引用符で囲む必要があります。

第3章 JBoss EAP の管理

コマンドライン管理 CLI、Web ベースの管理コンソール、Java API、または HTTP API を使用して JBoss EAP を設定できます。これらの管理インターフェイスを使用して加えられた変更は自動的に永続化され、XML 設定ファイルは管理 API によって上書きされます。方法としては、管理 CLI と管理コンソールの使用が推奨され、XML 設定ファイルの手作業による編集は推奨されません。これらは、JBoss EAP の起動時に管理 CLI を使用して変更できる設定ファイルの例です。

JBoss EAP は簡単な設定を使用し、スタンドアロンサーバーまたはマネージドドメインごとに 1 つの設定ファイルを使用します。別の設定ファイルが指定されていない場合、JBoss EAP は次のサンプル設定ファイルのいずれかを使用します。

  • スタンドアロンサーバーのデフォルト設定は、EAP_HOME/standalone/configuration/standalone.xml ファイルに保存されています。
  • マネージドドメインのデフォルト設定は、EAP_HOME/domain/configuration/domain.xml ファイルに保存されています。
  • ホストコントローラーのデフォルト設定は、EAP_HOME/domain/configuration/host.xml ファイルに保存されています。

JBoss EAP では、YAML 設定ファイルを使用してスタンドアロンサーバーを設定できます。詳細は、YAML 設定ファイルを使用したスタンドアロンサーバーの設定 を参照してください。

注記

マネージドドメイン内のサーバーでは、YAML 設定はサポートされて いません

3.1. サブシステム、エクステンション、プロファイルについて

JBoss EAP の各サブシステムは、JBoss EAP 機能のさまざまな側面を設定します。たとえば、logging サブシステムはアプリケーションとサーバーのロギングを設定します。

エクステンション は、サーバーのコア機能を拡張するモジュールです。エクステンションはデプロイメントが必要なときにロードされ、必要でなくなるとアンロードされます。

サブシステム は特定のエクステンションの設定オプションを提供します。利用可能なサブシステムの詳細は、JBoss EAP サブシステムの概要 を参照してください。

サーバーの要求を満たすために設定される プロファイル は、複数のサブシステムで設定されます。スタンドアロンサーバーには名前のないプロファイルが 1 つあります。マネージドドメインでは、ドメインのサーバーグループによって使用される プロファイル を複数定義できます。

管理コンソールまたは管理 CLI の使用

JBoss EAP インスタンスの設定更新には管理コンソールと管理 CLI の両方を使用でき、サポートされます。どちらを使用するかはユーザーの好みによります。グラフィカルな Web ベースのインターフェイスを好むユーザーは管理コンソールを使用する必要があります。コマンドラインインターフェイスを好むユーザーは、管理 CLI を使用する必要があります。

3.2. 管理ユーザー

デフォルトの JBoss EAP 設定はローカル認証を提供するため、ユーザーは認証の必要なくローカルホスト上で管理 CLI にアクセスできます。

しかし、リモートで管理 CLI にアクセスする場合や管理コンソールを使用する場合 (トラフィックの送信元がローカルホストであってもリモートアクセスとして見なされます) は、管理ユーザーを追加する必要があります。管理ユーザーを追加せずに管理コンソールへアクセスしようとすると、エラーメッセージが出力されます。

グラフィカルインストーラーを使用して JBoss EAP がインストールされた場合は、インストールプロセス中に管理ユーザーが作成されます。

このガイドでは、add-user スクリプトを使用した JBoss EAP の簡単なユーザー管理を取り上げます。このスクリプトはデフォルトの認証のプロパティーファイルに新しいユーザーを追加するためのユーティリティーです。

LDAP やロールベースアクセス制御 (RBAC) など、高度な認証および認可オプションは、JBoss EAP セキュリティーアーキテクチャーコア管理認証 セクションを参照してください。

3.2.1. 管理ユーザーの追加

管理ユーザーを追加するには、add-user ユーティリティースクリプトを使用できます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. add-user ユーティリティースクリプトを実行し、プロンプトに従います。

    $ EAP_HOME/bin/add-user.sh
    Copy to Clipboard Toggle word wrap
    注記

    Windows Server の場合は、EAP_HOME\bin\add-user.bat スクリプトを使用します。

  2. ENTER を押して、デフォルトのオプション a を選択し、管理ユーザーを追加します。

    このユーザーは ManagementRealm に追加され、管理コンソールまたは管理 CLI を使用して管理操作を実行する権限が与えられます。代わりに b を選択すると、アプリケーションに使用される ApplicationRealm にユーザーが追加され、特定のパーミッションは提供されません。

  3. ユーザー名とパスワードを入力します。入力後、パスワードを確認するよう指示されます。

    注記

    ユーザー名には、以下の文字のみを使用できます。文字の数と順番は自由です。

    • 英数字 (a-z、A-Z、0-9)
    • ダッシュ (-)、ピリオド (.)、コンマ (,)、アットマーク (@)
    • バックスラッシュ (\)
    • 等号 (=)

    JBoss EAP ではデフォルトで、脆弱なパスワードは許可されますが、警告が表示されます。

    このデフォルトの動作を変更する方法の詳細は、add-user ユーティリティーのパスワード制限の設定 を参照してください。

  4. ユーザーが属するグループのコンマ区切りリストを入力します。ユーザーがグループに属さないようにする場合は ENTER を押して空白のままにします。
  5. 情報を確認し、正しければ yes を入力します。

パラメーターを add-user スクリプトに渡すと、非対話的にユーザーを作成できます。ログや履歴ファイルにパスワードが表示されるため、この方法は共有システムでは推奨されません。詳細は add-user ユーティリティーの非対話的な実行 を参照してください。

3.2.2. add-user ユーティリティーの非対話的な実行

コマンドラインで引数を渡すと add-user スクリプトを非対話的に実行することができます。最低でも、ユーザー名とパスワードを提供する必要があります。

前提条件

  • JBoss EAP が実行中である。
警告

ログや履歴ファイルにパスワードが表示されるため、この方法は共有システムでは推奨されません。

複数のグループに属するユーザーの作成

以下のコマンドは、guest および mgmtgroup グループの管理ユーザー mgmtuser1 を追加します。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'
Copy to Clipboard Toggle word wrap
代替プロパティーファイルの指定

デフォルトでは、add-user スクリプトを使用して作成されたユーザーおよびグループ情報は、サーバー設定ディレクトリーにあるプロパティーファイルに保存されます。

ユーザー情報は以下のプロパティーファイルに保存されます。

  • EAP_HOME/standalone/configuration/mgmt-users.properties
  • EAP_HOME/domain/configuration/mgmt-users.properties

グループ情報は以下のプロパティーファイルに保存されます。

  • EAP_HOME/standalone/configuration/mgmt-groups.properties
  • EAP_HOME/domain/configuration/mgmt-groups.properties

これらのデフォルトディレクトリーとプロパティーファイル名はオーバーライドできます。以下のコマンドは、ユーザープロパティーファイルの名前と場所を指定して、新しいユーザーを追加します。

$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'
Copy to Clipboard Toggle word wrap

新しいユーザーは /path/to/standaloneconfig/newname.properties および /path/to/domainconfig/newname.properties にあるユーザープロパティーファイルに追加されます。これらのファイルは存在している必要があり、存在しない場合はエラーが出力されます。

使用可能なすべての add-user 引数とその目的の完全なリストは、--help 引数を使用するか、add-user ユーティリティー引数 セクションを参照してください。

3.2.3. add-user ユーティリティーのパスワード制限

add-user ユーティリティースクリプトのパスワード制限は、EAP_HOME/bin/add-user.properties ファイルを使用して設定できます。

重要

add-user.properties ファイルは保護されていないプレーンテキストファイルです。コンテンツへの不正アクセスを回避するために保護する必要があります。

意図しないパスワードを設定しないようにするには、キーボードのシステムキーマップが正しいことを確認します。デフォルトのシステムキーマップは en-qwerty です。このデフォルト設定を変更して新しいパスワードを作成する場合は、SimplePasswordStrengthChecker クラスにある基準をパスワードが満たしていることを確認する必要があります。

JBoss EAP ではデフォルトで、脆弱なパスワードは許可されますが、警告が表示されます。指定の最低要件を満たさないパスワードを拒否するには、password.restriction プロパティーを REJECT に設定します。

以下の表は、EAP_HOME/bin/add-user.properties ファイルで設定できる追加のパスワード要件の設定を示しています。

Expand
表3.1 パスワード要件の追加設定
属性説明

minLength

パスワードの最小文字数。たとえば、password.restriction.minLength=8 はパスワードを最小文字に制限します。

strength

有効なパスワードに必要なしきい値を設定します。有効なしきい値エントリーには以下が含まれます。

* VERY_WEAK

* WEAK

* MODERATE

* MEDIUM

* STRONG

* VERY_STRONG

* EXCEPTIONAL

デフォルト値は MODERATE です。しきい値が定義され、そのデフォルト値が SimplePasswordStrengthChecker クラスに指定されます。

注記: しきい値を指定しない場合は、MODERATE がデフォルト値になります。この値は SimplePasswordStrengthChecker クラスに指定されます。

minAlpha

パスワードに設定されたアルファベットの最小文字数。たとえば、password.restriction.minAlpha=1 は、パスワードに最低 1 文字のアルファベット文字を含めるよう制限します。

minDigit

パスワードに設定された数字の最小数。たとえば、password.restriction.minDigit=1 は、最低でも 1 つの数字を含むようにパスワードを制限します。

minSymbol

パスワードに設定された記号の最小数。たとえば、password.restriction.minSymbol=1 は、パスワードに記号を最低でも 1 文字含めるよう制限します。

forbiddenValue

簡単に思いつくパスワード (root など) を設定しないように、ユーザーを制限します。たとえば、password.restriction.forbidden=root,admin,administrator は、パスワードとして rootadmin、または administrator を設定できないように制限します。

mustNotMatchUsername

ユーザーがユーザー名をパスワードとして設定できないように制限します。たとえば、password.restriction.mustNotMatchUsername=TRUE と指定すると、ユーザーはユーザー名をパスワードとして設定できなくなります。false に設定すると、このルールは無視されます。

関連情報

Red Hat カスタマーポータルの 基本的なシステム設定 を参照してください。

3.2.4. 管理ユーザーの更新

add-user ユーティリティースクリプトを使用し、プロンプトに従ってユーザー名を入力すると、既存の管理ユーザーの設定を更新できます。

$ EAP_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.
Using realm 'ManagementRealm' as discovered from the existing property files.
Username : test-user
User 'test-user' already exists and is enabled, would you like to...
 a) Update the existing user password and roles
 b) Disable the existing user
 c) Type a new username
(a):
Copy to Clipboard Toggle word wrap

すでに存在するユーザー名を入力すると、複数のオプションが出力されます。

  • 既存ユーザーのパスワードを更新する場合は a を入力します。
  • 既存ユーザーを無効にする場合は b を入力します。
  • 新しいユーザー名を入力する場合は c を入力します。
警告

add-user スクリプトを使用して非対話的にユーザーを更新すると、ユーザーは自動的に更新され、確認のプロンプトは表示されません。

3.3. 管理インターフェイス

3.3.1. 管理 CLI

管理コマンドラインインターフェイス (CLI) は、JBoss EAP のコマンドライン管理ツールです。

管理 CLI を使用して、サーバーの起動および停止、アプリケーションのデプロイおよびアンデプロイ、システムの設定、他の管理タスクの実行を行います。操作はバッチモードで実行できるため、複数のタスクをグループとして実行できます。

lscdpwd など、多くの共通するターミナルコマンドを使用できます。管理 CLI はタブ補完をサポートします。

コマンドと操作、構文、およびバッチモードでの実行を含む、管理 CLI の使用に関する詳細は、JBoss EAP の 管理 CLI ガイド を参照してください。

管理 CLI の起動
$ EAP_HOME/bin/jboss-cli.sh
Copy to Clipboard Toggle word wrap
注記

Windows Server の場合は、EAP_HOME\bin\jboss-cli.bat スクリプトを使用します。

稼働中のサーバーへの接続
connect
Copy to Clipboard Toggle word wrap

上記の代わりに、管理 CLI を起動し、EAP_HOME/bin/jboss-cli.sh --connect コマンドを使用すると 1 度に接続できます。

ヘルプの表示

以下のコマンドを実行してヘルプを表示します。

help
Copy to Clipboard Toggle word wrap

コマンドで --help フラグを使用すると、そのコマンドの使用に関する説明が表示されます。たとえば、deploy コマンドの使用に関する情報を表示するには、以下のコマンドを実行します。

deploy --help
Copy to Clipboard Toggle word wrap
管理 CLI の終了
quit
Copy to Clipboard Toggle word wrap
システム設定の表示

以下のコマンドは read-attribute 操作を使用して、データソースの例が有効になっているかどうかを表示します。

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
{
    "outcome" => "success",
    "result" => true
}
Copy to Clipboard Toggle word wrap

マネージドドメインで実行している場合、コマンドの前に /profile=PROFILE_NAME を付けて更新するプロファイルを指定する必要があります。

/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
Copy to Clipboard Toggle word wrap
システム設定の更新

以下のコマンドは write-attribute 操作を使用して、データソースの例を無効にします。

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
Copy to Clipboard Toggle word wrap
サーバーの起動

マネージドドメインで実行している場合、管理 CLI を使用してサーバーを起動および停止することもできます。

/host=HOST_NAME/server=server-one:start
Copy to Clipboard Toggle word wrap

3.3.2. 管理コンソールの概要

管理コンソールは、JBoss EAP の Web ベースの管理ツールです。

管理コンソールを使用して、サーバーの開始および停止、アプリケーションのデプロイおよび削除、システム設定の調整、サーバー設定の変更の永続化を行います。管理コンソールは、サーバーの再起動またはリロードが必要な変更をユーザーが行ったときに、ライブ通知を使用して管理タスクを実行することもできます。

管理対象ドメインでは、同じドメインのサーバーインスタンスとサーバーグループをドメインコントローラーの管理コンソールから集中管理できます。

デフォルトの管理ポートを使用してローカルホストで稼働している JBoss EAP インスタンスの場合、Web ブラウザーを使用して http://localhost:9990/console/index.html で管理コンソールにアクセスできます。管理コンソールにアクセスするには、必要なロールを持つユーザーとしてログインします。

管理コンソールでは、JBoss EAP スタンドアロンサーバーまたはマネージドドメインを操作および管理するために以下のタブが提供されます。

Homepage
一般的な設定および管理タスクを行う方法を学ぶことができます。ツアーに参加して JBoss EAP 管理コンソールをよく理解してください。
Deployments
デプロイメントを追加、削除、および有効化します。マネージドドメインでは、デプロイメントをサーバーグループに割り当てます。
Configuration
Web サービス、メッセージング、高可用性などの機能を提供する利用可能なサブシステムを設定します。マネージドドメインでは、異なるサブシステム設定が含まれるプロファイルを管理します。
Runtime
サーバーの状態、JVM 使用率、サーバーログなどのランタイム情報を表示します。マネージドドメインではホスト、サーバーグループ、およびサーバーを管理します。
Update Manager
既存のインストールを更新し、チャネルを管理します。
Access control
ロールベースのアクセス制御を使用するときのユーザーとグループにロールを割り当てます。
3.3.2.1. 管理コンソールでのリソース属性の更新

必要な権限を持っている場合は、管理コンソールでリソース属性を編集できます。

前提条件

  • JBoss EAP が実行中である。
  • 選択したリソースを変更するための適切な権限を持っている。
  • ユーザーを作成している。

手順

  1. 管理コンソールにログインします。デフォルトのポートで実行されているローカルサーバーの場合は、http://localhost:9990/console/index.html で管理コンソールにアクセスできます。
  2. 管理コンソールの適切なセクションに移動し、変更するリソースを探します。
  3. Edit をクリックします。
  4. 必要な変更を行います。

    必須フィールドにはアスタリスク (*) が付いています。Help をクリックすると、属性の説明を表示できます。

    注記

    入力フィールドは、属性のタイプに応じて、テキストフィールド、ON/OFF フィールド、またはドロップダウンになります。一部のテキストフィールドでは、入力すると、設定内の他の場所の値が候補として表示されます。

  5. Save をクリックします。
  6. 必要な場合は、サーバーをリロードして変更を反映します。

    有効にするためにリロードが必要な変更を加えると、ポップアップウィンドウが開きます。スタンドアロンサーバーをリロードするには、ポップアップウィンドウで Reload をクリックします。マネージドドメイン内のサーバーをリロードするには、Topology をクリックし、適切なサーバーを選択して、ドロップダウンリストから Reload を選択します。

最近実行した設定アクションの履歴を表示するには、通知アイコンをクリックします。

3.3.2.2. 管理コンソールの有効化または無効化

/core-service=management/management-interface=http-interface リソースの console-enabled ブール値属性を設定すると、管理コンソールを有効または無効にできます。ドメインモードのプライマリーホストの場合は、/host=primary/core-service=management/management-interface=http-interface を使用します。

注記

管理コンソールを有効または無効にした後、JBoss EAP インスタンスを再起動またはリロードする必要があります。

管理コンソールを有効にする場合の例

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=true)
Copy to Clipboard Toggle word wrap

管理コンソールを無効にする場合の例

/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=false)
Copy to Clipboard Toggle word wrap

3.3.2.3. 管理コンソールの言語の変更

管理リソースの言語はデフォルトの英語に設定されています。代わりに、次のいずれかの言語を使用することもできます。

  • ドイツ語 (de)
  • 簡体中国語 (zh-Hans)
  • ブラジルポルトガル語 (pt-BR)
  • フランス語 (fr)
  • スペイン語 (es)
  • 日本語 (ja)

前提条件

  • JBoss EAP が実行中である。
  • ユーザーを作成している。

手順

  1. 管理コンソールにログインします。デフォルトのポートで実行されているローカルサーバーの場合は、http://localhost:9990/console/index.html で管理コンソールにアクセスできます。
  2. Settings をクリックします。
  3. Locale リストから必要な言語を選択します。
  4. Save をクリックします。確認ボックスに、アプリケーションのリロードが必要であると表示されます。
  5. Yes をクリックします。システムによってブラウザーが自動的に更新され、選択したロケールが使用されます。
3.3.2.4. 管理コンソールのタイトルのカスタマイズ

各 JBoss EAP インスタンスを迅速かつ簡単に識別できるように、管理コンソールのタイトルをカスタマイズできます。管理コンソールのタイトルをカスタマイズした場合、管理コンソールのインスタンスを閉じると、変更が保持されません。コンソールの新しいインスタンスを開いてログインすると、管理コンソールのタイトルがリセットされます。

前提条件

  • JBoss EAP が実行中である。
  • ユーザーを作成している。

手順

  1. 管理コンソールにログインします。デフォルトのポートで実行されているローカルサーバーの場合は、http://localhost:9990/console/index.html で管理コンソールにアクセスできます。
  2. Settings をクリックし、Title フィールドでタイトルを変更します。
  3. Save をクリックします。

    確認ボックスに、管理コンソールのリロードが必要であることが表示されます。

  4. Yes をクリックします。

    システムは Web ブラウザーを自動的に更新し、新しいタイトルがタブヘッダーに表示されます。

3.4. 管理 API

管理 API エンドポイントは、管理クライアントが JBoss EAP 管理レイヤーと統合するためのエントリーポイントとして機能します。

3.4.1. HTTP API

HTTP API のエンドポイントは、HTTP プロトコルに依存して JBoss EAP 管理レイヤーと統合する管理クライアントのエントリーポイントです。

HTTP API は、JBoss EAP 管理コンソールによって使用されますが、他のクライアントの統合機能も提供します。デフォルトでは、http://HOST_NAME:9990/management で HTTP API にアクセスできます。この URL は、API に公開される raw 属性および値を表示します。

リソースの読み取り

HTTP POST メソッドを使用して他の操作を読み取り、書き込み、および実行できますが、GET リクエストを使用すると一部の読み取り操作を実行できます。HTTP GET メソッドは以下の URL 形式を使用します。

http://HOST_NAME:9990/management/PATH_TO_RESOURCE?operation=OPERATION&PARAMETER=VALUE
Copy to Clipboard Toggle word wrap

置き換え可能な値は必ず適切な値に置き換えてください。置き換え可能な OPERATION の値は、以下の値に置き換えられます。

Expand
Value説明

attribute

read-attribute 操作を実行します。

operation-description

read-operation-description 操作を実行します。

operation-names

read-operation-names 操作を実行します。

resource

read-resource 操作を実行します。

resource-description

read-resource-description 操作を実行します。

snapshots

list-snapshots 操作を実行します。

以下の URL 例は、HTTP API を使用して読み取り操作を実行する方法を示しています。

例: リソースのすべての属性と値の読み取り

http://HOST_NAME:9990/management/subsystem/undertow/server/default-server/http-listener/default
Copy to Clipboard Toggle word wrap

これは、default HTTP リスナーのすべての属性とそれらの値を表示します。

注記

デフォルトの操作は read-resource です。

例: リソースの属性値の読み取り

http://HOST_NAME:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled
Copy to Clipboard Toggle word wrap

これは、ExampleDS データソースの enabled 属性の値を読み取ります。

リソースの更新

HTTP POST メソッドを使用して設定値を更新するか、HTTP API を使用して他の操作を実行できます。これらの操作の認証を提供する必要があります。

以下の例は、HTTP API を使用してリソースを更新する方法を示しています。

例: リソースの属性値の更新

$ curl --digest http://HOST_NAME:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"write-attribute", "address":["subsystem","datasources","data-source","ExampleDS"], "name":"enabled", "value":"false", "json.pretty":"1"}'
Copy to Clipboard Toggle word wrap

これは、ExampleDS データソースの enabled 属性の値を false に更新します。

例: サーバーに対する操作の実行

$ curl --digest http://localhost:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"reload"}'
Copy to Clipboard Toggle word wrap

これは、サーバーをリロードします。

HTTP API を使用して JBoss EAP にアプリケーションをデプロイする方法は、HTTP API を使用したアプリケーションのデプロイ を参照してください

3.4.1.1. custom-constant HTTP ヘッダー

JBoss EAP の HTTP 管理エンドポイントは、クライアントに送信されるすべての応答で事前定義された HTTP ヘッダーのセットを返します。この事前定義された HTTP ヘッダーのセットに加えて、custom-constant HTTP ヘッダーを定義できます。

JBoss EAP は、以下のように custom-constant HTTP ヘッダーをリクエストに適用します。

  • JBoss EAP は、リクエストパスに対して設定された接頭辞を照合して、custom-constant HTTP ヘッダーを適用します。

    たとえば、//management などのリクエストパスのリクエストに、custom-constant HTTP ヘッダーをマップできます。

  • リクエストが複数の接頭辞に一致する場合、JBoss EAP はすべてのマッピングから custom-constant HTTP ヘッダーを適用します。

    たとえば、パス /management へのリクエストは、//management の両方のマッピングと一致します。JBoss EAP は両方のマッピングからヘッダーを適用します。

  • リクエストの処理の最後に、応答がクライアントに返される前に、対応するエンドポイントによって設定されたヘッダーをオーバーライドします。

    たとえば、管理エンドポイントは各応答に X-Frame-Options ヘッダーを設定します。X-Frame-Options という名前の custom-constant HTTP ヘッダーを定義すると、custom-constant HTTP ヘッダーがデフォルトのヘッダーをオーバーライドします。

複数の custom-constant HTTP ヘッダーが、単一のマッピングのレスポンスで返されるように定義できます。

custom-constant HTTP ヘッダーを定義するルールは次のとおりです。

  • custom-constant HTTP ヘッダーには、RFC-7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content でサポートされている文字のみを使用できます。
  • 次の定義済み HTTP ヘッダーをオーバーライドすることはできません。

    • Connection
    • Content-Length
    • Content-Type
    • Date
    • Transfer-Encoding

      これらの定義済みヘッダーのいずれかをオーバーライドしようとすると、エラーが発生します。

    • たとえば、Date という名前で custom-constant HTTP ヘッダーを設定しようとすると、次のエラーが返されます。

      {
          "outcome" => "failed",
          "failure-description" => "WFLYCTL0458:Disallowed HTTP Header name 'Date'",
          "rolled-back" => true
      }
      Copy to Clipboard Toggle word wrap

custom-constant HTTP ヘッダーを作成する際の重要な考慮事項:

  • JBoss EAP は指定されたパスにアクセスできるかどうかを検証しません。
  • サブシステムは、HTTP 管理インターフェイスがサポートするコンテキストを動的に追加できます。
  • custom-constant HTTP ヘッダーは、エンドポイントがリクエストへの応答を処理する方法を変更しません。
3.4.1.2. custom-constant HTTP ヘッダーの定義

必要なパス接頭辞への各レスポンスで返される custom-constant HTTP ヘッダーを定義します。

重要

custom-constant HTTP ヘッダーを作成する前に、以下の考慮事項を理解する必要があります。

  • JBoss EAP は指定されたパスにアクセスできるかどうかを検証 しません
  • サブシステムは、HTTP 管理インターフェイスがサポートするコンテキストを動的に追加できます。
  • custom-constant HTTP ヘッダーは、エンドポイントがリクエストへの応答を処理する方法を変更しません。

手順

  1. custom-constant HTTP ヘッダーを定義します。

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="PATH_PREFIX",headers=[{name="HEADER_NAME",value="HEADER_VALUE"}]}])
    Copy to Clipboard Toggle word wrap
    重要

    write-attribute 操作を使用すると、reload-required プロンプトが開きます。

  2. 変更を反映するためにサーバーをリロードします。

    reload
    Copy to Clipboard Toggle word wrap

    HTTP 管理インターフェイスへのリクエストが、事前定義された HTTP ヘッダーのセットに加えて、HEADER_VALUE の値で HTTP ヘッダー HEADER_NAME を返すようになりました。

    custom-constant HTTP ヘッダー X-help の例

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="/",headers=[{name="X-Help",value="http://mywebsite.com/help"}]}])
    Copy to Clipboard Toggle word wrap

検証手順

  • HTTP 管理インターフェイスにリクエストを送信します。

    curl -s -D - -o /dev/null --digest http://localhost:9990/management/ -u USERNAME:PASSWORD
    Copy to Clipboard Toggle word wrap

    custom-constant HTTP ヘッダー X-Help の例のレスポンス例

    admin:redhat
    HTTP/1.1 200 OK
    Connection: keep-alive
    X-Frame-Options: SAMEORIGIN
    Content-Type: application/json; charset=utf-8
    Content-Length: 3312
    X-Help: http://mywebsite.com
    Date: Tue, 27 Oct 2020 08:13:17 GMT
    Copy to Clipboard Toggle word wrap

    レスポンスには、X-Help custom-constant HTTP ヘッダーが含まれます。

3.4.1.3. custom-constant HTTP ヘッダーを定義する CLI コマンド

以下の CLI コマンドは、スタンドアロンおよびマネージドドメインモードで custom-constant HTTP ヘッダーを定義します。

スタンドアロンモード

  • 単一の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADERVALUE}]}])
    Copy to Clipboard Toggle word wrap

    このコマンドにより、XML 設定は以下のようになります。

    <management-interfaces>
        <http-interface http-authentication-factory="management-http-authentication">
            <http-upgrade enabled="true" sasl-authentication-factory="management-sasl-authentication/>
            <socket-binding http="management-http"/>
            <constant-headers>
                <header-mapping path="/PREFIX">
                    <header name="X-HEADER" value="HEADERVALUE"/>
                </header-mapping>
            </constant-headers>
        </http-interface>
    </management-interfaces>
    Copy to Clipboard Toggle word wrap
  • 複数の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX1,headers=[{name=X-HEADER,value=HEADERVALUE-FOR-X}]},{path=/PREFIX2,headers=[{name=Y-HEADER,value=HEADERVALUE-FOR-Y}]}])
    Copy to Clipboard Toggle word wrap

ドメインモード

  • 単一の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。

    /host=primary/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADER-VALUE}]}])
    Copy to Clipboard Toggle word wrap

    このコマンドにより、XML 設定は以下のようになります。

    <management-interfaces>
        <http-interface http-authentication-factory="management-http-authentication">
            <http-upgrade enabled="true" sasl-authentication-factory="management-sasl-authentication/>
            <socket interface="management" port="${jboss.management.http.port:9990}"/>
            <constant-headers>
                <header-mapping path="/PREFIX">
                    <header name="X-HEADER" value="HEADER-VALUE"/>
                </header-mapping>
            </constant-headers>
        </http-interface>
    </management-interfaces>
    Copy to Clipboard Toggle word wrap
  • 複数の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。

    /host=primary/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[ {path=/PREFIX-1,headers=[{name=X-HEADER,value=HEADER-VALUE-FOR-X}]},{path=/PREFIX-2,headers=[{name=Y-HEADER,value=HEADER-VALUE-FOR-Y}]}])
    Copy to Clipboard Toggle word wrap

3.4.2. ネイティブ API

ネイティブ API のエンドポイントは、ネイティブプロトコルに依存して JBoss EAP 管理レイヤーと統合する管理クライアントのエントリーポイントです。ネイティブ API は JBoss EAP 管理 CLI によって使用されますが、他のクライアントの統合機能も提供します。

以下の Java コードは、ネイティブ API を使用して Java コードから管理操作を実行する方法の例を示しています。

注記

EAP_HOME/bin/client/jboss-cli-client.jar ファイルにある、必要な JBoss EAP ライブラリーをクラスパスに追加する必要があります。

例: ネイティブ API を使用したリソースの読み取り

// Create the management client
import org.jboss.dmr.ModelNode;
import org.jboss.as.controller.client.ModelControllerClient;
ModelControllerClient client = ModelControllerClient.Factory.create("localhost", 9990);

// Create the operation request
ModelNode op = new ModelNode();

// Set the operation
op.get("operation").set("read-resource");

// Set the address
ModelNode address = op.get("address");
address.add("subsystem", "undertow");
address.add("server", "default-server");
address.add("http-listener", "default");

// Execute the operation and manipulate the result
ModelNode returnVal = client.execute(op);
System.out.println("Outcome: " + returnVal.get("outcome").toString());
System.out.println("Result: " + returnVal.get("result").toString());

// Close the client
client.close();
Copy to Clipboard Toggle word wrap

3.5. 設定データ

3.5.1. スタンドアロンサーバー設定ファイル

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

Expand
表3.2 スタンドアロン設定ファイル
設定ファイル目的

standalone.xml

このスタンドアロン設定ファイルは、Jakarta EE Web Profile 認定設定であり、スタンドアロンサーバーの起動時に JBoss EAP が使用するデフォルト設定です。この設定には、サブシステム、ネットワーク、デプロイメント、ソケットバインディング、および Jakarta EE Web Profile の他の設定可能な詳細など、サーバーに関するすべての情報が含まれています。この設定では、メッセージングや高可用性のために必要なサブシステムは提供されません。

standalone-ha.xml

このスタンドアロン設定ファイルは、高可用性を提供する Jakarta EE Web Profile 認定設定です。このファイルには、すべてのデフォルトサブシステムが含まれており、高可用性に必要な modcluster および jgroups サブシステムが追加されています。メッセージングに必要なサブシステムは提供しません。

standalone-full.xml

このスタンドアロン設定ファイルは、Jakarta EE Full Platform 認定設定です。このファイルには、すべてのデフォルトサブシステムが含まれており、messaging-activemq および iiop-openjdk サブシステムが追加されています。高可用性に必要なサブシステムは提供しません。

standalone-full-ha.xml

このスタンドアロン設定ファイルは、Jakarta EE Full Platform 認定設定です。このファイルには、メッセージング用や高可用性用のサブシステムを含め、あらゆるサブシステムのサポートが含まれています。

standalone-load-balancer.xml

このスタンドアロン設定ファイルには、ビルトインの mod_cluster フロントエンドロードバランサーを使用して他の JBoss EAP インスタンスの負荷を分散するために必要な最低限のサブシステムが含まれます。

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

$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml
Copy to Clipboard Toggle word wrap
YAML ファイルを使用したスタンドアロンサーバーの更新

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

注記

マネージドドメイン内のサーバーでは、YAML 設定はサポートされて いません

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

  • core-service
  • interface
  • socket-binding-group
  • subsystem
  • system-property

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

  • extension: サーバーにエクステンションを追加します。この要素は、不足しているモジュールを必要とする可能性があるため、サポートされていません。
  • deployment: サーバーにデプロイメントを追加します。この要素は、設定に加えてより広範な変更が必要となるため、サポートされていません。
  • deployment-overlay: デプロイメントオーバーレイをサーバーに追加します。この要素は、設定に加えてより広範な変更が必要となるため、サポートされていません。
  • path: YAML ファイルの解析時にすでに定義されています。

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

新しい PostGresql データソースを定義する 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
Copy to Clipboard Toggle word wrap

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

注記

YAML 設定ファイルを使用してモジュールを管理することはできません。代わりに、org.postgresql.jdbc モジュールを手動で、または管理 CLI を使用して作成またはプロビジョニングする必要があります。

3.5.1.1. タグを使用した YAML ファイルの操作

タグを使用して、YAML 設定ファイルに対していくつかの操作を実行できます。

  • !undefine: 属性を未定義にする

    CONSOLE ロガーレベルを未定義にする YAML 設定ファイルの例

    wildfly-configuration:
        subsystem:
            logging:
              console-handler:
                CONSOLE:
                  level: !undefine
    Copy to Clipboard Toggle word wrap

  • !remove: リソースを削除する

    組み込みの Artemis ブローカーを削除し、リモートブローカーに接続する YAML 設定ファイルの例

    wildfly-configuration:
      socket-binding-group:
        standard-sockets:
          remote-destination-outbound-socket-binding:
            remote-artemis:
              host: localhost
              port: 61616
      subsystem:
        messaging-activemq:
          server:
            default: !remove
          remote-connector:
            artemis:
              socket-binding: remote-artemis
          pooled-connection-factory:
            RemoteConnectionFactory:
              connectors:
                - artemis
              entries:
                - "java:jboss/RemoteConnectionFactory"
                - "java:jboss/exported/jms/RemoteConnectionFactory"
              enable-amq1-prefix: false
              user: admin
              password: admin
        ejb3:
          default-resource-adapter-name: RemoteConnectionFactory
        ee:
          service:
            default-bindings:
              jms-connection-factory: "java:jboss/RemoteConnectionFactory"
    Copy to Clipboard Toggle word wrap

  • !list-add: リストに要素を追加する (必要に応じてインデックスを指定)

    権限リストに RemoteTransactionPermission を追加する YAML 設定ファイルの例

    wildfly-configuration:
        subsystem:
            elytron:
              permission-set:
               default-permissions:
                 permissions: !list-add
                  - class-name: org.wildfly.transaction.client.RemoteTransactionPermission
                    module: org.wildfly.transaction.client
                    target-name: "*"
                    index: 0
    Copy to Clipboard Toggle word wrap

    注記

    index 属性が定義されていない場合、エントリーはリストの末尾に追加されます。

3.5.1.2. YAML ファイルを使用したスタンドアロンサーバーの起動

YAML 設定ファイルを使用してスタンドアロンサーバーを起動できます。

手順

  1. ターミナルを開きます。
  2. 次のコマンドを使用して、YAML ファイルを使用してスタンドアロンサーバーを起動します。

    ./standalone.sh -y=/home/ehsavoie/dev/wildfly/config2.yml:config.yml -c standalone-full.xml
    Copy to Clipboard Toggle word wrap

    --yaml または -y 引数を指定すると、YAML ファイルのリストを渡すことができます。各 YAML ファイルパスを区切る必要があります。Windows Server の場合はセミコロン (;)、Mac および Unix ベースのオペレーティングシステムの場合はコロン (:) を使用して区切ります。絶対パス、現在の実行ディレクトリーからの相対パス、またはスタンドアロン設定ディレクトリーからの相対パスを使用できます。

    操作は、最初の操作が XML 設定によって定義された後、ファイルの定義順に適用されます。

3.5.2. マネージドドメイン設定ファイル

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

Expand
表3.3 マネージドドメイン設定ファイル
設定ファイル目的

domain.xml

これは、マネージドドメインの主要設定ファイルです。このファイルを読み取りできるのはドメインコントローラーのみです。このファイルには、すべてのプロファイル (defaulthafullfull-ha、および load-balancer) の設定が含まれています。

host.xml

このファイルには、マネージドドメインの物理ホスト固有の設定情報が含まれています (ネットワークインターフェイス、ソケットバインディング、ホスト名、その他のホスト固有の詳細など)。host.xml ファイルは、ファイル自身をマネージドドメインコントローラーとして定義し、サーバーインスタンスを起動できます。これには、この表で説明されている host-primary.xmlhost-secondary.xml の両方の機能がすべて含まれています。

host-primary.xml

このファイルには、サーバーを管理対象ドメインコントローラーとして実行するために必要な設定情報のみが含まれています。host-primary.xml ファイルは、ファイル自身をドメインコントローラーとして定義します。サーバーインスタンスは定義しません。

host-secondary.xml

このファイルには、サーバーをマネージドドメインのホストコントローラーとして実行するために必要な設定情報のみが含まれています。このファイルではドメインコントローラーが定義されていないため、host-secondary.xml の接続先のドメインコントローラーアドレスを設定する必要があります。この xml ファイルは、host-secondary.xml がマシン上で実行され、リモートドメインコントローラーによって管理される設定の例を表しています。マシンは、サーバーインスタンスを定義および起動するためのホストコントローラーとして機能します。ドメインコントローラーは、これらのサーバーインスタンスを管理します。

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

$ EAP_HOME/bin/domain.sh --host-config=host-primary.xml
Copy to Clipboard Toggle word wrap

3.5.3. 設定データのバックアップ

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

  • EAP_HOME/standalone/configuration/

    • ディレクトリー全体をバックアップして、スタンドアロンサーバーのユーザーデータ、サーバー設定、およびロギング設定を保存します。
  • EAP_HOME/standalone/data

    • data/content ディレクトリーに限定されている管理されたデプロイメントのデータをバックアップします。
  • EAP_HOME/standalone/deployments

    • スタンドアロンサーバーのデプロイメントをバックアップします。
  • EAP_HOME/domain/configuration/

    • ディレクトリー全体をバックアップして、マネージドドメインのユーザーおよびプロファイルデータ、ドメインおよびホスト設定、およびロギング設定を保存します。
  • EAP_HOME/domain/data

    • データ/コンテンツディレクトリーに限定されている管理対象ドメインおよび管理対象ドメイン内のデプロイメントのデータをバックアップします。
  • EAP_HOME/modules/

    • カスタムモジュールをバックアップします。
  • EAP_HOME/welcome-content/

    • カスタムのウェルカムコンテンツをバックアップします。
  • EAP_HOME/bin/

    • カスタムスクリプトまたは起動設定ファイルをバックアップします。

3.5.4. 設定ファイルのスナップショット

サーバーの保守や管理をしやすくするため、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"
}
Copy to Clipboard Toggle word wrap
スナップショットのリスト

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

:list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20151022-133109702standalone.xml",
            "20151022-132715958standalone.xml"
        ]
    }
}
Copy to Clipboard Toggle word wrap
スナップショットの削除

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

:delete-snapshot(name=20151022-133109702standalone.xml)
Copy to Clipboard Toggle word wrap

3.5.5. スナップショットを使用したサーバーの起動

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

前提条件

  • JBoss EAP がインストールされている。
  • 設定ファイルのスナップショットを取得している。

手順

  1. EAP_HOME/standalone/configuration/standalone_xml_history ディレクトリーへ移動し、ロードするスナップショットまたは保存された設定ファイルを確認します。
  2. サーバーを起動し、選択した設定ファイルを示します。設定ディレクトリー EAP_HOME/standalone/configuration/ からの相対パスを渡します。

    $ EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20151022-133109702standalone.xml
    Copy to Clipboard Toggle word wrap
注記

管理対象ドメインでサーバーを実行している場合は、代わりに --host-config および --domain-config=<config> 引数を使用して設定ファイルを指定します。

3.5.6. 設定変更の確認

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

重要

変更はメモリーに保存され、サーバーを再起動すると永続化されません。この機能は 管理監査ロギング の代替機能ではありません。

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

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

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

/subsystem=core-management/service=configuration-changes:add(max-history=20)
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、ホストおよびサーバー関連の設定変更はホストレベルで追跡されます。ホストコントローラーの設定変更を可能にすると、そのホストコントローラーが管理するサーバーすべてで設定の変更が可能になります。以下のコマンドを使用すると、ホストごとに設定の変更を追跡できます。

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:add(max-history=20)
Copy to Clipboard Toggle word wrap

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

/subsystem=core-management/service=configuration-changes:list-changes
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、以下のコマンドを使用してホストの設定変更をリストできます。

/host=HOST_NAME/subsystem=core-management/service=configuration-changes:list-changes
Copy to Clipboard Toggle word wrap

以下のコマンドを使用すると、特定のサーバーに影響する設定の変更をリストできます。

/host=HOST_NAME/server=SERVER_NAME/subsystem=core-management/service=configuration-changes:list-changes
Copy to Clipboard Toggle word wrap

このコマンドは、各設定変更とその変更日、変更元、結果、および操作の詳細をリストで表示します。たとえば、以下の 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"}
            }]
        }
    ]
}
Copy to Clipboard Toggle word wrap

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

  • 管理 CLI から行ったサーバーのリロード。
  • 管理 CLI から行った ExampleDS データソースの無効化。
  • 管理コンソールから行った ExpiryQueue キューの削除。
管理コンソールからの設定変更の追跡および表示

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

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

3.5.7. プロパティーの置き換え

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

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

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

/subsystem=datasources:read-resource-description(recursive=true)
Copy to Clipboard Toggle word wrap

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

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

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

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

<interface name="public">
    <inet-address value="${jboss.bind.address:127.0.0.1}"/>
</interface>
Copy to Clipboard Toggle word wrap

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

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
Copy to Clipboard Toggle word wrap
注記

デプロイメントの場合のみ、デプロイメントアーカイブの META-INF/jboss.properties ファイルにリストされたプロパティーをソースとすることができます。サブデプロイメントをサポートするデプロイメントタイプでは、プロパティーファイルが EAR などの外部のデプロイメントにある場合は解決がすべてのサブデプロイメントに対してスコープ指定されます。プロパティーファイルがサブデプロイメントにある場合は、解決はそのサブデプロイメントのみに対してスコープ指定されます。

3.5.8. ネストされた式

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

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

${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}
Copy to Clipboard Toggle word wrap

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

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

3.5.9. デプロイメント記述子ベースのプロパティー置換

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

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

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

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

  • ejb-jar.xml
  • permissions.xml
  • persistence.xml
  • application.xml
  • web.xml

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

/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)
Copy to Clipboard Toggle word wrap

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

  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • jboss-permissions.xml
  • *-jms.xml
  • *-ds.xml

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

/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)
Copy to Clipboard Toggle word wrap

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

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

/subsystem=ee:write-attribute(name="annotation-property-replacement",value=VALUE)
Copy to Clipboard Toggle word wrap

annotation-property-replacementtrue に設定すると、システムプロパティー値が設定されている場合にアノテーションのプロパティー置換を有効にできます。たとえば、システムプロパティーを設定して、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 {
...
}
Copy to Clipboard Toggle word wrap

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

3.5.10. Git を使用した設定データの管理

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

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

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

Expand
表3.4 Git 設定管理用のサーバー起動引数
引数説明

--git-repo

サーバー設定データの管理および永続化に使用される Git リポジトリーの場所。これは、ローカルで保存する場合は local を指定し、リモートの場合はリモートリポジトリーへの URL を指定します。

--git-branch

使用する Git リポジトリーのブランチまたはタグ名。ブランチまたはタグ名が存在 しない と作成されないため、この引数には既存のブランチまたはタグ名を指定する必要があります。タグ名を使用する場合、リポジトリーを detached HEAD 状態にし、今後のコミットがブランチにアタッチされないようにします。タグ名は読み取り専用で、通常複数のノード全体で設定をレプリケートする必要があるときに使用されます。

--git-auth

Elytron 設定ファイルへの URL には、リモート Git リポジトリーへの接続時に使用される認証情報が含まれています。この引数は、Git リポジトリーに認証が必要な場合に必要となります。Elytron は SSH をサポートしません。したがって、パスワードなしでの秘密鍵を使用したデフォルトの SSH 認証のみがサポートされます。この引数は local リポジトリーとは使用されません。

ローカル 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
Copy to Clipboard Toggle word wrap

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>
Copy to Clipboard Toggle word wrap
注記

Elytron は SSH をサポートしません。したがって、パスワードなしでの秘密鍵を使用したデフォルトの SSH 認証のみがサポートされます。

以下は、リモート 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
Copy to Clipboard Toggle word wrap

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

警告

この処理の完了後、当初使用したものとは異なる --git-repo URL または --git-branch 名を渡して、サーバーを起動すると、サーバーの起動時にエラーメッセージ java.lang.RuntimeException: WFLYSRV0268: Failed to pull the repository GIT_REPO_NAME が表示されます。これは、JBoss EAP が jboss.server.base.dir ディレクトリーに現在設定されていないリポジトリーとブランチから設定データをプルしようとし、競合が発生するためです。

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"}
Copy to Clipboard Toggle word wrap
Git でのスナップショットの使用

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

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

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

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

:take-snapshot(name="snapshot-01", comment="1st snapshot")
{
    "outcome" => "success",
    "result" => "1st snapshot"
}
Copy to Clipboard Toggle word wrap
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"
        ]
    }
}
Copy to Clipboard Toggle word wrap
Git 使用時のスナップショットの削除

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

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

:delete-snapshot(name="snapshot-01")
{"outcome" => "success"}
Copy to Clipboard Toggle word wrap

3.6. ファイルシステムパス

JBoss EAP はファイルシステムパスに論理名を使用します。他の設定は論理名を使用してパスを参照できます。そのため、各インスタンスに完全パスを使用する必要がなく、特定のホスト設定が汎用論理名に解決することができます。

たとえば、デフォルトの logging サブシステム設定は jboss.server.log.dir をサーバーログディレクトリーの論理名として宣言します。

例: サーバーログディレクトリーの相対パスの例

<file relative-to="jboss.server.log.dir" path="server.log"/>
Copy to Clipboard Toggle word wrap

JBoss EAP では、複数の標準的なパスが自動的に提供されるため、ユーザーが設定ファイルでこれらのパスを設定する必要はありません。

Expand
表3.5 標準パス
プロパティー説明

java.home

Java インストールディレクトリー。

jboss.controller.temp.dir

スタンドアロンサーバーおよびマネージドドメインの共通のエイリアス。ディレクトリーは一時ファイルのストレージとして使用されます。マネージドドメインの jboss.domain.temp.dir とスタンドアロンサーバーの jboss.server.temp.dir と同等です。

jboss.domain.base.dir

ドメインコンテンツのベースディレクトリー。

jboss.domain.config.dir

ドメイン設定が含まれるディレクトリー。

jboss.domain.data.dir

ドメインが永続データファイルの格納に使用するディレクトリー。

jboss.domain.log.dir

ドメインが永続ログファイルの格納に使用するディレクトリー。

jboss.domain.temp.dir

ドメインが一時ファイルの格納に使用するディレクトリー。

jboss.domain.deployment.dir

ドメインがデプロイ済みコンテンツの格納に使用するディレクトリー。

jboss.domain.servers.dir

ドメインがマネージドドメインインスタンスの出力を格納するために使用するディレクトリー。

jboss.home.dir

JBoss EAP ディストリビューションのルートディレクトリー。

jboss.server.base.dir

スタンドアロンサーバーコンテンツのベースディレクトリー。

jboss.server.config.dir

スタンドアロンサーバー設定が含まれるディレクトリー。

jboss.server.data.dir

スタンドアロンサーバーが永続データファイルの格納に使用するディレクトリー。

jboss.server.log.dir

スタンドアロンサーバーがログファイルの格納に使用するディレクトリー。

jboss.server.temp.dir

スタンドアロンサーバーが一時ファイルの格納に使用するディレクトリー。

jboss.server.deploy.dir

スタンドアロンサーバーがデプロイ済みコンテンツを格納するために使用するディレクトリー。

user.dir

ユーザーのカレントワーキングディレクトリー。

user.home

ユーザーのホームディレクトリー。

標準パスのオーバーライド または カスタムパスの追加 を行うことができます。

3.6.1. ファイルシステムパスの表示

以下の管理 CLI コマンドを使用して、ファイルシステムパスのリストを表示します。

ls /path
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、以下の管理 CLI コマンドを使用して、特定のサーバーのファイルシステムパスをリストできます。

ls /host=HOST_NAME/server=SERVER_NAME/path
Copy to Clipboard Toggle word wrap

以下の管理 CLI コマンドを使用して、ファイルシステムパスの値を読み取ります。

/path=PATH_NAME:read-resource
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、以下の管理 CLI コマンドを使用して、特定サーバーのファイルシステムパスの値を読み取りできます。

/host=HOST_NAME/server=SERVER_NAME/path=PATH_NAME:read-resource
Copy to Clipboard Toggle word wrap

3.6.2. 標準パスのオーバーライド

jboss.server.* または jboss.domain.* で始まる標準パスのデフォルトの場所をオーバーライドできます。これには 2 つの方法があります。

  • サーバーの起動時にコマンドライン引数を渡します。以下に例を示します。

    $ EAP_HOME/bin/standalone.sh -Djboss.server.log.dir=/var/log
    Copy to Clipboard Toggle word wrap
  • standalone.conf または domain.conf のいずれかのサーバー設定ファイルで JAVA_OPTS 変数を変更し、新しい場所が含まれるようにします。以下に例を示します。

    JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
    Copy to Clipboard Toggle word wrap
マネージドドメインの標準パスのオーバーライド

この例の目的は、/opt/jboss_eap/domain_data ディレクトリーにドメインファイルを格納し、各トップレベルディレクトリーにカスタム名を付けることです。デフォルトのディレクトリーグルーピングである by-server が使用されます。

  • ログファイルは all_logs サブディレクトリーに格納します。
  • データファイルは all_data サブディレクトリーに格納します。
  • 一時ファイルは all_temp サブディレクトリーに格納します。
  • サーバーのファイルは all_servers サブディレクトリーに格納します。

この設定を行うには、JBoss EAP の起動時にいくつかのシステムプロパティーをオーバーライドします。

$ EAP_HOME/bin/domain.sh -Djboss.domain.temp.dir=/opt/jboss_eap/domain_data/all_temp -Djboss.domain.log.dir=/opt/jboss_eap/domain_data/all_logs -Djboss.domain.data.dir=/opt/jboss_eap/domain_data/all_data -Djboss.domain.servers.dir=/opt/jboss_eap/domain_data/all_servers
Copy to Clipboard Toggle word wrap

この結果、パス構造は次のようになります。

/opt/jboss_eap/domain_data/
               ├── all_data
               ├── all_logs
               ├── all_servers
               │   ├── server-one
               │   │   ├── data
               │   │   ├── log
               │   │   └── tmp
               │   └── server-two
               │       ├── data
               │       ├── log
               │       └── tmp
               └── all_temp
Copy to Clipboard Toggle word wrap

3.6.3. カスタムパスの追加

管理 CLI または管理コンソールを使用してカスタムのファイルシステムパスを追加できます。

前提条件

  • JBoss EAP が実行中である。

手順

  • 管理 CLI の場合、以下の管理 CLI コマンドを使用して新しいパスを追加できます。

    /path=my.custom.path:add(path=/my/custom/path)
    Copy to Clipboard Toggle word wrap
  • 管理コンソールからファイルシステムパスを設定するには、設定 タブに移動し、パス を選択して 表示 をクリックします。ここからは、パスを追加、変更、および削除できます。

このカスタムパスを設定で使用できます。たとえば、以下のログハンドラーは相対パスにカスタムパスを使用します。

<subsystem xmlns="{LoggingSubsystemNamespace}">
  ...
  <periodic-rotating-file-handler name="FILE" autoflush="true">
    <formatter>
      <named-formatter name="PATTERN"/>
    </formatter>
    <file relative-to="my.custom.path" path="server.log"/>
    <suffix value=".yyyy-MM-dd"/>
    <append value="true"/>
  </periodic-rotating-file-handler>
  ...
</subsystem>
Copy to Clipboard Toggle word wrap

3.7. ディレクトリーのグループ化

マネージドドメインでは、各サーバーのファイルは EAP_HOME/domain ディレクトリーに格納されます。ホストコントローラーの directory-grouping 属性を使用すると、サーバーのサブディレクトリーの編成を指定できます。ディレクトリーは サーバー または タイプ を基にしてグループ化できます。デフォルトではディレクトリーは サーバー を基にしてグループ化されます。

サーバーを基にしたディレクトリーのグループ化

デフォルトでは、ディレクトリーはサーバーを基にしてグループ化されます。管理が サーバー中心 である場合は、この設定を推奨します。たとえば、サーバーインスタンスごとにバックアップやログファイルの処理を設定することができます。

ZIP インストールで JBoss EAP がインストールされた場合、デフォルトのディレクトリー構造 (サーバーによるグループ化) は次のようになります。

EAP_HOME/domain
         └─ servers
            ├── server-one
            │   ├── data
            │   ├── tmp
            │   └── log
            └── server-two
                ├── data
                ├── tmp
                └── log
Copy to Clipboard Toggle word wrap

サーバーを基にしてドメインディレクトリーをグループ化するには、以下の管理 CLI コマンドを入力します。

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-server)
Copy to Clipboard Toggle word wrap

このコマンドにより、ホストコントローラーの host.xml 設定ファイルが更新されます。

<servers directory-grouping="by-server">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>
Copy to Clipboard Toggle word wrap
タイプを基にしたディレクトリーのグループ化

サーバーを基にディレクトリーをグループ化する代わりに、ファイルタイプを基にしてグループ化することもできます。管理が ファイルタイプ中心 である場合は、この設定を推奨します。たとえば、data ファイルのみを簡単にバックアップすることができます。

ZIP インストールで JBoss EAP がインストールされ、ドメインのファイルがタイプを基にグループ化された場合、ディレクトリー構造は次のようになります。

EAP_HOME/domain
         ├── data
         │   └── servers
         │       ├── server-one
         │       └── server-two
         ├── log
         │   └── servers
         │       ├── server-one
         │       └── server-two
         └── tmp
             └── servers
                 ├── server-one
                 └── server-two
Copy to Clipboard Toggle word wrap

タイプを基にしてドメインディレクトリーをグループ化するには、以下の管理 CLI コマンドを入力します。

/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-type)
Copy to Clipboard Toggle word wrap

このコマンドにより、ホストコントローラーの host.xml 設定ファイルが更新されます。

<servers directory-grouping="by-type">
  <server name="server-one" group="main-server-group"/>
  <server name="server-two" group="main-server-group" auto-start="true">
    <socket-bindings port-offset="150"/>
  </server>
</servers>
Copy to Clipboard Toggle word wrap

3.8. システムプロパティー

Java システムプロパティーを使用すると、JBoss EAP の多くのオプションや、アプリケーションサーバー内で使用する名前と値のペアを設定することができます。

システムプロパティーを使用して、JBoss EAP 設定のデフォルト値をオーバーライドできます。たとえば、以下のパブリックインターフェイスバインドアドレスの XML 設定は、jboss.bind.address システムプロパティーによる設定が可能で、このシステムプロパティーが提供されないとデフォルトで 127.0.0.1 が使用されることを表しています。

<inet-address value="${jboss.bind.address:127.0.0.1}"/>
Copy to Clipboard Toggle word wrap

JBoss EAP でシステムプロパティーを設定する方法は複数あり、以下の方法が含まれます。

JBoss EAP のマネージドドメインを使用する場合、ドメイン全体、特定のサーバーグループ、特定のホストとそのすべてのサーバーインスタンス、または 1 つのサーバーインスタンスにシステムプロパティーを適用できます。他のほとんどの JBoss EAP ドメイン設定と同様に、より具体的なレベルで設定されたシステムプロパティーが、より抽象的なものをオーバーライドします。詳細は ドメイン管理 の章を参照してください。

起動スクリプトにシステムプロパティーを渡す

JBoss EAP 起動スクリプトにシステムプロパティーを渡すには -D 引数を使用します。以下に例を示します。

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=192.168.1.2
Copy to Clipboard Toggle word wrap

このシステムプロパティーの設定方法は、JBoss EAP が起動する前に JBoss EAP のオプションを設定する必要がある場合に便利です。

管理 CLI を使用したシステムプロパティーの設定

管理 CLI で以下の構文を使用すると、システムプロパティーを設定できます。

/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)
Copy to Clipboard Toggle word wrap

以下に例を示します。

/system-property=jboss.bind.address:add(value=192.168.1.2)
Copy to Clipboard Toggle word wrap

管理 CLI を使用してシステムプロパティーを設定する場合、一部の JBoss EAP オプション (上記の例の jboss.bind.address など) を有効にするにはサーバーの再起動が必要です。

マネージドドメインの場合、上記の例はドメイン全体のシステムプロパティーを設定しますが、より具体的なドメイン設定のレベルでシステムプロパティーを設定またはオーバーライドすることもできます。

管理コンソールを使用したシステムプロパティーの設定
  • スタンドアロン JBoss EAP サーバーでは、管理コンソールの Configuration タブでシステムプロパティーを設定できます。System Properties を選択し、表示 ボタンをクリックします。
  • マネージドドメインの場合:

    • ドメインレベルのシステムプロパティーは Configuration タブで設定できます。System Properties を選択し、表示 ボタンをクリックします。
    • サーバーグループおよびサーバーレベルのシステムプロパティーは Runtime タブで設定できます。設定するサーバーグループまたはサーバーを選択し、サーバーグループまたはサーバー名の横にある 表示 ボタンをクリックした後、System Properties タブを選択します。
    • ホストレベルのシステムプロパティーは Runtime タブで設定できます。設定するホストを選択し、ホスト名の横にあるドロップダウンメニューで Properties を選択します。
JAVA_OPTS を使用したシステムプロパティーの設定

システムプロパティーは JAVA_OPTS 環境変数を使用して設定することもできます。JAVA_OPTS を変更する方法は多くありますが、JBoss EAP では JBoss EAP のプロセスで使用される JAVA_OPTS を設定する設定ファイルが提供されます。

スタンドアロンサーバーの場合、このファイルは EAP_HOME/bin/standalone.conf になります。マネージドドメインの場合は、EAP_HOME/bin/domain.conf になります。Microsoft Windows システムではこれらのファイルに .bat 拡張子が付きます。

注記

RPM インストールの場合、RPM サービス設定ファイルJAVA_OPTS を変更してシステムプロパティーを設定することが推奨されます。RPM サービスプロパティーの設定 を参照してください。

適切な設定ファイルで JAVA_OPTS にシステムプロパティー定義を追加します。以下は、Red Hat Enterprise Linux システムでバインドアドレスを設定する例になります。

  • standalone.conf では、JAVA_OPTS システムプロパティー定義をファイルの最後に追加します。以下に例を示します。

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
    Copy to Clipboard Toggle word wrap
  • domain.conf では、プロセスコントローラーの JAVA_OPTS 設定の前に JAVA_OPTS を設定する必要があります。以下に例を示します。

    ...
    # Set the bind address
    JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
    
    # The ProcessController process uses its own set of java options
    if [ "x$PROCESS_CONTROLLER_JAVA_OPTS" = "x" ]; then
    ...
    Copy to Clipboard Toggle word wrap

3.9. 管理監査ロギング

管理コンソール、管理 CLI、または管理 API を使用するカスタムアプリケーションを使用して実行されたすべての操作をログに記録する、管理インターフェイスの監査ロギングを有効にできます。監査ログエントリーは JSON 形式で保存されます。監査ロギングはデフォルトでは無効になっています。

監査ロギングは、ファイル または syslog サーバー に出力するように設定できます。

注記

JBoss EAP には認証されたセッションがないため、ログインおよびログアウトイベントは監査できません。その代わりに、ユーザーから操作を受信すると監査メッセージがログに記録されます。

3.9.1. スタンドアロンサーバーの監査ロギング

監査ロギングはデフォルトでは無効になっていますが、デフォルトの監査ロギング設定はファイルに書き込みします。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="file" formatter="json-formatter" path="audit-log.log" relative-to="jboss.server.data.dir"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="file"/>
        </handlers>
    </logger>
</audit-log>
Copy to Clipboard Toggle word wrap

この設定は、以下の管理 CLI コマンドを使用して読み取ることができます。

/core-service=management/access=audit:read-resource(recursive=true)
Copy to Clipboard Toggle word wrap

スタンドアロンサーバーの監査ロギングを有効にする場合は、監査ロギングの有効化 を参照してください。

3.9.2. マネージドドメインの監査ロギング

監査ロギングはデフォルトでは無効になっていますが、デフォルトの監査ロギング設定は各ホストおよび各サーバーに対してファイルを書き込みします。

<audit-log>
    <formatters>
        <json-formatter name="json-formatter"/>
    </formatters>
    <handlers>
        <file-handler name="host-file" formatter="json-formatter" relative-to="jboss.domain.data.dir" path="audit-log.log"/>
        <file-handler name="server-file" formatter="json-formatter" relative-to="jboss.server.data.dir" path="audit-log.log"/>
    </handlers>
    <logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="host-file"/>
        </handlers>
    </logger>
    <server-logger log-boot="true" log-read-only="false" enabled="false">
        <handlers>
            <handler name="server-file"/>
        </handlers>
    </server-logger>
</audit-log>
Copy to Clipboard Toggle word wrap

この設定は、以下の管理 CLI コマンドを使用して読み取ることができます。

/host=HOST_NAME/core-service=management/access=audit:read-resource(recursive=true)
Copy to Clipboard Toggle word wrap

マネージドドメインの監査ロギングを有効にする場合は、監査ロギングの有効化 を参照してください。

3.9.3. 管理監査ロギングの有効化

監査ロギングはデフォルトでは無効になっていますが、JBoss EAP には監査ロギングのファイルハンドラーが事前設定されています。監査ロギングを有効にする管理 CLI コマンドは、スタンドアロンサーバーとして実行しているかまたはマネージドドメインで実行しているかによって異なります。ファイルハンドラーの属性は、管理監査ロギングの属性 を参照してください。

次の手順では、NATIVE および HTTP 監査ロギングを有効にします。JMX 監査ロギングを設定する場合は、JMX 管理監査ロギングの有効化 を参照してください。

syslog 監査ロギングを設定する場合は、syslog サーバーへの管理監査ロギングの送信 を参照してください。

3.9.3.1. スタンドアロンサーバーの監査ロギングの有効化

監査ロギングは以下のコマンドを使用して有効にできます。

/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
Copy to Clipboard Toggle word wrap

デフォルトでは、このコマンドによって監査ログが EAP_HOME/standalone/data/audit-log.log に書き込まれます。

3.9.3.2. マネージドドメインの監査ロギングの有効化

マネージドドメインのデフォルトの監査ログ設定は、各ホストおよび各サーバーに対して監査ログを書き込むよう事前設定されています。

各ホストの監査ロギングは以下のコマンドを使用して有効にできます。

/host=HOST_NAME/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
Copy to Clipboard Toggle word wrap

デフォルトでは、このコマンドによって監査ログが EAP_HOME/domain/data/audit-log.log に書き込まれます。

各サーバーの監査ロギングは以下のコマンドを使用して有効にできます。

/host=HOST_NAME/core-service=management/access=audit/server-logger=audit-log:write-attribute(name=enabled,value=true)
Copy to Clipboard Toggle word wrap

デフォルトでは、このコマンドによって監査ログが EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log に書き込まれます。

3.9.4. JMX 管理監査ロギングの有効化

JBoss EAP には、JMX 監査ロギングのファイルハンドラーが事前設定されていますが、これらのログはデフォルトで無効になっています。監査ロギングを有効にする管理 CLI コマンドは、スタンドアロンサーバーまたは管理対象ドメインとして実行しているかによって異なります。

NATIVE または HTTP 監査ロギングを設定する場合は、管理監査ロギングの有効化 を参照してください。

3.9.4.1. スタンドアロンサーバーの JMX 監査ロギングの有効化

以下のコマンドを使用すると、スタンドアロンサーバーでの JMX 監査ロギングを有効にできます。

/subsystem=jmx/configuration=audit-log:add()
/subsystem=jmx/configuration=audit-log/handler=file:add()
Copy to Clipboard Toggle word wrap

これにより、JMX 監査ロギングが有効になり、定義された file ハンドラーを使用してこれらのログを EAP_HOME/standalone/data/audit-log.log に書き込むことができるようになります。

3.9.4.2. マネージドドメインの JMX 監査ロギングの有効化

マネージドドメインの各ホストおよびプロファイルに JMX 監査ロギングを有効にすることができます。

ホストの JMX 監査ロギングの有効化

  1. ホストの jmx サブシステムで監査ロギングを有効にします。

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log:add()
    Copy to Clipboard Toggle word wrap
  2. jmx サブシステムの監査ロギングが有効になったら、以下のコマンドでホストにハンドラーを定義することができます。

    /host=HOST_NAME/subsystem=jmx/configuration=audit-log/handler=host-file:add()
    Copy to Clipboard Toggle word wrap

    デフォルトでは、このコマンドによって JMX 監査ログが EAP_HOME/domain/data/audit-log.log に書き込まれます。

プロファイルの JMX 監査ロギングの有効化

  1. プロファイルの jmx サブシステムで監査ロギングを有効にします。

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log:add()
    Copy to Clipboard Toggle word wrap
  2. jmx サブシステムの監査ロギングが有効になったら、以下のコマンドでプロファイルにハンドラーを定義することができます。

    /profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log/handler=server-file:add()
    Copy to Clipboard Toggle word wrap

    デフォルトでは、このコマンドによって JMX 監査ログが EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log に書き込まれます。

3.9.5. syslog サーバーへの管理監査ロギングの送信

syslog ハンドラーは、監査ログエントリーが syslog サーバーに送信されるときのパラメーター (syslog サーバーのホスト名および syslog サーバーがリッスンするポート) を指定します。監査ロギングを syslog サーバーへ送信すると、ローカルファイルまたはローカル syslog サーバーへロギングする場合よりも、セキュリティーオプションが多くなります。複数の syslog ハンドラーを同時に定義およびアクティブ化することができます。

デフォルトでは、監査ロギングが有効である場合にファイルへ出力するよう事前設定されています。以下の手順に従って、syslog サーバーへの監査ロギングを設定および有効化します。syslog ハンドラーの属性は、管理監査ロギングの属性 を参照してください。

前提条件

  • JBoss EAP が実行中である。

手順

  1. syslog ハンドラーを追加します。

    syslog サーバーのホストとポートを指定して syslog ハンドラーを作成します。マネージドドメインでは、/core-service コマンドの前に /host=HOST_NAME を追加する必要があります。

    batch
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME:add(formatter=json-formatter)
    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=udp:add(host=HOST_NAME,port=PORT)
    run-batch
    Copy to Clipboard Toggle word wrap
    注記

    渡すパラメーターは指定されたプロトコルによって異なります。

    TLS を使用して syslog サーバーとセキュアに通信するようハンドラーを設定するには、認証を設定する必要もあります。以下に例を示します。

    /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=tls/authentication=truststore:add(keystore-path=PATH_TO_TRUSTSTORE,keystore-password=TRUSTSTORE_PASSWORD)
    Copy to Clipboard Toggle word wrap
  2. syslog ハンドラーへの参照を追加します。

    マネージドドメインでは、このコマンドの前に /host=HOST_NAME を追加する必要があります。

    /core-service=management/access=audit/logger=audit-log/handler=SYSLOG_HANDLER_NAME:add
    Copy to Clipboard Toggle word wrap
  3. 監査ロギングを有効にします。

    監査ロギングを有効にするには、管理監査ロギングの有効化 を参照してください。

重要

オペレーティングシステムでロギングが有効になっていないと、JBoss EAP で syslog サーバーへの監査ロギングを有効にしても動作しません。

Red Hat Enterprise Linux の rsyslog 設定の詳細は、https://access.redhat.com/documentation/en/red-hat-enterprise-linux/ にある Red Hat Enterprise Linux の システム管理者ガイドRsyslog の基本設定 セクションを参照してください。

3.9.6. 監査ログエントリーの読み取り

ファイルに出力される監査ログエントリーは、テキスト ビューアー で参照することを推奨します。syslog サーバーに出力される監査ログエントリーは syslog ビューアーアプリケーションで参照することを推奨します

注記

ログファイルの参照にテキスト エディター を使用することは推奨されません。これは、追加のログエントリーがログファイルに書き込まれなくなることがあるためです。

監査ログエントリーは JSON 形式で保存されます。各ログエントリーは最初にオプションのタイムスタンプ、次に以下の表のフィールドが示されます。

Expand
表3.6 管理監査ログフィールド
フィールド名説明

access

以下のいずれかの値を使用できます。

  • NATIVE - 操作がネイティブ管理インターフェイスから実行されます。
  • HTTP - 操作がドメイン HTTP インターフェイスから実行されます。
  • JMX - 操作が jmx サブシステムから実行されます。

booting

起動プロセス中に操作が実行された場合は、値が true になります。サーバーの起動後に操作が実行された場合は false になります。

domainUUID

ドメインコントローラーからそのサーバー、セカンダリーホストコントローラー、およびセカンダリーホストコントローラーサーバーに伝播されるすべての操作をリンクするための ID。

ops

実行される操作。JSON へシリアライズ化された操作のリストになります。起動時は、XML の解析で生じたすべての操作がリストされます。起動後は、通常 1 つのエントリーがリストされます。

r/o

操作によって管理モデルが変更されない場合は、値が true になります。変更される場合は false になります。

remote-address

この操作を実行するクライアントのアドレス。

success

操作に成功した場合は値が true になります。ロールバックされた場合は false になります。

type

管理操作であることを示す core、または jmx サブシステムからであることを示す jmx を値として指定できます。

user

認証されたユーザーのユーザー名。稼働しているサーバーと同じマシンの管理 CLI を使用して操作を行った場合は、特別な $local ユーザーが使用されます。

version

JBoss EAP インスタンスのバージョン番号。

3.10. サーバーライフサイクルイベントの通知

JBoss EAP の core-management サブシステム または JMX を使用して、サーバーライフサイクルイベントの通知を設定できます。サーバーランタイム設定の状態やサーバー稼働の状態が変更されると、通知が発生します。

JBoss EAP のサーバーランタイム設定の状態には、STARTINGRUNNINGRELOAD_REQUIREDRESTART_REQUIREDSTOPPING、および STOPPED があります。

JBoss EAP のサーバー稼働の状態には、STARTINGNORMALADMIN_ONLYPRE_SUSPENDSUSPENDINGSUSPENDEDSTOPPING、および STOPPED があります。

3.10.1. core-management サブシステムを使用したサーバーライフサイクルイベントの監視

リスナーを JBoss EAP core-management サブシステムに登録すると、サーバーのライフサイクルイベントを監視できます。以下の手順は、イベントをログファイルの記録するサンプルリスナーを作成および登録する方法を示しています。

前提条件

  • JBoss EAP が実行中である。

手順

  1. リスナーを作成します。

    以下の例のように、org.wildfly.extension.core.management.client.ProcessStateListener の実装を作成します。

    例: リスナークラス

    package org.simple.lifecycle.events.listener;
    
    import java.io.File;
    import java.io.FileWriter;
    import java.io.IOException;
    
    import org.wildfly.extension.core.management.client.ProcessStateListener;
    import org.wildfly.extension.core.management.client.ProcessStateListenerInitParameters;
    import org.wildfly.extension.core.management.client.RunningStateChangeEvent;
    import org.wildfly.extension.core.management.client.RuntimeConfigurationStateChangeEvent;
    
    public class SimpleListener implements ProcessStateListener {
    
        private File file;
        private FileWriter fileWriter;
        private ProcessStateListenerInitParameters parameters;
    
        public void init(ProcessStateListenerInitParameters parameters) {
            this.parameters = parameters;
            this.file = new File(parameters.getInitProperties().get("file"));
            try {
                fileWriter = new FileWriter(file, true);
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void cleanup() {
            try {
                fileWriter.close();
            } catch (IOException e) {
                e.printStackTrace();
            } finally {
                fileWriter = null;
            }
        }
    
        public void runtimeConfigurationStateChanged(RuntimeConfigurationStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Runtime configuration state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    
        public void runningStateChanged(RunningStateChangeEvent evt) {
            try {
                fileWriter.write(String.format("Running state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState()));
                fileWriter.flush();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
    Copy to Clipboard Toggle word wrap

    注記

    リスナーの実装時には以下に気をつけてください。

    • サーバーがリロードすると、サーバーの停止時にリスナーはリッスンを停止し、サーバーの起動時にリスナーはリロードされます。そのため、実装では同じ JVM 内部でリスナーを適切に複数回ロード、初期化、および削除できるようにする必要があります。
    • サーバー状態の変更に対応できるようにするため、リスナーへの通知はブロッキング状態になります。実装では、リスナーがブロックまたはデッドロックしないようにする必要があります。
    • 各リスナーインスタンスは独自のスレッドで実行され、順番は保証されません。
  2. クラスおよびパッケージを JAR にコンパイルします。

    コンパイルするには、org.wildfly.core:wildfly-core-management-client Maven モジュールに依存する必要があります。

  3. JAR を JBoss EAP モジュールとして追加します。

    以下の管理 CLI コマンドを使用し、モジュール名と JAR へのパスを提供します。

    module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/path/to/simple-listener-0.0.1-SNAPSHOT.jar
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  4. リスナーを登録します。

    以下のかんり CLI コマンドを使用してリスナーを core-management サブシステムに追加します。クラス、モジュール、およびサーバーライフサイクルイベントを記録するログファイルの場所を指定します。

    /subsystem=core-management/process-state-listener=my-simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener,properties={file=/path/to/my-listener-output.txt})
    Copy to Clipboard Toggle word wrap

上記の SimpleListener クラスを基にしてサーバーライフサイクルのイベントが my-listener-output.txt ファイルに記録されるようになりました。たとえば、管理 CLI で :suspend コマンドを実行すると、以下が my-listener-output.txt ファイルに出力されます。

Running state change for STANDALONE_SERVER: normal to suspending
Running state change for STANDALONE_SERVER: suspending to suspended
Copy to Clipboard Toggle word wrap

これを見ると、稼働状態が normal から suspending に変わった後、suspending から suspended に変わったことがわかります。

3.10.2. JMX 通知を使用したサーバーライフサイクルイベントの監視

JMX 通知リスナーを登録すると、サーバーのライフサイクルイベントを監視できます。以下の手順は、イベントをログファイルの記録するサンプルリスナーを作成および追加する方法を示しています。

前提条件

  • JBoss EAP が実行中である。

手順

  1. リスナーを作成します。

    以下の例のように、java.management.NotificationListener の実装を作成します。

    例: リスナークラス

    import java.io.BufferedWriter;
    import java.io.IOException;
    import java.nio.charset.StandardCharsets;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.nio.file.StandardOpenOption;
    
    import java.management.AttributeChangeNotification;
    import java.management.Notification;
    import java.management.NotificationListener;
    
    import org.jboss.logging.Logger;
    
    public class StateNotificationListener implements NotificationListener {
    
      public static final String RUNTIME_CONFIGURATION_FILENAME = "runtime-configuration-notifications.txt";
      public static final String RUNNING_FILENAME = "running-notifications.txt";
      private final Path targetFile;
    
      public StateNotificationListener() {
        this.targetFile = Paths.get("notifications/data").toAbsolutePath();
        init(targetFile);
      }
    
      protected Path getRuntimeConfigurationTargetFile() {
        return this.targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME);
      }
    
      protected Path getRunningConfigurationTargetFile() {
        return this.targetFile.resolve(RUNNING_FILENAME);
      }
    
      protected final void init(Path targetFile) {
        try {
          Files.createDirectories(targetFile);
    
          if (!Files.exists(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME));
          }
    
          if (!Files.exists(targetFile.resolve(RUNNING_FILENAME))) {
            Files.createFile(targetFile.resolve(RUNNING_FILENAME));
          }
        } catch (IOException ex) {
            Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    
      @Override
      public void handleNotification(Notification notification, Object handback) {
        AttributeChangeNotification attributeChangeNotification = (AttributeChangeNotification) notification;
        if ("RuntimeConfigurationState".equals(attributeChangeNotification.getAttributeName())) {
          writeNotification(attributeChangeNotification, getRuntimeConfigurationTargetFile());
        } else {
          writeNotification(attributeChangeNotification, getRunningConfigurationTargetFile());
        }
      }
    
      private void writeNotification(AttributeChangeNotification notification, Path path) {
        try (BufferedWriter in = Files.newBufferedWriter(path, StandardCharsets.UTF_8, StandardOpenOption.APPEND)) {
          in.write(String.format("%s %s %s %s", notification.getType(), notification.getSequenceNumber(), notification.getSource().toString(), notification.getMessage()));
          in.newLine();
          in.flush();
        } catch (IOException ex) {
          Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex);
        }
      }
    }
    Copy to Clipboard Toggle word wrap

  2. 通知リスナーを登録します。

    通知リスナーを MBeanServer に追加します。

    例: 通知リスナーの追加

    MBeanServer server = ManagementFactory.getPlatformMBeanServer();
    server.addNotificationListener(ObjectName.getInstance("jboss.root:type=state"), new StateNotificationListener(), null, null);
    Copy to Clipboard Toggle word wrap

  3. JBoss EAP にパッケージ化およびデプロイします。

上記の StateNotificationListener クラスを基にしてサーバーライフサイクルイベントがファイルに記録されるようになりました。たとえば、管理 CLI で :suspend コマンドを実行すると、以下が running-notifications.txt ファイルに出力されます。

jmx.attribute.change 5 jboss.root:type=state The attribute 'RunningState' has changed from 'normal' to 'suspending'
jmx.attribute.change 6 jboss.root:type=state The attribute 'RunningState' has changed from 'suspending' to 'suspended'
Copy to Clipboard Toggle word wrap

これを見ると、稼働状態が normal から suspending に変わった後、suspending から suspended に変わったことがわかります。

第4章 ネットワークおよびポート設定

4.1. インターフェイス

JBoss EAP は設定全体で名前付きインターフェイスを参照します。これにより、使用ごとにインターフェイスの完全な詳細を必要とせず、論理名を使用して個々のインターフェイス宣言を参照できます。

また、複数のマシンでネットワークインターフェイスの詳細が異なる場合にマネージドドメインの設定が容易になります。各サーバーインスタンスは、論理名グループに対応できます。

standalone.xmldomain.xml、および host.xml ファイルにはインターフェイス宣言が含まれます。使用されるデフォルトの設定に応じて、複数の事前設定されたインターフェイス名があります。management インターフェイスは、HTTP 管理エンドポイントを含む、管理レイヤーが必要なすべてのコンポーネントおよびサービスに使用できます。public インターフェイスは、アプリケーション関連のネットワーク通信すべてに使用できます。unsecure インターフェイスは、標準設定の IIOP ソケットに使用されます。private インターフェイスは、標準設定の JGroups ソケットに使用されます。

4.1.1. デフォルトインターフェイス設定

デフォルトでは、次のインターフェイス設定が指定されています。

<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>
  <interface name="private">
    <inet-address value="${jboss.bind.address.private:127.0.0.1}"/>
  </interface>
  <interface name="unsecure">
    <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
  </interface>
</interfaces>
Copy to Clipboard Toggle word wrap

JBoss EAP はこれらのインターフェイスを 127.0.0.1 にバインドします。ただし、これらの値は、適切なプロパティーを設定することで、実行時にオーバーライドできます。たとえば、以下のコマンドで JBoss EAP をスタンドアロンサーバーとして起動するときに public インターフェイスの inet-address を設定できます。

$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
Copy to Clipboard Toggle word wrap

この代わりに、サーバー起動のコマンドラインで -b スイッチを使用することができます。

$ EAP_HOME/bin/standalone.sh -b IP_ADDRESS
Copy to Clipboard Toggle word wrap

上記のコマンドの -b IP_ADDRESS は、-Djboss.bind.address=IP_ADDRESS と同等です。

-b スイッチを使用して、management インターフェイスの inet-address を設定することもできます。

$ EAP_HOME/bin/standalone.sh -bmanagement=IP_ADDRESS
Copy to Clipboard Toggle word wrap

単一の変数のみを設定する場合は、jboss.bind.address.managementjboss.bind.address に変更できます。-b スイッチまたは -Djboss.bind.address を設定すると、パブリックインターフェイスと管理インターフェイスが同じ IP_ADDRESS を共有します。

サーバー起動オプションの詳細は、サーバーランタイム引数 を参照してください。

重要

JBoss EAP が使用するデフォルトのネットワークインターフェイスまたはポートを変更する場合は、変更したインターフェイスまたはポートを使用するスクリプトを変更する必要があることに注意してください。これには JBoss EAP サービススクリプトが含まれます。また、管理コンソールまたは CLI にアクセスするときに適切なインターフェイスとポートを指定するようにしてください。

4.1.2. インターフェイスの設定

ネットワークインターフェイスは、物理インターフェイスの論理名および選択基準を指定して宣言されます。選択基準はワイルドカードアドレスを参照したり、一致が有効となるためにインターフェイスまたはアドレスで必要となる 1 つ以上の特徴のセットを指定したりできます。使用できるすべてのインターフェイス選択基準は、インターフェイスの属性 を参照してください。

インターフェイスは管理コンソールまたは管理 CLI を使用して設定できます。以下にインターフェイスの追加および更新の例をいくつか示します。最初に管理 CLI コマンドを示し、その後に対応する設定 XML を示します。

NIC 値があるインターフェイスの追加

NIC 値が eth0 であるインターフェイスを新たに追加します。

/interface=external:add(nic=eth0)
Copy to Clipboard Toggle word wrap
<interface name="external">
   <nic name="eth0"/>
</interface>
Copy to Clipboard Toggle word wrap
複数の条件値があるインターフェイスの追加

稼働時に適切なサブネットのすべてのインターフェイスまたはアドレスと一致し、マルチキャストをサポートする、ポイントツーポイントでないインターフェイスを新たに追加します。

/interface=default:add(subnet-match=192.168.0.0/16,up=true,multicast=true,not={point-to-point=true})
Copy to Clipboard Toggle word wrap
<interface name="default">
   <subnet-match value="192.168.0.0/16"/>
   <up/>
   <multicast/>
   <not>
      <point-to-point/>
   </not>
</interface>
Copy to Clipboard Toggle word wrap
インターフェイス属性の更新

public インターフェイスのデフォルトの inet-address 値を更新し、jboss.bind.address プロパティーによってこの値が起動時に設定されるようにします。

/interface=public:write-attribute(name=inet-address,value="${jboss.bind.address:192.168.0.0}")
Copy to Clipboard Toggle word wrap
<interface name="public">
    <inet-address value="${jboss.bind.address:192.168.0.0}"/>
</interface>
Copy to Clipboard Toggle word wrap
マネージドドメイン内のサーバーにインターフェイスを追加する
/host=HOST_NAME/server-config=SERVER_NAME/interface=INTERFACE_NAME:add(inet-address=127.0.0.1)
Copy to Clipboard Toggle word wrap
<servers>
   <server name="SERVER_NAME" group="main-server-group">
      <interfaces>
         <interface name="INTERFACE_NAME">
            <inet-address value="127.0.0.1"/>
         </interface>
      </interfaces>
   </server>
</servers>
Copy to Clipboard Toggle word wrap

4.2. ソケットバインディング

ソケットバインディングとソケットバインディンググループを使用することにより、ネットワークポートと、JBoss EAP の設定で必要なネットワーキングインターフェイスとの関係を定義できます。ソケットバインディングはソケットの名前付き設定です。ソケットバインディンググループは、ある論理名でグループ化されたソケットバインディング宣言のコレクションです。

これにより、使用ごとにソケット設定の完全な詳細を必要とせずに、設定の他のセクションが論理名でソケットバインディングを参照できるようになります。

これらの名前付き設定の宣言は standalone.xml および domain.xml 設定ファイルにあります。スタンドアロンサーバーにはソケットバインディンググループが 1 つのみ含まれますが、マネージドドメインには複数のグループを含むことができます。マネージドドメインで各サーバーグループのソケットバインディンググループを作成するか、複数のサーバーグループ間でソケットバインディンググループを共有することができます。

デフォルトで JBoss EAP によって使用されるポートは、使用されるソケットバインディンググループと、個々のデプロイメントの要件に応じて異なります。

JBoss EAP 設定のソケットバインディンググループで定義できるソケットバインディングには 3 つの種類があります。

受信ソケットバインディング

socket-binding 要素は、JBoss EAP サーバーの受信ソケットバインディングを設定するために使用されます。デフォルトの JBoss EAP 設定には、HTTP や HTTPS トラフィック用などの、事前設定された socket-binding 要素が複数提供されます。JBoss EAP の メッセージングの設定ブロードキャストグループ セクションに、別の例が記載されています。

この要素の属性は、受信ソケットバインディングの属性 の表を参照してください。

リモート送信ソケットバインディング

remote-destination-outbound-socket-binding 要素は、JBoss EAP サーバーのリモートとなる宛先の送信ソケットバインディングを設定するために使用されます。デフォルトの JBoss EAP 設定には、メールサーバーに使用できるリモート宛先のソケットバインディングの例が含まれています。JBoss EAP の メッセージングの設定リモート接続の統合された Artemis リソースアダプターの使用 セクションに、別の例が記載されています。

この要素の属性は、リモート送信ソケットバインディングの属性 の表を参照してください。

ローカル送信ソケットバインディング

local-destination-outbound-socket-binding 要素は、JBoss EAP サーバーのローカルとなる宛先の送信ソケットバインディングを設定するために使用されます。通常、このソケットバインディングはあまり使用されません。

この要素の属性は、ローカル送信ソケットバインディングの属性 の表を参照してください。

4.2.1. 管理ポート

JBoss EAP 7 では、管理ポートが集約されました。JBoss EAP 8.0 は、管理 CLI によって使用されるネイティブ管理と、Web ベース管理コンソールによって使用される HTTP 管理の両方に 9990 ポートを使用します。JBoss EAP 6 でネイティブ管理ポートとして使用されていた 9999 ポートは使用されなくなりましたが、必要な場合は有効にできます。

管理コンソールに対して HTTPS を有効にすると、デフォルトではポート 9993 が使用されます。

4.2.2. デフォルトのソケットバインディング

JBoss EAP には、事前設定された 5 つのプロファイル (defaulthafullfull-haload-balancer) のソケットバインディンググループが含まれています。

デフォルトのポートや説明など、デフォルトのソケットバインディングの詳細は、デフォルトのソケットバインディンググループ セクションを参照してください。

重要

JBoss EAP が使用するデフォルトのネットワークインターフェイスまたはポートを変更する場合は、変更したインターフェイスまたはポートを使用するスクリプトを変更する必要があることに注意してください。これには JBoss EAP サービススクリプトが含まれます。また、管理コンソールまたは CLI にアクセスするときに適切なインターフェイスとポートを指定するようにしてください。

スタンドアロンサーバー

スタンドアロンサーバーとして実行されている場合、設定ファイルごとに 1 つのソケットバインディンググループのみが定義されます。各スタンドアロン設定ファイル (standalone.xmlstandalone-ha.xmlstandalone-full.xmlstandalone-full-ha.xmlstandalone-load-balancer.xml) は、対応するプロファイルによって使用される技術のソケットバインディングを定義します。

たとえば、デフォルトのスタンドアロン設定ファイル (standalone.xml) は以下のソケットバインディングを指定します。

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>
Copy to Clipboard Toggle word wrap
管理対象ドメイン

管理対象ドメインで実行されている場合、すべてのソケットバインディンググループは domain.xml ファイルで定義されます。事前定義されたソケットバインディンググループは 5 つあります。

  • standard-sockets
  • ha-sockets
  • full-sockets
  • full-ha-sockets
  • load-balancer-sockets

各ソケットバインディンググループは、対応するプロファイルによって使用される技術のソケットバインディングを指定します。たとえば、full-ha-sockets ソケットバインディンググループは、高可用性のために full-ha プロファイルによって使用される複数の jgroups ソケットバインディングを定義します。

<socket-binding-groups>
  <socket-binding-group name="standard-sockets" default-interface="public">
    <!-- Needed for server groups using the 'default' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'ha' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full' profile  -->
    ...
  </socket-binding-group>
  <socket-binding-group name="full-ha-sockets" default-interface="public">
    <!-- Needed for server groups using the 'full-ha' profile  -->
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:8080}"/>
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="iiop" interface="unsecure" port="3528"/>
    <socket-binding name="iiop-ssl" interface="unsecure" port="3529"/>
    <socket-binding name="jgroups-mping" interface="private" port="0" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45700"/>
    <socket-binding name="jgroups-tcp" interface="private" port="7600"/>
    <socket-binding name="jgroups-udp" interface="private" port="55200" multicast-address="${jboss.default.multicast.address:230.0.0.4}" multicast-port="45688"/>
    <socket-binding name="modcluster" port="0" multicast-address="224.0.1.105" multicast-port="23364"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
      <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
  </socket-binding-group>
  <socket-binding-group name="load-balancer-sockets" default-interface="public">
    <!-- Needed for server groups using the 'load-balancer' profile  -->
    ...
  </socket-binding-group>
</socket-binding-groups>
Copy to Clipboard Toggle word wrap
注記

管理インターフェイスのソケット設定は、ドメインコントローラーの host.xml ファイルに定義されます。

4.2.3. ソケットバインディングの設定

ソケットバインディングを設定するとき、port および interface 属性や、multicast-address および multicast-port などのマルチキャスト設定を設定できます。使用可能なすべてのソケットバインディング属性の詳細は、ソケットバインディングの属性 セクションを参照してください。

ソケットバインディングは管理コンソールまたは管理 CLI を使用して設定できます。以下の手順では、ソケットバインディンググループの追加、ソケットバインディングの追加、および管理 CLI を使用したソケットバインディングの設定を行います。

手順

  1. 新しいソケットバインディンググループを追加します。

    注記

    このステップは、スタンドアロンサーバーとして実行している場合は実行 できません

    /socket-binding-group=new-sockets:add(default-interface=public)
    Copy to Clipboard Toggle word wrap
  2. ソケットバインディングを追加します。

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:add(port=1234)
    Copy to Clipboard Toggle word wrap
  3. ソケットバインディンググループによって設定されるデフォルト以外のインターフェイスを使用するよう、ソケットバインディングを変更します。

    /socket-binding-group=new-sockets/socket-binding=new-socket-binding:write-attribute(name=interface,value=unsecure)
    Copy to Clipboard Toggle word wrap

以下の例は、上記の手順の完了後に XML 設定がどのようになるかを示しています。

<socket-binding-groups>
    ...
    <socket-binding-group name="new-sockets" default-interface="public">
        <socket-binding name="new-socket-binding" interface="unsecure" port="1234"/>
    </socket-binding-group>
</socket-binding-groups>
Copy to Clipboard Toggle word wrap

4.2.4. サーバーのソケットバインディングおよび開放ポートの表示

管理コンソールから、サーバーのソケットバインディング名と開放ポートを表示できます。

前提条件

ソケットバインディング名と開放ポートは、サーバーが次のいずれかの状態にある場合にのみ表示されます。

  • running
  • reload-required
  • restart-required

手順

  1. 管理コンソールにアクセスし、Runtime に移動します。
  2. サーバーをクリックすると、右側のペインにソケットバインディング名と開放ポートが表示されます。

4.2.5. ポートオフセット

ポートオフセットとは、該当するサーバーのソケットバインディンググループに指定されたすべてのポート値に追加される数値のオフセットのことです。これにより、同じホストの別のサーバーとの競合を防ぐため、サーバーはソケットバインディンググループに定義されたポート値とオフセットを継承できるようになります。たとえば、ソケットバインディンググループの HTTP ポートが 8080 で、サーバーが 100 をポートオフセットとして使用する場合、HTTP ポートは 8180 になります。

管理 CLI を使用してマネージドドメインのサーバーにポートオフセットとして 250 を設定する例を以下に示します。

/host=primary/server-config=server-two/:write-attribute(name=socket-binding-port-offset,value=250)
Copy to Clipboard Toggle word wrap

ポートオフセットは、マネージドドメインのサーバーと、同じホストで複数のスタンドアロンサーバーを実行する場合に使用できます。

jboss.socket.binding.port-offset プロパティーを使用してスタンドアロンサーバーを起動するときにポートオフセットを渡すことができます。

$ EAP_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100
Copy to Clipboard Toggle word wrap

4.3. IPv6 アドレス

デフォルトでは、JBoss EAP は IPv4 アドレスを使用して実行するように設定されます。以下の手順では、IPv6 アドレスを使用して実行するよう JBoss EAP を設定する方法を示します。

4.3.1. IPv6 アドレスの JVM スタックの設定

IPv6 アドレスを優先するように、起動設定を更新します。

手順

  1. 起動設定ファイルを開きます。

    • スタンドアロンサーバーとして実行している場合は、EAP_HOME/bin/standalone.conf ファイル (Windows Server の場合は standalone.conf.bat) を編集します。
    • マネージドドメインで実行している場合は、EAP_HOME/bin/domain.conf ファイル (Windows Server の場合は domain.conf.bat) を編集します。
  2. java.net.preferIPv4Stack プロパティーを false に設定します。

    -Djava.net.preferIPv4Stack=false
    Copy to Clipboard Toggle word wrap
  3. java.net.preferIPv6Addresses プロパティーを追加し、true に設定します。

    -Djava.net.preferIPv6Addresses=true
    Copy to Clipboard Toggle word wrap

以下の例は、上記の変更を行った後に起動設定ファイルの JVM オプションがどのようになるかを示しています。

# Specify options to pass to the Java VM.
#
if [ "x$JAVA_OPTS" = "x" ]; then
   JAVA_OPTS="$JBOSS_JAVA_SIZING -Djava.net.preferIPv4Stack=false"
   JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv6Addresses=true"
else
Copy to Clipboard Toggle word wrap

4.3.2. IPv6 アドレスのインターフェイス宣言の更新

設定のデフォルトのインターフェイス値は、IPv6 アドレスに変更できます。たとえば、以下の管理 CLI コマンドは management インターフェイスを IPv6 ループバックアドレス (::1) に設定します。

/interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:[::1]}")
Copy to Clipboard Toggle word wrap

以下の例は、上記のコマンド実行後に XML 設定がどのようになるかを示しています。

<interfaces>
    <interface name="management">
        <inet-address value="${jboss.bind.address.management:[::1]}"/>
    </interface>
    ....
</interfaces>
Copy to Clipboard Toggle word wrap

第5章 JBoss EAP のクラスローディングの概要

JBoss EAP は、デプロイされたアプリケーションのクラスパスを制御するためにモジュール形式のクラスローディングシステムを使用します。このシステムは、階層クラスローダーの従来のシステムよりも、柔軟性があり、より詳細に制御できます。開発者は、アプリケーションで利用可能なクラスに対して粒度の細かい制御を行い、アプリケーションサーバーで提供されるクラスを無視して独自のクラスを使用するようデプロイメントを設定できます。

モジュール形式のクラスローダーにより、すべての Java クラスはモジュールと呼ばれる論理グループに分けられます。各モジュールは他のモジュールへの依存関係を定義して、そのモジュールのクラスを自身のクラスパスに含めることができます。デプロイされた各 Java Archive (JAR) および Web Archive (WAR) ファイルは、モジュールとして扱われます。そのため、開発者はモジュール設定を追加することでアプリケーションのクラスパスの内容を制御できます。

5.1. JBoss EAP のモジュールの種類

モジュールは、クラスローディングおよび依存関係管理に使用されるクラスの論理グループです。JBoss EAP は次の 2 種類のモジュールを識別します。

  • 静的モジュール
  • 動的モジュール

この 2 種類のモジュールの主な違いは、パッケージ化方法です。

JBoss EAP は、事前定義されたモジュールのセットも提供します。

5.1.1. JBoss EAP の静的モジュール

静的モジュールは、アプリケーションサーバーの EAP_HOME/modules/ ディレクトリーで定義されます。各モジュールは EAP_HOME/modules/com/mysql/ のようにサブディレクトリーとして存在します。各モジュールには、module.xml 設定ファイルとすべての必要な Java Archive (JAR) ファイルが格納されるスロットサブディレクトリー (デフォルトでは main) が含まれます。アプリケーションサーバーにより提供される API は、Jakarta EE API と他の API を含む静的モジュールとして提供されます。

例: MySQL JDBC ドライバー module.xml ファイル

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-j-8.0.33.jar"/>
  </resources>
  <dependencies>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap

注記

MySQL ドライバーの JAR 名 (mysql-connector-j-8.0.33.jar) は、あくまで例として示したものです。テスト済みの MySQL バージョンの詳細は、Tested databases を参照してください。

モジュール名 com.mysql は、スロット名 main を除くモジュールのディレクトリー構造と一致する必要があります。

カスタム静的モジュールの作成は、同じサードパーティーライブラリーを使用する同じサーバー上に多くのアプリケーションがデプロイされる場合に役立ちます。これらのライブラリーを各アプリケーションとバンドルする代わりに、管理者はこれらのライブラリーが含まれるモジュールを作成およびインストールできます。アプリケーションは、カスタム静的モジュールで明示的な依存関係を宣言できます。

JBoss EAP ディストリビューションで提供されるモジュールは、EAP_HOME/modules ディレクトリー内の system ディレクトリーにあります。このため、サードパーティーによって提供されるモジュールから分離されます。また、JBoss EAP 上で使用する、Red Hat により提供されるすべての製品によって、system ディレクトリー内にモジュールがインストールされます。

モジュールごとに 1 つのディレクトリーを使用して、カスタムモジュールが EAP_HOME/modules ディレクトリーにインストールされるようにする必要があります。こうすると、同梱されたバージョンではなく、system ディレクトリーに存在するカスタムバージョンのモジュールがロードされるようになります。これにより、ユーザー提供のモジュールがシステムモジュールよりも優先されます。

JBOSS_MODULEPATH 環境変数を使用して JBoss EAP がモジュールを検索する場所を変更する場合は、指定された場所の 1 つで system サブディレクトリー構造を探します。system 構造は、JBOSS_MODULEPATH で指定された場所のどこかに存在する必要があります。

module.xml ファイルの resource-root path 要素では、絶対パスも使用できます。これにより、リソースライブラリーを EAP_HOME/modules ディレクトリーに移動しなくても、リソースライブラリーにアクセスできます。

例: module.xml ファイルの絶対パス

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="oracle.jdbc">
    <resources>
        <resource-root path="/home/redhat/test.jar"/>
    </resources>
</module>
Copy to Clipboard Toggle word wrap

5.1.2. JBoss EAP の動的モジュール

動的モジュールは、Java Archive (JAR) または Web Archive (WAR) デプロイメントごとに、または Enterprise Archive (EAR) 内のサブデプロイメントごとに、アプリケーションサーバーによって作成およびロードされます。動的モジュールの名前は、デプロイされたアーカイブの名前に由来します。デプロイメントはモジュールとしてロードされるため、依存関係を設定し、他のデプロイメントで依存関係として使用することが可能です。

モジュールは必要な場合にのみロードされます。通常は、明示的または暗黙的な依存関係を持つアプリケーションがデプロイされるときにロードされます。

5.1.3. JBoss EAP の定義済みモジュール

アプリケーションサーバーでデフォルトのモジュールローダーを使用する場合、定義済みモジュールのセットを使用できます。このモジュールはすべての JBoss Modules API が含まれる org.jboss.modules で、JBoss Modules によって提供され、常に利用可能です。標準の Java Platform Module System (JPMS) モジュールも、標準の名前で使用できます。

Java 9 以上で使用できるプラットフォームモジュールのリストは、該当する JDK のドキュメントを参照してください。

5.2. JBoss EAP のモジュール依存関係

モジュール依存関係とは、1 つのモジュールを機能させるために 1 つ以上の他のモジュールのクラスが必要であることを宣言することです。JBoss EAP がモジュールをロードするときに、モジュール形式のクラスローダーがモジュールの依存関係を解析し、各依存関係のクラスをクラスパスに追加します。指定の依存関係が見つからない場合、モジュールはロードできません。

Java Archive (JAR) や Web Archive (WAR) などのデプロイされたアプリケーションは、動的モジュールとしてロードされ、依存関係を利用して JBoss EAP によって提供される API にアクセスします。

依存関係には、明示的暗黙的 の 2 種類があります。

明示的な依存関係
明示的な依存関係は開発者が設定ファイルで宣言します。静的モジュールでは、依存関係を module.xml ファイルに宣言できます。動的モジュールでは、デプロイメントの MANIFEST.MF または jboss-deployment-structure.xml デプロイメント記述子に依存関係を宣言できます。
暗黙的な依存関係
暗黙的な依存関係は、デプロイメントで特定の条件またはメタデータが検出された場合、自動的に追加されます。JBoss EAP に同梱される Jakarta EE API は、デプロイメントで暗黙的な依存関係が検出されたときに追加されるモジュールの例になります。

jboss-deployment-structure.xml デプロイメント記述子ファイルを使用して、特定の暗黙的な依存関係を除外するようデプロイメントを設定することも可能です。これは、JBoss EAP が暗黙的な依存関係として追加しようとする特定バージョンのライブラリーをアプリケーションがバンドルする場合に役に立つことがあります。

オプションの依存関係

明示的な依存関係は、オプションとして指定できます。オプションの依存関係をロードできなくても、モジュールのロードは失敗しません。ただし、依存関係は後で使用できるようになっても、モジュールのクラスパスには追加されません。依存関係はモジュールがロードされるときに利用可能である必要があります。

エクスポートした依存関係

モジュールのクラスパスには独自のクラスとその直接の依存関係のクラスのみが含まれます。モジュールは 1 つの依存関係の依存関係クラスにはアクセスできませんが、暗黙的な依存関係のエクスポートを指定できます。ただし、モジュールは、明示的な依存関係をエクスポートするように指定できます。エクスポートした依存関係は、エクスポートするモジュールに依存するモジュールに提供されます。

たとえば、モジュール A はモジュール B に依存し、モジュール B はモジュール C に依存するとします。モジュール A はモジュール B のクラスにアクセスでき、モジュール B はモジュール C のクラスにアクセスできます。モジュール A は、以下の場合を除き、モジュール C のクラスにはアクセスできません。

  • モジュール A がモジュール C への明示的な依存関係を宣言する場合。
  • または、モジュール B がモジュール B の依存関係をモジュール C でエクスポートする場合。
グローバルモジュール

グローバルモジュールは、JBoss EAP が各アプリケーションへの依存関係として提供するモジュールです。このモジュールをグローバルモジュールの JBoss EAP のリストへ追加すると、モジュールをグローバルモジュールにすることができます。モジュールへの変更は必要ありません。

詳細は、JBoss EAP のグローバルモジュール を参照してください。

5.3. JBoss EAP のカスタムモジュールの作成

同じサードパーティーライブラリーを使用する多くのアプリケーションを同じサーバーにデプロイする場合は、カスタムモジュールを作成すると便利です。これらのライブラリーを各アプリケーションとバンドルする代わりに、管理者はこれらのライブラリーが含まれるモジュールを作成およびインストールできます。

カスタムモジュールは次の方法で作成できます。

5.3.1. カスタムモジュールの手動作成

Java Archive (JAR) またはその他のリソースファイルからモジュールを作成し、JBoss EAP のアプリケーションでそれらのファイルを使用できます。

前提条件

  • モジュールに必要な JAR またはリソースファイルがある。

手順

  1. EAP_HOME/modules/ ディレクトリーに適切なディレクトリー構造を作成します。

    例: MySQL JDBC ドライバーディレクトリー構造の作成

    $ cd EAP_HOME/modules/
    $ mkdir -p com/mysql/main
    Copy to Clipboard Toggle word wrap

  2. JAR ファイルまたはその他必要なリソースを main/ サブディレクトリーにコピーします。

    例: MySQL JDBC ドライバー JAR のコピー

    $ cp /path/to/mysql-connector-j-8.0.33.jar EAP_HOME/modules/com/mysql/main/
    Copy to Clipboard Toggle word wrap

    注記

    MySQL ドライバーの JAR 名 (mysql-connector-j-8.0.33.jar) は、あくまで例として示したものです。テスト済みの MySQL バージョンの詳細は、Tested databases を参照してください。

  3. module.xml ファイルを main/ サブディレクトリーに作成し、そのファイルの適切なリソースおよび依存関係を指定します。

    例: MySQL JDBC ドライバー module.xml ファイル

    <?xml version="1.0" ?>
    <module xmlns="urn:jboss:module:1.9" name="com.mysql">
      <resources>
        <resource-root path="mysql-connector-j-8.0.33.jar"/>
      </resources>
      <dependencies>
        <module name="java.xml" export="true"/>
        <module name="java.xml.crypto" export="true"/>
        <module name="jdk.xml.dom" export="true"/>
    
        <module name="jakarta.transaction.api"/>
      </dependencies>
    </module>
    Copy to Clipboard Toggle word wrap

    注記

    MySQL ドライバーの JAR 名 (mysql-connector-j-8.0.33.jar) は、あくまで例として示したものです。テスト済みの MySQL バージョンの詳細は、Tested databases を参照してください。

5.3.2. 管理 CLI を使用したカスタムモジュールの作成

管理 CLI を使用して、Java Archive (JAR) またはその他のリソースファイルからモジュールを作成し、JBoss EAP のアプリケーションでそれらのファイルを使用できます。

重要

module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境では、モジュールを手作業で追加および削除する必要があります。詳細は以下を参照してください。

テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

前提条件

  • モジュールに必要な JAR またはリソースファイルがある。

手順

  1. JBoss EAP サーバーを起動します。
  2. 管理 CLI を起動します。

    $ EAP_HOME/bin/jboss-cli.sh
    Copy to Clipboard Toggle word wrap
  3. module add 管理 CLI コマンドを使用して新しいコアモジュールを追加します。

    構文

    module add --name=<MODULE_NAME> --resources=<PATH_TO_RESOURCE> --dependencies=<DEPENDENCIES>
    Copy to Clipboard Toggle word wrap

    例: MySQL モジュールの作成

    module add --name=com.mysql --resources=</path/to>/mysql-connector-j-8.0.33.jar --dependencies=java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap

    注記

    MySQL ドライバーの JAR 名 (mysql-connector-j-8.0.33.jar) は、あくまで例として示したものです。テスト済みの MySQL バージョンの詳細は、Tested databases を参照してください。

5.4. モジュールを依存関係として追加する

モジュールのリソースにアクセスするには、アプリケーションにモジュールを依存関係として追加する必要があります。

たとえば、以下の手順は複数のプロパティーファイルが含まれる JAR ファイルをモジュールとして追加し、グローバルモジュールを定義して、アプリケーションがこれらのプロパティーをロードできるようにします。

手順

  1. JAR ファイルをコアモジュールとして追加します。

    module add --name=myprops --resources=</path/to>/properties.jar
    Copy to Clipboard Toggle word wrap
  2. すべてのデプロイメントが使用できるようにするため、このモジュールをグローバルモジュールとして定義します。

    /subsystem=ee:list-add(name=global-modules,value={name=myprops})
    Copy to Clipboard Toggle word wrap

検証

  • Java Archive (JAR) 内に含まれるプロパティーファイルの 1 つから、アプリケーションがプロパティーを取得できることを確認します。

    Thread.currentThread().getContextClassLoader().getResource("my.properties");
    Copy to Clipboard Toggle word wrap

5.5. JBoss EAP からのカスタムモジュールの削除

次の方法で、JBoss EAP から不要なモジュールを削除できます。

5.5.1. カスタムモジュールの手動削除

モジュールを手作業で削除する前に、デプロイされたアプリケーションやサーバー設定 (データソースなど) がそのモジュールを必要としていないことを確認してください。

手順

  • EAP_HOME/modules/ 配下のモジュールのディレクトリーを削除します。このディレクトリーには、module.xml ファイルと関連する JAR ファイルまたはその他のリソースが含まれています。

    たとえば、main スロットのカスタム MySQL JDBC ドライバーモジュールを削除するには、EAP_HOME/modules/com/mysql/main/ ディレクトリーを削除します。

5.5.2. 管理 CLI を使用したカスタムモジュールの削除

module remove 管理 CLI コマンドを使用するとカスタムモジュールを削除できます。

重要

管理 CLI コマンドを使用してカスタムモジュールを削除する機能は、テクノロジープレビューとしてのみ提供されます。テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 管理 CLI を起動します。

    $ EAP_HOME/bin/jboss-cli.sh
    Copy to Clipboard Toggle word wrap
  2. module remove 管理 CLI コマンドを使用してカスタムモジュールを削除します。

    構文

    module remove --name=MODULE_NAME
    Copy to Clipboard Toggle word wrap

    • 削除するモジュールが main 以外のスロットにある場合は、--slot 引数を使用します。

    例: MySQL モジュールの削除

    module remove --name=com.mysql
    Copy to Clipboard Toggle word wrap

module --help を実行すると、このコマンドを使用したモジュールの追加および削除の詳細を表示できます。

5.6. JBoss EAP のグローバルモジュール

JBoss EAP のグローバルモジュールのリストを定義して、すべての JBoss EAP デプロイメントに依存関係として追加できます。

注記

グローバルモジュールとして設定するモジュールの名前を知っている必要があります。含まれるモジュールの完全なリストとこれらのモジュールがサポートされているかは、Red Hat カスタマーポータルの JBoss Enterprise Application Platform 8.0 に含まれるモジュール を参照してください。デプロイメント内のモジュールの命名規則は、JBoss EAP の動的モジュール命名規則 セクションを参照してください。

グローバルモジュールのリストを定義するには、次の管理 CLI コマンドを使用します。

/subsystem=ee:write-attribute(name=global-modules,value=[{name=<MODULE_NAME_1>},{name=<MODULE_NAME_2>}]
Copy to Clipboard Toggle word wrap

既存のグローバルモジュールのリストに 1 つのモジュールを追加するには、次の管理 CLI コマンドを使用します。

/subsystem=ee:list-add(name=global-modules,value={name=<MODULE_NAME>})
Copy to Clipboard Toggle word wrap

管理コンソールを使用してグローバルモジュールを追加および削除することもできます。Configuration タブから EE サブシステムに移動し、Global Modules セクションを選択します。

外部依存関係からグローバルモジュールにアクセスできるようにする必要がある場合は、明示的に可能にする必要があります。グローバルモジュール内のサービスを外部から利用できるようにするには、次のオプションを使用できます。

  • services="import" を、jboss-deployment-structure.xml のモジュールに追加します。
  • global モジュール定義に services="true" を追加します。

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true}]
    Copy to Clipboard Toggle word wrap

    または、複数のモジュールを追加する場合は以下を使用します。

    /subsystem=ee:write-attribute(name=global-modules,value=[{name=module1,services=true},{name=module2,services=false}]
    Copy to Clipboard Toggle word wrap

    新しいモジュールを既存のリストに追加するには、以下を行います。

    /subsystem=ee:list-add(name=global-modules,value={name=module1,services=true})
    Copy to Clipboard Toggle word wrap
  • 管理コンソールを使用してグローバルモジュールを定義する場合は、Services プロパティーの値が On であることを確認します。

5.7. グローバルディレクトリーの作成

グローバルディレクトリーは、グローバルモジュールの代わりのアプローチとなります。たとえば、グローバルモジュールに一覧表示されているライブラリーの名前を変更する場合は、グローバルモジュールを削除し、ライブラリーの名前を変更して新しいグローバルモジュールにライブラリーを追加する必要があります。グローバルディレクトリーにリストされたライブラリーの名前を変更する場合は、サーバーの再読み込みを行い、ライブラリー名の変更が全デプロイメントで利用できるようにするだけです。

グローバルディレクトリーを使用すると、以下を実行できます。

  • デプロイされたアプリケーション間で複数のライブラリーを共有する
  • 通常、アプリケーションライブラリーに追加された共通のフレームワークを共通のロケーションに移動することで、ライブラリーを維持する

グローバルディレクトリーを作成する場合、EE サブシステムはグローバルディレクトリーを設定し、ディレクトリーをスキャンして JBoss Modules のモジュール依存関係を作成します。モジュールの依存関係には、グローバルディレクトリーライブラリーおよび JAR ファイルが含まれます。このモジュール依存関係には、次のリソースローダーも含まれています。

  • パスリソースローダーは、ファイルをリソースとしてアプリケーションに提供します。
  • リソースローダーは、JAR ファイルに含まれるクラスをアプリケーションに提供します。

EE サブシステムは、デプロイされた各アプリケーションのシステム依存関係としてモジュールの依存関係を追加します。

前提条件

  • オペレーティングシステムに標準ディレクトリーを作成します。この標準ディレクトリーには、アプリケーションにデプロイする必要のあるすべての JAR ファイルとリソースが含まれている必要があります。これにより、ディレクトリーツリーが作成されます。

    アプリケーションにコピーされた共通のライブラリーのリストを示す共通ディレクトリーの例:

    /my-common-libs/log4j2.xml
    /my-common-libs/libs/log4j-api-2.14.1.jar
    /my-common-libs/libs/log4j-core-2.14.1.jar
    Copy to Clipboard Toggle word wrap

    注記

    サーバーはアプリケーションをデプロイし、グローバルディレクトリーをロードします。そのため、サーバーのライブラリーバージョンをオーバーライドするようにグローバルディレクトリーを設定することはできません。グローバルディレクトリーは、サーバーに同梱されたライブラリーを置き換えることはできません。

手順

  1. サーバーの設定に応じて、グローバルディレクトリーを作成します。オプションの relative-to 属性を使用して、グローバルディレクトリーを相対パスで設定できます。

    スタンドアロンサーバーにグローバルディレクトリーを作成する例:

    [standalone@localhost:9990 /] /subsystem=ee/global-directory=my-common-libs:add(path=my-common-libs, relative-to=jboss.home.dir)
    Copy to Clipboard Toggle word wrap

    マネージドドメイン内のサーバーにグローバルディレクトリーを作成する例:

    [domain@localhost:9990 /] /profile=default/subsystem=ee/global-directory=my-common-libs:add(path=my-common-libs, relative-to=jboss.server.data.dir)
    Copy to Clipboard Toggle word wrap

    マネージドドメインのサーバーでは、relative-path 属性を使用して、domain.xml で定義される JBoss EAP プロファイルにグローバルディレクトリーを追加できます。relative-to 属性には、システムパスまたはカスタムシステムパスのいずれかを指定できます。

    注記

    マネージドドメインでサーバーを実行する場合は、グローバルディレクトリーのコンテンツがすべてのサーバーインスタンスで一貫していることを確認する必要があります。たとえば、各ホストには、グローバルディレクトリーのコンテンツを含むローカルファイルシステムディレクトリーが含まれている必要があります。

  2. サーバーインスタンスをリロードして、グローバルディレクトリーをアクティベートします。

    サーバーが、ルートディレクトリーから開始して、アルファベット順に、各サブディレクトリーレベルを含むディレクトリーツリーの内容をスキャンできるように、サーバーをリロードする必要があります。サーバーは、各ディレクトリーレベルから JBoss Modules モジュールの依存関係に、アルファベット順にファイルを追加します。

    グローバルディレクトリーの内容を変更するか、グローバルディレクトリーで JAR ファイルを変更または追加する場合は、サーバーをリロードして、デプロイされたアプリケーションで変更を利用できるようにする必要があります。たとえば、グローバルディレクトリーの JAR ライブラリーを置き換える場合は、サーバーをリロードして、グローバルディレクトリーを再スキャンし、変更した JAR ライブラリーでデプロイされたアプリケーションを更新します。

5.8. グローバルディレクトリー設定の現在の値の読み取り

read-resource 操作を使用すると、グローバルディレクトリー設定の現在の値を読み取ることができます。

手順

  • サーバーの設定に応じて、read-resource 操作を使用してグローバルディレクトリー設定の現在の値を読み取ります。

    スタンドアロンサーバーのグローバルディレクトリー設定の現在の値を読み取る場合の出力例。

    [standalone@localhost:9990 /] /subsystem=ee/global-directory=my-common-libs:read-resource
    {
          "outcome" => "success",
          "result" => {
              "path" => "my-common-libs",
              "relative-to" => "jboss.home.dir"
          }
     }
    Copy to Clipboard Toggle word wrap

    マネージドドメインのサーバーのグローバルディレクトリー設定の現在の値を読み取る場合の出力例。

    [domain@localhost:9990 /] /subsystem=ee/global-directory=my-common-libs:read-resource
     {
          "outcome" => "success",
          "result" => {
              "path" => "my-common-libs",
              "relative-to" => "jboss.server.data.dir"
          }
     }
    Copy to Clipboard Toggle word wrap

5.9. グローバルディレクトリーの削除

サーバー設定からグローバルディレクトリーを削除できます。この操作は、サーバー設定ファイルからグローバルディレクトリーリソースのみを削除します。基になっているディレクトリーやそのファイルには影響しません。

手順

  • スタンドアロンサーバーからグローバルディレクトリーを削除するには、以下のコマンドを使用します。

    [standalone@localhost:9990 /] /subsystem=ee/global-directory=my-common-libs:remove()
    Copy to Clipboard Toggle word wrap
  • マネージドドメインのサーバー上のグローバルディレクトリーを削除するには、以下のコマンドを使用します。

    [domain@localhost:9990 /] /profile=default/subsystem=ee/global-directory=my-common-libs:remove()
    Copy to Clipboard Toggle word wrap

5.10. JBoss EAP のサブデプロイメント分離設定

Enterprise Archive (EAR) 内の各サブデプロイメントは、独自のクラスローダーを持つ動的モジュールです。サブデプロイメントは、EAR/lib のクラスへのアクセスを提供する親モジュールの暗黙的な依存関係を常に持ちます。デフォルトでは、サブデプロイメントはその EAR 内にある他のサブデプロイメントのリソースにアクセスできます。

サブデプロイメントが他のサブデプロイメントに属するクラスにアクセスできないようにするには、JBoss EAP で厳格なサブデプロイメント分離を有効にします。この設定はすべてのデプロイメントに影響します。

5.10.1. すべてのデプロイメントを対象とするサブデプロイメントモジュール分離の有効化

サブデプロイメント分離は ee サブシステムから管理コンソールまたは管理 CLI を使用して有効または無効にできます。デフォルトでは、サブデプロイメント分離は false に設定されています。そのため、サブデプロイメントは Enterprise Archive (EAR) デプロイメント内にある他のサブデプロイメントのリソースにアクセスできます。

手順

  • 次の管理 CLI コマンドを使用して、EAR のサブデプロイメント分離を有効にします。

    /subsystem=ee:write-attribute(name=ear-subdeployments-isolated,value=true)
    Copy to Clipboard Toggle word wrap

EAR のサブデプロイメントは他のサブデプロイメントからリソースにアクセスできなくなります。

5.11. 外部 JBoss EAP モジュールディレクトリーの定義

JBoss EAP モジュールのデフォルトのディレクトリーは EAP_HOME/modules です。JBOSS_MODULEPATH 変数を使用すると JBoss EAP モジュールの他のディレクトリーを指定できます。以下の手順に従って、JBoss EAP 起動設定ファイルでこの変数を設定します。

注記

JBOSS_MODULEPATH を JBoss EAP 起動設定ファイルで設定する代わりに、環境変数として設定することもできます。

手順

  1. 起動設定ファイルを編集します。

    • スタンドアロンサーバーとして実行している場合は、EAP_HOME/bin/standalone.conf ファイル (Windows Server の場合は standalone.conf.bat) を編集します。
    • マネージドドメインで実行している場合は、EAP_HOME/bin/domain.conf ファイル (Windows Server の場合は domain.conf.bat) を編集します。
  2. JBOSS_MODULEPATH 変数を設定します。例を以下に示します。

    JBOSS_MODULEPATH="/path/to/modules/directory/"
    Copy to Clipboard Toggle word wrap

    ディレクトリーのリストを指定するには、ディレクトリーのリストをコロン (:) で区切ります。

    注記

    Windows Server の場合、次の構文を使用して JBOSS_MODULEPATH 変数を設定します。

    set "JBOSS_MODULEPATH /path/to/modules/directory/"
    Copy to Clipboard Toggle word wrap

    ディレクトリーのリストを指定するには、ディレクトリーのリストをセミコロン (;) で区切ります。

5.12. JBoss EAP の動的モジュール命名規則

JBoss EAP では、すべてのデプロイメントが、以下の規則に従って名前が付けられたモジュールとしてロードされます。

  • Web Archive (WAR) および Java Archive (JAR) ファイルのデプロイメントには、次の形式で名前が付けられます。

    deployment.DEPLOYMENT_NAME
    Copy to Clipboard Toggle word wrap

    たとえば、inventory.warstore.jar のモジュール名はそれぞれ deployment.inventory.wardeployment.store.jar になります。

  • Enterprise Archive (EAR) 内のサブデプロイメントには、次の形式で名前が付けられます。

    deployment.EAR_NAME.SUBDEPLOYMENT_NAME
    Copy to Clipboard Toggle word wrap

    たとえば、エンタープライズアーカイブ accounts.ear 内にある reports.war のサブデプロイメントのモジュール名は deployment.accounts.ear.reports.war になります。

第6章 アプリケーションデプロイメントの管理

JBoss EAP には、管理者向けと開発者向けのアプリケーションデプロイメントおよび設定オプションが多くあります。管理者は、管理コンソール のグラフィカルインターフェイスや 管理 CLI のコマンドラインインターフェイスを使用して本番環境のアプリケーションデプロイメントを管理できます。開発者は、設定可能なファイルシステムの デプロイメントスキャナーHTTP API、Red Hat CodeReady Studio などの IDE、および Maven などを含む、多くのテストオプションをアプリケーションのデプロイメントで使用できます。

アプリケーションをデプロイするときにデプロイメント記述子の検証を有効にするには、org.jboss.metadata.parser.validate システムプロパティーを true に設定します。これには、以下の方法の 1 つを使用します。

  • サーバー起動時

    $ EAP_HOME/bin/standalone.sh -Dorg.jboss.metadata.parser.validate=true
    Copy to Clipboard Toggle word wrap
  • 以下の管理 CLI コマンドでサーバー設定に追加

    /system-property=org.jboss.metadata.parser.validate:add(value=true)
    Copy to Clipboard Toggle word wrap

6.1. 管理 CLI を使用したアプリケーションデプロイメントの管理

管理 CLI を使用してアプリケーションをデプロイすると、単一のコマンドラインインターフェイスでデプロイメントスクリプトを作成および実行できます。このスクリプト機能を使用して、特定のアプリケーションデプロイメントおよび管理シナリオを設定できます。スタンドアロンサーバーとして稼働している場合は単一サーバーのデプロイメント状態を管理でき、マネージドドメインで稼働している場合はサーバーのネットワーク全体のデプロイメントを管理できます。

6.1.1. スタンドアロンサーバーでのアプリケーションデプロイメントの管理

6.1.1.1. 管理 CLI を使用したスタンドアロンサーバーへのアプリケーションのデプロイ

管理 CLI で deployment deploy-file コマンドを使用して、アプリケーションをスタンドアロンサーバーにデプロイできます。

前提条件

  • JBoss EAP が実行中である。

手順

  • 管理 CLI から、Web Archive (war) としてパッケージ化されたアプリケーションをデプロイします。

    構文

    deployment deploy-file <path_to_the_application>/<application_name>.war
    Copy to Clipboard Toggle word wrap

    deployment deploy-file /my-applications/test-application.war
    Copy to Clipboard Toggle word wrap

    正常にデプロイされると、管理 CLI には何も出力されませんが、サーバーログに次の出力のようなデプロイメントメッセージが記録されます。

    WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
    WFLYUT0021: Registered web context: /test-application
    WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")
    Copy to Clipboard Toggle word wrap

同様に、以下の deployment コマンドを使用できます。

  • deployment deploy-cli-archive を使用してコンテンツを .cli アーカイブファイルからデプロイします。CLI デプロイメントアーカイブは、.cli 拡張子を持つ JAR ファイルです。デプロイする必要があるアプリケーションアーカイブと、コマンドおよび操作が含まれる deploy.scr および undeploy.scr CLI スクリプトファイルが含まれます。deploy.scr スクリプトファイルには、アプリケーションアーカイブをデプロイし、環境を設定するコマンドと操作が含まれます。undeploy.scr スクリプトファイルには、アプリケーションアーカイブをアンデプロイし、環境をクリーンアップするコマンドが含まれます。
  • deployment deploy-url を使用して、URL によって参照されるコンテンツをデプロイします。
注記

--runtime-name オプションで runtime-name 属性を指定する場合は、名前に .war 拡張子を含める必要があります。そうしないと、Web コンテキストが JBoss EAP によって登録されません。

6.1.1.2. 管理 CLI を使用したスタンドアロンサーバーからのアプリケーションのアンデプロイ

管理 CLI で deployment undeploy コマンドを使用して、スタンドアロンサーバーからアプリケーションをアンデプロイできます。アプリケーションをアンデプロイすると、リポジトリーからデプロイメントコンテンツが削除されます。デプロイメントコンテンツを保持しながらアプリケーションを使用不可にする場合は、代わりにデプロイメントを無効にできます。詳細は、管理 CLI を使用したスタンドアロンサーバーでのアプリケーションの無効化 を参照してください。

前提条件

  • JBoss EAP が実行中である。

手順

  • 管理 CLI を使用してアプリケーションをアンデプロイします。

    構文

    deployment undeploy <deployment>
    Copy to Clipboard Toggle word wrap

    deployment undeploy test-application.war
    Copy to Clipboard Toggle word wrap

    正常にアンデプロイされると、管理 CLI には何も出力されませんが、サーバーログに次の出力のようなアンデプロイメントメッセージが記録されます。

    WFLYUT0022: Unregistered web context: /test-application
    WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 62ms
    WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")
    Copy to Clipboard Toggle word wrap

同様に、deployment undeploy-cli-archive を使用して .cli アーカイブファイルからコンテンツをアンデプロイできます。ワイルドカード (*) を使用してすべてのデプロイメントをアンデプロイすることも可能です。

deployment undeploy *
Copy to Clipboard Toggle word wrap
6.1.1.3. 管理 CLI を使用したスタンドアロンサーバーでのアプリケーションの無効化

リポジトリーからデプロイメントコンテンツを削除せずに、デプロイされたアプリケーションを無効にできます。

前提条件

  • JBoss EAP が実行中である。

手順

  • 管理 CLI から deployment disable コマンドを使用して、JBoss EAP にデプロイされた 1 つまたはすべてのアプリケーションを無効にできます。

    • 1 つのデプロイメントを無効にする場合:

      構文

      deployment disable <deployment>
      Copy to Clipboard Toggle word wrap

      deployment disable test-application.war
      Copy to Clipboard Toggle word wrap

    • すべてのデプロイメントを無効にする場合:

      deployment disable-all
      Copy to Clipboard Toggle word wrap
6.1.1.4. 管理 CLI を使用したスタンドアロンサーバーでのアプリケーションの有効化

無効になっているアプリケーションを有効にできます。

前提条件

  • JBoss EAP が実行中である。

手順

  • 管理 CLI から deployment enable コマンドを使用して、JBoss EAP にデプロイされた 1 つまたはすべてのアプリケーションを有効にできます。

    • 1 つのデプロイメントを有効化する場合:

      構文

      deployment enable <deployment>
      Copy to Clipboard Toggle word wrap

      deployment enable test-application.war
      Copy to Clipboard Toggle word wrap

    • すべてのデプロイメントを有効化する場合:

      deployment enable-all
      Copy to Clipboard Toggle word wrap
6.1.1.5. 管理 CLI を使用したスタンドアロンサーバーでのデプロイメントのリスト表示

スタンドアロンサーバー内のデプロイメントをリスト表示し、ランタイム名、ステータスなどのデプロイメント情報を表示できます。

前提条件

  • JBoss EAP が実行中である。

手順

  • deployment info コマンドを使用して、デプロイメント情報をリスト表示します。

    deployment info
    Copy to Clipboard Toggle word wrap

    出力には、ランタイム名、状態、有効であるかどうかなど、各デプロイメントの詳細が表示されます。

    NAME                 RUNTIME-NAME         PERSISTENT ENABLED STATUS
    helloworld.war       helloworld.war       true       true    OK
    test-application.war test-application.war true       true    OK
    Copy to Clipboard Toggle word wrap

    以下のコマンドは、名前を指定してデプロイメント情報を表示します。

    deployment info helloworld.war
    Copy to Clipboard Toggle word wrap

deployment list コマンドを使用して、デプロイメントをすべて表示することもできます。

6.1.2. マネージドドメインでのアプリケーションデプロイメントの管理

6.1.2.1. 管理 CLI を使用したマネージドドメインへのアプリケーションのデプロイ

管理 CLI で deployment deploy-file コマンドを使用し、アプリケーションをデプロイするサーバーグループを指定して、アプリケーションをスタンドアロンサーバーにデプロイできます。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • 管理 CLI から、Web Archive (war) としてパッケージ化されたアプリケーションを特定のサーバーグループまたはすべてのサーバーグループにデプロイできます。

    • 特定のサーバーグループにアプリケーションをデプロイする場合:

      構文

      deployment deploy-file <path_to_the_application>/<application_name>.war --server-groups=<server-group_1>,..., <server-group_1>
      Copy to Clipboard Toggle word wrap

      deployment deploy-file /my-applications/test-application.war --server-groups=main-server-group,other-server-group
      Copy to Clipboard Toggle word wrap

    • すべてのサーバーグループにアプリケーションをデプロイする場合:

      構文

      deployment deploy-file <path_to_the_application>/<application_name>.war --all-server-groups
      Copy to Clipboard Toggle word wrap

      deployment deploy-file /my-applications/test-application.war --all-server-groups
      Copy to Clipboard Toggle word wrap

      正常にデプロイされると、管理 CLI には何も出力されませんが、サーバーログに各サーバーのデプロイメントメッセージが記録されます。

    [Server:server-one] WFLYSRV0027: Starting deployment of "test-application.war" (runtime-name: "test-application.war")
    [Server:server-one] WFLYUT0021: Registered web context: /test-application
    [Server:server-one] WFLYSRV0010: Deployed "test-application.war" (runtime-name : "test-application.war")
    Copy to Clipboard Toggle word wrap

同様に、以下の deployment コマンドを使用できます。

  • deployment deploy-cli-archive コマンドを使用してコンテンツを .cli アーカイブファイルからデプロイします。CLI デプロイメントアーカイブは、.cli 拡張子を持つ JAR ファイルです。デプロイする必要があるアプリケーションアーカイブと、コマンドおよび操作が含まれる deploy.scr および undeploy.scr CLI スクリプトファイルが含まれます。deploy.scr スクリプトファイルには、アプリケーションアーカイブをデプロイし、環境を設定するコマンドと操作が含まれます。undeploy.scr スクリプトファイルには、アプリケーションアーカイブをアンデプロイし、環境をクリーンアップするコマンドが含まれます。
  • deployment deploy-url コマンドを使用して、URL によって参照されるコンテンツをデプロイします。
注記

--runtime-name オプションで runtime-name 属性を指定する場合は、名前に .war 拡張子を含める必要があります。そうしないと、Web コンテキストが JBoss EAP によって登録されません。

6.1.2.2. 管理 CLI を使用したマネージドドメインからのアプリケーションのアンデプロイ

管理 CLI の deployment undeploy コマンドを使用して、マネージドドメインとして実行されている JBoss EAP からアプリケーションをアンデプロイできます。アプリケーションをアンデプロイすると、リポジトリーからデプロイメントコンテンツが削除されます。デプロイメントコンテンツを保持しながらアプリケーションを使用不可にする場合は、代わりにデプロイメントを無効にできます。詳細は、管理 CLI を使用したマネージドドメイン内のアプリケーションの無効化 を参照してください。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • 管理 CLI から、アプリケーションデプロイメントを持つすべてのサーバーグループからアプリケーションをアンデプロイします。

    構文

    deployment undeploy <application_name>.war --all-relevant-server-groups
    Copy to Clipboard Toggle word wrap

    deployment undeploy test-application.war --all-relevant-server-groups
    Copy to Clipboard Toggle word wrap

    正常にアンデプロイされると、管理 CLI には何も出力されませんが、サーバーログに次の出力のような各サーバーのアンデプロイメントメッセージが記録されます。

[Server:server-one] WFLYUT0022: Unregistered web context: /test-application
[Server:server-one] WFLYSRV0028: Stopped deployment test-application.war (runtime-name: test-application.war) in 74ms
[Server:server-one] WFLYSRV0009: Undeployed "test-application.war" (runtime-name: "test-application.war")
Copy to Clipboard Toggle word wrap

同様に、deployment undeploy-cli-archive コマンドを使用して .cli アーカイブファイルからコンテンツをアンデプロイできます。ワイルドカード (*) を使用してすべてのデプロイメントをアンデプロイすることも可能です。

deployment undeploy * --all-relevant-server-groups
Copy to Clipboard Toggle word wrap
6.1.2.3. 管理 CLI を使用したマネージドドメイン内のアプリケーションの無効化

デプロイされたアプリケーションを特定のサーバーグループから無効にし、そのデプロイメントを持つ他のサーバーグループのリポジトリーにそのコンテンツを保持できます。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • 管理 CLI から deployment disable コマンドを使用して、JBoss EAP にデプロイされた 1 つまたはすべてのアプリケーションを無効にできます。

    • 1 つのアプリケーションを無効にする場合:

      構文

      deployment disable <application_name>.war --server-groups=<server-group_1>,..., <server-group_1>
      Copy to Clipboard Toggle word wrap

      deployment disable test-application.war --server-groups=other-server-group
      Copy to Clipboard Toggle word wrap

    • すべてのデプロイメントを無効にする場合:

      構文

      deployment disable-all --server-groups=<server-group_1>,..., <server-group_1>
      Copy to Clipboard Toggle word wrap

      deployment disable-all --server-groups=other-server-group
      Copy to Clipboard Toggle word wrap

6.1.2.4. 管理 CLI を使用したマネージドドメイン内のアプリケーションの有効化

無効になっているデプロイされたアプリケーションを有効にします。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • 管理 CLI から deployment enable コマンドを使用して、JBoss EAP にデプロイされた 1 つまたはすべてのアプリケーションを有効にできます。

    • 1 つのデプロイメントを有効化する場合:

      構文

      deployment enable <deployment> --server-groups=<server-group_1>,..., <server-group_1>
      Copy to Clipboard Toggle word wrap

      deployment enable test-application.war --server-groups=other-server-group
      Copy to Clipboard Toggle word wrap

    • すべてのデプロイメントを有効化する場合:

      deployment enable-all --server-groups=<server-group_1>,..., <server-group_1>
      Copy to Clipboard Toggle word wrap

      deployment enable-all --server-groups=other-server-group
      Copy to Clipboard Toggle word wrap

6.1.2.5. 管理 CLI を使用したマネージドドメイン内のデプロイメントのリスト表示

デプロイメントをリスト表示し、ランタイム名、ステータスなどのデプロイメント情報を表示できます。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • deployment info コマンドを使用して、デプロイメント情報をリスト表示します。

    deployment info helloworld.war
    Copy to Clipboard Toggle word wrap

    出力には、デプロイメントと各サーバーグループでの状態が表示されます。

    NAME               RUNTIME-NAME
    helloworld.war     helloworld.war
    
    SERVER-GROUP       STATE
    main-server-group  enabled
    other-server-group added
    Copy to Clipboard Toggle word wrap

    以下のコマンドは、サーバーグループを指定してデプロイメント情報を表示します。

    deployment info --server-group=other-server-group
    Copy to Clipboard Toggle word wrap

    出力には、デプロイメントと、指定のサーバーグループに対する状態が表示されます。

    NAME                 RUNTIME-NAME         STATE
    helloworld.war       helloworld.war       added
    test-application.war test-application.war enabled
    Copy to Clipboard Toggle word wrap

deployment list コマンドを使用して、ドメインのデプロイメントをすべて表示することもできます。

6.2. 管理コンソールを使用したアプリケーションデプロイメントの管理

管理コンソールを使用してアプリケーションをデプロイすると、使用が簡単なグラフィカルインターフェイスを利用することができます。サーバーまたはサーバーグループにデプロイされたアプリケーションを一目で確認できるほか、必要に応じてアプリケーションを有効または無効にしたり、アプリケーションをコンテンツリポジトリーから削除したりすることができます。

6.2.1. 管理コンソールを使用したスタンドアロンサーバーへのアプリケーションのデプロイ

JBoss EAP 管理コンソールの Deployments タブからデプロイメントを表示および管理できます。

アプリケーションのデプロイ

追加 (+) ボタンをクリックします。デプロイメントのアップロード未管理デプロイメントの追加、または 空のデプロイメントの作成 を選択して、アプリケーションをデプロイできます。デプロイメントはデフォルトで有効になります。

  • 新規デプロイメントのアップロード

    サーバーのコンテンツリポジトリーにコピーされ、JBoss EAP によって管理されるアプリケーションをアップロードします。

  • 未管理デプロイメントの追加

    デプロイメントの場所を指定します。このデプロイメントはサーバーのコンテンツリポジトリーにはコピーされず、JBoss EAP によって管理されません。

  • 空のデプロイメントの作成

    空の展開形式 (exploded) のデプロイメントを作成します。このデプロイメントの作成後、ファイルをデプロイメントに追加できます。

アプリケーションのアンデプロイ

デプロイメントを選択し、Undeploy オプションを選びます。JBoss EAP により、コンテンツリポジトリーからデプロイメントが削除されます。

アプリケーションの無効化

デプロイメントを選択し、無効 オプションを選択してアプリケーションを無効にします。これにより、デプロイメントがアンデプロイされますが、コンテンツリポジトリーから削除されません。

アプリケーションの置換

デプロイメントを選択し、置換 オプションを選択します。元のバージョンと同じ名前を持つ新しいバージョンのデプロイメントを選択し、Finish をクリックします。これにより、元のバージョンのデプロイメントがアンデプロイおよび削除され、新しいバージョンがデプロイされます。

JBoss EAP 管理コンソールの Deployments タブではデプロイメントを表示および管理できます。

  • Content Repository

    管理されるデプロイメントと管理されないデプロイメントはすべて Content Repository セクションで表示されます。ここで、デプロイメントを追加したり、デプロイメントをサーバーグループにデプロイすることができます。

  • Server Groups

    1 つまたは複数のサーバーグループにデプロイされたデプロイメントは Server Groups セクションにリストされます。ここで、デプロイメントを直接サーバーグループに追加したり、有効にしたりすることができます。

6.2.2.1. 管理コンソールを使用したコンテンツリポジトリーへのアプリケーションの追加

管理コンソールを使用して、コンテンツリポジトリーにアプリケーションを追加できます。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。

手順

  1. 管理コンソールにログインします。

    デフォルトでは、管理コンソールには http://localhost:9990 からアクセスできます。

  2. Content Repository から、Add ボタンをクリックします。
  3. デプロイメントのアップロード または 未管理のデプロイメント作成 を選択し、アプリケーションを追加します。
  4. プロンプトに従ってアプリケーションをデプロイします。

    デプロイメントを有効にするには、デプロイメントをサーバーグループにデプロイする必要があります。

6.2.2.2. 管理コンソールを使用したサーバーグループへのアプリケーションのデプロイ

管理コンソールを使用して、アプリケーションをサーバーグループにデプロイできます。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。
  • アプリケーションをコンテンツリポジトリーに追加した。

手順

  1. 管理コンソールにログインします。

    デフォルトでは、管理コンソールには http://localhost:9990 からアクセスできます。

  2. Content Repository でデプロイメントを選択し、Deploy を選択します。
  3. このデプロイメントをデプロイするサーバーグループを 1 つ以上選択します。
  4. 選択したサーバーグループのデプロイメントを有効にするオプションを任意で選択することもできます。
6.2.2.3. 管理コンソールを使用したサーバーグループからのアプリケーションのアンデプロイ

管理コンソールを使用して、サーバーグループからアプリケーションをアンデプロイできます。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。

手順

  1. Server Groups で適切なサーバーグループを選択します。
  2. 希望のデプロイメントを選択し、Undeploy ボタンをクリックします。

また、Content Repository でデプロイメントの Undeploy ボタンを選択して、複数のサーバーグループから 1 度にデプロイメントをアンデプロイすることもできます。

6.2.2.4. 管理コンソールを使用したマネージドドメインからのアプリケーションの削除

管理コンソールを使用して、マネージドドメインからアプリケーションを削除できます。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。

手順

  1. デプロイメントがサーバーグループにデプロイされている場合は、必ずデプロイメントをアンデプロイします。
  2. Content Repository でデプロイメントを選択し、削除 を選択します。

これにより、コンテンツリポジトリーからデプロイメントが削除されます。

6.2.2.5. 管理コンソールを使用したマネージドドメイン内のアプリケーションの無効化

管理コンソールを使用して、マネージドドメイン内のアプリケーションを無効にできます。アプリケーションを無効にしても、アプリケーションはサーバーからアンデプロイされるだけで、コンテンツリポジトリーからは削除されません。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。

手順

  1. Server Groups で適切なサーバーグループを選択します。
  2. 無効にするデプロイメントを選択し、無効 を選択します。

これにより、デプロイメントがアンデプロイされますが、コンテンツリポジトリーから削除されません。

6.2.2.6. 管理コンソールを使用したマネージドドメイン内のアプリケーションの置き換え

管理コンソールを使用して、マネージドドメイン内のアプリケーションデプロイメントを新しいバージョンに置き換えることができます。

前提条件

  • JBoss EAP が実行中である。
  • JBoss EAP でユーザーを作成した。

手順

  1. Content Repository からデプロイメントを選択し、置換 ボタンをクリックします。
  2. 元のバージョンと同じ名前を持つ新しいバージョンのデプロイメントを選択し、置換 をクリックします。

これにより、元のバージョンのデプロイメントがアンデプロイおよび削除され、新しいバージョンがデプロイされます。

6.3. デプロイメントスキャナーを使用したアプリケーションのデプロイ

デプロイメントスキャナーは、デプロイするアプリケーションのデプロイメントディレクトリーを監視します。デフォルトでは、デプロイメントスキャナーは 5 秒ごとに EAP_HOME/standalone/deployments/ をスキャンし、変更を確認します。デプロイメントの状態を示し、アンデプロイや再デプロイなどのデプロイメントに対するアクションをトリガーするため、マーカーファイルが使用されます。

本番環境では、アプリケーションのデプロイメントに管理コンソールまたは管理 CLI の使用が推奨されますが、デプロイメントスキャナーは開発者の便宜を図るために提供されます。これにより、ペースの早い開発サイクルに適した方法でアプリケーションを構築およびテストできます。デプロイメントスキャナーは、他のデプロイメント方法と併用しないでください。

デプロイメントスキャナーは JBoss EAP をスタンドアロンサーバーとして実行している場合のみ利用できます。

デプロイメントスキャナーを設定して、XML、zip 形式、および展開形式のコンテンツの自動デプロイメントを有効または無効にすることができます。自動デプロイメントが無効の場合、マーカーファイルを手作業で作成してデプロイメントのアクションをトリガーする必要があります。利用できるマーカーファイルタイプやそれらの目的に関する詳細は、デプロイメントスキャナーのマーカーファイル の項を参照してください。

デフォルトでは、XML および zip 形式のコンテンツの自動デプロイメントは有効になっています。各コンテンツタイプの自動デプロイメントの設定に関する詳細は デプロイメントスキャナーの設定 を参照してください。

警告

デプロイメントスキャナーを使用したデプロイメントは開発者の便宜を図るために提供され、本番環境での使用は推奨されません。デプロイメントスキャナーは他のデプロイメント方法と併用しないでください。

アプリケーションのデプロイ

コンテンツをデプロイメントフォルダーにコピーします。

$ cp /path/to/test-application.war EAP_HOME/standalone/deployments/
Copy to Clipboard Toggle word wrap

自動デプロイメントが有効の場合、このファイルは自動的に選択され、デプロイされます。さらに、.deployed マーカーファイルが作成されます。自動デプロイメントが無効の場合、.dodeploy マーカーファイルを手作業で追加し、デプロイメントをトリガーする必要があります。

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy
Copy to Clipboard Toggle word wrap
アプリケーションのアンデプロイ

.deployed マーカーファイルを削除して、アンデプロイメントをトリガーします。

$ rm EAP_HOME/standalone/deployments/test-application.war.deployed
Copy to Clipboard Toggle word wrap

自動デプロイメントが有効な場合、アンデプロイメントをトリガーする test-application.war ファイルを削除することもできます。これは、展開形式のデプロイメントには適用されないことに注意してください。

アプリケーションの再デプロイ

.dodeploy マーカーファイルを作成し、再デプロイを開始します。

$ touch EAP_HOME/standalone/deployments/test-application.war.dodeploy
Copy to Clipboard Toggle word wrap

6.3.2. デプロイメントスキャナーの設定

デプロイメントスキャナーは管理コンソールまたは管理 CLI を使用して設定できます。スキャンの間隔、デプロイメントフォルダーの場所、特定のアプリケーションファイルタイプの自動デプロイメントなど、デプロイメントスキャナーの動作を設定できます。また、デプロイメントスキャナーを完全に無効にすることもできます。

利用できるデプロイメントスキャナー属性の詳細は、デプロイメントスキャナーの属性 の項を参照してください。

以下の管理 CLI コマンドを使用してデフォルトのデプロイメントスキャナーを設定します。

デプロイメントスキャナーの無効化
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-enabled,value=false)
Copy to Clipboard Toggle word wrap

default デプロイメントスキャナーが無効になります。

スキャン間隔の変更
/subsystem=deployment-scanner/scanner=default:write-attribute(name=scan-interval,value=10000)
Copy to Clipboard Toggle word wrap

スキャンの間隔が 5000 ミリ秒 (5 秒) から 10000 ミリ秒 (10 秒) に変更されます。

デプロイメントフォルダーの変更
/subsystem=deployment-scanner/scanner=default:write-attribute(name=path,value=/path/to/deployments)
Copy to Clipboard Toggle word wrap

デプロイメントフォルダーの場所がデフォルトの EAP_HOME/standalone/deployments から /path/to/deployments に変更されます。

relative-to 属性が指定されていない場合、path の値は絶対パスになります。relative-to 属性が指定されている場合は相対パスになります。

展開形式のコンテンツの自動デプロイメントを有効にする
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-exploded,value=true)
Copy to Clipboard Toggle word wrap

デフォルトで無効になっている展開形式のコンテンツの自動デプロイメントを有効にします。

zip 形式のコンテンツの自動デプロイメントを無効にする
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-zipped,value=false)
Copy to Clipboard Toggle word wrap

デフォルトで有効になっている zip 形式のコンテンツの自動デプロイメントを無効にします。

XML コンテンツの自動デプロイメントの無効化
/subsystem=deployment-scanner/scanner=default:write-attribute(name=auto-deploy-xml,value=false)
Copy to Clipboard Toggle word wrap

デフォルトで有効になっている XML コンテンツの自動デプロイメントを無効にします。

6.3.3. カスタムのデプロイメントスキャナー

新しいデプロイメントスキャナーを追加するには、管理 CLI を使用するか、管理コンソールの Configuration タブから Deployment Scanners サブシステムに移動します。デプロイメントを確認するためにスキャンする新しいディレクトリーを定義します。デフォルトのデプロイメントスキャナーは EAP_HOME/standalone/deployments を監視します。既存のデプロイメントスキャナーの設定に関する詳細は、デプロイメントスキャナーの設定 を参照してください。

以下の管理 CLI コマンドは、EAP_HOME/standalone/new_deployment_dir を 5 秒ごとにチェックしてデプロイメントを確認する新しいデプロイメントスキャナーを追加します。

/subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
Copy to Clipboard Toggle word wrap
注記

指定のディレクトリーがすでに存在しないと、このコマンドに失敗し、エラーが発生します。

新しいデプロイメントスキャナーが定義され、デプロイメントを確認するために指定のディレクトリーが監視されます。

6.4. Maven を使用したアプリケーションデプロイメントの管理

Apache Maven を使用してアプリケーションをデプロイすると、JBoss EAP へのデプロイメントを簡単に既存の開発ワークフローに取り入れることができます。

アプリケーションをアプリケーションサーバーにデプロイおよびアンデプロイする簡単な操作を提供する WildFly Maven Plugin を使用すると、Maven を使用してアプリケーションを JBoss EAP にデプロイできます。

6.4.1. Maven を使用したスタンドアロンサーバーでのアプリケーションデプロイメントの管理

WildFly Maven プラグインを使用すると、スタンドアロンサーバーとして実行されている JBoss EAP にアプリケーションをデプロイおよびアンデプロイできます。

6.4.1.1. Maven を使用したスタンドアロンサーバーへのアプリケーションのデプロイ

次の手順では、Maven を使用して JBoss EAP helloworld クイックスタートをスタンドアロンサーバーにアンデプロイする方法を示します。

JBoss EAP クイックスタートの詳細は、JBoss EAP スタートガイドクイックスタートサンプルの使用 を参照してください。

手順

  1. Maven pom.xml ファイルで WildFly Maven Plugin を初期化します。これは、JBoss EAP クイックスタートの pom.xml ファイルで設定されているはずです。

    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <version>${version.wildfly.maven.plugin}</version>
    </plugin>
    Copy to Clipboard Toggle word wrap
  2. helloworld クイックスタートディレクトリーで以下の Maven コマンドを実行します。

    $ mvn clean install wildfly:deploy
    Copy to Clipboard Toggle word wrap

    デプロイする Maven コマンドの実行後、ターミナルウインドウにはデプロイメントの成功を表す以下の出力が表示されます。

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 2.981 s
    [INFO] Finished at: 2015-12-23T15:06:13-05:00
    [INFO] Final Memory: 21M/231M
    [INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

検証

  • アクティブなサーバーインスタンスのサーバーログでデプロイメントの成功を確認することもできます。

    WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
    WFLYUT0021: Registered web context: /helloworld
    WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
    Copy to Clipboard Toggle word wrap
6.4.1.2. Maven を使用したスタンドアロンサーバーからのアプリケーションのアンデプロイ

次の手順では、Maven を使用して JBoss EAP helloworld クイックスタートをスタンドアロンサーバーにアンデプロイする方法を示します。

前提条件

  • Maven pom.xml ファイルで WildFly Maven プラグインを初期化した。

手順

  • helloworld クイックスタートディレクトリーで以下の Maven コマンドを実行します。

    $ mvn wildfly:undeploy
    Copy to Clipboard Toggle word wrap

    アンデプロイする Maven コマンドの実行後、ターミナルウインドウにはアンデプロイメントの成功を表す以下の出力が表示されます。

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 1.237 s
    [INFO] Finished at: 2015-12-23T15:09:10-05:00
    [INFO] Final Memory: 10M/183M
    [INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

検証

  • アクティブなサーバーインスタンスのサーバーログでアンデプロイメントの成功を確認することもできます。

    WFLYUT0022: Unregistered web context: /helloworld
    WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 27ms
    WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")
    Copy to Clipboard Toggle word wrap

6.4.2. Maven を使用したマネージドドメインでのアプリケーションデプロイメントの管理

WildFly Maven プラグインを使用して、マネージドドメインとして実行されている JBoss EAP にアプリケーションをデプロイおよびアンデプロイできます。

6.4.2.1. Maven を使用したマネージドドメインへのアプリケーションのデプロイ

次の手順では、Maven を使用してマネージドドメインに JBoss EAP helloworld クイックスタートをデプロイする方法を示します。

JBoss EAP クイックスタートの詳細は、JBoss EAP スタートガイドクイックスタートサンプルの使用 を参照してください。

手順

  1. Maven pom.xml ファイルで、アプリケーションをデプロイするサーバーグループを指定します。pom.xml の以下の設定は WildFly Maven Plugin を初期化し、main-server-group をアプリケーションがデプロイされるサーバーグループとして指定します。

    <plugin>
      <groupId>org.wildfly.plugins</groupId>
      <artifactId>wildfly-maven-plugin</artifactId>
      <version>${version.wildfly.maven.plugin}</version>
      <configuration>
        <domain>
          <server-groups>
            <server-group>main-server-group</server-group>
          </server-groups>
        </domain>
      </configuration>
    </plugin>
    Copy to Clipboard Toggle word wrap
  2. helloworld クイックスタートディレクトリーで以下の Maven コマンドを実行します。

    $ mvn clean install wildfly:deploy
    Copy to Clipboard Toggle word wrap

    デプロイする Maven コマンドの実行後、ターミナルウインドウにはデプロイメントの成功を表す以下の出力が表示されます。

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 4.005 s
    [INFO] Finished at: 2016-09-02T14:36:17-04:00
    [INFO] Final Memory: 21M/226M
    [INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

    検証

    • アクティブなサーバーインスタンスのサーバーログでデプロイメントの成功を確認することもできます。

      WFLYSRV0027: Starting deployment of "helloworld.war" (runtime-name: "helloworld.war")
      WFLYUT0021: Registered web context: /helloworld
      WFLYSRV0010: Deployed "helloworld.war" (runtime-name : "helloworld.war")
      Copy to Clipboard Toggle word wrap
6.4.2.2. Maven を使用したマネージドドメインからのアプリケーションのアンデプロイ

次の手順では、Maven を使用してマネージドドメインに JBoss EAP helloworld クイックスタートをデプロイする方法を示します。

前提条件

  • WildFly Maven プラグインを初期化した。

手順

  • helloworld クイックスタートディレクトリーで以下の Maven コマンドを実行します。

    $ mvn wildfly:undeploy
    Copy to Clipboard Toggle word wrap

    アンデプロイする Maven コマンドの実行後、ターミナルウインドウにはアンデプロイメントの成功を表す以下の出力が表示されます。

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 1.750 s
    [INFO] Finished at: 2016-09-02T14:45:10-04:00
    [INFO] Final Memory: 10M/184M
    [INFO] ------------------------------------------------------------------------
    Copy to Clipboard Toggle word wrap

検証

  • アクティブなサーバーインスタンスのサーバーログでアンデプロイメントの成功を確認することもできます。
WFLYUT0022: Unregistered web context: /helloworld
WFLYSRV0028: Stopped deployment helloworld.war (runtime-name: helloworld.war) in 106ms
WFLYSRV0009: Undeployed "helloworld.war" (runtime-name: "helloworld.war")
Copy to Clipboard Toggle word wrap

6.5. HTTP API を使用したアプリケーションデプロイメントの管理

HTTP API を使用してアプリケーションを JBoss EAP にデプロイするには、curl コマンドを使用します。HTTP API の使用に関する詳細は、HTTP API セクションを参照してください。

6.5.1. HTTP API を使用したスタンドアロンサーバーでのアプリケーションデプロイメント管理

デフォルトでは、HTTP API は http://HOST:PORT/management でアクセスできます (例: http://localhost:9990/management)。

アプリケーションのデプロイ

$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:/path/to/test-application.war"}]},{"operation" : "deploy", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'
Copy to Clipboard Toggle word wrap

アプリケーションのアンデプロイ

$ curl --digest -L -D - http://HOST:PORT/management --header "Content-Type: application/json" -u USER:PASSWORD -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "test-application.war"}},{"operation" : "remove", "address" : {"deployment" : "test-application.war"}}],"json.pretty":1}'
Copy to Clipboard Toggle word wrap

JSON リクエストをプログラムで生成する方法の詳細は、この Red Hat ナレッジベースの記事 を参照してください。

6.5.2. HTTP API を使用したマネージドドメインでのアプリケーションデプロイメントの管理

HTTP API を使用して、マネージドドメインにアプリケーションをデプロイおよびアンデプロイできます。

6.5.2.1. HTTP API を使用したマネージドドメインでのアプリケーションのデプロイ

デフォルトでは、HTTP API は http://HOST:PORT/management でアクセスできます (例: http://localhost:9990/management)。

手順

  1. デプロイメントをコンテンツリポジトリーに追加します。

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "add", "address" : {"deployment" : "test-application.war"}, "content" : [{"url" : "file:</path/to>/test-application.war"}],"json.pretty":1}'
    Copy to Clipboard Toggle word wrap
  2. デプロイメントを指定のサーバーグループに追加します。

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "add", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
    Copy to Clipboard Toggle word wrap
  3. サーバーグループにアプリケーションをデプロイします。

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "deploy", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
    Copy to Clipboard Toggle word wrap
6.5.2.2. HTTP API を使用したマネージドドメインでのアプリケーションのアンデプロイ

デフォルトでは、HTTP API は http://HOST:PORT/management でアクセスできます (例: http://localhost:9990/management)。

手順

  1. 割り当てられたサーバーグループすべてからデプロイメントを削除します。

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "remove", "address" : {"server-group" : "main-server-group","deployment":"test-application.war"},"json.pretty":1}'
    Copy to Clipboard Toggle word wrap
  2. コンテンツリポジトリーからデプロイメントを削除します。

    $ curl --digest -L -D - http://<HOST>:<PORT>/management --header "Content-Type: application/json" -u <USER>:<PASSWORD> -d '{"operation" : "remove", "address" : {"deployment" : "test-application.war"}, "json.pretty":1}'
    Copy to Clipboard Toggle word wrap

6.6. デプロイメントの動作のカスタマイズ

6.6.1. デプロイメントコンテンツ用のカスタムディレクトリー

JBoss EAP では、デプロイされたコンテンツを格納する場所をカスタマイズし、定義できます。

スタンドアロンサーバーでのカスタムディレクトリーの定義

デフォルトでは、スタンドアロンサーバーのデプロイされたコンテンツは EAP_HOME/standalone/data/content ディレクトリーに格納されます。この場所を変更するには、サーバーの起動時に -Djboss.server.deploy.dir 引数を渡します。

$ EAP_HOME/bin/standalone.sh -Djboss.server.deploy.dir=/path/to/new_deployed_content
Copy to Clipboard Toggle word wrap

選択する場所は JBoss EAP インスタンスすべてで一意になる必要があります。

注記

jboss.server.deploy.dir プロパティーは、管理コンソールまたは管理 CLI を使用してデプロイされたコンテンツの格納に使用されるディレクトリーを指定します。デプロイメントスキャナーによって監視されるカスタムデプロイメントディレクトリーを定義するには、デプロイメントスキャナーの設定 を参照してください。

マネージドドメインでのカスタムディレクトリーの定義

デフォルトでは、マネージドドメインのデプロイされたコンテンツは EAP_HOME/domain/data/content ディレクトリーに格納されます。この場所を変更するには、ドメインの起動時に -Djboss.domain.deployment.dir 引数を渡します。

$ EAP_HOME/bin/domain.sh -Djboss.domain.deployment.dir=/path/to/new_deployed_content
Copy to Clipboard Toggle word wrap

選択する場所は JBoss EAP インスタンスすべてで一意になる必要があります。

6.6.2. デプロイメント順序の制御

JBoss EAP では、サーバー起動時にアプリケーションがデプロイされる順序を細かく制御できます。複数の EAR ファイルに存在するアプリケーションのデプロイメント順序を徹底することができ、再起動後の順序を永続化することもできます。

jboss-all.xml デプロイメント記述子を使用してトップレベルのデプロイメント間で依存関係を宣言できます。

たとえば、最初にデプロイされた framework.ear に依存する app.ear がある場合、以下のように app.ear/META-INF/jboss-all.xml ファイルを作成できます。

<jboss xmlns="urn:jboss:1.0">
  <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
    <dependency name="framework.ear" />
  </jboss-deployment-dependencies>
</jboss>
Copy to Clipboard Toggle word wrap
注記

デプロイメントのランタイム名を jboss-all.xml ファイルの依存名として使用することができます。

これにより、app.ear の前に framework.ear がデプロイされます。

重要

app.earjboss-all.xml ファイルを作成し、framework.ear をデプロイしない場合、サーバーは app.ear のデプロイを試行して失敗します。

6.6.3. デプロイメントコンテンツのオーバーライド

6.6.3.1. デプロイメントオーバーレイについて

デプロイメントオーバーレイ を使用すると、デプロイメントアーカイブのコンテンツを物理的に変更せずに既存デプロイメントにコンテンツをオーバーレイすることができます。これにより、アーカイブを再構築せずに実行時にデプロイメント記述子、ライブラリー JAR ファイル、クラス、Jakarta Server Pages ページ、およびその他のファイルをオーバーライドできます。

これは、異なる設定が必要な異なる環境にデプロイメントを適応する必要がある場合に便利です。たとえば、アプリケーションのライフサイクルに従って開発からテスト、ステージ、および実稼働とデプロイメントを移動する場合、目的の環境に応じてデプロイメント記述子の交換、アプリケーションのブランディングを変更するための静的 Web リソースの変更、JAR ライブラリーの別バージョンへの置き換えなどを行う可能性があります。また、方針やセキュリティーの制限によりアーカイブを変更できない、設定変更が必要なインストールにも便利な機能です。

デプロイメントオーバーレイを定義する場合、デプロイメントアーカイブのファイルを置き換える、ファイルシステム上のファイルを定義します。さらに、デプロイメントオーバーレイの影響を受けるデプロイメントを指定する必要もあります。変更を有効にするには、影響を受けるデプロイメントを再デプロイする必要があります。

パラメーター

以下のパラメーターのいずれかを使用して、デプロイメントオーバーレイを設定できます。

  • name: デプロイメントオーバーレイの名前。
  • content: ファイルシステム上のファイルを、アーカイブ内の置き換えるファイルにマップするコンマ区切りリスト。各エントリーの形式は ARCHIVE_PATH=FILESYSTEM_PATH です。
  • deployments: このオーバーレイがリンクされるデプロイメントのコンマ区切りリスト。
  • redeploy-affected: 影響を受けるデプロイメントをすべて再デプロイします。

使用方法の詳細を表示するには deployment-overlay --help を実行してください。

6.6.3.2. デプロイメントオーバーレイの定義

デプロイメントオーバーレイを定義すると、デプロイメントアーカイブのコンテンツを物理的に変更せずに、既存のデプロイメントにコンテンツをオーバーレイできます。

手順

  1. deployment-overlay add 管理 CLI コマンドを使用してデプロイメントオーバーレイを追加します。

    deployment-overlay add --name=new-deployment-overlay --content=WEB-INF/web.xml=/path/to/other/web.xml --deployments=test-application.war --redeploy-affected
    Copy to Clipboard Toggle word wrap
    注記

    管理対象ドメインでは、--server-groups を使用して該当するサーバーグループを指定するか、--all-server-groups を使用してすべてのサーバーグループを指定します。

  2. デプロイメントオーバーレイの作成後、既存のオーバーレイへのコンテンツの追加、オーバーレイのデプロイメントへのリンク、またはオーバーレイの削除を行うことができます。
  3. オプション: オーバーレイ設定を指定し、<overlay> 要素を使用して、HTML、イメージ、またはビデオなどの静的 Web リソースが含まれる外部ディレクトリーにリンクできます。

    <overlay> 要素は、JAR オーバーレイの手順と同様に、Web アプリケーションの静的ファイルをオーバーレイする静的ファイルを指定します。この要素は、アプリケーションファイル jboss-web.xml にあります。この要素設定では、アプリケーションを再パッケージ化する必要はありません。

    以下の例は、<overlay> 要素のシステムプロパティーの置換を示しています。{example.path.to.overlay} は、/PATH/TO/STATIC/WEB/CONTENT の場所を定義します。

    例: jboss-web.xml ファイルの <overlay> 要素

    <jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_10_0.xsd"
               version="10.0">
            <overlay>{example.path.to.overlay}</overlay>
    </jboss-web>
    Copy to Clipboard Toggle word wrap

    jboss-descriptor-property-replacementtrue に設定されている場合、<overlay> 要素にシステムプロパティーを指定できます。

    jboss-descriptor-property-replacement を設定するには、以下の管理 CLI コマンドを使用します。

    /subsystem=ee:write-attribute(name=jboss-descriptor-property-replacement,value=true)
    Copy to Clipboard Toggle word wrap

    このコマンドは、以下の XML コンテンツを JBoss EAP 設定の ee サブシステムに追加します。

    <subsystem xmlns="urn:jboss:domain:ee:4.0">
        <jboss-descriptor-property-replacement>true</jboss-descriptor-property-replacement>
    </subsystem>
    Copy to Clipboard Toggle word wrap
    注記

    <overlay> 要素は、EAP プロジェクトにすでに存在するデプロイメントファイルをオーバーライドしません。複数の <overlay> 要素に同じファイルが含まれている場合、優先順位はアプリケーションの jboss-web.xml ファイル内のオーバーレイ要素の順序に基づいて決定されます。

6.6.4. ロールアウト計画の使用

マネージドドメインでは、ドメインまたはホストレベルのリソースで目的となる操作は複数のサーバーに影響する可能性があります。このような操作には、サーバーに適用される操作の順序を説明するロールアウト計画や、一部のサーバーで実行に失敗した場合に操作を元に戻すかどうかを指示するポリシーなどが含まれます。指定されたロールアウト計画がない場合、デフォルトのロールアウト計画 が使用されます。

6.6.4.1. ロールアウト計画の例

以下は 5 つのサーバーグループが関係するロールアウト計画の例になります。操作は順次 (in-series) または同時 (concurrent-groups) にサーバーグループへ適用することができます。詳細は、ロールアウト計画の構文 を参照してください。

{"my-rollout-plan" => {"rollout-plan" => {
    "in-series" => [
        {"concurrent-groups" => {
            "group-A" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-B" => undefined
        }},
        {"server-group" => {"group-C" => {
            "rolling-to-servers" => "false",
            "max-failed-servers" => "1"
        }}},
        {"concurrent-groups" => {
            "group-D" => {
                "max-failure-percentage" => "20",
                "rolling-to-servers" => "true"
            },
            "group-E" => undefined
        }}
    ],
    "rollback-across-groups" => "true"
}}}
Copy to Clipboard Toggle word wrap

上記の例を見ると、3 つの段階を経てドメインのサーバーに操作が適用されることが分かります。あるサーバーグループのポリシーによってサーバーグループ全体で操作のロールバックが引き起こされると、他のサーバーグループもすべてロールバックされます。

  1. サーバーグループ group-Agroup-B には同時に操作が適用されます。group-A のサーバーには操作が順次適用され、group-B のすべてのサーバーは操作を同時に処理します。group-A で操作の適用に失敗したサーバーが 20 % を超えると、グループ全体でロールバックが実行されます。group-B で操作を適用できなかったサーバーがあると、このグループ全体でロールバックが実行されます。
  2. group-Agroup-B のすべてのサーバーが完了すると、group-C のサーバーに操作が適用されます。これらのサーバーは操作を同時に処理します。group-C では操作を適用できなかったサーバーが 2 台以上あると、グループ全体でロールバックが実行されます。
  3. group-C のすべてのサーバーが完了すると、操作が group-Dgroup-E に同時に適用されます。group-D のサーバーには操作が順次適用され、group-E のすべてのサーバーは操作を同時に処理します。group-D で操作の適用に失敗したサーバーが 20 % を超えると、グループ全体でロールバックが実行されます。group-E で操作を適用できなかったサーバーがあると、このグループ全体でロールバックが実行されます。
6.6.4.2. ロールアウト計画の構文

ロールアウト計画は以下のいずれかの方法で指定できます。

上記の方法で最初に使用するコマンドは異なりますが、どちらも rollout 操作ヘッダーを使用してロールアウト計画を定義します。以下の構文を使用します。

rollout (id=PLAN_NAME | SERVER_GROUP_LIST) [rollback-across-groups]
Copy to Clipboard Toggle word wrap
  • PLAN_NAME は、rollout-plan コマンドを使用して保存されたロールアウト計画の名前です。
  • SERVER_GROUP_LIST はサーバーグループのリストです。各サーバーグループで操作を順次実行する場合はコンマ (,) を使用して複数のサーバーグループを区切ります。各サーバーグループで同時に操作を実行する場合はキャレット (^) を区切り文字として使用します。

    • 各サーバーグループでは、以下のポリシーをかっこで囲んで設定します。複数のポリシーはコンマで区切ります。

      • rolling-to-servers: ブール値。true に設定すると、操作はグループの各サーバーに順次適用されます。false に設定した場合、または指定がない場合は、操作はグループのサーバーに同時に適用されます。
      • max-failed-servers: 整数値。グループにおける操作の適用に失敗したサーバー合計数の最大率 (パーセント) で、失敗したサーバーの率がこの値を超えるとグループのすべてのサーバーが元に戻されます。指定がない場合のデフォルト値は 0 で、操作の適用に失敗したサーバーが 1 台でもあるとグループ全体でロールバックが引き起こされます。
      • max-failure-percentage: 0 から 100 までの整数値。グループにおける操作の適用に失敗したサーバー合計数の最大率 (パーセント) で、失敗したサーバーの率がこの値を超えるとグループのすべてのサーバーが元に戻されます。指定がない場合のデフォルト値は 0 で、操作の適用に失敗したサーバーが 1 台でもあるとグループ全体でロールバックが引き起こされます。

        注記

        max-failed-serversmax-failure-percentage の両方がゼロ以外の値に設定された場合、max-failure-percentage が優先されます。

  • rollback-across-groups: ブール値。1 つのサーバーグループのサーバーすべてで操作をロールバックする必要があると、すべてのサーバーグループでロールバックの実行を引き起こすかどうかを指定します。デフォルトは false です。
6.6.4.3. ロールアウト計画を使用したアプリケーションのデプロイ

ロールアウト計画の完全詳細を直接 deploy コマンドに提供するには、rollout 設定を headers 引数に渡します。形式の詳細は ロールアウト計画の構文 を参照してください。

以下の管理 CLI コマンドは、順次のデプロイメントに rolling-to-servers=true を指定するデプロイメント計画を使用して、アプリケーションを main-server-group サーバーグループにデプロイします。

deploy /path/to/test-application.war --server-groups=main-server-group --headers={rollout main-server-group(rolling-to-servers=true)}
Copy to Clipboard Toggle word wrap
6.6.4.4. 保存保存されたロールアウト計画を使用したアプリケーションのデプロイ

ロールアウト計画は複雑になることがあるため、ロールアウト計画の詳細を保存するオプションがあります。これにより、毎回ロールアウト計画の完全詳細を必要とせずに、ロールアウト計画を使用するときにロールアウト計画の名前を参照することができます。

手順

  1. rollout-plan 管理 CLI コマンドを使用してロールアウト計画を保存します。形式の詳細は、ロールアウト計画の構文 を参照してください。

    rollout-plan add --name=my-rollout-plan --content={rollout main-server-group(rolling-to-servers=false,max-failed-servers=1),other-server-group(rolling-to-servers=true,max-failure-percentage=20) rollback-across-groups=true}
    Copy to Clipboard Toggle word wrap

    これにより、以下のデプロイメント計画が作成されます。

    "rollout-plan" => {
        "in-series" => [
            {"server-group" => {"main-server-group" => {
                "rolling-to-servers" => false,
                "max-failed-servers" => 1
            }}},
            {"server-group" => {"other-server-group" => {
                "rolling-to-servers" => true,
                "max-failure-percentage" => 20
            }}}
        ],
        "rollback-across-groups" => true
    }
    Copy to Clipboard Toggle word wrap
  2. アプリケーションのデプロイ時に保存されたロールアウト計画名を指定します。

    以下の管理 CLI コマンドは、保存されたロールアウト計画 my-rollout-plan を使用してすべてのサーバーグループにアプリケーションをデプロイします。

    deploy /path/to/test-application.war --all-server-groups --headers={rollout id=my-rollout-plan}
    Copy to Clipboard Toggle word wrap
6.6.4.5. 保存されたロールアウト計画の削除

削除するロールアウト計画の名前を指定して rollout-plan 管理 CLI コマンドを使用すると、保存されたロールアウト計画を削除できます。

rollout-plan remove --name=my-rollout-plan
Copy to Clipboard Toggle word wrap
6.6.4.6. デフォルトのロールアウト計画

複数のサーバーに影響する操作はすべてロールアウト計画を使用して実行されます。操作リクエストにロールアウト計画が指定されていない場合は、デフォルトのロールアウト計画が生成されます。計画には以下の特徴があります。

  • ハイレベルなフェーズは 1 つのみです。操作に影響するすべてのサーバーグループには同時に操作が適用されます。
  • 各サーバーグループ内では、操作がすべてのサーバーに同時に適用されます。
  • サーバーグループのいずれかのサーバーに操作を適用できないと、グループ全体でロールバックが実行されます。
  • あるサーバーグループに操作を適用できないと、他のすべてのサーバーグループでロールバックが実行されます。

6.7. 展開形式のデプロイメントの管理

管理インターフェイスを使用して、展開形式のデプロイメントを管理できます。これにより、新しいバージョンのアプリケーションをデプロイしなくても、展開形式のアプリケーションのコンテンツを変更できます。

注記

JavaScript や CSS ファイルなど、デプロイメントの静的ファイルが更新されると、即座に更新が反映されます。Java クラスなどの他のファイルが変更された場合は、変更の反映にアプリケーションの再デプロイが必要になることがあります。

最初に、空のデプロイメント を使用するか、既存のアーカイブデプロイメントをデプロイメント した後、コンテンツを追加または削除 します。

デプロイメントのコンテンツの表示 を参照してデプロイメントのファイルを閲覧するか、ファイルのコンテンツを読み取ります。

空の展開形式のデプロイメントを作成する

空の展開形式のデプロイメントを作成し、後で必要に応じてコンテンツを追加できます。次の管理 CLI コマンドを使用して、空の展開形式のデプロイメントを作成します。

/deployment=DEPLOYMENT_NAME.war:add(content=[{empty=true}])
Copy to Clipboard Toggle word wrap

empty=true オプションは、空のデプロイメントの作成を確認するために必要です。

既存のアーカイブデプロイメントのデプロイメント

既存のアーカイブデプロイメントをデプロイメントしてコンテンツを更新できます。デプロイメントする前に デプロイメントを無効化 する必要があります。以下の管理 CLI コマンドを使用してデプロイメントをデプロイメントします。

/deployment=ARCHIVE_DEPLOYMENT_NAME.ear:explode
Copy to Clipboard Toggle word wrap

これで、このデプロイメントの コンテンツを追加または削除 できるようになります。

注記

管理コンソールから既存のアーカイブデプロイメントをデプロイメントすることもできます。Deployments タブからデプロイメントを選択し、ドロップダウンメニューで Explode を選択します。

展開形式のデプロイメントにコンテンツを追加する

デプロイメントにコンテンツを追加するには、add-content 管理 CLI 操作を使用します。コンテンツを追加するデプロイメントの場所へのパスを指定し、アップロードするコンテンツを提供します。アップロードするコンテンツは、ローカルファイルストリーム、URL、JBoss EAP コンテンツリポジトリーにすでに存在するコンテンツのハッシュ、またはコンテンツのバイトアレイとして提供できます。以下の管理 CLI コマンドは、input-stream-index オプションを使用してローカルファイルのコンテンツをデプロイメントにアップロードします。

/deployment=DEPLOYMENT_NAME.war:add-content(content=[{target-path=/path/to/FILE_IN_DEPLOYMENT, input-stream-index=/path/to/LOCAL_FILE_TO_UPLOAD}]
Copy to Clipboard Toggle word wrap
注記

add-content 操作を使用してコンテンツをデプロイメントに追加するとき、デプロイメントのコンテンツはデフォルトで上書きされます。この挙動を変更するには、overwrite オプションを false に設定します。

展開形式のデプロイメントからコンテンツを削除する

デプロイメントからコンテンツを削除するには、remove-content 管理 CLI 操作を使用し、デプロイメントの削除するコンテンツへのパスを指定します。

/deployment=DEPLOYMENT_NAME.war:remove-content(paths=[/path/to/FILE_1, /path/to/FILE_2])
Copy to Clipboard Toggle word wrap

6.8. デプロイメントのコンテンツの表示

JBoss EAP の管理インターフェイスを使用すると、管理されたデプロイメントのファイルに関する 情報を閲覧 し、ファイルの 内容を読み取る ことができます。

6.8.1. デプロイメントのファイルの閲覧

管理されたデプロイメントのファイルやディレクトリーを閲覧するには、browse-content 操作を使用します。引数を指定しないと、デプロイメント構造全体が返されます。特定のディレクトリーへのパスを指定するには、path 引数を使用します。

注記

また、管理コンソールからデプロイメントの内容を閲覧することもできます。Deployments タブに移動してデプロイメントを選択し、ドロップダウンメニューで 表示 を選択します。

/deployment=helloworld.war:browse-content(path=META-INF/)
Copy to Clipboard Toggle word wrap

上記は、helloworld.war デプロイメントの META-INF/ ディレクトリーにあるファイルとディレクトリーを表示します。

{
    "outcome" => "success",
    "result" => [
        {
            "path" => "MANIFEST.MF",
            "directory" => false,
            "file-size" => 827L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.properties",
            "directory" => false,
            "file-size" => 106L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/pom.xml",
            "directory" => false,
            "file-size" => 2713L
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/helloworld/",
            "directory" => true
        },
        {
            "path" => "maven/org.jboss.eap.quickstarts/",
            "directory" => true
        },
        {
            "path" => "maven/",
            "directory" => true
        },
        {
            "path" => "INDEX.LIST",
            "directory" => false,
            "file-size" => 251L
        }
    ]
}
Copy to Clipboard Toggle word wrap

以下の引数を browse-content 操作に指定することもできます。

archive
アーカイブファイルのみを返すかどうか。
depth
返すファイルの深さを指定します。

6.8.2. デプロイメントのコンテンツの読み取り

管理されたデプロイメントでファイルの内容を読み取るには、read-content 操作を使用します。引数を指定しないと、デプロイメント全体が返されます。または、path 引数を指定して、特定のファイルへのパスを提供します。以下に例を示します。

/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)
Copy to Clipboard Toggle word wrap

上記は、管理 CLI に表示 または ファイルシステムに保存 できるファイルストリームを返します。

{
    "outcome" => "success",
    "result" => {"uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95"},
    "response-headers" => {"attached-streams" => [{
        "uuid" => "24ba8e06-21bd-4505-b4d4-bdfb16451b95",
        "mime-type" => "text/plain"
    }]}
}
Copy to Clipboard Toggle word wrap
6.8.2.1. ファイルの内容の表示

attachment display コマンドを使用して MANIFEST.MF ファイルの内容を読み取ります。

attachment display --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF)
Copy to Clipboard Toggle word wrap

上記は、helloworld.war デプロイメントからの MANIFEST.MF ファイルの内容を管理 CLI に表示します。

ATTACHMENT 8af87836-2abd-423a-8e44-e731cc57bd80:
Manifest-Version: 1.0
Implementation-Title: Quickstart: helloworld
Implementation-Version: 7.4.0.GA
Java-Version: 1.8.0_131
Built-By: username
Scm-Connection: scm:git:git@github.com:jboss/jboss-parent-pom.git/quic
 kstart-parent/helloworld
Specification-Vendor: JBoss by Red Hat
...
Copy to Clipboard Toggle word wrap
6.8.2.2. ファイルの内容の保存

attachment save コマンドを使用して、MANIFEST.MF ファイルの内容をファイルシステムに保存します。

attachment save --operation=/deployment=helloworld.war:read-content(path=META-INF/MANIFEST.MF) --file=/path/to/MANIFEST.MF
Copy to Clipboard Toggle word wrap

上記は、helloworld.war デプロイメントからの MANIFEST.MF ファイルを path/to/MANIFEST.MF のファイルシステムに保存します。--file 引数を使用してファイルパスを指定しないと、一意な添付 ID を使用してファイル名が付けられ、管理 CLI の作業ディレクトリー (デフォルトは EAP_HOME/bin/) に保存されます。

第7章 JBoss EAP のマネージドドメインの設定

マネージドドメインの操作モードを使用すると、単一の制御ポイントから複数の JBoss EAP インスタンスを管理できます。

一元管理された複数の JBoss EAP サーバーは、ドメインのメンバーと呼ばれます。ドメインの JBoss EAP インスタンスは共通の管理ポリシーを共有します。

ドメインは、1 つのドメインコントローラー、1 つ以上のホストコントローラー、およびホストごとに 0 個以上のサーバーグループで構成されます。

マネージドドメイン
ドメインコントローラー
ドメインコントローラーは、ドメインが制御される中心点です。ドメインの管理ポリシーに従って各サーバーが設定されるようにします。ドメインコントローラーはホストコントローラーでもあります。
ホストコントローラー
ホストコントローラーは、ドメインコントローラーとやり取りする物理ホストまたは仮想ホストであり、ホスト上で実行されているアプリケーションサーバーインスタンスのライフサイクルを制御します。また、ドメインコントローラーによるアプリケーションサーバーインスタンスの管理を支援します。各ホストに複数のサーバーグループが含まれるようにすることが可能です。
サーバーグループ
サーバーグループは、JBoss EAP がインストールされているサーバーインスタンスの集まりです。これは 1 つのサーバーインスタンスとして管理および設定されます。ドメインコントローラーはサーバーグループにデプロイされたアプリケーションとその設定を管理します。そのため、サーバーグループの各サーバーは同じ設定とデプロイメントを共有します。

ホストコントローラーは特定の物理または仮想ホストに割り当てられます。異なる設定を使用する場合は、同じハードウェア上で複数のホストコントローラーを実行でき、ポートとその他のリソースが競合しないようにします。1 つのドメインコントローラー、1 つのホストコントローラー、および複数のサーバーを、同じ物理システムの同じ JBoss EAP インスタンス内で実行することができます。

7.1. マネージドドメインにおけるドメインコントローラーの役割

ドメインコントローラーは、ドメインの集中管理点として動作する JBoss EAP サーバーインスタンスです。1 つのホストコントローラーインスタンスがドメインコントローラーとして動作するよう設定されます。

ドメインコントローラーの主な役割は次のとおりです。

  • ドメインの集中管理ポリシーを維持する。
  • すべてのホストコントローラーが現在のコンテンツを認識するようにする。
  • 実行中のすべての JBoss EAP サーバーインスタンスがこのポリシーに従って設定されるよう、ホストコントローラーをサポートする。

デフォルトでは、集中管理ポリシーは EAP_HOME/domain/configuration/domain.xml ファイルに格納されます。このファイルは、ドメインコントローラーとして動作するように設定されているホストコントローラーのディレクトリーに必要です。

domain.xml ファイルには、ドメインのサーバーに適用できるプロファイル設定が含まれています。プロファイルには、そのプロファイルで使用できるさまざまなサブシステムの詳細設定が含まれています。ドメイン設定には、ソケットグループの定義とサーバーグループの定義も含まれます。プロファイルの詳細は、プロファイルについて を参照してください。

7.2. マネージドドメインにおけるホストコントローラーの役割

ホストコントローラーの主な役割はサーバーを管理することです。ドメイン管理タスクを委譲し、ホスト上で実行される個別のアプリケーションサーバープロセスを開始および停止します。

ホストコントローラーはドメインコントローラーと対話し、サーバーとドメインコントローラー間の通信を管理できるようにします。ドメインの複数のホストコントローラーは 1 つのドメインコントローラーのみと対話できます。そのため、単一のドメインモード上で実行されるホストコントローラーおよびサーバーインスタンスはすべて単一のドメインコントローラーを持ち、同じドメインに属する必要があります。

デフォルトでは、各ホストコントローラーは、ホストのファイルシステムに展開された JBoss EAP インストールファイルにある EAP_HOME/domain/configuration/host.xml ファイルから設定を読み取ります。host.xml ファイルには、特定のホストに固有する以下の設定情報が含まれています。

  • このインストールから実行されるサーバーインスタンスの名前。
  • ローカルの物理インストールに固有する設定。たとえば、domain.xml に宣言された名前付きインターフェイスの定義は host.xml にある実際のマシン固有の IP アドレスへマップできます。さらに、domain.xml の抽象パス名を host.xml のファイルシステムパスへマップできます。
  • 次の設定のいずれか。

    • ホストコントローラーがドメインコントローラーへ通知して、ホストコントローラー自体を登録し、ドメイン設定へアクセスする方法。
    • リモートドメインコントローラーの検索および通知方法。
    • ホストコントローラーがドメインコントローラーとして動作するかどうか。

7.3. マネージドドメインにおけるプロセスコントローラーの役割

プロセスコントローラーは小型のライトウェイトなプロセスで、ホストコントローラープロセスを起動し、そのライフサイクルを監視します。ホストコントローラーがクラッシュすると、プロセスコントローラーによって再起動されます。さらに、ホストコントローラーの指示に従ってサーバープロセスを開始しますが、クラッシュしたサーバープロセスは自動的に再起動しません。

プロセスコントローラーのログは EAP_HOME/domain/log/process-controller.log ファイルに記録されます。プロセスコントローラーの JVM オプションは、PROCESS_CONTROLLER_JAVA_OPTS 変数を使用して EAP_HOME/bin/domain.conf ファイルに設定します。

7.4. マネージドドメイン内のサーバーグループについて

サーバーグループとは、1 つのグループとして管理および設定される複数のサーバーインスタンスのことです。マネージドドメインでは、各アプリケーションサーバーインスタンスは唯一のメンバーである場合でも 1 つのサーバーグループに属します。グループのサーバーインスタンスは同じプロファイル設定とデプロイされたコンテンツを共有します。

ドメインコントローラーとホストコントローラーは、ドメインにある各サーバーグループのすべてのインスタンスに標準設定を強制します。

ドメインは複数のサーバーグループで構成できます。異なるサーバーグループを異なるプロファイルやデプロイメントで設定できます。たとえば、ドメインは異なるサービスを提供する異なるサーバー層で設定できます。

異なるサーバーグループが同じプロファイルやデプロイメントを持つこともできます。これにより、最初のサーバーグループでアプリケーションがアップグレードされた後に 2 つ目のサーバーグループでアプリケーションが更新されるアプリケーションのローリングアップグレードが可能になり、サービスの完全停止を防ぎます。

7.5. マネージドドメイン内のサーバーについて

サーバーはアプリケーションサーバーインスタンスを表します。マネージドドメインでは、すべてのサーバーインスタンスがサーバーグループのメンバーになります。各サーバーインスタンスは、ホストコントローラーにより、独自の Java 仮想マシン (JVM) プロセスで起動されます。詳細は、マネージドドメインのサーバー設定 を参照してください。

7.6. ドメイン設定のナビゲーション

JBoss EAP は、規模の小さいマネージドドメインと規模の大きいマネージドドメインの両方をサポートするスケーラブルな管理インターフェイスを提供します。

管理コンソール

JBoss EAP 管理コンソールは、ドメインのグラフィカルビューを提供し、ドメインのホスト、サーバー、デプロイメント、およびプロファイルの管理を容易にします。

Configuration (設定)

Configuration タブからドメインで使用される各プロファイルのサブシステムを設定できます。必要な機能に応じて、メインの異なるサーバーグループが異なるプロファイルを使用することがあります。

希望のプロファイルを選択すると、そのプロファイルで利用できるサブシステムがすべて表示されます。プロファイルの設定の詳細は、JBoss EAP プロファイルの管理 を参照してください。

Runtime

Runtime タブから、サーバー、サーバーグループ、およびホストの設定を管理できます。ホストまたはサーバーグループごとにドメインを閲覧できます。

Hosts から、ホストプロパティーと JVM を設定でき、そのホストのサーバーを追加および設定することもできます。

Server Groups から、新しいサーバーグループを追加でき、プロパティーや JVM を設定できます。また、そのサーバーグループにサーバーを追加および設定することもできます。選択したサーバーグループの全サーバーの起動、停止、一時停止、およびリロードなど、操作を実行できます。

Hosts または Server Groups から、新しいサーバーを追加でき、サーバープロパティーや JVM を設定できます。選択したサーバーの起動、停止、一時停止、およびリロードなどの操作を実行できます。また、JVM の使用率、サーバーログ、サブシステム固有の情報など、ランタイム情報を表示することもできます。

Topology から、ドメインのホスト、サーバーグループ、およびサーバーの概要や詳細情報を表示できます。再ロードや停止などの操作をそれぞれに実行できます。

Deployments

Deployments タブから、デプロイメントをサーバーグループに追加およびデプロイできます。コンテンツリポジトリーのすべてのデプロイメントや、特定のサーバーグループにデプロイされたデプロイメントを表示できます。

管理コンソールを使用してアプリケーションをデプロイする方法の詳細は、マネージドドメインでのアプリケーションのデプロイ を参照してください。

管理 CLI

JBoss EAP 管理 CLI は、ドメインのホスト、サーバー、デプロイメントおよびプロファイルを管理するコマンドラインインターフェイスを提供します。

適切なプロファイルを選択するとサブシステムの設定にアクセスできます。

/profile=<profile_name>/subsystem=<subsystem_name>:read-resource(recursive=true)
Copy to Clipboard Toggle word wrap
注記

このガイドの手順や例では、スタンドアロンサーバーとして稼働している場合に適用されるサブシステム設定の管理 CLI コマンドが含まれている可能性があります。例を以下に示します。

/subsystem=datasources/data-source=ExampleDS:read-resource
Copy to Clipboard Toggle word wrap

マネージドドメインで実行するために管理 CLI コマンドを調整するには、設定するプロファイルを指定する必要があります。例を以下に示します。

/profile=default/subsystem=datasources/data-source=ExampleDS:read-resource
Copy to Clipboard Toggle word wrap

適切なホストを指定した後、ホストを設定し、そのホストのサーバーで操作を実行できます。

/host=<host_name>/server=<server_name>:read-resource
Copy to Clipboard Toggle word wrap

適切なホストの指定後、そのホストのサーバーを設定できます。

/host=<host_name>/server-config=<server_name>:write-attribute(name=<attribute_name>,value=<value>)
Copy to Clipboard Toggle word wrap

適切なサーバーグループの指定後、サーバーグループを設定し、選択したサーバーグループのすべてのサーバーで操作を実行することができます。

/server-group=<server_group_name>:read-resource
Copy to Clipboard Toggle word wrap

deploy 管理 CLI コマンドを使用し、適切なサーバーグループを指定すると、マネージドドメインでアプリケーションをデプロイできます。手順は、マネージドドメインでのアプリケーションのデプロイ を参照してください。

7.7. マネージドドメインの設定

7.7.1. JBoss EAP をマネージドドメインとして起動する

ドメインおよびホストコントローラーは、JBoss EAP に同梱される domain.sh または domain.bat スクリプトを使用して起動できます。使用可能なすべての起動スクリプト引数とその目的の完全なリストは、--help 引数を使用するか、サーバーランタイムの引数とスイッチ セクションを参照してください。

ドメイン内のサーバーグループのセカンダリーサーバーを起動する前にドメインコントローラーを起動する必要があります。最初にドメインコントローラーを起動した後、ドメイン内の関連する他のホストコントローラーを起動します。

前提条件

手順

  1. 専用のドメインコントローラー用に事前設定された host-primary.xml 設定ファイルを使用してドメインコントローラーを起動します。

    $ EAP_HOME/bin/domain.sh --host-config=host-primary.xml
    Copy to Clipboard Toggle word wrap
  2. セカンダリーホストコントローラー用に事前設定された host-secondary.xml 設定ファイルを使用してホストコントローラーを起動します。

    $ EAP_HOME/bin/domain.sh  --host-config=host-secondary.xml
    Copy to Clipboard Toggle word wrap

ドメインの設定に応じて、ドメインコントローラーへ接続し、ドメインコントローラーとの競合を回避するために設定を追加する必要があります。また、以下のドメイン設定例を参照してください。

7.7.2. ドメインコントローラーの設定

ドメイン内のホストをドメインコントローラーとして設定する必要があります。

重要

RPM インストール方法を使用して JBoss EAP をインストールした場合、同じマシンに複数のドメインやホストコントローラーを設定できません。

手順

  1. <domain-controller> 宣言に <local/> 要素を追加して、ホストをドメインコントローラーとして設定します。<domain-controller> 要素には他の内容を含めないでください。

    <domain-controller>
      <local/>
    </domain-controller>
    Copy to Clipboard Toggle word wrap
  2. ドメイン内の他のホストからアクセス可能にする必要がある管理インターフェイスを公開します。HTTP インターフェイスは標準の管理インターフェイスです。

    <management-interfaces>
      <http-interface http-authentication-factory="management-http-authentication">
        <http-upgrade enabled="true" sasl-authentication-factory="management-sasl-authentication"/>
        <socket interface="management" port="${jboss.management.http.port:9990}"/>
      </http-interface>
    </management-interfaces>
    Copy to Clipboard Toggle word wrap

最小のドメインコントローラー設定ファイルのサンプル EAP_HOME/domain/configuration/host-primary.xml には、これらの設定が含まれています。

7.7.3. ホストコントローラーの設定

ホストコントローラー自体をドメインに登録するようにホストコントローラーを設定する必要があります。

重要

RPM インストール方法を使用して JBoss EAP をインストールした場合、同じマシンに複数のドメインやホストコントローラーを設定できません。

手順

  • 設定の <domain-controller> 要素を使用して、ドメインコントローラーへの接続を設定します。

    <domain-controller>
      <remote>
        <discovery-options>
          <static-discovery name="primary" protocol="${jboss.domain.primary.protocol:remote+http}" host="${jboss.domain.primary.address}" port="${jboss.domain.primary.port:9990}"/>
          </discovery-options>
      </remote>
    </domain-controller>
    Copy to Clipboard Toggle word wrap

最小のホストコントローラー設定ファイルのサンプル EAP_HOME/domain/configuration/host-secondary.xml には、ドメインコントローラーに接続する設定が含まれています。この設定は、ホストコントローラーの起動時に jboss.domain.primary.address プロパティーを指定するものと想定しています。

$ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml -Djboss.domain.primary.address=<ip_address>
Copy to Clipboard Toggle word wrap

ドメインの設定によっては、認証を提供して、ホストコントローラーがドメインコントローラーによって認証されるようにする必要がある場合があります。管理ユーザーと秘密の値を生成し、その値でホストコントローラー設定を更新する方法の詳細は、2 台のマシンでマネージドドメインを設定する を参照してください。

7.7.4. マネージドドメインのホスト名の設定

マネージドドメインで実行されている各ホストには一意な名前を付ける必要があります。管理を容易にし、複数のホストで同じホスト設定ファイルを使用できるようにするために、以下の優先順位を用いてホスト名が決定されます。

  • 設定されている場合、host.xml 設定ファイルのホスト要素名属性。
  • jboss.host.name システムプロパティーの値。
  • jboss.qualified.host.name システムプロパティーの最初のピリオド (.) より前の値。最後のピリオド (.) がない場合は値全体。
  • POSIX ベースのオペレーティングシステムでは、HOSTNAME 環境変数のピリオド (.) より前の値。Microsoft Windows では、COMPUTERNAME 環境変数のピリオド (.) より前の値。最後のピリオドがない場合は、値全体。

関連する host.xml 設定ファイルの上部にある host 要素に設定されたホストコントローラーの名前。例は次のとおりです。

<host xmlns="urn:jboss:domain:default:20.0" name="host1">
Copy to Clipboard Toggle word wrap

7.7.5. マネージドドメインのホスト名の更新

以下の手順に従って、管理 CLI を使用してホスト名を更新します。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  1. 管理 CLI を起動し、ドメインコントローラーに接続します。

    $ EAP_HOME/bin/jboss-cli.sh --connect --controller=<domain_controller_ip_address>
    Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを実行して新しいホスト名を設定します。

    /host=<existing_host_name>:write-attribute(name=name,value=<new_host_name>)
    Copy to Clipboard Toggle word wrap

    これにより、host-secondary.xml ファイル内のホスト名属性が次のように変更されます。

    <host name="<new_host_name>" xmlns="urn:jboss:domain:default:20.0">
    Copy to Clipboard Toggle word wrap
  3. 変更を反映するためにホストコントローラーをリロードします。

    reload --host=<existing_host_name>
    Copy to Clipboard Toggle word wrap

ホストコントローラーの名前が設定ファイルに設定されていない場合は、起動時にホスト名を渡すこともできます。

$ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml  -Djboss.host.name=<host_name>
Copy to Clipboard Toggle word wrap

7.8. サーバーグループの設定

サーバーグループの設定は、管理 CLI を使用するか、管理コンソールの Runtime タブから行います。

以下はサーバーグループ定義の例になります。

<server-group name="main-server-group" profile="full">
  <jvm name="default">
    <heap size="64m" max-size="512m"/>
  </jvm>
  <socket-binding-group ref="full-sockets"/>
  <deployments>
    <deployment name="test-application.war" runtime-name="test-application.war"/>
    <deployment name="helloworld.war" runtime-name="helloworld.war" enabled="false"/>
  </deployments>
</server-group>
Copy to Clipboard Toggle word wrap
サーバーグループの CLI コマンド

サーバーグループの追加

/server-group=<server_group_name>:add(profile=<profile_name>,socket-binding-group=<socket_binding_group_name>)
Copy to Clipboard Toggle word wrap

サーバーグループの更新

/server-group=<server_group_name>:write-attribute(name=<attribute_name>,value=<value>)
Copy to Clipboard Toggle word wrap

サーバーグループの削除

/server-group=<server_group_name>:remove
Copy to Clipboard Toggle word wrap

7.9. マネージドドメインのサーバー設定

サーバーの設定は、管理 CLI を使用するか、管理コンソールの Runtime タブから行います。

デフォルトの host.xml 設定ファイルは 3 つのサーバーを定義します。

<servers>
  <server name="server-one" group="main-server-group">                       
1

  </server>
  <server name="server-two" group="main-server-group" auto-start="true">     
2

    <socket-bindings port-offset="150"/>
  </server>
  <server name="server-three" group="other-server-group" auto-start="false"> 
3

    <socket-bindings port-offset="250"/>
  </server>
</servers>
Copy to Clipboard Toggle word wrap
1
server-one という名前のサーバーインスタンスは main-server-group に関連付けられ、そのサーバーグループによって指定されるサブシステム設定とソケットバインディングを継承します。
2
server-two という名前のサーバーインスタンスも main-server-group に関連付けられていますが、server-one によって使用されるポートの値と競合しないようにソケットバインディングの port-offset の値も定義します。
3
server-three という名前のサーバーインスタンスは other-server-group に関連付けられ、そのグループの設定を使用します。また、port-offset の値も定義し、ホストコントローラーの起動時にこのサーバーが起動しないように auto-startfalse に設定します。
サーバー設定の CLI コマンド

サーバーの追加

/host=<host_name>/server-config=<server_name>:add(group=<server_group_name>)
Copy to Clipboard Toggle word wrap

サーバーの更新

/host=<host_name>/server-config=<server_name>:write-attribute(name=<attribute_name>,value=<value>)
Copy to Clipboard Toggle word wrap

サーバーの削除

/host=<host_name>/server-config=<server_name>:remove
Copy to Clipboard Toggle word wrap

7.10. マネージドドメインのサーバー操作

管理コンソールから起動、停止、リロードなどの操作をサーバーで実行するには、Runtime タブに移動して適切なホストまたはサーバーグループを選択します。

サーバーの起動

特定のホストで 1 台のサーバーを起動できます。

/host=<host_name>/server=<server_name>:start
Copy to Clipboard Toggle word wrap

指定のサーバーグループのサーバーをすべて起動できます。

/server-group=<server_group_name>:start-servers
Copy to Clipboard Toggle word wrap
サーバーの停止

特定のホストで 1 台のサーバーを停止できます。

/host=<host_name>/server=<server_name>:stop
Copy to Clipboard Toggle word wrap

指定のサーバーグループのサーバーをすべて停止できます。

/server-group=<server_group_name>:stop-servers
Copy to Clipboard Toggle word wrap
サーバーのリロード

特定のホストで 1 台のサーバーをリロードできます。

/host=<host_name>/server=<server_name>:reload
Copy to Clipboard Toggle word wrap

指定のサーバーグループのサーバーをすべてリロードできます。

/server-group=<server_group_name>:reload-servers
Copy to Clipboard Toggle word wrap
サーバーの Kill

指定のサーバーグループのすべてのサーバープロセスを kill することができます。

/server-group=<server_group_name>:kill-servers
Copy to Clipboard Toggle word wrap

7.11. ドメインコントローラーの検出とフェイルオーバーの設定

マネージドドメインの設定時、ドメインコントローラーに接続するために必要な情報を使用して各ホストコントローラーを設定する必要があります。JBoss EAP では、ドメインコントローラーを検索する複数のオプションを使用して各ホストコントローラーを設定できます。ホストコントローラーは、適切なオプションが見つかるまでオプションのリストを繰り返し処理します。

プライマリードメインコントローラーに問題がある場合は、バックアップホストコントローラーをドメインコントローラーに昇格できます。これにより、昇格後にホストコントローラーを新しいドメインコントローラーへ自動的にフェイルオーバーできます。詳細は、ホストコントローラーをドメインコントローラーとして動作するように昇格する を参照してください。

7.11.1. ドメイン検出オプション

以下は、ドメインコントローラー検索の複数のオプションを持つホストコントローラーを設定する方法の例になります。

例: 複数のドメインコントローラーオプションを持つホストコントローラー

<domain-controller>
  <remote>
    <discovery-options>
      <static-discovery name="primary" protocol="${jboss.domain.primary.protocol:remote}" host="172.16.81.100" port="${jboss.domain.primary.port:9990}"/>
      <static-discovery name="backup" protocol="${jboss.domain.primary.protocol:remote}" host="172.16.81.101" port="${jboss.domain.primary.port:9990}"/>
    </discovery-options>
  </remote>
</domain-controller>
Copy to Clipboard Toggle word wrap

静的検出オプションには、以下の必須属性が含まれます。

name
このドメインコントローラー検出オプションの名前。
host
リモートドメインコントローラーのホスト名。
port
リモートドメインコントローラーのポート。

上記の例では、最初の検出オプションが指定されることが予想されます。2 つ目のオプションはフフェイルオーバーの状況で使用される可能性があります。

7.11.2. キャッシュされたドメイン設定を使用するホストコントローラー

--cached-dc オプションを使用すると、ドメインコントローラーへ接続していなくてもホストコントローラーを起動できますが、ホストコントローラーは前もってドメインコントローラーからドメイン設定をローカルでキャッシュする必要があります。--cached-dc オプションを使用してホストコントローラーを起動すると、ドメインコントローラーからホストコントローラーのドメイン設定がキャッシュされます。

$ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml --cached-dc
Copy to Clipboard Toggle word wrap

これにより、このホストコントローラーがドメインコントローラーに接続せずに現在のサーバーを一時的に管理するために必要な情報が含まれる EAP_HOME/domain/configuration/ ディレクトリーに domain.cached-remote.xml ファイルが作成されます。

注記

デフォルトでは、--cached-dc オプションを使用すると、このホストコントローラーによって使用される設定のみがキャッシュされます。ドメイン設定全体をキャッシュして、ホストコントローラーがドメインコントローラーとして動作できるようにする方法は、ホストコントローラーをドメインコントローラーとして動作するように昇格する を参照してください。

--cached-dc を使用してこのホストコントローラーを起動したときにドメインコントローラーを利用できない場合、ホストコントローラーは domain.cached-remote.xml ファイルに保存されたキャッシュされた設定の使用を開始します。このファイルが存在しないとホストコントローラーは起動しないことに注意してください。

この状態の間、ホストコントローラーはドメイン設定を編集できませんが、サーバーを開始したり、デプロイメントを管理することはできます。

ホストコントローラーがキャッシュされた設定を使用して起動されると、ホストコントローラーは継続してドメインコントローラーへの再接続を試みます。ドメインコントローラーが使用できるようになると、ホストコントローラーは自動的にドメインコントローラーに再接続し、ドメイン設定を同期化します。変更された設定によっては、変更の反映にホストコントローラーのリロードが必要になることがあります。この場合、警告がホストコントローラーのログに記録されます。

7.11.3. ホストコントローラーをドメインコントローラーとして動作するように昇格する

主要のドメインコントローラーに問題が発生した場合に、ホストコントローラーがドメインコントローラーとして動作するよう昇格できます。ホストコントローラーを昇格する前に、ドメインコントローラーからドメイン設定をローカルでキャッシュする必要があります。

手順

  1. ドメインコントローラーとして使用したいホストコントローラーに --backup オプションを使用します。

    $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml --backup
    Copy to Clipboard Toggle word wrap

    これにより、ドメイン設定全体のコピーが含まれる EAP_HOME/domain/configuration/ ディレクトリーに domain.cached-remote.xml ファイルが作成されます。この設定は、ホストコントローラーがドメインコントローラーとして動作するよう再設定された場合に使用されます。

    注記

    ignore-unused-configuration 属性は、特定のホストがキャッシュする設定の範囲を判断するために使用されます。true を指定すると、このホストコントローラーに関係する設定のみがキャッシュされ、ドメインコントローラーとして引き継ぐことはできません。false を指定すると、ドメイン設定全体がキャッシュされます。

    The --backup 引数はデフォルトでこの属性の値を false とし、ドメイン全体をキャッシュします。しかし、この属性を host.xml ファイルで設定した場合は、その値が使用されます。

    また、--cached-dc オプションのみを使用して、ドメイン設定のコピーを作成できますが、host.xmlignore-unused-configuration の値を false と設定し、ドメイン全体をキャッシュする必要があります。以下に例を示します。

    <domain-controller>
      <remote username="$local" ignore-unused-configuration="false">
        <discovery-options>
          ...
        </discovery-options>
      </remote>
    </domain-controller>
    Copy to Clipboard Toggle word wrap
  2. ホストコントローラーをドメインコントローラーに昇格します。

    1. 元のドメインコントローラーが停止した状態であることを確認します。
    2. 管理 CLI を使用して、新しいドメインコントローラーとなるホストコントローラーへ接続します。
    3. 以下のコマンドを実行してホストコントローラーを設定し、新しいドメインコントローラーとして動作するようにします。

      /host=backup:write-attribute(name=domain-controller.local, value={})
      Copy to Clipboard Toggle word wrap
    4. 以下のコマンドを実行し、ホストコントローラーをリロードします。

      reload --host=<host_name>
      Copy to Clipboard Toggle word wrap

    このホストコントローラーがドメインコントローラーとして動作するようになります。

7.12. 1 台のマシンでマネージドドメインを設定する

jboss.domain.base.dir プロパティーを使用すると 1 台のマシンで複数のホストコントローラーを実行できます。

重要

1 台のマシン上で複数の JBoss EAP ホストコントローラーをシステムサービスとして設定することはできません。

手順

  1. ドメインコントローラーの EAP_HOME/domain ディレクトリーをコピーします。

    $ cp -r EAP_HOME/domain <path_to>/domain1
    Copy to Clipboard Toggle word wrap
  2. ホストコントローラーの EAP_HOME/domain ディレクトリーをコピーします。

    $ cp -r EAP_HOME/domain <path_to>/host1
    Copy to Clipboard Toggle word wrap
  3. <path_to>/domain1 を使用してドメインコントローラーを起動します。

    $ EAP_HOME/bin/domain.sh --host-config=host-primary.xml -Djboss.domain.base.dir=<path_to>/domain1
    Copy to Clipboard Toggle word wrap
  4. <path_to>/host1 を使用してホストコントローラーを起動します。

    $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml -Djboss.domain.base.dir=<path_to>/host1 -Djboss.domain.primary.address=<ip_adress> -Djboss.management.http.port=<port>
    Copy to Clipboard Toggle word wrap
    注記

    ホストコントローラーの起動時に、jboss.domain.primary.address プロパティーを使用してドメインコントローラーのアドレスを指定する必要があります。

    さらに、このホストコントローラーはドメインコントローラーと同じマシンで実行されているため、ドメインコントローラーの管理インターフェイスと競合しないように管理インターフェイスを変更する必要があります。このコマンドは jboss.management.http.port プロパティーを設定します。

このように起動された各インスタンスは、ベースインストールディレクトリー (例: EAP_HOME/modules/) のその他のリソースを共有しますが、jboss.domain.base.dir によって指定されたディレクトリーからドメイン設定を使用します。

7.13. 2 台のマシンでマネージドドメインを設定する

1 台がドメインコントローラーでもう 1 台がホストである 2 台のマシンでマネージドドメインを作成できます。詳細は、マネージドドメインにおけるドメインコントローラーの役割 を参照してください。

  • <IP1> = ドメインコントローラーの IP アドレス (マシン 1)
  • <IP2> = ホストの IP アドレス (マシン 2)
注記

この例の実行には、ファイアウォールの設定が必要になることがあります。

手順

  1. マシン 1 での作業

    1. ホストがドメインコントローラーによって認証されるよう、管理ユーザーを追加します。

      add-user.sh スクリプトを使用してホストコントローラー HOST_NAME の管理ユーザーを追加します。

    2. ドメインコントローラーを起動します。

      専用のドメインコントローラー用に事前設定された host-primary.xml 設定ファイルを指定します。さらに、jboss.bind.address.management プロパティーを設定し、ドメインコントローラーが他のマシンにも表示されるようにします。

      $ EAP_HOME/bin/domain.sh --host-config=host-primary.xml -Djboss.bind.address.management=<IP1>
      Copy to Clipboard Toggle word wrap
  2. マシン 2 での作業

    1. ホスト設定を次のように更新します。

      1. elytron サブシステムに次の設定を追加します。

        <subsystem xmlns="urn:wildfly:elytron:18.0"...>
          <authentication-client>
            <authentication-configuration name="secondary-hc-auth" authentication-name="MGMT_USER_NAME">
              <credential-reference clear-text="MGMT_USER_PASSWORD"/>
            </authentication-configuration>
            <authentication-context name="secondary-hc-auth-context">
              <match-rule authentication-configuration="secondary-hc-auth"/>
            </authentication-context>
          </authentication-client>
        ...
        </subsystem>
        Copy to Clipboard Toggle word wrap
        重要

        この例では、クリアテキストのパスワード "MGMT_USER_PASSWORD" を使用します。実稼働環境では、セキュリティーを強化するために、クリアテキストのパスワードを使用する代わりに、認証情報ストアへの参照を使用するか、暗号化された式を使用してください。詳細は、JBoss EAP での認証情報のセキュアな保管 を参照してください。

      2. ドメインコントローラーに認証コンテキストを追加します。

        <domain-controller>
          <remote authentication-context="secondary-hc-auth-context">
          ...
        </domain-controller>
        Copy to Clipboard Toggle word wrap
    2. ホストコントローラーを起動します。

      セカンダリーホストコントローラー用に事前設定さた host-secondary.xml 設定ファイルを指定します。さらに、jboss.domain.primary.address プロパティーを設定してドメインコントローラーに接続し、jboss.bind.address プロパティーを設定してホストコントローラーバインドアドレスを設定します。

      $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml  -Djboss.domain.primary.address=<IP1>  -Djboss.bind.address=<IP2>
      Copy to Clipboard Toggle word wrap

起動時に --controller パラメーターを使用してドメインコントローラーアドレスを指定し、管理 CLI からドメインを管理できるようになります。

$ EAP_HOME/bin/jboss-cli.sh --connect --controller=<IP1>
Copy to Clipboard Toggle word wrap

また、http://<IP1>:9990 で管理コンソールからドメインを管理することもできます。

7.14. JBoss EAP 7.4 インスタンスを管理するための JBoss EAP 8.0 ドメインコントローラーの設定

ホストとサーバーが JBoss EAP 7.4 以降を実行している場合、JBoss EAP 8.0 ドメインコントローラーは、JBoss EAP 7.4 を実行しているホストとサーバーを管理できます。

7.14.1. JBoss EAP 7.4 の設定を JBoss EAP 8.0 ドメインコントローラーに追加する

ドメインコントローラーが JBoss EAP 7.4 サーバーを管理できるようにするには、JBoss EAP 8.0 のドメイン設定に JBoss EAP 7.4 の設定詳細を指定する必要があります。これを行うには、JBoss EAP 7.4 プロファイル、ソケットバインディンググループ、およびサーバーグループを JBoss EAP 8.0 の domain.xml 設定ファイルにコピーします。

JBoss EAP 7.4 設定内の既存の名前と競合する場合は、リソースの名前を変更する必要があります。さらに、正しく動作するように、追加の 調整 を行う必要もあります。

次の手順では、JBoss EAP 7.4 の default プロファイル、standard-sockets ソケットバインディンググループ、および main-server-group サーバーグループを使用します。

手順

  1. JBoss EAP 8.0 の domain.xml 設定ファイルを編集します。このファイルをバックアップしてから編集することが推奨されます。
  2. 該当する JBoss EAP 7.4 プロファイルを JBoss EAP 8.0 の domain.xml ファイルにコピーします。

    この手順では、JBoss EAP 7.4 の default プロファイルをコピーし、eap74-default に名前を変更したことを前提としています。

    JBoss EAP 7.4 の domain.xml

    <profiles>
      ...
      <profile name="eap74-default">
        ...
      </profile>
    </profiles>
    Copy to Clipboard Toggle word wrap

  3. このプロファイルによって使用される必要なエクステンションを追加します。

    JBoss EAP 7.4 のプロファイルが JBoss EAP 8.0 には存在しないサブシステムを使用する場合は、JBoss EAP ドメイン設定に適切なエクステンションを追加する必要があります。

    JBoss EAP 8.0 の domain.xml

    <extensions>
      ...
      <extension module="org.jboss.as.jsr77"/>
      <extension module="org.jboss.as.security"/>
    <extensions>
    Copy to Clipboard Toggle word wrap

  4. 該当する JBoss EAP 7.4 のソケットバインディンググループを JBoss EAP 8.0 の domain.xml ファイルにコピーします。

    この手順では、JBoss EAP 7.4 の standard-sockets ソケットバインディンググループをコピーし、eap74-standard-sockets に名前を変更したことを前提としています。

    JBoss EAP 8.0 の domain.xml

    <socket-binding-groups>
      ...
      <socket-binding-group name="eap74-standard-sockets" default-interface="public">
        ...
      </socket-binding-group>
    </socket-binding-groups>
    Copy to Clipboard Toggle word wrap

  5. 該当する JBoss EAP 7.4 のサーバーグループを JBoss EAP 8.0 の domain.xml ファイルにコピーします。

    この手順では、JBoss EAP 7.4 main-server-group サーバーグループをコピーし、eap74-main-server-group に名前を変更したことを前提としています。また、このサーバーグループを、JBoss EAP 7.4 のプロファイル eap74-default と JBoss EAP 7.4 のソケットバインディンググループ eap74-standard-sockets を使用するように更新する必要があります。

    JBoss EAP 8.0 の domain.xml

    <server-groups>
      ...
      <server-group name="eap74-main-server-group" profile="eap7.4-default">
        ...
        <socket-binding-group ref="eap7.4-standard-sockets"/>
      </server-group>
    </server-groups>
    Copy to Clipboard Toggle word wrap

7.14.2. JBoss EAP 7.4 バージョンプロファイルの動作の更新

JBoss EAP のバージョンや必要な動作に応じて、JBoss EAP 7.4 インスタンスによって使用されるプロファイルを追加更新する必要があります。既存の JBoss EAP 7.4 インスタンスが使用するサブシステムや設定に応じて、追加の変更が必要になる場合があります。次の手順では、JBoss EAP 7.4 プロファイルが eap74-default であることを前提としています。

手順

  1. JBoss EAP 8.0 ドメインコントローラーを起動し、管理 CLI を起動して次の更新を実行します。
  2. CDI 1.0 の動作を設定します。

    これは、JBoss EAP 7.4 サーバーで、JBoss EAP 8.0 で使用される新しい CDI バージョンの動作ではなく、CDI 1.0 の動作が必要な場合にのみ必要です。CDI 1.0 の動作が必要な場合は、weld サブシステムに次の更新を加えます。

    JBoss EAP 8.0 ドメインコントローラー CLI

    /profile=eap74-default/subsystem=weld:write-attribute(name=require-bean-descriptor,value=true)
    
    /profile=eap74-default/subsystem=weld:write-attribute(name=non-portable-mode,value=true)
    Copy to Clipboard Toggle word wrap

7.14.3. JBoss EAP 7.4 サーバーのサーバーグループの設定

サーバーグループの名前を変更した場合は、JBoss EAP 7.4 のホスト設定を更新し、JBoss EAP 8.0 の設定に指定された新しいサーバーグループを使用する必要があります。この例では、JBoss EAP 8.0 の domain.xml 設定ファイルに指定された eap74-main-server-group サーバーグループを使用します。

手順

  • ホスト設定を更新します。

    JBoss EAP 7.4 host-secondary.xml

    <servers>
        <server name="server-one" group="eap74-main-server-group"/>
        <server name="server-two" group="eap74-main-server-group">
            <socket-bindings port-offset="150"/>
        </server>
    </servers>
    Copy to Clipboard Toggle word wrap

注記

ホストは、実行している JBoss EAP よりも新しいバージョンで導入された機能や設定を使用できません。

7.14.4. JBoss EAP 7.4 インスタンスが JBoss EAP 8.0 サーバーの更新を取得しないようにする

マネージドドメインのドメインコントローラーは、設定の更新をホストコントローラーに転送します。host-exclude 設定を使用して、特定のバージョンが認識できないようにするリソースを指定する必要があります。ご使用の JBoss EAP 7.4 バージョンに合わせて事前設定された適切な host-exclude オプション (EAP74) を選択してください。

host-exclude 設定の active-server-groups 属性は、特定のバージョンによって使用されるサーバーグループのリストを指定します。指定のバージョンのホストは、指定されたサーバーグループとそれらに関連するプロファイル、ソケットバインディンググループ、およびデプロイメントリソースを利用できますが、それ以外は認識しません。

次の例では、バージョンが JBoss EAP 7.4 であると想定し、JBoss EAP 7.4 のサーバーグループ eap74-main-server-group をアクティブなサーバーグループとして追加します。

JBoss EAP 8.0 ドメインコントローラー CLI

/host-exclude=EAP74:write-attribute(name=active-server-groups,value=[eap74-main-server-group])
Copy to Clipboard Toggle word wrap

必要な場合は、active-socket-binding-groups 属性を使用して、サーバーによって使用される追加のソケットバインディンググループを指定します。これは、active-server-groups に指定されたサーバーグループと関連していないソケットバインディンググループのみに必要です。

7.15. JBoss EAP プロファイルの管理

7.15.1. プロファイルについて

JBoss EAP は、プロファイルを使用してサーバーが使用できるサブシステムを整理します。プロファイルは、使用可能なサブシステムの集まりと、各サブシステムの固有の設定で構成されます。プロファイルのサブシステムの数が多いと、サーバーの機能が多くなります。プロファイルのサブシステムが集中的で数が少ないと、機能が少なくなりますが、フットプリントも少なくなります。

JBoss EAP にはほとんどのユースケースに対応する事前定義されたプロファイルが 5 つあります。

default
loggingsecuritydatasourcesinfinispanwebserviceseeejb3transactions など、一般的に使用されるサブシステムが含まれます。
ha
default プロファイルで提供されるサブシステムに加えて、高可用性のための jgroups および modcluster サブシステムが含まれます。
full
default プロファイルで提供されるサブシステムに加えて、messaging-activemq および iiop-openjdk サブシステムが含まれます。
full-ha
full プロファイルで提供されるサブシステムに加えて、高可用性のための jgroups および modcluster サブシステムが含まれます。
load-balancer
ビルトインの mod_cluster フロントエンドロードバランサーを使用して他の JBoss EAP インスタンスの負荷を分散するために必要な最低限のサブシステムが含まれます。

7.15.2. プロファイルのクローン

JBoss EAP では、既存のプロファイルをクローンしてマネージドドメインで新しいプロファイルを作成することができます。クローンした既存プロファイルの設定およびサブシステムのコピーが作成されます。

手順

  • クローンするプロファイルに対して clone 操作を使用して、プロファイルをクローンします。

    /profile=full-ha:clone(to_profile=<cloned_profile>)
    Copy to Clipboard Toggle word wrap

管理コンソールからプロファイルをクローンするには、クローンするプロファイルを選択し、Clone をクリックします。

7.15.3. マネージドドメイン内の階層型プロファイル

マネージドドメインでは、プロファイルの階層を作成できます。これにより、他のプロファイルが継承できる共通のエクステンションが含まれるベースプロファイルを作成できます。

マネージドドメインは domain.xml の複数のプロファイルを定義します。複数のプロファイルが特定のサブシステムで同じ設定を使用する場合、複数のプロファイルで設定せずに、1 つのプロファイルで設定を行うことができます。親プロファイルの値はオーバーライドできません。

さらに、各プロファイルは他に依存しなくてもすむ必要があります。要素やサブシステムが参照される場合、参照されるプロファイルに定義する必要があります。

管理 CLI を使用して list-add 操作を実行し、含めるプロファイルを指定すると、プロファイルに階層の別のプロファイルを含めることができます。

/profile=new-profile:list-add(name=includes, value=<profile_name>)
Copy to Clipboard Toggle word wrap

第8章 JVM の設定

スタンドアロンの JBoss EAP サーバーまたはマネージドドメインの JBoss EAP サーバーの Java 仮想マシン (JVM) を設定できます。

スタンドアロン JBoss EAP サーバーインスタンスでは、起動時にサーバー起動プロセスが JVM 設定を JBoss EAP サーバーに渡します。これは、JBoss EAP を起動する前にコマンドラインから宣言できます。また、管理コンソールの Configuration にある System Properties 画面を使用して宣言することもできます。

マネージドドメインでは、JVM の設定は host.xml および domain.xml 設定ファイルで宣言され、ホスト、サーバーグループ、またはサーバーレベルで設定できます。

注記

スタンドアロンサーバーまたはマネージドドメインホストコントローラーの起動の初期フェーズ中に、JVM 自体または JBoss EAP モジュール (ロギングマネージャーなど) によってシステムプロパティーを読み取る必要がある場合は、JAVA_OPTS でシステムプロパティーを設定してください。

8.1. スタンドアロンサーバーの JVM 設定

サーバーを起動する前に JAVA_OPTS 環境変数を設定することで、実行時にスタンドアロン JBoss EAP サーバーインスタンスの Java 仮想マシン (JVM) 設定を定義できます。または、standalone.conf または standalone.bat 設定ファイルに JVM 設定を追加したり、システムプロパティーを設定したりすることもできます。システムプロパティーが複数の方法で設定されている場合、JBoss EAP 設定ファイル standalone*.xml の値が他の値をオーバーライドします。

手順

  • JAVA_OPTS 環境変数の設定:

    Linux

    $ export JAVA_OPTS="-Xmx1024M"
    Copy to Clipboard Toggle word wrap

    Microsoft Windows

    set JAVA_OPTS="Xmx1024M"
    Copy to Clipboard Toggle word wrap

  • この代わりに、JVM に渡すオプションの例が含まれる EAP_HOME/bin フォルダーの standalone.conf ファイル (Windows Server の場合は standalone.conf.bat) に JVM 設定を追加することもできます。
  • JAVA_OPTS 環境変数を設定する以外に、次に挙げる代替方法のいずれかを使用してシステムプロパティーを設定できます。

    • 以下のコマンドを実行します。

      $ EAP_HOME/bin/standalone.sh -Dmyproperty=value
      Copy to Clipboard Toggle word wrap
    • JBoss EAP 設定ファイル standalone*.xml を編集します。
警告

システムプロパティーが複数の方法で設定されている場合、JBoss EAP 設定ファイル standalone*.xml の値が他の値をオーバーライドます。これにより、JBoss EAP の起動の問題が発生する可能性があります。たとえば、JAVA_OPTS 環境変数と JBoss EAP 設定ファイルでシステム設定を定義した場合、JBoss EAP 設定の値が JAVA_OPTS の値をオーバーライドします。

8.2. マネージドドメインの JVM 設定

JBoss EAP マネージドドメインでは、複数のレベルで JVM の設定を定義できます。特定ホストのカスタム JVM 設定を定義し、それらの設定をサーバーグループまたは個別のサーバーインスタンスに適用できます。

デフォルトでは、サーバーグループおよび各サーバーは親から JVM 設定を継承しますが、各レベルで JVM 設定をオーバーライドすることもできます。

注記

domain.conf の JVM 設定 (Windows Server の場合は domain.conf.bat) は JBoss EAP ホストコントローラーの Java プロセスに適用されます。ホストコントローラーによって制御される個別の JBoss EAP サーバーインスタンスには適用されません。

8.2.1. ホストコントローラーの JVM 設定の定義

ホストコントローラーの Java 仮想マシン (JVM) 設定を定義し、その設定をサーバーグループまたは個々のサーバーに適用できます。JBoss EAP には default JVM 設定が付属していますが、次の手順では、いくつかのカスタム JVM 設定とオプションを使用して、production_jvm という名前の新しい JVM 設定を作成する方法を示します。これらの設定は、host.xml<jvm> タグ内に保存されます。

前提条件

  • JBoss EAP がマネージドドメインとして実行されている。

手順

  • 管理 CLI を使用して JVM 設定を定義します。

    構文

    /host=<HOST_NAME>/jvm=<SETTING_NAME>:add(heap-size=<HEAP_SIZE>, max-heap-size=<MAX_HEAP_SIZE>, max-permgen-size=<MAX_PERMANENT_GENERATION_SIZED>, stack-size=<STACK_SIZE>, jvm-options=["<JVM_OPTIONS>"])
    Copy to Clipboard Toggle word wrap

    /host=exampleHost1/jvm=production_jvm:add(heap-size=2048m, max-heap-size=2048m, max-permgen-size=512m, stack-size=1024k, jvm-options=["-XX:-UseParallelGC"])
    Copy to Clipboard Toggle word wrap

    使用可能なすべてのオプションの説明は、マネージドドメインの JVM 設定の属性 を参照してください。

  • 管理コンソールを使用して JVM 設定を定義します。

    1. 管理コンソールで RuntimeHosts に移動します。
    2. ホストを選択し、View をクリックします。
    3. JVM タブを選択し、設定を定義します。

8.2.2. サーバーグループへの JVM 設定の適用

サーバーグループの作成時に、グループのすべてのサーバーが使用する JVM 設定を指定できます。サーバーグループの設定は domain.xml に保存されます。

前提条件

手順

  • 管理 CLI を使用して、サーバーグループに JVM 設定を適用します。

    production_jvm JVM 設定を使用するサーバーグループ名 exampleGroupA を作成します。

    /server-group=exampleGroupA:add(profile=default,socket-binding-group=standard-sockets)
    /server-group=exampleGroupA/jvm=production_jvm:add
    Copy to Clipboard Toggle word wrap

    サーバーグループレベルで特定の JVM 設定をオーバーライドすることもできます。たとえば、別のヒープサイズを設定するには、以下のコマンドを使用できます。

    /server-group=exampleGroupA/jvm=production_jvm:write-attribute(name=heap-size,value="1024m")
    Copy to Clipboard Toggle word wrap

    上記コマンドの実行後、サーバーグループ groupAproduction_jvm から JVM 設定を継承しますが、ヒープサイズの値は 1024m にオーバーライドされます。

  • 管理コンソールを使用して、サーバーグループに JVM 設定を適用します。

    1. RuntimeServer Groups に移動します。
    2. サーバーグループを選択し、View をクリックします。
    3. JVM タブを選択し、設定を適用します。

8.2.3. サーバーグループ内の個々のサーバーに JVM 設定を適用する

デフォルトでは、個別の JBoss EAP サーバーインスタンスは属するサーバーグループの JVM 設定を継承します。しかし、継承した設定をホストコントローラーからの別の JVM 設定定義でオーバーライドしたり、特定の JVM 設定をオーバーライドすることもできます。各サーバーのこれらの設定は host.xml に保存されます。

前提条件

手順

  • 管理 CLI を使用して個々のサーバーに JVM 設定を適用します。

    サーバーグループへの JVM 設定の適用 手順の JVM 定義をオーバーライドし、server-one の JVM 設定を default JVM 定義に設定します。

    /host=exampleHost1/server-config=server-one/jvm=default:add
    Copy to Clipboard Toggle word wrap

    また、サーバーグループと同様に、サーバーレベルで特定の JVM 設定をオーバーライドすることもできます。たとえば、別のヒープサイズを設定するには、以下のコマンドを使用できます。

    /host=exampleHost1/server-config=server-one/jvm=default:write-attribute(name=heap-size,value="1024m")
    Copy to Clipboard Toggle word wrap
  • 管理コンソールを使用して、個々のサーバーに JVM 設定を適用します。

    1. RuntimeHosts に移動します。
    2. ホストを選択し、サーバーの View をクリックします。
    3. JVM タブを選択し、設定を適用します。

8.3. 管理コンソールで JVM リソースのステータスを表示する

ヒープおよびスレッドの使用状況など、スタンドアロンまたはマネージドドメインサーバーの JVM リソースの状態は管理コンソールから表示できます。統計はリアルタイムでは表示されませんが、Refresh をクリックすると JVM リソースの最新の概要を表示できます。

前提条件

  • JBoss EAP が実行中である。

手順

  • スタンドアロンの JBoss EAP サーバーの JVM ステータスを表示します。

    • Runtime タブに移動し、サーバーを選択して、Status を選択します。
  • マネージドドメインの JBoss EAP サーバーの JVM ステータスを表示します。

    • RuntimeHosts に移動し、ホストとサーバーを選択して、Status を選択します。

次のヒープ使用情報が表示されます。

Max
メモリー管理に使用できるメモリーの最大量。
Used
使用されたメモリーの量。
Committed
Java 仮想マシンが使用するためにコミットされたメモリーの量。

JVM のアップタイムやスレッドの使用状況などの他の情報も表示されます。

JVM パフォーマンスの最適化の詳細は、JBoss EAP のパフォーマンスチューニング ガイドの JVM のチューニング を参照してください。

第9章 Mail サブシステム

この章では、メール機能を JBoss EAP アプリケーションに統合するために不可欠な mail サブシステムに焦点を当てます。このセクションでは、メールサーバーを設定し、組織の特定のニーズに合わせてトランスポートプロトコルをカスタマイズし、パスワード管理用の認証情報ストアを使用してセキュリティーを強化するための詳細な手順を説明します。

前提条件

  • JBoss EAP 8.0 がインストールされている。

9.1. メールサブシステムの設定

mail サブシステムを使用すると、JBoss EAP でメールセッションを設定し、JNDI を使用してメールセッションをアプリケーションに注入できます。また、このサブシステムは、@MailSessionDefinition@MailSessionDefinitions などの Jakarta EE アノテーションの使用をサポートし、設定プロセスを効率化します。

前提条件

  • JBoss EAP がインストールされ、実行されている。
  • SMTP サーバーへのネットワークアクセスがある。

手順

  1. 以下の CLI コマンドを使用して SMTP サーバーと送信ソケットバインディングを設定します。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp:add(host=localhost, port=25)
    Copy to Clipboard Toggle word wrap
    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    Copy to Clipboard Toggle word wrap
    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp, username=user, password=pass, tls=true)
    Copy to Clipboard Toggle word wrap
  2. アプリケーション内で設定されたメールセッションを呼び出します。

    @Resource(lookup="java:jboss/mail/MySession")
    private Session session;
    Copy to Clipboard Toggle word wrap

9.2. カスタムトランスポートの設定

JBoss EAP で SMTP、POP3、IMAP などの標準メールサーバーを設定する場合、いくつかの属性を定義する必要があります。最も重要なのは outbound-socket-binding-ref 属性です。この属性は、メールセッションを特定のホストとポートにリンクします。ただし、負荷分散のために複数のホストを設定する場合、標準の Jakarta Mail 設定では、複数のホストがサポートされていないため、不十分な場合があります。このような場合は、管理 CLI を通じてカスタムメールトランスポートを設定する必要があります。このカスタムトランスポートでは、より柔軟な設定が可能で、outbound-socket-binding-ref 属性が必要ありません。

前提条件

  • JBoss EAP がインストールされ、実行されている。

手順

  1. 新しいメールセッションを追加し、JNDI 名を指定します。

    /subsystem=mail/mail-session=mySession:add(jndi-name=java:jboss/mail/MySession)
    Copy to Clipboard Toggle word wrap
  2. 送信ソケットバインディングを追加し、ホストとポートを指定します。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-smtp-binding:add(host=localhost, port=25)
    Copy to Clipboard Toggle word wrap
  3. SMTP サーバーを追加し、送信ソケットバインディング、ユーザー名、およびパスワードを指定します。

    /subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, password=pass, tls=true)
    Copy to Clipboard Toggle word wrap
注記

同様の手順で POP3 または IMAP サーバーを設定できます。

POP3 サーバー

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-pop3-binding:add(host=localhost, port=110)
/subsystem=mail/mail-session=mySession/server=pop3:add(outbound-socket-binding-ref=my-pop3-binding, username=user, password=pass)
Copy to Clipboard Toggle word wrap

IMAP サーバー

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=my-imap-binding:add(host=localhost, port=143)
/subsystem=mail/mail-session=mySession/server=imap:add(outbound-socket-binding-ref=my-imap-binding, username=user, password=pass)
Copy to Clipboard Toggle word wrap

カスタムサーバーを使用するには、送信ソケットバインディングを指定せずにカスタムメールサーバーを作成します。カスタムメールサーバーのプロパティー定義でホスト情報を指定できます。以下に例を示します。

/subsystem=mail/mail-session=mySession/custom=myCustomServer:add(username=user,password=pass, properties={"host" => "myhost", "my-property" =>"value"})
Copy to Clipboard Toggle word wrap

カスタムプロトコルを定義する場合、ピリオド (.) が含まれるプロパティー名は完全修飾名と見なされ、直接渡されます。my-property など、他の形式は mail.server-name.my-property という形式に変換されます。

以下の XML は、カスタムサーバーが含まれるメール設定の例になります。

<subsystem xmlns="urn:jboss:domain:mail:4.0">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
        <smtp-server outbound-socket-binding-ref="mail-smtp"/>
   </mail-session>
    <mail-session name="myMail" from="user.name@domain.org" jndi-name="java:/Mail">
        <smtp-server password="password" username="user" tls="true" outbound-socket-binding-ref="mail-smtp"/>
        <pop3-server outbound-socket-binding-ref="mail-pop3"/>
        <imap-server password="password" username="nobody" outbound-socket-binding-ref="mail-imap"/>
    </mail-session>
    <mail-session name="custom" jndi-name="java:jboss/mail/Custom" debug="true">
        <custom-server name="smtp" password="password" username="username">
            <property name="host" value="mail.example.com"/>
        </custom-server>
    </mail-session>
    <mail-session name="custom2" jndi-name="java:jboss/mail/Custom2" debug="true">
        <custom-server name="pop3" outbound-socket-binding-ref="mail-pop3">
            <property name="custom-prop" value="some-custom-prop-value"/>
        </custom-server>
    </mail-session>
</subsystem>
Copy to Clipboard Toggle word wrap

9.3. パスワードに認証情報ストアを使用する

クリアテキストのパスワードを使用するほかに、認証情報ストアを使用して JBoss EAP メールサブシステムのセキュリティーを強化できます。elytron サブシステムを使用すると、認証情報ストアを作成および管理して、パスワードをセキュアに保存してアクセスできます。このような認証情報ストアを設定して使用する方法の詳細な手順は、サーバーセキュリティーの設定方法認証情報ストア セクションを参照してください。

前提条件

  • JBoss EAP がインストールされ、実行されている。

管理 CLI を使用してパスワードに認証情報ストアを使用する:

/subsystem=mail/mail-session=mySession/server=smtp:add(outbound-socket-binding-ref=my-smtp-binding, username=user, credential-reference={store=exampleCS, alias=mail-session-pw}, tls=true)
Copy to Clipboard Toggle word wrap

注記

以下は、クリアテキストパスワードを使用する credential-reference 属性を指定する方法の例になります。

credential-reference={clear-text="MASK-Ewcyuqd/nP9;A1B2C3D4;351"}
Copy to Clipboard Toggle word wrap

管理コンソールを使用してパスワードに認証情報ストアを使用する:

  1. 管理コンソールにアクセスします。詳細は、管理コンソール を参照してください。
  2. ConfigurationSubsystemsMail と選択します。
  3. 適切なメールセッションを選択し、View をクリックします。
  4. Server を選択し、該当するメールセッションサーバーを選択します。Credential Reference タブで認証情報リファレンスを設定でき、Attributes タブでその他の属性を編集できます。

第10章 JBoss EAP を用いたロギング

JBoss EAP は、内部使用とデプロイされたアプリケーションの両方で設定可能なロギング機能を提供します。logging サブシステムは JBoss LogManager を基盤とし、JBoss Logging だけでなくサードパーティーアプリケーションのロギングフレームワークを複数サポートします。

10.1. JBoss EAP のロギングメカニズム

JBoss EAP は、サーバー環境の監視、トラブルシューティング、および管理をサポートするさまざまなロギングメカニズムを提供します。これらのメカニズムを理解すると、JBoss EAP の設定の維持およびデバッグに役立ちます。

10.1.1. JBoss EAP でのサーバーロギング

JBoss EAP では、サーバーロギングは主にすべてのログエントリーが記録される server.log ファイルから管理されます。

このログファイルの場所は操作モードによって異なります。

  • スタンドアロンサーバーの場合: EAP_HOME/standalone/log/server.log
  • マネージドドメインの場合: EAP_HOME/domain/servers/SERVER_NAME/log/server.log

このファイルは一般的にサーバーログとして知られています。

10.1.2. JBoss EAP での起動時のロギング

起動中に JBoss EAP は Java 環境と各サービスの起動に関する情報をログに記録します。このログはトラブルシューティングに役立ち、デフォルトでは サーバーログ に書き込まれます。

起動時のロギングは、JBoss EAP の logging サブシステムが起動するまで logging.properties ファイルで設定されます。

ファイルの場所は操作モードによって異なります。

  • スタンドアロンサーバーの場合: EAP_HOME/standalone/configuration/logging.properties
  • 管理対象ドメイン:ドメインコントローラーと各サーバーの両方に logging.properties ファイルがあります。

    • ドメインコントローラー: EAP_HOME/domain/configuration/logging.properties
    • サーバー: EAP_HOME/domain/servers/SERVER_NAME/data/logging.properties

      警告

      必要な場合を除き、logging.properties ファイルを直接編集しないでください。特定のユースケースがある場合は、変更する前に Red Hat カスタマーポータル を参照してください。

      logging.properties ファイルに手動で変更すると、起動時に上書きされます。

10.1.2.1. 起動時のエラーの表示

JBoss EAP をトラブルシューティングする場合、起動時のエラーを確認することが重要なステップになります。この情報を使用して、エラーを診断し、解決できます。必要に応じて、起動時のエラーのトラブルシューティングについてサポートが必要な場合はサポートケースを作成してください。

以下の方法で、起動時のエラーを表示できます。

  • server.log ファイルでの起動エラーの確認
  • 管理 CLI コマンドでの起動エラーの読み取り

それぞれの方法には、要件に応じて独自の利点があります。

10.1.2.1.1. server.log ファイルでの起動エラーの確認

server.log ファイルを開いて起動中に発生したエラーを確認します。

このメソッドは、エラーメッセージと関連情報を提供し、エラーの原因を理解するのに役立ちます。エラーメッセージがプレーンテキスト形式で表示されます。

前提条件

  • JBoss EAP サーバーのファイルシステムにアクセスできる。
  • 確認のために server.log ファイルにアクセスできます。

手順

  1. ファイルビューアーで server.log ファイルを開きます。
  2. ファイルの最後に移動します。
  3. 最新の起動シーケンスの開始を示す WFLYSRV0049 メッセージ ID を後方検索します。
  4. ログのその位置から ERROR を前方検索します。各検索一致箇所には、エラーの説明が示され、関連するモジュールがリストされます。

    以下は、server.log ログファイルのエラー説明の例です。

    2016-03-16 14:32:01,627 ERROR [org.jboss.msc.service.fail] (MSC service thread 1-7) MSC000001: Failed to start service jboss.undertow.listener.default: org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
            at org.wildfly.extension.undertow.ListenerService.start(ListenerService.java:142)
            at org.jboss.msc.service.ServiceControllerImpl$StartTask.startService(ServiceControllerImpl.java:1948)
            at org.jboss.msc.service.ServiceControllerImpl$StartTask.run(ServiceControllerImpl.java:1881)
            at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
            at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
            at java.lang.Thread.run(Thread.java:745)
    Caused by: java.net.BindException: Address already in use
            ...
    Copy to Clipboard Toggle word wrap
10.1.2.1.2. 管理 CLI コマンドでの起動エラーの読み取り

JBoss EAP のトラブルシューティング時に、read-boot-errors 管理 CLI コマンドを使用して、ブートアップ中に報告されるエラーを表示できます。

この方法は、サーバーのファイルシステムへのアクセスできず、スクリプトによるリモート監視およびエラーチェックを有効にする場合に便利です。管理 CLI コマンドを使用すると、ブートエラーを特定し、対処できます。たとえば、複数の JBoss EAP インスタンスを起動し、起動エラーをチェックするスクリプトを作成できます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 管理 CLI を起動します。

    $ <EAP_HOME>/bin/jboss-cli.sh
    Copy to Clipboard Toggle word wrap
  2. 次の管理 CLI コマンドを実行します。

    /core-service=management:read-boot-errors
    Copy to Clipboard Toggle word wrap
  3. 出力を確認し、起動時に発生したエラーの一覧を表示します。

    出力例
    {
        "outcome" => "success",
        "result" => [
            {
                "failed-operation" => {
                    "operation" => "add",
                    "address" => [
                        ("subsystem" => "undertow"),
                        ("server" => "default-server"),
                        ("http-listener" => "default")
                    ]
                },
                "failure-description" => "{\"WFLYCTL0080: Failed services\" => {\"jboss.undertow.listener.default\" => \"org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
        Caused by: java.net.BindException: Address already in use\"}}",
                "failed-services" => {"jboss.undertow.listener.default" => "org.jboss.msc.service.StartException in service jboss.undertow.listener.default: Could not start http listener
        Caused by: java.net.BindException: Address already in use"}
            }
            ...
        ]
    }
    Copy to Clipboard Toggle word wrap

10.1.3. JBoss EAP でのガベッジコレクションのロギング

ガベッジコレクションロギングは、すべてのガベッジコレクションのアクティビティーをプレーンテキストのログファイルに記録します。これらのログは診断を行う場合に役立ちます。

ガベッジコレクションのログは EAP_HOME/standalone/log/gc.log.DIGIT.current にあります。各ログファイルは 3 MB に制限され、最大 5 つのファイルがローテーションされます。

トラブルシューティングに役立ち、オーバーヘッドを最小限に抑えるため、ガベッジコレクションのロギングを有効にすることを推奨します。ただし、スタンドアロンサーバーでは、サーバーを起動する前に GC_LOG 変数を false に設定することで無効にできます。以下に例を示します。

$ export GC_LOG=false
$ EAP_HOME/bin/standalone.sh
Copy to Clipboard Toggle word wrap

10.1.4. JBoss EAP におけるデフォルトのログファイルの場所

以下のログファイルは、デフォルトのロギング設定に基づいて作成されます。これらの設定は Periodic ログハンドラーを使用してサーバーログファイルを書き込みます。

Expand
表10.1 スタンドアロンサーバーのデフォルトのログファイル
ログファイル説明

EAP_HOME/standalone/log/server.log

起動メッセージを含むサーバーログメッセージが含まれます。

EAP_HOME/standalone/log/gc.log.DIGIT.current

ガベージコレクションの詳細が含まれます。

Expand
表10.2 管理対象ドメインのデフォルトログファイル
ログファイル説明

EAP_HOME/domain/log/host-controller.log

ホストコントローラーの起動に関連するログメッセージが含まれます。

EAP_HOME/domain/log/process-controller.log

プロセスコントローラーの起動に関連するログメッセージが含まれます。

EAP_HOME/domain/servers/SERVER_NAME/log/server.log

起動メッセージを含む、名前付きサーバーのログメッセージが含まれます。

10.1.5. JBoss EAP でのサーバーのデフォルトのロケール設定

JVM プロパティーを起動設定ファイルに設定すると、デフォルトのロケールを設定できます。起動設定ファイルは、スタンドアロンサーバーの場合は EAP_HOME/bin/standalone.conf、管理対象ドメインの場合は EAP_HOME/bin/domain.conf になります。

注記

Windows サーバーでは、JBoss EAP 起動設定ファイルは standalone.conf.bat および domain.conf.bat になります。

国際化または現地化されたログメッセージはこのデフォルトロケールを使用します。

前提条件

  • JBoss EAP が実行中である。
  • サーバーモードの起動設定ファイルへのアクセスがある。

手順

  1. user.language プロパティーを JAVA_OPTS 変数に追加して言語を設定します。たとえば、ロケールをフランス語に設定するには、以下の行を起動設定ファイルに追加します。

    JAVA_OPTS="$JAVA_OPTS -Duser.language=fr"
    Copy to Clipboard Toggle word wrap
  2. user.language および user.country プロパティーを追加して、言語と国を設定します。たとえば、ロケールをブラジル語ポルトガル語に設定するには、以下の行を追加します。

    JAVA_OPTS="$JAVA_OPTS -Duser.language=pt -Duser.country=BR"
    Copy to Clipboard Toggle word wrap
  3. o'rg.jboss.logging.locale' プロパティーを使用してサーバーロケールを設定し、ログメッセージに別のロケールを指定します。これにより、ロギング用のデフォルトのロケールが上書きされます。たとえば、サーバーロケールをブラジル語ポルトガル語に設定するには、以下の行を追加します。

    JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.logging.locale=pt-BR"
    Copy to Clipboard Toggle word wrap

    このプロパティーは、JBoss Logging を使用するログメッセージとその依存関係にのみ影響します。Jakarta Server Faces などの他の依存関係ではロケールをオーバーライドできません。

    注記

    システムデフォルト以外のロケールで JBoss EAP を起動するには、スタンドアロンモードの場合は EAP_HOME/bin/standalone.conf を編集するか、管理対象ドメインモードの場合は EAP_HOME/bin/domain.conf を編集します。org.jboss.logging.locale プロパティーを使用して、BCP 47 形式でロケールを設定します。

10.2. ログファイルの表示

サーバーおよびアプリケーションログを表示することは、エラー、パフォーマンスの問題、およびその他の問題を診断するために重要です。

以下の方法を使用してログを表示できます。

ログへのアクセスと管理に関する以下の主要なポイントについて考えてみましょう。

  • ログはサーバーの jboss.server.log.dir プロパティーによって指定されたディレクトリーに存在する必要があります。
  • ログは、ファイル、定期的なローテーション、サイズローテーション、または定期的なサイズローテーション ログハンドラーとして定義されます。
  • ロールベースアクセス制御(RBAC)は、管理コンソールまたは CLI でのアクセスが許可されているログのみを表示できるようにユーザーを制限します。

10.2.1. 管理コンソールからのログの表示

ログアクセス用のグラフィカルインターフェイスを提供する JBoss EAP 管理コンソールから直接ログを表示できます。

前提条件

  • JBoss EAP が実行中である。
  • 管理コンソールにアクセスできる。

手順

  1. 管理コンソールにログインします。
  2. Runtime タブを選択し、該当するサーバーを選択します。
  3. ログファイル を選択し、リストからログファイルを選択します。
  4. 表示 をクリックしてログの内容を開き、検索するか、ドロップダウンから ダウンロード を選択してログファイルをローカルファイルシステムに保存します。

    警告

    管理コンソールのログビューアーは、100MB を超えるログファイルなど、非常に大きなログファイル用には設計されていません。15MB を超えるログファイルを開こうとすると、確認プロンプトが表示されます。管理コンソールで非常に大きなファイルを開くと、ブラウザーがクラッシュする可能性があります。大規模なログファイルをダウンロードしてテキストエディターで開くことが推奨されます。

10.2.2. 管理 CLI からのログの表示

read-log-file コマンドを使用すると管理 CLI からログファイルの内容を読み取ることができます。デフォルトでは、指定されたログファイルの最後の 10 行が表示されます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 次のコマンドを使用して、ログファイルの内容を読み取ります。

    /subsystem=logging/log-file=LOG_FILE_NAME:read-log-file
    Copy to Clipboard Toggle word wrap
    注記

    管理対象ドメインでは、このコマンドの前に /host=HOST_NAME/server=SERVER_NAME を追加します。

  2. 次のパラメーターを使用して、ログの出力をカスタマイズします。

    • encoding: ファイルの読み取りに使用される文字エンコーディングを指定します。
    • Lines: ファイルから読み取る行数を設定します。-1 はログの行すべてを取得します。デフォルトは 10 です。
    • skip: 読み取る前にスキップする行数を指定します。デフォルトは 0 です。
    • tail: ファイルの最後から読み取るかどうかを設定します。デフォルトは true です。

たとえば、以下の管理 CLI コマンドは server.log ログファイルの最初の 5 行を読み取ります。

/subsystem=logging/log-file=server.log:read-log-file(lines=5,tail=false)
Copy to Clipboard Toggle word wrap

このコマンドを実行すると以下が出力されます。

{
    "outcome" => "success",
    "result" => [
        "2016-03-24 08:49:26,612 INFO  [org.jboss.modules] (main) JBoss Modules version 1.5.1.Final-redhat-1",
        "2016-03-24 08:49:26,788 INFO  [org.jboss.msc] (main) JBoss MSC version 1.2.6.Final-redhat-1",
        "2016-03-24 08:49:26,863 INFO  [org.jboss.as] (MSC service thread 1-7) WFLYSRV0049: JBoss EAP 7.0.0.GA (WildFly Core 2.0.13.Final-redhat-1) starting",
        "2016-03-24 08:49:27,973 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0039: Creating http management service using socket-binding (management-http)",
        "2016-03-24 08:49:27,994 INFO  [org.xnio] (MSC service thread 1-1) XNIO version 3.3.4.Final-redhat-1"
    ]
}
Copy to Clipboard Toggle word wrap

10.3. ロギングサブシステム設定の概要

JBoss EAP の logging サブシステムは設定に ログカテゴリー および ログハンドラー を使用します。ログカテゴリーはキャプチャーするメッセージを指定し、ログハンドラーはディスクへの書き込みやコンソールへの送信などのメッセージの処理方法を定義します。

アプリケーションのロギングプロファイル を使用すると、メインのロギング設定とは別に、デプロイメントに割り当てることができる一意の名前や、複数のデプロイメントに割り当てることができます。ロギングプロファイルの設定は、メインの logging サブシステムの設定とほぼ同じです。

10.3.1. ルートロガー設定

JBoss EAP のルートロガーは、ロガーによってキャプチャーされない指定のログレベル以上ですべてのログメッセージをキャプチャーします。しかし、定義したロガーで use-parent-handlers が true に設定され、ハンドラーも定義されている場合、定義されたロガーとルートロガーの両方がメッセージの処理に使用されます。

デフォルトでは、ルートロガーは、server.log ファイルに書き込むコンソールと Periodic ログハンドラーを使用します。このファイルは一般的にサーバーログとして知られています。

10.3.2. JBoss EAP のログカテゴリー

ログカテゴリーは、キャプチャーするログメッセージのセットと、それらのメッセージを処理する 1 つ以上のログハンドラーを定義します。

ログメッセージは指定された送信元およびログレベルによって決定されます。任意の文字列値を指定できます。ただし、パッケージ名またはクラス名が推奨されます。ロガー名は、Logger.getLogger ("example.logger.name") のようにドット表記を使用して指定されます。ログマネージャーは名前の各セクションを処理し、一致する設定をチェックします。find and use-parent-handlers が false に設定されていると、プロセスは停止します。設定が定義されていないか、use-parent-handlers が true に設定されている場合には、ログマネージャーは example.logger などの親名を確認し続けます。ロガー設定は、パッケージまたはクラス名ではなく、ロガーの作成方法によって異なります。

注記

通常、ログカテゴリーは Java パッケージとクラス名に基づいていますが、Logger.getLogger (LOGGER_NAME) メソッドによって指定された名前にすることができます。

ロガーにはハンドラーを割り当てることができます。use-parent-handlersfalse に設定されている場合、ロガーによってログ可能なと判断された場合でも、上位レベルのロガーはメッセージを処理しません。たとえば、ロガー名が org.jboss.as.logging で、use-parent-handlers=false で設定されている場合、org.jboss.as ロガーはチェックされません。

10.3.3. JBoss EAP のログハンドラー

ログハンドラーは、エントリーの宛先および形式を指定して、キャプチャーされたログメッセージの記録方法を定義します。ログハンドラーのタイプを理解することは、さまざまなニーズに合わせた個別の目的に対応するため、効果的なロギング設定のために不可欠です。

注記

ログハンドラーは、少なくとも 1 つのロガーに追加してアクティブにする必要があります。

10.3.3.1. ログハンドラーの種類

ログハンドラーは、ログエントリーの処理および保存方法を決定するいくつかのタイプに分類されます。それぞれのタイプには、さまざまなロギング要件を満たすための個別の機能があります。

  • コンソール: ホストオペレーティングシステムの標準出力( stdout )または標準エラー( stderr )ストリームのいずれかにログメッセージを書き込みます。これらのメッセージは、JBoss EAP がコマンドラインプロンプトから実行されると表示されます。オペレーティングシステムで標準出力または標準エラーストリームをキャプチャーするように設定されていない限り、Console ログハンドラーからのメッセージは保存されません。
  • File: ログメッセージを指定されたファイルに書き込みます。
  • 定期的: 指定された時間が経過するまで、ログメッセージを名前付きファイルに書き込みます。その後、ファイルの名前はタイムスタンプで変更され、ハンドラーは元の名前で新しい作成されたログファイルに書き込みを継続します。
  • サイズ: ファイルが指定されたサイズに達するまで、ログメッセージを名前付きファイルに書き込みます。ファイルがそのサイズに達すると、数値の接尾辞が付いて名前が変更され、ハンドラーは元の名前で新規作成されたログファイルに書き込みを継続します。各サイズログハンドラーは、このような方法で保持するファイルの最大数を指定する必要があります。
  • Periodic Size: ファイルが指定されたサイズに達するか、指定の期間の有効期限が切れるまで、ログメッセージを名前付きファイルに書き込みます。その後、ハンドラーはファイルの名前を変更し、新規作成されたログファイルに元の名前で書き込みを継続します。このハンドラーは、Periodic ログハンドラーと Size ログハンドラーの両方の機能を組み合わせたものです。
  • syslog: リモートロギングサーバーにメッセージを送信します。これにより、複数のアプリケーションが同じサーバーにログメッセージを送信して解析を行うことができます。
  • socket: ソケットでログメッセージをリモートロギングサーバーに送信します。これは、TCP ソケットまたは UDP ソケットのいずれかを使用できます。
  • Custom: 新しいタイプのログハンドラーを設定できます。カスタムハンドラーは、java.util.logging.Handler を拡張し、モジュールに含める Java クラスとして実装する必要があります。Log4J アペンダーをカスタムログハンドラーとして使用することもできます。
  • async: 1 つ以上の他のログハンドラーの非同期動作を提供します。これは、ネットワークファイルシステムへのログファイルの書き込みなど、長い遅延やパフォーマンスの問題があるログハンドラーに役立ちます。

10.3.4. JBoss EAP でサポートされるログレベル

ログレベルとは、ログメッセージの性質と重大度を示す列挙値です。開発者は、このメッセージを送信するために選択したロギングフレームワークの適切なメソッドを使用してログメッセージのレベルを指定できます。

JBoss EAP は、サポートされるアプリケーションロギングフレームワークによって使用されるすべてのログレベルをサポートします。最も一般的に使用されるログレベルは、ログレベルの低い順に TRACEDEBUGINFOWARNERROR および FATAL となります。

ログレベルは、ログカテゴリーとハンドラーが処理するメッセージを制限するのに役立ちます。各ログレベルには、他のログレベルに対して相対的な順番を示す数値が割り当てられています。ログカテゴリーとハンドラーにはログレベルが割り当てられ、そのレベル以上のログメッセージのみを処理します。たとえば、WARN レベルのログハンドラーは、 WARN ERROR、および FATAL にメッセージを記録します。

Expand
表10.3 サポート対象のログレベル
ログのレベルValue説明

ALL

Integer.MIN_VALUE

すべてのログメッセージを提供します。

FINEST

300

-

FINER

400

-

TRACE

400

TRACE レベルのログメッセージは、実行中のアプリケーションの状態に関する詳細な情報を提供し、デバッグ時のみキャプチャーされます。

DEBUG

500

DEBUG レベルのログメッセージは、個々の要求またはアプリケーションアクティビティーの進捗状況を示し、通常はデバッグ時のみキャプチャーされます。

FINE

500

-

CONFIG

700

-

INFO

800

INFO レベルのログメッセージはアプリケーションの全体的な進捗状況を示します。多くの場合、アプリケーションの起動、シャットダウン、およびその他の主要なライフサイクルイベントに使用されます。

WARN

900

WARN レベルのログメッセージはエラーではないが、理想的とは見なされない状況を示します。WARN ログメッセージは将来のエラーを引き起こす可能性のある状況を示す可能性があります。

WARNING

900

-

ERROR

1000

ERROR レベルのログメッセージは、現在のアクティビティーや要求の完了を妨げる可能性があるが、アプリケーションの実行を停止しないエラーを示します。

SEVERE

1000

-

FATAL

1100

FATAL レベルのログメッセージは重大なサービス障害やアプリケーションのシャットダウンを引き起こす可能性があるイベントを示します。これにより、JBoss EAP のシャットダウンにつながる可能性があります。

OFF

Integer.MAX_VALUE

ログメッセージを表示しません。

注記

ALL は、最低ログレベルであり、すべてのログレベルのメッセージを含みます。ロギングの量は最も多くなります。

FATAL は、最大ログレベルであり、そのレベルのメッセージのみを含みます。ロギングの量は最も少なくなります。

10.3.5. JBoss EAP のログフォーマッター

ログフォーマッターはログメッセージのフォーマットに使用されます。named-formatter 属性を使用するとフォーマッターをログハンドラーに割り当てることができます。

10.3.5.1. ログフォーマッターのタイプ

ログエントリーがフォーマットされる方法を決定する複数のタイプに分類されたログフォーマッター。

logging サブシステムには 4 種類のフォーマッターが含まれます。

  • Pattern formatter: ログメッセージをプレーンテキストでフォーマットします。ログハンドラーの named-formatter 属性としてフォーマッターを使用する他に、最初にフォーマッターリソースを作成せずに formatter 属性として使用することもできます。
  • JSON formatter: ログメッセージを JSON 形式でフォーマットします。
  • XML formatter: ログメッセージを XML 形式でフォーマットします。
  • Custom formatter: ハンドラーで使用されます。ほとんどのログレコードは printf 形式でフォーマットされます。フォーマッターは、適切なフォーマットのために org.jboss.logmanager.ExtLogRecord#getFormattedMessage () の呼び出しが必要になる場合があります。

10.3.6. JBoss EAP でのロギング用のフィルター式

フィルター式。filter-spec 属性を使用して設定され、さまざまな基準に基づいてログメッセージを記録します。フィルターは、未フォーマットの raw メッセージに適用されます。フィルターはロガーまたはハンドラーに追加できますが、ハンドラーに配置されたフィルターよりもロガーフィルターが優先されます。

注記

ルートロガーに対して指定された filter-spec は他のロガーによって継承されません。ハンドラーごとに filter-spec を指定する必要があります。

以下の表は、ロギングに使用できるフィルター式について説明しています。

Expand
表10.4 ロギングのフィルター式
フィルター式説明

accept

すべてのログメッセージを許可します。

deny

すべてのログメッセージを拒否します。

not[filter expression]

単一のフィルター式の逆の値を返します。以下に例を示します。

not(match("WFLY"))

all[filter expression]

フィルター式のコンマ区切りリストから連結された値を返します。以下に例を示します。

all(match("WFLY"),match("WELD"))

any[filter expression]

フィルター式のコンマ区切りリストから 1 つの値を返します。以下に例を示します。

any(match("WFLY"),match("WELD"))

levelChange[level]

指定のレベルでログレコードを更新します。以下に例を示します。

levelChange(WARN)

levels[levels]

レベルのコンマ区切りリストにあるレベルの 1 つでログメッセージをフィルターします。以下に例を示します。

levels(DEBUG,INFO,WARN,ERROR)

levelRange[minLevel,maxLevel]

指定されたレベル範囲内でログメッセージをフィルターします。[ および ] は、含まれるレベルを示すために使用されます。( および ) は除外されるレベルを示すために使用されます。以下に例を示します。

  • levelRange[INFO,ERROR]

    • 最小レベルは INFO 以上で、最大レベルは ERROR 以下でなければなりません。
  • levelRange[DEBUG,ERROR)

    • 最小レベルは DEBUG 以上で、最大レベルは ERROR 未満でなければなりません。

match["pattern"]

提供される正規表現を使用してログメッセージをフィルターします。以下に例を示します。

match("WFLY\d+")

substitute["pattern","replacement value"]

最初の一致とパターン(最初の引数)を代替テキスト(2 番目の引数)に置き換えます。以下に例を示します。

substitute("WFLY","EAP")

substituteAll["pattern","replacement value"]

パターン(最初の引数)と一致したすべての値を代替テキスト(2 番目の引数)に置き換えます。以下に例を示します。

substituteAll("WFLY","EAP")

注記

管理 CLI を使用してフィルター式を設定する場合、フィルターテキストのコンマと引用符をエスケープして、値が文字列として正しく処理されるようにします。コンマと引用符の前にバックスラッシュ (\) を付け、式全体を引用符で囲む必要があります。以下は substituteAll("WFLY","YLFW") を適切にエスケープした例になります。

/subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"WFLY\"\,\"YLFW\")")
Copy to Clipboard Toggle word wrap

10.3.7. JBoss EAP の暗黙的なロギングの依存関係

JBoss EAP の logging サブシステムはデフォルトで暗黙的なロギング API 依存関係をデプロイメントに追加します。add-logging-api-dependencies 属性を使用して、これらの暗黙的な依存関係をデプロイメントに追加するかどうかを管理できます。これは、デフォルトで true に設定されています。

これらの依存関係が追加されないようにするには、管理 CLI を使用して add-logging-api-dependencies 属性を false に設定します。

/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)
Copy to Clipboard Toggle word wrap

10.4. ログカテゴリーの設定

管理 CLI を使用すると、JBoss EAP でログカテゴリーを設定できます。または、管理コンソールから設定 > サブシステム > ログ > 設定 を選択し、表示 をクリックして Categories を選択します。

次のタスクを実行して、ログカテゴリーを設定できます。

重要

ロギングプロファイルにこのログカテゴリーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

10.4.1. 管理 CLI を使用したログカテゴリーの追加および設定

ログカテゴリー名は通常、元の Java パッケージです。ただし、ロガーは要件に基づいて任意の文字列名を使用できます。詳細は、Java ロギング API のドキュメントを参照してください。そのパッケージのクラスからのメッセージは、ログレベルなどの他の設定を満たす場合にキャプチャーされます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してログカテゴリーを追加します。

    /subsystem=logging/logger=LOG_CATEGORY:add
    Copy to Clipboard Toggle word wrap
  2. 必要に応じて、以下のログカテゴリー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ログカテゴリーのログレベルを設定します。

      /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 以下のコマンドを使用して、このカテゴリーがルートロガーのログハンドラーを使用するかどうかを設定します。

      /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=use-parent-handlers,value=USE_PARENT_HANDLERS)
      Copy to Clipboard Toggle word wrap

      デフォルトでは、ログカテゴリーは独自のハンドラーに加えてルートロガーのハンドラーを使用します。use-parent-handlers 属性を false に設定して、ログカテゴリーが割り当てられたハンドラーのみを使用するようにします。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/logger=LOG_CATEGORY:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ログカテゴリーのログメッセージをフィルターするための式を指定します。コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を設定します。

10.4.2. ログハンドラーの割り当ておよびログカテゴリーの管理

JBoss EAP のログハンドラーは、ログカテゴリーに対するログメッセージの処理および記録方法を制御します。ログハンドラーを特定のログカテゴリーに割り当て、アプリケーションのニーズに合わせてロギングの動作をカスタマイズします。不要になったログカテゴリーを削除し、ロギング設定を整理して効率的にすることもできます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してログハンドラーをログカテゴリーに割り当てます。

    /subsystem=logging/logger=LOG_CATEGORY:add-handler(name=LOG_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap
  2. 必要に応じて、remove 操作を使用してログカテゴリーを削除できます。

    /subsystem=logging/logger=LOG_CATEGORY:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログカテゴリーが必要なくなったら、ログカテゴリーを削除できます。

10.5. ログハンドラーの設定

ログハンドラーはキャプチャーしたメッセージの記録方法を定義します。

特定のログハンドラーを設定するには、以下のセクションを参照してください。

10.5.1. Console ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP でコンソールログハンドラーを設定できます。または、管理コンソールから設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Console Handler と選択します。

以下のタスクを実行して Console ログハンドラーを設定できます。

  • 新しい Console ログハンドラーの追加
  • Console ログハンドラーの設定
  • Console ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Console ログハンドラーを追加します。

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:add
    Copy to Clipboard Toggle word wrap
  2. 必要に応じて、以下の Console ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 以下のコマンドを使用してハンドラーのターゲットを設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=target,value=TARGET)
      Copy to Clipboard Toggle word wrap

      ターゲットは、System.outSystem.errconsole のいずれかです。デフォルト System.out です。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用して Console ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=CONSOLE_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、Console ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/console-handler=CONSOLE_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.2. File ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP の File ログハンドラーを設定できます。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > File Handler を選択します。

File ログハンドラーを設定するには、以下のタスクを実行します。

  • 新しい File ログハンドラーの追加
  • File ログハンドラーの設定
  • File ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して File ログハンドラーを追加します。

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
    Copy to Clipboard Toggle word wrap
    注記

    File ログハンドラーを追加する場合、path および relative-to 属性で設定される file 属性を使用して ファイル パス を指定します。path 属性を使用して、ファイル名を含むログファイルのパスを設定します(例: my-log.log )。必要に応じて、relative-to 属性を使用して、パスが jboss.server.log.dir などの名前付きパスと相対的であることを示します。

  2. 必要に応じて、以下の File ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用して、ハンドラーの追加動作を設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
      Copy to Clipboard Toggle word wrap

      サーバーの再起動時にファイルを上書きするには、append 属性を false に設定します。デフォルトでは、サーバーの再起動時に JBoss EAP はログメッセージを同じファイルに追加します。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/file-handler=FILE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用して、File ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=FILE_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、File ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 次のコマンドを使用して、File ログハンドラーを CATEGORY という名前の特定のロガーに割り当てます。

    /subsystem=logging/logger=CATEGORY:add-handler(name=FILE_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    CATEGORY は、ファイルログハンドラーを割り当てるロガーの名前に置き換えます。

  5. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/file-handler=FILE_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.3. Periodic rotating ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Periodic rotating ログハンドラーを設定できます。または、管理コンソールからこれらの設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Periodic Handler を選択します。

以下のタスクを実行して、Periodic rotating ログハンドラーを設定できます。

  • 新しい周期ローテーションログハンドラーの追加
  • Periodic rotating ログハンドラーの設定
  • Periodic rotating ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Periodic rotating ログハンドラーを追加します。

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
    Copy to Clipboard Toggle word wrap
    注記

    Periodic rotating ログハンドラーを追加する場合、path および relative-to 属性で設定される file 属性を使用して ファイル パス を指定します。path 属性を使用して、ファイル名を含むログファイルのパスを設定します(例: my-log.log )。必要に応じて、relative-to 属性を使用して、パスが jboss.server.log.dir などの名前付きパスと相対的であることを示します。

    suffix 属性を使用してローテーションログの接尾辞を設定する必要があります。接尾辞は、.yyyy-MM-dd-HH のように java.text.SimpleDateFormat が理解できる形式に従う必要があります。ローテーション期間はこの接尾辞を基に自動的に算出されます。

  2. 必要に応じて、以下の Periodic rotating ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用して、ハンドラーの追加動作を設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=append,value=APPEND)
      Copy to Clipboard Toggle word wrap

      サーバーの再起動時にファイルを上書きするには、append 属性を false に設定します。デフォルトでは、サーバーの再起動時に JBoss EAP はログメッセージを同じファイルに追加します。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用して、Periodic rotating ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、Periodic rotating ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/periodic-rotating-file-handler=PERIODIC_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.4. Size rotating ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Size ログハンドラーを設定できます。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Size Handler と選択します。

Size ログハンドラーを設定するには、以下のタスクを実行します。

  • 新しい Size ログハンドラーの追加
  • Size ログハンドラーの設定
  • Size ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Size ログハンドラーを追加します。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH})
    Copy to Clipboard Toggle word wrap
    注記

    Size ログハンドラーを追加する場合、path および relative-to 属性で設定される file 属性を使用して ファイル パス を指定します。path 属性を使用して、ファイル名を含むログファイルのパスを設定します(例: my-log.log )。必要に応じて、relative-to 属性を使用して、パスが jboss.server.log.dir などの名前付きパスと相対的であることを示します。

  2. 必要に応じて、以下の Size ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用して、ローテーションログの接尾辞を設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=suffix, value=SUFFIX)
      Copy to Clipboard Toggle word wrap
      注記

      指定されている場合、接尾辞は .yyyy-MM-dd-HH のように java.text.SimpleDateFormat が理解できる形式に従う必要があります。接尾辞は size-rotating-file-handler はオプションです。これは、ローテーション期間自体ではなく、ファイルがローテーションされたタイミングを示します。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/size-rotating-file-handler=PERIODIC_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 次のコマンドを使用してローテーションサイズを設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
      Copy to Clipboard Toggle word wrap

      ローテーション前の最大ファイルサイズを設定します。デフォルトは 2 メガバイトを意味する 2m です。

    • 次のコマンドを使用して、保持するバックアップログの最大数を設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
      Copy to Clipboard Toggle word wrap

      保持するバックアップの数を指定します。デフォルト値は 1 です。

      注記

      ローテーションは、接尾辞ではなく、サイズ制限に基づいて行われます。接尾辞が定義されている場合、ローテーションされたファイルに追加されますが、これらのファイルは削除されません。サイズ制限に達したファイルのみがローテーション時に削除されます。

    • 次のコマンドを使用して、起動時にログをローテーションするかどうかを設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
      Copy to Clipboard Toggle word wrap

      デフォルトでは、サーバーの再起動時に新しいログファイルは作成されません。サーバーの再起動時にログをローテーションするには、これを true に設定します。

    • 次のコマンドを使用して、ハンドラーの追加動作を設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
      Copy to Clipboard Toggle word wrap

      サーバーの再起動時にファイルを上書きするには、append 属性を false に設定します。デフォルトでは、サーバーの再起動時に JBoss EAP はログメッセージを同じファイルに追加します。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用して Size ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=SIZE_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、Size ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/size-rotating-file-handler=SIZE_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.5. Periodic Size rotating ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Periodic Size rotating ログハンドラーを設定できます。または、管理コンソールからこれらの設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Periodic Size Handler と選択します。

Periodic Size ログハンドラーを設定するには、以下のタスクを実行します。

  • 新しい Periodic Size ログハンドラーの追加
  • Periodic Size ログハンドラーの設定
  • Periodic Size ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Periodic Size ログハンドラーを追加します。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:add(file={path=FILE_PATH,relative-to=RELATIVE_TO_PATH},suffix=SUFFIX)
    Copy to Clipboard Toggle word wrap
    注記

    Periodic Size ログハンドラーを追加する場合、path および relative-to 属性で設定される file 属性を使用して ファイル パス を指定します。path 属性を使用して、ファイル名を含むログファイルのパスを設定します(例: my-log.log )。必要に応じて、relative-to 属性を使用して、パスが jboss.server.log.dir などの名前付きパスと相対的であることを示します。

    suffix 属性を使用してローテーションログの接尾辞を設定する必要があります。接尾辞は、.yyyy-MM-dd-HH のように java.text.SimpleDateFormat が理解できる形式に従う必要があります。ローテーション期間はこの接尾辞を基に自動的に算出されます。

  2. 必要に応じて、以下の Periodic Size ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用してローテーションサイズを設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-size, value=ROTATE_SIZE)
      Copy to Clipboard Toggle word wrap

      ローテーション前の最大ファイルサイズを設定します。デフォルトは 2 メガバイトを意味する 2m です。

    • 次のコマンドを使用して、保持するバックアップログの最大数を設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=max-backup-index, value=MAX_BACKUPS)
      Copy to Clipboard Toggle word wrap

      保持するバックアップの数を指定します。デフォルト値は 1 です。

      注記

      接尾辞でローテーションされる場合、ローテーションされたファイルは削除されません。ローテーションがローテーション時に削除される場合、サイズ制限に達したファイルのみ。

    • 次のコマンドを使用して、起動時にログをローテーションするかどうかを設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=rotate-on-boot, value=ROTATE_ON_BOOT)
      Copy to Clipboard Toggle word wrap

      デフォルトでは、サーバーの再起動時に新しいログファイルは作成されません。サーバーの再起動時にログをローテーションするには、これを true に設定します。

    • 次のコマンドを使用して、ハンドラーの追加動作を設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=append,value=APPEND)
      Copy to Clipboard Toggle word wrap

      サーバーの再起動時にファイルを上書きするには、append 属性を false に設定します。デフォルトでは、サーバーの再起動時に JBoss EAP はログメッセージを同じファイルに追加します。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用して Periodic Size ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=PERIODIC_SIZE_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、Periodic Size ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/periodic-size-rotating-file-handler=PERIODIC_SIZE_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.6. Syslog ハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Syslog ハンドラーを設定できます。このハンドラーは、Syslog プロトコルをサポートするリモートロギングサーバーに RFC-3164 または RFC-5424 のメッセージを送信します。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Syslog Handler を選択します。

syslog ハンドラーを設定するには、以下のタスクを実行します。

  • 新しい Syslog ハンドラーの追加
  • Syslog ハンドラーの設定
  • Syslog ハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Syslog ハンドラーを追加します。

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:add
    Copy to Clipboard Toggle word wrap
  2. 必要に応じて、以下の Syslog ハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用して、ログのアプリケーション名を設定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=app-name,value=APP_NAME)
      Copy to Clipboard Toggle word wrap

      デフォルトのアプリケーション名は java です。

    • 以下のコマンドを使用して syslog サーバーのアドレスを設定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=server-address,value=SERVER_ADDRESS)
      Copy to Clipboard Toggle word wrap

      デフォルトのアドレスは localhost です。

    • 以下のコマンドを使用して syslog サーバーのポートを設定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=port,value=PORT)
      Copy to Clipboard Toggle word wrap

      デフォルトのポートは 514 です。

    • 以下のコマンドを使用して、RFC 仕様に従って syslog 形式を設定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=syslog-format,value=SYSLOG_FORMAT)
      Copy to Clipboard Toggle word wrap

      デフォルトの形式は RFC5424 です。

    • 以下のコマンドを使用して、syslog ペイロードメッセージをフォーマットするために named-formatter 属性を指定します。

      /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:write-attribute(name=named-formatter, value=FORMATTER_NAME)
      Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して Syslog ハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=SYSLOG_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーをアクティブにするには、syslog ハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 必要に応じて、以下のコマンドで remove 操作を使用してログハンドラーを削除できます。

    /subsystem=logging/syslog-handler=SYSLOG_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.7. Socket ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Socket ログハンドラーを設定できます。ハンドラーは TCP または UDP ソケットを介してメッセージを送信します。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Socket Handler と選択します。

注記

サーバーが admin-only モードで起動すると、ログメッセージを破棄します。

Socket ログハンドラーを設定するには、以下のタスクを実行します。

  • ソケットバインディングの追加
  • ログフォーマッターの追加
  • Socket ログハンドラーの追加
  • 設定を設定する
  • Socket ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してソケットバインディングを追加します。

    /socket-binding-group=SOCKET_BINDING_GROUP/remote-destination-outbound-socket-binding=SOCKET_BINDING_NAME:add(host=HOST, port=PORT)
    Copy to Clipboard Toggle word wrap
    注記

    remote-destination-outbound-socket-binding または local-destination-outbound-socket-binding を使用するソケットバインディングとして定義できます。???

  2. 以下のコマンドを使用して、JSON フォーマッターなど、使用する ログ フォーマッターを追加します。

    /subsystem=logging/json-formatter=FORMATTER:add
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して、ソケットバインディングとフォーマッターを指定して、Socket ログハンドラーを追加します。

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:add(outbound-socket-binding-ref=SOCKET_BINDING_NAME,named-formatter=FORMATTER)
    Copy to Clipboard Toggle word wrap
  4. 必要に応じて、以下の Socket ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用してプロトコルを設定します。

      /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=protocol,value=PROTOCOL)
      Copy to Clipboard Toggle word wrap

      デフォルトのプロトコルは TCP です。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

      注記

      サーバーの起動中、Socket ログハンドラーによって処理されるログメッセージは、ソケットバインディングが設定され、logging サブシステムが初期化されるまでキューに置かれます。ログレベルが低く設定されている場合( TRACEDEBUG など)、起動時に大量のメモリーが消費される可能性があります。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 次のコマンドを使用して、自動フラッシュを設定します。

      /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=autoflush,value=AUTO_FLUSH)
      Copy to Clipboard Toggle word wrap

      毎回書き込みの後に自動的にフラッシュするかどうかを指定します。デフォルト値は true です。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  5. 以下のコマンドを使用して Socket ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=SOCKET_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーをアクティブにするには、Socket ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  6. 必要に応じて、以下のコマンドで remove 操作を使用して Socket ログハンドラーを削除できます。

    /subsystem=logging/socket-handler=SOCKET_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.7.1. SSL/TLS によるソケットログメッセージの送信

SSL_TCP プロトコルを使用して、ソケットにログメッセージを送信するように Socket ログハンドラーを設定できます。この設定には、キーストア、トラストマネージャー、クライアント SSL コンテキストなど、elytron サブシステムの主要なコンポーネントを設定する必要があります。この設定により、JSON フォーマッターによってフォーマットされたメッセージと、指定されたソケット上でルートロガーからのログメッセージを安全に送信できるようになります。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 以下の手順に従って、Elytron を設定します。

    1. 以下のコマンドを使用してキーストアを追加します。

      /subsystem=elytron/key-store=log-server-ks:add(path=/path/to/keystore.jks, type=JKS, credential-reference={clear-text=mypassword})
      Copy to Clipboard Toggle word wrap
    2. 以下のコマンドを使用してトラストマネージャーを追加します。

      /subsystem=elytron/trust-manager=log-server-tm:add(key-store=log-server-ks)
      Copy to Clipboard Toggle word wrap
    3. 以下のコマンドを使用してクライアント SSL コンテキストを追加します。

      /subsystem=elytron/client-ssl-context=log-server-context:add(trust-manager=log-server-tm, protocols=["TLSv1.2"])
      Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを使用してソケットバインディングを追加します。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=log-server:add(host=localhost, port=4560)
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して JSON フォーマッターを追加します。

    /subsystem=logging/json-formatter=json:add
    Copy to Clipboard Toggle word wrap
  4. 以下のコマンドを使用して Socket ログハンドラーを追加します。

    /subsystem=logging/socket-handler=log-server-handler:add(named-formatter=json, level=INFO, outbound-socket-binding-ref=log-server, protocol=SSL_TCP, ssl-context=log-server-context)
    Copy to Clipboard Toggle word wrap
  5. 以下のコマンドを使用して、ログハンドラーをルートロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=log-server-handler)
    Copy to Clipboard Toggle word wrap

10.5.8. カスタムログハンドラーの設定

管理 CLI を使用すると、JBoss EAP でカスタムログハンドラーを設定できます。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Custom Handler と選択します。

以下のタスクを実行して、カスタムログハンドラーを設定できます。

  • 新しいカスタムログハンドラーの追加
  • カスタムログハンドラーの設定
  • カスタムログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してカスタムログハンドラーを追加します。

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:add(class=CLASS_NAME,module=MODULE_NAME)
    Copy to Clipboard Toggle word wrap
    注記

    カスタムログハンドラーを追加するとき、ハンドラーの Java クラスとハンドラーを含む JBoss EAP モジュールを指定します。クラスは java.util.logging.Handler を拡張する必要があります。

    カスタムロガーが含まれる モジュールを作成していることを確認してください。作成されていないと、このコマンドの実行 に失敗します。

  2. 必要に応じて、以下のカスタムログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 以下のコマンドを使用してログハンドラーのプロパティーを設定します。

      /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
      Copy to Clipboard Toggle word wrap

      setter メソッドを使用してプロパティーにアクセスできなければなりません。

    • 次のコマンドを使用して、utf-8 など、ハンドラーのエンコーディングを設定します。

      /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=encoding,value=ENCODING)
      Copy to Clipboard Toggle word wrap
    • 以下のコマンドを使用してハンドラーのフォーマッター文字列を設定します。

      /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=formatter,value=FORMAT)
      Copy to Clipboard Toggle word wrap

      たとえば、デフォルトの書式設定文字列は %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n です。FORMAT の値は引用符で囲みます。

      注記
    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  3. 以下のコマンドを使用してカスタムログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=CUSTOM_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、ハンドラーをルートロガーまたはその他のロガーに割り当てます。

  4. 以下のコマンドを使用して、カスタムログハンドラーを CATEGORY という名前の特定のロガーに割り当てます。

    /subsystem=logging/logger=CATEGORY:add-handler(name=CUSTOM_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    CATEGORY は、カスタムログハンドラーを割り当てるロガーの名前に置き換えます。

  5. 必要に応じて、以下のコマンドで remove 操作を使用してカスタムログハンドラーを削除できます。

    /subsystem=logging/custom-handler=CUSTOM_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーまたは Async ログハンドラーに割り当てられている場合は削除できません。

10.5.9. Async ログハンドラーの設定

管理 CLI を使用すると、JBoss EAP で Async ログハンドラーを設定できます。または、管理コンソールから設定する場合は、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Handler > Async Handler と選択します。

以下のタスクを実行して Async ログハンドラーを設定できます。

  • 新しい非同期ログハンドラーの追加
  • サブハンドラーの Async ログハンドラーへの追加
  • Async ログハンドラーの設定
  • Async ログハンドラーのロガーへの割り当て
重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して Async ログハンドラーを追加します。

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add(queue-length=QUEUE_LENGTH)
    Copy to Clipboard Toggle word wrap
    注記

    Async ログハンドラーを追加する場合、キューの長さを指定します。これは、いつでもキューに保持できるログリクエストの最大数です。

  2. 次のコマンドを使用してサブハンドラーを追加します。

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:add-handler(name=HANDLER_NAME)
    Copy to Clipboard Toggle word wrap
    注記

    1 つ以上のハンドラーを Async ログハンドラーのサブハンドラーとして追加できます。ハンドラーは設定にすでに存在している必要があります。存在しない場合、このコマンドは失敗します。

  3. 必要に応じて、以下の Async ログハンドラー属性を 1 つ以上設定できます。

    • 次のコマンドを使用して、ハンドラーのログレベルを設定します。

      /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=level,value=LEVEL)
      Copy to Clipboard Toggle word wrap

      デフォルトは ALL です。

    • 次のコマンドを使用してオーバーフローアクションを設定します。

      /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=overflow-action,value=OVERFLOW_ACTION)
      Copy to Clipboard Toggle word wrap

      デフォルトの値は BLOCK で、キューがいっぱいになるとスレッドがブロックされます。この値を DISCARD に変更すると、最も古いログメッセージが削除され、キューが満杯になった場合に新しいメッセージに対応します。

    • 次のコマンドを使用してフィルター式を設定します。

      /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:write-attribute(name=filter-spec, value=FILTER_EXPRESSION)
      Copy to Clipboard Toggle word wrap

      ハンドラーのログメッセージをフィルターする式の指定コンマと引用符をエスケープし、式を引用符で囲みます。たとえば、FILTER_EXPRESSION 変数を "not (match (\"WFLY\")) " に置き換え、not (match ("WFLY")) のフィルター式を作成します。

  4. 以下のコマンドを使用して Async ログハンドラーをロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=ASYNC_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap

    ログハンドラーを有効にするには、Async ログハンドラーをルートロガーまたはその他のロガーに割り当てます。

  5. 必要に応じて、以下のコマンドで remove 操作を使用すると非同期ログハンドラーを削除できます。

    /subsystem=logging/async-handler=ASYNC_HANDLER_NAME:remove
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。ただし、ログハンドラーが現在ロガーに割り当てられている場合は削除できません。

10.6. ルートロガーの設定

ルートロガーは、ログカテゴリーによってキャプチャーされないサーバーに送信された指定されたログレベル以上のすべてのログメッセージをキャプチャーします。

管理 CLI を使用して、JBoss EAP のルートロガーを設定できます。または、管理コンソールから設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Root Logger を選択します。

重要

ロギングプロファイルにこのログハンドラーを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用して、ログハンドラーをルートロガーに割り当てます。

    /subsystem=logging/root-logger=ROOT:add-handler(name=LOG_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap
  2. 必要に応じて、以下のコマンドを使用してルートハンドラーを削除できます。

    /subsystem=logging/root-logger=ROOT:remove-handler(name=LOG_HANDLER_NAME)
    Copy to Clipboard Toggle word wrap
    注記

    ロギング設定にログハンドラーが必要なくなったら、ログハンドラーを削除できます。

  3. 次のコマンドを使用して、ハンドラーのログレベルを設定します。

    /subsystem=logging/root-logger=ROOT:write-attribute(name=level,value=LEVEL)
    Copy to Clipboard Toggle word wrap

10.7. ログフォーマッターの設定

ログフォーマッターはハンドラーでのログメッセージの形式を定義します。

logging サブシステムを使用すると、以下のタイプのログフォーマッターを設定できます。

10.7.1. パターンフォーマッターの設定

ログハンドラー間で使用する名前付きパターンフォーマッターを作成して、ログメッセージをフォーマットすることができます。

管理 CLI を使用すると、JBoss EAP のパターンフォーマッターを設定できます。または、管理コンソールから設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Formatter を選択し、Pattern Formatter オプションを選択します。

重要

ロギングプロファイルにこのログフォーマッターを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してパターンフォーマッターを作成します。

    /subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:add(pattern=PATTERN)
    Copy to Clipboard Toggle word wrap

    パターンフォーマッターを定義するとき、ログメッセージをフォーマットするパターン文字列を指定します。たとえば、デフォルトの設定はサーバーログメッセージに次のログフォーマッター文字列を使用します: %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c](%t)%s%e%n.

    2016-03-18 15:49:32,075 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990
    Copy to Clipboard Toggle word wrap

  2. 以下のコマンドを使用してパターンフォーマッターの色マップを設定します。

    /subsystem=logging/pattern-formatter=PATTERN_FORMATTER_NAME:write-attribute(name=color-map,value="LEVEL:COLOR,LEVEL:COLOR")
    Copy to Clipboard Toggle word wrap

    カラーマップを定義して、ログレベルごとに色を割り当てます。形式は LEVEL:COLOR のコンマ区切りリストです。

    • 有効なレベル: finestfinerfineconfigtracedebuginfowarningwarnerrorfatalsevere
    • 有効な色: blackgreenredyellowbluemagentacyanwhitebrightblackbrightredbrightgreenbrightbluebrightyellowbrightmagentabrightcyanbrightwhite

10.7.2. JSON ログフォーマッターの設定

JSON 形式でログメッセージをフォーマットする JSON ログフォーマッターを作成できます。

管理 CLI を使用すると、JBoss EAP で JSON ログフォーマッターを設定できます。または、管理コンソールから設定を設定するには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Formatter を選択し、JSON Formatter オプションを選択します。

重要

ロギングプロファイルにこのログフォーマッターを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. JSON ログフォーマッターを追加します。

    /subsystem=logging/json-formatter=JSON_FORMATTER_NAME:add(pretty-print=true, exception-output-type=formatted)
    Copy to Clipboard Toggle word wrap

    予想される出力

    {
        "timestamp": "2018-10-18T13:53:43.031-04:00",
        "sequence": 62,
        "loggerClassName": "org.jboss.as.server.logging.ServerLogger_$logger",
        "loggerName": "org.jboss.as",
        "level": "INFO",
        "message": "WFLYSRV0025: JBoss EAP 8.1.0.GA (WildFly Core 21.0.5.Final-redhat-00001) started in 5227ms - Started 317 of 556 services (343 services are lazy, passive or on-demand),
        "threadName": "Controller Boot Thread",
        "threadId": 22,
        "mdc": {
        },
        "ndc": "",
        "hostName": "localhost.localdomain",
        "processName": "jboss-modules.jar",
        "processId": 7461
    }
    Copy to Clipboard Toggle word wrap

  2. 以下のコマンドを使用して Logstash JSON ログフォーマッターを追加します。

    /subsystem=logging/json-formatter=logstash:add(exception-output-type=formatted, key-overrides=[timestamp="@timestamp"], meta-data=[@version=1])
    Copy to Clipboard Toggle word wrap
    注記

    JSON ログフォーマッター出力キーを変更し、静的メタデータを追加できます。JSON ログフォーマッターの主な目的は、ログメッセージを JSON 形式でフォーマットすることです。Logstash はこの JSON 出力を消費し、@timestamp および @version フィールドを検索します。以下の例では、Logstash のメッセージをフォーマットする JSON ログフォーマッターを作成します。

    JSON フォーマッター属性は次のように使用できます。

    • key-overrides 属性は、定義されたキーの名前をオーバーライドします。
    • exception-output-type 属性を formatted に設定すると、例外をオブジェクトとしてフォーマットします。
    • exception-output-type 属性を detailed に設定して、例外スタックトレースを含めます。
    • exception-output-typedetailed-and-formatted に設定することにより、例外をオブジェクトとしてフォーマットし、スタックトレースを含めます。
    • meta-data 属性を使用して、レコードにメタデータを追加します。

10.7.3. XML ログフォーマッターの設定

XML 形式でログメッセージをフォーマットする XML ログフォーマッターを作成できます。

管理 CLI を使用して JBoss EAP で XML ログフォーマッターを設定できます。または、管理コンソールから設定( ConfigurationSubsystemsLoggingConfiguration )と選択し、表示 をクリックして Formatter を選択し、XML Formatter オプションを選択します。

重要

ロギングプロファイルにこのログフォーマッターを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. XML ログフォーマッターを追加します。

    /subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, exception-output-type=detailed-and-formatted)
    Copy to Clipboard Toggle word wrap

    予想される出力

    <record>
        <timestamp>2018-10-18T13:55:53.419-04:00</timestamp>
        <sequence>62</sequence>
        <loggerClassName>org.jboss.as.server.logging.ServerLogger_$logger</loggerClassName>
        <loggerName>org.jboss.as</loggerName>
        <level>INFO</level>
        <message>WFLYSRV0025: {ProductCurrentVersionExamples} (WildFly Core 10.0.0.Final-redhat-20190924) started in 6271ms - Started 495 of 679 services (331 services are lazy, passive or on-demand)</message>
        <threadName>Controller Boot Thread</threadName>
        <threadId>22</threadId>
        <mdc>
        </mdc>
        <ndc></ndc>
        <hostName>localhost.localdomain</hostName>
        <processName>jboss-modules.jar</processName>
        <processId>7790</processId>
    </record>
    Copy to Clipboard Toggle word wrap

  2. 以下のコマンドを使用して、キーオーバーライド XML ログフォーマッターを追加します。

    /subsystem=logging/xml-formatter=XML_FORMATTER_NAME:add(pretty-print=true, print-namespace=true, namespace-uri="urn:custom:1.0", key-overrides={message=msg, record=logRecord, timestamp=date}, print-details=true)
    Copy to Clipboard Toggle word wrap

    XML フォーマッター属性は次のように使用できます。

    • key-overrides 属性は、定義されたキーの名前をオーバーライドします。
    • exception-output-type 属性を formatted に設定すると、例外をオブジェクトとしてフォーマットします。
    • exception-output-type 属性を detailed に設定して、例外スタックトレースを含めます。
    • exception-output-typedetailed-and-formatted に設定することにより、例外をオブジェクトとしてフォーマットし、スタックトレースを含めます。
    • meta-data 属性を使用して、レコードにメタデータを追加します。

10.7.4. カスタムログフォーマッターの設定

ログハンドラーすべてで使用するカスタムログフォーマッターを作成して、ログメッセージをフォーマットすることができます。

管理 CLI を使用すると、JBoss EAP でカスタムログフォーマッターを設定できます。または、管理コンソールから設定を行うには、Configuration > Subsystems > Logging > Configuration と選択し、表示 をクリックして Formatter を選択し、Custom Formatter オプションを選択します。

重要

ロギングプロファイルにこのログフォーマッターを設定する場合は、/subsystem=logging/ ではなく /subsystem=logging/logging-profile=LOGGING_PROFILE_NAME/ を指定してコマンドを開始します。

さらに、マネージドドメインで実行している場合はコマンドの前に /profile=PROFILE_NAME を付けます。

前提条件

  • JBoss EAP が実行中である。
  • 管理 CLI にアクセスできる。

手順

  1. 以下のコマンドを使用してカスタムログフォーマッターを追加します。

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:add(class=CLASS_NAME, module=MODULE_NAME)
    Copy to Clipboard Toggle word wrap
    注記

    カスタムログフォーマッターを追加するとき、フォーマッターの Java クラスとそれが含まれる JBoss EAP モジュールを指定します。このクラスは java.util.logging.Formatter を拡張する必要があります。カスタムロガーが含まれる モジュールを作成していることを確認してください。作成されていないと、このコマンドの実行 に失敗します。

  2. 以下のコマンドを使用してログフォーマッターのプロパティーを設定します。

    /subsystem=logging/custom-formatter=CUSTOM_FORMATTER_NAME:write-attribute(name=properties.PROPERTY_NAME,value=PROPERTY_VALUE)
    Copy to Clipboard Toggle word wrap

    setter メソッドを使用してプロパティーにアクセスできなければなりません。

  3. 以下のコマンドを使用してカスタムフォーマッターをログハンドラーに割り当てます。

    /subsystem=logging/periodic-rotating-file-handler=FILE_HANDLER_NAME:write-attribute(name=named-formatter, value=CUSTOM_FORMATTER_NAME)
    Copy to Clipboard Toggle word wrap

    このコマンドは、Periodic rotating ファイルハンドラーで使用するカスタムフォーマッターを割り当てます。

以下の例は、カスタム XML フォーマッターを設定します。org.jboss.logmanager モジュールに提供される java.util.logging.XMLFormatter クラスを使用し、Console ログハンドラーに割り当てます。

/subsystem=logging/custom-formatter=custom-xml-formatter:add(class=java.util.logging.XMLFormatter, module=java.logging)
/subsystem=logging/console-handler=CONSOLE:write-attribute(name=named-formatter, value=custom-xml-formatter)
Copy to Clipboard Toggle word wrap

想定される出力

<record>
  <date>2016-03-23T12:58:13</date>
  <millis>1458752293091</millis>
  <sequence>93963</sequence>
  <logger>org.jboss.as</logger>
  <level>INFO</level>
  <class>org.jboss.as.server.BootstrapListener</class>
  <method>logAdminConsole</method>
  <thread>22</thread>
  <message>WFLYSRV0051: Admin console listening on http://%s:%d</message>
  <param>127.0.0.1</param>
  <param>9990</param>
</record>
Copy to Clipboard Toggle word wrap

10.8. JBoss EAP でのアプリケーションロギングの設定

JBoss EAP の logging サブシステムを使用するか、デプロイメントごと にアプリケーションの ロギング を設定できます。ロギング サブシステムは集中管理を提供し、デプロイメントごと のロギングでは各アプリケーション固有のカスタム設定を有効にします。

10.8.1. デプロイメントごとのロギング設定

デプロイメントごとのロギングを使用すると、開発者はアプリケーションのロギングを事前に設定できます。アプリケーションがデプロイされると、定義された設定に従ってロギングが開始されます。この設定で生成されたログファイルにはアプリケーションの動作に関する情報のみが含まれます。

注記

デプロイメントごとのロギングを使用する場合、アプリケーションは logging サブシステム設定を使用しません。代わりに、アプリケーションのデプロイメントファイル内で定義されたロギング設定を使用します。各アプリケーションには、グローバル設定とは関係なくカスタムロギング設定を指定できます。

このアプローチには、システム全体のロギングと比較して長所と短所があります。利点は、JBoss EAP 管理者がサーバーロギング以外のロギングを設定する必要がないことです。欠点は、デプロイメントごとのロギング設定はサーバーの起動時に読み取り専用であり、実行時に変更できないことです。

10.8.1.1. デプロイメントごとのロギングの無効化

use-deployment-logging-config 属性を設定するか、logging サブシステムを除外すると、JBoss EAP のデプロイメントごとの ロギング を無効にできます。

前提条件

  • JBoss EAP が実行中である。

手順

以下の方法のいずれかを使用して、デプロイメントごとのロギングを無効にします。

  • use-deployment-logging-config 属性を false に設定します。

    /subsystem=logging:write-attribute(name=use-deployment-logging-config,value=false)
    Copy to Clipboard Toggle word wrap

    use-deployment-logging-config 属性は、デプロイメントをデプロイメントごとにスキャンするかどうかを制御します。デフォルトは true です。デプロイメントごとのロギングを無効にするには false に設定します。

  • jboss-deployment-structure.xml ファイルを使用して logging サブシステムを除外します。

10.8.2. アプリケーションロギングプロファイル

ロギングプロファイルは、デプロイされたアプリケーションに割り当てることができる独立したロギング設定のセットです。通常の logging サブシステムと同様に、ロギングプロファイルはハンドラー、カテゴリー、フォーマッター、およびルートロガーを定義できます。ただし、他のプロファイルやメインの logging サブシステムを参照できません。ロギングプロファイルの設計は、設定を容易にする logging サブシステムに似ています。

ロギングプロファイルを使用すると、管理者は他の設定に影響を与えずに 1 つ以上のアプリケーションに固有のロギング設定を作成できます。各プロファイルはサーバー設定で定義されるため、影響を受けるアプリケーションの再デプロイを必要とせずにロギング設定を変更できます。

各ロギングプロファイルには以下の項目を設定できます。

  • 一意な名前。この値は必須です。
  • 任意の数のログハンドラー。
  • 任意の数のログカテゴリー。
  • 最大 1 つのルートロガー。
  • ログフォーマッター。

アプリケーションでは Logging-Profile 属性を設定すると、MANIFEST.MF ファイルで使用するロギングプロファイルを指定できます。

10.8.2.1. ロギングプロファイルの設定

ログハンドラー、カテゴリー、およびルートロガーを使用してロギングプロファイルを設定できます。ロギングプロファイルの設定には、logging サブシステムの設定と同じ構文を使用しますが、以下の点が異なります。

  • ルート設定パスが /subsystem=logging/logging-profile=NAME になります。
  • ロギングプロファイルに他のロギングプロファイルを追加できません。
  • logging サブシステムには、ロギングプロファイルに使用できない以下の属性が含まれています。

    • add-logging-api-dependencies
    • use-deployment-logging-config

管理 CLI を使用して、JBoss EAP のロギングプロファイルを設定できます。または、Configuration > Subsystems > Logging > Logging Profiles と選択すると、管理コンソールからこれらを設定することもできます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 以下のコマンドを使用してロギングプロファイルを作成します。

    /subsystem=logging/logging-profile=PROFILE_NAME:add
    Copy to Clipboard Toggle word wrap
  2. 次のコマンドを使用してファイルハンドラーを追加します。

    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:add(file={path=>"LOG_NAME.log", "relative-to"=>"jboss.server.log.dir"})
    Copy to Clipboard Toggle word wrap
  3. 次のコマンドを使用して、ファイルハンドラーのログレベルを設定します。

    /subsystem=logging/logging-profile=PROFILE_NAME/file-handler=FILE_HANDLER_NAME:write-attribute(name="level", value="DEBUG")
    Copy to Clipboard Toggle word wrap
  4. 次のコマンドを使用してロガー名を作成します。

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add(level=TRACE)
    Copy to Clipboard Toggle word wrap
  5. 次のコマンドを使用して、ファイルハンドラーをカテゴリーに割り当てます。

    /subsystem=logging/logging-profile=PROFILE_NAME/logger=CATEGORY_NAME:add-handler(name="FILE_HANDLER_NAME")
    Copy to Clipboard Toggle word wrap

この後、アプリケーションによって使用されるロギングプロファイルを MANIFEST.MF ファイルに設定できます。

10.8.2.2. アプリケーションロギングプロファイルの設定例

この例は、ロギングプロファイルとそれを使用するアプリケーションの設定を表しています。これには、管理 CLI コマンド、結果となる XML、およびアプリケーションの MANIFEST.MF ファイルが含まれます。

ロギングプロファイルの例には次のような特徴があります。

  • 名前は accounts-app-profile です。
  • ログカテゴリーは com.company.accounts.ejbs です。
  • ログレベルは TRACE です。
  • ログハンドラーは、ejb-trace.log ファイルを使用するファイルハンドラーです。

管理 CLI セッション

/subsystem=logging/logging-profile=accounts-app-profile:add

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:add(file={path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})

/subsystem=logging/logging-profile=accounts-app-profile/file-handler=ejb-trace-file:write-attribute(name="level", value="DEBUG")

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add(level=TRACE)

/subsystem=logging/logging-profile=accounts-app-profile/logger=com.company.accounts.ejbs:add-handler(name="ejb-trace-file")
Copy to Clipboard Toggle word wrap

XML 設定

<logging-profiles>
   <logging-profile name="accounts-app-profile">
      <file-handler name="ejb-trace-file">
         <level name="DEBUG"/>
         <file relative-to="jboss.server.log.dir" path="ejb-trace.log"/>
      </file-handler>
      <logger category="com.company.accounts.ejbs">
         <level name="TRACE"/>
         <handlers>
            <handler name="ejb-trace-file"/>
         </handlers>
      </logger>
   </logging-profile>
</logging-profiles>
Copy to Clipboard Toggle word wrap

アプリケーションの MANIFEST.MF ファイル

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile
Copy to Clipboard Toggle word wrap

10.8.3. デプロイメントロギング設定の表示

管理 CLI を使用して、JBoss EAP でデプロイメントのロギング設定を表示できます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 次のコマンドを使用して、特定のデプロイメントのロギング設定を取得します。

    /deployment=DEPLOYMENT_NAME/subsystem=logging/configuration=CONFIG:read-resource
    Copy to Clipboard Toggle word wrap

    CONFIG の値は次のいずれかになります。

    • デフォルト: デプロイメントが logging サブシステムを使用している場合は、logging サブ システム設定が出力されます。
    • profile-PROFILE_NAME: デプロイメントが logging サブシステムに定義されている ロギングプロファイル を使用している場合は、ロギングプロファイル設定が出力されます。
    • 使用される設定ファイルへのパス (例: myear.ear/META-INF/logging.properties) を指定します。
  2. 特定のロギングプロファイルの設定を表示するには、次のコマンドを実行します。

    /deployment=mydeployment.war/subsystem=logging/configuration=profile-MYPROFILE:read-resource(recursive=true,include-runtime=true)
    Copy to Clipboard Toggle word wrap

    このコマンドは、指定のデプロイメントで使用される MYPROFILE ロギングプロファイルの設定を取得します。

    予想される出力

    {
        "outcome" => "success",
        "result" => {
            "error-manager" => undefined,
            "filter" => undefined,
            "formatter" => {
                "MYFORMATTER" => {
                    "class-name" => "org.jboss.logmanager.formatters.PatternFormatter",
                    "module" => undefined,
                    "properties" => {"pattern" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n"}
                }
            },
            "handler" => {
                "MYPERIODIC" => {
                    "class-name" => "org.jboss.logmanager.handlers.PeriodicRotatingFileHandler",
                    "encoding" => undefined,
                    "error-manager" => undefined,
                    "filter" => undefined,
                    "formatter" => "MYFORMATTER",
                    "handlers" => [],
                    "level" => "ALL",
                    "module" => undefined,
                    "properties" => {
                        "append" => "true",
                        "autoFlush" => "true",
                        "enabled" => "true",
                        "suffix" => ".yyyy-MM-dd",
                        "fileName" => "EAP_HOME/standalone/log/deployment.log"
                    }
                }
            },
            "logger" => {"MYCATEGORY" => {
                "filter" => undefined,
                "handlers" => [],
                "level" => "DEBUG",
                "use-parent-handlers" => true
            }},
            "pojo" => undefined
        }
    }
    Copy to Clipboard Toggle word wrap

  3. 次のコマンドを使用して、再帰的な read-resource 操作を実行して、ロギング設定全体やデプロイメントに関する他の情報を取得することもできます。

    /deployment=DEPLOYMENT_NAME/subsystem=logging:read-resource(include-runtime=true, recursive=true)
    Copy to Clipboard Toggle word wrap

10.9. ロギングサブシステムのパフォーマンス管理

ロギング サブシステムのパフォーマンスを最適化および監視して、効率的なロギングとリソース管理を確保できます。通常の監視は、パフォーマンスに影響を与える前に潜在的な問題を特定するのに役立ちます。

第11章 データソース管理

11.1. JBoss EAP データソースについて

JDBC

JDBC API は、Java アプリケーションがデータベースにアクセスする方法を定義する基準です。アプリケーションは JDBC ドライバーを参照するデータソースを設定します。その後、データベースではなくドライバーに対してアプリケーションを記述できます。ドライバーはコードをデータベース言語に変換します。そのため、適切なドライバーがインストールされていればアプリケーションをサポートされるデータベースで使用できます。

詳細は JDBC の仕様 を参照してください。

サポートされているデータベース

JBoss EAP 8.0 でサポートされている JDBC 対応データベースのリストは、Red Hat JBoss Enterprise Application Platform (EAP) 8.0 でサポートされる構成 を参照してください。

データソースタイプ

リソースの一般的なタイプには、データソースXA データソース の 2 つのタイプがあります。

非 XA データソース
トランザクションを使用しないアプリケーション、または単一のデータベースでトランザクションを使用するアプリケーションに使用されます。
XA データソース
複数のデータベースまたはある XA トランザクションの一部として他の XA リソースを使用するアプリケーションによって使用されます。XA データソースを使用すると追加のオーバーヘッドが発生します。

JBoss EAP 管理インターフェイスを使用してデータソースを作成するときに、使用するデータソースのタイプを指定します。

ExampleDS データソース

JBoss EAP には、データソースの定義方法を実証するために提供されるデータソース設定例 ExampleDS が含まれています。このデータソースは、H2 データベースを使用します。H2 データベースはライトウェイトなリレーショナルデータベース管理システムで、アプリケーションを迅速に構築できる開発者向けの機能を提供します。

警告

ExampleDS データソースと H2 データベースは本番環境で使用 しないでください。これは、アプリケーションのテストおよび構築に必要なすべての標準をサポートする非常に小さい自己完結型のデータソースであり、本番稼働用として堅牢またはスケーラブルではありません。

11.2. JDBC ドライバー

JBoss EAP でアプリケーションが使用するデータソースを定義する前に、最初に適切な JDBC ドライバーをインストールする必要があります。

11.2.1. コアモジュールとしての JDBC ドライバーのインストール

JDBC ドライバーをコアモジュールとしてインストールするには、最初に JDBC ドライバーをコアモジュールとして追加 し、datasources サブシステムで JDBC ドライバーを登録 する必要があります。

11.2.1.1. JDBC ドライバーのコアモジュールとしての追加

以下の手順に従うと、管理 CLI を使用して JDBC ドライバーをコアモジュールとしてインストールすることができます。

  1. JDBC ドライバーをダウンロードします。

    データベースのベンダーから適切な JDBC ドライバーをダウンロードします。一般的なデータベースの JDBC ドライバーをダウンロードできる場所は、JDBC ドライバーのダウンロードできる場所 を参照してください。

    JDBC ドライバーの JAR ファイルが ZIP または TAR アーカイブ内に含まれている場合は、必ずそのアーカイブを展開してください。

  2. JBoss EAP サーバーを起動します。
  3. 管理 CLI を起動します。

    $ EAP_HOME/bin/jboss-cli.sh
    Copy to Clipboard Toggle word wrap
  4. module add 管理 CLI コマンドを使用して新しいコアモジュールを追加します。

    [disconnected /] module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES
    Copy to Clipboard Toggle word wrap

    次のコマンドは、MySQL JDBC ドライバーモジュールを追加します。

    [disconnected /] module add --name=com.mysql --resources=/path/to/mysql-connector-j-8.0.33.jar --dependencies=jakarta.transaction.api,java.se,wildflyee.api,java.xml,java.xml.crypto,jdk.xml.dom
    Copy to Clipboard Toggle word wrap

    管理 CLI を起動して新しいコアモジュールを 1 ステップで追加するには、次のコマンドを使用します。

    $ EAP_HOME/bin/jboss-cli.sh --command="module add --name=MODULE_NAME --resources=PATH_TO_JDBC_JAR --dependencies=DEPENDENCIES"
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

    module --help を実行すると、このコマンドを使用したモジュールの追加および削除の詳細を表示できます。

次に、アプリケーションデータソースによって参照されるよう、JDBC ドライバーとして登録する必要があります。

11.2.1.2. JDBC ドライバーの登録

ドライバーが コアモジュールとしてインストール されたら、以下の管理 CLI コマンドを使用して JDBC ドライバーとして登録する必要があります。マネージドドメインを実行している場合は、コマンドの前に /profile=PROFILE_NAME を付けてください。

/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-class-name=DRIVER_CLASS_NAME)
Copy to Clipboard Toggle word wrap
注記

driver-class-name パラメーターは、JDBC ドライバー jar が /META-INF/services/java.sql.Driver ファイルで複数の jar を定義する場合のみ必要です。

たとえば、MySQL 5.1.36 JDBC ドライバー JAR の /META-INF/services/java.sql.Driver ファイルは、以下の 2 つのクラスを定義します。

  • com.mysql.cj.jdbc.Driver
  • com.mysql.fabric.jdbc.FabricMySQLDriver

この場合、driver-class-name=com.mysql.cj.jdbc.Driver で渡します。

たとえば、以下のコマンドは MySQL JDBC ドライバーを登録します。

/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
Copy to Clipboard Toggle word wrap

アプリケーションのデータソースが JDBC ドライバーを参照できる状態になります。

11.2.2. JDBC ドライバーの JAR デプロイメントとしてのインストール

管理 CLI または管理コンソールを使用して JDBC ドライバーを JAR デプロイメントとしてインストールできます。JDBC 4 に対応するドライバーは、自動的に認識され、デプロイメント時に JDBC ドライバーとしてインストールされます。

以下の手順は、管理 CLI を使用した JDBC ドライバーのインストール方法になります。

注記

JDBC ドライバーを コアモジュール としてインストールする方法が推奨されます。

  1. JDBC ドライバーをダウンロードします。

    データベースのベンダーから適切な JDBC ドライバーをダウンロードします。一般的なデータベースの JDBC ドライバーをダウンロードできる場所は、JDBC ドライバーのダウンロードできる場所 を参照してください。

    JDBC ドライバーの JAR ファイルが ZIP または TAR アーカイブ内に含まれている場合は、必ずそのアーカイブを展開してください。

  2. JDBC ドライバーが JDBC 4 に対応していない場合は、JDBC ドライバー JAR を JDBC 4 対応に更新 の手順を参照してください。
  3. JAR を JBoss EAP にデプロイします。

    deploy PATH_TO_JDBC_JAR
    Copy to Clipboard Toggle word wrap
    注記

    マネージドドメインでは、適切なサーバーグループを指定します。

    たとえば、以下のコマンドは MySQL JDBC ドライバーをデプロイします。

    deploy /path/to/mysql-connector-j-8.0.33.jar
    Copy to Clipboard Toggle word wrap

    JBoss EAP サーバーログにメッセージが表示され、データソースを定義するときに使用されるデプロイされたドライバーの名前が表示されます。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-j-8.0.33.jar
    Copy to Clipboard Toggle word wrap

アプリケーションのデータソースが JDBC ドライバーを参照できる状態になります。

JDBC ドライバー JAR を JDBC 4 対応に更新する

JDBC ドライバー JAR が JDBC 4 に対応していない場合、以下の手順に従ってデプロイ可能にすることができます。

  1. 空の一時ディレクトリーを作成します。
  2. META-INF サブディレクトリーを作成します。
  3. META-INF/services サブディレクトリーを作成します。
  4. META-INF/services/java.sql.Driver ファイルを作成し、JDBC ドライバーの完全修飾クラス名を示す 1 行を追加します。

    たとえば、MySQL JDBC ドライバーでは以下の行を追加します。

    com.mysql.cj.jdbc.Driver
    Copy to Clipboard Toggle word wrap
  5. JAR コマンドラインツールを使用して、この新しいファイルを JAR に追加します。

    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver
    Copy to Clipboard Toggle word wrap

11.2.3. JDBC ドライバーをダウンロードできる場所

下表は、JBoss EAP で使用される一般的なデータベースの JDBC ドライバーをダウンロードできる場所を示しています。

注記

これらのリンク先は他社の Web サイトであるため、Red Hat は管理しておらず、積極的に監視も行っていません。ご使用のデータベースの最新ドライバーは、データベースベンダーのドキュメントおよび Web サイトを確認してください。

Expand
表11.1 JDBC ドライバーをダウンロードできる場所
ベンダーダウンロード場所

MySQL

http://www.mysql.com/products/connector/

PostgreSQL

http://jdbc.postgresql.org/

Oracle

http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

IBM

http://www-01.ibm.com/support/docview.wss?uid=swg21363866

Sybase

jConnect JDBC ドライバーは、SAP ASE インストールの SDK の一部です。現在、このドライバーのみをダウンロードできるサイトはありません。

Microsoft

http://msdn.microsoft.com/data/jdbc/

11.2.4. ベンダー固有クラスへのアクセス

場合によっては、アプリケーションが JDBC API の一部ではないベンダー固有の機能を使用する必要があることがあります。このような場合、そのアプリケーションで依存関係を宣言してベンダー固有の API にアクセスすることができます。

警告

これは高度な使用法です。JDBC API に含まれない機能を必要とするアプリケーションのみこれを実装します。

重要

このプロセスは、再認証メカニズムを使用し、ベンダー固有のクラスにアクセスする場合に必要です。

MANIFEST.MF ファイルまたは jboss-deployment-structure.xml ファイルを使用するとアプリケーションの依存関係を定義できます。

JDBC ドライバーをコアモジュールとしてインストール していない場合は、インストールしてください。

MANIFEST.MF ファイルの使用
  1. アプリケーションの META-INF/MANIFEST.MF ファイルを編集します。
  2. Dependencies 行を追加し、モジュール名を指定します。

    たとえば、以下の行は com.mysql モジュールを依存関係として宣言します。

    Dependencies: com.mysql
    Copy to Clipboard Toggle word wrap
jboss-deployment-structure.xml ファイルの使用
  1. アプリケーションの META-INF/ または WEB-INF/ フォルダーで jboss-deployment-structure.xml というファイルを作成します。
  2. dependencies 要素を使用してモジュールを指定します。

    たとえば、以下の jboss-deployment-structure.xml ファイル例は com.mysql モジュールを依存関係として宣言します。

    <jboss-deployment-structure>
      <deployment>
        <dependencies>
          <module name="com.mysql"/>
        </dependencies>
      </deployment>
    </jboss-deployment-structure>
    Copy to Clipboard Toggle word wrap

以下のコード例は MySQL API にアクセスします。

import java.sql.Connection;
...
Connection c = ds.getConnection();
if (c.isWrapperFor(com.mysql.jdbc.Connection.class)) {
    com.mysql.jdbc.Connection mc = c.unwrap(com.mysql.jdbc.Connection.class);
}
Copy to Clipboard Toggle word wrap
重要

接続は IronJacamar コンテナーによって制御されるため、ベンダー固有の API ガイドラインに従ってください。

11.3. データソースの作成

データソースは管理コンソールまたは管理 CLI を使用して作成できます。

JBoss EAP 8.0 では、enabled 属性などのデータソース属性の値に式を使用できます。

11.3.1. 非 XA データソースの作成

管理 CLI または管理コンソールを使用して、非 XA データソース作成できます。

管理コンソールを使用した非 XA データソースの定義
  1. スタンドアロンモードまたはドメインモードで、データソースに移動します。

    • スタンドアロンモードでは、次のナビゲーションを使用します。

      ConfigurationSubsystemsDatasources & DriversDatasources

    • ドメインモードで次のナビゲーションを使用します。

      ConfigurationProfilesfullDatasources & DriversDatasources

  2. 追加 (+) ボタンをクリックし、Add Datasource を選択します。
  3. データソースタイプを選択できる Add Datasource ウィザードが表示されたら、Next をクリックします。これにより、データベースのテンプレートが作成されます。ウィザードの以下のページには、選択したデータソースに固有する値が自動的に入力されています。これにより、データソースの作成プロセスが簡単になります。
  4. データソースの作成を終了する前に、Test Connection ページで接続をテストできます。
  5. 詳細を確認し、Finish をクリックしてデータソースを作成します。
管理 CLI を使用した非 XA データソースの定義

data-source add 管理 CLI コマンドを使用すると、非 XA データソースを定義できます。

  1. JDBC ドライバーをコアモジュールとしてインストールおよび登録していない場合は、コアモジュールとしての JDBC ドライバーのインストール を参照してインストールと登録を行ってください。
  2. 適切な引数の値を指定し、data-source add コマンドを使用してデータソースを定義します。

    data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --connection-url=CONNECTION_URL --user-name=USER_NAME --password=PASSWORD
    Copy to Clipboard Toggle word wrap
    注記

    マネージドドメインでは、--profile=PROFILE_NAME 引数を指定する必要があります。

    これらのパラメーター値は、以下の データソースパラメーター の項を参照してください。

詳細な例は、サポート対象データベースの データソース設定例 を参照してください。

データソースのパラメーター
jndi-name
データソースの JNDI 名は、java:/ または java:jboss/ で始まる必要があります。たとえば、java:jboss/datasources/ExampleDS になります。
driver-name

ドライバー名の値は、JDBC ドライバーがコアモジュールまたは JAR デプロイメントとしてインストールされたかによって異なります。

  1. コアモジュールでは、ドライバー名の値は登録時に指定した JDBC ドライバーの名前になります。
  2. JAR デプロイメントでは、/META-INF/services/java.sql.Driver ファイルに 1 つのクラスのみがある場合はドライバー名が JAR の名前になります。複数のクラスがリストされている場合は値が JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION (例: mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1) になります。

    また、JDBC JAR がデプロイされると JBoss EAP サーバーログにドライバー名がリストされます。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
    Copy to Clipboard Toggle word wrap
connection-url
サポートされるデータベースの接続 URL 形式の詳細は、データソース接続 URL のリストを参照してください。

利用できるデータソース属性の完全リストは、データソース属性 を参照してください。

user-name
新しいデータソース接続を作成するときに使用するユーザー名。
password
新しいデータソース接続を作成するときに使用するパスワード。

11.3.2. XA データソースの作成

管理 CLI または管理コンソールを使用して XA データソースを作成できます。

管理コンソールを使用した XA データソースの定義
  1. スタンドアロンモードまたはドメインモードで、データソースに移動します。

    • スタンドアロンモードでは、次のナビゲーションを使用します。

      ConfigurationSubsystemsDatasources & DriversDatasources

    • ドメインモードで次のナビゲーションを使用します。

      ConfigurationProfilesfullDatasources & DriversDatasources

  2. 追加 (+) ボタンをクリックし、XA データソースを追加 を選択します。
  3. データソースタイプを選択できる XA データソースを追加 ウィザードが表示されたら、Next をクリックします。これにより、データベースのテンプレートが作成されます。ウィザードの以下のページには、選択したデータソースに固有する値が自動的に入力されています。これにより、データソースの作成プロセスが簡単になります。
  4. データソースの作成を終了する前に、Test Connection ページで接続をテストできます。
  5. 詳細を確認し、Finish をクリックしてデータソースを作成します。
管理 CLI を使用した XA データソースの定義

xa-data-source add 管理 CLI コマンドを使用すると XA データソースを定義できます。

注記

マネージドドメインでは、使用するプロファイルを指定する必要があります。管理 CLI コマンドの形式に応じて、コマンドの前に /profile=PROFILE_NAME を付けるか、--profile=PROFILE_NAME 引数に渡します。

  1. JDBC ドライバーをコアモジュールとしてインストールおよび登録していない場合は、コアモジュールとしての JDBC ドライバーのインストール を参照してインストールと登録を行ってください。
  2. 適切な引数の値を指定し、xa-data-source add コマンドを使用してデータソースを定義します。

    xa-data-source add --name=XA_DATASOURCE_NAME --jndi-name=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasource-class=XA_DATASOURCE_CLASS --xa-datasource-properties={"ServerName"=>"HOST_NAME","DatabaseName"=>"DATABASE_NAME"}
    Copy to Clipboard Toggle word wrap

    これらのパラメーター値は、以下の データソースパラメーター の項を参照してください。

  3. XA データソースプロパティー を設定します。

    XA データソースを定義するときに最低でも 1 つの XA データソースプロパティー が必要になります。XA データソースプロパティーがないと、前のステップでデータソースを追加するときにエラーが発生します。XA データソースを定義するときに設定しなかったプロパティーは後で個別に設定することができます。

    1. サーバー名を設定します。

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=ServerName:add(value=HOST_NAME)
      Copy to Clipboard Toggle word wrap
    2. データベース名を設定します。

      /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=DatabaseName:add(value=DATABASE_NAME)
      Copy to Clipboard Toggle word wrap

詳細な例は、サポート対象データベースの データソース設定例 を参照してください。

データソースのパラメーター
jndi-name
データソースの JNDI 名は、java:/ または java:jboss/ で始まる必要があります。たとえば、java:jboss/datasources/ExampleDS になります。
driver-name

ドライバー名の値は、JDBC ドライバーがコアモジュールまたは JAR デプロイメントとしてインストールされたかによって異なります。

  1. コアモジュールでは、ドライバー名の値は登録時に指定した JDBC ドライバーの名前になります。
  2. JAR デプロイメントでは、/META-INF/services/java.sql.Driver ファイルに 1 つのクラスのみがある場合はドライバー名が JAR の名前になります。複数のクラスがリストされている場合は値が JAR_NAME + "_" + DRIVER_CLASS_NAME + "_" + MAJOR_VERSION + "_" + MINOR_VERSION (例: mysql-connector-java-5.1.36-bin.jar_com.mysql.jdbc.Driver_5_1) になります。

    また、JDBC JAR がデプロイされると JBoss EAP サーバーログにドライバー名がリストされます。

    WFLYJCA0018: Started Driver service with driver-name = mysql-connector-java-5.1.36-bin.jar_com.mysql.cj.jdbc.Driver_5_1
    Copy to Clipboard Toggle word wrap
xa-datasource-class
JDBC ドライバーの jakarta.sql.XADataSource クラスの実装に対して XA データソースクラスを指定します。
xa-datasource-properties
XA データソースを定義するときに最低でも 1 つの XA データソースプロパティー が必要になります。XA データソースプロパティーがないと、追加するときにエラーが発生します。XA データソースの定義後にプロパティーを追加することもできます。

利用できるデータソース属性の完全リストは、データソース属性 を参照してください。

11.4. データソースの変更

データソースは、管理コンソールまたは管理 CLI を使用して設定できます。

JBoss EAP 8.0 では、enabled 属性などのデータソース属性の値に式を使用できます。

11.4.1. 非 XA データソースの変更

非 XA データソース設定は data-source 管理 CLI コマンドを使用して更新できます。スタンドアロンモードまたはドメインモードの管理コンソールから datasource 属性を更新することもできます。

  • スタンドアロンモードでは、ConfigurationSubsystemsDatasources & DriversDatasources に移動します。
  • ドメインモードでは、ConfigurationProfilesfullDatasources & DriversDatasources に移動します。
注記

非 XA データソースは Jakarta Transactions トランザクションと統合できます。データソースを Jakarta Transactions と統合する場合、必ず jta パラメーターを true に設定してください。

データソースの設定を更新する例

データソースの設定は、以下の管理 CLI コマンドを使用して更新できます。

data-source --name=DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、--profile=PROFILE_NAME 引数を指定する必要があります。

変更を反映するのにサーバーのリロードが必要になる場合があります。

11.4.2. XA データソースの変更

XA データソース設定は xa-data-source 管理 CLI コマンドを使用して更新できます。スタンドアロンモードまたはドメインモードの管理コンソールから datasource 属性を更新することもできます。

  • スタンドアロンモードでは、ConfigurationSubsystemsDatasources & DriversDatasources に移動します。
  • ドメインモードでは、ConfigurationProfilesfullDatasources & DriversDatasources に移動します。

XA データソースの更新例

  • XA データソースの設定は、以下の管理 CLI コマンドを使用して更新できます。

    xa-data-source --name=XA_DATASOURCE_NAME --ATTRIBUTE_NAME=ATTRIBUTE_VALUE
    Copy to Clipboard Toggle word wrap
    注記

    マネージドドメインでは、--profile=PROFILE_NAME 引数を指定する必要があります。

XA データソースプロパティーの追加例

  • 以下の管理 CLI コマンドを使用すると XA データソースプロパティー を追加できます。

    /subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME/xa-datasource-properties=PROPERTY:add(value=VALUE)
    Copy to Clipboard Toggle word wrap
    注記

    マネージドドメインでは、このコマンドの前に /profile=PROFILE_NAME を追加する必要があります。

変更を反映するのにサーバーのリロードが必要になる場合があります。

11.5. データソースの削除

データソースは管理コンソールまたは管理 CLI を使用して削除できます。

11.5.1. 非 XA データソースの削除

非 XA データソースは data-source remove 管理 CLI コマンドを使用して削除できます。スタンドアロンモードまたはドメインモードの管理コンソールを使用して、データソースを削除することもできます。

  • スタンドアロンモードでは、ConfigurationSubsystemsDatasources & DriversDatasources に移動します。
  • ドメインモードでは、ConfigurationProfilesfullDatasources & DriversDatasources に移動します。

次のコマンドを使用して非 XA データソースを削除します。

data-source remove --name=DATASOURCE_NAME
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、--profile=PROFILE_NAME 引数を指定する必要があります。

データソースの削除後にサーバーのリロードが必要になります。

11.5.2. XA データソースの削除

XA データソースは xa-data-source remove 管理 CLI コマンドを使用して削除できます。スタンドアロンモードまたはドメインモードの管理コンソールを使用して、データソースを削除することもできます。

  • スタンドアロンモードでは、ConfigurationSubsystemsDatasources & DriversDatasources に移動します。
  • ドメインモードでは、ConfigurationProfilesfullDatasources & DriversDatasources に移動します。

次のコマンドを使用して XA データソースを削除します。

xa-data-source remove --name=XA_DATASOURCE_NAME
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、--profile=PROFILE_NAME 引数を指定する必要があります。

XA データソースの削除後にサーバーのリロードが必要になります。

11.6. データソース接続のテスト

管理 CLI または管理コンソールを使用してデータソースの接続をテストし、設定が適切であることを検証できます。

管理 CLI を使用したデータソース接続のテスト

以下の管理 CLI コマンドを実行すると、データソースの接続をテストできます。

/subsystem=datasources/data-source=DATASOURCE_NAME:test-connection-in-pool
Copy to Clipboard Toggle word wrap
注記

マネージドドメインでは、このコマンドの前に /host=HOST_NAME/server=SERVER_NAME を追加する必要があります。XA データソースをテストする場合は、data-source=DATASOURCE_NAMExa-data-source=XA_DATASOURCE_NAME に置き換えてください。

管理コンソールを使用したデータソース接続のテスト

管理コンソールで データソースの追加 ウィザードを使用する場合、データソースの作成前に接続をテストできます。ウィザードの テスト接続 画面で テスト接続 ボタンをクリックします。

データソースが追加されたら、次の手順を使用して接続をテストできます。

  1. スタンドアロンモードでは、ConfigurationSubsystemsDatasources & DriversDatasources に移動します。ドメインモードでは、ConfigurationProfilesfullDatasources & DriversDatasources に移動します。
  2. データソースを選択します。
  3. ドロップダウンリストから Test Connection を選択します。

11.7. データソース接続のフラッシュ

以下の管理 CLI コマンドを使用して、データベースの接続をフラッシュします。

注記

マネージドドメインでは、コマンドの前に /host=HOST_NAME/server=SERVER_NAME を追加する必要があります。

  • プールの接続をすべてフラッシュします。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-all-connection-in-pool
    Copy to Clipboard Toggle word wrap
  • プールの接続をすべて正常にフラッシュします。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-gracefully-connection-in-pool
    Copy to Clipboard Toggle word wrap

    サーバーは、接続がアイドル状態なるまで待ってから接続をフラッシュします。

  • プールのアイドル状態の接続をすべてフラッシュします。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-idle-connection-in-pool
    Copy to Clipboard Toggle word wrap
  • プールの無効な接続をすべてフラッシュします。

    /subsystem=datasources/data-source=DATASOURCE_NAME:flush-invalid-connection-in-pool
    Copy to Clipboard Toggle word wrap

    サーバーは、データベース接続の検証 で説明した valid-connection-checker-class-name または check-valid-connection-sql 検証メカニズムなどによって無効と判断されたすべての接続をフラッシュします。

管理コンソールを使用して接続をフラッシュすることもできます。Runtime タブでサーバーを選択し、Datasources を選択してデータソースを指定します。ドロップダウンメニューを使用してアクションを選択します。

11.8. XA データソースのリカバリー

XA データソースは、XA グローバルトランザクションに参加できるデータソースです。XA グローバルトランザクションはトランザクションマネージャーによって調整され、1 つのトランザクションで複数のリソースにまたがる可能性があります。参加者の 1 つが変更のコミットに失敗した場合、他の参加者がトランザクションをアボートし、トランザクション発生前の状態にリストアします。これにより、一貫性を保持し、データの損失や破損を防ぎます。

XA リカバリーは、リソースやトランザクションの参加者がクラッシュしたり利用できない状態になっても、トランザクションの影響を受けるすべてのリソースが更新またはロールバックされるようにするプロセスです。XA リカバリーはユーザーが関与せずに行われます。

各 XA リソースにはその設定に関連するリカバリーモジュールが必要になります。リカバリーモジュールは、リカバリーの実行中に実行されるコードです。JBoss EAP は JDBC XA リソースのリカバリーモジュールを自動的に登録します。カスタムのリカバリーコードを実装する場合は XA データソースでカスタムモジュールを登録できます。リカバリーモジュールは com.arjuna.ats.jta.recovery.XAResourceRecovery クラスを拡張する必要があります。

11.8.1. XA リカバリーの設定

ほとんどの JDBC では、リカバリーモジュールがリソースに自動的に関連付けられます。この場合は、リカバリーモジュールがリソースに接続してリカバリーを実行することを許可するオプションのみを設定する必要があります。

以下の表は、XA リカバリーに固有する XA データソースパラメーターを表しています。これらの設定属性はデータソースの作成中または作成後に設定できます。これらは管理コンソールまたは管理 CLI を使用して設定できます。XA データソースの設定に関する詳細は、XA データソースの変更 を参照してください。

Expand
表11.2 XA リカバリーのデータソースパラメーター
属性説明

recovery-username

リカバリーでリソースに接続するために使用するユーザー名。指定しないと、データソースのセキュリティー設定が使用されます。

recovery-password

リカバリーのリソースへの接続に使用するパスワード。指定しないと、データソースのセキュリティー設定が使用されます。

recovery-security-domain

リカバリーでリソースに接続するために使用するセキュリティードメイン。

recovery-plugin-class-name

カスタムのリカバリーモジュールを使用する必要がある場合は、この属性をモジュールの完全修飾クラス名に設定します。モジュールはクラス com.arjuna.ats.jta.recovery.XAResourceRecovery を拡張する必要があります。

recovery-plugin-properties

プロパティーを設定する必要があるカスタムのリカバリーモジュールを使用する場合は、この属性をプロパティーに対するコンマ区切りの KEY=VALUE ペアのリストに設定します。

XA リカバリーの無効化

複数の XA データソースが同じ物理データベースに接続する場合、通常 XA リカバリーは XA データソースの 1 つのみに設定する必要があります。

以下の管理 CLI コマンドを使用して XA データソースのリカバリーを無効にします。

/subsystem=datasources/xa-data-source=XA_DATASOURCE_NAME:write-attribute(name=no-recovery,value=true)
Copy to Clipboard Toggle word wrap

11.8.2. ベンダー固有の XA リカバリー

ベンダー固有の設定

一部のデータベースは、JBoss EAP トランザクションマネージャーによって管理される XA トランザクションに対応するために特定の設定が必要になります。詳細な最新情報は、データベースベンダーの資料を参照してください。

MySQL
特別な設定は必要ありません。詳細は MySQL のドキュメントを参照してください。
注記

自動化された XA リカバリーの場合には、MySQL 8 以降では特別な設定が必要です。詳細は、Red Hat JBoss Enterprise Application Platform (EAP) 8.0 でサポートされる構成 を参照してください。

PostgreSQL および Postgres Plus Advanced Server
PostgreSQL による XA トランザクションの処理を可能にするには、max_prepared_transactions 設定パラメーターを 0 よりも大きい値または max_connections 以上の値に変更します。
Oracle

必ず Oracle ユーザー USER がリカバリーに必要なテーブルにアクセスできるようにしてください。

GRANT SELECT ON sys.dba_pending_transactions TO USER;
GRANT SELECT ON sys.pending_trans$ TO USER;
GRANT SELECT ON sys.dba_2pc_pending TO USER;
GRANT EXECUTE ON sys.dbms_xa TO USER;
Copy to Clipboard Toggle word wrap

Oracle ユーザーに適切なパーミッションがないと、以下のようなエラーが表示される可能性があります。

WARN [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception jakarta.transaction.xa.XAException, XAException.XAER_RMERR
Copy to Clipboard Toggle word wrap
Microsoft SQL Server
詳細は、Understanding XA transactions などの Microsoft SQL Server のドキュメントを参照してください。
IBM DB2
特別な設定は必要ありません。詳細は IBM DB2 のドキュメントを参照してください。
Sybase

Sybase は、XA トランザクションがデータベース上で有効であることを想定します。XA トランザクションはデータベース設定が正しくないと動作しません。enable xact coordination パラメーターは、Adaptive Server トランザクションコーディネーションサービスを有効または無効にします。このパラメーターを有効にすると、リモート Adaptive Server データの更新が、確実に元のトラザクションでコミットまたはロールバックされるようになります。

トラザクションコーディネーションを有効にするには、以下を使用します。

sp_configure 'enable xact coordination', 1
Copy to Clipboard Toggle word wrap
MariaDB
特別な設定は必要ありません。詳細は MariaDB のドキュメントを参照してください。
既知の問題

ここで取り上げる既知の問題は、JBoss EAP 8.0 でサポートされる特定のデータベースおよび JDBC ドライバーバージョンの XA トランザクションの処理に関する問題です。サポートされるデータベースの最新情報は、Red Hat JBoss Enterprise Application Platform (EAP) 8.0 でサポートされる構成 を参照してください。

MySQL
MySQL は XA トランザクションを完全に処理できません。クライアントと MySQL の接続が切断されると、トランザクションに関する情報がすべて失われます。詳細は MySQL のバグ を参照してください。この問題は MySQL 5.7 で修正されました。
PostgreSQL および Postgres Plus Advanced Server

2 フェーズコミット (2PC) のコミットフェーズ中にネットワークの障害が発生すると、JDBC ドライバーによって XAER_RMERR XAException エラーコードが返されます。このエラーは、トランザクションマネージャーでリカバリー不可能な重大なイベントが発生したことを示しますが、トランザクションはデータベース側で in-doubt 状態を維持し、ネットワーク接続の回復後に簡単に修正できます。適切な戻りコードは XAER_RMFAIL または XAER_RETRY になります。誤ったエラーコードにより、トランザクションが JBoss EAP 側で Heuristic 状態のままになり、データベースでロックが保持されるため、手動の介入が必要になります。詳細は PostgreSQL のバグ を参照してください。

1 フェーズコミットの最適化が使用されたときに接続の障害が発生した場合、JDBC ドライバーは XAER_RMERR を返しますが、適切な戻りコードは XAER_RMFAIL になります。そのため、1 フェーズコミット中にデータベースがデータをコミットし、同時に接続が切断されると、クライアントにはトラザクションがロールバックされたと伝えられるため、データの不整合が発生する場合があります。

Postgres Plus JDBC ドライバーは、Postgres Plus Server に存在するすべての準備済みトランザクションの XID を返すため、XID が属するデータベースを判断する方法がありません。JBoss EAP で複数のデータソースを同じデータベースに定義すると、in-doubt トランザクションリカバリーが誤ったアカウントで実行される可能性があります。この場合、リカバリーに失敗します。

Oracle

一部のユーザー認証情報で設定されたデータソースを使用してリカバリーマネージャーがリカバリーを呼び出すと、JDBC ドライバーはデータベースインスタンスのすべてのユーザーに属する XID を返します。JDBC ドライバーは他のユーザーに属する XID をリカバリーしようとするため、例外 ORA-24774: cannot switch to specified transaction が発生します。

この問題を回避するには、リカバリーデータソース設定で認証情報が使用されるユーザーに FORCE ANY TRANSACTION 権限を付与します。特権の設定に関する詳細は、Manually overriding in-doubt transactions を参照してください。

Microsoft SQL Server

2 フェーズコミット (2PC) のコミットフェーズ中にネットワークの障害が発生すると、JDBC ドライバーによって XAER_RMERR XAException エラーコードが返されます。このエラーは、トランザクションマネージャーでリカバリー不可能な重大なイベントが発生したことを示しますが、トランザクションはデータベース側で in-doubt 状態を維持し、ネットワーク接続の回復後に簡単に修正できます。適切な戻りコードは XAER_RMFAIL または XAER_RETRY になります。誤ったエラーコードにより、トランザクションが JBoss EAP 側で Heuristic 状態のままになり、データベースでロックが保持されるため、手動の介入が必要になります。詳細は Microsoft SQL Server の問題レポート を参照してください。

1 フェーズコミットの最適化が使用されたときに接続の障害が発生した場合、JDBC ドライバーは XAER_RMERR を返しますが、適切な戻りコードは XAER_RMFAIL になります。そのため、1 フェーズコミット中にデータベースがデータをコミットし、同時に接続が切断されると、クライアントにはトラザクションがロールバックされたと伝えられるため、データの不整合が発生する場合があります。

IBM DB2
1 フェーズコミット中に接続の障害が発生した場合、JDBC ドライバーは XAER_RMERR を返しますが、適切な戻りコードは XAER_RMFAIL です。そのため、1 フェーズコミット中にデータベースがデータをコミットし、同時に接続が切断されると、クライアントにはトラザクションがロールバックされたと伝えられるため、データの不整合が発生する場合があります。
Sybase

2 フェーズコミット (2PC) のコミットフェーズ中にネットワークの障害が発生すると、JDBC ドライバーによって XAER_RMERR XAException エラーコードが返されます。このエラーは、トランザクションマネージャーでリカバリー不可能な重大なイベントが発生したことを示しますが、トランザクションはデータベース側で in-doubt 状態を維持し、ネットワーク接続の回復後に簡単に修正できます。適切な戻りコードは XAER_RMFAIL または XAER_RETRY になります。誤ったエラーコードにより、トランザクションが JBoss EAP 側で Heuristic 状態のままになり、データベースでロックが保持されるため、手動の介入が必要になります。

1 フェーズコミットの最適化が使用されたときに接続の障害が発生した場合、JDBC ドライバーは XAER_RMERR を返しますが、適切な戻りコードは XAER_RMFAIL になります。そのため、1 フェーズコミット中にデータベースがデータをコミットし、同時に接続が切断されると、クライアントにはトラザクションがロールバックされたと伝えられるため、データの不整合が発生する場合があります。

Sybase トランザクションブランチが準備済み状態になる前に、Sybase 15.7 または 16 データベースへの挿入が含まれる XA トランザクションが失敗すると、XA トランザクションの繰り返しや同じプライマリーキーでの同じレコードの挿入に失敗し、エラー com.sybase.jdbc4.jdbc.SybSQLException: Attempt to insert duplicate key row が発生します。この例外は、元の終了していない Sybase トランザクションブランチがロールバックするまで発生します。

MariaDB
MariaDB は XA トランザクションを完全に処理できません。クライアントと MariaDB の接続が切断されると、トランザクションに関する情報がすべて失われます。
MariaDB Galera クラスター
MariaDB Galera クラスターでは XA トランザクションはサポートされません。

11.9. データベース接続の検証

データベースのメンテナンス、ネットワークの問題、またはその他の障害により、JBoss EAP からデータベースへの接続が失われることがあります。このような状況から回復するために、データソースのデータベース接続検証を有効にすることができます。

データベース接続の検証を設定するには、検証発生時を定義する検証タイミングメソッド、検証の実行方法を決定する検証メカニズム、および例外の処理方法を定義する例外ソーターを指定します。

  1. 検証タイミングメソッドを 1 つ 選択します。

    validate-on-match

    validate-on-match メソッドが true に設定されている場合は、データ接続が、次の手順で指定された検証メカニズムを使用して接続プールからチェックアウトされるたびに検証されます。

    接続が有効でない場合は、警告がログに書き込まれ、プール内の次の接続が取得されます。このプロセスは、有効な接続が見つかるまで続行します。プール内の各接続を繰り返し処理しない場合は、use-fast-fail オプションを使用できます。有効な接続がプールにない場合は、新しい接続が作成されます。接続の作成に失敗すると、例外が要求元アプリケーションに返されます。

    background-validation

    background-validation メソッドを true に設定すると、使用前にバックグラウンドスレッドで接続が周期的に検証されます。検証の頻度は background-validation-millis プロパティーによって指定されます。background-validation-millis のデフォルト値は 0 で、無効になっています。

    以下を考慮して background-validation-millis プロパティーの値を決定してください。

    • この値は idle-timeout-minutes 設定とは違う値に設定してください。
    • 値が小さいほどプールの検証頻度が高くなり、より迅速に無効な接続がプールから削除されます。
    • 値が小さいほど使用されるデータベースリソースが多くなります。値が大きいほど接続検証チェックの頻度が低くなり、データベースリソースの使用量が減りますが、無効な接続が検出されない期間が長くなります。
    注記

    次の例に示すように、これらの検証方法は同時に使用できません。

    • validate-on-matchtrue に設定されている場合には、background-validationfalse に設定する必要があります。
    • background-validationtrue に設定されている場合は、validate-on-matchfalse に設定する必要があります。

    これらの検証方法の比較マトリックスは 検証タイミング方法の比較 を参照してください。

  2. 検証メカニズムを 1 つ 選択します。

    valid-connection-checker-class-name

    検証メカニズムとして valid-connection-checker-class-name を使用することが推奨されます。これは、使用中のデータベースの接続を検証するために使用される接続チェッカークラスを指定します。JBoss EAP は以下の接続チェッカーを提供します。

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
    check-valid-connection-sql

    check-valid-connection-sql を使用して、接続の検証に使用する SQL ステートメントを提供します。

    以下は、Oracle の接続を検証するために使用する SQL ステートメントの例になります。

    select 1 from dual
    Copy to Clipboard Toggle word wrap

    以下は、MySQL または PostgreSQL の接続を検証するために使用する SQL ステートメントの例になります。

    select 1
    Copy to Clipboard Toggle word wrap
  3. 例外ソータークラス名を設定します。

    例外が致命的とマークされた場合、接続はトランザクションに参加していてもすぐに閉じられます。致命的な接続例外を適切に検出およびクリーンアップするには、例外ソータークラスオプションを使用します。データソースタイプに適切な JBoss EAP 例外ソーターを選択します。

    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter

11.10. データソースセキュリティー

データソースセキュリティーとは、データソース接続のパスワードを暗号化したり分かりにくくすることを言います。これらのパスワードはプレーンテキストで設定ファイルに保存できますが、セキュリティーリスクが高くなります。

データソースセキュリティーに使用できるメソッドは複数あります。以下には、各メソッドの例が含まれています。

セキュリティードメインを使用したデータソースの保護

セキュリティードメインを使用してデータソースをセキュアにするには、以下の手順に従います。

  1. 新しいセキュリティードメインを作成します。

    /subsystem=security/security-domain=DsRealm:add(cache-type=default)
    /subsystem=security/security-domain=DsRealm/authentication=classic:add(login-modules=[{code=ConfiguredIdentity,flag=required,module-options={userName=sa,
    principal=sa, password=sa}}])
    Copy to Clipboard Toggle word wrap

    データソースのセキュリティードメインが定義されます。以下の XML の抜粋は、CLI コマンドを呼び出した結果です。

     <security-domain name="DsRealm" cache-type="default">
      <authentication>
        <login-module code="ConfiguredIdentity" flag="required">
          <module-option name="userName" value="sa"/>
          <module-option name="principal" value="sa"/>
          <module-option name="password" value="sa"/>
        </login-module>
      </authentication>
    </security-domain>
    Copy to Clipboard Toggle word wrap
  2. 新しいデータソースを追加します。

    data-source add --name=securityDs
    --jndi-name=java:jboss/datasources/securityDs
    --connection-url=jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 --driver-name=h2
    --new-connection-sql="select current_user()"
    Copy to Clipboard Toggle word wrap
  3. データソースにセキュリティードメインを設定します。

    data-source --name=securityDs --security-domain=DsRealm
    Copy to Clipboard Toggle word wrap
  4. 変更を有効にするには、サーバーをリロードします。

    reload
    Copy to Clipboard Toggle word wrap
注記

複数のデータソースでセキュリティードメインを使用している場合は、セキュリティードメインでキャッシュを無効にします。これには、cache-type 属性の値を none に設定するか、この属性を削除します。ただし、キャッシュが必要な場合は、各データソースに個別のセキュリティードメインを使用します。

以下の XML の抜粋は、DsRealm で保護されたデータソースを示しています。

<datasources>
  <datasource jndi-name="java:jboss/datasources/securityDs"
    pool-name="securityDs">
    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
      <driver>h2</driver>
      <new-connection-sql>select current_user()</new-connection-sql>
      <security>
        <security-domain>DsRealm</security-domain>
      </security>
    </datasource>
</datasources>
Copy to Clipboard Toggle word wrap

セキュリティードメインの使用に関する詳細は、アイデンティティー管理の設定方法 を参照してください。

パスワード Vault を使用したデータソースの保護

パスワード vault を使用してデータソースを保護するには、以下の手順を使用します。

  1. ExampleDS データソースのパスワード vault を設定します。

    data-source --name=ExampleDS
    --password=${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}
    Copy to Clipboard Toggle word wrap
  2. サーバーをリロードして、変更を実装します。

    reload
    Copy to Clipboard Toggle word wrap

以下の XML セキュリティー要素は、パスワード vault でセキュア化された ExampleDS データソースに追加されます。

<security>
  <user-name>admin</user-name>
  <password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>
Copy to Clipboard Toggle word wrap

パスワード vault の使用に関する詳細は、JBoss EAP の サーバーセキュリティーの設定方法パスワード Vault の項を参照してください。

認証情報ストアを使用したデータソースの保護

認証情報ストアを使用してパスワードを提供することもできます。elytron サブシステムを使用すると、認証情報ストアを作成してパスワードをセキュアに保存し、JBoss EAP 全体でパスワードを使用することができます。認証情報ストアの作成および使用に関する詳細は、JBoss EAP の サーバーセキュリティーの設定方法クレデンシャルストア を参照してください。

認証情報ストア参照の ExampleDS への追加

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=credential-reference,value={store=exampleCS, alias=example-ds-pw})
Copy to Clipboard Toggle word wrap

認証コンテキストを使用したデータソースの保護

Elytron 認証コンテキストを使用して、ユーザー名とパスワードを提供することもできます。

以下の手順にしたがって、データソースセキュリティーの認証コンテキストを設定および使用します。

  1. passworduser-name を削除します。

    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=password)
    /subsystem=datasources/data-source=ExampleDS:undefine-attribute(name=user-name)
    Copy to Clipboard Toggle word wrap
  2. データソースの Elytron セキュリティーを有効にします。

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=elytron-enabled,value=true)
    
    reload
    Copy to Clipboard Toggle word wrap
  3. 認証情報の authentication-configuration を作成します。

    認証設定には、接続時にデータソースに使用させる認証情報が含まれています。以下の例は、認証情報ストアへの参照を使用しますが、Elytron セキュリティードメインを使用することもできます。

    /subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
    Copy to Clipboard Toggle word wrap
  4. authentication-context を作成します。

    /subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
    Copy to Clipboard Toggle word wrap
  5. 認証コンテキストを使用するよう、データソースを更新します。

    以下の例は、認証コンテキストを使用するよう、ExampleDS を更新します。

    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=authentication-context,value=exampleAuthContext)
    
    reload
    Copy to Clipboard Toggle word wrap
    注記

    authentication-context 属性が設定されておらず、elytron-enabled 属性が true に設定されている場合、JBoss EAP は認証に現在のコンテキストを使用します。

Kerberos を使用したデータソースの保護

kerberos 認証を使用してデータソースを保護にするには、以下の設定が必要です。

  • Kerberos がデータベースサーバーに設定されている。
  • JBoss EAP ホストサーバーには、データベースサーバーのキータブエントリーがある。

kerberos を使用してデータソースを保護にするには、以下を実行します。

  1. Kerberos を使用するよう JBoss EAP を設定

    /system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")
    /system-property=sun.security.krb5.debug:add(value="false")
    /system-property=sun.security.spnego.debug:add(value="false")
    Copy to Clipboard Toggle word wrap

    デバッグを行う場合は、sun.security.krb5.debugsun.security.spnego.debug の値を true に変更します。本番環境では、値を false に設定することが推奨されます。

  2. セキュリティーを設定します。

    データソースを保護にするには、レガシーセキュリティーまたは Elytron セキュリティーを使用できます。

    • レガシーのセキュリティーで kerberos を使用するには、以下の手順に従います。

      1. 期限切れのチケットをキャッシュから定期的に削除するように infinispan キャッシュを設定します。

        batch
        /subsystem=infinispan/cache-container=security:add(default-cache=auth-cache)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache:add()
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/expiration=EXPIRATION:add(lifespan=3540000,max-idle=3540000)
        /subsystem=infinispan/cache-container=security/local-cache=auth-cache/memory=object:add(size=1000)
        run-batch
        Copy to Clipboard Toggle word wrap

        以下の属性はチケットの有効期限を定義します。

        • lifespan: KDC から新しい証明書を要求する間隔 (ミリ秒単位)。KDC で定義される lifespan 条件よりも小さい値になるように、lifespan 属性の値を設定します。
        • max-idle: 未使用の場合に、有効なチケットがキャッシュから削除される間隔 (ミリ秒単位)。
        • max-entries: キャッシュに保持する kerberos チケットの最大コピー数。この値は、データソースで設定された接続の数に対応します。
      2. セキュリティードメインを作成します。

        batch
        /subsystem=security/security-domain=KerberosDatabase:add(cache-type=infinispan)
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic:add
        /subsystem=security/security-domain=KerberosDatabase/authentication=classic/login-module="KerberosDatabase-Module":add(code="org.jboss.security.negotiation.KerberosLoginModule",module="org.jboss.security.negotiation",flag=required, module-options={ "debug" => "false", "storeKey" => "false", "useKeyTab" => "true", "keyTab" => "/path/to/eap.keytab", "principal" => "PRINCIPAL@SERVER.COM", "doNotPrompt" => "true", "refreshKrb5Config" => "true", "isInitiator" => "true", "addGSSCredential" => "true", "credentialLifetime" => "-1"})
        run-batch
        Copy to Clipboard Toggle word wrap
        • SQL サーバーに Microsoft JDBC ドライバーを使用する場合は、module-options に属性と "wrapGSSCredential" ⇒ "true" の値を追加します。
        • デバッグするには、module-optionsdebug 属性の値を true に変更します。
    • Elytron で kerberos を使用するには、以下を行います。

      1. Elytron で kerberos ファクトリーを設定します。

        /subsystem=elytron/kerberos-security-factory=krbsf:add(debug=false, principal=PRINCIPAL@SERVER.COM, path=/path/to/keytab, request-lifetime=-1, obtain-kerberos-ticket=true, server=false)
        Copy to Clipboard Toggle word wrap
        • デバッグを行う場合は、属性および debug = true の値を追加します。

          対応している属性のリストは、How to Configure Server SecurityKerberos Security Factory Attributes を参照してください。

      2. kerberos ファクトリーを使用するよう認証設定を作成します。

        /subsystem=elytron/authentication-configuration=kerberos-conf:add(kerberos-security-factory=krbsf)
        Copy to Clipboard Toggle word wrap
      3. authentication-context を作成します。

        /subsystem=elytron/authentication-context=ds-context:add(match-rules=[{authentication-configuration=kerberos-conf}])
        Copy to Clipboard Toggle word wrap
  3. データソースを kerberos で保護します。

    • Elytron を使用する場合:

      1. 認証コンテキストを使用するようにデータソースを設定します。

        /subsystem=datasources/data-source=KerberosDS:add(connection-url="URL", min-pool-size=0, max-pool-size=10, jndi-name="java:jboss/datasource/KerberosDS", driver-name=<jdbc-driver>.jar, elytron-enabled=true, authentication-context=ds-context, allow-multiple-users=false, pool-prefill=false, pool-use-strict-min=false, idle-timeout-minutes=2)
        Copy to Clipboard Toggle word wrap
      2. ベンダー固有の接続プロパティーを設定します。

        /subsystem=datasources/data-source=KerberosDS/connection-properties=<connection-property-name>:add(value="(<kerberos-value>)")
        Copy to Clipboard Toggle word wrap

        例: Oracle データベースの接続プロパティー

        /subsystem=datasources/data-source=KerberosDS/connection-properties=oracle.net.authentication_services:add(value="(KERBEROS5)")
        Copy to Clipboard Toggle word wrap

      kerberos 認証を使用する場合は、データソースに以下の属性と値を使用することが推奨されます。

      • pool-prefill=false
      • pool-use-strict-min=false
      • idle-timeout-minutes

    対応している属性のリストは、データソースの属性 を参照してください。

11.11. データソースの統計

データソースの統計収集が 有効化 されている場合、データソースの ランタイム統計を表示 できます。

11.11.1. データソース統計の有効化

データソース統計は、デフォルトでは有効に なっていません。データソース統計の収集は、管理 CLI または 管理コンソール を使用して有効にできます。

11.11.1.1. 管理 CLI を使用したデータソース統計の有効化

以下の管理 CLI コマンドは、ExampleDS データソースの統計の収集を有効にします。

注記

マネージドドメインでは、このコマンドの前に /profile=PROFILE_NAME を付けます。

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=statistics-enabled,value=true)
Copy to Clipboard Toggle word wrap

変更を反映するためにサーバーをリロードします。

11.11.1.2. 管理コンソールを使用したデータソース統計の有効化

以下の手順にしたがって管理コンソールを使用し、統計の収集を有効にします。

手順

  1. スタンドアロンモードまたはドメインモードで、データソースに移動します。

    • スタンドアロンモードでは、次のナビゲーションを使用します。

      ConfigurationSubsystemsDatasources & DriversDatasources

    • ドメインモードで次のナビゲーションを使用します。

      ConfigurationProfilesfullDatasources & DriversDatasources

  2. データソースを選択し、View をクリックします。
  3. Attributes タブ下の Edit をクリックします。
  4. Statistics Enabled フィールドを ON に設定し、Save をクリックします。変更の反映にはリロードが必要であることを伝えるポップアップが表示されます。
  5. サーバーをリロードします。

    • スタンドアロンサーバーの場合は、ポップアップの Reload ボタンをクリックしてサーバーをリロードします。
    • マネージドドメインの場合は、ポップアップの Topology リンクをクリックします。Topology タブで該当するサーバーを選択し、Reload ドロップダウンオプションを選択してサーバーをリロードします。

11.11.2. データソース統計の表示

管理 CLI または 管理コンソール を使用してデータソースのランタイム統計を表示できます。

11.11.2.1. 管理 CLI を使用したデータソース統計の表示

以下の管理 CLI コマンドは、ExampleDS データソースのコア プール の統計を取得します。

注記

マネージドドメインでは、コマンドの前に /host=HOST_NAME/server=SERVER_NAME を追加します。

/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "ActiveCount" => 1,
        "AvailableCount" => 20,
        "AverageBlockingTime" => 0L,
        "AverageCreationTime" => 122L,
        "AverageGetTime" => 128L,
        "AveragePoolTime" => 0L,
        "AverageUsageTime" => 0L,
        "BlockingFailureCount" => 0,
        "CreatedCount" => 1,
        "DestroyedCount" => 0,
        "IdleCount" => 1,
        ...
}
Copy to Clipboard Toggle word wrap

以下の管理 CLI コマンドは、ExampleDS データソースの JDBC の統計を取得します。

/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "PreparedStatementCacheAccessCount" => 0L,
        "PreparedStatementCacheAddCount" => 0L,
        "PreparedStatementCacheCurrentSize" => 0,
        "PreparedStatementCacheDeleteCount" => 0L,
        "PreparedStatementCacheHitCount" => 0L,
        "PreparedStatementCacheMissCount" => 0L,
        "statistics-enabled" => true
    }
}
Copy to Clipboard Toggle word wrap
注記
Since statistics are runtime information, be sure to specify the `include-runtime=true` argument.
Copy to Clipboard Toggle word wrap

利用可能な統計の詳細リストは、データソースの統計 を参照してください。

11.11.2.2. 管理コンソールを使用したデータソース統計の表示

管理コンソールからデータソースの統計を表示するには、Runtime タブで Datasources サブシステムを選択し、データソースを選択してから 表示 をクリックします。

利用可能な統計の詳細リストは、データソースの統計 を参照してください。

11.12. データソースのチューニング

datasources サブシステムのパフォーマンスを監視および最適化するためのヒントは、JBoss EAP のパフォーマンスチューニングデータソースおよびリソースアダプターの調整 セクションを参照してください。

11.13. キャパシティーポリシー

JBoss EAP は、データソースを含む Jakarta Connectors デプロイメントのキャパシティーポリシーの定義をサポートします。キャパシティーポリシーは、キャパシティーのインクリメントと呼ばれるプールの物理接続の作成方法と、キャパシティーのデクリメントと呼ばれる破棄方法を定義します。デフォルトのポリシーは、キャパシティーのインクリメントではリクエストごとに 1 つの接続を作成し、キャパシティーのデクリメントではアイドル状態のタイムアウトがスケジュールされたときにタイムアウトするとすべての接続が破棄されるよう設定されます。

キャパシティーポリシーを設定するには、キャパシティーインクリメンタークラスかキャパシティーデクリメンタークラスのいずれか、両方を指定する必要があります。

例: キャパシティーポリシーの定義

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer")

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-class, value="org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer")
Copy to Clipboard Toggle word wrap

指定したキャパシティーインクリメンターまたはデクリメンタークラスにプロパティーを設定することもできます。

例: キャパシティーポリシーのプロパティー設定

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-incrementer-properties.size, value=2)

/subsystem=datasources/data-source=ExampleDS:write-attribute(name=capacity-decrementer-properties.size, value=2)
Copy to Clipboard Toggle word wrap

MaxPoolSize インクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.MaxPoolSizeIncrementer

MaxPoolSize インクリメンターポリシーは、リクエストごとにプールを最大サイズまでインクリメントします。このポリシーは、常時利用できる接続を最大数維持したい場合に便利です。

Size インクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.SizeIncrementer

Size インクリメンターポリシーは、リクエストごとにプールを指定の接続数までインクリメントします。このポリシーは、次のリクエストにも接続が必要であることを予想する場合に追加の接続数でインクリメントしたい場合に便利です。

Expand
表11.3 Size ポリシープロパティー
名前説明

Size

作成される接続数

注記

これはデフォルトのインクリメントポリシーで、size の値は 1 になります。

Watermark インクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer

Watermark インクリメンターポリシーは、リクエストごとにプールを指定の接続数までインクリメントします。このポリシーは、常時プールに指定数の接続を維持したい場合に便利です。

Expand
表11.4 Watermark ポリシープロパティー
名前説明

Watermark

接続数のウォーターマークレベル

MinPoolSize デクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer

MinPoolSize デクリメンターポリシーは、リクエストごとにのプールを最小サイズまでデクリメントします。このポリシーは、各アイドルタイムアウトリクエストの後に接続の数を制限したい場合に便利です。プールは先入れ先出し (FIFO) で操作します。

Size デクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer

Size デクリメンターポリシーは、アイドルタイムアウトリクエストごとにプールを指定の接続数までデクリメントします。

Expand
表11.5 Size ポリシープロパティー
名前説明

Size

破棄されるべき接続の数

このポリシーは、プールの使用度が徐々に減少することが予想されるためアイドルタイムアウトリクエストごとの追加接続数をデクリメントしたい場合に便利です。

プールは先入れ先出し (FIFO) で操作します。

TimedOut デクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer

TimedOut デクリメンターポリシーは、アイドルタイムアウトリクエストごとにタイムアウトした接続をすべてプールから削除します。プールは先入れ後出し (FILO) で操作します。

注記

このポリシーはデフォルトのデクリメントポリシーです。

TimedOut/FIFO デクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutFIFODecrementer

TimedOutFIFO デクリメンターポリシーは、アイドルタイムアウトリクエストごとにタイムアウトした接続をすべてプールから削除します。プールは先入れ先出し (FIFO) で操作します。

Watermark デクリメンターポリシー

クラス名: org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer

Watermark デクリメンターポリシーは、アイドルタイムアウトリクエストごとにプールを指定の接続数までデクリメントします。このポリシーは、常時プールに指定数の接続を維持したい場合に便利です。プールは先入れ先出し (FIFO) で操作します。

Expand
表11.6 Watermark ポリシープロパティー
名前説明

Watermark

接続数のウォーターマークレベル

11.14. エンリストメントトレース

XAResource インスタンスのエンリストメント中に発生するエラーを特定できるようにするために、エンリストメントトレースを記録することができます。エンリストメントトレースが有効である場合、必要時に正確なスタックトレースを作成できるように jca サブシステムはプール操作ごとに例外オブジェクトを作成しますが、これにはパフォーマンスのオーバーヘッドが発生します。

JBoss EAP 7.1 より、エンリストメントトレースはデフォルトで無効になっています。管理 CLI を使用してデータソースのエンリストメントトレースを有効にするには、enlistment-trace 属性を true に設定します。

非 XA データソースのエンリストメントトレースの有効化

data-source --name=DATASOURCE_NAME --enlistment-trace=true
Copy to Clipboard Toggle word wrap

XA データソースのエンリストメントトレースの有効化

xa-data-source --name=XA_DATASOURCE_NAME --enlistment-trace=true
Copy to Clipboard Toggle word wrap

警告

エンリストメントトレースを有効にするとパフォーマンスに影響することがあります。

11.15. データソース設定例

11.15.1. MySQL データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる MySQL データソースの設定例になります。

例: MySQL データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
    <connection-url>jdbc:mysql://localhost:3306/jbossdb</connection-url>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: MySQL JDBC ドライバー module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-j-8.0.33.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. MySQL JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.mysql --resources=/path/to/mysql-connector-j-8.0.33.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. MySQL JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
    Copy to Clipboard Toggle word wrap
  3. MySQL データソースを追加します。

    data-source add --name=MySqlDS --jndi-name=java:jboss/MySqlDS --driver-name=mysql --connection-url=jdbc:mysql://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.2. MySQL XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる MySQL XA データソースの設定例になります。

例: MySQL XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/MySqlXADS" pool-name="MySqlXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mysqldb
    </xa-datasource-property>
    <driver>mysql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mysql" module="com.mysql">
      <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
      <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: MySQL JDBC ドライバー module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-j-8.0.33.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. MySQL JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.mysql --resources=/path/to/mysql-connector-j-8.0.33.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. MySQL JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource, driver-class-name=com.mysql.cj.jdbc.Driver)
    Copy to Clipboard Toggle word wrap
  3. MySQL XA データソースを追加します。

    xa-data-source add --name=MySqlXADS --jndi-name=java:jboss/MySqlXADS --driver-name=mysql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mysqldb"}
    Copy to Clipboard Toggle word wrap

11.15.3. PostgreSQL データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる PostgreSQL データソースの設定例になります。

例: PostgreSQL データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
    <connection-url>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: PostgreSQL JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap

上記の例で、42.x.y をドライバーバージョン番号に置き換えてください。

管理 CLI コマンドの例

以下の CLI コマンドを使用して、PostgreSQL JDBC ドライバーおよび PostgreSQL データソースを JDBC API に追加できます。

  1. PostgreSQL JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap

    上記の例で、42.x.y をドライバーバージョン番号に置き換えてください。

    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. PostgreSQL JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
    Copy to Clipboard Toggle word wrap
  3. PostgreSQL データソースを追加します。

    data-source add --name=PostgresDS --jndi-name=java:jboss/PostgresDS --driver-name=postgresql --connection-url=jdbc:postgresql://localhost:5432/postgresdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.4. PostgreSQL XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる PostgreSQL XA データソースの設定例になります。

例: PostgreSQL XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/PostgresXADS" pool-name="PostgresXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      5432
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      postgresdb
    </xa-datasource-property>
    <driver>postgresql</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="postgresql" module="com.postgresql">
      <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: PostgreSQL JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.postgresql">
  <resources>
    <resource-root path="postgresql-42.x.y.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap

上記の例で、42.x.y をドライバーバージョン番号に置き換えてください。

管理 CLI コマンドの例

以下の CLI コマンドを使用して、PostgreSQL JDBC ドライバーおよび PostgreSQL データソースを JDBC API に追加できます。

  1. PostgreSQL JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.postgresql --resources=/path/to/postgresql-42.x.y.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap

    上記の例で、42.x.y をドライバーバージョン番号に置き換えてください。

    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. PostgreSQL JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql,driver-module-name=com.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
    Copy to Clipboard Toggle word wrap
  3. PostgreSQL XA データソースを追加します。

    xa-data-source add --name=PostgresXADS --jndi-name=java:jboss/PostgresXADS --driver-name=postgresql --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","PortNumber"=>"5432","DatabaseName"=>"postgresdb"}
    Copy to Clipboard Toggle word wrap

11.15.5. Oracle データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる Oracle データソースの設定例になります。

例: Oracle データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@localhost:1521:XE</connection-url>
    <driver>oracle</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Oracle JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Oracle JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Oracle JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Oracle データソースを追加します。

    data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url=jdbc:oracle:thin:@localhost:1521:XE --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.6. Oracle XA データソースの例

重要

Oracle XA データソースにアクセスするユーザーは、以下の設定を適用しないと XA リカバリーが適切に操作しません。値 user は、JBoss EAP から Oracle に接続するために定義されたユーザーです。

  • GRANT SELECT ON sys.dba_pending_transactions TO user;
  • GRANT SELECT ON sys.pending_trans$ TO user;
  • GRANT SELECT ON sys.dba_2pc_pending TO user;
  • GRANT EXECUTE ON sys.dbms_xa TO user;

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる Oracle XA データソースの設定例になります。

例: Oracle XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS">
    <xa-datasource-property name="URL">
      jdbc:oracle:thin:@oracleHostName:1521:orcl
    </xa-datasource-property>
    <driver>oracle</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Oracle JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Oracle JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Oracle JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Oracle XA データソースを追加します。

    xa-data-source add --name=OracleXADS --jndi-name=java:jboss/OracleXADS --driver-name=oracle --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter --same-rm-override=false --xa-datasource-properties={"URL"=>"jdbc:oracle:thin:@oracleHostName:1521:orcl"}
    Copy to Clipboard Toggle word wrap

11.15.7. Oracle RAC データソースの例

これは、接続情報、基本的なセキュリティー、および検証オプションを使用した Real Application Cluster (RAC) データソース設定の例です。

例: Oracle RAC データソースの設定

<datasources>
  <datasource jndi-name="java:jboss/OracleDS" pool-name="OracleDS">
    <connection-url>jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))</connection-url>
    <driver>oracle</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
        <validate-on-match>true</validate-on-match>
        <background-validation>false</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
        <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap

例: Oracle JDBC ドライバーの module.xml ファイル

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap

管理 CLI コマンドの例

この設定例を実現するには、以下の管理 CLI コマンドを使用します。

  1. Oracle JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
  2. Oracle JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Oracle RAC データソースを追加します。

    data-source add --name=OracleDS --jndi-name=java:jboss/OracleDS --driver-name=oracle --connection-url="jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))" --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.8. Oracle RAC XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる RAC データソースの設定例になります。

例: Oracle RAC XA データソース設定

<datasources>
  <xa-datasource jndi-name="java:jboss/OracleXADS" pool-name="OracleXADS">
    <xa-datasource-property name="URL">
      jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))
    </xa-datasource-property>
    <driver>oracle</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="oracle" module="com.oracle">
      <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap

例: Oracle JDBC ドライバーの module.xml ファイル

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.oracle">
    <resources>
        <resource-root path="ojdbc7.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap

管理 CLI コマンドの例

この設定例を実現するには、以下の管理 CLI コマンドを使用します。

  1. Oracle JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.oracle --resources=/path/to/ojdbc7.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
  2. Oracle JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=oracle:add(driver-name=oracle,driver-module-name=com.oracle,driver-xa-datasource-class-name=oracle.jdbc.xa.client.OracleXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Oracle RAC XA データソースを追加します。

    xa-data-source add --name=OracleXADS --jndi-name=java:jboss/OracleXADS --driver-name=oracle --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter --same-rm-override=false --xa-datasource-properties={"URL"=>"jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521))"}
    Copy to Clipboard Toggle word wrap

11.15.9. Microsoft SQL Server データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる Microsoft SQL Server データソースの設定例になります。

例: Microsoft SQL Server データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/MSSQLDS" pool-name="MSSQLDS">
    <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url>
    <driver>sqlserver</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Microsoft SQL Server JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc42.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
    <module name="jakarta.xml.bind.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Microsoft SQL Server の JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,jakarta.xml.bind.api,wildflyee.api,java.se
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Microsoft SQL Server の JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Microsoft SQL Server データソースを追加します。

    data-source add --name=MSSQLDS --jndi-name=java:jboss/MSSQLDS --driver-name=sqlserver --connection-url=jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.10. Microsoft SQL Server XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる Microsoft SQL Server XA データソースの設定例になります。

例: Microsoft SQL Server XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/MSSQLXADS" pool-name="MSSQLXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mssqldb
    </xa-datasource-property>
    <xa-datasource-property name="SelectMethod">
      cursor
    </xa-datasource-property>
    <driver>sqlserver</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
      <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Microsoft SQL Server JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.microsoft">
  <resources>
    <resource-root path="sqljdbc42.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
    <module name="jakarta.xml.bind.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Microsoft SQL Server の JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.microsoft --resources=/path/to/sqljdbc42.jar --dependencies=java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,jakarta.xml.bind.api,wildflyee.api,java.se
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Microsoft SQL Server の JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=sqlserver:add(driver-name=sqlserver,driver-module-name=com.microsoft,driver-xa-datasource-class-name=com.microsoft.sqlserver.jdbc.SQLServerXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Microsoft SQL Server XA データソースを追加します。

    xa-data-source add --name=MSSQLXADS --jndi-name=java:jboss/MSSQLXADS --driver-name=sqlserver --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter --same-rm-override=false --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mssqldb","SelectMethod"=>"cursor"}
    Copy to Clipboard Toggle word wrap

11.15.11. IBM DB2 データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる IBM DB2 データソースの設定例になります。

例: IBM DB2 データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/DB2DS" pool-name="DB2DS">
    <connection-url>jdbc:db2://localhost:50000/ibmdb2db</connection-url>
    <driver>ibmdb2</driver>
    <pool>
      <min-pool-size>0</min-pool-size>
      <max-pool-size>50</max-pool-size>
    </pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
        <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: IBM DB2 JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. IBM DB2 の JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. IBM DB2 の JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
    Copy to Clipboard Toggle word wrap
  3. IBM DB2 データソースを追加します。

    data-source add --name=DB2DS --jndi-name=java:jboss/DB2DS --driver-name=ibmdb2 --connection-url=jdbc:db2://localhost:50000/ibmdb2db --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --min-pool-size=0 --max-pool-size=50
    Copy to Clipboard Toggle word wrap

11.15.12. IBM DB2 XA のデータソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる IBM DB2 XA データソースの設定例になります。

例: IBM DB2 XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/DB2XADS" pool-name="DB2XADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      ibmdb2db
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      50000
    </xa-datasource-property>
    <xa-datasource-property name="DriverType">
      4
    </xa-datasource-property>
    <driver>ibmdb2</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <recovery>
      <recover-plugin class-name="org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin">
        <config-property name="EnableIsValid">
          false
        </config-property>
        <config-property name="IsValidOverride">
          false
        </config-property>
        <config-property name="EnableClose">
          false
        </config-property>
      </recover-plugin>
    </recovery>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
        <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: IBM DB2 JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. IBM DB2 の JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.ibm --resources=/path/to/db2jcc4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. IBM DB2 の JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=ibmdb2:add(driver-name=ibmdb2,driver-module-name=com.ibm,driver-xa-datasource-class-name=com.ibm.db2.jcc.DB2XADataSource)
    Copy to Clipboard Toggle word wrap
  3. IBM DB2 XA データソースを追加します。

    xa-data-source add --name=DB2XADS --jndi-name=java:jboss/DB2XADS --driver-name=ibmdb2 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter --same-rm-override=false --recovery-plugin-class-name=org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin --recovery-plugin-properties={"EnableIsValid"=>"false","IsValidOverride"=>"false","EnableClose"=>"false"} --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"ibmdb2db","PortNumber"=>"50000","DriverType"=>"4"}
    Copy to Clipboard Toggle word wrap

11.15.13. Sybase データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる Sybase データソースの設定例になります。

例: Sybase データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/SybaseDB" pool-name="SybaseDB">
    <connection-url>jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6</connection-url>
    <driver>sybase</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Sybase JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.sybase">
    <resources>
      <resource-root path="jconn4.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Sybase JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Sybase JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=sybase:add(driver-name=sybase,driver-module-name=com.sybase,driver-xa-datasource-class-name=com.sybase.jdbc4.jdbc.SybXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Sybase データソースを追加します。

    data-source add --name=SybaseDB --jndi-name=java:jboss/SybaseDB --driver-name=sybase --connection-url=jdbc:sybase:Tds:localhost:5000/DATABASE?JCONNECT_VERSION=6 --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.14. Sybase XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる Sybase XA データソースの設定例になります。

例: Sybase XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/SybaseXADS" pool-name="SybaseXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mydatabase
    </xa-datasource-property>
    <xa-datasource-property name="PortNumber">
      4100
    </xa-datasource-property>
    <xa-datasource-property name="NetworkProtocol">
      Tds
    </xa-datasource-property>
    <driver>sybase</driver>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="sybase" module="com.sybase">
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: Sybase JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="com.sybase">
    <resources>
      <resource-root path="jconn4.jar"/>
    </resources>
    <dependencies>
      <module name="wildflyee.api"/>
      <module name="java.se"/>
      <module name="java.xml" export="true"/>
      <module name="java.xml.crypto" export="true"/>
      <module name="jdk.xml.dom" export="true"/>
      <module name="jakarta.transaction.api"/>
    </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. Sybase JDBC ドライバーをコアモジュールとして追加します。

    module add --name=com.sybase --resources=/path/to/jconn4.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. Sybase JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=sybase:add(driver-name=sybase,driver-module-name=com.sybase,driver-xa-datasource-class-name=com.sybase.jdbc4.jdbc.SybXADataSource)
    Copy to Clipboard Toggle word wrap
  3. Sybase XA データソースを追加します。

    xa-data-source add --name=SybaseXADS --jndi-name=java:jboss/SybaseXADS --driver-name=sybase --user-name=admin --password=admin --validate-on-match=true --background-validation=false --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter --same-rm-override=false --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mydatabase","PortNumber"=>"4100","NetworkProtocol"=>"Tds"}
    Copy to Clipboard Toggle word wrap

11.15.15. MariaDB データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる MariaDB データソースの設定例になります。

例: MariaDB データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/MariaDBDS" pool-name="MariaDBDS">
    <connection-url>jdbc:mariadb://localhost:3306/jbossdb</connection-url>
    <driver>mariadb</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="mariadb" module="org.mariadb">
      <driver-class>org.mariadb.jdbc.Driver</driver-class>
      <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: MariaDB JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="org.mariadb">
  <resources>
    <resource-root path="mariadb-java-client-3.3.0.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="org.slf4j"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. MariaDB JDBC ドライバーをコアモジュールとして追加します。

    module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. MariaDB JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
    Copy to Clipboard Toggle word wrap
  3. MariaDB データソースを追加します。

    data-source add --name=MariaDBDS --jndi-name=java:jboss/MariaDBDS --driver-name=mariadb --connection-url=jdbc:mariadb://localhost:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    Copy to Clipboard Toggle word wrap

11.15.16. MariaDB XA データソースの例

以下は、XA データソースプロパティー、基本のセキュリティー、およびバリデーションオプションが含まれる MariaDB XA データソースの設定例になります。

例: MariaDB XA データソースの設定
<datasources>
  <xa-datasource jndi-name="java:jboss/MariaDBXADS" pool-name="MariaDBXADS">
    <xa-datasource-property name="ServerName">
      localhost
    </xa-datasource-property>
    <xa-datasource-property name="DatabaseName">
      mariadbdb
    </xa-datasource-property>
    <driver>mariadb</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </xa-datasource>
  <drivers>
    <driver name="mariadb" module="org.mariadb">
      <driver-class>org.mariadb.jdbc.Driver</driver-class>
      <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: MariaDB JDBC ドライバーの module.xml ファイル
<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.9" name="org.mariadb">
  <resources>
    <resource-root path="mariadb-java-client-3.3.0.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="org.slf4j"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. MariaDB JDBC ドライバーをコアモジュールとして追加します。

    module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. MariaDB JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
    Copy to Clipboard Toggle word wrap
  3. MariaDB XA データソースを追加します。

    xa-data-source add --name=MariaDBXADS --jndi-name=java:jboss/MariaDBXADS --driver-name=mariadb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter --xa-datasource-properties={"ServerName"=>"localhost","DatabaseName"=>"mariadbdb"}
    Copy to Clipboard Toggle word wrap

11.15.17. MariaDB Galera Cluster データソースの例

以下は、接続情報、基本のセキュリティー、およびバリデーションオプションが含まれる MariaDB Galera Cluster データソースの設定例になります。

警告

MariaDB Galera Cluster は XA トランザクションをサポートしません。

例: MariaDB Galera Cluster データソースの設定
<datasources>
  <datasource jndi-name="java:jboss/MariaDBGaleraClusterDS" pool-name="MariaDBGaleraClusterDS">
    <connection-url>jdbc:mariadb://192.168.1.1:3306,192.168.1.2:3306/jbossdb</connection-url>
    <driver>mariadb</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
    </validation>
  </datasource>
  <drivers>
    <driver name="mariadb" module="org.mariadb">
      <driver-class>org.mariadb.jdbc.Driver</driver-class>
      <xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
Copy to Clipboard Toggle word wrap
例: MariaDB JDBC ドライバーの module.xml ファイル
<?xml version='1.0' encoding='UTF-8'?>
<module xmlns="urn:jboss:module:1.9" name="org.mariadb">
  <resources>
    <resource-root path="mariadb-java-client-3.3.0.jar"/>
  </resources>
  <dependencies>
    <module name="wildflyee.api"/>
    <module name="java.se"/>
    <module name="java.xml" export="true"/>
    <module name="java.xml.crypto" export="true"/>
    <module name="jdk.xml.dom" export="true"/>
    <module name="org.slf4j"/>
    <module name="jakarta.transaction.api"/>
  </dependencies>
</module>
Copy to Clipboard Toggle word wrap
管理 CLI コマンドの例

以下の管理 CLI コマンドを使用すると、この設定例を実現できます。

  1. MariaDB JDBC ドライバーをコアモジュールとして追加します。

    module add --name=org.mariadb --resources=/path/to/mariadb-java-client-3.3.0.jar --dependencies=wildflyee.api,java.se,java.xml,java.xml.crypto,jdk.xml.dom,jakarta.transaction.api,org.slf4j
    Copy to Clipboard Toggle word wrap
    重要

    module 管理 CLI コマンドを使用したモジュールの追加および削除は、テクノロジープレビューとしてのみ提供されます。このコマンドは、マネージドドメインでの使用や、リモートによる管理 CLI への接続時には適していません。本番環境ではモジュールを手作業で 追加 および 削除 してください。

    テクノロジープレビュー機能は、Red Hat の実稼働環境のサービスレベルアグリーメント (SLA) ではサポートされず、機能的に完全ではないことがあるため、Red Hat では実稼働環境での使用を推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。

    テクノロジープレビュー機能のサポート範囲は、Red Hat カスタマーポータルの テクノロジープレビュー機能のサポート範囲 を参照してください。

  2. MariaDB JDBC ドライバーを登録します。

    /subsystem=datasources/jdbc-driver=mariadb:add(driver-name=mariadb,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource, driver-class-name=org.mariadb.jdbc.Driver)
    Copy to Clipboard Toggle word wrap
  3. MariaDB Galera Cluster データソースを追加します。

    data-source add --name=MariaDBGaleraClusterDS --jndi-name=java:jboss/MariaDBGaleraClusterDS --driver-name=mariadb --connection-url=jdbc:mariadb://192.168.1.1:3306,192.168.1.2:3306/jbossdb --user-name=admin --password=admin --validate-on-match=true --background-validation=false --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    Copy to Clipboard Toggle word wrap

第12章 Transactions サブシステムの設定

12.1. Transactions サブシステムの設定

金融取引、注文管理、その他の重要なワークフローを処理するエンタープライズアプリケーションを管理する場合は、操作の信頼性とデータの一貫性を確保する必要があります。JBoss EAP のトランザクションサブシステムを使用すると、Transaction Manager™ を完全に制御できるため、タイムアウト値の設定、トランザクションロギングの有効化、統計の収集が可能になります。アプリケーションが複数のシステムで実行され、トランザクションの伝播が必要な場合は、JBoss Remoting または JTS の少なくとも 1 つを有効にする必要があります。

JBoss EAP は、Narayana トランザクションマネージャーを使用してトランザクションを効率的に処理します。Jakarta Transactions、JTS、Web サービストランザクションなどの業界標準プロトコルをサポートしています。データベースの更新、メッセージの送信、分散サービスの調整などを行う場合でも、トランザクションサブシステムによって一貫性、信頼性、回復力が確保されます。

注記

このリンクをクリックすると、JBoss EAP 7.4 のトランザクション管理ガイドに移動します。現在、Red Hat JBoss Enterprise Application Platform 8.0 のドキュメントは更新中です。新しいドキュメントが完成すると、このリンクは更新されます。

第13章 ORB 設定

本章では、Java Transaction Service (JTS)をサポートするように Object Request Broker (ORB)を設定し、JBoss EAP で SSL/TLS による通信をセキュアにする方法を説明します。

13.1. Common Object Request Broker Architecture (CORBA)について

Common Object Request Broker Architecture (CORBA)は、オブジェクト要求ブローカー(ORB)と呼ばれるコンポーネントを介して、アプリケーションとサービスが異なるプログラミング言語やプラットフォーム間で対話できるようにする標準です。JBoss EAP は、Open JDK ORB コンポーネントを用いて ORB インスタンスを提供します。

ORB は JTS トランザクションに対して内部的に使用され、ユーザー独自のアプリケーションが使用することもできます。

注記

Object Transaction Service (OTS) は、CORBA の一部を形成するクロスプラットフォームサービスです。OTS 仕様は、オブジェクト管理グループにより維持されます。JTS はトランザクションマネージャーの構築の仕様で、JTS は OTS 仕様に基づいて設計されました。

13.2. 管理 CLI と管理コンソールを使用した JTS の ORB の設定

ここでは、JBoss EAP で管理 CLI と管理コンソールの両方を使用して Java Transaction Service (JTS)の Object Request Broker (ORB)を設定する手順を説明します。ORB を設定すると、分散環境のトランザクション機能が堅牢になります。

前提条件

  • JBoss EAP がインストールされている。
  • 管理 CLI と管理コンソールに管理者権限があります。
手順

この手順は、スタンドアロンモードまたはドメインモードで使用できます。スタンドアロンモードを使用する場合は、profile=full 接頭辞を使用せず、standalone-full.xml 設定を使用してください。

  1. セキュリティーインターセプターを有効にし ます。

    管理 CLI を使用して、以下のコマンドを実行して security 属性を identity に設定します。

    /profile=full/subsystem=iiop-openjdk:write-attribute(name=security,value=identity)
    Copy to Clipboard Toggle word wrap

    または、管理コンソールを使用します。

    • Configuration タブに移動します。
    • SubsystemsIIOP (OpenJDK)View の順に選択します。
    • Edit をクリックし、必要に応じて属性を変更し、Save をクリックします。
  2. IIOP サブシステムでトランザクションを有効にし ます。

    JTS に対して ORB を有効にするには、CLI を使用して transactions 属性を full に設定します。

    /profile=full/subsystem=iiop-openjdk:write-attribute(name=transactions,value=full)
    Copy to Clipboard Toggle word wrap

    管理コンソールで以下を行います。

    • SubsystemsIIOP (OpenJDK)View へ移動します。
    • Edit をクリックし、必要に応じて属性を変更し、Save をクリックします。
  3. Transactions サブシステムで JTS を有効にし ます。

    CLI を使用して、jts 属性を true に設定します。

    /profile=full/subsystem=transactions:write-attribute(name=jts,value=true)
    Copy to Clipboard Toggle word wrap

    管理コンソールで以下を行います。

    • SubsystemsTransactionsView の順に移動します。
    • Edit をクリックし、必要に応じて属性を変更し、Save をクリックします。
  4. サーバーを再起動し ます。

    JTS をアクティブにするには、簡単なリロードでは不十分なため、サーバーを完全に再起動する必要があります。

検証

  • 属性設定を読み、CLI を使用して設定を確認します。

    /profile=full/subsystem=iiop-openjdk:read-resource
    Copy to Clipboard Toggle word wrap
  • または、サーバーの再起動後に管理コンソールで更新された属性を確認します。

13.3. SSL/TLS を使用するための IIOP の設定

iiop-openjdk サブシステムを設定すると、クライアントとサーバー間のセキュアな通信に SSL/TLS を使用することができます。以下の手順は、IIOP サブシステムに SSL/TLS を設定する方法の概要を説明します。

前提条件

  • JBoss EAP がインストールされている。
  • 管理 CLI または管理コンソールに管理者権限でアクセスできます。

手順

  1. server-ssl-context を作成します。

    /subsystem=elytron/server-ssl-context=<server-ssl-context_name>:add(key-manager=<key-manager_name>, protocols=<list_of_protocols>)
    Copy to Clipboard Toggle word wrap

    server-ssl-context の作成例は、最新の JBoss EAP セキュリティーガイド(JBoss EAP での SSL/TLS の設定 ガイド)を参照してください。

    iiop-openjdk サブシステムで SSL/TLS を使用するには、server-ssl-context を定義する必要があります。JBoss EAP は、サーバーへの SSL/TLS 接続を確立するときに、server-ssl-context によって提供される設定を使用します。server-ssl-context 属性の詳細は、JBoss EAP の SSL/TLS の設定 を参照してください

  2. client-ssl-context を作成します。以下に例を示します。

    /subsystem=elytron/client-ssl-context=exampleCSC:add(key-manager=applicationKM, protocols=["TLSv1.2"])
    Copy to Clipboard Toggle word wrap

    iiop-openjdk サブシステムで SSL/TLS を使用するには、client-ssl-context を定義する必要があります。JBoss EAP は、クライアントへの SSL/TLS 接続を確立するときに、client-ssl-context によって提供される設定を使用します。client-ssl-context 作成の詳細は サーバーセキュリティーの設定方法 ガイドの client-ssl-context の使用 を参照してください。

    注記

    このリンクから、JBoss EAP 7.4 の JBoss EAP セキュリティーガイドを参照することに注意してください。現在、Red Hat JBoss Enterprise Application Platform 8.0 のドキュメントは更新中です。新しいドキュメントが完成すると、このリンクは更新されます。

  3. client-ssl-context および server-ssl-context を使用するよう、iiop-openjdk サブシステムを設定します。

    例: client-ssl-context および server-ssl-context の設定

    batch
    
    /subsystem=iiop-openjdk:write-attribute(name=client-ssl-context,value=iiopClientSSC)
    
    /subsystem=iiop-openjdk:write-attribute(name=server-ssl-context,value=iiopServerSSC)
    
    run-batch
    
    reload
    Copy to Clipboard Toggle word wrap

  4. iiop-openjdk サブシステムを接続先および接続元とする接続の設定

    以下の属性を調整すると、iiop-openjdk サブシステムを接続先および接続元とする接続を確立するときに SSL/TLS 接続を要求するかどうかを示すことができます。

    • iiop-openjdk サブシステムで SSL のサポートを有効にするには、support-ssltrue に設定します。デフォルトは false です。
    • iiop-openjdk サブシステムからの SSL/TLS 接続を要求するには、client-requires-ssltrue に設定します。デフォルトは false です。
    • iiop-openjdk サブシステムへの SSL/TLS 接続を要求するには、server-requires-ssltrue に設定します。デフォルトは false です。これを true に設定すると、非 SSL IIOP ソケットへの接続をブロックすることに注意してください。
    • socket-binding を調整するには、ssl-socket-binding を希望のバインディングに設定します。デフォルトは iiop-ssl です。

    例: IIOP を接続先および接続元とする SSL/TLS 接続の設定

    /subsystem=iiop-openjdk:write-attribute(name=support-ssl,value=true)
    
    /subsystem=iiop-openjdk:write-attribute(name=client-requires-ssl,value=true)
    
    /subsystem=iiop-openjdk:write-attribute(name=server-requires-ssl,value=true)
    
    /subsystem=iiop-openjdk:write-attribute(name=ssl-socket-binding,value=iiop-ssl)
    
    reload
    Copy to Clipboard Toggle word wrap

第14章 Jakarta Connectors 管理

14.1. Jakarta Connectors について

Jakarta Connectors は、Jakarta EE システムが外部の異種 Enterprise Information Systems (EIS) とやり取りするための標準アーキテクチャーを定義します。EIS の例として、エンタープライズリソースプランニング (ERP) システム、メインフレームトランザクション処理 (TP)、データベース、メッセージングシステムなどが挙げられます。リソースアダプター は、Jakarta Connectors アーキテクチャーを実装するコンポーネントの 1 つです。

Jakarta Connectors 1.7 は以下を管理するための機能を提供します。

  • 接続
  • トランザクション
  • セキュリティー
  • ライフサイクル
  • ワークインスタンス
  • トランザクションインフロー
  • メッセージインフロー

14.2. リソースアダプター

リソースアダプターは、Jakarta Connectors 仕様を使用して Jakarta EE アプリケーションとエンタープライズ情報システム (EIS) との間の通信を提供するデプロイ可能な Jakarta EE コンポーネントです。EIS ベンダーの製品と Jakarta EE アプリケーションの統合を容易にするため、リソースアダプターは通常 EIS ベンダーによって提供されます。

エンタープライズ情報システムは、組織内における他のあらゆるソフトウェアシステムのことです。例としては、エンタープライズリソースプランニング (ERP) システム、データベースシステム、メールサーバー、プロプライエタリーのメッセージングシステムなどがあります。

リソースアダプターは、JBoss EAP にデプロイできる Resource Adapter Archive (RAR) ファイルでパッケージ化されます。また、RAR ファイルは、Enterprise Archive (EAR) デプロイメントにも含めることができます。

リソースアダプター自体は、IronJacamar プロジェクトによって提供される resource-adapters サブシステム内に定義されます。

14.3. jca サブシステムの設定

jca サブシステムは、Jakarta Connectors およびリソースアダプターデプロイメントの一般的な設定を制御します。管理コンソールまたは管理 CLI を使用して jca サブシステムを設定できます。

設定する主な jca サブシステム要素は次のとおりです。

14.3.1. 管理コンソールでの jca サブシステムの設定

管理コンソールから ConfigurationSubsystemsJCA に移動し、View をクリックすることで、jca サブシステムを設定できます。次に、該当するタブを選択します。

  • Configuration

    キャッシュ接続マネージャー、アーカイブバリデーション、および Bean バリデーションの設定が含まれています。設定を変更するには、タブを開き、Edit リンクをクリックします。

  • Bootstrap Context

    設定済みのブートストラップコンテキストのリストが含まれています。新しいブートストラップコンテキストオブジェクトを追加、削除、および設定できます。各ブートストラップコンテキストをワークマネージャーに割り当てる必要があります。

  • Workmanager

    設定済みのワークマネージャーのリストが含まれています。新しいワークマネージャーを追加および削除でき、スレッドプールをここで設定できます。各ワークマネージャーは短時間実行されるスレッドプールを 1 つ持つことができ、任意で長時間実行されるスレッドプールを 1 つ持つことができます。

スレッドプール属性を設定するには、選択したワークマネージャーの Thread Pools をクリックします。

14.3.2. 管理 CLI での jca サブシステム設定

この手順に従って、管理 CLI を使用して jca サブシステムを設定できます。

手順

  1. 管理 CLI を使用して jca サブシステムを設定します。
/subsystem=jca
Copy to Clipboard Toggle word wrap
  1. マネージドドメインでは、コマンドの前に以下を追加する必要があります。

    /profile=PROFILE_NAME
    Copy to Clipboard Toggle word wrap
注記

以下のセクションの表には、管理モデルで使用される属性名を示しています (管理 CLI を使用している場合など)。XML で使用される名前は管理モデルの名前と異なる場合があるため、XML で使用される要素を EAP_HOME/docs/schema/wildfly-jca_5_0.xsd のスキーマ定義ファイルで確認してください。

14.3.3. アーカイブバリデーション

デプロイメントユニットでアーカイブバリデーションを実行するかどうかを決定します。以下の表はアーカイブバリデーションに設定できる属性を表しています。

Expand
表14.1 アーカイブバリデーションの属性
属性デフォルト値説明

enabled

true

アーカイブバリデーションが有効であるかどうかを指定します。

fail-on-error

true

アーカイブバリデーションのエラーレポートによってデプロイメントが失敗するかどうかを指定します

fail-on-warn

false

アーカイブバリデーションの警告レポートによってデプロイメントが失敗するかどうかを指定します。

アーカイブバリデーションが指定されていない場合は、アーカイブバリデーションが指定されているとみなされ、enabled 属性のデフォルトが true に設定されます。

デプロイ中のエラーメッセージの例

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl
Copy to Clipboard Toggle word wrap

14.3.4. Bean バリデーション

Bean バリデーションは、Bean バリデーションを実行するかどうかを決定します。この仕様の詳細は、Jakarta Bean Validation 仕様 を参照してください。

Expand
表14.2 Bean バリデーションの属性
属性デフォルト値説明

enabled

true

Bean バリデーションが有効であるかどうかを指定します。

Bean バリデーションが指定されていない場合は、Bean バリデーションが指定されているとみなされ、enabled 属性のデフォルトが true に設定されます。

14.3.5. ワークマネージャー

ワークマネージャーは、Jakarta Connectors サブシステム内のワークインスタンスを管理します。ワークマネージャーには次の 2 種類があります。

  • デフォルトワークマネージャー

    デフォルトのワークマネージャーおよびそのスレッドプール。

  • カスタムワークマネージャー

    カスタムワークマネージャーの定義およびそのスレッドプール。

Expand
表14.3 ワークマネージャーの属性
属性説明

name

ワークマネージャーの名前を指定します。

elytron-enabled

ワークマネージャーの Elytron セキュリティーを有効にします。

ワークマネージャーには、次の子要素もあります。

Expand
表14.4 ワークマネージャーの子要素
子要素説明

short-running-threads

標準のワークインスタンスのスレッドプール。ワークマネージャーごとに短時間実行されるスレッドプールが 1 つあります。

long-running-threads

LONG_RUNNING ヒントを設定する Jakarta Connectors 1.7 Work インスタンスのスレッドプール。各ワークマネージャーはオプションの長期スレッドプールを 1 つ持てます。

ワークマネージャーのスレッドプールに設定できる属性は下表のとおりです。

Expand
表14.5 スレッドプールの属性
属性説明

allow-core-timeout

コアスレッドがタイムアウトするかどうかを決定するブール値の設定。デフォルト値は false です。

core-threads

コアスレッドプールのサイズ。スレッドプールの最大サイズ以下である必要があります。

handoff-executor

タスクが受け入れられない場合、タスクを委譲するエグゼキューター。指定されていない場合、受け入れられないタスクは警告なしに破棄されます。

keepalive-time

ワーク実行後にスレッドプールが保持される期間を指定します。

max-threads

スレッドプールの最大サイズ。

name

スレッドプールの名前を指定します。

queue-length

キューの最大長。

thread-factory

スレッドファクトリーへの参照。

14.3.6. 分散ワークマネージャー

分散ワークマネージャーは、別のワークマネージャーインスタンスでワークの実行スケジュールを変更できるワークマネージャーです。

以下の管理 CLI コマンドの例は、分散ワークマネージャーを設定します。スタンドアロンサーバーの standalone-ha.xml または standalone-full-ha.xml 設定ファイルなど、高可用性を提供する設定を使用する必要があることに注意してください。

例: 分散ワークマネージャーの設定

batch
/subsystem=jca/distributed-workmanager=myDistWorkMgr:add(name=myDistWorkMgr)
/subsystem=jca/distributed-workmanager=myDistWorkMgr/short-running-threads=myDistWorkMgr:add(queue-length=10,max-threads=10)
/subsystem=jca/bootstrap-context=myCustomContext:add(name=myCustomContext,workmanager=myDistWorkMgr)
run-batch
Copy to Clipboard Toggle word wrap

注記

short-running-threads 要素の名前は distributed-workmanager 要素の名前と同じである必要があります。

以下の表は、分散ワークマネージャーに設定できる属性を表しています。

Expand
表14.6 分散ワークマネージャーの属性
属性説明

elytron-enabled

ワークマネージャーの Elytron セキュリティーを有効にします。

name

分散ワークマネージャーの名前。

policy

ワークインスタンスをいつ再分散するかを決定します。使用できる値は次のとおりです。

  • NEVER - ワークインスタンスを別のノードに分散しません。
  • ALWAYS - 常にワークインスタンスを別のノードに分散します。
  • WATERMARK - 現在のノードで使用できる空きのワーカースレッドの数に応じてワーカーインスタンスを別のノードに分散します。

policy-options

ポリシーのキーバリューペアのオプションリスト。WATERMARK ポリシーを使用する場合、watermark ポリシーオプションを使用して、ワークが分散される空きスレッドの数を指定します。以下に例を示します。

/subsystem=jca/distributed-workmanager=myDistWorkMgr:write-attribute(name=policy-options,value={watermark=3})
Copy to Clipboard Toggle word wrap

selector

ワークインスタンスを再分散するネットワークのノードを決定します。使用できる値は次のとおりです。

  • FIRST_AVAILABLE - リストの最初に利用できるノードを選択します。
  • PING_TIME - ping の時間が最も短いノードを選択します。
  • MAX_FREE_THREADS - 空きワーカースレッドの数が最も多いノードを選択します。

selector-options

セレクターのキーバリューペアのオプションリスト。

分散ワークマネージャーには以下の子要素もあります。

Expand
表14.7 分散ワークマネージャーの子要素
子要素説明

long-running-threads

LONG_RUNNING ヒントを設定するワークインスタンスのスレッドプール。各分散ワークマネージャーはオプションで長時間実行スレッドプールを持つことができます。

short-running-threads

標準ワークインスタンスのスレッドプール。各分散ワークマネージャーには短期間実行スレッドプールがある必要があります。

14.3.7. ブートストラップコンテキスト

カスタムのブートストラップコンテキストを定義するために使用されます。以下の表は、ブートストラップコンテキストに設定できる属性を表しています。

Expand
表14.8 ブートストラップコンテキストの属性
属性説明

name

ブートストラップコンテキストの名前を指定します。

workmanager

このコンテキストに使用するワークマネージャーの名前を指定します。

14.3.8. キャッシュ接続マネージャー

キャッシュ接続マネージャーは、接続のデバッグや、トランザクションにおける接続のレイジーエンリストメントのサポートに使用され、接続がアプリケーションによって適切に使用および解放されているかどうかを追跡します。以下の表はキャッシュ接続マネージャーに設定できる属性を表しています。

Expand
表14.9 キャッシュ接続マネージャーの属性
属性デフォルト値説明

debug

false

接続を明示的に閉じるため、障害時に警告を出力します。

error

false

接続を明示的に閉じるため、障害時に例外が発生します。

ignore-unknown-connections

false

未知の接続はキャッシュされないことを指定します。

install

false

キャッシュ接続マネージャーのバルブおよびインターセプターを有効または無効にします。

14.3.9. 管理 CLI を使用したリソースアダプターのデプロイ

管理 CLI を使用してリソースアダプターをデプロイします。

前提条件

  • 管理 CLI へのアクセス。

手順

  1. リソースアダプターをスタンドアロンサーバーにデプロイします。

       ----
       deploy /path/to/resource-adapter.rar
       ----
    Copy to Clipboard Toggle word wrap
  2. マネージドドメイン内のすべてのサーバーグループにリソースアダプターをデプロイします。

       ----
       deploy /path/to/resource-adapter.rar --all-server-groups
       ----
    Copy to Clipboard Toggle word wrap

14.3.10. 管理コンソールを使用したリソースアダプターのデプロイ

管理コンソールを使用してリソースアダプターをデプロイします。

前提条件

  • 管理コンソールへのアクセス。

手順

  1. 管理コンソールにログインします。
  2. Deployments タブに移動します。
  3. Add (+) ボタンをクリックします。

    • マネージドドメインでは最初に Content Repository を選択する必要があります。
  4. Upload Deployment オプションを選択します。
  5. リソースアダプターのアーカイブを参照して、Next をクリックします。
  6. アップロードを確認して、Finish をクリックします。
  7. マネージドドメインで、デプロイメントを該当するサーバーグループにデプロイし、デプロイメントを有効にします。

14.3.11. デプロイメントスキャナーを使用したリソースアダプターのデプロイ

スタンドアロンサーバーでデプロイメントスキャナーを使用してリソースアダプターをデプロイします。

前提条件

  • サーバーのファイルシステムへのアクセス。

手順

  • リソースアダプターを手作業でスタンドアロンサーバーにデプロイするには、リソースアダプターアーカイブをサーバーデプロイメントディレクトリー (例: EAP_HOME/standalone/deployments/) にコピーします。これにより、デプロイメントスキャナーによって検出され、デプロイされます。
注記

このオプションはマネージドドメインでは使用できません。管理コンソールまたは管理 CLI を使用してリソースアダプターをサーバーグループにデプロイする必要があります。

14.4. リソースアダプターの設定

管理インターフェイスを使用してリソースアダプターを設定できます。以下の例は、管理 CLI を使用してリソースアダプターを設定する方法を示しています。サポートされるプロパティーやその他の重要な情報は、リソースアダプターベンダーのマニュアルを参照してください。

14.4.1. リソースアダプター設定の追加

管理 CLI を使用してリソースアダプター設定を追加します。

前提条件

  • 管理 CLI へのアクセス。

手順

  1. リソースアダプター設定の追加:

    /subsystem=resource-adapters/resource-adapter=eis.rar:add(archive=eis.rar, transaction-support=XATransaction)
    Copy to Clipboard Toggle word wrap

14.4.2. リソースアダプターの設定

リソースアダプター設定は、アプリケーションサーバーと外部システム間の接続を管理し、統合とパフォーマンスを最適化するように接続を設定します。

前提条件

  • リソースアダプター設定が追加されている。
  • 管理 CLI にアクセスできる。

手順

  1. config-properties を設定します。

    • server 設定プロパティーを追加します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=server:add(value=localhost)
           ----
      Copy to Clipboard Toggle word wrap
    • port 設定プロパティーを追加します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/config-properties=port:add(value=9000)
           ----
      Copy to Clipboard Toggle word wrap
  2. admin-objects を設定します。

    • 管理オブジェクトを追加します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName:add(class-name=com.acme.eis.ra.EISAdminObjectImpl, jndi-name=java:/eis/AcmeAdminObject)
           ----
      Copy to Clipboard Toggle word wrap
    • 管理オブジェクトの設定プロパティーを設定します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/admin-objects=aoName/config-properties=threshold:add(value=10)
           ----
      Copy to Clipboard Toggle word wrap
  3. connection-definitions を設定します。

    • 管理対象接続ファクトリーの接続定義を追加します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:add(class-name=com.acme.eis.ra.EISManagedConnectionFactory, jndi-name=java:/eis/AcmeConnectionFactory)
           ----
      Copy to Clipboard Toggle word wrap
    • 管理対象接続ファクトリーの設定プロパティーを設定します。

           ----
           /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName/config-properties=name:add(value=Acme Inc)
           ----
      Copy to Clipboard Toggle word wrap
    • エンリストメントトレースを記録するかどうかを設定します。

      • enlistment-trace 属性を true に設定して、エンリストメントトレースの記録を有効にします。

             ----
             /subsystem=resource-adapters/resource-adapter=eis.rar/connection-definitions=cfName:write-attribute(name=enlistment-trace,value=true)
             ----
        Copy to Clipboard Toggle word wrap
        警告

        エンリストメントトレースを有効にすると、トランザクションエンリストメント中のエラーを容易に追跡できますが、パフォーマンスに影響します。

14.4.3. リソースアダプターのアクティブ化

リソースアダプターを設定した後、アクティブ化します。

前提条件

  • リソースアダプターが設定されている。
  • 管理 CLI へのアクセス。

手順

  • リソースアダプターをアクティブ化します。

    ----
    /subsystem=resource-adapters/resource-adapter=eis.rar:activate
    ----
    Copy to Clipboard Toggle word wrap
注記

リソースアダプターのキャパシティーポリシーを定義することも可能です。詳細は、キャパシティーポリシー セクションを参照してください。

14.5. Elytron サブシステムを使用するためのリソースアダプターの設定

IronJacamar のリソースアダプターでは、サーバーとリソースアダプターの間で 2 種類の通信が発生します。

  • 一方の種類の通信は、サーバーがリソースアダプター接続を開くときに発生します。これは、コンテナー管理のサインオンによって保護できます。コンテナー管理のサインオンでは、接続を開くときに、プリンシパルと認証情報を含む JAAS サブジェクトをリソースアダプターに伝播する必要があります。このサインオンは Elytron に委譲できます。
  • もう一方の種類の通信は、リソースアダプターがワークマネージャーにワークを送信する際、または同じ JBoss EAP インスタンス内のエンドポイントにメッセージを配信する際に、セキュリティー情報を確立するときに発生します。このメカニズムはセキュリティーインフローと呼ばれます。

14.5.1. Elytron によるコンテナー管理のサインオン

Elytron でコンテナー管理のサインオンを実現するには、elytron-enabled 属性を true に設定する必要があります。これにより、リソースアダプターへのすべての接続が Elytron によってセキュア化されます。

/subsystem=resource-adapters/resource-adapter=<RAR_NAME>/connection-definitions=<FACTORY_NAME>:write-attribute(name=elytron-enabled,value=true)
Copy to Clipboard Toggle word wrap

resource-adapters サブシステムの elytron-enabled 属性を true に設定すると、管理 CLI を使用して elytron-enabled 属性を設定できます。デフォルトではこの属性は false に設定されています。

authentication-context 属性は、サインオンの実行に使用される Elytron 認証コンテキストの名前を定義します。

Elytron の authentication-context 属性には 1 つ以上の authentication-configuration 要素を含めることができ、使用を希望する認証情報が含まれます。

authentication-context 属性が設定されていない場合、JBoss EAP は現在の authentication-context を使用します。これは、接続を開く呼び出し元コードによって使用される authentication-context です。

例: authentication-configuration の作成

/subsystem=elytron/authentication-configuration=exampleAuthConfig:add(authentication-name=sa,credential-reference={clear-text=sa})
Copy to Clipboard Toggle word wrap

例: 上記設定を使用した authentication-context の作成

/subsystem=elytron/authentication-context=exampleAuthContext:add(match-rules=[{authentication-configuration=exampleAuthConfig}])
Copy to Clipboard Toggle word wrap

14.5.2. Elytron によるセキュリティーインフロー

セキュリティーインフローは、リソースアダプターがワークマネージャーにワークを送信する際、または同じ JBoss EAP インスタンス内のエンドポイントにメッセージを配信する際に、セキュリティー情報を確立することを可能にします。これにより、Elytron を使用してワークを実行する前に、ワークがワーク自身を認証できるようになります。認証に成功すると、提出されたワークは結果となる認証コンテキスト下で実行されます。認証に失敗すると、ワークの実行は拒否されます。

Elytron セキュリティーインフローを有効にするには、リソースアダプターのワークマネージャーを設定するときに wm-elytron-security-domain 属性を設定します。

注記
  • リソースアダプターのワークマネージャーが Elytron セキュリティードメイン wm-elytron-security-domain を使用するよう設定された場合、参照されたワークマネージャーの elytron-enabled 属性を true に設定する必要があります。
/subsystem=jca/workmanager=customWM:add(name=customWM, elytron-enabled=true)
Copy to Clipboard Toggle word wrap
  • wm-elytron-security-domain の代わりに wm-security-domain 属性が使用された場合、セキュリティーインフローはレガシーの security サブシステムによって実行されます。

以下の jca サブシステムの設定例では、ra-with-elytron-security-domain というリソースアダプターの設定を確認できます。このリソースアダプターは、Elytron セキュリティードメインの wm-realm を使用するようワークマネージャーセキュリティーを設定します。

<subsystem xmlns="urn:jboss:domain:jca:5.0">
    <archive-validation enabled="true" fail-on-error="true" fail-on-warn="false"/>
    <bean-validation enabled="true"/>
    <default-workmanager>
        <short-running-threads>
            <core-threads count="50"/>
            <queue-length count="50"/>
            <max-threads count="50"/>
            <keepalive-time time="10" unit="seconds"/>
        </short-running-threads>
        <long-running-threads>
            <core-threads count="50"/>
            <queue-length count="50"/>
            <max-threads count="50"/>
            <keepalive-time time="10" unit="seconds"/>
        </long-running-threads>
    </default-workmanager>
    <workmanager name="customWM">
        <elytron-enabled>true</elytron-enabled>
        <short-running-threads>
            <core-threads count="20"/>
            <queue-length count="20"/>
            <max-threads count="20"/>
        </short-running-threads>
    </workmanager>
    <bootstrap-contexts>
        <bootstrap-context name="customContext" workmanager="customWM"/>
    </bootstrap-contexts>
    <cached-connection-manager/>
</subsystem>
Copy to Clipboard Toggle word wrap

その後、ワークマネージャーは resource-adapter サブシステムからブートストラップコンテキストを使用して参照されます。

<subsystem xmlns="urn:jboss:domain:resource-adapters:5.0">
    <resource-adapters>
        <resource-adapter id="ra-with-elytron-security-domain">
            <archive>
                ra-with-elytron-security-domain.rar
            </archive>
            <bootstrap-context>customContext</bootstrap-context>
            <transaction-support>NoTransaction</transaction-support>
            <workmanager>
                <security>
                    <elytron-security-domain>wm-realm</elytron-security-domain>
                    <default-principal>wm-default-principal</default-principal>
                    <default-groups>
                        <group>
                            wm-default-group
                        </group>
                    </default-groups>
                </security>
            </workmanager>
        </resource-adapter>
    </resource-adapters>
</subsystem>
Copy to Clipboard Toggle word wrap

例: セキュリティードメインの設定

/subsystem=elytron/properties-realm=wm-properties-realm:add(users-properties={path=/security-dir/users.properties, plain-text=true}, groups-properties={path=/security-dir/groups.properties})

/subsystem=elytron/simple-role-decoder=wm-role-decoder:add(attribute=groups)

/subsystem=elytron/constant-permission-mapper=wm-permission-mapper:add(permissions=[{class-name="org.wildfly.security.auth.permission.LoginPermission"}])

/subsystem=elytron/security-domain=wm-realm:add(default-realm=wm-properties-realm, permission-mapper=wm-permission-mapper, realms=[{role-decoder=wm-role-decoder, realm=wm-properties-realm}])
Copy to Clipboard Toggle word wrap

Work クラスは、指定のドメイン下で Elytron の認証の認証情報を提供するロールがあります。そのためには、jakarta.resource.spi.work.WorkContextProvider を実装する必要があります。

public interface WorkContextProvider {
   /**
    * Gets an instance of <code>WorkContexts</code> that needs to be used
    * by the <code>WorkManager</code> to set up the execution context while
    * executing a <code>Work</code> instance.
    *
    * @return an <code>List</code> of <code>WorkContext</code> instances.
    */
   List<WorkContext> getWorkContexts();
}
Copy to Clipboard Toggle word wrap

このインターフェイスは、Work クラスが WorkContext を使用して、ワークが実行されるコンテキストの一部の機能を設定できるようにします。その機能の 1 つがセキュリティーインフローです。そのためには、List<WorkContext> getWorkContexts メソッドが jakarta.resource.spi.work.SecurityContext を提供する必要があります。このコンテキストは、Jakarta Authentication で定義されている jakarta.security.auth.callback.Callback オブジェクトを使用します。

例: コンテキストを使用したコールバックの作成

public class ExampleWork implements Work, WorkContextProvider {

    private final String username;
    private final String role;

    public MyWork(TestBean bean, String username, String role) {
        this.principals = null;
        this.roles = null;
        this.bean = bean;
        this.username = username;
        this.role = role;
    }

    public List<WorkContext> getWorkContexts() {
        List<WorkContext> l = new ArrayList<>(1);
        l.add(new MySecurityContext(username, role));
        return l;
    }

    public void run() {
        ...
    }

    public void release() {
        ...
    }

    public class ExampleSecurityContext extends SecurityContext {

        public void setupSecurityContext(CallbackHandler handler, Subject executionSubject, Subject serviceSubject) {
            try {
                List<jakarta.security.auth.callback.Callback> cbs = new ArrayList<>();
                cbs.add(new CallerPrincipalCallback(executionSubject, new SimplePrincipal(username)));
                cbs.add(new GroupPrincipalCallback(executionSubject, new String[]{role}));
                handler.handle(cbs.toArray(new jakarta.security.auth.callback.Callback[cbs.size()]));
            } catch (Throwable t) {
                throw new RuntimeException(t);
            }
        }
    }
Copy to Clipboard Toggle word wrap

上記の例では、ExampleWorkWorkContextProvider インターフェイスを実装し、ExampleSecurityContext を提供します。そのコンテキストは、ワークの実行時に Elytron によって認証されるセキュリティー情報の提供に必要なコールバックを作成します。

14.6. 管理対象接続プールの設定

JBoss EAP は、以下に示す ManagedConnectionPool インターフェイスの 3 つの実装を提供します。

  • org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreConcurrentLinkedQueueManagedConnectionPool: これは、JBoss EAP 7 のデフォルトの接続プールであり、そのままの設定で最高のパフォーマンスを提供します。
  • org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool: これは、以前の JBoss EAP バージョンではデフォルトの接続プールでした。
  • org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool: この接続プールは、デバッグ目的でのみ使用され、シャットダウン時またはプールがフラッシュされたときにリークを報告します。

前提条件

  • 管理 CLI へのアクセス。

手順

  1. データソースの管理対象接続プールの実装を設定します。

       ----
       /subsystem=datasources/data-source=DATA_SOURCE:write-attribute(name=mcp,value=MCP_CLASS)
       ----
    Copy to Clipboard Toggle word wrap
  2. リソースアダプターの管理対象接続プールの実装を設定します。

       ----
       /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:write-attribute(name=mcp,value=MCP_CLASS)
       ----
    Copy to Clipboard Toggle word wrap
  3. メッセージングサーバーの管理対象接続プールの実装を設定します。

       ----
       /subsystem=messaging-activemq/server=SERVER/pooled-connection-factory=CONNECTION_FACTORY:write-attribute(name=managed-connection-pool,value=MCP_CLASS)
       ----
    Copy to Clipboard Toggle word wrap

14.7. 接続の統計情報の表示

/deployment=NAME.rar サブツリーから、定義された接続に関する統計情報を読み取ります。これにより、standalone.xml または domain.xml 設定で接続が定義されていない場合でも、任意の RAR の統計情報にアクセスできます。

前提条件

  • 管理 CLI へのアクセス。

手順

  • 次のコマンドを実行し、接続の統計情報を読み取ります。

       ----
       /deployment=NAME.rar/subsystem=resource-adapters/statistics=statistics/connection-definitions=java\:\/testMe:read-resource(include-runtime=true)
       ----
    Copy to Clipboard Toggle word wrap
注記

統計はすべてランタイムのみの情報であるため、必ず include-runtime=true 引数を指定してください。

14.8. リソースアダプター接続のフラッシュ

以下の管理 CLI コマンドを使用して、リソースアダプターの接続をフラッシュします。

注記

マネージドドメインでは、これらのコマンドの前に /host=HOST_NAME/server=SERVER_NAME/ を付ける必要があります。

前提条件

  • 管理 CLI へのアクセス。

手順

  • プールの接続をすべてフラッシュします。

       ----
       /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-all-connection-in-pool
       ----
    Copy to Clipboard Toggle word wrap
  • プールの接続をすべて正常にフラッシュします。

       ----
       /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-gracefully-connection-in-pool
       ----
    Copy to Clipboard Toggle word wrap
    The server will wait until connections become idle before flushing them.
    Copy to Clipboard Toggle word wrap
  • プールのアイドル状態の接続をすべてフラッシュします。

       ----
       /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-idle-connection-in-pool
       ----
    Copy to Clipboard Toggle word wrap
  • プールの無効な接続をすべてフラッシュします。

       ----
       /subsystem=resource-adapters/resource-adapter=RESOURCE_ADAPTER/connection-definitions=CONNECTION_DEFINITION:flush-invalid-connection-in-pool
       ----
    Copy to Clipboard Toggle word wrap
    The server will flush all connections that it determines to be invalid.
    Copy to Clipboard Toggle word wrap
注記

この手順は順番に行うものではありません。

第15章 JBoss EAP での Web サーバー (Undertow) の設定

この章では、JBoss EAP に組み込まれているデフォルトサーバーである Undertow Web サーバーの設定に焦点を当てます。ここでは、安全な通信のために SSL/TLS を有効にする方法、パフォーマンスを向上させるために HTTP/2 を活用する方法、運用要件に合わせてサーバー設定を微調整する方法について詳しく説明します。

15.1. Undertow サブシステムの概要

JBoss EAP 8.0 では、Undertow サブシステムはアプリケーションサーバー内の Web レイヤーとして機能します。コア Web サーバーおよびサーブレットコンテナー機能を提供し、Jakarta Servlet 6.0 仕様、Web ソケット、HTTP アップグレードなどの高度な機能をサポートします。Undertow は、mod_cluster をサポートする高性能リバースプロキシーとしても機能し、Web トラフィックの処理におけるスケーラビリティー、効率、柔軟性の向上に貢献します。

undertow サブシステムは、Web サーバーおよびサーブレットコンテナーの設定を可能にします。Jakarta Servlet 6.0 Specification や websocket を実装します。HTTP のアップグレードや、サーブレットデプロイメントでの高パフォーマンスな非ブロッキングハンドラーの使用もサポートします。undertow サブシステムは、mod_cluster をサポートする高パフォーマンスなリバースプロキシーとして動作することも可能です。

undertow サブシステム内で設定する主なコンポーネントは 5 つあります。

  • Buffer caches
  • Server
  • Servlet container
  • Handlers
  • Filters
注記

JBoss EAP には、これらの各コンポーネントの設定を更新する機能がありますが、デフォルト設定は妥当なパフォーマンスの設定を提供し、ほとんどのユースケースに適しています。

デフォルトの Undertow サブシステムの設定
<subsystem xmlns="{UndertowSubsystemNamespace}" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    <servlet-container name="default">
        <jsp-config/>
        <websockets/>
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>
Copy to Clipboard Toggle word wrap
重要

undertow サブシステムは、XNIO ワーカーとバッファープールを提供するために io サブシステムにも依存します。io サブシステムは個別に設定され、ほとんどの場合で最適なパフォーマンスを得られるデフォルト設定を提供します。

15.1.1. Undertow サブシステムでの Elytron の使用

web アプリケーションがデプロイされると、そのアプリケーションが必要なセキュリティードメインの名前が特定されます。これは、デプロイメント内からで、デプロイメントにセキュリティードメインがない場合は undertow サブシステムで定義された default-security-domain が仮定されます。デフォルトでは、default-security-domainApplicationDomain です。アプリケーションに必要なセキュリティードメインの名前から適切な Elytron 設定への適切なマッピングを確実に行うために、application-security-domain リソースを undertow サブシステムに追加できます。

例: マッピングの追加

/subsystem=undertow/application-security-domain=ApplicationDomain:add(security-domain=ApplicationDomain)
Copy to Clipboard Toggle word wrap

マッピングの追加に成功すると、以下のような結果が出力されます。

<subsystem xmlns="{UndertowSubsystemNamespace}" ... default-security-domain="other">
...
    <application-security-domains>
        <application-security-domain name="ApplicationDomain" security-domain="ApplicationDomain"/>
    </application-security-domains>
...
</subsystem>
Copy to Clipboard Toggle word wrap

注記
  • この時点でデプロイメントがすでにデプロイされている場合は、アプリケーションサーバーをリロードして、アプリケーションセキュリティードメインマッピングを有効にする必要があります。
  • 現在の Web サービス/Elytron 統合では、Web サービスエンドポイントと Elytron セキュリティードメイン名をセキュアにするために指定されたセキュリティードメインの名前が同じである必要があります。

この簡単な例は、BASICCLIENT_CERTDIGESTFORM など、デプロイメントがサーブレット仕様内で定義された標準の HTTP メカニズムを使用する場合に適しています。この場合、認証は ApplicationDomain セキュリティードメインに対して実行されます。このフォームは、アプリケーションが認証メカニズムを使用せず、代わりにプログラムによる認証を使用したり、デプロイメントに関連する SecurityDomain を取得して直接使用したりする場合にも適しています。

例: 高度なマッピング

/subsystem=undertow/application-security-domain=MyAppSecurity:add(http-authentication-factory=application-http-authentication)
Copy to Clipboard Toggle word wrap

高度なマッピングに成功すると、以下のような結果が出力されます。

<subsystem xmlns="{UndertowSubsystemNamespace}" ... default-security-domain="other">
...
    <application-security-domains>
        <application-security-domain name="MyAppSecurity" http-authentication-factory="application-http-authentication"/>
    </application-security-domains>
...
</subsystem>
Copy to Clipboard Toggle word wrap

このような設定では、セキュリティードメインを参照する代わりに、http-authentication-factory が参照されます。これは、認証メカニズムのインスタンスの取得に使用されるファクトリーで、セキュリティードメインと関連付けられます。

カスタム HTTP 認証メカニズムを使用する場合や、プリンシパルトランスフォーマー、認証情報ファクトリー、メカニズムレルムなどのメカニズムに追加の設定を定義する必要がある場合など、http-authentication-factory 属性を参照する必要があります。また、Servlet 仕様に記載されている 4 つのメカニズム以外を使用する場合は、http-authentication-factory 属性を参照した方がよいでしょう。

高度なマッピングが使用される場合、別の設定オプション override-deployment-config を使用できます。参照された http-authentication-factory は認証メカニズムの完全セットを返すことができます。デフォルトでは、アプリケーションによってリクエストされたメカニズムと一致するするためにフィルターされます。このオプションが true に設定された場合、ファクトリーによって提供されたメカニズムは、アプリケーションによってリクエストされたメカニズムをオーバーライドします。

application-security-domain リソースには追加のオプション enable-jacc もあります。これを true に設定すると、このマッピングに一致するデプロイメントに対して Java Authorization Contract for Containers が有効になります。

15.1.1.1. ランタイム情報

application-security-domain マッピングが使用されている場合、このマッピングに対してデプロイメントが想定どおり一致していることを再度確認すると便利です。リソースが include-runtime=true で読み取りされた場合、マッピングに関連するデプロイメントは以下のように表示されます。

/subsystem=undertow/application-security-domain=MyAppSecurity:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "enable-jacc" => false,
        "http-authentication-factory" => undefined,
        "override-deployment-config" => false,
        "referencing-deployments" => ["simple-webapp.war"],
        "security-domain" => "ApplicationDomain",
        "setting" => undefined
    }
}
Copy to Clipboard Toggle word wrap

この出力の referencing-deployments 属性は、simple-webapp.war デプロイメントがマッピングを使用してデプロイされたことを示しています。

15.1.2. バッファーキャッシュの設定

この手順では、静的リソースをキャッシュしてパフォーマンスを向上させる JBoss EAP でのバッファーキャッシュの設定について説明します。異なるデプロイメントでは、異なるキャッシュサイズを使用してリソース管理を最適化できます。使用領域の合計は、バッファーサイズ、リージョンごとのバッファー数、およびリージョンの最大数を掛けて算出できます。バッファーキャッシュのデフォルトサイズは 10MB です。

注記

JBoss EAP はデフォルトで単一のキャッシュを提供します。

<subsystem xmlns="{UndertowSubsystemNamespace}" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    ...
</subsystem>
Copy to Clipboard Toggle word wrap

前提条件

  • JBoss EAP がインストールされており、管理 CLI への管理アクセス権があることを確認します。

手順

  1. 既存のバッファーキャッシュを更新します。

    • バッファーサイズ属性を変更します。

      /subsystem=undertow/buffer-cache=default/:write-attribute(name=buffer-size,value=2048)
      Copy to Clipboard Toggle word wrap
      reload
      Copy to Clipboard Toggle word wrap
  2. 新しいバッファーキャッシュを作成します。

    • 新しいバッファーキャッシュを追加します。

      /subsystem=undertow/buffer-cache=new-buffer:add
      Copy to Clipboard Toggle word wrap
  3. バッファーキャッシュを削除します。

    • 既存のバッファーキャッシュを削除します。

      /subsystem=undertow/buffer-cache=new-buffer:remove
      Copy to Clipboard Toggle word wrap
      reload
      Copy to Clipboard Toggle word wrap

15.1.3. バイトバッファープールの設定

Undertow バイトバッファープールは、プールされた NIO ByteBuffer インスタンスの割り当てに使用されます。すべてのリスナーにバイトバッファープールがあり、各リスナーに異なるバッファープールおよびワーカーを使用できます。バイトバッファープールは異なるサーバーインスタンス間で共有できます。

これらのバッファーは IO 操作に使用され、バッファーサイズはアプリケーションのパフォーマンスに大きく影響します。通常、ほとんどのサーバーでは 16 K が理想のサイズになります。

前提条件

  • JBoss EAP がインストールされており、管理 CLI への管理アクセス権があることを確認します。

手順

  1. 既存のバイトバッファープールを更新します。

    • バッファーサイズ属性を変更します。

      /subsystem=undertow/byte-buffer-pool=myByteBufferPool:write-attribute(name=buffer-size,value=1024)
      Copy to Clipboard Toggle word wrap
      reload
      Copy to Clipboard Toggle word wrap
  2. 新しいバイトバッファープールを作成します。

    • 新しいバイトバッファープールを追加します。

      /subsystem=undertow/byte-buffer-pool=newByteBufferPool:add
      Copy to Clipboard Toggle word wrap
  3. バイトバッファープールを削除します。

    • 既存のバイトバッファープールを削除します。

      /subsystem=undertow/byte-buffer-pool=newByteBufferPool:remove
      Copy to Clipboard Toggle word wrap
      reload
      Copy to Clipboard Toggle word wrap

検証

  • 管理コンソールでバッファープールの設定を確認して、変更を確認します。

関連情報

15.1.4. Undertow でのサーバー設定について

サーバーは Undertow のインスタンスを表し、次のいくつかの要素で構成されます。

  • host
  • http-listener
  • https-listener
  • ajp-listener

host 要素は仮想ホスト設定を提供し、3 つのリスナーはそのタイプの接続を Undertow インスタンスに提供します。

サーバーのデフォルトの動作では、サーバーの起動中にリクエストをキューに置きます。このデフォルトの動作は、ホストの queue-requests-on-start 属性を使用して変更できます。この属性が true (デフォルト) に設定されている場合、サーバーの起動時に到着した要求は、サーバーの準備が整うまで保留されます。この属性が false に設定された場合、サーバーが完全に起動する前に到達したリクエストは、デフォルトの応答コードで拒否されます。

属性の値に関わらず、サーバーが完全に起動するまでリクエストの処理は開始されません。

管理コンソールを使用して queue-requests-on-start 属性を設定するには、ConfigurationSubsystemsWeb (Undertow)Server と選択した後、サーバーを選択して 表示 をクリックし、Hosts タブを選択します。マネージドドメイでは、設定するプロファイルを指定する必要があります。

注記

複数のサーバーを設定できるため、デプロイメントやサーバーを完全に分離できます。これは、マルチテナント環境などで便利です。

JBoss EAP はデフォルトでサーバーを提供します。

15.1.5. デフォルトの Undertow サブシステムの設定

このリファレンスでは、Undertow サブシステムのデフォルト設定について説明します。

<subsystem xmlns="{UndertowSubsystemNamespace}" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    ...
</subsystem>
Copy to Clipboard Toggle word wrap

15.1.6. 管理 CLI を使用したサーバーの設定

この手順では、管理 CLI を使用して Undertow サブシステム内のサーバーを管理する方法について説明します。必要に応じて、既存のサーバーを更新したり、新しいサーバーを作成したり、サーバーを削除したりできます。

注記

管理コンソールを使用してサーバーを設定する場合は、ConfigurationSubsystemsWeb (Undertow)Server と選択します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. 既存のサーバーを更新します。

    /subsystem=undertow/server=default-server:write-attribute(name=default-host,value=default-host)
    Copy to Clipboard Toggle word wrap
    reload
    Copy to Clipboard Toggle word wrap
  2. 新しいサーバーを作成します。

    /subsystem=undertow/server=new-server:add
    Copy to Clipboard Toggle word wrap
    reload
    Copy to Clipboard Toggle word wrap
  3. サーバーを削除します。

    /subsystem=undertow/server=new-server:remove
    Copy to Clipboard Toggle word wrap
    reload
    Copy to Clipboard Toggle word wrap

15.1.7. アクセスロギング

定義する各ホストにアクセスロギングを設定できます。

利用できるアクセスロギングオプションは、標準のアクセスロギングとコンソールアクセスロギングの 2 つです。

アクセスロギングに必要な追加の処理はシステムパフォーマンスに影響を与える可能性があることに注意してください。

15.1.7.1. 標準のアクセスロギング

標準のアクセスログは、ログエントリーをログファイルに書き込みます。

デフォルトでは、ログファイルは standalone/log/access_log.log ディレクトリーに保存されます。

標準のアクセスログを有効にするには、アクセスログデータを取得するホストに access-log 設定を追加します。以下の CLI コマンドは、デフォルトの JBoss EAP サーバーのデフォルトのホストの設定を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=access-log:add
Copy to Clipboard Toggle word wrap
注記

標準のアクセスログを有効にしたら、サーバーをリロードする必要があります。

デフォルトでは、アクセスログレコードには以下のデータが含まれます。

  • リモートホスト名
  • リモート論理ユーザー名 (常に -)
  • 認証されたリモートユーザー
  • Common Log Format 形式のリクエストの日時
  • 要求の最初の行
  • 応答の HTTP ステータスコード
  • HTTP ヘッダーを除く、送信済みバイト数。

この一連のデータは共通のパターンとして定義されます。組み合わせた別のパターンも使用できます。一般的なパターンでログ記録されているデータのほかに、組み合わせたパターンには、受信ヘッダーからの閲覧元およびユーザーエージェントが含まれます。

ログに記録されるデータは、pattern 属性を使用して変更できます。以下の CLI コマンドは、組み合わせたパターンを使用ための pattern 属性の更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=access-log:write-attribute(name=pattern,value="combined"
Copy to Clipboard Toggle word wrap
注記

pattern 属性を更新した後は、サーバーをリロードする必要があります。

Expand
表15.1 利用可能なパターン
パターン説明

%a

リモート IP アドレス

%A

ローカル IP アドレス

%b

送信済みバイト数 (HTTP ヘッダーまたは - を除く (バイトが送信されなかった場合))

%B

送信済みバイト数 (HTTP ヘッダーを除く)

%h

リモートホスト名

%H

要求プロトコル

%l

identd からのリモート論理ユーザー名 (常に - を返します。これは、Apache アクセスログの互換性のために含まれています)

%m

要求メソッド

%p

ローカルポート

%q

クエリー文字列 (? 文字を除く)

%r

要求の最初の行

%s

応答の HTTP ステータスコード

%t

Common Log Format 形式の日時

%u

認証されたリモートユーザー

%U

要求された URL パス

%v

ローカルサーバー名

%D

要求を処理するのにかかった時間 (ミリ秒単位)

%T

要求を処理するのにかかった時間 (秒単位)

%I

現在の要求スレッド名 (後でスタックトレースと比較できます)

common

%h %l %u %t "%r" %s %b

combined

%h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}"

cookie、受信ヘッダーおよび応答ヘッダー、またはセッションから情報を書き込むこともできます。これは、Apache 構文に基づきます。

  • %{i,xxx} (受信ヘッダーの場合)
  • %{o,xxx} (送信応答ヘッダーの場合)
  • %{c,xxx} (特定のクッキーの場合)
  • %{r,xxx} (xxxServletRequest の属性)
  • %{s,xxx} (xxxHttpSession の属性)

このログには、追加の設定オプションも利用できます。詳細は、付録の "access-log 属性" を参照してください。

15.1.7.2. コンソールアクセスロギング

コンソールのアクセスログは、JSON データとして構造化された標準出力 (stdout) にデータを書き込みます。

各アクセスログレコードは、1 行のデータです。ログ集約システムにより、このデータを取得して処理できます。

コンソールアクセスロギングを設定するには、アクセスログデータをキャプチャーしたいホストに console-access-log 設定を追加します。以下の CLI コマンドは、デフォルトの JBoss EAP サーバーのデフォルトのホストの設定を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add
Copy to Clipboard Toggle word wrap

デフォルトでは、コンソールアクセスログレコードには以下のデータが含まれます。

Expand
表15.2 デフォルトのコンソールアクセスログデータ
ログデータフィールド名説明

eventSource

リクエストのイベントのソース

hostName

要求を処理した JBoss EAP ホスト

bytesSent

JBoss EAP サーバーがリクエストへの応答として送信したバイト数

dateTime

要求が JBoss EAP サーバーによって処理された日時

remoteHost

要求の発信先のマシンの IP アドレス

remoteUser

リモート要求に関連付けられたユーザー名

requestLine

送信された要求

responseCode

JBoss EAP サーバーによって返された HTTP 応答コード

デフォルトプロパティーはログ出力に常に含まれます。attributes 属性を使用して、デフォルトのログデータのラベルを変更できます。場合によっては、データ設定を変更することも可能です。attributes 属性を使用して、さらにログデータを出力に追加することもできます。

Expand
表15.3 利用可能なコンソールアクセスログデータ
ログデータフィールド名説明形式

authentication-type

要求に関連付けられたユーザーの認証に使用される認証タイプデフォルトラベル: authenticationType。このキーオプションを使用して、このプロパティーのラベルを変更します。

authentication-type{} authentication-type={key="authType"}

bytes-sent

リクエストに対して返されるバイト数。HTTP ヘッダーを除く。デフォルトラベル: bytesSent。このキーオプションを使用して、このプロパティーのラベルを変更します。

bytes-sent={} bytes-sent={key="sent-bytes"}

date-time

要求が受信および処理された日時。デフォルトラベル: dateTime。このキーオプションを使用して、このプロパティーのラベルを変更します。date-format を使用して、日付レコードのフォーマットに使用するパターンを定義します。このパターンは Java SimpleDateFormatter パターンである必要があります。date-format オプションが定義されている場合は、time-zone オプションを使用して日付や時間データのフォーマットに使用するタイムゾーンを指定します。この値は有効な java.util.TimeZone である必要があります。

date-time={key="<keyname>", date-format="<date-time format>"} date-time={key="@timestamp", date-format="yyyy-MM-dd’T’HH:mm:ssSSS"}

host-and-port

リクエストによってクエリーされたホストおよびポート。デフォルトラベル: hostAndPort。このキーオプションを使用して、このプロパティーのラベルを変更します。

host-and-port{} host-and-port={key="port-host"}

local-ip

ローカル接続の IP アドレス。このキーオプションを使用して、このプロパティーのラベルを変更します。デフォルトラベル: localIp。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-ip{} local-ip{key="localIP"}

local-port

ローカル接続のポート。デフォルトラベル: localPort。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-port{} local-port{key="LocalPort"}

local-server-name

要求を処理したローカルサーバー名。デフォルトラベル: localServerName。このキーオプションを使用して、このプロパティーのラベルを変更します。

local-server-name {} local-server-name {key=LocalServerName}

path-parameter

リクエストに含まれる 1 つ以上のパスまたは URI パラメーター。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

path-parameter{names={store,section}} path-parameter{names={store,section}, key-prefix="my-"}

predicate

述語コンテキストの名前。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

predicate{names={store,section}} predicate{names={store,section}, key-prefix="my-"}

query-parameter

リクエストに含まれる 1 つ以上のパラメーターまたはクエリーパラメーター。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合は、出力の各 path パラメーター名の前に接頭辞が追加されます。

query-parameter{names={store,section}} query-parameter{names={store,section}, key-prefix="my-"}

query-string

リクエストのクエリー文字列。デフォルトラベル: queryString。このキーオプションを起用して、このプロパティーのラベルを変更します。include-question-mark プロパティーを使用して、クエリー文字列に疑問符を含めるかどうかを指定します。デフォルトでは、疑問符は含まれていません。

query-string{} query-string{key="QueryString", include-question-mark="true"}

relative-path

要求の相対パス。デフォルトラベル: relativePath。このキーオプションを使用して、このプロパティーのラベルを変更します。

relative-path{} relative-path{key="RelativePath"}

remote-host

リモートホスト名デフォルトラベル: remoteHost。このキーオプションを使用して、このプロパティーのラベルを変更します。

remote-host{} remote-host{key="RemoteHost"}

remote-ip

リモート IP アドレス。デフォルトラベル: remoteIp。このキーオプションを使用して、このプロパティーのラベルを変更します。この難読化プロパティーを使用して、出力ログレコードの IP アドレスを難読化します。デフォルト値は false です。

remote-ip{} remote-ip{key="RemoteIP", obfuscated="true"}

remote-user

認証されたリモートユーザーデフォルトラベル: remoteUser。このキーオプションを使用して、このプロパティーのラベルを変更します。

remote-user{} remote-user{key="RemoteUser"}

request-header

要求ヘッダーの名前。構造化されたデータのキーはヘッダーの名前です。その値は名前付きヘッダーの値になります。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合には、出力の要求ヘッダー名の前に接頭辞が追加されます。

request-header{names={store,section}} request-header{names={store,section}, key-prefix="my-"}

request-line

リクエストの行。デフォルトラベル: requestLine。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-line{} request-line{key="Request-Line"}

request-method

要求メソッドデフォルトラベル: requestMethod。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-method{} request-method{key="RequestMethod"}

request-path

リクエストの相対パス。デフォルトラベル: requestPath。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-path{} request-path{key="RequestPath"}

request-protocol

要求のプロトコル。デフォルトラベル: requestProtocol。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-protocol{} request-protocol{key="RequestProtocol"}

request-scheme

要求の URI スキーム。デフォルトラベル: requestScheme。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-scheme{} request-scheme{key="RequestScheme"}

request-url

元の要求 URI。クライアントで指定した場合、ホスト名、プロトコルなどが含まれます。デフォルトラベル: requestUrl。このキーオプションを使用して、このプロパティーのラベルを変更します。

request-url{} request-url{key="RequestURL"}

resolved-path

解決したパス。デフォルトラベル: resolvedPath。このキーオプションを使用して、このプロパティーのラベルを変更します。

resolved-path{} resolved-path{key="ResolvedPath"}

response-code

応答コード。デフォルトラベル: responseCode。このキーオプションを使用して、このプロパティーのラベルを変更します。

response-code{} response-code{key="ResponseCode"}

response-header

応答ヘッダーの名前。構造化されたデータのキーはヘッダーの名前です。その値は名前付きヘッダーの値になります。names プロパティーは、交換値を解決するために使用される名前のコンマ区切りリストです。key-prefix プロパティーを使用してキーを一意にします。key-prefix が指定されている場合には、出力の要求ヘッダー名の前に接頭辞が追加されます。

response-header{names={store,section}} response-header{names={store,section}, key-prefix="my-"}

response-reason-phrase

応答コードのテキスト理由。デフォルトラベル: responseReasonPhrase。このキーオプションを使用してこのプロパティーのラベルを変更します。

response-reason-phrase{} response-reason-phrase{key="ResponseReasonPhrase"}

response-time

リクエストの処理に使われる時間。デフォルトラベル: responseTime。このキーオプションを使用して、このプロパティーのラベルを変更します。デフォルトの時間単位はミリ秒 (MILLISECONDS) です。利用可能な時間の単位は以下のとおりです。* NANOSECONDS * MICROSECONDS * MILLISECONDS * SECONDS

response-time{} response-time{key="ResponseTime", time-unit=SECONDS}

secure-exchange

交換がセキュアであったかどうかを示します。デフォルトラベル: secureExchange。このキーオプションを使用して、このプロパティーのラベルを変更します。

secure-exchange{} secure-exchange{key="SecureExchange"}

ssl-cipher

要求の SSL 暗号。デフォルトラベル: sslCipher。このオプションを使用して、このプロパティーのラベルを変更します。

ssl-cipher{} ssl-cipher{key="SSLCipher"}

ssl-client-cert

要求の SSL クライアント証明書。デフォルトラベル: sslClientCert。このキーオプションを使用して、このプロパティーのラベルを変更します。

ssl-client-cert{} ssl-client-cert{key="SSLClientCert"}

ssl-session-id

要求の SSL セッション ID。デフォルトラベル: sslSessionId。このキーオプションを使用して、このプロパティーのラベルを変更します。

ssl-session-id{} stored-response

要求に対する、保存した応答。デフォルトラベル: storedResponse。このキーオプションを使用して、このプロパティーのラベルを変更します。

stored-response{} stored-response{key="StoredResponse"}

thread-name

現在のスレッドのスレッド名。デフォルトラベル: threadName。このキーオプションを使用して、このプロパティーのラベルを変更します。

thread-name{} thread-name{key="ThreadName"}

transport-protocol

metadata 属性を使用して、アクセスログレコードに追加する追加の任意のデータを設定できます。metadata 属性の値は、アクセスログレコードに追加するデータを定義する key:value ペアのセットです。ペアのこの値は管理モデルの式になります。管理モデル式は、サーバーの起動またはリロード時に解決されます。キーと値のペアはコンマで区切られます。

以下の CLI コマンドは、追加のログデータ、ログデータのカスタマイズ、追加のメタデータなど、複雑なコンソールログ設定の例を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:add(metadata={"@version"="1", "qualifiedHostName"=${jboss.qualified.host.name:unknown}}, attributes={bytes-sent={}, date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:ssSSS"}, remote-host={}, request-line={}, response-header={key-prefix="responseHeader", names=["Content-Type"]}, response-code={}, remote-user={}})
Copy to Clipboard Toggle word wrap

結果として生成されるアクセスログレコードは以下の追加の JSON データに類似しています (注意: 以下の出力例は、読みやすさを考慮してフォーマットされています。実際の記録では、すべてのデータが単一の行として出力されます)。

{
    "eventSource":"web-access",
    "hostName":"default-host",
    "@version":"1",
    "qualifiedHostName":"localhost.localdomain",
    "bytesSent":1504,
    "@timestamp":"2019-05-02T11:57:37123",
    "remoteHost":"127.0.0.1",
    "remoteUser":null,
    "requestLine":"GET / HTTP/2.0",
    "responseCode":200,
    "responseHeaderContent-Type":"text/html"
}
Copy to Clipboard Toggle word wrap

以下のコマンドは、コンソールアクセスログを有効にした後にのログデータへの更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:write-attribute(name=attributes,value={bytes-sent={}, date-time={key="@timestamp", date-format="yyyy-MM-dd'T'HH:mm:ssSSS"}, remote-host={}, request-line={}, response-header={key-prefix="responseHeader", names=["Content-Type"]}, response-code={}, remote-user={}})
Copy to Clipboard Toggle word wrap

以下のコマンドは、コンソールアクセスログを有効にした後にカスタムメタデータへの更新を示しています。

/subsystem=undertow/server=default-server/host=default-host/setting=console-access-log:write-attribute(name=metadata,value={"@version"="1", "qualifiedHostName"=${jboss.qualified.host.name:unknown}})
Copy to Clipboard Toggle word wrap

15.2. サーブレットコンテナーの設定

サーブレットコンテナーは、セッション関連の設定を含む、サーブレット、JavaServer Pages、Jakarta Server Pages、および WebSocket 関連のすべての設定を提供します。ほとんどのサーバーでは 1 つのサーブレットコンテナーのみが必要ですが、追加の servlet-container 要素を追加して複数のサーブレットコンテナーを設定することもできます。サーブレットコンテナーが複数設定されていると、複数のデプロイメントを異なる仮想ホストの同じコンテキストパスにデプロイできるなど、一部の動作を有効にすることができます。

注記

サーブレットコンテナーによって提供される設定の多くは、デプロイされたアプリケーションによって web.xml ファイルを使用して個別にオーバーライドできます。

15.2.1. デフォルトの undertow サブシステム設定

JBoss EAP はデフォルトでサーブレットコンテナーを提供します。このリファレンスでは、サーブレットコンテナーを含む Undertow サブシステムのデフォルト設定について説明します。

<subsystem xmlns="{UndertowSubsystemNamespace}">
  <buffer-cache name="default"/>
  <server name="default-server">
    ...
  </server>
  <servlet-container name="default">
    <jsp-config/>
    <websockets/>
  </servlet-container>
  ...
</subsystem>
Copy to Clipboard Toggle word wrap

15.2.2. 管理 CLI と管理コンソールを使用してサーブレットコンテナーを管理する

この手順では、管理 CLI と管理コンソールを使用して Undertow サブシステム内のサーブレットコンテナーを管理する方法について説明します。必要に応じて、既存のサーブレットコンテナーを更新したり、新しいサーブレットコンテナーを作成したり、サーブレットコンテナーを削除したりできます。

前提条件

  • 管理 CLI にアクセスできる。
  • 管理コンソールにアクセスできる。
  • サーバー設定を変更する権限がある。

管理コンソールを使用して Undertow サブシステム内のサーブレットコンテナーを管理する

管理コンソールを使用してサーブレットコンテナーを設定する場合は、ConfigurationSubsystemsWeb (Undertow)Servlet Container と選択します。

管理 CLI を使用して Undertow サブシステム内のサーブレットコンテナーを管理する

以下の例は、管理 CLI を使用してサーブレットコンテナーを設定する方法を示しています。

手順

  1. 管理 CLI へ接続します。
  2. サーブレットコンテナーの属性を更新するには、次のコマンドを実行します。

         ----
         /subsystem=undertow/servlet-container=default:write-attribute(name=ignore-flush,value=true)
         ----
    Copy to Clipboard Toggle word wrap
  3. 変更を適用するには、サーバーをリロードします。

         ----
         reload
         ----
    Copy to Clipboard Toggle word wrap

新規サーブレットコンテナーの作成

  1. 管理 CLI へ接続します。
  2. 新しいサーブレットコンテナーを作成するには、次のコマンドを実行します。

         ----
         /subsystem=undertow/servlet-container=new-servlet-container:add
         ----
    Copy to Clipboard Toggle word wrap
  3. 変更を適用するには、サーバーをリロードします。

         ----
         reload
         ----
    Copy to Clipboard Toggle word wrap

サーブレットコンテナーの削除

  1. 管理 CLI へ接続します。
  2. サーブレットコンテナーを削除するには、次のコマンドを実行します。

         ----
         /subsystem=undertow/servlet-container=new-servlet-container:remove
         ----
    Copy to Clipboard Toggle word wrap
  3. 変更を適用するには、サーバーをリロードします。

         ----
         reload
         ----
    Copy to Clipboard Toggle word wrap

15.3. サーブレット拡張の設定

サーブレット拡張は、サーブレットデプロイメントプロセスへのフックや、サーブレットデプロイメントの変更を可能にします。これは、追加の認証メカニズムをデプロイメントに追加する必要がある場合や、ネイティブ Undertow ハンドラーをサーブレットデプロイメントの一部として使用する必要がある場合などに便利です。

カスタムサーブレット拡張を作成するには、io.undertow.servlet.ServletExtension インターフェイスを実装した後、実装クラスの名前をデプロイメントの META-INF/services/io.undertow.servlet.ServletExtension ファイルに追加する必要があります。さらに、ServletExtension 実装のコンパイルされたクラスファイルを含める必要もあります。Undertow がサーブレットをデプロイすると、deployments クラスローダーからすべてのサービスをロードし、それらの handleDeployment メソッドを呼び出します。

デプロイメントの完全かつ変更可能な記述が含まれる Undertow DeploymentInfo 構造は、このメソッドに渡されます。この構造を変更して、デプロイメントの内容を変更することができます。

DeploymentInfo 構造は、組み込み API によって使用される構造と同じあるため、ServletExtension は Undertow を組み込みモードで使用したときと同じ柔軟性を持ちます。

15.4. ハンドラーの設定

JBoss EAP では、次の 2 種類のハンドラーを設定できます。

  • ファイルハンドラー
  • リバースプロキシーハンドラー

ファイルハンドラー は静的ファイルを提供します。各ファイルハンドラーは仮想ホストの場所にアタッチされている必要があります。リバースプロキシーハンドラー を使用すると、JBoss EAP は高性能なリバースプロキシーとして機能できます。

15.4.1. ハンドラーを設定するためのデフォルトの Undertow サブシステム設定

JBoss EAP はデフォルトでファイルハンドラーを提供します。このリファレンスでは、ハンドラーの Undertow サブシステムのデフォルト設定について説明します。

<subsystem xmlns="{UndertowSubsystemNamespace}" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    <buffer-cache name="default"/>
    <server name="default-server">
        ...
    </server>
    <servlet-container name="default">
        ...
    </servlet-container>
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>
Copy to Clipboard Toggle word wrap

15.4.2. 管理 CLI を使用してファイルハンドラーを管理する

この手順では、管理 CLI を使用して Undertow サブシステム内のファイルハンドラーを管理する方法について説明します。必要に応じて、既存のファイルハンドラーを更新したり、新しいファイルハンドラーを作成したり、ファイルハンドラーを削除したりできます。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  • 既存のファイルハンドラーの更新

    1. 管理 CLI へ接続します。
    2. ファイルハンドラーの属性を更新するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=case-sensitive,value=true)
      ----
      Copy to Clipboard Toggle word wrap
    3. 変更を適用するには、サーバーをリロードします。

      ----
      reload
      ----
      Copy to Clipboard Toggle word wrap
  • 新規ファイルハンドラーの作成

    1. 管理 CLI へ接続します。
    2. 新しいファイルハンドラーを作成するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=handler/file=new-file-handler:add(path="${jboss.home.dir}/welcome-content")
      ----
      Copy to Clipboard Toggle word wrap
      [WARNING]
      ====
      If you set a file handler's `path` directly to a file instead of a directory, any `location` elements that reference that file handler must not end with a forward slash (`/`). Otherwise, the server will return a `404 - Not Found` response.
      ====
      Copy to Clipboard Toggle word wrap
  • ファイルハンドラーの削除

    1. 管理 CLI へ接続します。
    2. ファイルハンドラーを削除するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=handler/file=new-file-handler:remove
      ----
      Copy to Clipboard Toggle word wrap
    3. 変更を適用するには、サーバーをリロードします。

      ----
      reload
      ----
      Copy to Clipboard Toggle word wrap

15.5. フィルターの設定

フィルターはリクエストの一部の変更を可能にし、述語を使用してフィルターの実行時を制御できます。フィルターの一般的なユースケースには、ヘッダーの設定や GZIP 圧縮などがあります。

注記

フィルターの機能は、JBoss EAP 6 で使用されたグローバルバルブと同等です。

以下のタイプのフィルターを定義できます。

  • custom-filter
  • error-page
  • expression-filter
  • gzip
  • mod-cluster
  • request-limit
  • response-header
  • rewrite

15.5.1. 管理 CLI と管理コンソールを使用したファイルハンドラーの管理

この手順では、管理 CLI と管理コンソールを使用して Undertow サブシステムでフィルターを管理する方法について説明します。必要に応じて、既存のフィルターを更新したり、新しいフィルターを作成したり、フィルターを削除したりできます。

前提条件

  • 管理 CLI にアクセスできる。
  • 管理コンソールにアクセスできる。
  • サーバー設定を変更する権限がある。

管理コンソールを使用してファイルハンドラーを管理する

管理コンソールを使用してフィルターを設定するには、ConfigurationSubsystemsWeb (Undertow)Filters に移動します。

管理 CLI を使用してファイルハンドラーを管理する

次の手順は、管理 CLI を使用してフィルターを設定する方法を示しています。

手順

  • 既存のフィルターの更新

    1. 管理 CLI へ接続します。
    2. フィルターの属性を更新するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=filter/response-header=myHeader:write-attribute(name=header-value,value="JBoss-EAP")
      ----
      Copy to Clipboard Toggle word wrap
    3. 変更を適用するには、サーバーをリロードします。

      ----
      reload
      ----
      Copy to Clipboard Toggle word wrap
  • 新規のフィルターの作成

    1. 管理 CLI へ接続します。
    2. 新しいフィルターを作成するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=filter/response-header=new-response-header:add(header-name=new-response-header,header-value="My Value")
      ----
      Copy to Clipboard Toggle word wrap
  • フィルターの削除

    1. 管理 CLI へ接続します。
    2. フィルターを削除するには、次のコマンドを実行します。

      ----
      /subsystem=undertow/configuration=filter/response-header=new-response-header:remove
      ----
      Copy to Clipboard Toggle word wrap
    3. 変更を適用するには、サーバーをリロードします。

      ----
      reload
      ----
      Copy to Clipboard Toggle word wrap
15.5.1.1. buffer-request ハンドラーの設定

クライアントまたはブラウザーからのリクエストは、ヘッダーとボディーの 2 つの部分で構成されます。通常の場合、ヘッダーとボディーの間に遅延がない状態で JBoss EAP に送信されます。しかし、ヘッダーが最初に送信され、その数秒後にボディーが送信されると、完全なリクエストの送信に遅延が発生します。このような場合、JBoss EAP にスレッドが作成され、完全なリクエストの実行を待機していることを示す waiting が表示されます。

リクエストのヘッダーおよびボティーの送信による遅延は、buffer-request ハンドラーを使用して修正できます。buffer-request ハンドラーは、ワーカースレッドに割り当てする前に、非ブロッキング IO スレッドからリクエストの消費を試みます。追加された buffer-request ハンドラーがない場合、スレッドは直接ワーカースレッドに割り当てられます。しかし、buffer-request ハンドラーが追加されると、ワーカースレッドに割り当てする前に、ハンドラーは IO スレッドを使用してブロックせずにバッファー処理できる量のデータを読み取ろうとします。

以下の管理 CLI コマンドを使用して buffer-request ハンドラーを設定できます。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. バッファー要求 ハンドラーを追加するには、次のコマンドを実行します。

       ----
       /subsystem=undertow/configuration=filter/expression-filter=buf:add(expression="buffer-request(buffers=1)")
       ----
    Copy to Clipboard Toggle word wrap
  2. 次のコマンドを実行して、ハンドラーをサーバーとホストに接続します。

       ----
       /subsystem=undertow/server=default-server/host=default-host/filter-ref=buf:add
       ----
    Copy to Clipboard Toggle word wrap
  3. バッファー要求サイズを計算します。

    `Total_size = num_buffers {MultiplicationSign} buffer_size`
    Copy to Clipboard Toggle word wrap
    Where:
    Copy to Clipboard Toggle word wrap
    • Total_size は、リクエストがワーカースレッドに送信される前にバッファー処理されるデータのサイズになります。
    • num_buffers は、ハンドラーの buffers パラメーターによって設定されるバッファーの数です (この例では 1 に設定されています)。
    • buffer_size は、io サブシステムで設定される各バッファーのサイズです (デフォルトはリクエストあたり 16 KB)。

      警告

      メモリー不足になる可能性があるため、サイズが大きすぎるバッファーリクエストは設定しないでください。

  4. 変更を適用するには、サーバーをリロードします。

       ----
       reload
       ----
    Copy to Clipboard Toggle word wrap
15.5.1.2. SameSite 属性について

SameSite 属性を使用して、同じサイト内での Cookie のアクセシビリティーを定義します。この属性は、ブラウザーがクロスサイトリクエストで Cookie を送信しないため、クロスサイトリクエストフォージェリー攻撃を防ぐのに役立ちます。

undertow サブシステムの SameSiteCookieHandler を使用して、Cookie の SameSite 属性を設定できます。この設定では、アプリケーションコードを変更する必要はありません。

15.5.1.3. SameSiteCookieHandler パラメーター

次の表は、SameSiteCookieHandler のパラメーターの詳細を示しています。

Expand
表15.4 SameSiteCookieHandler パラメーター
パラメーター名存在説明

add-secure-for-none

任意

SameSite 属性モードが None の場合、Cookie に Secure 属性を追加します。デフォルト値は true です。

case-sensitive

任意

cookie-pattern が大文字と小文字を区別するかどうかを示します。デフォルト値は true です。

cookie-pattern

任意

Cookie 名の正規表現パターンを受け入れます。指定されていない場合は、属性 SameSite=<specified-mode> がすべての Cookie に追加されます。

enable-client-checker

任意

クライアントアプリケーションが SameSite=None 属性と互換性がないかどうかを確認します。デフォルト値は true です。

このデフォルト値を使用し、SameSite 属性モードを None 以外の値に設定すると、パラメーターは検証を無視します。

互換性のないクライアントの問題を防ぐため、このパラメーターは SameSite 属性モードを None に設定をスキップするため、影響はありません。互換性のあるクライアントからのリクエストの場合、パラメーターは期待どおりに SameSite 属性モード None を適用します。

mode

必須

SameSite 属性モードを指定します。これは、StrictLax、または None に設定できます。

クロスサイトリクエストフォージェリー攻撃に対するセキュリティーを向上させるために、一部のブラウザーではデフォルトの SameSite 属性モードを Lax に設定します。詳細は、関連情報 セクションを参照してください。

SameSiteCookieHandler は、cookie-pattern に一致する Cookie に、または cookie-pattern が指定されていない場合はすべての Cookie に、属性 SameSite=<specified-mode> を追加します。cookie-pattern は、case-sensitive に設定された値に従って照合されます。

SameSite 属性を設定する前に、次の点を考慮してください。

  • アプリケーションを確認して、Cookie に SameSite 属性が必要かどうか、またそれらの Cookie を保護する必要があるかどうかを確認します。
  • すべての Cookie に対して SameSite 属性モードを None に設定すると、アプリケーションが攻撃を受けやすくなる可能性があります。
15.5.1.4. 式フィルターを使用して SameSiteCookieHandler を設定する

この手順では expression-filter を使用してサーバー上で SameSiteCookieHandler を設定する方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. SameSiteCookieHandler を使用して新しい expression-filter を作成します。

    ----
    /subsystem=undertow/configuration=filter/expression-filter=addSameSiteLax:add(expression="path-prefix('/mypathprefix') -> samesite-cookie(Lax)")
    ----
    Copy to Clipboard Toggle word wrap
  2. Undertow Web サーバーで 式フィルター を有効にします。

    ----
    /subsystem=undertow/server=default-server/host=default-host/filter-ref=addSameSiteLax:add
    ----
    Copy to Clipboard Toggle word wrap
15.5.1.5. 設定ファイルを使用して SameSiteCookieHandler を設定する

この手順では、undertow-handlers.conf ファイルを追加して、アプリケーションで SameSiteCookieHandler を設定する方法について説明します。

前提条件

  • アプリケーションのソースコードへのアクセス。
  • アプリケーションファイルを変更する権限。

手順

  1. WAR の WEB-INF ディレクトリーに undertow-handlers.conf ファイルを追加します。
  2. undertow-handlers.conf ファイルに、特定の SameSiteCookieHandler パラメーターを指定して次のコマンドを追加します。

    ----
    samesite-cookie(mode=<mode>)
    ----
    Copy to Clipboard Toggle word wrap
    Replace `<mode>` with one of the valid values: `Strict`, `Lax`, or `None`.
    Copy to Clipboard Toggle word wrap
    You can also configure other `SameSiteCookieHandler` parameters, such as `cookie-pattern`, `case-sensitive`, `enable-client-checker`, or `add-secure-for-none`.
    Copy to Clipboard Toggle word wrap
  3. ファイルを保存し、必要に応じてアプリケーションを再デプロイします。

15.6. デフォルトの Welcome Web アプリケーションの設定

JBoss EAP には、デフォルトではポート 8080 のルートコンテキストで表示されるデフォルトの Welcome アプリケーションが含まれます。

Undertow には、Welcome コンテンツに対応するデフォルトのサーバーが事前設定されています。

デフォルトの Undertow サブシステムの設定
<subsystem xmlns="{UndertowSubsystemNamespace}" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other">
    ...
    <server name="default-server">
        <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
    ...
    <handlers>
        <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
    </handlers>
</subsystem>
Copy to Clipboard Toggle word wrap

デフォルトのサーバー default-server にはデフォルトのホスト default-host が設定されています。デフォルトのホストは、welcome-content ファイルハンドラーで <location> 要素を使用して、サーバーのルートへのリクエストを処理するよう設定されています。welcome-content ハンドラーは path プロパティーに指定された場所でコンテンツを処理します。

このデフォルトの Welcome アプリケーションは、独自の Web アプリケーションで置き換えることができます。これは、以下の 2 つのいずれかの方法で設定できます。

Welcome コンテンツを無効 にすることもできます。

15.6.1. welcome-content ファイルハンドラーの変更

この手順では welcome-content ファイルハンドラーを変更して独自の Web アプリケーションを指すようにする方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. 既存の welcome-content ファイルハンドラーのパスを変更して、新しいコンテンツを指すようにします。

       ----
       /subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=path,value="/path/to/your/content")
       ----
    Copy to Clipboard Toggle word wrap

    または、サーバーのルートが使用する新しいファイルハンドラーを作成することもできます。

       ----
       /subsystem=undertow/configuration=handler/file=NEW_FILE_HANDLER:add(path="/path/to/your/content")
       /subsystem=undertow/server=default-server/host=default-host/location=\/:write-attribute(name=handler,value=NEW_FILE_HANDLER)
       ----
    Copy to Clipboard Toggle word wrap
  2. 変更を反映するためにサーバーをリロードします。

       ----
       reload
       ----
    Copy to Clipboard Toggle word wrap

15.6.2. デフォルトの Web モジュール の変更

この手順では default-web-module を変更して、デプロイされた Web アプリケーションをサーバーのルートにマップする方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. デプロイされた Web アプリケーションをサーバーのルートにマップします。

       ----
       /subsystem=undertow/server=default-server/host=default-host:write-attribute(name=default-web-module,value=your-application.war)
       ----
    Copy to Clipboard Toggle word wrap
  2. 変更を反映するためにサーバーをリロードします。
   ----
   reload
   ----
Copy to Clipboard Toggle word wrap

15.6.3. デフォルトの welcome Web アプリケーションを無効にする

この手順では、root context の location エントリーを削除して、デフォルトの welcome Web アプリケーションを無効にする方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. default-hostlocation エントリー / を削除します。

       ----
       /subsystem=undertow/server=default-server/host=default-host/location=\/:remove
       ----
    Copy to Clipboard Toggle word wrap
  2. 変更を反映するためにサーバーをリロードします。

       ----
       reload
       ----
    Copy to Clipboard Toggle word wrap

15.7. HTTP セッションタイムアウトの設定

HTTP セッションタイムアウトは、HTTP セッションの無効を宣言するために必要な非アクティブな期間を定義します。たとえば、ユーザーが JBoss EAP にデプロイされたアプリケーションにアクセスすると、HTTP セッションが作成されます。HTTP セッションのタイムアウト期間が経過した後にユーザーがアプリケーションに再度アクセスしようとすると、元の HTTP セッションは無効になり、ユーザーは新しい HTTP セッションを作成する必要があります。これにより、永続化されていないデータが失われたり、ユーザーの再認証が必要になる可能性があります。

HTTP セッションタイムアウトは通常、アプリケーションの web.xml ファイルで設定されます。ただし、JBoss EAP 内でデフォルトの HTTP セッションタイムアウトを指定することもできます。アプリケーションの web.xml ファイルによって上書きされない限り、サーバーのタイムアウト値はデプロイされたすべてのアプリケーションに適用されます。

サーバーの値は、undertow サブシステムの servlet-container セクション内の default-session-timeout プロパティーで指定されます。default-session-timeout の値は分単位で指定され、デフォルトは 30 です。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. 管理 CLI へ接続します。
  2. default-session-timeout 値を設定します。

    Run the following command to set the `default-session-timeout` value to `60` minutes:
    ----
    /subsystem=undertow/servlet-container=default:write-attribute(name=default-session-timeout, value=60)
    ----
    Copy to Clipboard Toggle word wrap
  3. 変更を反映するためにサーバーをリロードします。

    ----
    reload
    ----
    Copy to Clipboard Toggle word wrap

15.8. HTTP のみのセッション管理クッキーの設定

セッション管理クッキーは、JavaScript などの HTTP API および非 HTTP API の両方によってアクセスされます。JBoss EAP は HttpOnly ヘッダーを Set-Cookie 応答ヘッダーの一部としてクライアント (通常はブラウザー) に送信します。サポートされているブラウザーでは、このヘッダーを有効にすると、ブラウザーは非 HTTP API 経由でセッション管理 Cookie にアクセスできないようにします。セッション管理 Cookie を HTTP API のみに制限すると、クロスサイトスクリプティング攻撃によるセッション Cookie 盗難の脅威を軽減できます。この動作を有効にするには、http-only 属性を true に設定する必要があります。

重要

HttpOnly ヘッダーを使用しても、単にブラウザーに通知を行うだけで、クロスサイトスクリプティングによる攻撃を実際に防ぐわけではありません。この動作を有効にするには、ブラウザーも HttpOnly をサポートしている必要があります。

重要

http-only 属性を使用すると制限がセッション管理クッキーのみに適用され、その他のブラウザークッキーには適用されません。

http-only 属性は undertow サブシステムの 2 カ所で設定されます。

  • セッションクッキー設定としてサーブレットコンテナーで設定
  • 単一のサインオンプロパティーとしてサーバーのホストセクションで設定

15.8.2. ホストシングルサインオンの http のみの設定

この手順では、undertow サブシステムでホストシングルサインオンの http-only プロパティーを設定する方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. ホストにシングルサインオン設定を追加します。

    Run the following command:
    Copy to Clipboard Toggle word wrap
    ----
    /subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:add
    ----
    Copy to Clipboard Toggle word wrap
  2. http-only 属性を true に設定します。

    Run the following command:
    Copy to Clipboard Toggle word wrap
    ----
    /subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:write-attribute(name=http-only,value=true)
    ----
    Copy to Clipboard Toggle word wrap
  3. 変更を反映するためにサーバーをリロードします。

    ----
    reload
    ----
    Copy to Clipboard Toggle word wrap

15.9. Undertow における HTTP/2 について

Undertow では、HTTP/2 標準を使用できます。この標準は、ヘッダーの圧縮と多くのストリームの多重化を同じ TCP 接続で行い、待ち時間を削減します。さらに、リクエストの前にサーバーがリソースをクライアントにプッシュできる機能も提供するため、ページのロードがより速くなります。

HTTP/2 は、HTTP/2 標準をサポートするクライアントとブラウザーでのみ機能することに注意してください。

重要

最近のブラウザーのほとんどは、h2 と呼ばれるセキュリティーで保護された TLS 接続経由の HTTP/2 を強制し、h2c と呼ばれるプレーン HTTP 経由の HTTP/2 をサポートしていない可能性があります。HTTPS を使用せず、HTTP アップグレードでプレーン HTTP のみを使用して、h2c で HTTP/2 を使用するように JBoss EAP を設定できます。その場合は、HTTP リスナーで HTTP/2 を有効にするだけです。

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=enable-http2,value=true)
Copy to Clipboard Toggle word wrap

15.9.1. Undertow での HTTP/2 の設定

この手順では、HTTPS リスナーを設定して Undertow で HTTP/2 を有効にする方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. HTTPS リスナーで HTTP/2 を有効にします。

       ----
       /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enable-http2,value=true)
       ----
    Copy to Clipboard Toggle word wrap
  2. 変更を適用するには、サーバーをリロードします。

       ----
       reload
       ----
    Copy to Clipboard Toggle word wrap
注記

elytron サブシステムで HTTP/2 を使用するには、Undertow の https-listener にある設定済みの ssl-context が変更可能として設定される必要があります。これには、適切な server-ssl-contextwrap 属性を false に設定します。デフォルトでは wrap 属性は false に設定されます。これは、ALPN に関する ssl-context の変更を行うために Undertow で必要になります。提供された ssl-context が書き込み可能でない場合、ALPN は使用できず、接続は HTTP/1.1 にフォールバックします。

15.9.2. HTTP/2 使用時の ALPN サポート

セキュリティーで保護された TLS 接続を介して HTTP/2 を使用する場合は、アプリケーション層プロトコルネゴシエーション (ALPN) TLS プロトコル拡張をサポートする TLS スタックが必要です。このスタックの取得はインストールされた JDK によって異なります。

  • Java 9 より、JDK は ALPN をネイティブでサポートするようになりましたが、Java 9 以上を使用する場合でも OpenSSL プロバイダーからの ALPN TLS プロトコル拡張サポートを使用するとパフォーマンスが向上されるはずです。

ALPN TLS プロトコル拡張サポートを取得するために OpenSSL をインストールする手順は JBoss Core Services から OpenSSL をインストールする を参照してください。標準システムの OpenSSL は Red Hat Enterprise Linux 8 でサポートされており、追加の OpenSSL は必要ありません。

OpenSSL がインストールされたら、xref:"configure-jboss-eap-to-use-openssl_configuring-the-web-server-undertow-in-jboss-eap"[OpenSSL を使用するように JBoss EAP を設定する] の指示に従います。

15.9.3. HTTP/2 の使用状況の確認

Undertow が HTTP/2 を使用していることを検証するには、Undertow からのヘッダーを確認する必要があります。https を使用して JBoss EAP インスタンスに移動し (例: https://localhost:8443)、ブラウザーの開発者ツールを使用してヘッダーを確認します。Google Chrome などの一部のブラウザーは、HTTP/2 の使用時には :path:authority:method:scheme などの HTTP/2 擬似ヘッダーを表示します。Firefox や Safari などの他のブラウザーは、ヘッダーの状態またはバージョンを HTTP/2.0 と表示します。

15.10. RequestDumping ハンドラーについて

RequestDumping ハンドラーである、io.undertow.server.handlers.RequestDumpingHandler は、JBoss EAP 内で Undertow によって処理されるリクエストと対応するレスポンスオブジェクトの詳細をログに記録します。

重要

このハンドラーはデバッグに便利ですが、機密情報がログに記録される可能性があります。この点に留意してこのハンドラーを有効にしてください。

注記

RequestDumping ハンドラーは、JBoss EAP 6 の RequestDumperValve の代わりに使用されます。

RequestDumping ハンドラーは、JBoss EAP のサーバーレベルまたは個別のアプリケーション内のいずれかで設定できます。

15.10.1. サーバーでの RequestDumping ハンドラーの設定

この手順では、式フィルターを使用してサーバーレベルで RequestDumping ハンドラーを設定する方法について説明します。

前提条件

  • 管理 CLI にアクセスできる。
  • サーバー設定を変更する権限がある。

手順

  1. RequestDumping ハンドラーで新しい式フィルターを作成する

       ----
       /subsystem=undertow/configuration=filter/expression-filter=requestDumperExpression:add(expression="dump-request")
       ----
    Copy to Clipboard Toggle word wrap
  2. Undertow Web サーバーで式フィルターを有効にする

       ----
       /subsystem=undertow/server=default-server/host=default-host/filter-ref=requestDumperExpression:add
       ----
    Copy to Clipboard Toggle word wrap
重要

この方法で RequestDumping ハンドラーを式フィルターとして有効にすると、Undertow Web サーバーによって処理されるすべてのリクエストと対応するレスポンスがログに記録されます。

15.10.1.1. 特定の URL のハンドラーを設定する

すべてのリクエストをログに記録する他に、特定の URL のリクエストやそれらの応答のみをログに記録するために式フィルターを使用することもできます。これには、pathpath-prefixpath-suffix などの述語を式に使用します。たとえば、/myApplication/test へのリクエストとそれらの応答をすべてログに記録するには、式フィルターの作成時に式 "dump-request" の代わりに "path(/myApplication/test) -> dump-request" を使用します。これにより、/myApplication/test に完全一致するパスを持つリクエストのみが RequestDumping ハンドラーに送られます。

15.10.1.2. アプリケーション内での RequestDumping ハンドラーの設定

この手順では、個々のアプリケーション内で RequestDumping ハンドラーを設定する方法について説明します。これにより、ハンドラーのスコープはその特定のアプリケーションに制限されます。

手順

  1. アプリケーションで WEB-INF/undertow-handlers.conf ファイルを作成または編集します。
  2. このアプリケーションのすべてのリクエストと対応するレスポンスをログに記録するには、undertow-handlers.conf に次の行を追加します。

    ----
    dump-request
    ----
    Copy to Clipboard Toggle word wrap

    または、アプリケーション内の特定の URL のリクエストとレスポンスをログに記録するには、式で述語を使用します。

    Replace `/test` with the desired path relative to the application's context root.
    Copy to Clipboard Toggle word wrap
    [source]
    ----
    path(/test) -> dump-request
    ----
    Copy to Clipboard Toggle word wrap
    注記

    アプリケーションの WEB-INF/undertow-handlers.conf で定義された式で pathpath-prefixpath-suffix などの述語を使用する場合、使用される値はアプリケーションのコンテキストルートを基準とします。

    たとえば、アプリケーションのコンテキストルートが /myApplication で、式が path (/test) → dump-request としてを使用すると、/myApplication/test へのリクエストがログに記録されます。

  3. 変更を適用する必要がある場合は、アプリケーションを再デプロイします。

第16章 remoting と接続の設定

リモートサブシステムを設定し、JBoss EAP 内でさまざまな接続タイプを管理できます。これには、サーバーとアプリケーション間の通信を容易にするためのエンドポイント、コネクター、および送信接続の設定が含まれます。HTTP コネクター、リモートおよびローカルの送信接続を設定し、追加のリモート設定オプションを検討することができ、JBoss EAP で remoting と接続を効果的に管理するために必要なツールが提供されます。

16.1. Remoting サブシステムの設定

remoting サブシステムは、ローカルサービスとリモートサービスの受信接続と送信接続の設定を行います。

JBoss EAP remoting サブシステムには、設定可能な要素がいくつか含まれています。

ほとんどのユースケースでは、remoting サブシステムを設定する必要はありません。ただし、アプリケーションでカスタムコネクターを使用する場合は、そのコネクターを設定する必要があります。Jakarta Enterprise Beans などの、リモーティングクライアントとして動作するアプリケーションには特定のコネクターに接続するための別の設定が必要になります。

デフォルトの remoting サブシステムの設定は次のとおりです。

<subsystem xmlns="urn:jboss:domain:remoting:4.0">
    <endpoint worker="default"/>
    <http-connector name="http-remoting-connector"
                    connector-ref="default"
                    sasl-authentication-factory="application-sasl-authentication"/>
</subsystem>
Copy to Clipboard Toggle word wrap

16.1.1. remoting エンドポイント

リモーティングエンドポイントは、io サブシステムによって宣言および設定される XNIO ワーカーを使用します。このワーカーは非ブロッキング I/O 操作を容易にし、リモート接続のパフォーマンスとスケーラビリティーを強化します。

16.1.2. http-connector 設定要素

http-connector 要素は、undertow の HTTP アップグレード機能を使用して外部クライアントがサーバーに接続できるようにするデフォルトの設定要素です。

この設定では、クライアントは最初に HTTP プロトコルを使用してサーバーとの接続を確立し、次に同じ接続を介して remote プロトコルに切り替えます。これにより、異なるプロトコルを使用するクライアントが undertow のデフォルトポート 8080 などの同じポート経由で接続できるようになり、サーバー上で開放されているポートの数が削減されます。

HTTP アップグレードを使用してサーバーに接続する必要があるクライアントは、暗号化されていない接続の場合はリモート remote+https プロトコルを使用し、暗号化された接続の場合は、remoting remote+https プロトコルを使用する必要があります。

16.1.3. 送信接続

remoting サブシステムの送信接続により、アプリケーションは外部リソースと通信できるようになります。

3 つのタイプの送信接続を指定することができます。

16.2. エンドポイントの設定

JBoss EAP で remoting エンドポイントを設定して、アプリケーションの接続を確立できます。JBoss EAP には、管理 CLI コマンドを使用して更新できるデフォルトのエンドポイント設定が含まれています。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • エンドポイント設定を指定して、特殊なサービスまたは環境に合わせて通信をカスタマイズします。たとえば、認証とセキュリティー設定を調整して、管理トラフィックを通常のアプリケーショントラフィックから分離できます。
  • セキュリティーまたはパフォーマンスの要件を満たすように既存のエンドポイント設定を更新します。たとえば、認証の再試行やタイムアウトなどの設定を調整することで、セキュリティーが向上し、さまざまな負荷下で最適なパフォーマンスを確保できます。
重要

JBoss EAP 8.0 では、remoting サブシステムの endpoint 設定は、io サブシステムのワーカーを使用します。このワーカーは、remoting 操作のスレッドプールを管理します。

JBoss EAP によって提供されるデフォルトの endpoint 設定は次のとおりです。

<subsystem xmlns="urn:jboss:domain:remoting:4.0">
  <endpoint worker="default"/>
  ...
</subsystem>
Copy to Clipboard Toggle word wrap

前提条件

  • JBoss EAP が実行中である。

手順

  1. 次のコマンドを使用して、既存のエンドポイント設定を更新します。

    /subsystem=remoting:write-attribute(name=authentication-retries,value=2)
    Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap

16.3. HTTP コネクターの設定

JBoss EAP で HTTP コネクターを設定し、HTTP アップグレードベースのリモートプロトコルを使用して接続を確立できます。JBoss EAP は、管理 CLI コマンドを使用して簡単に更新、作成、または削除できるデフォルトの HTTP コネクター設定を提供します。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • HTTP アップグレードベースの remoting プロトコルを使用してリモート通信を確立するための新しい HTTP コネクターを作成します。これにより、JBoss EAP サービスへの安全かつ効率的なリモートアクセスが可能になります。
  • 既存の HTTP コネクターを更新して、パフォーマンスを最適化したり、セキュリティーを強化したり、特定のネットワーク設定と統合したりします。認証メカニズムや接続タイムアウトなどの属性を調整すると、信頼性が向上し、セキュリティーポリシーへの準拠が確保されます。
  • 不要な HTTP コネクターを削除して設定を簡素化し、セキュリティーリスクを軽減します。使用されていないコネクターを削除すると、不正アクセスのリスクを最小限に抑え、クリーンかつ安全な環境を維持できます。

JBoss EAP によって提供されるデフォルトの http-connector 設定は次のとおりです。

<subsystem xmlns="urn:jboss:domain:remoting:4.0">
    ...
    <http-connector name="http-remoting-connector"
                    connector-ref="default"
                    sasl-authentication-factory="application-sasl-authentication"/>
</subsystem>
Copy to Clipboard Toggle word wrap

デフォルトでは、この HTTP コネクターは、undertow サブシステムで設定されている default という名前の HTTP リスナーに接続します。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 次のコマンドを使用して、新しい HTTP コネクターを作成します。

    /subsystem=remoting/http-connector=new-connector:add(connector-ref=new-connector-ref)
    Copy to Clipboard Toggle word wrap
    注記

    別のコネクターでまだ使用されていない一意の connector-ref を使用する必要があります。connector-ref は、Undertow 内の新規または未使用のコネクターを指す必要があります。または、代わりに定義済みの https コネクターを使用することもできます。

  2. 次のコマンドを使用して、既存の HTTP コネクター設定を更新します。

    /subsystem=remoting/http-connector=new-connector:write-attribute(name=connector-ref,value=new-connector-ref)
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap
  4. 必要に応じて、次のコマンドを使用して HTTP コネクターを削除します。

    /subsystem=remoting/http-connector=new-connector:remove
    Copy to Clipboard Toggle word wrap

16.4. 送信接続の設定

JBoss EAP で送信接続を設定して、URI で指定された汎用リモート送信接続を確立できます。これにより、アプリケーションは外部サービスと効率的に通信できるようになります。

管理 CLI コマンドを使用して設定を更新、作成、または削除することで、これらの接続を簡単に管理できます。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • 外部サービスとの通信を確立するための新しい送信接続を作成します。これにより、リモートシステムとのシームレスなデータ交換と統合が可能になります。
  • 既存の送信接続を更新して、パフォーマンスの向上、セキュリティーの強化、またはネットワーク設定との整合を図ります。ターゲット URI などの属性を調整すると、信頼性が向上し、システム要件との互換性が確保されます。
  • 不要な送信接続を削除して、設定を合理化し、セキュリティーリスクを減らします。使用されていない接続を削除すると、不正アクセスのリスクを最小限に抑え、クリーンかつ安全な環境を維持できます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 以下のコマンドを使用して、新しい送信接続を作成します。

    /subsystem=remoting/outbound-connection=new-outbound-connection:add(uri=http://example.com)
    Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを使用して、既存の送信接続を更新します。

    /subsystem=remoting/outbound-connection=new-outbound-connection:write-attribute(name=uri,value=http://example.com)
    Copy to Clipboard Toggle word wrap
  3. 必要に応じて、次のコマンドを使用して送信接続を削除します。

    /subsystem=remoting/outbound-connection=new-outbound-connection:remove
    Copy to Clipboard Toggle word wrap
  4. 次のコマンドを使用して、送信接続を削除した後、サーバーをリロードして変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap

16.5. リモート送信接続の設定

プロトコル、送信ソケットバインディング、ユーザー名、およびセキュリティーレルムを使用して、リモート送信接続を指定できます。プロトコルは、remotehttp-remoting、または https-remoting を指定できます。管理 CLI コマンドを使用して設定を更新、作成、または削除して、これらの接続を簡単に管理できます。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • 外部サービスとの安全な通信を可能にするために、新しいリモート送信接続を作成します。これにより、アプリケーションは指定されたプロトコルと認証方法を使用してリモートシステムと対話できるようになります。
  • 既存のリモート送信接続を更新して、セキュリティーを強化したり、パフォーマンスを改善したり、特定のネットワーク設定と統合したりします。送信ソケットバインディングや認証設定などの属性を調整することで、安定性とセキュリティーポリシーへの準拠が確保されます。
  • 不要なリモート送信接続を削除して設定を簡素化し、セキュリティーリスクを軽減します。使用されていない接続を削除すると、不正アクセスのリスクを最小限に抑え、クリーンかつ安全な環境を維持できます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 次のコマンドを使用して、新しいリモート送信接続を作成します。

    /subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
    Copy to Clipboard Toggle word wrap
    注記

    これらのコマンドを実行する前に、設定で outbound-socket-binding が定義されていることを確認してください。詳細は、アウトバウンドソケットバインディング を参照してください。

  2. 次のコマンドを使用して、既存のリモート送信接続を更新します。

    /subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
    Copy to Clipboard Toggle word wrap
  3. 必要に応じて、次のコマンドを使用してリモート送信接続を削除できます。

    /subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:remove
    Copy to Clipboard Toggle word wrap

16.6. ローカル送信接続の設定

送信ソケットバインディングのみを使用して、ローカル送信接続をプロトコル local のリモート送信接続として指定できます。管理 CLI コマンドを使用して設定を更新、作成、または削除して、これらの接続を簡単に管理できます。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • 同じサーバーインスタンス内で安全かつ効率的な通信を可能にするために、新しいローカル送信接続を作成します。これにより、外部ネットワークを必要とせずに内部のやり取りを効率化できます。
  • 既存のローカル送信接続を更新して、パフォーマンスを向上したり、ソケットバインディングを変更したり、特定の設定に合わせたりします。送信ソケットバインディングなどの属性を調整することで、安定性と互換性が確保されます。
  • 不要なローカル送信接続を削除して設定を簡素化し、セキュリティーリスクを軽減します。使用されていない接続を削除すると、不正アクセスのリスクを最小限に抑え、クリーンかつ安全な環境を維持できます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 次のコマンドを使用して、新しいローカル送信接続を作成します。

    /subsystem=remoting/local-outbound-connection=new-local-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
    Copy to Clipboard Toggle word wrap
    注記

    これらのコマンドを実行する前に、設定で outbound-socket-binding が定義されていることを確認してください。詳細は、以下を参照してください。

  2. 次のコマンドを使用して、既存のローカル送信接続を更新します。

    /subsystem=remoting/local-outbound-connection=new-local-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
    Copy to Clipboard Toggle word wrap
  3. 必要に応じて、次のコマンドを使用してローカル送信接続を削除できます。

    /subsystem=remoting/local-outbound-connection=new-local-outbound-connection:remove
    Copy to Clipboard Toggle word wrap

16.7. 追加の remoting 設定

remoting サブシステム外部に接続されるリモーティング要素が複数あります。

JBoss EAP 管理者または開発者は、次の操作を行う必要がある場合があります。

  • パフォーマンスを向上させ、remoting タスクを効率的に管理するには、remoting 用の IO ワーカーを設定します。ワーカーが IO サブシステムで定義されていることを確認します。
  • ネットワークインターフェイスの設定を変更して、remoting を必要なパブリックインターフェイス、管理インターフェイス、または安全でないインターフェイスと一致させます。正しいインターフェイスを設定すると、適切な接続が確保されます。
  • remoting サブシステムのソケットバインディングを調整して適切なポートを指定し、ネットワークおよびセキュリティーポリシーとの互換性を維持します。
  • remoting 通信を保護するために、STARTTLS を使用して安全なトランスポートを有効にします。中間者攻撃などのセキュリティーリスクを防ぐために、設定で安全な接続が検証されていることを確認します。

    IO ワーカー

    以下のコマンドを使用してリモーティングの IO ワーカーを設定します。このコマンドを実行する前に、ワーカーが IO サブシステムで定義されていることを確認してください。

    /subsystem=remoting:write-attribute(name=worker, value=WORKER_NAME)
    Copy to Clipboard Toggle word wrap
    ネットワークインターフェイス

    remoting サブシステムによって使用されるネットワークインターフェイスは public インターフェイスです。このインターフェイスは他のサブシステムでも使用されるため、変更する際には注意してください。

    <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>
       <interface name="unsecure">
          <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
       </interface>
    </interfaces>
    Copy to Clipboard Toggle word wrap

    マネージドドメインでは、public インターフェイスはホストごとに host.xml ファイルで定義されます。

    ソケットバインディング
    remoting サブシステムのデフォルトのソケットバインディングはポート 8080 にバインドされます。
    セキュアなトランスポート設定
    remoting トランスポートは、クライアントが要求した場合、STARTTLS を使用して HTTPS や Secure Servlet などのセキュアな接続を確立します。セキュアな接続とセキュアでない接続の両方で同じソケットバインディングまたはネットワークポートが使用されるため、サーバー側に追加の設定をする必要はありません。クライアントは必要に応じて、セキュアなトランスポートまたはセキュアでないトランスポートを要求します。Jakarta Enterprise Beans、ORB、Jakarta Messaging プロバイダーなど、リモーティングを使用する JBoss EAP コンポーネントは、デフォルトでセキュアなインターフェイスを要求します。
警告

STARTTLS はクライアントの要求があればセキュアな接続を有効にしますが、セキュアでない接続がデフォルトになります。これは本質的に中間者攻撃からの影響を受けやすく、攻撃者がクライアントのリクエストを傍受して改ざんし、安全でない接続を要求させる可能性があります。セキュアでない接続が適切なフォールバックである場合を除き、クライアントがセキュアな接続を取得できなかったときに適切に失敗するよう記述する必要があります。

第17章 IO サブシステムの設定

JBoss EAP で io サブシステムを設定すると、システムパフォーマンスが向上し、アプリケーション操作がサポートされます。XNIO ワーカーおよびバッファープールを管理することで、Undertow や Remoting などのサブシステムに最適な機能を確保できます。これらのコンポーネントを適切に調整すると、アプリケーション内で効率的なデータ処理と応答性が可能になります。

17.1. IO サブシステムの設定

io サブシステムは、Undertow や Remoting などの他のサブシステムによって使用される XNIO ワーカーバッファープール を定義します。

これらのワーカーおよびバッファープールは、以下の CLI コマンドを使用して io サブシステムで定義されます。

/subsystem=io/worker=*
/subsystem=io/buffer-pool=*
Copy to Clipboard Toggle word wrap

この設定は、io サブシステムのデフォルトのセットアップを表します。io サブシステムのデフォルト設定を表示するには、以下の CLI コマンドを実行します。

/subsystem=io/:read-resource(recursive=true)
Copy to Clipboard Toggle word wrap

17.2. ワーカーの設定

JBoss EAP でワーカーを設定して、IO タスクとワーカースレッドを効率的に管理できます。ワーカーは XNIO ワーカーインスタンスとして機能し、Java NIO API およびサポート対象 SSL の抽象化層を提供します。

ワーカーは、IO 操作を管理してタスクを調整し、データの送受信の要求を効率的に処理できるようにします。これらのタスクは、IO スレッドプールに保持される一連のスレッドによって処理されます。

デフォルトでは、JBoss EAP には default という名前の単一のワーカーが含まれています。必要に応じて追加のワーカーを定義できます。複数のワーカーを作成する場合、追加のワーカーごとに個別の IO スレッドプールが作成され、リソースの使用率に影響を与える可能性があることに注意してください。

ワーカーにスレッドサイズが指定されていない場合、JBoss EAP は利用可能な CPU コアの数に基づいてデフォルト値を計算します。設定オプションは以下のとおりです。

  • io-threads: ワーカーに作成する IO スレッドの数を指定します。指定しない場合、デフォルトは cpuCount * 2 として計算されます。
  • task-max-threads: ワーカータスクスレッドプールの最大スレッド数を指定します。指定されていない場合、デフォルト値は cpuCount * 16 として計算されます。

管理 CLI コマンドを使用してワーカーを管理し、設定の更新、作成、または削除を行うことができます。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 以下のコマンドを使用して、既存のワーカーを更新します。

    /subsystem=io/worker=default:write-attribute(name=io-threads,value=10)
    Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して、新規ワーカーを作成します。

    /subsystem=io/worker=newWorker:add
    Copy to Clipboard Toggle word wrap
  4. 必要に応じて、以下のコマンドを使用して、ワーカーを削除できます。

    /subsystem=io/worker=newWorker:remove
    Copy to Clipboard Toggle word wrap
  5. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap

17.3. バッファープールの設定

JBoss EAP でバッファープールを設定して、プールされた NIO バッファーインスタンスを管理できます。これは、アプリケーションのパフォーマンスにおいて重要な役割を果たします。既存のバッファープールを更新して新しいバッファープールを作成したり、システム効率を最適化するために必要なくなったバッファープールを削除したりできます。

注記

IO バッファープールは非推奨となっていますが、現行リリースではデフォルト設定のままです。バッファープールはプールされた NIO バッファーインスタンスです。バッファーサイズを変更すると、アプリケーションのパフォーマンスに大きく影響します。通常、ほとんどのサーバーでは 16k が理想のバッファーサイズになります。詳細は、JBoss EAP の 設定ガイドバイトバッファープールの設定 を参照してください。詳細は、Add lightweight global buffer pool API; deprecate heavier API を参照してください。以前のバッファープール API の非推奨化と、Undertow サブシステムバッファープールへの置き換えについて説明されています。

前提条件

  • JBoss EAP が実行中である。

手順

  1. 以下のコマンドを使用して、既存のバッファープールを更新します。

    /subsystem=io/buffer-pool=default:write-attribute(name=direct-buffers,value=true)
    Copy to Clipboard Toggle word wrap
  2. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して、新しいバッファープールを作成します。

    /subsystem=io/buffer-pool=newBuffer:add
    Copy to Clipboard Toggle word wrap
  4. 必要に応じて、以下のコマンドを使用して、バッファープールを削除できます。

    /subsystem=io/buffer-pool=newBuffer:remove
    Copy to Clipboard Toggle word wrap
  5. 以下のコマンドを使用して、サーバーをリロードし、変更を適用します。

    reload
    Copy to Clipboard Toggle word wrap

17.4. IO サブシステムのパフォーマンスチューニング

io サブシステムのパフォーマンスを最適化および監視して、効率的なリソース管理および応答性を確保できます。通常の監視は、システムパフォーマンスに影響を与える前に潜在的な問題を特定するのに役立ちます。

17.5. ワーカーの設定

ワーカーは XNIO ワーカーインスタンスです。XNIO ワーカーインスタンスは、IO およびワーカースレッドの管理や SSL サポートなどの機能を提供する Java NIO API の抽象化レイヤーです。JBoss EAP はデフォルトで default という単一のワーカーを提供しますが、複数のワーカーを定義できます。

既存のワーカーの更新

既存のワーカーを更新するには、以下を指定します。

/subsystem=io/worker=default:write-attribute(name=io-threads,value=10)
Copy to Clipboard Toggle word wrap
reload
Copy to Clipboard Toggle word wrap
新規ワーカーの作成

新規ワーカーを作成するには、以下を指定します。

/subsystem=io/worker=newWorker:add
Copy to Clipboard Toggle word wrap
ワーカーの削除

ワーカーを削除するには、以下を指定します。

/subsystem=io/worker=newWorker:remove
Copy to Clipboard Toggle word wrap
reload
Copy to Clipboard Toggle word wrap

ワーカーの設定に使用できる属性の完全リストは IO サブシステムの属性 の項を参照してください。

17.6. バッファープールの設定

注記

IO バッファープールは非推奨となっていますが、現行リリースではデフォルトとして設定されています。バッファープールはプールされた NIO バッファーインスタンスです。バッファーサイズの変更はアプリケーションのパフォーマンスに大きく影響します。通常、ほとんどのサーバーでは 16K が理想のバッファーサイズになります。Undertow バイトバッファープールの設定の詳細は、JBoss EAP 設定ガイドUndertow バイトバッファープール を参照してください。

既存のバッファープールの更新

既存のバッファープールを更新するには、以下を指定します。

/subsystem=io/buffer-pool=default:write-attribute(name=direct-buffers,value=true)
Copy to Clipboard Toggle word wrap
reload
Copy to Clipboard Toggle word wrap
バッファープールの作成

新しいバッファープールを作成するには、以下を指定します。

/subsystem=io/buffer-pool=newBuffer:add
Copy to Clipboard Toggle word wrap
バッファープールの削除

バッファープールを削除するには、以下を指定します。

/subsystem=io/buffer-pool=newBuffer:remove
Copy to Clipboard Toggle word wrap
reload
Copy to Clipboard Toggle word wrap

バッファープールの設定に使用できる属性の完全リストは IO サブシステムの属性 の項を参照してください。

17.7. IO サブシステムのチューニング

io サブシステムのパフォーマンスを監視および最適化するためのヒントは、JBoss EAP のパフォーマンスチューニングIO サブシステムのチューニング セクションを参照してください。

第18章 JBoss EAP の Web サービス設定

JBoss EAP では、管理コンソールまたは管理 CLI を使用して webservices サブシステム経由でデプロイされた Web サービスの動作を設定できます。この設定は Jakarta Web Services (JAX-WS)エンドポイントに適用され、パブリッシュされたエンドポイントアドレス、ハンドラーチェーン、および Web サービスのランタイム統計収集を設定できます。

第19章 Jakarta Server Faces の設定

jsf サブシステムでは、複数の Jakarta Server Faces 実装を同じ JBoss EAP サーバーインスタンスにインストールできます。Jakarta Server Faces 4.0 以降の仕様を実装する Sun Mojarra または Apache MyFaces のバージョンをインストールできます。機能パックは、Apache MyFaces 実装のインストールにのみ使用できます。

注記

JBoss EAP に含まれる Jakarta Server Faces 実装のみが完全サポートされます。

19.1. Jakarta Server Faces 実装のインストール

JBoss EAP は、必要な機能のみを含むサーバーのプロビジョニングをサポートできるように、JBoss EAP Installation Manager を使用し、機能パックとしてこれらの機能を提供します。

前提条件

  • JBoss EAP がインストールされている。

手順

  1. 以下の内容を含む myfaces-manifest.yaml ファイルを作成します。

    schemaVersion: "1.0.0"
    name: "MyFaces manifest"
    id: "myfaces"
    streams:
      - groupId: "org.apache.myfaces.core"
        artifactId: "myfaces-api"
        version: "4.0.2"
      - groupId: "org.apache.myfaces.core"
        artifactId: "myfaces-impl"
        version: "4.0.2"
    Copy to Clipboard Toggle word wrap
  2. 次のコマンドを使用して MyFaces マニフェストを追加します。

    $JBOSS_HOME/bin/jboss-eap-installation-manager.sh channel add \
      --channel-name=myfaces \
      --manifest=myfaces-manifest.yaml \
      --repositories=https://repo1.maven.org/maven2/
    Copy to Clipboard Toggle word wrap
  3. 以下のコマンドを使用して MyFaces Maven マニフェストをローカル Maven リポジトリーにデプロイします。

    mvn deploy:deploy-file -Dfile=myfaces-manifest.yaml \
      -DgroupId=org.apache.myfaces.channel -DartifactId=myfaces \
      -Dclassifier=manifest -Dpackaging=yaml -Dversion=4.0.2 \
      -Durl=file://$HOME/.m2/repository
    Copy to Clipboard Toggle word wrap
  4. 以下のコマンドを使用し、MyFaces 機能パックを使用してサーバーをプロビジョニングします。

    $JBOSS_HOME/bin/jboss-eap-installation-manager.sh fp add \
      --fpl=org.jboss.eap:eap-myfaces-feature-pack \
      --layers=myfaces
    Copy to Clipboard Toggle word wrap
  5. サービスを起動します。

検証

  • 以下の CLI コマンドを使用して、新しい Jakarta Server Faces 実装が正常にインストールされていることを確認します。

    [standalone@localhost:9990 /] /subsystem=jsf:list-active-jsf-impls()
    Copy to Clipboard Toggle word wrap

19.2. デフォルトの Jakarta Server Faces 実装の変更

マルチ Jakarta Server Faces 機能には jsf サブシステムに default-jsf-impl-slot 属性が含まれており、デフォルトの Jakarta Server Faces 実装を変更できます。

前提条件

  • サーバーに複数の Jakarta Server Faces 実装がインストールされている。

手順

  1. write-attribute コマンドを使用して、default-jsf-impl-slot 属性の値をアクティブな Jakarta Server Faces 実装の 1 つに設定します。

    /subsystem=jsf:write-attribute(name=default-jsf-impl-slot,value=JSF_IMPLEMENTATION)
    Copy to Clipboard Toggle word wrap

    JSF_IMPLEMENTATION は、デフォルトとして設定する Jakarta Server Faces 実装の名前に置き換えます。

  2. 変更を反映するために、JBoss EAP サーバーを再起動します。

    reload
    Copy to Clipboard Toggle word wrap

検証

  • 以下のコマンドを使用して、利用可能な Jakarta Server Faces 実装を特定します。

    /subsystem=jsf:read-attribute(name=default-jsf-impl-slot)
    Copy to Clipboard Toggle word wrap
    予想される出力
    {
        "outcome" => "success",
        "result" => "myfaces"
    }
    Copy to Clipboard Toggle word wrap

19.3. デフォルト以外の実装のための Jakarta Server Faces アプリケーション設定

デフォルト以外の Jakarta Server Faces 実装を使用するよう Jakarta Server Faces アプリケーションを設定するには、org.jboss.jbossfaces.JSF_CONFIG_NAME コンテキストパラメーターを web.xml ファイルに追加します。このパラメーターは、アプリケーションのデプロイ時に指定された Jakarta Server Faces 実装を適用するように jsf サブシステムに指示します。

たとえば、アプリケーションで MyFaces 4.0.0 を使用する場合は、web.xml ファイルに以下のコンテキストパラメーターを追加します。

<context-param>
    <param-name>org.jboss.jbossfaces.JSF_CONFIG_NAME</param-name>
    <param-value>myfaces-4.0.0</param-value>
</context-param>
Copy to Clipboard Toggle word wrap

Jakarta Server Faces アプリケーションにこのコンテキストパラメーターが含まれていない場合、'jsf' サブシステムはデフォルトの Jakarta Server Faces 実装を使用します。

19.4. DOCTYPE 宣言の拒否

Jakarta Server Faces デプロイメントの DOCTYPE 宣言を拒否するように jsf サブシステムを設定できます。この設定により、外部エンティティーの使用を防ぐことでセキュリティーが向上します。

前提条件

  • jsf サブシステムを設定する管理 CLI アクセス権がある。

手順

  1. 以下のコマンドを使用して、すべての Jakarta Server Faces デプロイメントの DOCTYPE 宣言を拒否します。

    /subsystem=jsf:write-attribute(name=disallow-doctype-decl, value=true)
    Copy to Clipboard Toggle word wrap
  2. JBoss EAP サーバーを再起動し、変更を反映します。

    reload
    Copy to Clipboard Toggle word wrap
  3. 特定の Jakarta Server Faces デプロイメントで DOCTYPE 宣言を許可するには、以下の設定で com.sun.faces.disallowDoctypeDecl コンテキストパラメーターをデプロイメントの web.xml ファイルに追加します。

    <context-param>
        <param-name>com.sun.faces.disallowDoctypeDecl</param-name>
        <param-value>false</param-value>
    </context-param>
    Copy to Clipboard Toggle word wrap

第20章 バッチアプリケーションの設定

JBoss EAP 8.0 は Jakarta Batch をサポートします。バッチアプリケーションを実行するための環境を設定し、batch-jberet サブシステムを使用してバッチジョブを管理できます。

バッチアプリケーションの開発に関する詳細は、JBoss EAP 開発ガイドJakarta バッチアプリケーション開発 を参照してください。

20.1. バッチジョブの設定

JBeret 実装を基にした batch-jberet サブシステムを使用してバッチジョブを設定できます。

デフォルトの batch-jberet サブシステム設定は、インメモリージョブリポジトリーとデフォルトのスレッドプールの設定を定義します。

<subsystem xmlns="{BatchSubsystemNamespace}">
    <default-job-repository name="in-memory"/>
    <default-thread-pool name="batch"/>
    <job-repository name="in-memory">
        <in-memory/>
    </job-repository>
    <thread-pool name="batch">
        <max-threads count="10"/>
        <keepalive-time time="30" unit="seconds"/>
    </thread-pool>
</subsystem>
Copy to Clipboard Toggle word wrap

デフォルトでは、サーバーの一時停止中に停止したバッチジョブはサーバーの再開時に再度開始されます。restart-jobs-on-resume プロパティーを false に設定すると STOPPED 状態のジョブをそのままにすることができます。

/subsystem=batch-jberet:write-attribute(name=restart-jobs-on-resume,value=false)
Copy to Clipboard Toggle word wrap

バッチ ジョブリポジトリー および スレッドプール を設定することもできます。

20.1.1. バッチジョブリポジトリーの設定

このセクションでは、管理 CLI を使用してバッチジョブ情報を保存するインメモリーおよび JDBC ジョブリポジトリーを設定する方法を説明します。管理コンソールでは、ConfigurationSubsystemsBatch (JBeret) と選択し、表示 をクリックして左側のメニューで In Memory または JDBC のいずれかを選択すると、ジョブリポジトリーを設定することができます。

インメモリージョブリポジトリーの追加

バッチジョブ情報をメモリーに保存するジョブリポジトリーを追加できます。

/subsystem=batch-jberet/in-memory-job-repository=REPOSITORY_NAME:add
Copy to Clipboard Toggle word wrap
JDBC ジョブリポジトリーの追加

バッチジョブ情報をデータベースに保存するジョブリポジトリーを追加できます。データソースの名前を指定してデータベースに接続する必要があります。

/subsystem=batch-jberet/jdbc-job-repository=REPOSITORY_NAME:add(data-source=DATASOURCE)
Copy to Clipboard Toggle word wrap

データソースの詳細は、JBoss EAP データソースについて を参照してください。

デフォルトのジョブリポジトリーの設定

インメモリーまたは JDBC ジョブリポジトリーをバッチアプリケーションのデフォルトのジョブリポジトリーとして設定できます。

/subsystem=batch-jberet:write-attribute(name=default-job-repository,value=REPOSITORY_NAME)
Copy to Clipboard Toggle word wrap

サーバーをリロードする必要があります。

reload
Copy to Clipboard Toggle word wrap

20.1.2. バッチスレッドプールの設定

このセクションでは、管理 CLI を使用してバッチジョブに使用するスレッドプールとスレッドファクトリーを設定する方法を説明します。管理コンソールでは、ConfigurationSubsystemsBatch (JBeret) と選択し、表示 をクリックして左側のメニューで Thread Factory または Thread Pool のいずれかを選択すると、スレッドプールとスレッドファクトリーを設定できます。

スレッドプールの設定

スレッドプールを追加するときに max-threads を指定する必要があります。パーティションのジョブが想定どおりに実行されるように 2 つのスレッドが予約されているため、3 よりも大きい値を常に設定してください。

手順

  1. スレッドプールを追加します。

    /subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:add(max-threads=10)
    Copy to Clipboard Toggle word wrap
  2. 必要な場合は keepalive-time の値を設定します。

    /subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:write-attribute(name=keepalive-time,value={time=60,unit=SECONDS})
    Copy to Clipboard Toggle word wrap
スレッドファクトリーの使用

手順

  1. スレッドファクトリーを追加します。

    /subsystem=batch-jberet/thread-factory=THREAD_FACTORY_NAME:add
    Copy to Clipboard Toggle word wrap
  2. スレッドファクトリーの属性を設定します。

    • group-name - このスレッドファクトリーに作成するスレッドグループの名前。
    • priority - 作成されたスレッドの優先度。
    • thread-name-pattern - スレッドの名前の作成に使用されるテンプレート。以下のパターンを使用できます。

      • %% - パーセント記号
      • %t - ファクトリーごとのスレッドシーケンス番号
      • %g - グローバルスレッドシーケンス番号
      • %f - ファクトリーシーケンス番号
      • %i - スレッド ID
  3. スレッドファクトリーをスレッドプールに割り当てます。

    /subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:write-attribute(name=thread-factory,value=THREAD_FACTORY_NAME)
    Copy to Clipboard Toggle word wrap

    サーバーをリロードする必要があります。

    reload
    Copy to Clipboard Toggle word wrap
デフォルトスレッドプールの設定

別のスレッドプールをデフォルトのスレッドプールとして設定できます。

/subsystem=batch-jberet:write-attribute(name=default-thread-pool,value=THREAD_POOL_NAME)
Copy to Clipboard Toggle word wrap

サーバーをリロードする必要があります。

reload
Copy to Clipboard Toggle word wrap
スレッドプールの統計の表示

read-resource 管理 CLI 操作を使用するとバッチスレッドプールのランタイム情報を表示できます。このランタイム情報を表示するには include-runtime=true パラメーターを使用する必要があります。

/subsystem=batch-jberet/thread-pool=THREAD_POOL_NAME:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "active-count" => 0,
        "completed-task-count" => 0L,
        "current-thread-count" => 0,
        "keepalive-time" => undefined,
        "largest-thread-count" => 0,
        "max-threads" => 15,
        "name" => "THREAD_POOL_NAME",
        "queue-size" => 0,
        "rejected-count" => 0,
        "task-count" => 0L,
        "thread-factory" => "THREAD_FACTORY_NAME"
    }
}
Copy to Clipboard Toggle word wrap

管理コンソールの Runtime タブで Batch サブシステムを選択して、バッチスレッドプールのランタイム情報を表示することもできます。

20.2. バッチジョブの管理

デプロイメントの batch-jberet サブシステムリソースを使用すると、バッチジョブを起動、停止、および再起動でき、実行詳細を表示することもできます。バッチジョブは 管理 CLI または 管理コンソール から管理できます。

管理 CLI からのバッチジョブの管理
バッチジョブの再開

STOPPED または FAILED 状態のジョブを再開するには、実行 ID を指定し、任意でバッチジョブの再開時に使用するプロパティーを指定します。

/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:restart-job(execution-id=EXECUTION_ID,properties={PROPERTY=VALUE})
Copy to Clipboard Toggle word wrap

実行 ID はジョブインスタンスが最後に実行された ID である必要があります。

バッチジョブの開始

バッチジョブを開始するには、ジョブ XML ファイルを指定し、任意でバッチジョブの再開時に使用するプロパティーを指定します。

/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:start-job(job-xml-name=JOB_XML_NAME,properties={PROPERTY=VALUE})
Copy to Clipboard Toggle word wrap
バッチジョブの停止

実行中のバッチジョブを停止するには、実行 ID を指定します。

/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:stop-job(execution-id=EXECUTION_ID)
Copy to Clipboard Toggle word wrap
バッチジョブ実行詳細の表示

バッチジョブ実行の詳細を表示することができます。このランタイム情報を表示するには、read-resource 操作で include-runtime=true パラメーターを使用する必要があります。

/deployment=DEPLOYMENT_NAME/subsystem=batch-jberet:read-resource(recursive=true,include-runtime=true)
{
    "outcome" => "success",
    "result" => {"job" => {"import-file" => {
        "instance-count" => 2,
        "running-executions" => 0,
        "execution" => {
            "2" => {
                "batch-status" => "COMPLETED",
                "create-time" => "2016-04-11T22:03:12.708-0400",
                "end-time" => "2016-04-11T22:03:12.718-0400",
                "exit-status" => "COMPLETED",
                "instance-id" => 58L,
                "last-updated-time" => "2016-04-11T22:03:12.719-0400",
                "start-time" => "2016-04-11T22:03:12.708-0400"
            },
            "1" => {
                "batch-status" => "FAILED",
                "create-time" => "2016-04-11T21:57:17.567-0400",
                "end-time" => "2016-04-11T21:57:17.596-0400",
                "exit-status" => "Error : org.hibernate.exception.ConstraintViolationException: could not execute statement",
                "instance-id" => 15L,
                "last-updated-time" => "2016-04-11T21:57:17.597-0400",
                "start-time" => "2016-04-11T21:57:17.567-0400"
            }
        }
    }}}
}
Copy to Clipboard Toggle word wrap
管理コンソールからのバッチジョブの管理

管理コンソールからバッチジョブを管理するには、Runtime タブでサーバーを選択し、Batch (JBeret) を選択してリストからジョブを選びます。

バッチジョブの開始

ジョブを選択してドロップダウンメニューで Start を選択し、バッチジョブの新たな実行を開始します。

20.3. バッチジョブのセキュリティー設定

batch-jberet サブシステムを設定すると、Elytron セキュリティードメインでバッチジョブを実行することができます。これにより、バッチジョブをセキュアに一時停止でき、同じセキュアなアイデンティティーで再開できます。たとえば、batch-jberet サブシステムを使用して、バッチジョブを開始するためにセキュアな RESTful エンドポイントが作成されます。RESTful エンドポイントと batch-jberet サブシステムの両方が同じセキュリティードメインを使用してセキュア化された場合、または batch-jberet セキュリティードメインが RESTful エンドポイントのセキュリティードメインドメインを信頼した場合、このように開始されたバッチジョブはセキュアに一時停止され、同じセキュアなアイデンティティーによって再開されます。

以下の管理 CLI コマンドを使用して security-domain 属性を更新し、バッチジョブのセキュリティーを設定します。

/subsystem=batch-jberet:write-attribute(name=security-domain, value=ExampleDomain)

reload
Copy to Clipboard Toggle word wrap
注記

バッチジョブには、org.wildfly.extension.batch.jberet.deployment.BatchPermission パーミッションが必要です。このパーミッションは、jakarta.batch.operations.JobOperator と対応する startstoprestartabandon、および read パーミッションを提供します。default-permission-mapper マッパーは org.wildfly.extension.batch.jberet.deployment.BatchPermission パーミッションを提供します。

第21章 naming サブシステムの設定

21.1. naming サブシステムについて

naming サブシステムは JBoss EAP の JNDI 実装を提供します。このサブシステムを設定して、グローバル JNDI 名前空間のエントリーをバインド することができます。さらに、このサブシステムを設定して リモート JNDI をアクティブまたは非アクティブ にすることもできます。

以下は、すべての要素と属性が指定された naming サブシステムの XML 設定例になります。

<subsystem xmlns="{NamingSubsystemNamespace}">
    <bindings>
        <simple name="java:global/simple-integer-binding" value="100" type="int" />
        <simple name="java:global/jboss.org/docs/url" value="https://docs.jboss.org" type="java.net.URL" />
        <object-factory name="java:global/foo/bar/factory" module="org.foo.bar" class="org.foo.bar.ObjectFactory" />
        <external-context name="java:global/federation/ldap/example" class="jakarta.naming.directory.InitialDirContext" cache="true">
            <environment>
                <property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
                <property name="java.naming.provider.url" value="ldap://ldap.example.com:389" />
                <property name="java.naming.security.authentication" value="simple" />
                <property name="java.naming.security.principal" value="uid=admin,ou=system" />
                <property name="java.naming.security.credentials" value="secret" />
            </environment>
        </external-context>
        <lookup name="java:global/new-alias-name" lookup="java:global/original-name" />
    </bindings>
    <remote-naming/>
</subsystem>
Copy to Clipboard Toggle word wrap

21.2. グローバルバインディングの設定

naming サブシステムは、エントリーを java:globaljava:jboss、または java グローバル JNDI 名前空間へバインドできるようにしますが、標準のポータブルな java:global 名前空間を使用することが推奨されます。

グローバルバインディングは naming サブシステムの <bindings> 要素で設定されます。以下の 4 種類のバインディングがサポートされます。

シンプルバインディングの設定

simple XML 設定要素は、プリミティブまたは java.net.URL エントリーにバインドします。

  • name 属性は必須で、エントリーのターゲット JNDI 名を指定します。
  • value 属性は必須で、エントリーの値を定義します。
  • 任意の type 属性はエントリーの値の型を指定し、デフォルトは java.lang.String になります。java.lang.String の他に、int または java.lang.Integer、および java.net.URL などのプリミティブ型や対応するオブジェクトラッパークラスを指定できます。

以下に、シンプルバインディングを作成する管理 CLI コマンドの例を示します。

/subsystem=naming/binding=java\:global\/simple-integer-binding:add(binding-type=simple, type=int, value=100)
Copy to Clipboard Toggle word wrap

結果の XML 設定

<subsystem xmlns="{NamingSubsystemNamespace}">
    <bindings>
        <simple name="java:global/simple-integer-binding" value="100" type="int"/>
    </bindings>
    <remote-naming/>
</subsystem>
Copy to Clipboard Toggle word wrap

以下のコマンドを使用してバインディングを削除します。

/subsystem=naming/binding=java\:global\/simple-integer-binding:remove
Copy to Clipboard Toggle word wrap
オブジェクトファクトリーのバインド

object-factory XML 設定要素は、jakarta.naming.spi.ObjectFactory エントリーをバインドします。

  • name 属性は必須で、エントリーのターゲット JNDI 名を指定します。
  • class 属性は必須で、オブジェクトファクトリーの Java タイプを定義します。
  • module 属性は必須で、オブジェクトファクトリーの Java クラスをロードできる JBoss Module ID を指定します。
  • 任意の environment 子要素は、カスタム環境をオブジェクトファクトリーに提供するために使用できます。

以下に、オブジェクトファクトリーバインディングを作成する管理 CLI コマンドの例を示します。

/subsystem=naming/binding=java\:global\/foo\/bar\/factory:add(binding-type=object-factory, module=org.foo.bar, class=org.foo.bar.ObjectFactory, environment=[p1=v1, p2=v2])
Copy to Clipboard Toggle word wrap

結果の XML 設定

<subsystem xmlns="{NamingSubsystemNamespace}">
    <bindings>
        <object-factory name="java:global/foo/bar/factory" module="org.foo.bar" class="org.foo.bar.ObjectFactory">
            <environment>
                <property name="p1" value="v1" />
                <property name="p2" value="v2" />
            </environment>
        </object-factory>
    </bindings>
  </subsystem>
Copy to Clipboard Toggle word wrap

以下のコマンドを使用してバインディングを削除します。

/subsystem=naming/binding=java\:global\/foo\/bar\/factory:remove
Copy to Clipboard Toggle word wrap
外部コンテンツのバインド

LDAP コンテキストなどの外部 JNDI コンテキストのフェデレーションは、external-context XML 設定要素を使用して実行されます。

  • name 属性は必須で、エントリーのターゲット JNDI 名を指定します。
  • class 属性は必須で、フェデレートされたコンテキストの作成に使用される Java 初期ネーミングコンテキストタイプを示します。このようなタイプには、単一の環境マップ引数を持つコンストラクターが必要なことに注意してください。
  • 任意の module 属性は、外部 JNDI コンテキストが必要とするすべてのクラスをロードできる JBoss Module ID を指定します。
  • オプションの cache 属性は外部コンテキストインスタンスをキャッシュする必要があるかどうかを示し、デフォルトは false になります。
  • 任意の environment 子要素は、外部コンテキストを検索するために必要なカスタム環境を提供するために使用されます。

以下に、外部コンテキストバインディングを作成する管理 CLI コマンドの例を示します。

/subsystem=naming/binding=java\:global\/federation\/ldap\/example:add(binding-type=external-context, cache=true, class=jakarta.naming.directory.InitialDirContext, module=org.jboss.as.naming, environment=[java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url="ldap://ldap.example.com:389", java.naming.security.authentication=simple, java.naming.security.principal="uid=admin,ou=system", java.naming.security.credentials=secret])
Copy to Clipboard Toggle word wrap

結果の XML 設定

<subsystem xmlns="{NamingSubsystemNamespace}">
  <bindings>
    <external-context name="java:global/federation/ldap/example" module="org.jboss.as.naming" class="jakarta.naming.directory.InitialDirContext" cache="true">
      <environment>
        <property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
        <property name="java.naming.provider.url" value="ldap://ldap.example.com:389"/>
        <property name="java.naming.security.authentication" value="simple"/>
        <property name="java.naming.security.principal" value="uid=admin,ou=system"/>
        <property name="java.naming.security.credentials" value="secret"/>
      </environment>
    </external-context>
  </bindings>
</subsystem>
Copy to Clipboard Toggle word wrap

以下のコマンドを使用してバインディングを削除します。

/subsystem=naming/binding=java\:global\/federation\/ldap\/example:remove
Copy to Clipboard Toggle word wrap
注記

JNDI プロバイダーのリソース検索が lookup(Name) メソッドを適切に実装していないと、"jakarta.naming.InvalidNameException: Only support CompoundName names" というエラーが発生することがあります。

以下のプロパティーを追加せずに、外部コンテキスト環境が lookup(String) メソッドを使用するよう指定すると、この問題を回避できる可能性がありますが、パフォーマンスが劣化します。

<property name="org.jboss.as.naming.lookup.by.string" value="true"/>
Copy to Clipboard Toggle word wrap
ルックアップエイリアスのバインド

lookup 要素を使用すると、既存のエントリーを追加の名前またはエイリアスにバインドできます。

  • name 属性は必須で、エントリーのターゲット JNDI 名を指定します。
  • lookup 属性は必須で、ソース JNDI 名を示します。

以下に、既存のエントリーをエイリアスにバインドする管理 CLI コマンドの例を示します。

/subsystem=naming/binding=java\:global\/new-alias-name:add(binding-type=lookup, lookup=java\:global\/original-name)
Copy to Clipboard Toggle word wrap

結果の XML 設定

<lookup name="java:global/new-alias-name" lookup="java:global/original-name" />
Copy to Clipboard Toggle word wrap

以下のコマンドを使用してバインディングを削除します。

/subsystem=naming/binding=java\:global\/c:remove
Copy to Clipboard Toggle word wrap

21.3. JNDI バンディングの動的な変更

JBoss EAP 7.1 には、サーバーのリロードや再起動を強制せずに JNDI バインディングを動的に変更する機能が追加されました。この機能は、バージョンの更新、テストの要件、またはアプリケーション機能の更新によってネットワークサービスのエンドポイントが動的に設定される場合に便利です。

JNDI バインディングを更新するには、rebind 操作を使用します。rebind 操作は add 操作と同じ引数を取ります。このコマンドは、external-context バンディングタイプ以下のすべてのバインディングタイプで動作します。外部コンテキストバインディングは、モジュラーサービスコンテナー (MSC) の状態に影響する追加の依存関係を必要とするため、サービスを再起動せずに外部コンテキストバインディングを再起動することはできません。

以下のコマンドは、シンプルバインディングの設定 の例で定義した JNDI バインディングを動的に変更します。

/subsystem=naming/binding=java\:global\/simple-integer-binding:rebind(binding-type=simple, type=int, value=200)
Copy to Clipboard Toggle word wrap

naming サブシステムでグローバルバインディングを設定する方法に関する詳細は、グローバルバインディングの設定 を参照してください。

21.4. リモート JNDI インターフェイスの設定

リモート JNDI インターフェイスは、クライアントがリモート JBoss EAP インスタンスでエントリーをルックアップできるようにします。naming サブシステムを設定すると、このインターフェイスをアクティブまたは非アクティブにすることができます (デフォルトではアクティブになります)。リモート JNDI インターフェイスは <remote-naming> 要素を使用して設定されます。

以下の管理 CLI コマンドを使用して、リモート JNDI インターフェイスをアクティブまたは非アクティブにします。

/subsystem=naming/service=remote-naming:add
Copy to Clipboard Toggle word wrap

以下の管理 CLI コマンドを使用して、リモート JNDI インターフェイスを非アクティブにします。

/subsystem=naming/service=remote-naming:remove
Copy to Clipboard Toggle word wrap
注記

リモート JNDI 上では java:jboss/exported コンテキスト内のエントリーのみにアクセスできます。

第22章 高可用性の設定

22.1. 高可用性の概要

JBoss EAP はデプロイされた Jakarta EE アプリケーションの可用性を保証するために以下の 高可用性 サービスを提供します。

ロードバランシング
複数のサーバーにワークロードを分散し、サービスが大量のリクエストを処理できるようにします。リクエストが大量に発生しても、クライアントはサービスからタイムリーに応答を受け取ることができます。
フェイルオーバー
ハードウェアやネットワークの障害が発生してもクライアントのサービスへのアクセスが中断しないようにします。サービスに障害が発生すると、別のクラスターメンバーがクライアントのリクエストを引き継ぎ、処理が続行されます。

クラスタリング はこれらすべての機能を包括する言葉です。クラスターのメンバーを設定すると、ロードバランシングと呼ばれるワークロードの共有や、フェイルオーバーと呼ばれる他のクラスターメンバーの障害時におけるクライアント処理の引き継ぎを行うことができます。

注記

選択した JBoss EAP の操作モード (スタンドアロンサーバー または マネージドドメイン) によってサーバーの管理方法が異なることに注意してください。操作モードに関係なく JBoss EAP で高可用性サービスを設定できます。

JBoss EAP は、さまざまなコンポーネントを使用した異なるレベルの高可用性をサポートします。高可用性を実現できるランタイムのコンポーネントおよびアプリケーションの一部は以下のとおりです。

  • アプリケーションサーバーのインスタンス
  • 内部の JWS、Apache HTTP Server、Microsoft IIS、または Oracle iPlanet Web Server と併用される Web アプリケーション
  • ステートフルおよびステートレスセッション Jakarta Enterprise Beans
  • シングルサインオン (SSO) メカニズム
  • HTTP セッション
  • Java Message Service サービスおよびメッセージ駆動型 Bean (MDB)
  • シングルトン MSC サービス
  • シングルトンデプロイメント

JBoss EAP では、jgroupsinfinispan、および modcluster サブシステムによってクラスタリングが使用できるようになります。ha および full-ha プロファイルではこれらのシステム有効になっています。JBoss EAP では、これらのサービスは必要に応じて起動およびシャットダウンしますが、分散可能 と設定されたアプリケーションがサーバーにデプロイされた場合のみ起動します。

アプリケーションを分散可能とする 方法は、JBoss EAP の 開発ガイド を参照してください。

22.2. JGroups を用いたクラスター通信

22.2.1. JGroups

JGroups は信頼できるメッセージングのためのツールキットで、お互いにメッセージを送信するノードを持つクラスターを作成するために使用できます。

jgroups サブシステムは JBoss EAP で高可用性サービスのグループ通信サポートを提供します。これにより、名前付きのチャネルおよびプロトコルスタックを設定でき、チャネルのランタイム統計を表示することもできます。jgroups サブシステムは高可用性の機能を提供する設定を使用する場合に使用できます (マネージドドメインでは hafull-ha プロファイル、スタンドアロンサーバーは standalone-ha.xmlstandalone-full-ha.xml 設定ファイルなど)。

JBoss EAP には 2 つの JGroups スタックが事前に設定されています。

udp
クラスターのノードは UDP (User Datagram Protocol) マルチキャストを使用してお互いに通信します。これはデフォルトのスタックです。
tcp
クラスターのノードは TCP (Transmission Control Protocol) を使用してお互いに通信します。
注記

TCP はエラー検出、パケットの順序付け、および輻輳制御を自身で処理するため、オーバーヘッドが大きく、UDP よりも遅いと見なされることが多々あります。JGroups は UDP のこれらの機能を処理しますが、TCP はこれらの機能を独自で処理します。信頼できないネットワークや輻輳度の高いネットワークで JGroups を使用する場合やマルチキャストが使用できない場合は、TCP を選択するとよいでしょう。

事前設定されたスタックを使用できますが、システムの要件に合うように独自に定義をすることもできます。使用できるプロトコルとそれらの属性は、以下の項を参照してください。

22.2.2. デフォルトの JGroups チャネルが TCP を使用するよう設定する

デフォルトでは、クラスターノードは ee JGroups チャネルに設定された udp プロトコルスタックを使用して通信します。

<channels default="ee">
  <channel name="ee" stack="udp"/>
</channels>
<stacks>
  <stack name="udp">
    <transport type="UDP" socket-binding="jgroups-udp"/>
    <protocol type="PING"/>
    ...
  </stack>
  <stack name="tcp">
    <transport type="TCP" socket-binding="jgroups-tcp"/>
    <protocol type="MPING" socket-binding="jgroups-mping"/>
    ...
  </stack>
</stacks>
Copy to Clipboard Toggle word wrap
22.2.2.1. マルチキャストを使用した TCP の設定

一部のネットワークでは TCP のみを使用できます。

手順

  1. 以下の管理 CLI コマンドを使用して、ee チャネルが事前設定された tcp スタックを使用するようにします。

    /subsystem=jgroups/channel=ee:write-attribute(name=stack,value=tcp)
    Copy to Clipboard Toggle word wrap

    このデフォルトの tcp スタックは、IP マルチキャストを使用して初期クラスターメンバーシップを検出する MPING プロトコルを使用します。

22.2.2.2. マルチキャストを使用しない TCP の設定

マルチキャストが好ましくない場合、またはセキュリティーポリシーで許可されていない場合は、マルチキャストなしで TCP を使用するようにデフォルトのプロトコルスタックを変更できます。

手順

マルチキャストなしで TCP ベースのクラスタリングを設定するには、以下の手順を実行します。

  1. 以下のコマンドを実行して、ee チャネルが JGroups サブシステムで事前設定された tcp スタックを使用するように切り替えます。

    <channel name="ee" stack="tcp" cluster="ejb"/>
    Copy to Clipboard Toggle word wrap
  2. クラスターノードの名前を設定します。

    • スタンドアロン設定モードでは、次のいずれかの手順を実行します。

      • 以下のコマンドを実行します。

        <server xmlns="urn:jboss:domain:8.0" name="node_1">
        Copy to Clipboard Toggle word wrap
      • インスタンスの起動時にシステムプロパティー jboss.node.name に一意の名前を指定します。
    • ドメインモードでは、クラスターサーバーはサーバーのタグの host-*.xml ファイルに一覧表示されます。デフォルト設定では、以下のサーバー名を指定します。このサーバー名は、必要に応じて編集できます。

      <servers>
          <server name="server-one" group="main-server-group"/>
          <server name="server-two" group="other-server-group">
              <socket-bindings port-offset="150"/>
          </server>
      </servers>
      Copy to Clipboard Toggle word wrap
  3. 他のクラスターメンバーを検出するには、以下のいずれかのプロトコルを選択します。

    • TCPGOSSIP: このプロトコルは、外部のゴシップルーターサービスを使用してクラスターのメンバーを検出します。これには、追加のプロセスの設定および管理が必要ですが、個々の EAP インスタンスが相互のクラスターメンバーを一覧表示しないようにすることができます。このプロトコルは、クラスターメンバーが頻繁に変更される場合に役立ちます。詳細は TCPPING を参照してください。
    • TCPPING: このプロトコルは静的クラスターメンバーシップリストを定義し、各ノードが潜在的なクラスターメンバーの一覧を表示する必要があります。このプロトコルは、クラスターメンバーアドレスが認識されており、頻繁に変更されない場合に推奨されます。詳細は、TCPGOSSIP を参照してください。

22.2.3. TCPPING の設定

この手順は TCPPING プロトコルを使用する新しい JGroups スタックを作成し、静的クラスターメンバーシップのリストを定義します。ベーススクリプトは、tcpping スタックを作成し、この新しいスタックを使用するようデフォルトの ee チャネルを設定します。このスクリプトの管理 CLI コマンドは環境に合わせてカスタマイズする必要があり、バッチで処理されます。

手順

  1. 以下のスクリプトをテキストエディターにコピーし、ローカルファイルシステムに保存します。

    # Define the socket bindings
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=jgroups-host-a:add(host=HOST_A,port=7600)
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=jgroups-host-b:add(host=HOST_B,port=7600)
    batch
    # Add the tcpping stack
    /subsystem=jgroups/stack=tcpping:add
    /subsystem=jgroups/stack=tcpping/transport=TCP:add(socket-binding=jgroups-tcp)
    /subsystem=jgroups/stack=tcpping/protocol=TCPPING:add(socket-bindings=[jgroups-host-a,jgroups-host-b])
    /subsystem=jgroups/stack=tcpping/protocol=MERGE3:add
    /subsystem=jgroups/stack=tcpping/protocol=FD_SOCK:add
    /subsystem=jgroups/stack=tcpping/protocol=FD_ALL:add
    /subsystem=jgroups/stack=tcpping/protocol=VERIFY_SUSPECT:add
    /subsystem=jgroups/stack=tcpping/protocol=pbcast.NAKACK2:add
    /subsystem=jgroups/stack=tcpping/protocol=UNICAST3:add
    /subsystem=jgroups/stack=tcpping/protocol=pbcast.STABLE:add
    /subsystem=jgroups/stack=tcpping/protocol=pbcast.GMS:add
    /subsystem=jgroups/stack=tcpping/protocol=MFC:add
    /subsystem=jgroups/stack=tcpping/protocol=FRAG3:add
    # Set tcpping as the stack for the ee channel
    /subsystem=jgroups/channel=ee:write-attribute(name=stack,value=tcpping)
    run-batch
    reload
    Copy to Clipboard Toggle word wrap

    定義されたプロトコルの順番が重要になることに注意してください。また、add-index の値を add コマンドに渡すと、特定のインデックスでプロトコルを挿入できます。インデックスはゼロベースであるため、以下の管理 CLI コマンドは UNICAST3 プロトコルを 7 つ目のプロトコルとして追加します。

    /subsystem=jgroups/stack=tcpping/protocol=UNICAST3:add(add-index=6)
    Copy to Clipboard Toggle word wrap
  2. 環境に合わせてスクリプトを変更します。

    • マネージドドメインで実行している場合は、/subsystem=jgroups コマンドの前に /profile=PROFILE_NAME を追加し、更新するプロファイルを指定する必要があります。
    • 以下のプロパティーを環境に合わせて調整します。

      • socket-bindings: ウェルノウンとして見なされ、最初のメンバーシップの検索に利用できるホストとポートの組み合わせのコンマ区切りリスト。ソケットバインディングの定義の詳細は、ソケットバインディングの設定 を参照してください。
      • initial_hosts: ウェルノウンとして見なされ、最初のメンバーシップの検索に使用できる HOST[PORT] という構文を使用したホストとポートの組み合わせのコンマ区切りリスト (例: host1[1000],host2[2000])。
      • port_range: このプロパティーは、initial_hosts ポート範囲を指定した値の分拡張するために使用されます。たとえば、initial_hostshost1[1000],host2[2000] に設定し、port_range1 に設定した場合 initial_hosts 設定は host1[1000],host1[1001],host2[2000],host2[2001] に拡張されます。このプロパティーは initial_hosts プロパティーと併用した場合のみ有効です。
  3. スクリプトファイルを管理 CLI に渡してスクリプトを実行します。

    $ EAP_HOME/bin/jboss-cli.sh --connect --file=/path/to/SCRIPT_NAME
    Copy to Clipboard Toggle word wrap

TCPPING スタックが使用できるようになり、ネットワークの通信に TCP が使用されます。

22.2.3.1. スタンドアロンモードでの TCPPING の設定

この手順では、スタンドアロンモードでクラスター化されたアプリケーションの TCP スタックおよびノードを設定するのに役立ちます。

手順

  1. JGroups サブシステムで、デフォルトのスタックを udp から tcp に変更します。

    <channel name="ee" stack="tcp" cluster="ejb"/>
    Copy to Clipboard Toggle word wrap
  2. デフォルトの MPING プロトコルの代わりに TCPPING プロトコルを使用するように TCP スタックを設定します。以下のコードでは、initial_hosts プロパティーはクラスター内の全ノードのリストに相関し、7600 は設定および環境に応じて異なるデフォルトの jgroups-tcp ポートを示します。

    <stack name="tcp">
      <transport type="TCP" socket-binding="jgroups-tcp"/>
      <protocol type="TCPPING">
        <property name="initial_hosts">192.168.1.5[7600],192.168.1.9[7600]</property>
        <property name="port_range">0</property>
      </protocol>
      <protocol type="MERGE3"/>
      <protocol type="FD_SOCK" socket-binding="jgroups-tcp-fd"/>
      <protocol type="FD_ALL"/>
      <protocol type="VERIFY_SUSPECT"/>
      <protocol type="pbcast.NAKACK2"/>
      <protocol type="UNICAST3"/>
      <protocol type="pbcast.STABLE"/>
      <protocol type="pbcast.GMS"/>
      <protocol type="MFC"/>
      <protocol type="FRAG3"/>
    </stack>
    Copy to Clipboard Toggle word wrap
    注記

    initial_hosts に設定されたポート番号 7600 は、jgroups-tcp ソケットバインディング定義で定義されたポート番号と同じでなければなりません。ソケットバインディングに port-offset 機能を使用する場合は、initial_hosts のオフセットの後に同じ値を指定する必要があります。

  3. JGroups コンポーネントによって使用されるプライベートインターフェイスの IP アドレスを設定します。IP アドレスは、initial_hosts で指定されている IP アドレスのいずれかに関連付ける必要があります。

    <interface name="private">
      <inet-address value="${jboss.bind.address.private:192.168.1.5}"/>
    </interface>
    Copy to Clipboard Toggle word wrap
  4. クラスター内の他のノードを設定するには、上記の手順を繰り返します。ノードが設定されたら、各ノードを起動して、クラスター化されたアプリケーションをデプロイします。

検証

  • ログを確認して、ノードが稼働しているかどうかを確認できます。

    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2,ee,node_1) ISPN000094: Received new cluster view for channel server: [node_1|1] (2) [node_1, node_2]
    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2,ee,node_1) ISPN000094: Received new cluster view for channel web: [node_1|1] (2) [node_1, node_2]
    Copy to Clipboard Toggle word wrap
22.2.3.2. ドメインモードでの TCPPING の設定

この手順では、ドメインモードでクラスター化されたアプリケーションの TCP スタックおよびノードを設定するのに役立ちます。

手順

  1. 複数のクラスターに同じプロファイルを使用する場合は、システムプロパティーの値を initial_hosts に設定します。

    <protocol type="TCPPING">
      <property name="initial_hosts">${jboss.cluster.tcp.initial_hosts}</property>
    
    Set the system property at the `server-group` level:
    <server-groups>
      <server-group name="a-server-group" profile="ha">
      <socket-binding-group ref="ha-sockets"/>
      <system-properties>
        <property name="jboss.cluster.tcp.initial_hosts" value="192.168.1.5[7600],192.168.1.9[7600]" />
      </system-properties>
    Copy to Clipboard Toggle word wrap
  2. ホストコントローラーの XML 設定内でプライベートインターフェイスの IP アドレスを設定します。プライベートインターフェイスの IP アドレスは、initial_hosts で指定されている IP アドレスのいずれかに関連付ける必要があります。

    <interfaces>
        ....
      <interface name="private">
        <inet-address value="${jboss.bind.address.private:192.168.1.5}"/>
      </interface>
    </interfaces>
    Copy to Clipboard Toggle word wrap

検証

  • ログを確認して、ノードが稼働しているかどうかを確認できます。

    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2,ee,node_1) ISPN000094: Received new cluster view for channel server: [node_1|1] (2) [node_1, node_2]
    INFO  [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (thread-2,ee,node_1) ISPN000094: Received new cluster view for channel web: [node_1|1] (2) [node_1, node_2]
    Copy to Clipboard Toggle word wrap

22.2.4. TCPGOSSIP の設定

この手順は、TCPGOSSIP プロトコルを使用する新しい JGroups スタックを作成し、外部ゴシップルーターを使用してクラスターのメンバーを検索します。ベーススクリプトは、tcpgossip スタックを作成し、この新しいスタックを使用するようデフォルトの ee チャネルを設定します。このスクリプトの管理 CLI コマンドは環境に合わせてカスタマイズする必要があり、バッチで処理されます。

手順

  1. 以下のスクリプトをテキストエディターにコピーし、ローカルファイルシステムに保存します。

    # Define the socket bindings
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=jgroups-host-a:add(host=HOST_A,port=13001)
    batch
    # Add the tcpgossip stack
    /subsystem=jgroups/stack=tcpgossip:add
    /subsystem=jgroups/stack=tcpgossip/transport=TCP:add(socket-binding=jgroups-tcp)
    /subsystem=jgroups/stack=tcpgossip/protocol=TCPGOSSIP:add(socket-bindings=[jgroups-host-a])
    /subsystem=jgroups/stack=tcpgossip/protocol=MERGE3:add
    /subsystem=jgroups/stack=tcpgossip/protocol=FD_SOCK:add
    /subsystem=jgroups/stack=tcpgossip/protocol=FD_ALL:add
    /subsystem=jgroups/stack=tcpgossip/protocol=VERIFY_SUSPECT:add
    /subsystem=jgroups/stack=tcpgossip/protocol=pbcast.NAKACK2:add
    /subsystem=jgroups/stack=tcpgossip/protocol=UNICAST3:add
    /subsystem=jgroups/stack=tcpgossip/protocol=pbcast.STABLE:add
    /subsystem=jgroups/stack=tcpgossip/protocol=pbcast.GMS:add
    /subsystem=jgroups/stack=tcpgossip/protocol=MFC:add
    /subsystem=jgroups/stack=tcpgossip/protocol=FRAG3:add
    # Set tcpgossip as the stack for the ee channel
    /subsystem=jgroups/channel=ee:write-attribute(name=stack,value=tcpgossip)
    run-batch
    reload
    Copy to Clipboard Toggle word wrap

    定義されたプロトコルの順番が重要になることに注意してください。また、add-index の値を add コマンドに渡すと、特定のインデックスでプロトコルを挿入できます。インデックスはゼロベースであるため、以下の管理 CLI コマンドは UNICAST3 プロトコルを 7 つ目のプロトコルとして追加します。

    /subsystem=jgroups/stack=tcpgossip/protocol=UNICAST3:add(add-index=6)
    Copy to Clipboard Toggle word wrap
  2. 環境に合わせてスクリプトを変更します。

    • マネージドドメインで実行している場合は、/subsystem=jgroups コマンドの前に /profile=PROFILE_NAME を追加し、更新するプロファイルを指定する必要があります。
    • 以下のプロパティーを環境に合わせて調整します。

      • socket-bindings: ウェルノウンとして見なされ、最初のメンバーシップの検索に利用できるホストとポートの組み合わせのコンマ区切りリスト。ソケットバインディングの定義の詳細は、ソケットバインディングの設定 を参照してください。
      • initial_hosts: ウェルノウンとして見なされ、最初のメンバーシップの検索に使用できる HOST[PORT] という構文を使用したホストとポートの組み合わせのコンマ区切りリスト (例: host1[1000],host2[2000])。
      • port_range: このプロパティーは、initial_hosts ポート範囲を指定した値の分拡張するために使用されます。たとえば、initial_hostshost1[1000],host2[2000] に設定し、port_range1 に設定した場合 initial_hosts 設定は host1[1000],host1[1001],host2[2000],host2[2001] に拡張されます。このプロパティーは initial_hosts プロパティーと併用した場合のみ有効です。
      • reconnect_interval: 接続が切断されたスタブがゴシップルーターへの再接続を試みる間隔 (ミリ秒単位)。
      • sock_conn_timeout: ソケット作成の最大時間。デフォルトは 1000 ミリ秒です。
      • sock_read_timeout: 読み取りがブロックされる最大時間 (ミリ秒単位)。0 を値として指定すると無制限にブロックされます。
  3. スクリプトファイルを管理 CLI に渡してスクリプトを実行します。

    $ EAP_HOME/bin/jboss-cli.sh --connect --file=/path/to/SCRIPT_NAME
    Copy to Clipboard Toggle word wrap

TCPGOSSIP スタックが使用できるようになり、ネットワークの通信に TCP が使用されます。このスタックはゴシップルーターと使用するように設定されるため、JGroups メンバーは他のクラスターメンバーを見つけることができます。

22.2.5. JDBC_PING の設定

JDBC_PING プロトコルを使用して、クラスターでメンバーシップを管理および検出できます。

JDBC_PING はデータソースに指定されたデータベースを使用して、クラスターのメンバーをリスト表示します。

手順

  1. クラスターメンバーシップの管理に使用するデータベースに接続するデータソースを作成します。
  2. 以下のスクリプトをテキストエディターにコピーし、ローカルファイルシステムに保存します。

    batch
    # Add the JDBC_PING stack
    /subsystem=jgroups/stack=JDBC_PING:add
    /subsystem=jgroups/stack=JDBC_PING/transport=TCP:add(socket-binding=jgroups-tcp)
    /subsystem=jgroups/stack=JDBC_PING/protocol=JDBC_PING:add(data-source=ExampleDS)
    /subsystem=jgroups/stack=JDBC_PING/protocol=MERGE3:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=FD_SOCK:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=FD_ALL:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=VERIFY_SUSPECT:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.NAKACK2:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=UNICAST3:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.STABLE:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=pbcast.GMS:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=MFC:add
    /subsystem=jgroups/stack=JDBC_PING/protocol=FRAG3:add
    # Set JDBC_PING as the stack for the ee channel
    /subsystem=jgroups/channel=ee:write-attribute(name=stack,value=JDBC_PING)
    run-batch
    reload
    Copy to Clipboard Toggle word wrap
    注記

    定義されたプロトコルの順序は重要です。また、add-index の値を add コマンドに渡すと、特定のインデックスでプロトコルを挿入できます。インデックスはゼロベースであるため、以下の管理 CLI コマンドは UNICAST3 プロトコルを 7 つ目のプロトコルとして追加します。

    /subsystem=jgroups/stack=JDBC_PING/protocol=UNICAST3:add(add-index=6)
    Copy to Clipboard Toggle word wrap
  3. 環境に合わせてスクリプトを変更します。

    • マネージドドメインで実行している場合は、/subsystem=jgroups コマンドの前に /profile=PROFILE_NAME を追加し、更新するプロファイルを指定する必要があります。
    • 'ExampleDS' を、手順 1 で定義したデータソースの名前に置き換えます。
  4. スクリプトファイルを管理 CLI に渡してスクリプトを実行します。

    $ EAP_HOME/bin/jboss-cli.sh --connect --file=/path/to/SCRIPT_NAME
    Copy to Clipboard Toggle word wrap

JDBC_PING スタックが使用できるようになり、ネットワークの通信に TCP が使用されます。

22.2.6. JGroups のネットワークインターフェイスへのバインディング

デフォルトでは、JGroups は private ネットワークインターフェイスのみへバインドし、デフォルト設定でローカルホストへ示されます。クラスタリングのトラフィックはパブリックネットワークインターフェイスで公開するべきではないため、セキュリティー上の理由で JGroups は JBoss EAP の起動中に指定された -b 引数によって定義されたネットワークインターフェイスにはバインドしません。

ネットワークインターフェイスの設定方法は、ネットワークおよびポート設定 の章を参照してください。

重要

セキュリティー上の理由で、JGroups はパブリックではないネットワークインターフェイスのみにバインドされる必要があります。また、パフォーマンス上の理由で JGroups トラフィックのネットワークインターフェイスは専用の VLAN (Virtual Local Area Network) の一部にすることが推奨されます。

22.2.7. クラスターの保護

クラスターをセキュアに実行するには、複数の課題に対応する必要があります。

  • 承認されていないノードがクラスターに参加しないようにします。これは 認証 を要求して対処します。
  • クラスターメンバーがクラスターメンバー以外と通信しないようにします。これは メッセージの暗号化 で対処します。
22.2.7.1. 認証の設定

JGroups の認証は AUTH プロトコルによって実行されます。認証されたノードのみがクラスターに参加できるようにすることが目的です。

該当のサーバー設定ファイルに AUTH プロトコルと適切なプロパティー設定を追加します。AUTH プロトコルは pbcast.GMS プロトコルの直前に設定する必要があります。

以下に、AUTH とさまざまな形式の認可トークンを使用する例を示します。

AUTH とシンプルトークン
...
<protocol type="pbcast.STABLE"/>
<auth-protocol type="AUTH">
  <plain-token>
    <shared-secret-reference clear-text="my_password"/>
  </plain-token>
</auth-protocol>
<protocol type="pbcast.GMS"/>
...
Copy to Clipboard Toggle word wrap
AUTH とダイジェストアルゴリズムトークン

この形式は、MD5 や SHA-2 など、どのダイジェストアルゴリズムでも使用できます。JBoss EAP 8.0 のデフォルトのダイジェストアルゴリズムは SHA-256 です。これは、JVM で必ずサポートされなければならない最も強力なダイジェストアルゴリズムです。多くの JVM は、追加で SHA-512 を実装します。

...
<protocol type="pbcast.STABLE"/>
<auth-protocol type="AUTH">
  <digest-token algorithm="SHA-512">
    <shared-secret-reference clear-text="my_password"/>
  </digest-token>
</auth-protocol>
<protocol type="pbcast.GMS"/>
...
Copy to Clipboard Toggle word wrap
AUTH と X509 トークン

この例は、elytron サブシステムで新しいキーストアを作成し、JGroups の AUTH 設定で参照します。

  1. キーストアを作成します。

    $ keytool -genkeypair -alias jgroups_key -keypass my_password -storepass my_password -storetype jks -keystore jgroups.keystore -keyalg RSA
    Copy to Clipboard Toggle word wrap
  2. 管理 CLI を使用して、キーストアを elytron サブシステムに追加します。

    /subsystem=elytron/key-store=jgroups-token-store:add(type=jks,path=/path/to/jgroups.keystore,credential-reference={clear-text=my_password}, required=true)
    Copy to Clipboard Toggle word wrap
  3. JGroups のスタック定義で AUTH を設定してキーストアを使用するようにします。

    ...
    <protocol type="pbcast.STABLE"/>
    <auth-protocol type="AUTH">
      <cipher-token algorithm="RSA" key-alias="jgroups_key" key-store="jgroups-token-store">
        <shared-secret-reference clear-text="my_password"/>
        <key-credential-reference clear-text="my_password"/>
      </cipher-token>
    </auth-protocol>
    <protocol type="pbcast.GMS"/>
    ...
    Copy to Clipboard Toggle word wrap
22.2.7.2. 暗号化の設定

JGroups はクラスターのメンバーが共有する秘密鍵を使用してメッセージを暗号化します。送信元は共有する秘密鍵を使用してメッセージを暗号化し、受信先は同じ秘密鍵を使用してメッセージを復号化します。対称暗号化SYM_ENCRYPT プロトコルを使用して設定され、ノードは共有のキーストアを使用して秘密鍵を取得します。非対称暗号化ASYM_ENCRYPT プロトコルを使用して設定され、ノードは AUTH を使用して認証された後にクラスターのコーディネーターから秘密鍵を取得します。

対称暗号化の使用

SYM_ENCRYPT を使用するには、各ノードの JGroups 設定で参照されるキーストアを設定する必要があります。

  1. キーストアを作成します。

    以下のコマンドでは、VERSION を適切な JGroups JAR バージョンに置き換え、PASSWORD をキーストアパスワードに置き換えます。

    $ java -cp EAP_HOME/modules/system/layers/base/org/jgroups/main/jgroups-VERSION.jar org.jgroups.demos.KeyStoreGenerator --alg AES --size 128 --storeName defaultStore.keystore --storepass PASSWORD --alias mykey
    Copy to Clipboard Toggle word wrap

    これにより、JGroups 設定で参照される defaultStore.keystore ファイルが生成されます。

  2. キーストアが生成されたら、2 つの方法の 1 つを使用して SYM_PROTOCOL で定義されます。

注記

SYM_ENCRYPT を使用する場合、AUTH の設定は任意です。

キーストアの直接参照による対称暗号化の使用
  1. jgroups サブシステムで SYM_ENCRYPT プロトコルを設定します。

    該当するサーバー設定ファイルに、SYM_ENCRYPT プロトコルと適切なプロパティー設定を追加します。このプロトコルは、以前作成されたキーストアを参照します。SYM_ENCRYPT プロトコルは pbcast.NAKACK2 の直前に設定する必要があります。

    <subsystem xmlns="{JgroupsSubsystemNamespace}">
      <stacks>
        <stack name="udp">
          <transport type="UDP" socket-binding="jgroups-udp"/>
          <protocol type="PING"/>
          <protocol type="MERGE3"/>
          <protocol type="FD_SOCK"/>
          <protocol type="FD_ALL"/>
          <protocol type="VERIFY_SUSPECT"/>
          <protocol type="SYM_ENCRYPT">
            <property name="provider">SunJCE</property>
            <property name="sym_algorithm">AES</property>
            <property name="encrypt_entire_message">true</property>
            <property name="keystore_name">/path/to/defaultStore.keystore</property>
            <property name="store_password">PASSWORD</property>
            <property name="alias">mykey</property>
          </protocol>
          <protocol type="pbcast.NAKACK2"/>
          <protocol type="UNICAST3"/>
          <protocol type="pbcast.STABLE"/>
          <protocol type="pbcast.GMS"/>
          <protocol type="UFC"/>
          <protocol type="MFC"/>
          <protocol type="FRAG3"/>
        </stack>
      </stacks>
    </subsystem>
    Copy to Clipboard Toggle word wrap
Elytron と対称暗号化の使用
  1. 管理 CLI を使用して、対称暗号化を使用して 作成された defaultStore.keystore を参照するキーストアを elytron サブシステムに作成します。

    /subsystem=elytron/key-store=jgroups-keystore:add(path=/path/to/defaultStore.keystore,credential-reference={clear-text=PASSWORD},type=JCEKS)
    Copy to Clipboard Toggle word wrap
  2. SYM_ENCRYPT プロトコルと適切なプロパティー設定を jgroups サブシステムに追加します。以下の設定どおり、SYM_ENCRYPT プロトコルは pbcast.NAKACK2 プロトコルの直前に設定する必要があります。

    <subsystem xmlns="{JgroupsSubsystemNamespace}">
      <stacks>
        <stack name="udp">
          <transport type="UDP" socket-binding="jgroups-udp"/>
          <protocol type="PING"/>
          <protocol type="MERGE3"/>
          <protocol type="FD_SOCK"/>
          <protocol type="FD_ALL"/>
          <protocol type="VERIFY_SUSPECT"/>
          <encrypt-protocol type="SYM_ENCRYPT" key-alias="mykey" key-store="jgroups-keystore">
            <key-credential-reference clear-text="PASSWORD"/>
            <property name="provider">SunJCE</property>
            <property name="encrypt_entire_message">true</property>
          </encrypt-protocol>
          <protocol type="pbcast.NAKACK2"/>
          <protocol type="UNICAST3"/>
          <protocol type="pbcast.STABLE"/>
          <protocol type="pbcast.GMS"/>
          <protocol type="UFC"/>
          <protocol type="MFC"/>
          <protocol type="FRAG3"/>
        </stack>
      </stacks>
    </subsystem>
    Copy to Clipboard Toggle word wrap
    注記

    上記の例はクリアテキストのパスワードを使用しますが、認証情報ストアを定義して設定ファイル外部にパスワードを定義することもできます。認証情報ストアの設定に関する詳細は、サーバーセキュリティーの設定方法認証情報ストア を参照してください。

非対称暗号化の使用

ASYM_ENCRYPT を使用するには AUTH プロトコルを定義する必要があります。AUTH プロトコルを jgroups サブシステムで設定する手順は、認証の設定 セクションを参照してください。

ASYM_ENCRYPT は 2 つの方法の 1 つで設定されます。

シークレット鍵の生成による非対象暗号化の使用
  1. jgroups サブシステムで ASYM_ENCRYPT プロトコルを設定します。

    該当のサーバー設定ファイルに ASYM_ENCRYPT プロトコルと適切なプロパティー設定を追加します。以下の設定どおり、ASYM_ENCRYPT プロトコルは pbcast.NAKACK2 プロトコルの直前に設定する必要があります。

    <subsystem xmlns="{JgroupsSubsystemNamespace}">
      <stacks>
        <stack name="udp">
          <transport type="UDP" socket-binding="jgroups-udp"/>
          <protocol type="PING"/>
          <protocol type="MERGE3"/>
          <protocol type="FD_SOCK"/>
          <protocol type="FD_ALL"/>
          <protocol type="VERIFY_SUSPECT"/>
          <protocol type="ASYM_ENCRYPT">
            <property name="encrypt_entire_message">true</property>
            <property name="sym_keylength">128</property>
            <property name="sym_algorithm">AES/ECB/PKCS5Padding</property>
            <property name="asym_keylength">512</property>
            <property name="asym_algorithm">RSA</property>
          </protocol>
          <protocol type="pbcast.NAKACK2"/>
          <protocol type="UNICAST3"/>
          <protocol type="pbcast.STABLE"/>
          <!-- Configure AUTH protocol here -->
          <protocol type="pbcast.GMS"/>
          <protocol type="UFC"/>
          <protocol type="MFC"/>
          <protocol type="FRAG3"/>
        </stack>
      </stacks>
    </subsystem>
    Copy to Clipboard Toggle word wrap
Elytron での非対称暗号化の使用
  1. キーペアが含まれるキーストアを作成します。以下のコマンドは、mykey というエイリアスでキーストアを作成します。

    $ keytool -genkeypair -alias mykey -keyalg RSA -keysize 1024 -keystore defaultKeystore.keystore -dname "CN=localhost" -keypass secret -storepass secret
    Copy to Clipboard Toggle word wrap
  2. 管理 CLI を使用して、defaultStore.keystore を参照するキーストアを elytron サブシステムに作成します。

    /subsystem=elytron/key-store=jgroups-keystore:add(path=/path/to/defaultStore.keystore,credential-reference={clear-text=PASSWORD},type=JCEKS)
    Copy to Clipboard Toggle word wrap
  3. ASYM_ENCRYPT プロトコルと適切なプロパティー設定を jgroups サブシステムに追加します。以下の設定どおり、ASYM_ENCRYPT プロトコルは pbcast.NAKACK2 プロトコルの直前に設定する必要があります。

    <subsystem xmlns="{JgroupsSubsystemNamespace}">
      <stacks>
        <stack name="udp">
          <transport type="UDP" socket-binding="jgroups-udp"/>
          <protocol type="PING"/>
          <protocol type="MERGE3"/>
          <protocol type="FD_SOCK"/>
          <protocol type="FD_ALL"/>
          <protocol type="VERIFY_SUSPECT"/>
          <encrypt-protocol type="ASYM_ENCRYPT" key-alias="mykey" key-store="jgroups-keystore">
            <key-credential-reference clear-text="secret" />
            <property name="encrypt_entire_message">true</property>
          </encrypt-protocol>
          <protocol type="pbcast.NAKACK2"/>
          <protocol type="UNICAST3"/>
          <protocol type="pbcast.STABLE"/>
          <!-- Configure AUTH protocol here -->
          <protocol type="pbcast.GMS"/>
          <protocol type="UFC"/>
          <protocol type="MFC"/>
          <protocol type="FRAG3"/>
        </stack>
      </stacks>
    </subsystem>
    Copy to Clipboard Toggle word wrap
    注記

    上記の例はクリアテキストのパスワードを使用しますが、認証情報ストアを定義して設定ファイル外部にパスワードを定義することもできます。認証情報ストアの設定に関する詳細は、サーバーセキュリティーの設定方法認証情報ストア を参照してください。

22.2.8. JGroups スレッドプールの設定

jgroups サブシステムには defaultinternaloob、および timer スレッドプールが含まれます。これらのプールはすべての JGroups スタックに対して設定でき、ローカルノードに設定された Bean やその他のプールには影響しません。JGroup スレッドプールは、クラスター通信をサポートするために使用されます。

以下の表は、各スレッドプールに設定できる属性とデフォルト値を表しています。

Expand
スレッドプール名説明keepalive-timemax-threadsmin-threadsqueue-length

default

このプールは、帯域外としてマークされていない受信メッセージを処理するために使用されます。

60000L

300

20

100

internal

このプールは、EAP のメンテナンスに必要な内部プロセスを処理するために使用されます。

60000L

4

2

100

oob

このプールは、受信 OOB (out of band) メッセージを処理する場合に使用されます。

60000L

300

20

0

timer

このプールは、タイムバウンドスケジューラーメッセージを処理するために使用されます。

5000L

4

2

500

以下の構文を使用して、管理 CLI で JGroups スレッドプールを設定します。

/subsystem=jgroups/stack=STACK_TYPE/transport=TRANSPORT_TYPE/thread-pool=THREAD_POOL_NAME:write-attribute(name=ATTRIBUTE_NAME, value=ATTRIBUTE_VALUE)
Copy to Clipboard Toggle word wrap

以下は、udp スタックの default スレッドプールで max-threads の値を 500 に設定する管理 CLI コマンドの例になります。

/subsystem=jgroups/stack=udp/transport=UDP/thread-pool=default:write-attribute(name="max-threads", value="500")
Copy to Clipboard Toggle word wrap

22.2.9. JGroups の送受信バッファーの設定

バッファーサイズ警告の解決

デフォルトでは、JGroups は特定の送受信バッファー値で設定されています。しかし、可能なバッファーサイズがオペレーティングシステムによって制限され、JBoss EAP が設定されたバッファー値を使用できないことがあります。このような場合、以下と似た警告が JBoss EAP のログに記録されます。

WARNING [org.jgroups.protocols.UDP] (ServerService Thread Pool -- 68)
JGRP000015: the send buffer of socket DatagramSocket was set to 640KB, but the OS only allocated 212.99KB.
This might lead to performance problems. Please set your max send buffer in the OS correctly (e.g. net.core.wmem_max on Linux)
WARNING [org.jgroups.protocols.UDP] (ServerService Thread Pool -- 68)
JGRP000015: the receive buffer of socket DatagramSocket was set to 20MB, but the OS only allocated 212.99KB.
This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux)
Copy to Clipboard Toggle word wrap

これに対応するには、オペレーティングシステムのマニュアルでバッファーサイズを増やす方法を参照してください。Red Hat Enterprise Linux システムの場合は、root ユーザーとして /etc/sysctl.conf を編集し、システムの再起動後も維持されるバッファーサイズの最大値を設定します。以下に例を示します。

# Allow a 25MB UDP receive buffer for JGroups
net.core.rmem_max = 26214400
# Allow a 1MB UDP send buffer for JGroups
net.core.wmem_max = 1048576
Copy to Clipboard Toggle word wrap

/etc/sysctl.conf を変更後、sysctl -p を実行して変更を反映します。

JGroups バッファーサイズの設定

以下のトランスポートプロパティーを UDP および TCP JGroups スタックに設定すると、JBoss EAP が使用する JGroups バッファーサイズを設定できます。

UDP スタック
  • ucast_recv_buf_size
  • ucast_send_buf_size
  • mcast_recv_buf_size
  • mcast_send_buf_size
TCP スタック
  • recv_buf_size
  • send_buf_size

JGroups バッファーサイズは、管理コンソールまたは管理 CLI を使用して設定できます。

以下の構文を使用して、管理 CLI で JGroups バッファーサイズプロパティーを設定します。

/subsystem=jgroups/stack=STACK_NAME/transport=TRANSPORT/property=PROPERTY_NAME:add(value=BUFFER_SIZE)
Copy to Clipboard Toggle word wrap

以下は、tcp スタックで recv_buf_size プロパティーを 20000000 に設定する管理 CLI コマンドの例になります。

/subsystem=jgroups/stack=tcp/transport=TRANSPORT/property=recv_buf_size:add(value=20000000)
Copy to Clipboard Toggle word wrap

JGroups バッファーサイズは管理コンソールを使用して設定することもできます。Configuration タブで JGroups サブシステムを選択し、表示 をクリックして Stack タブを選択し、該当するスタックを選びます。Transport をクリックし、Properties フィールドを編集します。

22.2.10. JGroups サブシステムのチューニング

jgroups サブシステムのパフォーマンスを監視および最適化するためのヒントは、JBoss EAP のパフォーマンスチューニングJGroups サブシステムのチューニング セクションを参照してください。

22.2.11. JGroups トラブルシューティング

22.2.11.1. ノードがクラスターを形成しない

マシンで IP マルチキャストが正しくセットアップされていることを確認します。JBoss EAP には、IP マルチキャストのテストに使用できる McastReceiverTestMcastSenderTest の 2 つのテストプログラムが含まれています。

ターミナルで McastReceiverTest を開始します。

$ java -cp EAP_HOME/bin/client/jboss-client.jar org.jgroups.tests.McastReceiverTest -mcast_addr 230.11.11.11 -port 5555
Copy to Clipboard Toggle word wrap

別のターミナルウインドウで McastSenderTest を開始します。

$ java -cp EAP_HOME/bin/client/jboss-client.jar org.jgroups.tests.McastSenderTest -mcast_addr 230.11.11.11 -port 5555
Copy to Clipboard Toggle word wrap

特定のネットワークインターフェイスカード (NIC) をバインドする場合は、-bind_addr YOUR_BIND_ADDRESS を使用します。YOUR_BIND_ADDRESS はバインドする NIC の IP アドレスに置き換えます。送信側と受信側の両方にこのパラメーターを使用します。

McastSenderTest ターミナルウインドウで入力すると McastReceiverTest ウインドウに出力が表示されます。表示されない場合は以下の手順に従います。

  • 送信側のコマンドに -ttl VALUE を追加して、マルチキャストパケットの TTL (time-to-live) を増やします。このテストプログラムによって使用されるデフォルトの値は 32 で、VALUE255 以下である必要があります。
  • マシンに複数のインターフェイスがある場合は、適切なインターフェイスを使用していることを確認します。
  • システム管理者に連絡し、マルチキャストが選択したインターフェイスで動作することを確認します。

クラスターの各マシンでマルチキャストが適切に動作したら、送信側と受信側を別々のマシンに配置し、テストを繰り返します。

22.2.11.2. 障害検出での不明なハートビートの原因

ハートビートの確認が一定時間 (T) 受信されないと、障害検出 (FD) によってクラスターメンバーが原因として疑われることがあります。T は timeout および max_tries によって定義されます。

たとえば、ノード A、B、C、および D のクラスターがあり、A が B、B が C、C が D、D が A を ping する場合、以下のいずれかの理由で C が疑われます。

  • B または C が CPU の使用率が 100% の状態で T 秒よりも長く稼働している場合。この場合、C がハートビート確認を B に送信しても、CPU の使用率が 100% であるため B が確認を処理できないことがあります。
  • B または C がガベッジコレクションを実行している場合、上記と同じ結果になります。
  • 上記 2 件の組み合わせ。
  • ネットワークによるパケットの損失が発生する場合。通常、ネットワークに大量のトラフィックがあり、スイッチがパケットを破棄すると発生します (通常は最初にブロードキャスト、次に IP マルチキャスト、そして最後に TCP パケットが破棄されます)。
  • B または C がコールバックを処理する場合。C が処理に T + 1 秒かかるリモートメソッド呼び出しをチャネル上で受信した場合、C はハートビートを含む他のメッセージを処理できません。そのため、B はハートビート確認を受信せず、C が疑われます。

22.3. Infinispan

22.3.1. Infinispan

Infinispan は Java データグリッドプラットフォームで、キャッシュされたデータの管理に Jakarta Persistence 2.2 準拠のキャッシュインターフェイスを提供します。

Infinispan の機能や設定オプションの詳細は Infinispan のドキュメント を参照してください。

infinispan サブシステムは JBoss EAP のキャッシュサポートを提供します。名前付きのキャッシュコンテナーやキャッシュのランタイムメトリックスを設定および表示できます。

高可用性の機能を提供する設定を使用する場合 (マネージドドメインでは hafull-ha プロファイル、スタンドアロンサーバーは standalone-ha.xmlstandalone-full-ha.xml 設定ファイル)、infinispan サブシステムはキャッシング、状態のレプリケーション、および状態分散サポートを提供します。高可用性でない設定では、infinispan サブシステムはローカルのキャッシュサポートを提供します。

重要

Infinispan は、JBoss EAP 8.0 のパブリックモジュールです。アプリケーション用の infinispan サブシステムを使用して、新しいキャッシュコンテナーまたはキャッシュを作成および使用できます。また、Infinispan API の使用は、アプリケーションによってサポートされています。

22.3.2. キャッシュコンテナー

キャッシュコンテナーはサブシステムによって使用されるキャッシュのリポジトリーです。各キャッシュコンテナーは、使用されるデフォルトのキャッシュを定義します。

JBoss EAP 8.0 では、次のデフォルトの Infinispan キャッシュコンテナーが定義されています。

  • server (シングルトンキャッシング)
  • web (Web セッションクラスタリング)
  • ejb (ステートフルセッション Bean クラスタリング)
  • hibernate (エンティティーキャッシング)

例: Infinispan のデフォルト設定

<subsystem xmlns="{InfinispanSubsystemNamespace}">
  <cache-container name="server" aliases="singleton cluster" default-cache="default" module="org.wildfly.clustering.server">
    <transport lock-timeout="60000"/>
    <replicated-cache name="default">
      <transaction mode="BATCH"/>
    </replicated-cache>
  </cache-container>
  <cache-container name="web" default-cache="dist" module="org.wildfly.clustering.web.infinispan">
    <transport lock-timeout="60000"/>
    <distributed-cache name="dist">
      <locking isolation="REPEATABLE_READ"/>
      <transaction mode="BATCH"/>
      <file-store/>
    </distributed-cache>
  </cache-container>
  <cache-container name="ejb" aliases="sfsb" default-cache="dist" module="org.wildfly.clustering.ejb.infinispan">
    <transport lock-timeout="60000"/>
    <distributed-cache name="dist">
      <locking isolation="REPEATABLE_READ"/>
      <transaction mode="BATCH"/>
      <file-store/>
    </distributed-cache>
  </cache-container>
  <cache-container name="hibernate" default-cache="local-query" module="org.hibernate.infinispan">
    <transport lock-timeout="60000"/>
    <local-cache name="local-query">
      <object-memory size="1000"/>
      <expiration max-idle="100000"/>
    </local-cache>
    <invalidation-cache name="entity">
      <transaction mode="NON_XA"/>
      <object-memory size="1000"/>
      <expiration max-idle="100000"/>
    </invalidation-cache>
    <replicated-cache name="timestamps" mode="ASYNC"/>
  </cache-container>
</subsystem>
Copy to Clipboard Toggle word wrap

各キャッシュコンテナーで定義されたデフォルトのキャッシュに注目してください。この例では、web キャッシュコンテナーは dist 分散キャッシュをデフォルトとして定義します。そのため、Web セッションのクラスタリングでは dist キャッシュが使用されます。

デフォルトキャッシュの変更やキャッシュの追加に関する詳細は、キャッシュコンテナーの設定 を参照してください。

22.3.2.1. キャッシュコンテナーの設定

キャッシュコンテナーやキャッシュ属性は、管理コンソールまたは管理 CLI を使用して設定できます。

警告

設定の他のコンポーネントが参照する可能性があるため、キャッシュまたはキャッシュコンテナーの名前を変更しないでください。

22.3.2.1.1. 管理コンソールを使用したキャッシュの設定

管理コンソールの Configuration タブで Infinispan サブシステムを選択するとキャッシュやキャッシュコンテナーを設定できます。マネージドドメインでは設定するプロファイルを選択してください。

  • キャッシュコンテナーを追加します。

    Cache Container の横にある追加 (+) ボタンをクリックし、Cache Container を追加 を選択して新しいキャッシュコンテナーの設定を入力します。

  • キャッシュコンテナー設定を更新します。

    該当するキャッシュコンテナーを選択し、表示 を選択します。必要に応じてキャッシュコンテナーの設定を行います。

  • キャッシュコンテナートランスポート設定を更新します。

    該当するキャッシュコンテナーを選択し、表示 を選択します。Transport タブで、必要に応じてキャッシュコンテナートランスポートを設定します。

  • キャッシュを設定します。

    該当するキャッシュコンテナーを選択し、表示 を選択します。キャッシュタブ (Replicated Cache など) でキャッシュを追加、更新、および削除できます。

22.3.2.1.2. 管理 CLI を使用したキャッシュの設定

管理 CLI を使用してキャッシュおよびキャッシュコンテナーを設定できます。マネージドドメインではコマンドの前に /profile=PROFILE_NAME を追加して更新するプロファイルを指定する必要があります。

  • キャッシュコンテナーを追加します。

    /subsystem=infinispan/cache-container=CACHE_CONTAINER:add
    Copy to Clipboard Toggle word wrap
  • レプリケートされたキャッシュを追加します。

    /subsystem=infinispan/cache-container=CACHE_CONTAINER/replicated-cache=CACHE:add(mode=MODE)
    Copy to Clipboard Toggle word wrap
  • キャッシュコンテナーのデフォルトキャッシュを設定します。

    /subsystem=infinispan/cache-container=CACHE_CONTAINER:write-attribute(name=default-cache,value=CACHE)
    Copy to Clipboard Toggle word wrap
  • レプリケートされたキャッシュのバッチ処理を設定します。

    /subsystem=infinispan/cache-container=CACHE_CONTAINER/replicated-cache=CACHE/component=transaction:write-attribute(name=mode,value=BATCH)
    Copy to Clipboard Toggle word wrap

    これにより、サーバーが以下のように設定されます。

    <cache-container name="web" default-cache="concurrent" module="org.wildfly.clustering.web.infinispan">
      ...
      <distributed-cache name="concurrent">
          <file-store/>
      </distributed-cache>
    </cache-container>
    Copy to Clipboard Toggle word wrap
22.3.2.1.3. デフォルト Jakarta Enterprise Beans キャッシュコンテナーの変更

以下のようにキャッシュコンテナーを ejb3 サブシステムで使用できます。

  • Jakarta Enterprise Beans セッション bean のパッシベーションをサポートするには、infinispan サブシステムに定義された ejb キャッシュコンテナーを使用してセッションを保存できます。
  • サーバー上でクラスター化されたデプロイメントに接続するリモート Jakarta Enterprise Beans クライアントの場合、クラスタートポロジーの情報をこれらのクライアントに提供して、これらのクライアントが対話するノードに障害が発生したときにクラスターの別のノードにフェイルオーバーできるようにする必要があります。
22.3.2.1.4. Infinispan サブシステムから Jakarta EE アプリケーションにリソースを注入する

@Resource アノテーションを使用して、キャッシュなどの Infinispan リソースを Infinispan サブシステムからアプリケーションに注入できます。次の例は、@Resource アノテーションを使用して Jakarta EE アプリケーションにキャッシュを注入する方法を示しています。

@Resource(lookup = "java:jboss/infinispan/cache/foo/bar")
private org.infinispan.Cache<Integer, Object> cache;
Copy to Clipboard Toggle word wrap

上記の例では、foo はキャッシュコンテナーの名前であり、bar は注入するキャッシュの名前です。

EAP は注入されたリソースのライフサイクルを管理するため、アプリケーションはキャッシュやキャッシュマネージャーなどのリソースを管理する必要がありません。

注記

リソースを手動で作成すると、EAP ではなくアプリケーションがそれらのリソースを管理します。

次の例は、Infinispan サブシステムから、さまざまなリソースをアプリケーションに注入する方法を示しています。

デフォルトのキャッシュを注入する例

キャッシュコンテナーのデフォルトキャッシュを Infinispan サブシステムからアプリケーションに注入するには、次のコマンドを使用します。

@Resource(lookup = "java:jboss/infinispan/cache/foo/default")
Copy to Clipboard Toggle word wrap

埋め込みキャッシュマネージャーの注入例

埋め込みキャッシュマネージャーを注入して、アプリケーションが新しいキャッシュ設定とキャッシュを作成できるようにするには、次のコマンドを使用します。

@Resource(lookup = "java:jboss/infinispan/container/foo")
private org.infinispan.manager.EmbeddedCacheManager manager;
Copy to Clipboard Toggle word wrap

キャッシュ設定の注入例

Infinispan サブシステム内で定義されたキャッシュ設定は、アプリケーションがそれらのキャッシュ設定に明示的に依存しない限り、常にインストールされていたり使用できたりするわけではありません。Infinispan サブシステムからアプリケーションにキャッシュ設定を注入するには、@Resource アノテーションを使用します。

  • 次の例では、@Resource アノテーションを使用して foo コンテナーのキャッシュ設定を注入します。

    @Resource(lookup = "java:jboss/infinispan/configuration/foo/bar")
    private org.infinispan.config.Configuration config;
    Copy to Clipboard Toggle word wrap
  • 次の例では、@Resource アノテーションを使用して、foo コンテナーのデフォルトのキャッシュ設定を注入します。

    @Resource(lookup = "java:jboss/infinispan/configuration/foo/default")
    private org.infinispan.config.Configuration config;
    Copy to Clipboard Toggle word wrap
22.3.2.1.5. Hibernate キャッシュコンテナーのエビクション機能

hibernate キャッシュコンテナーのエビクション機能は、メモリーからキャッシュエントリーを削除します。この機能は、サブシステムのメモリー負荷を軽減するのに役立ちます。

size 属性は、キャッシュエントリーのエビクションの開始前に保存されるキャッシュエントリーの最大数を設定します。

例: エビクション機能

  <cache-container name="hibernate" default-cache="local-query" module="org.hibernate.infinispan">
    <transport lock-timeout="60000"/>
    <local-cache name="local-query">
      <object-memory size="1000"/>
      <expiration max-idle="100000"/>
Copy to Clipboard Toggle word wrap

エビクションはメモリー内でのみ実行されることに注意してください。キャッシュストアは、情報の永続的な損失を防ぐためにエビクトされたキャッシュエントリーを保持します。エビクション機能の詳細は、Infinispan ユーザーガイドの エビクションおよびデータコンテナー セクションを参照してください。

22.3.2.1.6. Hibernate キャッシュコンテナーの有効期限機能

hibernate キャッシュコンテナーの有効期限機能は、クラスター化された操作です。したがって、クラスター化されたキャッシュを使用すると、期限切れのキャッシュエントリーがすべてのクラスターメンバーから削除されます。詳細は、Infinispan ユーザーガイドの 有効期限 セクションを参照してください。

22.3.3. クラスタリングモード

JBoss EAP で Infinispan を使用すると、2 つの方法でクラスタリングを設定できます。ご使用のアプリケーションに最も適した方法は要件によって異なります。各モードでは可用性、一貫性、信頼性、およびスケーラビリティーのトレードオフが発生します。クラスタリングモードを選択する前に、ネットワークで最も重要な点を特定し、これらの要件のバランスを取る必要があります。

キャッシュモード
レプリケーション
Replication (レプリケーション) モードはクラスターの新しいインスタンスを自動的に検出し、追加します。これらのインスタンスに加えられた変更は、クラスター上のすべてのノードにレプリケートされます。ネットワークでレプリケートされる情報量が多いため、通常 Replication モードは小型のクラスターでの使用に最も適しています。UDP マルチキャストを使用するよう Infinispan を設定すると、ネットワークトラフィックの輻輳をある程度軽減できます。
Distribution (分散)

Distribution (分散) モードでは、Infinispan はクラスターを線形にスケールできます。Distribution モードは一貫性のあるハッシュアルゴリズムを使用して、クラスター内で新しいノードを配置する場所を決定します。保持する情報のコピー数 (または所有者数) は設定可能です。保持するコピー数、データの永続性、およびパフォーマンスにはトレードオフが生じます。保持するコピー数が多いほどパフォーマンスへの影響が大きくなりますが、サーバーの障害時にデータを損失する可能性は低くなります。ハッシュアルゴリズムは、メタデータのマルチキャストや保存を行わずにエントリーを配置し、ネットワークトラフィックを軽減します。

クラスターサイズが 6-8 ノードを超える場合は Distribution モードをキャッシュストラテジーとして使用することを考慮してください。Distribution モードでは、データはクラスター内のすべてのノードではなくノードのサブセットのみに分散されます。

22.3.3.1. キャッシュモードの設定

管理 CLI を使用してデフォルトキャッシュを変更できます。

注記

ここでは、デフォルトが Distribution モードである Web セッションキャッシュの設定に固有する手順を説明します。手順と管理 CLI コマンドは、他のキャッシュコンテナー向けに簡単に調整できます。

レプリケーションキャッシュモードへの変更

Web セッションキャッシュのデフォルトの JBoss EAP 8.0 設定には、repl レプリケーションキャッシュが含まれていません。最初にこのキャッシュを追加する必要があります。

注記

以下はスタンドアロンサーバーの管理 CLI コマンドになります。マネージドドメインで実行している場合は、/subsystem=infinispan コマンドの前に /profile=PROFILE_NAME を追加し、更新するプロファイルを指定する必要があります。

  1. レプリケーションキャッシュ repl を追加し、デフォルトのキャッシュとして設定します。

    batch
    /subsystem=infinispan/cache-container=web/replicated-cache=repl:add()
    /subsystem=infinispan/cache-container=web/replicated-cache=repl/component=transaction:add(mode=BATCH)
    /subsystem=infinispan/cache-container=web/replicated-cache=repl/component=locking:add(isolation=REPEATABLE_READ)
    /subsystem=infinispan/cache-container=web/replicated-cache=repl/store=file:add
    /subsystem=infinispan/cache-container=web:write-attribute(name=default-cache,value=repl)
    run-batch
    Copy to Clipboard Toggle word wrap
  2. サーバーをリロードします。

    reload
    Copy to Clipboard Toggle word wrap
分散キャッシュモードへの変更

Web セッションキャッシュのデフォルトの JBoss EAP 8.0 設定には、すでに dist ディストリビューションキャッシュが含まれています。

注記

以下はスタンドアロンサーバーの管理 CLI コマンドになります。マネージドドメインで実行している場合は、/subsystem=infinispan コマンドの前に /profile=PROFILE_NAME を追加し、更新するプロファイルを指定する必要があります。

  1. デフォルトのキャッシュを dist 分散キャッシュに変更します。

    /subsystem=infinispan/cache-container=web:write-attribute(name=default-cache,value=dist)
    Copy to Clipboard Toggle word wrap
  2. 分散キャッシュの所有者数を設定します。以下のコマンドは所有者の数を 5 に設定します。デフォルトは 2 です。

    /subsystem=infinispan/cache-container=web/distributed-cache=dist:write-attribute(name=owners,value=5)
    Copy to Clipboard Toggle word wrap
  3. サーバーをリロードします。

    reload
    Copy to Clipboard Toggle word wrap
22.3.3.2. キャッシュストラテジーのパフォーマンス

SYNC キャッシュストラテジーを使用すると、レプリケーションが完了するまでリクエストが完了しないため、レプリケーションのコストを簡単に評価でき、直接応答時間に影響します。

ASYNC キャッシュストラテジーの応答時間は SYNC キャッシュストラテジーよりも短いと思われがちですが、一定の状況下でのみ短くなります。ASYNC キャッシュストラテジーの評価はより困難ですが、リクエスト間の時間がキャッシュ操作を完了できるほど長い場合はパフォーマンスが SYNC よりも良くなります。これは、レプリケーションのコストが応答時間に即影響しないためです。

同じセッションのリクエストの作成が早すぎると、先行リクエストからのレプリケーションが完了するまで待機しなければならないため、先行リクエストのレプリケーションコストが後続リクエストの前に移動します。応答の受信直後に後続リクエストが送信され、リクエストが急速に発生する場合、ASYNC キャッシュストラテジーのパフォーマンスは SYNC よりも劣化します。そのため、同じセッションのリクエストの間には、SYNC キャッシュストラテジーのパフォーマンスが ASYNC キャッシュストラテジーよりも良くなる期間のしきい値があります。実際の使用状態では、通常同じセッションのリクエストが立て続けに受信されることはありませんが、一般的にリクエストの間に数秒程度の時間が存在します。その代わりに、通常、要求間に数秒以上の時間が経過します。この場合、ASYNC キャッシュストラテジーが適切なデフォルトで、応答時間が早くなります。

22.3.4. 状態遷移

状態遷移は、基本的なデータグリッドとクラスター化されたキャッシュ機能の両方です。状態遷移がない状態では、ノードがクラスターに追加されたり、クラスターから削除されるとデータが失われます。

状態遷移は、キャッシュメンバーシップの変更に応じて、キャッシュの内部状態を調整します。この変更は、ノードがクラスターに参加または退出するとき、2 つ以上のクラスターパーティションがマージするとき、またはこれらのイベントの組み合わせが発生した後に自動的に行われます。新しいキャッシュは、以下のキャッシュのモードを基にして、最大量の状態を受け取る必要があるため、新たに開始されたキャッシュの最初の状態遷移は最も多くのリソースが必要となります。

timeout 属性を使用すると、新たに開始されたキャッシュが状態を受け取る待ち時間を制御することができます。timeout 属性が正の値である場合、キャッシュはすべての初期状態を受け取るまで待機した後、リクエストに対応できるようになります。状態遷移が指定時間内 (デフォルトは 240000 ミリ秒) に完了しなかった場合、キャッシュによってエラーが発生し、開始がキャンセルされます。timeout0 に設定するとキャッシュは即座に利用可能になり、バックグラウンド操作中に最初の状態を受け取ります。最初の状態遷移が完了するまで、キャッシュが受け取っていないキャッシュエントリーのリクエストは、リモートノードから取得する必要があります。

timeout 属性を 0 に設定するには、以下のコマンドを実行します。

/subsystem=infinispan/cache-container=server/CACHE_TYPE=CACHE/component=state-transfer:write-attribute(name=timeout,value=0)
Copy to Clipboard Toggle word wrap

状態遷移の挙動はキャッシュのモードによって決まります。

  • レプリケーションモードでは、キャッシュに参加する新規ノードは既存ノードからキャッシュの状態をすべて受け取ります。ノードがクラスターから退出すると、状態遷移はありません。
  • Distribution モードでは、新しいノードは既存のノードから状態の一部のみを受け取り、既存のノードは一貫したハッシュの決定どおりに、各キーの owners コピーを維持するために状態の一部を削除します。ノードがクラスターから退出する場合、分散キャッシュはそのノードに保存されたキーの追加コピーを作成し、各キーの所有者が存続するようにする必要デフォルトがあります。
  • インバリデーションモードでは、最初の状態推移はレプリケーションモードと似ていますが、ノードが同じ状態でいられる保証がないことが唯一の違いです。ノードがクラスターから退出すると、状態遷移はありません。

デフォルトでは、状態遷移はインメモリーおよび永続状態の両方を遷移しますが、設定で無効にすることもできます。状態遷移が無効になっている場合、ClusterLoader を設定しないと、データをキャッシュにロードせずにノードがキーの所有者またはバックアップ所有者になります。さらに、Distribution モードで状態遷移が無効になっていると、キャッシュでキーのコピーが owners コピーよりも少なくなることがあります。

22.3.5. Infinispan スレッドプールの設定

infinispan サブシステムには async-operationsexpirationlistenerpersistenceremote-commandstate-transfer、および transport スレッドプールが含まれます。これらのプールはすべての Infinispan キャッシュコンテナーに設定できます。

以下の表は、infinispan サブシステムの各スレッドプールに設定できる属性とデフォルト値を表しています。

Expand
スレッドプール名keepalive-timemax-threadsmin-threadsqueue-length

async-operations

60000L

25

25

1000

expiration

60000L

1

該当なし

該当なし

listener

60000L

1

1

100000

persistence

60000L

4

1

0

remote-command

60000L

200

1

0

state-transfer

60000L

60

1

0

transport

60000L

25

25

100000

以下の構文を使用して、管理 CLI で Infinispan スレッドプールを設定します。

/subsystem=infinispan/cache-container=CACHE_CONTAINER_NAME/thread-pool=THREAD_POOL_NAME:write-attribute(name=ATTRIBUTE_NAME, value=ATTRIBUTE_VALUE)
Copy to Clipboard Toggle word wrap

以下は、server キャッシュコンテナーの persistence スレッドプールで max-threads の値を 10 に設定する管理 CLI コマンドの例になります。

/subsystem=infinispan/cache-container=server/thread-pool=persistence:write-attribute(name="max-threads", value="10")
Copy to Clipboard Toggle word wrap

22.3.6. Infinispan の統計

監視目的で、Infinispan キャッシュやキャッシュコンテナーに関する実行時統計を有効にできます。パフォーマンス上の理由で、統計の収集はデフォルトでは無効になっています。

統計収集は、各キャッシュコンテナー、キャッシュ、または両方に対して有効にできます。各キャッシュの統計オプションはキャッシュコンテナーのオプションをオーバーライドします。キャッシュコンテナーの統計収集を無効または有効にすると、独自の設定が明示的に指定されている場合以外はそのコンテナーのすべてのキャッシュが設定を継承します。

22.3.6.1. Infinispan 統計の有効化
警告

Infinispan の統計を有効にすると、infinispan サブシステムのパフォーマンスに影響する可能性があります。統計は必要な場合のみ有効にしてください。

管理コンソールまたは管理 CLI を使用すると Infinispan の統計収集を有効または無効にできます。管理コンソールでは、Configuration タブで Infinispan サブシステム選択してキャッシュまたはキャッシュコンテナーを選択し、Statistics Enabled 属性を編集します。管理 CLI を使用する場合は以下のコマンドを実行して統計を有効にします。

キャッシュコンテナーの統計収集を有効にします。サーバーをリロードする必要があります。

/subsystem=infinispan/cache-container=CACHE_CONTAINER:write-attribute(name=statistics-enabled,value=true)
Copy to Clipboard Toggle word wrap

キャッシュの統計収集を有効にします。サーバーをリロードする必要があります。

/subsystem=infinispan/cache-container=CACHE_CONTAINER/CACHE_TYPE=CACHE:write-attribute(name=statistics-enabled,value=true)
Copy to Clipboard Toggle word wrap
注記

以下のコマンドを使用すると、キャッシュの statistics-enabled 属性の定義が解除され、キャッシュコンテナーの statistics-enabled 属性の設定を継承します。

/subsystem=infinispan/cache-container=CACHE_CONTAINER/CACHE_TYPE=CACHE:undefine-attribute(name=statistics-enabled)
Copy to Clipboard Toggle word wrap

22.3.7. Infinispan パーティションの処理

Infinispan クラスター は、データが保存される複数のノードで構築されます。複数のノードに障害が発生した場合のデータの損失を防ぐため、Infinispan は複数のノードで同じデータをコピーします。このレベルのデータ冗長性は owners 属性を使用して設定されます。設定されたノードの数未満のノードが同時にクラッシュしても、Infinispan はデータのコピーを利用できます。

しかし、クラスターから大量のノードが消滅すると最悪の事態を招く可能性があります。

スプリットブレイン

スプリットブレインはクラスターを独立して動作する 2 つ以上のパーティションまたはサブクラスターに分割します。このような場合、異なるパーティションから読み書きする複数のクライアントが同じキャッシュエントリーの異なるバージョンを見ることになり、多くのアプリケーションにとって問題となります。

注記

スプリットブレインの発生を軽減する方法には、冗長化ネットワークや IP ボンディング などがあります。しかし、これらの方法は問題発生のリードタイムを削減するだけです。

複数ノードの連続クラッシュ
複数のノード (所有者の数) が連続してクラッシュし、Infinispan がクラッシュ間の状態を適切に調整する時間がない場合、結果として部分的なデータの損失が発生します。

スプリットブレインや複数ノードの連続クラッシュが原因で、不適切なデータがユーザーに返されないようにすることが大切です。

22.3.7.1. スプリットブレイン

スプリットブレインが発生した場合、各ネットワークパーティションが独自の JGroups ビューをインストールし、他のパーティションからノードを削除します。パーティションはお互いを認識しないため、クラスターが 2 つ以上のパーティションに分割されたかどうかを直接判断することはできません。そのため、明示的な脱退メッセージを送信せずに、1 つ以上のノードが JGroups クラスターから消滅した場合にクラスターが分割されたと判断します。

パーティション処理が無効の場合、各パーティションは継続して独立したクラスターとして機能します。各パーティションはデータの一部のみを認識できる可能性があり、競合する更新をキャッシュに書き込む可能性があります。

パーティション処理が有効の場合、スプリットを検出したときに各パーティションは即座にリバランスを行わず、degrade モードにするかどうかを最初にチェックします。

  • 1 つ以上のセグメントがすべての所有者を失った場合 (最後に行ったリバランスが完了した後に指定した所有者の数以上が脱退した場合)、パーティションは degrade モードになります。
  • 最新の安定したトポロジー でパーティションに単純多数のノード (floor(numNodes/2) + 1) が含まれない場合も、パーティションは degrade モードになります。
  • その他の場合は、パーティションは通常通り動作し、リバランスを開始します。

安定したトポロジー は、リバランス操作が終了するたびに更新され、コーディネーターによって他のリバランスが必要ないと判断された場合に毎回更新されます。これらのルールは、1 つのパーティションが available モードを維持し、他のパーティションが degraded モードになるようにします。

パーティションが degraded モードの場合、完全に所有されたキーへのアクセスのみを許可します。

  • このパーティション内のノード上のコピーをすべて持つエントリーのリクエスト (読み取りおよび書き込み) は許可されます。
  • 消滅したノードによって完全所有または一部所有されたエントリーのリクエストは AvailabilityException によって拒否されます。

これにより、パーティションが同じキーに異なる値を書き込めないようにし (キャッシュの一貫性を保つ)、さらにパーティションが他のパーティションで更新されたキーを読み取れないようにします (陳腐データをなくす)。

注記

2 つのパーティションは分離して開始できます。これらのパーティションはマージされなければ不整合なデータを読み書きできます。将来的に、この状況に対処できるカスタムの可用性ストラテジーが許可される可能性があります (例: 特定のノードがクラスターの一部であるかを確認、外部のマシンにアクセスできるかどうかを確認など)。

22.3.7.2. パーティション処理の設定

パーティション処理はデフォルトで無効になっています。パーティション処理を有効にすると、設定可能な属性が 2 つあります。

Expand
属性

when-split

"DENY_READ_WRITES", "ALLOW_READS", "ALLOW_READ_WRITES"

merge-policy

"NONE", "PREFERRED_ALWAYS", "PREFERRED_NON_NULL", "REMOVE_ALL"

ネットワークパーティションの検出時に、キャッシュの読み取りおよび書き込み動作を決定するために、when-split を設定します。

merge-policy を設定して、複数のネットワークパーティションをマージする際に競合解決ポリシーストラテジーを決定します。

CLI コマンドの例

/subsystem=infinispan/cache-container=web/distributed-cache=dist/component=partition-handling:write-attribute(name=when-split, value=DENY_READ_WRITES)
Copy to Clipboard Toggle word wrap

22.3.7.3. リモートキャッシュコンテナーの設定

マネージドドメインのすべてのサーバーグループにリモートキャッシュを設定する必要があります。statistics-enabled 属性により、指定の remote-cache-container および関連するランタイムキャッシュについてのメトリックのコレクションを有効にできます。

22.3.7.3.1. リモートキャッシュコンテナーの作成

マネージドドメインの各サーバーグループには、一意のリモートキャッシュが必要です。このキャッシュは、同じデータグリッドに所属することができます。そのため、ユーザーは、サーバーグループのソケットバインディングを定義し、ソケットバインディングをリモートキャッシュコンテナーに関連付けることにより、すべてのサーバーグループのリモートキャッシュを設定する必要があります。

手順

  1. socket-binding を定義します。クラスターの各リモート Red Hat Data Grid インスタンスの必要に応じて、コマンドを繰り返し実行します。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=SOCKET_BINDING:add(host=HOSTNAME,port=PORT)
    Copy to Clipboard Toggle word wrap
  2. 新規作成されたソケットバインディングを参照する remote-cache-container を定義します。

    batch
    /subsystem=infinispan/remote-cache-container=CACHE_CONTAINER:add(default-remote-cluster=data-grid-cluster)
    /subsystem=infinispan/remote-cache-container=CACHE_CONTAINER/remote-cluster=data-grid-cluster:add(socket-bindings=[SOCKET_BINDING,SOCKET_BINDING_2,...])
    run-batch
    Copy to Clipboard Toggle word wrap
22.3.7.3.2. リモートキャッシュコンテナーの統計の有効化

statistics-enabled 属性により、指定の remote-cache-container および関連するランタイムキャッシュに関するメトリックのコレクションが有効になります。

  • "foo" という remote-cache-container 場合は、次の操作を使用して統計を有効にします。
/subsystem=infinispan/remote-cache-container=foo:write-attribute(name=statistics-enabled, value=true)
Copy to Clipboard Toggle word wrap
  • "foo" という remote-cache-container は、以下のメトリックがランタイム時に表示されます。
/subsystem=infinispan/remote-cache-container=foo:read-attribute(name=connections)
/subsystem=infinispan/remote-cache-container=foo:read-attribute(name=active-connections)
/subsystem=infinispan/remote-cache-container=foo:read-attribute(name=idle-connections)
Copy to Clipboard Toggle word wrap
  • これらのメトリックの説明は、remote-cache-container に read-resource-description 操作を実行します。
/subsystem=infinispan/remote-cache-container=foo:read-resource-description
Copy to Clipboard Toggle word wrap
  • 以下のメトリックは、選択したデプロイメントによって使用されるリモートキャッシュに固有のものです。
/subsystem=infinispan/remote-cache-container=foo/remote-cache=bar.war:read-resource(include-runtime=true, recursive=true)
{
    "average-read-time" : 1,
    "average-remove-time" : 0,
    "average-write-time" : 2,
    "hits" : 9,
    "misses" : 0,
    "near-cache-hits" : 7,
    "near-cache-invalidations" : 8,
    "near-cache-misses" : 9,
    "near-cache-size" : 1,
    "removes" : 0,
    "time-since-reset" : 82344,
    "writes" : 8
}
Copy to Clipboard Toggle word wrap
  • これらのメトリックの説明は、リモートキャッシュに対して read-resource-description 操作を実行します。
/subsystem=infinispan/remote-cache-container=foo/remote-cache=bar.war:read-resource-description
Copy to Clipboard Toggle word wrap
  • これらのメトリックの一部は計算値 (例: average- *) であり、ヒットやミスなどのその他は集計値です。この集計メトリックは、以下の操作でリセットできます。
/subsystem=infinispan/remote-cache-container=foo/remote-cache=bar.war:reset-statistics()
Copy to Clipboard Toggle word wrap

22.3.8. HTTP セッションの Red Hat Data Grid への外部化

注記

この機能を使用するには Red Hat Data Grid のサブスクリプションが必要です。

Red Hat Data Grid は、HTTP セッションなどの JBoss EAP のアプリケーション固有データの外部キャッシュコンテナーとして使用できます。これにより、アプリケーションとは独立したデータレイヤーのスケーリングが可能になり、さまざまなドメインに存在する可能性がある異なる JBoss EAP クラスターが同じ Red Hat Data Grid クラスターからデータにアクセスできるようになります。また、他のアプリケーションは Red Hat Data Grid によって提供されたキャッシュと対話できます。

以下の例は、HTTP セッションを外部化する方法を説明しています。これは、JBoss EAP のスタンドアロンインスタンスとマネージドドメインの両方に適用されます。

  1. remote-cache-container を作成します。詳細は、リモートキャッシュコンテナーの設定 を参照してください。
  2. HotRod ストアを設定します。HotRod ストアは、JBoss EAP サーバーによって作成された各キャッシュに対して専用のリモートキャッシュを 1 つ使用します。通常、以下の CLI スクリプトのように、JBoss EAP サーバーで 1 つのインバリデーションキャッシュが使用されます。

    注記

    Red Hat Data Grid サーバーでリモートキャッシュを手作業で設定する必要があります。これらのキャッシュに推奨される設定は、楽観的ロックを持つトランザクション分散モードです。キャッシュ名はデプロイメントファイル名に対応する必要があります (例: test.war)。

    リモートキャッシュコンテナーが設定されたら、hotrod ストアを設定して既存のストアを置き換えることができます。以下の CLI スクリプトは、インバリデーションキャッシュとともにセッションをオフロードする典型的なユースケースを示しています。

    batch
    /subsystem=infinispan/cache-container=web/invalidation-cache=CACHE_NAME:add()
    /subsystem=infinispan/cache-container=web/invalidation-cache=CACHE_NAME/store=hotrod:add(remote-cache-container=CACHE_CONTAINER,fetch-state=false,purge=false,passivation=false,shared=true)
    /subsystem=infinispan/cache-container=web/invalidation-cache=CACHE_NAME/component=transaction:add(mode=BATCH)
    /subsystem=infinispan/cache-container=web/invalidation-cache=CACHE_NAME/component=locking:add(isolation=REPEATABLE_READ)
    /subsystem=infinispan/cache-container=web:write-attribute(name=default-cache,value=CACHE_NAME)
    run-batch
    Copy to Clipboard Toggle word wrap

    このスクリプトは新しいインバリデーションキャッシュを設定します。作成後、セッションデータはパフォーマンスの目的でキャッシュに維持され、復元の目的でストアに書き込まれます。

    @Resource アノテーションを使用すると、HotRod クライアントを直接 Jakarta EE アプリケーションにインジェクトすることができます。@Resource アノテーションは hotrod-client.properties ファイルで、クラスパスの設定プロパティーを検索します。

    @Resource(lookup = "java:jboss/infinispan/remote-container/web-sessions")
    private org.infinispan.client.hotrod.RemoteCacheContainer client;
    Copy to Clipboard Toggle word wrap

    例: hotrod-client.properties ファイル

    infinispan.client.hotrod.transport_factory = org.infinispan.client.hotrod.impl.transport.tcp.TcpTransportFactory
    infinispan.client.hotrod.server_list = 127.0.0.1:11222
    infinispan.client.hotrod.marshaller = org.infinispan.commons.marshall.jboss.GenericJBossMarshaller
    infinispan.client.hotrod.async_executor_factory = org.infinispan.client.hotrod.impl.async.DefaultAsyncExecutorFactory
    infinispan.client.hotrod.default_executor_factory.pool_size = 1
    infinispan.client.hotrod.default_executor_factory.queue_size = 10000
    infinispan.client.hotrod.hash_function_impl.1 = org.infinispan.client.hotrod.impl.consistenthash.ConsistentHashV1
    infinispan.client.hotrod.tcp_no_delay = true
    infinispan.client.hotrod.ping_on_startup = true
    infinispan.client.hotrod.request_balancing_strategy = org.infinispan.client.hotrod.impl.transport.tcp.RoundRobinBalancingStrategy
    infinispan.client.hotrod.key_size_estimate = 64
    infinispan.client.hotrod.value_size_estimate = 512
    infinispan.client.hotrod.force_return_values = false
    
    ## below is connection pooling config
    
    maxActive=-1
    maxTotal = -1
    maxIdle = -1
    whenExhaustedAction = 1
    timeBetweenEvictionRunsMillis=120000
    minEvictableIdleTimeMillis=300000
    testWhileIdle = true
    minIdle = 1
    Copy to Clipboard Toggle word wrap

リモートキャッシュコンテナーの保護

SSL を使用してリモート Red Hat Data Grid インスタンスへの通信をセキュアにすることが可能です。これを行うには、JBoss EAP インスタンスで remote-cache-container を設定し、Red Hat Data Grid インスタンスで hotrod コネクターを調整してアクティブなセキュリティーレルムを使用するようにします。

  1. JBoss EAP で client-ssl-context を作成します。他の elytron コンポーネントの生成など、client-ssl-context 作成のその他の詳細は、JBoss EAP の How to Configure Server SecurityUsing a client-ssl-context を参照してください。

    /subsystem=elytron/client-ssl-context=CLIENT_SSL_CONTEXT:add(key-manager=KEY_MANAGER,trust-manager=TRUST_MANAGER)
    Copy to Clipboard Toggle word wrap
  2. クライアント SSL コンテキストを使用するよう、リモートキャッシュコンテナーを設定します。

    /subsystem=infinispan/remote-cache-container=CACHE_CONTAINER/component=security:write-attribute(name=ssl-context,value=CLIENT_SSL_CONTEXT)
    Copy to Clipboard Toggle word wrap
  3. リモート Red Hat Data Grid インスタンスをセキュアにします。各インスタンスの必要に応じて手順を繰り返します。

    1. client-ssl-context で使用されるキーストアをリモート Red Hat Data Grid インスタンスにコピーします。
    2. ApplicationRealm を設定して、このキーストアを使用するようにします。

      /core-service=management/security-realm=ApplicationRealm/server-identity=ssl:add(keystore-path="KEYSTORE_NAME",keystore-relative-to="jboss.server.config.dir",keystore-password="KEYSTORE_PASSWORD")
      Copy to Clipboard Toggle word wrap
    3. hotrod connector を調整して、このセキュリティーレルムを示すようにします。

      /subsystem=datagrid-infinispan-endpoint/hotrod-connector=hotrod-connector/encryption=ENCRYPTION:add(require-ssl-client-auth=false,security-realm="ApplicationRealm")
      Copy to Clipboard Toggle word wrap
    4. リモート Red Hat Data Grid インスタンスをリロードします。

      reload
      Copy to Clipboard Toggle word wrap

22.3.9. リモートストアを使用した HTTP セッションの Red Hat Data Grid への外部化

注記

この機能を使用するには Red Hat Data Grid のサブスクリプションが必要です。

この手順は、セッションを外部化する旧式の方法になります。JBoss EAP 7.2 には、elytron サブシステムと統合する HotRod プロトコルをベースとするカスタムの最適化されたキャッシュストアが導入されました。HTTP セッションの Red Hat Data Grid への外部化 の説明に従って、新しい hotrod ストアを使用することが推奨されます。

注記

分散可能なアプリケーションごとに完全に新しいキャッシュを作成する必要があります。新しいキャッシュは web などの既存のキャッシュコンテナーに作成できます。

HTTP セッションを外部化するには、以下を行います。

  1. ネットワーク情報を socket-binding-group に追加することにより、リモート Red Hat Data Grid サーバーの場所を定義します。

    例: リモートソケットバインディングの追加

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-rhdg-server1:add(host=RHDGHostName1, port=11222)
    
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-rhdg-server2:add(host=RHDGHostName2, port=11222)
    Copy to Clipboard Toggle word wrap

    結果の XML

    <socket-binding-group name="standard-sockets" ... >
      ...
      <outbound-socket-binding name="remote-rhdg-server1">
        <remote-destination host="RHDGHostName1" port="11222"/>
      </outbound-socket-binding>
      <outbound-socket-binding name="remote-rhdg-server2">
        <remote-destination host="RHDGHostName2" port="11222"/>
      </outbound-socket-binding>
    </socket-binding-group>
    Copy to Clipboard Toggle word wrap

    注記

    各 Red Hat Data Grid サーバーにリモートソケットバインディングを設定する必要があります。

  2. リモートキャッシュコンテナーが JBoss EAP の infinispan サブシステムで定義されているようにしてください。以下の例では、remote-store 要素の cache 属性によって、リモート Red Hat Data Grid サーバーのキャッシュ名が定義されます。

    マネージドドメインで実行している場合は、コマンドの前に /profile=PROFILE_NAME を追加してください。

    例: リモートキャッシュコンテナーの追加

    /subsystem=infinispan/cache-container=web/invalidation-cache=rhdg:add(mode=SYNC)
    
    /subsystem=infinispan/cache-container=web/invalidation-cache=rhdg/component=locking:write-attribute(name=isolation,value=REPEATABLE_READ)
    
    /subsystem=infinispan/cache-container=web/invalidation-cache=rhdg/component=transaction:write-attribute(name=mode,value=BATCH)
    
    /subsystem=infinispan/cache-container=web/invalidation-cache=rhdg/store=remote:add(remote-servers=["remote-rhdg-server1","remote-rhdg-server2"], cache=default, socket-timeout=60000, passivation=false, purge=false, shared=true)
    Copy to Clipboard Toggle word wrap

    結果の XML

    <subsystem xmlns="{InfinispanSubsystemNamespace}">
      ...
      <cache-container name="web" default-cache="dist" module="org.wildfly.clustering.web.infinispan" statistics-enabled="true">
        <transport lock-timeout="60000"/>
        <invalidation-cache name="rhdg" mode="SYNC">
          <locking isolation="REPEATABLE_READ"/>
          <transaction mode="BATCH"/>
          <remote-store cache="default" socket-timeout="60000" remote-servers="remote-rhdg-server1 remote-rhdg-server2" passivation="false" purge="false" shared="true"/>
        </invalidation-cache>
        ...
      </cache-container>
    </subsystem>
    Copy to Clipboard Toggle word wrap

22.4. JBoss EAP のフロントエンドロードバランサーとしての設定

バックエンド JBoss EAP サーバーへリクエストをプロキシーするフロントエンドロードバランサーとして動作するよう JBoss EAP と undertow サブシステムを設定できます。Undertow は非同期 IO を使用するため、リクエストに関与するスレッドは接続用の IO スレッドのみになります。同じスレッドがバックエンドサーバーへの接続に使用されます。

以下のプロトコルを使用できます。

  • HTTP/1 および HTTP/2 (h2c) をサポートするプレーンテキスト上の HTTP (http)
  • HTTP/1 および HTTP/2 (h2c) をサポートするセキュアの接続上の HTTP (http)
  • AJP (ajp)

静的ロードバランサー を定義して設定でバックエンドホストを指定するか、mod_cluster フロントエンド を使用してホストを動的に更新します。

22.4.1. mod_cluster を使用した Undertow のロードバランサーとしての設定

組み込みの mod_cluster フロントエンドロードバランサーを使用して、他の EAP インスタンスを負荷分散できます。

この手順では、マネージドドメインを実行し、以下が設定済みであることを前提としています。

  • ロードバランサーとして動作する JBoss EAP サーバー。

    • このサーバーは、load-balancer-sockets ソケットバインディンググループにバインドされる load-balancer プロファイルを使用します。

      注記

      このサーバーをフロントエンドロードバランサーとして使用するため、load-balancer プロファイルには、ソケットバインディング、mod-cluster Undertow フィルター、およびデフォルトホストでのフィルターへの参照がすでに事前設定されています。* バックエンドサーバーとして動作する 2 つの JBoss EAP サーバー。** これらのサーバーはクラスターで実行され、ha-sockets ソケットバインディンググループにバインドされる ha プロファイルを使用します。* 負荷分散の対象となる分散可能なアプリケーションがバックエンドサーバーにデプロイされます。

mod_cluster フロントエンドロードバランサーの設定

以下の手順は、マネージドドメインのサーバーを負荷分散しますが、手順を変更するとスタンドアロンサーバーのセットに適用することができます。ご使用の環境に応じて管理 CLI コマンドの値を変更してください。

手順

  1. mod_cluster アドバタイズセキュリティーキーを設定します。

    アドバタイズセキュリティーキーを追加すると、ロードバランサーとサーバーが検出中に認証されます。

    以下の管理 CLI コマンドを使用して、mod_cluster アドバタイズセキュリティーキーを設定します。

    /profile=ha/subsystem=modcluster/proxy=default:write-attribute(name=advertise-security-key, value=mypassword)
    Copy to Clipboard Toggle word wrap
  2. mod_cluster ロードバランサーのセキュリティーキーを更新します。

    以下の管理 CLI コマンドを使用して、mod_cluster フィルターのセキュリティーキーを設定します。

    /profile=load-balancer/subsystem=undertow/configuration=filter/mod-cluster=load-balancer:write-attribute(name=security-key,value=mypassword)
    Copy to Clipboard Toggle word wrap
重要

mod_cluster によって使用される管理およびアドバタイズソケットバインディングが内部ネットワークのみで公開され、パブリック IP アドレスで公開されないことが推奨されます。

ロードバランサーである JBoss EAP サーバーが 2 つのバックエンドである JBoss EAP サーバーを負荷分散できるようになります。

複数の mod_cluster 設定

mod_cluster サブシステムは名前の付いたプロキシー設定を複数サポートし、デフォルトでない undertow サーバーをリバースプロキシーに登録できます。さらに、単一のアプリケーションサーバーノードを異なるグループのプロキシーサーバーに登録することができます。

以下の例は、ajp-listener、サーバー、および undertow サーバーへのホストを追加します。また、アドバタイズのメカニズムを使用してホストを登録する新しい mod_cluster 設定も追加します。

/socket-binding-group=standard-sockets/socket-binding=ajp-other:add(port=8010)
/subsystem=undertow/server=other-server:add
/subsystem=undertow/server=other-server/ajp-listener=ajp-other:add(socket-binding=ajp-other)
/subsystem=undertow/server=other-server/host=other-host:add(default-web-module=root-other.war)
/subsystem=undertow/server=other-server/host=other-host
/location=other:add(handler=welcome-content)
/subsystem=undertow/server=other-server/host=other-host:write-attribute(name=alias,value=[localhost]))

/socket-binding-group=standard-sockets/socket-binding=modcluster-other:add(multicast-address=224.0.1.106,multicast-port=23364)
/subsystem=modcluster/proxy=other:add(advertise-socket=modcluster-other,balancer=other-balancer,connector=ajp-other)

reload
Copy to Clipboard Toggle word wrap

22.4.2. ロードバランサーでのランク付けされたセッションアフィニティーの有効化

distributable-web サブシステムで複数の順序付けされたルートを持つセッションアフィニティーを設定するには、ランク付けされたセッションアフィニティーをロードバランサーで有効にする必要があります。distributable-web サブシステムと各種アフィニティーオプションの詳細は、JBoss EAP の 開発ガイド分散可能な Web セッション設定のための分散可能な Web サブシステム を参照してください。

ノードルートを分離するデフォルトの区切り文字は . です。別の値が必要な場合は、affinity リソースの delimiter 属性を設定できます。

手順

  1. ロードバランサーに対して、ランク付けされたセッションアフィニティーを有効にします。

    /subsystem=undertow/configuration=filter/mod-cluster=load-balancer/affinity=ranked:add
    Copy to Clipboard Toggle word wrap
  2. オプション: affinity リソースの delimiter 属性を設定します。

    /subsystem=undertow/configuration=filter/mod-cluster=load-balancer/affinity=ranked:write-attribute(name=delimiter,value=':')
    Copy to Clipboard Toggle word wrap

22.4.3. Undertow の静的ロードバランサーとしての設定

Undertow の静的ロードバランサーを設定するには、undertow サブシステムでプロキシーハンドラーを設定する必要があります。Undertow でプロキシーハンドラーを設定するには、静的ロードバランサーとして動作する JBoss EAP インスタンスで以下を行う必要があります。

  1. リバースプロキシーハンドラーを追加します。
  2. 各リモートホストの送信ソケットバインディングを定義します。
  3. 各リモートホストをリバースプロキシーハンドラーへ追加します。
  4. リバースプロキシーの場所を追加します。

以下の例は、JBoss EAP インスタンスを静的ロードバランサーとして設定する方法を示しています。JBoss EAP インスタンスは lb.example.com にあり、2 つの追加サーバーである server1.example.comserver2.example.com との間で負荷分散を行います。ロードバランサーは /app に逆プロキシーを行い、AJP プロトコルを使用します。

手順

  1. リバースプロキシーハンドラーを追加するには、以下を指定します。

    /subsystem=undertow/configuration=handler/reverse-proxy=my-handler:add
    Copy to Clipboard Toggle word wrap
  2. 各リモートホストの送信ソケットバインディングを定義するには、以下を指定します。

    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host1/:add(host=server1.example.com, port=8009)
    
    /socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=remote-host2/:add(host=server2.example.com, port=8009)
    Copy to Clipboard Toggle word wrap
  3. 各リモートホストをリバースプロキシーハンドラーに追加するには、以下を指定します。

    /subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host1:add(outbound-socket-binding=remote-host1, scheme=ajp, instance-id=myroute1, path=/test)
    
    /subsystem=undertow/configuration=handler/reverse-proxy=my-handler/host=host2:add(outbound-socket-binding=remote-host2, scheme=ajp, instance-id=myroute2, path=/test)
    Copy to Clipboard Toggle word wrap
  4. リバースプロキシーの場所を追加するには、以下を指定します。

    /subsystem=undertow/server=default-server/host=default-host/location=\/test:add(handler=my-handler)
    Copy to Clipboard Toggle word wrap

lb.example.com:8080/app にアクセスすると、server1.example.com および server2.example.com からプロキシーされた内容が表示されるようになります。

22.5. 外部 Web サーバーのプロキシーサーバーとしての使用

JBoss EAP は、外部 Web サーバーの設定に応じて、サポートされる HTTP、HTTPS、または AJP プロトコルを使用して外部 Web サーバーからリクエストを許可できます。

各 Web サーバーのサポートされる HTTP コネクターの詳細は、HTTP コネクターの概要 を参照してください。使用する Web サーバーと HTTP コネクターを決定したら、適切なコネクターの設定情報の項を参照してください。

HTTP コネクターのサポートされる構成に関する最新情報は、JBoss EAP でサポートされる構成 を参照してください。

また、JBoss EAP が 外部 Web サーバーからのリクエストを許可 するよう設定されている必要があります。

22.5.1. HTTP コネクターの概要

JBoss EAP には、Apache HTTP Server、Microsoft IIS、Oracle iPlanet などの外部 Web サーバーや Undertow より構築された負荷分散およびクラスタリングメカニズムを使用する機能があります。JBoss EAP はコネクターを使用して Web サーバーと通信します。これらのコネクターは JBoss EAP の undertow サブシステム内に設定されます。

Web サーバーには、HTTP リクエストが JBoss EAP ノードにルーティングされる方法を制御するソフトウェアモジュールが含まれています。これらのモジュールの挙動や設定方法はモジュールごとに異なります。モジュールは、複数の JBoss EAP ノード全体でワークロードを分散したり、障害発生時にワークロードを他のサーバーに移動したりするために設定されます。

JBoss EAP は複数のコネクターをサポートします。使用中の Web サーバーや必要な機能に応じてコネクターを選択します。以下の表を参照して、サポートされる構成と、JBoss EAP と互換性のある HTTP コネクターの機能を比較してください。

JBoss EAP 8.0 をマルチプラットフォームロードバランサーとして使用する方法の詳細は、mod_cluster を使用した Undertow のロードバランサーとしての設定 を参照してください。

HTTP コネクターのサポートされる構成に関する最新情報は、JBoss EAP でサポートされる構成 を参照してください。

Expand
表22.1 HTTP コネクターのサポートされる構成
コネクターWeb Serverサポート対象オペレーティングシステムサポート対象プロトコル

mod_cluster

Red Hat JBoss Core Services の Apache HTTP Server、Red Hat JBoss Web Server の Apache HTTP Server、JBoss EAP (Undertow)

Red Hat Enterprise Linux、Microsoft Windows Server

HTTP、HTTPS、AJP、WebSocket

mod_jk

Red Hat JBoss Core Services の Apache HTTP Server、Red Hat JBoss Web Server の Apache HTTP Server

Red Hat Enterprise Linux、Microsoft Windows Server

AJP

mod_proxy

Red Hat JBoss Core Services の Apache HTTP Server、Red Hat JBoss Web Server の Apache HTTP Server

Red Hat Enterprise Linux、Microsoft Windows Server

HTTP、HTTPS、AJP

ISAPI コネクター

Microsoft IIS

Microsoft Windows Server

AJP

NSAPI コネクター

Oracle iPlanet Web Server

 

AJP

Expand
表22.2 HTTP コネクターの機能
コネクタースティッキーセッションのサポートデプロイメント状態への適合

mod_cluster

可。アプリケーションのデプロイメントとアンデプロイメントを検出し、アプリケーションがそのサーバーにデプロイされたかどうかに基づいて、サーバーにクライアント要求を送信するかどうかを動的に決定します。

mod_jk

不可。アプリケーションの状態に関係なく、コンテナーが利用可能な限り、クライアント要求をコンテナーに送信します。

mod_proxy

不可。アプリケーションの状態に関係なく、コンテナーが利用可能な限り、クライアント要求をコンテナーに送信します。

ISAPI コネクター

不可。アプリケーションの状態に関係なく、コンテナーが利用可能な限り、クライアント要求をコンテナーに送信します。

NSAPI コネクター

不可。アプリケーションの状態に関係なく、コンテナーが利用可能な限り、クライアント要求をコンテナーに送信します。

22.5.2. Apache HTTP Server

スタンドアロン Apache HTTP Server バンドルは、Red Hat JBoss Core Services の個別ダウンロードとして利用できるようになりました。これにより、インストールと設定が容易になり、更新の一貫性が保たれます。

22.5.2.1. Apache HTTP Server のインストール

Apache HTTP Server のインストールは、JBoss Core Services の Apache HTTP Server インストールガイド を参照してください。

22.5.3. 外部 Web サーバーからのリクエストの許可

JBoss EAP に AJP、HTTP、HTTPS などの適切なプロトコルハンドラーが設定されていれば、プロキシーサーバーからのリクエストを許可するための特別な設定は必要ありません。

プロキシーサーバーが mod_jk、mod_proxy、ISAPI、または NSAPI を使用する場合、リクエストを JBoss EAP に送信し、JBoss EAP は応答を返信します。mod_cluster の場合、リクエストをどこにルーティングするかを判断できるようにするため、JBoss EAP が現在の負荷、アプリケーションライフサイクルイベント、ヘルス状態などの情報をプロキシーサーバーへ送信できるようネットワークを設定する必要もあります。mod_cluster プロキシーサーバーの設定に関する詳細は mod_cluster HTTP コネクター を参照してください。

JBoss EAP 設定の更新

以下の手順では、例で使用されているプロトコルやポートを実際に設定する必要があるプロトコルやポートに置き換えてください。

手順

  1. Undertow の instance-id 属性を設定します。

    外部 Web サーバーは instance-id を使用してコネクター設定の JBoss EAP インスタンスを識別します。以下の管理 CLI コマンドを使用して、Undertow で instance-id 属性を設定します。

    /subsystem=undertow:write-attribute(name=instance-id,value=node1)
    Copy to Clipboard Toggle word wrap

    上記の例では、外部 Web サーバーは現在の JBoss EAP インスタンスを node1 として識別します。

  2. 必要なリスナーを Undertow に追加します。

    外部 Web サーバーが JBoss EAP に接続するには、Undertow にリスナーが必要です。各プロトコルにはソケットバインディングに関連する独自のリスナーが必要です。

    注記

    プロトコルやポート設定によってはこの手順は必要でないことがあります。HTTP リスナーはデフォルトの JBoss EAP 設定すべてに設定されており、ha または full-ha プロファイルを使用している場合、AJP リスナーは設定されています。

    デフォルトのサーバー設定を確認すると、必要なリスナーが設定済みであるかどうかを確認できます。

    /subsystem=undertow/server=default-server:read-resource
    Copy to Clipboard Toggle word wrap

    リスナーを Undertow に追加するには、ソケットバインディングが必要です。ソケットバインディングは、サーバーまたはサーバーグループによって使用されるソケットバインディンググループに追加されます。以下の管理 CLI コマンドを使用すると、ajp ソケットバインディングが追加され、ポート 8009standard-sockets ソケットバインディンググループにバインドされます。

    /socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)
    Copy to Clipboard Toggle word wrap

    以下の管理 CLI コマンドを使用すると ajp ソケットバインディングを使用して ajp リスナーが Undertow に追加されます。

    /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)
    Copy to Clipboard Toggle word wrap

22.6. mod_cluster HTTP コネクター

mod_cluster コネクターは Apache HTTP Server ベースのロードバランサーです。通信チャネルを使用して、リクエストを Apache HTTP Server からアプリケーションサーバーノードのセットの 1 つに転送します。

他のコネクターと比べて mod_cluster コネクターには複数の利点があります。

  • mod_cluster Management Protocol (MCMP) は、JBoss EAP サーバーと mod_cluster が有効な Apache HTTP Server との間の追加的な接続です。HTTP メソッドのカスタムセットを使用してサーバー側の負荷分散係数およびライフサイクルイベントを Apache HTTP Server サーバーに返信するために JBoss EAP サーバーによって使用されます。
  • mod_cluster がある Apache HTTP Server を動的に設定すると、手動設定を行わずに JBoss EAP サーバーが負荷分散に参加できます。
  • JBoss EAP は、mod_cluster がある Apache HTTP Server に依存せずに負荷分散係数の計算を行います。これにより、負荷分散メトリックが他のコネクターよりも正確になります。
  • mod_cluster コネクターにより、アプリケーションライフサイクルを細かく制御できるようになります。各 JBoss EAP サーバーは Web アプリケーションコンテキストライフサイクルイベントを Apache HTTP Server サーバーに転送し、指定コンテキストのルーティングリクエストを開始または停止するよう通知します。これにより、リソースを使用できないことが原因の HTTP エラーがエンドユーザーに表示されないようになります。
  • AJP、HTTP、または HTTPS トランスポートを使用できます。

modcluster サブシステムの特定の設定オプションに関する詳細は、ModCluster サブシステムの属性 を参照してください。

22.6.1. Apache HTTP Server の mod_cluster の設定

JBoss Core Services Apache HTTP Server をインストールする場合や JWS を使用する場合、mod_cluster モジュールはすでに含まれており、デフォルトでロードされます。

注記

Apache HTTP Server は、バージョン 3.1.0 以降、JWS には同梱されなくなりました。

以下の手順を参照し、お使いの環境に合った mod_cluster モジュールを設定します。

注記

Red Hat のお客様は Red Hat カスタマーポータルにある Load Balancer Configuration Tool を使用して mod_cluster やその他のコネクターに最適な設定テンプレートを迅速に生成することもできます。このツールを使用するにはログインする必要があります。

mod_cluster の設定

Apache HTTP Server には、mod_cluster モジュールをロードし、基本設定を提供する mod_cluster 設定ファイル mod_cluster.conf がすでに含まれています。このファイルに指定されている IP アドレス、ポート、およびその他の設定 (以下参照) は必要に応じて変更できます。

# mod_proxy_balancer should be disabled when mod_cluster is used
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule cluster_slotmem_module modules/mod_cluster_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule advertise_module modules/mod_advertise.so

MemManagerFile cache/mod_cluster

<IfModule manager_module>
  Listen 6666
  <VirtualHost *:6666>
    <Directory />
      Require ip 127.0.0.1
    </Directory>
    ServerAdvertise on
    EnableMCPMReceive
    <Location /mod_cluster_manager>
      SetHandler mod_cluster-manager
      Require ip 127.0.0.1
   </Location>
  </VirtualHost>
</IfModule>
Copy to Clipboard Toggle word wrap

Apache HTTP Server サーバーはロードバランサーとして設定でき、JBoss EAP で実行されている modcluster サブシステムと動作します。JBoss EAP が mod_cluster を認識するよう mod_cluster ワーカーノードを設定 する必要があります。

mod_cluster のアドバタイズを無効にし、代わりに静的プロキシーリストを設定する場合は mod_cluster のアドバタイズの無効化 を参照してください。Apache HTTP Server で使用できる mod_cluster 設定オプションの詳細は、Apache HTTP Server の mod_cluster ディレクティブ を参照してください。

mod_cluster の設定の詳細は、JWS HTTP コネクターおよび負荷分散ガイドApache HTTP Server および mod_cluster を使用した負荷分散の設定 セクションを参照してください。

22.6.2. mod_cluster のアドバタイズの無効化

デフォルトでは、modcluster サブシステムのバランサーはマルチキャスト UDP を使用して可用性をバックグラウンドワーカーにアドバタイズします。アドバタイズを無効にし、代わりにプロキシーリストを使用する場合は、以下の手順に従ってください。

注記

以下の手順の管理 CLI コマンドは、マネージドドメインで full-ha プロファイルを使用していることを前提としています。full-ha 以外のプロファイルを使用している場合は、コマンドに適切なプロファイル名を使用してください。スタンドアロンサーバーを実行している場合は /profile=full-ha を削除してください。

  1. Apache HTTP Server 設定を変更します。

    httpd.conf Apache HTTP Server 設定ファイルを編集します。EnableMCPMReceive ディレクティブを使用して、MCPM リクエストをリッスンする仮想ホストに以下の更新を加えてください。

    1. サーバーアドバタイズメントを無効にするディレクティブを追加します。

      ServerAdvertise ディレクティブを Off に設定し、サーバーのアドバタイズを無効にします。

      ServerAdvertise Off
      Copy to Clipboard Toggle word wrap
    2. アドバタイズの頻度を無効にします。

      設定に AdvertiseFrequency が指定されている場合は # 文字を使用してコメントアウトします。

      # AdvertiseFrequency 5
      Copy to Clipboard Toggle word wrap
    3. MCPM メッセージの受信機能を有効にします。

      Web サーバーがワーカーノードから MCPM メッセージを受信できるようにするため、必ず EnableMCPMReceive ディレクティブが存在するようにしてください。

      EnableMCPMReceive
      Copy to Clipboard Toggle word wrap
  2. modcluster サブシステムでアドバタイズを無効にします。

    以下の管理 CLI コマンドを使用してアドバタイズを無効にします。

    /profile=full-ha/subsystem=modcluster/proxy=default:write-attribute(name=advertise,value=false)
    Copy to Clipboard Toggle word wrap
    重要

    必ず次のステップでプロキシーのリストを提供してください。プロキシーのリストが空であるとアドバタイズが無効になりません。

  3. JBoss EAP の modcluster サブシステムにプロキシーのリストを提供します。

    アドバタイズが無効になっていると modcluster サブシステムは自動的にプロキシーを検出できないため、プロキシーのリストを提供する必要があります。

    最初に、適切なソケットバインディンググループに送信ソケットバインディングを定義します。

    /socket-binding-group=full-ha-sockets/remote-destination-outbound-socket-binding=proxy1:add(host=10.33.144.3,port=6666)
    /socket-binding-group=full-ha-sockets/remote-destination-outbound-socket-binding=proxy2:add(host=10.33.144.1,port=6666)
    Copy to Clipboard Toggle word wrap

    次に、プロキシーを mod_cluster 設定に追加します。

    /profile=full-ha/subsystem=modcluster/proxy=default:list-add(name=proxies,value=proxy1)
    /profile=full-ha/subsystem=modcluster/proxy=default:list-add(name=proxies,value=proxy2)
    Copy to Clipboard Toggle word wrap

Apache HTTP Server のバランサーがその存在をワーカーノードにアドバタイズしなくなり、UDP マルチキャストが使用されないようになります。

22.6.3. mod_cluster ワーカーノードの設定

mod_cluster ワーカーノードは、JBoss EAP サーバーで構成されます。このサーバーは、スタンドアロンサーバーまたはマネージドドメインのサーバーグループの一部になります。個別のプロセスが JBoss EAP 内で実行され、クラスターのワーカーノードをすべて管理します。これは、マネージドドメインではプライマリー、スタンドアロンサーバーではマスターと呼ばれます。

マネージドドメインのワーカーノードは、サーバーグループ全体で同じ設定を共有します。スタンドアロンサーバーとして実行しているワーカーノードは個別に設定されます。設定手順は同じです。

  • スタンドアロンサーバーは standalone-ha または standalone-full-ha プロファイルで起動する必要があります。
  • マネージドドメインのサーバーグループは ha または full-ha プロファイルを使用し、ha-sockets または full-ha-sockets ソケットバインディンググループを使用する必要があります。JBoss EAP にはこれらの要件を満たし、クラスターが有効になっている other-server-group というサーバーグループが含まれます。
ワーカーノードの設定

この手順の管理 CLI コマンドは、full-ha プロファイルのマネージドドメインを使用していることを前提としています。スタンドアロンサーバーを実行している場合は、コマンドの /profile=full-ha の部分を削除してください。

手順

  1. ネットワークインターフェイスの設定

    デフォルトでは、ネットワークインターフェイスがすべて 127.0.0.1 に設定されます。スタンドアロンサーバーまたはサーバーグループ内の 1 つまたは複数のサーバーをホストする各物理ホストでは、インターフェイスが他のサーバーが見つけることができるパブリック IP アドレスを使用するよう設定する必要があります。

    以下の管理 CLI コマンドを使用して、ご使用の環境に合うよう managementpublic、および unsecure インターフェイスの外部 IP アドレスを変更します。コマンドの EXTERNAL_IP_ADDRESS をホストの実際の外部 IP アドレスに置き換えてください。

    /interface=management:write-attribute(name=inet-address,value="${jboss.bind.address.management:EXTERNAL_IP_ADDRESS}")
    /interface=public:write-attribute(name=inet-address,value="${jboss.bind.address.public:EXTERNAL_IP_ADDRESS}")
    /interface=unsecure:write-attribute(name=inet-address,value="${jboss.bind.address.unsecure:EXTERNAL_IP_ADDRESS}")
    Copy to Clipboard Toggle word wrap

    サーバーをリロードします。

    reload
    Copy to Clipboard Toggle word wrap
  2. ホスト名を設定します。

    マネージドドメインに参加する各ホストに一意なホスト名を設定します。この名前は、セカンダリー全体で一意である必要があり、セカンダリーがクラスターを識別するために使用されます。そのため、使用する名前を控えておいてください。

    1. 適切な host.xml 設定ファイルを使用して、JBoss EAP セカンダリーホストを起動します。

      $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml
      Copy to Clipboard Toggle word wrap
    2. 以下の管理 CLI コマンドを使用して、一意なホスト名を設定します。この例では、新しいホスト名として secondary1 を使用します。

      /host=EXISTING_HOST_NAME:write-attribute(name=name,value=secondary1)
      Copy to Clipboard Toggle word wrap

      ホスト名の設定に関する詳細は、ホスト名の設定 を参照してください。

  3. ドメインコントローラーに接続する各ホストを設定します。

    注記

    このステップはスタンドアロンサーバーには適用されません。

    + 新たに設定されたホストがマネージドドメインに参加する必要がある場合、ローカル要素を削除し、ドメインコントローラーを示すリモート要素ホスト属性を追加する必要があります。

    + ..適切な host.xml 設定ファイルを使用して、JBoss EAP セカンダリーホストを起動します。

    +

    $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml
    Copy to Clipboard Toggle word wrap
    1. 以下の管理 CLI コマンドを使用して、ドメインコントローラーを設定します。

      /host=SECONDARY_HOST_NAME:write-remote-domain-controller(host=DOMAIN_CONTROLLER_IP_ADDRESS,port=${jboss.domain.primary.port:9990},security-realm="ManagementRealm")
      Copy to Clipboard Toggle word wrap

      これにより、host-secondary.xml ファイル内の XML が次のように変更されます。

      <domain-controller>
          <remote host="DOMAIN_CONTROLLER_IP_ADDRESS" port="${jboss.domain.primary.port:9990}" security-realm="ManagementRealm"/>
      </domain-controller>
      Copy to Clipboard Toggle word wrap

      詳細は、ホストコントローラーの設定 を参照してください。

  4. 各セカンダリーホストの認証を設定します。

    各セカンダリーサーバーには、ドメインコントローラーのプライマリーまたはスタンドアロンのマスター ManagementRealm で作成されたユーザー名とパスワードが必要です。ドメインコントローラーのプライマリーまたはスタンドアロンのマスターで、各ホストに対して EAP_HOME/bin/add-user.sh コマンドを実行します。セカンダリーのホスト名と一致するユーザー名を使用して、各ホストの管理ユーザーを追加します。

    秘密の値が提供されるようにするため、必ず最後の質問 ("Is this new user going to be used for one AS process to connect to another AS process?") に yes と返答してください。

    例: add-user.sh スクリプト出力 (抜粋)

    $ EAP_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
    
    Username : secondary1
    Password : changeme
    Re-enter Password : changeme
    What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]:
    About to add user 'secondary1' for realm 'ManagementRealm'
    Is this correct yes/no? yes
    Is this new user going to be used for one AS process to connect to another AS process?
    e.g. for a secondary host controller connecting to the primary or for a Remoting connection for server to server {JEB} calls.
    yes/no? yes
    To represent the user add the following to the server-identities definition <secret value="SECRET_VALUE" />
    Copy to Clipboard Toggle word wrap

    ここで出力された Base64 でエンコードされた秘密の値 SECRET_VALUE をコピーします。この値は次のステップで使用することがあります。

    詳細は、JBoss EAP の サーバーセキュリティーの設定方法 ガイドの プライマリードメインコントローラーへのユーザーの追加 セクションを参照してください。

  5. 新しい認証を使用するようにセカンダリーホストのセキュリティーレルムを変更します。

    サーバー設定に秘密の値を指定する方法、認証情報ストアまたは vault からパスワードを取得する方法、またはパスワードをシステムプロパティーとして渡す方法のいずれかでパスワードを指定できます。

    • 管理 CLI を使用して、サーバー設定ファイルに Base64 でエンコードされたパスワード値を指定します。

      以下の管理 CLI コマンドを使用して秘密の値を指定します。必ず SECRET_VALUE を前のステップの add-user 出力から返された秘密の値に置き換えてください。

      /host=SECONDARY_HOST_NAME/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="SECRET_VALUE")
      Copy to Clipboard Toggle word wrap

      サーバーをリロードする必要があります。--host 引数はスタンドアロンサーバーには適用されません。

      reload --host=HOST_NAME
      Copy to Clipboard Toggle word wrap

      詳細は、JBoss EAP の サーバーセキュリティーの設定方法 ガイドの 認証情報を使用するためのセカンダリーコントローラーの設定 セクションを参照してください。

    • ホストを設定し、認証情報ストアからパスワードを取得します。

      秘密の値を認証情報ストアに保存した場合、以下のコマンドを使用してサーバーの秘密の値が認証情報ストアからの値になるよう設定できます。

      /host=SECONDARY_HOST_NAME/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(credential-reference={store=STORE_NAME,alias=ALIAS}
      Copy to Clipboard Toggle word wrap

      サーバーをリロードする必要があります。--host 引数はスタンドアロンサーバーには適用されません。

      reload --host=HOST_NAME
      Copy to Clipboard Toggle word wrap

      詳細は、JBoss EAP の サーバーセキュリティーの設定方法認証情報ストア を参照してください。

    • ホストを設定し、vault からパスワードを取得します。

      1. EAP_HOME/bin/vault.sh スクリプトを使用してマスクされたパスワードを生成します。以下のような VAULT::secret::password::VAULT_SECRET_VALUE 形式の文字列が生成されます。

        VAULT::secret::password::ODVmYmJjNGMtZDU2ZC00YmNlLWE4ODMtZjQ1NWNmNDU4ZDc1TElORV9CUkVBS3ZhdWx0.
        Copy to Clipboard Toggle word wrap
        注記

        vault でパスワードを作成する場合、Base64 エンコードではなくプレーンテキストで指定する必要があります。

      2. 以下の管理 CLI コマンドを使用して秘密の値を指定します。必ず VAULT_SECRET_VALUE を前のステップで生成したマスクされたパスワードに置き換えてください。

        /host=primary/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${VAULT::secret::password::VAULT_SECRET_VALUE}")
        Copy to Clipboard Toggle word wrap

        サーバーをリロードする必要があります。--host 引数はスタンドアロンサーバーには適用されません。

        reload --host=HOST_NAME
        Copy to Clipboard Toggle word wrap

        詳細は、JBoss EAP の サーバーセキュリティーの設定方法パスワード vault を参照してください。

    • システムプロパティーとしてパスワードを指定します。

      次の例は、server.identity.password をパスワードのシステムプロパティー名として使用します。

      1. サーバー設定ファイルでパスワードのシステムプロパティーを指定します。

        以下の管理 CLI コマンドを使用して、システムプロパティーを使用する秘密のアイデンティティーを設定します。

        /host=SECONDARY_HOST_NAME/core-service=management/security-realm=ManagementRealm/server-identity=secret:add(value="${server.identity.password}")
        Copy to Clipboard Toggle word wrap

        サーバーをリロードする必要があります。--host 引数はスタンドアロンサーバーには適用されません。

        reload --host=primary
        Copy to Clipboard Toggle word wrap
      2. サーバーの起動時にシステムプロパティーのパスワードを設定します。

        server.identity.password システムプロパティーを設定するには、このプロパティーをコマンドライン引数として渡すか、プロパティーファイルで渡します。

        1. プレーンテキストのコマンドライン引数として渡します。

          サーバーを起動し、server.identity.password プロパティーを渡します。

          $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml -Dserver.identity.password=changeme
          Copy to Clipboard Toggle word wrap
          警告

          パスワードはプレーンテキストで入力する必要があります。ps -ef コマンドを実行すると、このパスワードを確認できます。

        2. プロパティーファイルでプロパティーを設定します。

          プロパティーファイルを作成し、キーバリューペアをプロパティーファイルに追加します。例を以下に示します。

          server.identity.password=changeme
          Copy to Clipboard Toggle word wrap
          警告

          パスワードはプレーンテキストで、このプロパティーファイルにアクセスできるユーザーはパスワードを確認できます。

          + コマンドライン引数を使用してサーバーを起動します。

          +

          $ EAP_HOME/bin/domain.sh --host-config=host-secondary.xml --properties=PATH_TO_PROPERTIES_FILE
          Copy to Clipboard Toggle word wrap
  6. サービスを再起動します。

    ホスト名をユーザー名として、暗号化された文字列をパスワードとして使用して、セカンダリーがプライマリーに対して認証するようになります。

スタンドアロンサーバーまたはマネージドドメインのサーバーグループ内のサーバーが mod_cluster ワーカーノードとして設定されます。クラスター化されたアプリケーションをデプロイする場合、セッションはフェイルオーバーのためにすべてのクラスターサーバーに複製され、外部 Web サーバーまたはロードバランサーからのリクエストを許可できます。クラスターの各ノードは、デフォルトで自動検出を使用して他のノードを検出します。

22.6.4. mod_cluster の fail_on_status パラメーターの設定

fail_on_status パラメーターは、クラスターのワーカーノードによって返されるとそのノードの失敗を意味する HTTP ステータスコードをリストします。ロードバランサーはその後のリクエストをクラスターの別のワーカーノードに送信します。失敗したワーカーノードは、ロードバランサーに STATUS メッセージを送信するまで NOTOK の状態になります。

fail_on_status パラメーターはロードバランサーの httpd 設定ファイルに設定する必要があります。fail_on_status の HTTP ステータスコードが複数ある場合はコンマで区切って指定します。以下の例は、HTTP ステータスコード 203 および 204fail_on_status に指定します。

例: fail_on_status の設定

ProxyPass / balancer://MyBalancer stickysession=JSESSIONID|jsessionid nofailover=on failonstatus=203,204
ProxyPassReverse / balancer://MyBalancer
ProxyPreserveHost on
Copy to Clipboard Toggle word wrap

22.6.5. クラスター間のトラフィックの移行

JBoss EAP を使用して新しいクラスターを作成した後、アップグレードプロセスの一部として以前のクラスターから新しいクラスターへトラフィックを移行できます。ここでは、停止時間やダウンライムを最小限に抑えてトラフィックを移行する方法を説明します。

  • 新しいクラスターの設定。このクラスターを ClusterNEW と呼びます。
  • 不要となった古いクラスターの設定。このクラスターを ClusterOLD と呼びます。
クラスターのアップグレードプロセス - 負荷分散グループ
  1. 前提条件に従って、新しいクラスターを設定します。
  2. ClusterNEW および ClusterOLD の両方で、設定オプション sticky-session をデフォルト設定の true に設定してください。このオプションを有効にすると、クラスターのクラスターノードへの新しいリクエストはすべてそのクラスターノードに送信されます。

    /profile=full-ha/subsystem=modcluster/proxy=default:write-attribute(name=sticky-session,value=true)
    Copy to Clipboard Toggle word wrap
  3. ClusterOLD のすべてのクラスターノードは ClusterOLD ロードバランシンググループのメンバーであることを仮定し、load-balancing-groupClusterOLD に設定します。

    /profile=full-ha/subsystem=modcluster/proxy=default:write-attribute(name=load-balancing-group,value=ClusterOLD)
    Copy to Clipboard Toggle word wrap
  4. mod_cluster ワーカーノードの設定 の手順に従って ClusterNEW のノードを個別に mod_cluster 設定に追加します。また、この手順を使用してロードバランシンググループを ClusterNEW に設定します。

    この時点で、以下の簡易例に似た出力が mod_cluster-manager コンソールに表示されます。

                    mod_cluster/<version>
    
        LBGroup ClusterOLD: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
            Node node-1-jvmroute (ajp://node1.oldcluster.example:8009):
                [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
                Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
                Virtual Host 1:
                    Contexts:
                        /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
    
            Node node-2-jvmroute (ajp://node2.oldcluster.example:8009):
                [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
                Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets: Off, ..., Load: 100
                Virtual Host 1:
                    Contexts:
                        /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
    
    
        LBGroup ClusterNEW: [Enable Nodes]   [Disable Nodes]   [Stop Nodes]
            Node node-3-jvmroute (ajp://node3.newcluster.example:8009):
                [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
                Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
                Virtual Host 1:
                    Contexts:
                        /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
    
            Node node-4-jvmroute (ajp://node4.newcluster.example:8009):
                [Enable Contexts]   [Disable Contexts]   [Stop Contexts]
                Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets: Off, ..., Load: 100
                Virtual Host 1:
                    Contexts:
                        /my-deployed-application-context, Status: ENABLED Request: 0 [Disable]   [Stop]
    Copy to Clipboard Toggle word wrap
  5. ClusterOLD グループ内に古いアクティブなセッションがあり、新しいセッションは ClusterOLD または CLusterNEW グループ内に作成されます。次に、現在アクティブなクライアントのセッションにエラーが発生しないようにクラスターノードを停止するため、ClusterOLD グループ全体を無効にします。

    mod_cluster-manager Web コンソールで LBGroup ClusterOLDDisable Nodes リンクをクリックします。

    この後、すでに確立されたセッションに属するリクエストのみが ClusterOLD ロードバランシンググループのメンバーにルーティングされます。新しいクライアントのセッションは ClusterNEW グループのみに作成されます。ClusterOLD グループ内にアクティブなセッションがなくなったら、そのメンバーを安全に削除できます。

    注記

    Stop Nodes を使用すると、即座にこのドメインへのリクエストのルーティングを停止するようロードバランサーが指示されます。これにより、別のロードバランシンググループへのフェイルオーバーが強制され、ClusterNEWClusterOLD の間にセッションレプリケーションがない場合はクライアントへのセッションデータが損失する原因となります。

デフォルトの負荷分散グループ

mod_cluster-manager コンソールの LBGroup を確認して、現在の ClusterOLD 設定にロードバランシンググループの設定が含まれていない場合でも、ClusterOLD ノードの無効化を利用できます。この場合、各 ClusterOLD ノードの Disable Contexts をクリックします。これらのノードのコンテンツは無効化され、アクティブなセッションがなくなったら削除することができます。新しいクライアントのセッションは、有効なコンテンツを持つノードのみに作成されます (この例では ClusterNEW メンバー)。

管理 CLI の使用

mod_cluster-manager web コンソールを使用する他に、JBoss EAP 管理 CLI を使用して特定のコンテキストを停止または無効化することもできます。

コンテキストの停止

/host=primary/server=server-one/subsystem=modcluster:stop-context(context=/my-deployed-application-context, virtualhost=default-host, waittime=0)
Copy to Clipboard Toggle word wrap

waittime0 に設定してタイムアウトがない状態でコンテキストを停止すると、すべてのリクエストのルーティングを即座に停止するようバランサーに指示を出し、利用できる他のコンテキストへのフェイルオーバーを強制します。

waittime 引数を使用してタイムアウト値を設定すると、このコンテキストでは新しいセッションは作成されませんが、既存のセッションが完了するか、指定のタイムアウト値を経過するまで、既存のセッションはこのノードに引き続き転送されます。waittime 引数のデフォルト値は 10 秒です。

コンテキストの無効化

/host=primary/server=server-one/subsystem=modcluster:disable-context(context=/my-deployed-application-context, virtualhost=default-host)
Copy to Clipboard Toggle word wrap

コンテキストを無効にすると、バランサーがこのコンテキストで新しいセッションを作成しないよう指示します。

22.7. Apache mod_jk HTTP コネクター

Apache mod_jk は、互換性の維持を目的に提供される HTTP コネクターです。

JBoss EAP は Apache HTTP プロキシーサーバーからのワークロードを許可します。プロキシーサーバーは Web フロントエンドからのクライアントリクエストを許可し、ワークを参加する JBoss EAP サーバーへ渡します。スティッキーセッションが有効な場合、同じクライアントリクエストは常に同じ JBoss EAP サーバーに送信されます (同じサーバーが使用できない場合を除く)。

mod_jk は AJP 1.3 プロトコルを介して通信します。mod_cluster または mod_proxy には他のプロトコルを使用できます。詳細は HTTP コネクターの概要 を参照してください。

注記

mod_cluster は mod_jk よりも高度なロードバランサーで、推奨される HTTP コネクターです。mod_cluster は mod_jk のすべての機能と、それ以外の追加機能を提供します。JBoss EAP の mod_cluster HTTP コネクターとは違い、Apache mod_jk HTTP コネクターはサーバーまたはサーバーグループのデプロイメントの状態を認識せず、ワークの送信先に順応できません。

詳細は、Apache mod_jk ドキュメント を参照してください。

22.7.1. Apache HTTP Server での mod_jk の設定

JBoss Core Services Apache HTTP Server をインストールする場合や JWS を使用する場合、mod_jk モジュール mod_jk.so はすでに含まれていますが、デフォルトではロードされません。

注記

Apache HTTP Server は、バージョン 3.1.0 以降、JWS には同梱されなくなりました。

以下の手順に従って、Apache HTTP Server の mod_jk をロードおよび設定します。この手順では、Apache HTTP Server の httpd/ ディレクトリーがカレントディレクトリーであることを前提としていますが、このディレクトリーはプラットフォームによって異なります。詳細は、JBoss Core Services Apache HTTP Server インストールガイド の各プラットフォームのインストール手順を参照してください。

注記

Red Hat のお客様は、Red Hat カスタマーポータルにある Load Balancer Configuration Tool を使用して mod_jk やその他のコネクターに最適な設定テンプレートを迅速に生成することもできます。このツールを使用するにはログインする必要があります。

手順

  1. mod_jk モジュールを設定します。

    注記

    mod_jk 設定ファイルの例は conf.d/mod_jk.conf.sample にあります。独自のファイルを作成せずにこのファイルを使用するには、.sample 拡張子を削除し、必要に応じて内容を変更します。

    conf.d/mod_jk.conf という新しいファイルを作成します。以下の設定をファイルに追加し、必要に応じて内容を変更します。

    # Load mod_jk module
    # Specify the filename of the mod_jk lib
    LoadModule jk_module modules/mod_jk.so
    
    # Where to find workers.properties
    JkWorkersFile conf.d/workers.properties
    
    # Where to put jk logs
    JkLogFile logs/mod_jk.log
    
    # Set the jk log level [debug/error/info]
    JkLogLevel info
    
    # Select the log format
    JkLogStampFormat  "[%a %b %d %H:%M:%S %Y]"
    
    # JkOptions indicates to send SSK KEY SIZE
    JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
    
    # JkRequestLogFormat
    JkRequestLogFormat "%w %V %T"
    
    # Mount your applications
    JkMount /application/* loadbalancer
    
    # Add shared memory.
    # This directive is present with 1.2.10 and
    # later versions of mod_jk, and is needed for
    # for load balancing to work properly
    JkShmFile logs/jk.shm
    
    # Add jkstatus for managing runtime data
    <Location /jkstatus/>
        JkMount status
        Require ip 127.0.0.1
    </Location>
    Copy to Clipboard Toggle word wrap
    注記

    JkMount ディレクティブは、Apache HTTP Server が mod_jk モジュールに転送する必要がある URL を指定します。ディレクティブの設定に基づき、mod_jk は受信した URL を適切なワーカーに送信します。直接静的コンテンツに対応し、Java アプリケーションのロードバランサーのみを使用するには、URL パスは /application/* である必要があります。mod_jk をロードバランサーとして使用するには、値 /* を使用してすべての URL を mod_jk に転送します。

    一般的な mod_jk の設定の他に、このファイルは mod_jk.so モジュールをロードするよう指定し、workers.properties ファイルの場所を定義します。

  2. mod_jk ワーカーノードを設定します。

    注記

    ワーカー設定ファイルの例は conf.d/workers.properties.sample にあります。独自のファイルを作成せずにこのファイルを使用するには、.sample 拡張子を削除し、必要に応じて内容を変更します。

    conf.d/workers.properties という新しいファイルを作成します。以下の設定をファイルに追加し、必要に応じて内容を変更します。

    # Define list of workers that will be used
    # for mapping requests
    worker.list=loadbalancer,status
    
    # Define Node1
    # modify the host as your host IP or DNS name.
    worker.node1.port=8009
    worker.node1.host=node1.mydomain.com
    worker.node1.type=ajp13
    worker.node1.ping_mode=A
    worker.node1.lbfactor=1
    
    # Define Node2
    # modify the host as your host IP or DNS name.
    worker.node2.port=8009
    worker.node2.host=node2.mydomain.com
    worker.node2.type=ajp13
    worker.node2.ping_mode=A
    worker.node2.lbfactor=1
    
    # Load-balancing behavior
    worker.loadbalancer.type=lb
    worker.loadbalancer.balance_workers=node1,node2
    worker.loadbalancer.sticky_session=1
    
    # Status worker for managing load balancer
    worker.status.type=status
    Copy to Clipboard Toggle word wrap

    mod_jk workers.properties ファイルの構文の詳細およびその他の高度な設定オプションの詳細は、mod_jk ワーカープロパティー を参照してください。

  3. 任意で JKMountFile ディレクティブを指定します。

    mod-jk.conf の JKMount ディレクティブの他に、mod_jk に転送される複数の URL パターンが含まれるファイルを指定できます。

    1. uriworkermap.properties ファイルを作成します。

      注記

      URI ワーカーマップ設定ファイルの例は conf.d/uriworkermap.properties.sample にあります。独自のファイルを作成せずにこのファイルを使用するには、.sample 拡張子を削除し、必要に応じて内容を変更します。

      conf.d/uriworkermap.properties という新しいファイルを作成します。以下の例のように、一致する各 URL パターンの行を追加します。

      # Simple worker configuration file
      /*=loadbalancer
      Copy to Clipboard Toggle word wrap
    2. uriworkermap.properties ファイルを示すよう、設定を更新します。

      conf.d/mod_jk.conf の最後に以下を追加します。

      # Use external file for mount points.
      # It will be checked for updates each 60 seconds.
      # The format of the file is: /url=worker
      # /examples/*=loadbalancer
      JkMountFile conf.d/uriworkermap.properties
      Copy to Clipboard Toggle word wrap

mod_jk の設定に関する詳細は、JWS HTTP コネクターおよび負荷分散ガイドmod_jk をロードする Apache HTTP Server の設定 セクションを参照してください。

22.7.2. JBoss EAP が mod_jk と通信するよう設定する

mod_jk HTTP コネクターには、Web サーバーによってロードされる単一のコンポーネント mod_jk.so モジュールがあります。このモジュールはクライアント要求を受け取り、コンテナー (この場合は JBoss EAP) に転送します。これらの要求を許可し、返信を Web サーバーに送信するように JBoss EAP を設定する必要もあります。

JBoss EAP の undertow サブシステムは、外部 Web サーバーからのリクエストを許可し、外部 Web サーバーへ返答を返送するために、リスナーを指定する必要があります。mod_jk は AJP プロトコルを使用するため、AJP リスナーを設定する必要があります。

デフォルトの高可用性設定の 1 つ (ha または full-ha) を使用している場合は、AJP リスナーはすでに設定されています。

手順は、外部 Web サーバーからのリクエストの許可 を参照してください。

22.8. Apache mod_proxy HTTP コネクター

Apache mod_proxy は、AJP、HTTP、および HTTPS プロトコルを介して接続をサポートする HTTP コネクターです。mod_proxy は負荷分散された設定と負荷分散されていない設定が可能で、スティッキーセッションをサポートします。

mod_proxy モジュールを使用するには、使用するプロトコルに応じて JBoss EAP の undertow サブシステムに HTTP、HTTPS または AJP リスナーを設定する必要があります。

注記

mod_cluster は mod_proxy よりも高度なロードバランサーで、推奨される HTTP コネクターです。mod_cluster は mod_proxy のすべての機能と、それ以外の追加機能を提供します。JBoss EAP の mod_cluster HTTP コネクターとは違い、Apache mod_proxy HTTP コネクターはサーバーまたはサーバーグループのデプロイメントの状態を認識せず、ワークの送信先に順応できません。

詳細は Apache mod_proxy ドキュメント を参照してください。

22.8.1. Apache HTTP Server での mod_proxy の設定

JBoss Core Services Apache HTTP Server をインストールする場合や JWS を使用する場合、mod_proxy モジュールはすでに含まれており、デフォルトでロードされます。

注記

Apache HTTP Server は、バージョン 3.1.0 以降、JWS には同梱されなくなりました。

基本の ロードバランシング または 非ロードバランシング プロキシーを設定するには、以下のセクションを参照してください。この手順では、Apache HTTP Server の httpd/ ディレクトリーがカレントディレクトリーであることを前提としていますが、このディレクトリーはプラットフォームによって異なります。詳細は、JBoss Core Services Apache HTTP Server インストールガイド の各プラットフォームのインストール手順を参照してください。また、この手順は JBoss EAP の undertow サブシステムに必要な HTTP リスナーが設定されていることを前提としています。

注記

Red Hat のお客様は Red Hat カスタマーポータルにある Load Balancer Configuration Tool を使用して mod_proxy やその他のコネクターに最適な設定テンプレートを迅速に生成することもできます。このツールを使用するにはログインする必要があります。

負荷分散以外のプロキシーの追加

以下の設定を、他の <VirtualHost> ディレクティブの直下にある conf/httpd.conf ファイルに追加します。値を設定に適切な値に置き換えます。

<VirtualHost *:80>
# Your domain name
ServerName YOUR_DOMAIN_NAME

ProxyPreserveHost On

# The IP and port of JBoss
# These represent the default values, if your httpd is on the same host
# as your JBoss managed domain or server

ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/

# The location of the HTML files, and access control information
DocumentRoot /var/www
<Directory /var/www>
Options -Indexes
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
Copy to Clipboard Toggle word wrap
負荷分散プロキシーの追加
注記

デフォルトの Apache HTTP Server は mod_cluster との互換性がないため、mod_proxy_balancer.so モジュールが無効になっています。この作業を行うには、このモジュールをロードし、mod_cluster を無効にする必要があります。

mod_proxy をロードバランサーとして使用し、ワークを複数の JBoss EAP インスタンスに送信するには、以下の設定を conf/httpd.conf ファイルに追加する必要があります。IP アドレスの例は以下のようになります。ご使用の環境に適切な値に置き換えてください。

<Proxy balancer://mycluster>

Order deny,allow
Allow from all

# Add each JBoss Enterprise Application Server by IP address and port.
# If the route values are unique like this, one node will not fail over to the other.
BalancerMember http://192.168.1.1:8080 route=node1
BalancerMember http://192.168.1.2:8180 route=node2
</Proxy>

<VirtualHost *:80>
 # Your domain name
 ServerName YOUR_DOMAIN_NAME

 ProxyPreserveHost On
 ProxyPass / balancer://mycluster/

 # The location of the HTML files, and access control information DocumentRoot /var/www
 <Directory /var/www>
  Options -Indexes
  Order allow,deny
  Allow from all
 </Directory>

</VirtualHost>
Copy to Clipboard Toggle word wrap

上記の例はすべて HTTP プロトコルを使用して通信します。適切な mod_proxy モジュールをロードすれば AJP または HTTPS プロトコルを使用することもできます。詳細は Apache mod_proxy ドキュメント を参照してください。

スティッキーセッションの有効化

スティッキーセッション を使用すると、クライアントリクエストが特定の JBoss EAP ワーカーに送信された場合に、ワーカーが利用不可能にならない限り、後続のリクエストがすべて同じワーカーに送信されます。これは、ほとんどの場合で推奨される動作です。

mod_proxy のスティッキーセッションを有効にするには、stickysession パラメーターを ProxyPass ステートメントに追加します。

ProxyPass / balancer://mycluster stickysession=JSESSIONID
Copy to Clipboard Toggle word wrap

追加のパラメーターを lbmethodnofailover などの ProxyPass ステートメントに指定できます。使用可能なパラメーターの詳細は、Apache mod_proxy ドキュメント を参照してください。

22.8.2. JBoss EAP が mod_proxy と通信するよう設定する

JBoss EAP の undertow サブシステムは、外部 Web サーバーからのリクエストを許可し、外部 Web サーバーへ返答を返送するために、リスナーを指定する必要があります。使用するプロトコルによっては、リスナーを設定する必要があることがあります。

HTTP リスナーは JBoss EAP のデフォルト設定に設定されます。デフォルトの高可用性設定である ha または full-ha のいずれかを使用している場合は、AJP リスナーも事前設定されています。

手順は、外部 Web サーバーからのリクエストの許可 を参照してください。

22.9. Microsoft ISAPI コネクター

Internet Server API (ISAPI) は、Microsoft のインターネット情報サービス (IIS) などの Web サーバー用の Digital Server 拡張やフィルターを書き込むために使用される API のセットです。ISAPI_redirect.dll は IIS 向けに調整された mod_jk の拡張機能です。ISAPI_redirect.dll を使用すると、JBoss EAP インスタンスをワーカーノードとしてロードバランサーとして設定できます。

注記

Windows Server および IIS のサポートされる構成は、JBoss EAP でサポートされる構成 を参照してください。

22.9.1. Microsoft IIS が ISAPI コネクターを使用するよう設定する

Red Hat カスタマーポータルから ISAPI コネクターをダウンロードします。

  1. ブラウザーを開き、Red Hat カスタマーポータルで JBoss の Software Downloads ページにログインします。
  2. Product ドロップダウンメニューから Web Connectors を選択します。
  3. Version ドロップダウンメニューで最新バージョンの JBoss Core Services を選択します。
  4. リストで Red Hat JBoss Core Services ISAPI Connector を見つけ、Download リンクをクリックします。
  5. アーカイブを抽出し、sbin ディレクトリーの内容をサーバーの場所にコピーします。以下の手順は、内容が C:\connectors\ にコピーされたことを前提としています。

IIS マネージャー (IIS 7) を使用して IIS リディレクターを設定するには、以下を行います。

  1. StartRun とクリックして IIS マネージャーを開き、inetmgr と入力します。
  2. 左側のツリービューペインで IIS 7 をデプロイメントします。
  3. ISAPI and CGI Registrations をダブルクリックし、新しいウインドウで開きます。
  4. Actions ペインで Add をクリックします。Add ISAPI or CGI Restriction ウインドウが開きます。
  5. 以下の値を指定します。

    • ISAPI or CGI Path: C:\connectors\isapi_redirect.dll
    • Description: jboss
    • Allow extension path to execute: チェックボックスを選択します。
  6. OK をクリックして Add ISAPI or CGI Restriction ウインドウを閉じます。
  7. JBoss ネイティブ仮想ディレクトリーの定義

    • Default Web Site を右クリックし、Add Virtual Directory をクリックします。Add Virtual Directory ウインドウが開きます。
    • 以下の値を指定して仮想ディレクトリーを追加します。

      • Alias: jboss
      • Physical Path: C:\connectors\
    • OK をクリックして値を保存し、Add Virtual Directory ウインドウを閉じます。
  8. JBoss ネイティブ ISAPI リダイレクトフィルターの定義

    • ツリービューペインで SitesDefault Web Site とデプロイメントします。
    • ISAPI Filters をダブルクリックします。ISAPI Filters Features ビューが表示されます。
    • Actions ペインで Add をクリックします。Add ISAPI Filter ウインドウが表示されます。
    • 以下の値を Add ISAPI Filter ウインドウに指定します。

      • Filter name: jboss
      • Executable: C:\connectors\isapi_redirect.dll
    • OK をクリックして値を保存し、Add ISAPI Filter ウインドウを閉じます。
  9. ISAPI-dll ハンドラーの有効化

    • ツリービューペインの IIS 7 をダブルクリックします。IIS 7 Home Features View が開きます。
    • Handler Mappings をダブルクリックします。Handler Mappings Features View が表示されます。
    • Group by コンボボックスで State を選択します。Handler MappingsEnabled and Disabled Groups に表示されます。
    • ISAPI-dll を見つけます。Disabled グループにある場合は右クリックし、Edit Feature Permissions を選択します。
    • 以下のパーミッションを有効にします。

      • Read
      • Script
      • Execute
    • OK をクリックして値を保存し、Edit Feature Permissions ウインドウを閉じます。

これで、ISAPI コネクターを使用するよう Microsoft IIS が設定されます。

22.9.2. ISAPI コネクターがクライアントリクエストを JBoss EAP に送信するよう設定する

このタスクでは、JBoss EAP サーバーのグループが ISAPI コネクターからのリクエストを受け入れるよう設定します。ロードバランシングまたは高可用性フェイルオーバーの設定は含まれません。

この設定は IIS サーバーで行われ、外部 Web サーバーからのリクエストを許可 するよう JBoss EAP が設定されていることを前提としています。また、IIS への完全な管理者アクセスが必要で、IIS が ISAPI コネクターを使用するよう設定 されている必要があります。

プロパティーファイルの作成およびリダイレクトのセットアップ
  1. ログ、プロパティーファイル、およびロックファイルを格納するディレクトリーを作成します。

    以下の手順では、ディレクトリー C:\connectors\ の使用を前提としています。異なるディレクトリーを使用する場合は、適切に手順を変更してください。

  2. isapi_redirect.properties ファイルを作成します。

    C:\connectors\isapi_redirect.properties という新しいファイルを作成します。このファイルに次の内容をコピーします。

    # Configuration file for the ISAPI Connector
    # Extension uri definition
    extension_uri=/jboss/isapi_redirect.dll
    
    # Full path to the log file for the ISAPI Connector
    log_file=c:\connectors\isapi_redirect.log
    
    # Log level (debug, info, warn, error or trace)
    log_level=info
    
    # Full path to the workers.properties file
    worker_file=c:\connectors\workers.properties
    
    # Full path to the uriworkermap.properties file
    worker_mount_file=c:\connectors\uriworkermap.properties
    
    #Full path to the rewrite.properties file
    rewrite_rule_file=c:\connectors\rewrite.properties
    Copy to Clipboard Toggle word wrap

    rewrite.properties ファイルを使用しない場合は、行の先頭に # 文字を記入して最後の行をコメントアウトします。

  3. uriworkermap.properties ファイルの作成

    uriworkermap.properties ファイルには、デプロイされたアプリケーション URL と、それらへの要求を処理するワーカー間のマッピングが含まれます。以下のサンプルファイルはファイルの構文を示しています。uriworkermap.properties ファイルを C:\connectors\ に格納します。

    # images and css files for path /status are provided by worker01
    /status=worker01
    /images/*=worker01
    /css/*=worker01
    
    # Path /web-console is provided by worker02
    # IIS (customized) error page is used for http errors with number greater or equal to 400
    # css files are provided by worker01
    /web-console/*=worker02;use_server_errors=400
    /web-console/css/*=worker01
    
    # Example of exclusion from mapping, logo.gif won't be displayed
    # !/web-console/images/logo.gif=*
    
    # Requests to /app-01 or /app-01/something will be routed to worker01
    /app-01|/*=worker01
    
    # Requests to /app-02 or /app-02/something will be routed to worker02
    /app-02|/*=worker02
    Copy to Clipboard Toggle word wrap
  4. workers.properties ファイルを作成します。

    workers.properties ファイルには、ワーカーラベルとサーバーインスタンス間のマッピング定義が含まれます。このファイルは、Apache mod_jk ワーカープロパティー 設定で使用される同じファイルの構文を使用します。

    以下は workers.properties ファイルの例になります。ワーカー名、worker01、および worker02 は、JBoss EAP の undertow サブシステムで設定 された instance-id に一致する必要があります。

    このファイルを C:\connectors\ ディレクトリーに格納してください。

    # An entry that lists all the workers defined
    worker.list=worker01, worker02
    
    # Entries that define the host and port associated with these workers
    
    # First JBoss EAP server definition, port 8009 is standard port for AJP in EAP
    worker.worker01.host=127.0.0.1
    worker.worker01.port=8009
    worker.worker01.type=ajp13
    
    # Second JBoss EAP server definition
    worker.worker02.host=127.0.0.100
    worker.worker02.port=8009
    worker.worker02.type=ajp13
    Copy to Clipboard Toggle word wrap
  5. rewrite.properties ファイルを作成します。

    rewrite.properties ファイルには、特定のアプリケーションの単純な URL 書き換えルールが含まれます。以下の例で示されているように、書き換えられたパスは名前と値のペアを使用して指定されます。このファイルを C:\connectors\ ディレクトリーに格納してください。

    #Simple example
    # Images are accessible under abc path
    /app-01/abc/=/app-01/images/
    Copy to Clipboard Toggle word wrap
  6. net stop および net start コマンドを使用して IIS サーバーを再起動します。

    C:\> net stop was /Y
    C:\> net start w3svc
    Copy to Clipboard Toggle word wrap

アプリケーションごとに、設定した特定の JBoss EAP サーバーにクライアントリクエストを送信するよう IIS サーバーが設定されます。

この設定は、指定する JBoss EAP サーバー全体でクライアントリクエストを分散します。この設定は IIS サーバーで行われ、外部 Web サーバーからのリクエストを許可 するよう JBoss EAP が設定されていることを前提としています。また、IIS への完全な管理者アクセスが必要で、IIS が ISAPI コネクターを使用するよう設定 されている必要があります。

複数のサーバー間でのクライアント要求の分散
  1. ログ、プロパティーファイル、およびロックファイルを格納するディレクトリーを作成します。

    以下の手順では、ディレクトリー C:\connectors\ の使用を前提としています。異なるディレクトリーを使用する場合は、適切に手順を変更してください。

  2. isapi_redirect.properties ファイルを作成します。

    C:\connectors\isapi_redirect.properties という新しいファイルを作成します。このファイルに次の内容をコピーします。

    # Configuration file for the ISAPI Connector
    # Extension uri definition
    extension_uri=/jboss/isapi_redirect.dll
    
    # Full path to the log file for the ISAPI Connector
    log_file=c:\connectors\isapi_redirect.log
    
    # Log level (debug, info, warn, error or trace)
    log_level=info
    
    # Full path to the workers.properties file
    worker_file=c:\connectors\workers.properties
    
    # Full path to the uriworkermap.properties file
    worker_mount_file=c:\connectors\uriworkermap.properties
    
    #OPTIONAL: Full path to the rewrite.properties file
    rewrite_rule_file=c:\connectors\rewrite.properties
    Copy to Clipboard Toggle word wrap

    rewrite.properties ファイルを使用しない場合は、行の先頭に # 文字を記入して最後の行をコメントアウトします。

  3. uriworkermap.properties ファイルを作成します。

    uriworkermap.properties ファイルには、デプロイされたアプリケーション URL と、それらへの要求を処理するワーカー間のマッピングが含まれます。以下のサンプルファイルは負荷分散が設定されたファイルの構文を示しています。ワイルドカード (*) はさまざまな URL サブディレクトリーのすべてのリクエストを router という名前のロードバランサーに送信します。ロードバランサーの設定は次のステップで説明します。

    uriworkermap.properties ファイルを C:\connectors\ に格納します。

    # images, css files, path /status and /web-console will be
    # provided by nodes defined in the load-balancer called "router"
    /css/*=router
    /images/*=router
    /status=router
    /web-console|/*=router
    
    # Example of exclusion from mapping, logo.gif won't be displayed
    # !/web-console/images/logo.gif=*
    
    # Requests to /app-01 and /app-02 will be routed to nodes defined
    # in the load-balancer called "router"
    /app-01|/*=router
    /app-02|/*=router
    
    # mapping for management console, nodes in cluster can be enabled or disabled here
    /jkmanager|/*=status
    Copy to Clipboard Toggle word wrap
  4. workers.properties ファイルを作成します。

    workers.properties ファイルには、ワーカーラベルとサーバーインスタンス間のマッピング定義が含まれます。このファイルは、Apache mod_jk ワーカープロパティー 設定で使用される同じファイルの構文を使用します。

    以下は workers.properties ファイルの例になります。ロードバランサーはファイルの末尾付近に設定され、ワーカー worker01 および worker02 で構成されます。これらのワーカーは、JBoss EAP の undertow サブシステム で設定された instance-id に一致する必要があります。

    このファイルを C:\connectors\ ディレクトリーに格納してください。

    # The advanced router LB worker
    worker.list=router,status
    
    # First EAP server definition, port 8009 is standard port for AJP in EAP
    #
    # lbfactor defines how much the worker will be used.
    # The higher the number, the more requests are served
    # lbfactor is useful when one machine is more powerful
    # ping_mode=A – all possible probes will be used to determine that
    # connections are still working
    
    worker.worker01.port=8009
    worker.worker01.host=127.0.0.1
    worker.worker01.type=ajp13
    worker.worker01.ping_mode=A
    worker.worker01.socket_timeout=10
    worker.worker01.lbfactor=3
    
    # Second EAP server definition
    worker.worker02.port=8009
    worker.worker02.host=127.0.0.100
    worker.worker02.type=ajp13
    worker.worker02.ping_mode=A
    worker.worker02.socket_timeout=10
    worker.worker02.lbfactor=1
    
    # Define the LB worker
    worker.router.type=lb
    worker.router.balance_workers=worker01,worker02
    
    # Define the status worker for jkmanager
    worker.status.type=status
    Copy to Clipboard Toggle word wrap

  5. rewrite.properties ファイルを作成します。

    rewrite.properties ファイルには、特定のアプリケーションの単純な URL 書き換えルールが含まれます。以下の例で示されているように、書き換えられたパスは名前と値のペアを使用して指定されます。このファイルを C:\connectors\ ディレクトリーに格納してください。

    #Simple example
    # Images are accessible under abc path
    /app-01/abc/=/app-01/images/
    Restart the IIS server.
    
    Restart your IIS server by using the net stop and net start commands.
    C:\> net stop was /Y
    C:\> net start w3svc
    Copy to Clipboard Toggle word wrap

IIS サーバーは、workers.properties ファイルで参照された JBoss EAP サーバーにクライアントリクエストを送信し、サーバー間で負荷を 1:3 の比率で分散するよう設定されます。この比率は、各サーバーに割り当てられた負荷分散係数 lbfactor から派生します。

22.10. Oracle NSAPI コネクター

Netscape Server API (NSAPI) は、拡張機能をサーバーに実装するために Oracle iPlanet Web Server (旧名 Netscape Web Server) によって提供される API です。これらの拡張機能はサーバープラグインと呼ばれます。NSAPI コネクターは、Oracle iPlanet Web Server 向けに調整された mod_jk の拡張機能である nsapi_redirector.so で使用されます。NSAPI コネクターを使用すると、JBoss EAP インスタンスをワーカーノード、Oracle iPlanet Web Server をロードバランサーとして設定できます。

注記

Oracle iPlanet Web Server のサポートされる構成は、JBoss EAP のサポートされる構成 を参照してください。

22.10.1. Oracle iPlanet Web Server が NSAPI コネクターを使用するよう設定する

前提条件

  • ワーカーとして動作する各サーバーに JBoss EAP がインストールおよび設定されます。

Red Hat カスタマーポータルから NSAPI コネクターをダウンロードします。

  1. ブラウザーを開き、Red Hat カスタマーポータルで JBoss の Software Downloads ページにログインします。
  2. Product ドロップダウンメニューから Web Connectors を選択します。
  3. Version ドロップダウンメニューで最新バージョンの JBoss Core Services を選択します。
  4. システムのプラットフォームとアーキテクチャーに対応する Red Hat JBoss Core Services NSAPI Connector を見つけ、Download リンクをクリックします。
  5. lib/ または lib64/ ディレクトリーにある nsapi_redirector.so ファイルを、IPLANET_CONFIG/lib/ または IPLANET_CONFIG/lib64/ ディレクトリーに展開します。

NSAPI コネクターを設定します。

注記

これらの手順では、IPLANET_CONFIG は Oracle iPlanet の設定ディレクトリーを意味します (通常 /opt/oracle/webserver7/config/ になります)。Oracle iPlanet 設定ディレクトリーが異なる場合は、適切に手順を変更してください。

  1. サーブレットマッピングを無効にします。

    IPLANET_CONFIG/default.web.xml ファイルを開き、Built In Server Mappings という見出しのセクションを見つけます。次の 3 つのサーブレットを XML コメント文字 (<!-- および -->) で囲み、これらのサーブレットへのマッピングを無効にします。

    • default
    • invoker
    • jsp

      以下の設定例は、無効にされたマッピングを示しています。

      <!-- ============== Built In Servlet Mappings =============== -->
      <!-- The servlet mappings for the built in servlets defined above. -->
      <!-- The mapping for the default servlet -->
      <!--servlet-mapping>
       <servlet-name>default</servlet-name>
       <url-pattern>/</url-pattern>
      </servlet-mapping-->
      <!-- The mapping for the invoker servlet -->
      <!--servlet-mapping>
       <servlet-name>invoker</servlet-name>
       <url-pattern>/servlet/*</url-pattern>
      </servlet-mapping-->
      <!-- The mapping for the Jakarta Server Pages servlet -->
      <!--servlet-mapping>
       <servlet-name>jsp</servlet-name>
       <url-pattern>*.jsp</url-pattern>
      </servlet-mapping-->
      Copy to Clipboard Toggle word wrap

      ファイルを保存し、終了します。

  2. iPlanet Web Server が NSAPI コネクターモジュールをロードするよう設定します。

    IPLANET_CONFIG/magnus.conf ファイルの最後に次の行を追加し、設定に合わせてファイルパスを変更します。これらの行は、nsapi_redirector.so モジュールと、ワーカーおよびそのプロパティーがリストされた workers.properties ファイルの場所を定義します。

    Init fn="load-modules" funcs="jk_init,jk_service" shlib="/lib/nsapi_redirector.so" shlib_flags="(global|now)"
    
    Init fn="jk_init" worker_file="IPLANET_CONFIG/connectors/workers.properties" log_level="info" log_file="IPLANET_CONFIG/connectors/nsapi.log" shm_file="IPLANET_CONFIG/connectors/tmp/jk_shm"
    Copy to Clipboard Toggle word wrap

    上記の設定は 32 ビットアーキテクチャー向けです。

    ファイルを保存し、終了します。

  3. NSAPI コネクターを設定します。

    負荷分散のない基本設定または負荷分散設定向けに NSAPI コネクターを設定できます。以下のいずれかのオプションを選択します。その後、設定が完了します。

22.10.2. NSAPI コネクターがクライアントリクエストを JBoss EAP に送信するよう設定する

このタスクでは、NSAPI コネクターが負荷分散またはフェイルオーバーなしでクライアントリクエストを JBoss EAP サーバーにリダイレクトするよう設定します。リダイレクトは、デプロイメントごとに (つまり、URL ごとに) 行われます。

重要

このタスクを続行するには、NSAPI コネクターが設定 されている必要があります。

基本的な HTTP コネクターの設定
  1. JBoss EAP サーバーにリダイレクトする URL パスを定義します。

    注記

    IPLANET_CONFIG/obj.conf では、前の行から継続する行以外は、行の最初にスペースを挿入しないでください。

    IPLANET_CONFIG/obj.conf ファイルを編集します。<Object name="default"> で始まるセクションを見つけ、一致する各 URL パターンを次のサンプルファイルで示された形式で追加します。文字列 jknsapi は、次の手順で定義される HTTP コネクターを示します。例は、ワイルドカードを使用したパターン一致を示しています。

    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    </Object>
    Copy to Clipboard Toggle word wrap
  2. 各パスを提供するワーカーを定義します。

    IPLANET_CONFIG/obj.conf ファイルの編集を続行します。編集したセクションの終了タグのすぐ後に、</Object> を追加します。

    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="worker01" path="/status"
    Service fn="jk_service" worker="worker02" path="/nc(/*)"
    Service fn="jk_service" worker="worker01"
    </Object>
    Copy to Clipboard Toggle word wrap

    上記の例は、URL パス /status へのリクエストを worker01 という名前のワーカーにリダイレクトし、/nc/ 以下のすべての URL パスを worker02 という名前のワーカーにリダイレクトします。3 番目の行は、前の行で一致しない jknsapi オブジェクトに割り当てられたすべての URL が worker01 に提供されることを示しています。

    ファイルを保存し、終了します。

  3. ワーカーとその属性を定義します。

    IPLANET_CONFIG/connectors/ ディレクトリーに workers.properties というファイルを作成します。以下の内容をそのファイルに貼り付けし、お使いの環境に合わせて変更します。

    # An entry that lists all the workers defined
    worker.list=worker01, worker02
    
    # Entries that define the host and port associated with these workers
    worker.worker01.host=127.0.0.1
    worker.worker01.port=8009
    worker.worker01.type=ajp13
    
    worker.worker02.host=127.0.0.100
    worker.worker02.port=8009
    worker.worker02.type=ajp13
    Copy to Clipboard Toggle word wrap

    workers.properties ファイルは Apache mod_jk と同じ構文を使用します。

    ファイルを保存し、終了します。

  4. iPlanet Web Server の再起動

    以下のコマンドを実行し、iPlanet Web Server を再起動します。

    IPLANET_CONFIG/../bin/stopserv
    IPLANET_CONFIG/../bin/startserv
    Copy to Clipboard Toggle word wrap

iPlanet Web Server が、JBoss EAP のデプロイメントに設定した URL へクライアントリクエストを送信します。

このタスクは、負荷分散の設定でクライアントリクエストを JBoss EAP サーバーに送信するよう NSAPI コネクターを設定します。

重要

このタスクを続行するには、NSAPI コネクターが設定 されている必要があります。

ロードバランシングのコネクターの設定
  1. JBoss EAP サーバーにリダイレクトする URL パスを定義します。

    注記

    IPLANET_CONFIG/obj.conf では、前の行から継続する行以外は、行の最初にスペースを挿入しないでください。

    IPLANET_CONFIG/obj.conf ファイルを編集します。<Object name="default"> で始まるセクションを見つけ、一致する各 URL パターンを次のサンプルファイルで示された形式で追加します。文字列 jknsapi は、次の手順で定義される HTTP コネクターを示します。例は、ワイルドカードを使用したパターン一致を示しています。

    <Object name="default">
    [...]
    NameTrans fn="assign-name" from="/status" name="jknsapi"
    NameTrans fn="assign-name" from="/images(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/css(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/nc(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jmx-console(|/*)" name="jknsapi"
    NameTrans fn="assign-name" from="/jkmanager/*" name="jknsapi"
    </Object>
    Copy to Clipboard Toggle word wrap
  2. 各パスを提供するワーカーを定義します。

    IPLANET_CONFIG/obj.conf ファイルの編集を続行します。前の手順で変更したセクションの終了タグ (</Object>) のすぐ後に、以下の新しいセクションを追加し、必要に応じて変更します。

    <Object name="jknsapi">
    ObjectType fn=force-type type=text/plain
    Service fn="jk_service" worker="status" path="/jkmanager(/*)"
    Service fn="jk_service" worker="router"
    </Object>
    Copy to Clipboard Toggle word wrap

    この jksnapi オブジェクトは、default オブジェクトの name="jksnapi" マッピングにマップされた各パスを提供するために使用されるワーカーノードを定義します。/jkmanager/* に一致する URL 以外のすべてが、router という名前のワーカーにリダイレクトされます。

  3. ワーカーとその属性を定義します。

    workers.properties という名前のファイルを IPLANET_CONFIG/connector/ で作成します。以下の内容をそのファイルに貼り付けし、お使いの環境に合わせて変更します。

    # The advanced router LB worker
    # A list of each worker
    worker.list=router,status
    
    # First JBoss EAP server
    # (worker node) definition.
    # Port 8009 is the standard port for AJP
    #
    
    worker.worker01.port=8009
    worker.worker01.host=127.0.0.1
    worker.worker01.type=ajp13
    worker.worker01.ping_mode=A
    worker.worker01.socket_timeout=10
    worker.worker01.lbfactor=3
    
    # Second JBoss EAP server
    worker.worker02.port=8009
    worker.worker02.host=127.0.0.100
    worker.worker02.type=ajp13
    worker.worker02.ping_mode=A
    worker.worker02.socket_timeout=10
    worker.worker02.lbfactor=1
    
    # Define the load-balancer called "router"
    worker.router.type=lb
    worker.router.balance_workers=worker01,worker02
    
    # Define the status worker
    worker.status.type=status
    Copy to Clipboard Toggle word wrap

    workers.properties ファイルは Apache mod_jk と同じ構文を使用します。

    ファイルを保存し、終了します。

  4. iPlanet Web Server 7.0 を再起動します。

    IPLANET_CONFIG/../bin/stopserv
    IPLANET_CONFIG/../bin/startserv
    Copy to Clipboard Toggle word wrap