AMQ Broker の設定
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、今後の複数のリリースで段階的に用語の置き換えを実施してまいります。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。
第1章 概要
AMQ Broker 設定ファイルは、ブローカーインスタンスの重要な設定を定義します。ブローカーの設定ファイルを編集することにより、ブローカーが環境で動作する方法を制御できます。
1.1. AMQ Broker の設定ファイルおよび場所
ブローカーの設定ファイルはすべて <broker_instance_dir>/etc
に保存されます。これらの設定ファイルで設定を編集すると、ブローカーを設定できます。
各ブローカーインスタンスは以下の設定ファイルを使用します。
broker.xml
- 主要設定ファイル。このファイルを使用して、ネットワーク接続、セキュリティー設定、メッセージアドレスなどのブローカーのほとんどの側面を設定します。
bootstrap.xml
-
AMQ Broker がブローカーインスタンスを起動するために使用するファイル。これは、
broker.xml
の場所を変更し、Web サーバーを設定し、セキュリティー設定を行います。 logging.properties
- このファイルを使用して、ブローカーインスタンスのログプロパティーを設定します。
artemis.profile
- このファイルを使用して、ブローカーインスタンスの実行中に使用される環境変数を設定します。
login.config
,artemis-users.properties
,artemis-roles.properties
- セキュリティー関連ファイル。これらのファイルを使用して、ブローカーインスタンスへのユーザーアクセスの認証を設定します。
1.2. デフォルトブローカー設定について
broker.xml
設定ファイルを編集して、ブローカーの機能の大半を設定します。このファイルにはデフォルト設定が含まれています。これはブローカーを起動し、操作するには十分です。ただし、デフォルト設定の一部を変更し、お使いの環境にブローカーを設定するために新しい設定を追加する必要があります。
デフォルトでは、broker.xml
には、以下の機能のデフォルト設定が含まれます。
- メッセージの永続性
- アクセプター
- セキュリティー
- メッセージアドレス
デフォルトのメッセージ永続性設定
デフォルトでは、AMQ Broker の永続性は、ディスク上のファイルセットで設定される追加のみのファイルジャーナルを使用します。ジャーナルは、メッセージ、トランザクション、およびその他の情報を保存します。
<configuration ...> <core ...> ... <persistence-enabled>true</persistence-enabled> <!-- this could be ASYNCIO, MAPPED, NIO ASYNCIO: Linux Libaio MAPPED: mmap files NIO: Plain Java Files --> <journal-type>ASYNCIO</journal-type> <paging-directory>data/paging</paging-directory> <bindings-directory>data/bindings</bindings-directory> <journal-directory>data/journal</journal-directory> <large-messages-directory>data/large-messages</large-messages-directory> <journal-datasync>true</journal-datasync> <journal-min-files>2</journal-min-files> <journal-pool-files>10</journal-pool-files> <journal-file-size>10M</journal-file-size> <!-- This value was determined through a calculation. Your system could perform 8.62 writes per millisecond on the current journal configuration. That translates as a sync write every 115999 nanoseconds. Note: If you specify 0 the system will perform writes directly to the disk. We recommend this to be 0 if you are using journalType=MAPPED and journal-datasync=false. --> <journal-buffer-timeout>115999</journal-buffer-timeout> <!-- When using ASYNCIO, this will determine the writing queue depth for libaio. --> <journal-max-io>4096</journal-max-io> <!-- how often we are looking for how many bytes are being used on the disk in ms --> <disk-scan-period>5000</disk-scan-period> <!-- once the disk hits this limit the system will block, or close the connection in certain protocols that won't support flow control. --> <max-disk-usage>90</max-disk-usage> <!-- should the broker detect dead locks and other issues --> <critical-analyzer>true</critical-analyzer> <critical-analyzer-timeout>120000</critical-analyzer-timeout> <critical-analyzer-check-period>60000</critical-analyzer-check-period> <critical-analyzer-policy>HALT</critical-analyzer-policy> ... </core> </configuration>
デフォルトのアクセプター設定
ブローカーは、acceptor
設定要素を使用して受信クライアント接続をリッスンし、クライアントが接続を作成するためにポートおよびプロトコルを定義します。デフォルトでは、AMQ Broker には以下のように、サポートされる各メッセージングプロトコルのアクセプターが含まれます。
<configuration ...> <core ...> ... <acceptors> <!-- Acceptor for every supported protocol --> <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- AMQP Acceptor. Listens on default AMQP port for AMQP traffic --> <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- STOMP Acceptor --> <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> <!-- HornetQ Compatibility Acceptor. Enables HornetQ Core and STOMP for legacy HornetQ clients. --> <acceptor name="hornetq">tcp://0.0.0.0:5445?anycastPrefix=jms.queue.;multicastPrefix=jms.topic.;protocols=HORNETQ,STOMP;useEpoll=true</acceptor> <!-- MQTT Acceptor --> <acceptor name="mqtt">tcp://0.0.0.0:1883?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=MQTT;useEpoll=true</acceptor> </acceptors> ... </core> </configuration>
デフォルトのセキュリティー設定
AMQ Broker には、アドレスに基づいてキューにセキュリティーを適用するための柔軟なロールベースのセキュリティーモデルが含まれています。デフォルト設定ではワイルドカードを使用して amq
ロールをすべてのアドレスに適用します (数値記号 #
で表されます)。
<configuration ...> <core ...> ... <security-settings> <security-setting match="#"> <permission type="createNonDurableQueue" roles="amq"/> <permission type="deleteNonDurableQueue" roles="amq"/> <permission type="createDurableQueue" roles="amq"/> <permission type="deleteDurableQueue" roles="amq"/> <permission type="createAddress" roles="amq"/> <permission type="deleteAddress" roles="amq"/> <permission type="consume" roles="amq"/> <permission type="browse" roles="amq"/> <permission type="send" roles="amq"/> <!-- we need this otherwise ./artemis data imp wouldn't work --> <permission type="manage" roles="amq"/> </security-setting> </security-settings> ... </core> </configuration>
デフォルトのメッセージアドレス設定
AMQ Broker には、作成されたキューまたはトピックに適用されるデフォルトの設定セットを確立するデフォルトアドレスが含まれています。
さらに、デフォルト設定では、DLQ
(Dead Letter Queue) の 2 つのキューが、既知の宛先で到達するメッセージを処理します。また、Expiry Queue
は有効期限を過ぎたメッセージを保持しているため、元の宛先にルーティングしないでください。
<configuration ...> <core ...> ... <address-settings> ... <!--default for catch all--> <address-setting match="#"> <dead-letter-address>DLQ</dead-letter-address> <expiry-address>ExpiryQueue</expiry-address> <redelivery-delay>0</redelivery-delay> <!-- with -1 only the global-max-size is in use for limiting --> <max-size-bytes>-1</max-size-bytes> <message-counter-history-day-limit>10</message-counter-history-day-limit> <address-full-policy>PAGE</address-full-policy> <auto-create-queues>true</auto-create-queues> <auto-create-addresses>true</auto-create-addresses> <auto-create-jms-queues>true</auto-create-jms-queues> <auto-create-jms-topics>true</auto-create-jms-topics> </address-setting> </address-settings> <addresses> <address name="DLQ"> <anycast> <queue name="DLQ" /> </anycast> </address> <address name="ExpiryQueue"> <anycast> <queue name="ExpiryQueue" /> </anycast> </address> </addresses> </core> </configuration>
1.3. 設定の更新のリロード
デフォルトでは、ブローカーは 5000 ミリ秒ごとに設定ファイルの変更をチェックします。ブローカーが設定ファイルの最後の変更されたタイムスタンプの変更を検出する場合、ブローカーは設定変更の実行を決定します。この場合、ブローカーは設定ファイルを再読み込みして変更を有効にします。
ブローカーが broker.xml
設定ファイルを再読み込みすると、以下のモジュールを再読み込みします。
アドレス設定およびキュー
設定ファイルを再読み込みすると、アドレス設定が、設定ファイルから削除されたアドレスおよびキューを処理する方法を決定します。これは、
config-delete-addresses
およびconfig-delete-queues
プロパティーで設定でき ます。詳細は、付録B アドレス設定要素 を参照してください。セキュリティー設定
既存のアクセプターの SSL/TLS キーストアおよびトラストストアをリロードすると、既存のクライアントに影響を与えずに新しい証明書を確立できます。接続されているクライアントは、古い証明書または異なる証明書を持つクライアントであっても、メッセージの送受信を継続できます。
crlPath
パラメーターを使用して設定された証明書失効リストファイルもリロードできます。
Diverts
設定の再読み込みにより、追加した 新しい 迂回をデプロイします。ただし、設定から迂回を削除したり、
<divert>
要素内のサブ要素に変更しても、ブローカーを再起動するまで反映されません。
以下の手順では、ブローカーが broker.xml
設定ファイルへの変更をチェックする間隔を変更する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <core>
要素内に<configuration-file-refresh-period> 要素を追加
し、更新期間 (ミリ秒単位) を設定します。以下の例では、設定の更新の期間を 60000 ミリ秒に設定します。
<configuration> <core> ... <configuration-file-refresh-period>60000</configuration-file-refresh-period> ... </core> </configuration>
設定ファイルへの何らかの理由でアクセスできない場合は、管理 API またはコンソールを使用して設定ファイルのリロードを強制することもできます。設定ファイルは、ActiveMQServerControl
で管理操作 reloadConfigurationFile()
を使用してリロードできます (ObjectName
org. apache.activemq.artemis:broker="BROKER_NAME"
またはリソース ネーム server
を使用)。
関連情報
- 管理 API の使用方法については、AMQ Broker の管理の 管理 API の使用 を参照してください。
1.4. ブローカー設定ファイルのモジュラー
共通の設定を共有する複数のブローカーがある場合は、個別のファイルに共通設定を定義し、各ブローカーの broker.xml
設定ファイルにこれらのファイルを含めることができます。
ブローカー間で共有できる最も一般的な設定には、以下が含まれます。
- アドレス
- アドレス設定
- セキュリティー設定
手順
共有する
broker.xml
セクションごとに個別の XML ファイルを作成します。各 XML ファイルには、
broker.xml
の単一のセクションのみを含めることができます (例: アドレス設定またはアドレス設定のどちらかですが、両方ではありません)。top-level 要素は、要素 namespace (xmlns="urn:activemq:core"
) も定義する必要があります。以下の例は、
my-security-settings.xml
で定義されたセキュリティー設定を示しています。my-security-settings.xml
<security-settings xmlns="urn:activemq:core"> <security-setting match="a1"> <permission type="createNonDurableQueue" roles="a1.1"/> </security-setting> <security-setting match="a2"> <permission type="deleteNonDurableQueue" roles="a2.1"/> </security-setting> </security-settings>
-
共通の設定を使用する各ブローカーの
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 開かれた
broker.xml
ファイルごとに、以下を行います。broker.xml
の最初の<configuration>
要素で、以下の行が表示されることを確認します。xmlns:xi="http://www.w3.org/2001/XInclude"
共有設定が含まれる各 XML ファイルに対して XML 包含を追加します。
この例には
my-security-settings.xml
ファイルが含まれます。broker.xml
<configuration ...> <core ...> ... <xi:include href="/opt/my-broker-config/my-security-settings.xml"/> ... </core> </configuration>
必要に応じて、
broker.xml
を検証し、XML がスキーマに対して有効であることを確認します。任意の XML バリデータープログラムを使用できます。この例では、
xmllint
を使用して、artemis-server.xsl
スキーマに対してbroker.xml
を検証します。$ xmllint --noout --xinclude --schema /opt/redhat/amq-broker/amq-broker-7.2.0/schema/artemis-server.xsd /var/opt/amq-broker/mybroker/etc/broker.xml /var/opt/amq-broker/mybroker/etc/broker.xml validates
関連情報
- XML 包含 (XIncludes) の詳細は、https://www.w3.org/TR/xinclude/ を参照してください。
1.4.1. モジュール設定ファイルのリロード
ブローカーが設定変更を定期的にチェックすると (configuration-file-refresh-period
で指定される頻度)、xi:include
を使用して broker.xml
設定ファイルに含まれる設定ファイルへの変更を自動的に検出しません。たとえば、broker.xml
に my-address-settings.xml
が含まれ、my-address-settings.xml
に加えられると、ブローカーは my-address-settings.xml
の変更を自動的に検出せず、設定を再読み込みしません。
broker.xml
設定ファイルのリロードと、それに含まれる変更された設定ファイルを 強制するには、broker.xml
設定ファイルの last modified タイムスタンプが変更されたことを確認する必要があります。標準の Linux touch
コマンドを使用して、他の変更を加えずに broker.xml
の最終変更のタイムスタンプを更新できます。以下に例を示します。
$ touch -m <broker_instance_dir>/etc/broker.xml
または、管理 API を使用して Broker のリロードを強制的に実行することもできます。設定ファイルは、ActiveMQServerControl
で管理操作 reloadConfigurationFile()
を使用してリロードできます (ObjectName
org. apache.activemq.artemis:broker="BROKER_NAME"
またはリソース ネーム server
を使用)。
関連情報
- 管理 API の使用方法については、AMQ Broker の管理の 管理 API の使用 を参照してください。
1.4.2. 外部 XML エンティティー (XXE) 処理の無効化
broker.xml
ファイルに含まれる別個のファイルでブローカー設定をモジュール化しない場合は、XXE 処理を無効にして AMQ Broker を XXE セキュリティー脆弱性から保護できます。モジュラーブローカー設定がない場合、Red Hat は XXE 処理を無効にすることを推奨します。
手順
-
<broker_instance_dir>/etc/artemis.profile
ファイルを開きます。 新しい引数
-Dartemis.disableXxe
を Java システム引数のJAVA_ARGS
リストに追加します。-Dartemis.disableXxe=true
-
artemis.profile
ファイルを保存します。
1.5. このドキュメントの表記慣例
このドキュメントでは、sudo
コマンド、ファイルパス、および置き換え可能な値について、以下の規則を使用します。
sudo
コマンド
このドキュメントでは、root 権限を必要とするすべてのコマンドに対して sudo
が使用されています。何らかの変更がシステム全体に影響を与える可能性があるため、sudo
を使用する場合は、常に注意が必要です。
sudo
の使用の詳細は、sudo アクセスの管理 を参照してください。
このドキュメントにおけるファイルパスの使用
このドキュメントでは、すべてのファイルパスは Linux、UNIX、および同様のオペレーティングシステムで有効です (例: /home/...
)。Microsoft Windows を使用している場合は、同等の Microsoft Windows パスを使用する必要があります (例: C:\Users\...
)。
交換可能な値
このドキュメントでは、お客様の環境に合わせた値に置き換える必要のある置換可能な値を使用している場合があります。置き換え可能な値は小文字で、角括弧 (< >
) で囲まれ、イタリックおよび monospace
フォントを使用してスタイルされます。単語が複数になる場合は、アンダースコア (_
) で区切ります。
たとえば、<install_dir>
を独自のディレクトリー名に置き換えます。
$ <install_dir>/bin/artemis create mybroker
第2章 ネットワーク接続でのアクセプターおよびコネクターの設定
AMQ Broker で使用される接続には、ネットワーク接続とin-VM接続の 2 種類があります。ネットワーク接続は、同じサーバーまたは物理的にリモート上に関係なく、2 つの当事者が異なる仮想マシンにある場合に使用されます。in-VM 接続は、クライアント (アプリケーションかサーバーかに関係なく) がブローカーと同じ仮想マシンにある場合に使用されます。
ネットワーク接続は Netty を使用します。Netty は、複数の方法でネットワーク接続を設定できるようにする、高パフォーマンスの低レベルネットワークライブラリーです。Java IO または NIO、TCP ソケット、SSL/TLS、または HTTP または HTTPS でのトンネリングの使用。Netty は、すべてのメッセージングプロトコルに単一のポートを使用することもできます。ブローカーは、使用されているプロトコルを自動的に検出し、さらに処理するために受信メッセージを適切なハンドラーに送ります。
ネットワーク接続の URI で、そのタイプを決定します。たとえば、URI で vm
を指定すると、イン VM 接続が作成されます。
<acceptor name="in-vm-example">vm://0</acceptor>
また、URI に tcp
を指定すると、ネットワーク接続が行われます。以下に例を示します。
<acceptor name="network-example">tcp://localhost:61617</acceptor>
以降のセクションでは、ネットワーク接続と VM の接続に必要な 2 つの設定要素 (acceptorsおよびconnectors) を説明します。ここでは、TCP、HTTP、および SSL/TLS ネットワーク接続のアクセプターおよびコネクター、および VM 接続の設定方法を説明します。
2.1. アクセプターについて
アクセプター はブローカーへの接続方法を定義します。各アクセプターは、クライアントが接続を確立するために使用できるポートおよびプロトコルを定義します。簡単なアクセプター設定を以下に示します。
<acceptors> <acceptor name="example-acceptor">tcp://localhost:61617</acceptor> </acceptors>
ブローカー設定で定義する各 acceptor
要素は単一の acceptors
要素に含まれます。ブローカーに定義できるアクセプターの数の上限はありません。デフォルトでは、AMQ Broker には以下のように、サポートされる各メッセージングプロトコルのアクセプターが含まれます。
<configuration ...> <core ...> ... <acceptors> ... <!-- Acceptor for every supported protocol --> <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- AMQP Acceptor. Listens on default AMQP port for AMQP traffic --> <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- STOMP Acceptor --> <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> <!-- HornetQ Compatibility Acceptor. Enables HornetQ Core and STOMP for legacy HornetQ clients. --> <acceptor name="hornetq">tcp://0.0.0.0:5445?anycastPrefix=jms.queue.;multicastPrefix=jms.topic.;protocols=HORNETQ,STOMP;useEpoll=true</acceptor> <!-- MQTT Acceptor --> <acceptor name="mqtt">tcp://0.0.0.0:1883?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=MQTT;useEpoll=true</acceptor> </acceptors> ... </core> </configuration>
2.2. アクセプターの設定
以下の例は、アクセプターを設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 acceptors
要素に、新しいacceptor
要素を追加します。ブローカーのプロトコルおよびポートを指定します。以下に例を示します。<acceptors> <acceptor name="example-acceptor">tcp://localhost:61617</acceptor> </acceptors>
上記の例では、TCP プロトコルのアクセプターを定義します。ブローカーは TCP を使用するクライアント接続用にポート 61617 でリッスンします。
アクセプターに定義された URI にキーと値のペアを追加します。セミコロン (
;
) を使用して複数のキーと値のペアを区切ります。以下に例を示します。<acceptor name="example-acceptor">tcp://localhost:61617?sslEnabled=true;key-store-path=</path/to/key_store></acceptor>
この設定は、TLS/SSL を使用し、必要なキーストアへのパスを定義するアクセプターを定義するようになりました。
関連情報
- アクセプターおよびコネクターで使用できる設定オプションの詳細は、付録A アクセプターおよびコネクター設定パラメーター を参照してください。
2.3. コネクターについて
アクセプターはブローカーが接続を受け入れる 方法を定義しますが、コネクターはクライアントによってブローカーへの接続方法を定義します。
ブローカー自体がクライアントとして動作する場合、コネクターはブローカーに設定されます。以下に例を示します。
- ブローカーが別のブローカーにブリッジされている場合
- ブローカーがクラスターの一部である場合
以下は、簡単なコネクター設定になります。
<connectors> <connector name="example-connector">tcp://localhost:61617</connector> </connectors>
2.4. コネクターの設定
以下の例は、コネクターの設定方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 connectors
要素に、新しいconnector
要素を追加します。ブローカーのプロトコルおよびポートを指定します。以下に例を示します。<connectors> <connector name="example-connector">tcp://localhost:61617</connector> </connectors>
上記の例では、TCP プロトコルのコネクターを定義します。クライアントはコネクター設定を使用して、TCP プロトコルを使用してポート 61617 のブローカーに接続できます。ブローカー自体は、送信接続にこのコネクターを使用することもできます。
コネクターに定義された URI にキーと値のペアを追加します。セミコロン (
;
) を使用して複数のキーと値のペアを区切ります。以下に例を示します。<connector name="example-connector">tcp://localhost:61616?tcpNoDelay=true</connector>
この設定は、
tcpNoDelay
プロパティーの値をtrue
に設定するコネクターを定義するようになりました。このプロパティーの値をtrue
に設定すると、接続の Nagle アルゴリズムがオフになります。Nagle のアルゴリズムは、小さなデータパケットの送信を遅延させ、それを大きなパケットに統合することで、TCP 接続の効率を向上させるために使用するアルゴリズムです。
関連情報
- アクセプターおよびコネクターで使用できる設定オプションの詳細は、付録A アクセプターおよびコネクター設定パラメーター を参照してください。
- AMQ Core Protocol JMS クライアントでブローカーコネクターを設定する方法は、AMQ Core Protocol JMS ドキュメントの Configuring a broker connector を参照してください。
2.5. TCP 接続の設定
AMQ Broker は Netty を使用して基本的な、暗号化されていない TCP ベースの接続を提供します。この接続は、ブロッキング Java IO または新しい非ブロッキング Java NIO を使用するように設定できます。多くの同時接続でスケーラビリティーを向上させるために、Java NIO が推奨されます。ただし、古い IO を使用すると、何万もの同時接続のサポートを受けても NIO より優れたレイテンシーが発生することがあります。
信頼できないネットワーク全体で接続を実行している場合は、TCP ネットワーク接続が暗号化されないことを認識する必要があります。セキュリティーが優先度であれば、SSL または HTTPS 設定を使用して、この接続で送信されたメッセージを暗号化することを検討してください。詳細は、「接続のセキュリティー保護」 を参照してください。
TCP 接続を使用すると、すべての接続がクライアントによって開始されます。ブローカーはクライアントへの接続を開始しません。これは、ファイアウォールポリシーと、強制的に接続を一方向から開始するように機能します。
TCP 接続では、コネクター URI のホストおよびポートは接続に使用されるアドレスを定義します。
以下の例は、TCP 接続を設定する方法を示しています。
前提条件
アクセプターおよびコネクターの設定を理解する必要があります。詳細は以下を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 新しいアクセプターを追加するか、既存のアクセプターを変更します。接続 URI で、
tcp
をプロトコルとして指定します。IP アドレスまたはホスト名とブローカーのポートの両方を含めます。以下に例を示します。<acceptors> <acceptor name="tcp-acceptor">tcp://10.10.10.1:61617</acceptor> ... </acceptors>
前述の例に基づいて、ブローカーは IP アドレス
10.10.10.1
でポート61617
に接続するクライアントからの TCP 通信を受け入れます。(任意設定): 同様の方法でコネクターを設定できます。以下に例を示します。
<connectors> <connector name="tcp-connector">tcp://10.10.10.2:61617</connector> ... </connectors>
前述の例のコネクターは、指定された IP およびポート
10.10.10.2:61617
に TCP 接続を確立する場合、クライアントまたはブローカー自体によって参照されます。
関連情報
- TCP 接続に使用できる設定オプションの詳細は、付録A アクセプターおよびコネクター設定パラメーター を参照してください。
2.6. HTTP 接続の設定
HTTP プロトコルを介した HTTP 接続トンネルは、ファイアウォールが HTTP トラフィックのみを許可する場合に便利です。AMQ Broker は HTTP が使用されているかどうかを自動的に検出するため、HTTP のネットワーク接続の設定は TCP の接続の設定と同じです。
前提条件
アクセプターおよびコネクターの設定を理解する必要があります。詳細は以下を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 新しいアクセプターを追加するか、既存のアクセプターを変更します。接続 URI で、
tcp
をプロトコルとして指定します。IP アドレスまたはホスト名とブローカーのポートの両方を含めます。以下に例を示します。<acceptors> <acceptor name="http-acceptor">tcp://10.10.10.1:80</acceptor> ... </acceptors>
前述の例に基づいて、ブローカーは IP アドレス
10.10.10.1
でポート80
に接続するクライアントからの HTTP 通信を受け入れます。ブローカーは HTTP プロトコルが使用中であることを自動的に検出し、それに応じてクライアントと通信します。(任意設定): 同様の方法でコネクターを設定できます。以下に例を示します。
<connectors> <connector name="http-connector">tcp://10.10.10.2:80</connector> ... </connectors>
前述の例に記載されているコネクターを使用すると、ブローカーは IP アドレス
10.10.10.2
のポート80
にアウトバウンド HTTP 接続を作成します。
関連情報
- HTTP 接続は TCP と同じ設定パラメーターを使用しますが、いくつかの設定パラメーターもあります。HTTP 接続で利用可能なすべての設定オプションについては、付録A アクセプターおよびコネクター設定パラメーター を参照してください。
-
HTTP の使用方法を示す完全な作業例は、ブローカーインストールの
<install_dir>/examples/features/standard/
ディレクトリーにあるhttp-transport
の例を参照してください。
2.7. セキュアな接続の設定
TLS/SSL を使用してネットワーク接続をセキュアにすることができます。詳細は、「接続のセキュリティー保護」 を参照してください。
2.8. イン仮想マシン接続の設定
複数のブローカーが同じ仮想マシンに共存する場合 (HA) 設定の一部として、VM 内の接続を使用できます。イン仮想マシン接続は、ブローカーと同じ JVM で実行されているローカルクライアントでも使用できます。
前提条件
アクセプターおよびコネクターの設定を理解する必要があります。詳細は以下を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 新しいアクセプターを追加するか、既存のアクセプターを変更します。接続 URI で、
vm
をプロトコルとして指定します。以下に例を示します。<acceptors> <acceptor name="in-vm-acceptor">vm://0</acceptor> ... </acceptors>
前述の例のアクセプターに基づいて、ブローカーは ID が
0
のブローカーからの接続を受け入れます。他のブローカーは、同じ仮想マシンで実行している必要があります。(任意設定): 同様の方法でコネクターを設定できます。以下に例を示します。
<connectors> <connector name="in-vm-connector">vm://0</connector> ... </connectors>
前述の例の connector は、クライアントがクライアントと同じ仮想マシンで実行している ID が
0
のブローカーにイン VM 接続を確立する方法を定義します。クライアントはアプリケーションまたは別のブローカーになります。
第3章 ネットワーク接続でのメッセージングプロトコルの設定
AMQ Broker にはプラグ可能なプロトコルアーキテクチャーがあるため、ネットワーク接続に 1 つ以上のプロトコルを簡単に有効化できます。
ブローカーは以下のプロトコルをサポートします。
上記のプロトコルのほかに、ブローカーは Core と呼ばれる独自のネイティブプロトコルもサポートします。このプロトコルの以前のバージョンは HornetQ と呼ばれ、Red Hat JBoss Enterprise Application Platform によって使用されていました。
3.1. メッセージングプロトコルを使用するためのネットワーク接続の設定
使用する前に、プロトコルをネットワーク接続に関連付ける必要があります。(ネットワーク接続の作成方法と設定方法について、詳しくは 2章ネットワーク接続でのアクセプターおよびコネクターの設定を参照してください。)<broker_instance_dir>/etc/broker.xml
ファイルにあるデフォルト設定には、すでに定義された接続が複数含まれています。便宜上、AMQ Broker にはサポートされる各プロトコルのアクセプターと、すべてのプロトコルをサポートするデフォルトのアクセプターが含まれます。
デフォルトのアクセプターの概要
以下は、broker.xml
設定ファイルにデフォルトで含まれるアクセプターです。
<configuration> <core> ... <acceptors> <!-- All-protocols acceptor --> <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- AMQP Acceptor. Listens on default AMQP port for AMQP traffic --> <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> <!-- STOMP Acceptor --> <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> <!-- HornetQ Compatibility Acceptor. Enables HornetQ Core and STOMP for legacy HornetQ clients. --> <acceptor name="hornetq">tcp://0.0.0.0:5445?anycastPrefix=jms.queue.;multicastPrefix=jms.topic.;protocols=HORNETQ,STOMP;useEpoll=true</acceptor> <!-- MQTT Acceptor --> <acceptor name="mqtt">tcp://0.0.0.0:1883?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=MQTT;useEpoll=true</acceptor> </acceptors> ... </core> </configuration>
特定のネットワーク設定でプロトコルを有効にする唯一の要件は、protocols
パラメーターを アクセプターの URI に追加することです。パラメーターの値は、プロトコル名のコンマ区切りリストである必要があります。protocol パラメーターが URI から省略される場合、すべてのプロトコルが有効になります。
たとえば、AMQP プロトコルを使用して 3232 番ポートでメッセージを受信するためにアクセプターを作成するには、以下の手順に従います。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
以下の行を
<acceptors>
スタンザに追加します。
<acceptor name="ampq">tcp://0.0.0.0:3232?protocols=AMQP</acceptor>
デフォルトのアクセプターの追加パラメーター
最小限のアクセプター設定では、接続 URI の一部としてプロトコルを指定します。ただし、broker.xml
設定ファイルのデフォルトのアクセプターには追加のパラメーターが設定されています。以下の表は、デフォルトのアクセプターに設定された追加パラメーターの詳細を示しています。
Acceptor(s) | パラメーター | 説明 |
---|---|---|
All-protocols acceptor AMQP STOMP | tcpSendBufferSize |
TCP 送信バッファーのサイズ (バイト単位)。デフォルト値は |
tcpReceiveBufferSize |
TCP 受信バッファーのサイズ (バイト単位)。デフォルト値は TCP バッファーサイズは、ネットワークの帯域幅およびレイテンシーに従って調整する必要があります。 つまり、TCP の送信/受信バッファーサイズは以下のように計算する必要があります。 buffer_size = bandwidth * RTT
帯域幅とは秒単位で、ネットワークラウンドトリップタイム (RTT) は秒単位になります。RTT は、 高速ネットワークでは、デフォルトからバッファーサイズを増やす必要がある場合があります。 | |
All-protocols acceptor AMQP STOMP HornetQ MQTT | useEpoll |
サポートするシステム (Linux) を使用する場合は Netty epoll を使用します。Netty ネイティブトランスポートは NIO トランスポートよりも優れたパフォーマンスを提供します。このオプションのデフォルト値は |
All-protocols acceptor AMQP | amqpCredits |
メッセージの合計サイズに関係なく、AMQP プロデューサーが送信できるメッセージの最大数。デフォルト値は AMQP メッセージのブロックにクレジットが使用される方法は、「AMQP プロデューサーのブロック」 を参照してください。 |
All-protocols acceptor AMQP | amqpLowCredits |
ブローカーによってプロデューサーのクレジットが返送される低いしきい値。デフォルト値は AMQP メッセージのブロックにクレジットが使用される方法は、「AMQP プロデューサーのブロック」 を参照してください。 |
HornetQ 互換性アクセプター | anycastPrefix |
anycast および アドレスへの接続時にクライアントがルーティングタイプを指定できるように接頭辞を設定する方法は、「アクセプター設定へのルーティングタイプの追加」 を参照してください。 |
multicastPrefix |
アドレスへの接続時にクライアントがルーティングタイプを指定できるように接頭辞を設定する方法は、「アクセプター設定へのルーティングタイプの追加」 を参照してください。 |
関連情報
- Netty ネットワーク接続に設定できるその他のパラメーターに関する情報は、付録A アクセプターおよびコネクター設定パラメーター を参照してください。
3.2. ネットワーク接続での AMQP の使用
ブローカーは AMQP 1.0 仕様をサポートします。AMQP リンクは、ソースとターゲット間のメッセージ (クライアントとブローカー) の一方向プロトコルです。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
以下の例のように、AMQP の値を持つ
protocols
パラメーターを URI の一部として追加または設定することで、acceptor
を追加または設定し、AMQP
クライアントを受信します。
<acceptors> <acceptor name="amqp-acceptor">tcp://localhost:5672?protocols=AMQP</acceptor> ... </acceptors>
上記の例では、ブローカーはデフォルトの AMQP ポートであるポート 5672 で AMQP 1.0 クライアントを受け入れます。
AMQP リンクには、送信者と受信側の 2 つのエンドポイントがあります。送信者がメッセージを送信する場合、ブローカーはこれを内部形式に変換するため、ブローカーの宛先に転送できます。受信側はブローカーの宛先に接続し、メッセージを配信前に AMQP に戻します。
AMQP リンクが動的の場合、一時キューが作成され、リモートソースまたはリモートターゲットアドレスのいずれかが一時キューの名前に設定されます。リンクが動的ではない場合、リモートターゲットまたはソースのアドレスがキューに使用されます。リモートターゲットまたはソースが存在しない場合は、例外が発生します。
リンクターゲットは、基礎となるセッションをトランザクションとして処理するために使用される Coordinator でも、ロールバックまたはコミットします。
AMQP ではセッションごとに複数のトランザクション amqp:multi-txns-per-ssn
を使用できますが、現在のバージョンの AMQ Broker はセッションごとに単一のトランザクションのみをサポートします。
AMQP 内の分散トランザクション (XA) の詳細は、仕様の 1.0 バージョンでは提供されません。お使いの環境で分散トランザクションのサポートが必要な場合は、AMQ Core Protocol JMS を使用することが推奨されます。
プロトコルとその機能の詳細は、AMQP 1.0 仕様を参照してください。
3.2.1. AMQP リンクをトピックとして使用
JMS とは異なり、AMQP プロトコルにはトピックが含まれません。ただし、キューのコンシューマーだけでなく、AMQP コンシューマーまたは受信側をサブスクリプションとして扱うことは可能です。デフォルトでは、接頭辞 jms.topic.
でアドレスにアタッチする受信リンクがサブスクリプションとして処理され、サブスクリプションキューが作成されます。以下の表でキャプチャーされているように、Terminus Durability の設定方法に応じて、サブスクリプションキューが永続的または揮発性になります。
この種のマルチキャスト専用キューのサブスクリプションを作成します。 | Terminus Durability を 下記のようにセットします。 |
---|---|
永続性 |
|
Non-durable |
|
永続キューの名前は、コンテナー ID とリンク名 (例: my-container-id:my-link-name
) で設定されます。
AMQ Broker は qpid-jms クライアントもサポートし、アドレスに使用される接頭辞に関係なくトピックの使用に対応します。
3.2.2. AMQP セキュリティーの設定
ブローカーは AMQP SASL 認証をサポートします。ブローカーで SASL ベースの認証を設定する方法は、Security を参照してください。
3.3. ネットワーク接続での MQTT の使用
ブローカーは MQTT v3.1.1と v5.0 (および古い v3.1 コードメッセージ形式) をサポートします。MQTT は軽量のクライアントからサーバーへ、パブリッシュ/サブスクライブメッセージングプロトコルです。MQTT は、メッセージングのオーバーヘッドおよびネットワークトラフィック、およびクライアントのコードフットプリントを削減します。このような理由から、MQTT は、センサーやアクチュエーターなどのデバイスを制限するのが適しており、この ng(IoT) のインターネット向けの de facto 標準通信プロトコルがすばやく考えられます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 - MQTT プロトコルが有効になっているアクセプターを追加します。以下に例を示します。
<acceptors> <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT</acceptor> ... </acceptors>
MQTT には、以下を含む便利な機能が多数含まれています。
- QoS (Quality of Service)
- 各メッセージは、関連付けられた QoS(Quality of Service) を定義できます。ブローカーは、定義された最大 QoS(Quality of Service) レベルで、サブスクライバーに対してメッセージの配信を試みます。
- 保持されるメッセージ
特定のアドレスに対してメッセージを保持できます。クライアントの接続前に保持されるメッセージが送信された場合でも、他のメッセージの前に最後に保持されたメッセージを受信する新しいサブスクライバー。
保持されたメッセージは、
sys.mqtt.<topic name>
という名前のキューに保存され、クライアントが保持されたメッセージを削除するまで、または有効期限が設定されている場合はメッセージの有効期限が切れるまで、キュー内に残ります。キューが空の場合、キューは明示的に削除するまで削除されません。たとえば、次の設定ではキューが削除されます。<address-setting match="$sys.mqtt.retain.#"> <auto-delete-queues>true</auto-delete-queues> <auto-delete-addresses>true</auto-delete-addresses> </address-setting>
- ワイルドカードサブスクリプション
- MQTT アドレスは、ファイルシステムの階層と同様に階層です。クライアントは、特定のトピックや、階層のブランチ全体にサブスクライブできます。
- メッセージ
- クライアントは、接続パケットの一部として will message を設定できます。クライアントが異常に切断されると、ブローカーは指定されたアドレスにメッセージを公開します。他のサブスクライバーはメッセージを受信し、対応できます。
MQTT プロトコルの詳細については、仕様を参照してください。
3.3.1. MQTT プロパティーの設定
キーと値のペアを MQTT アクセプターに追加して、接続プロパティーを設定できます。以下に例を示します。
<acceptors> <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT;receiveMaximum=50000;topicAliasMaximum=50000;maximumPacketSize;134217728; serverKeepAlive=30;closeMqttConnectionOnPublishAuthorizationFailure=false</acceptor> ... </acceptors>
- receiveMaximum
-
完了通知が必要になる前にブローカーがクライアントから受信できる QoS 1 および 2 メッセージの最大数を指定することにより、フロー制御を有効にします。デフォルト値は
65535
です。-1
の値は、クライアントからブローカーへのフロー制御を無効にします。これには、値を 0 に設定するのと同じ効果がありますが、CONNACK パケットのサイズが小さくなります。 - topicAliasMaximum
-
クライアントに対して、ブローカーがサポートするエイリアスの最大数を指定します。デフォルト値は
65535
です。-1 の値を指定すると、ブローカーはトピックエイリアスの制限をクライアントに通知できなくなります。これは、値を 0 に設定するのと同じ効果がありますが、CONNACK パケットのサイズが小さくなります。 - maximumPacketSize
-
ブローカーがクライアントから受け入れることができる最大パケットサイズを指定します。デフォルト値は
268435455
です。値が -1 の場合、ブローカーはクライアントに最大パケットサイズを通知できなくなります。つまり、受信パケットのサイズに制限が適用されません。 - serverKeepAlive
-
ブローカーが非アクティブなクライアント接続を開いたままにしておく期間を指定します。設定された値は、クライアントに設定されたキープアライブ値よりも小さい場合、またはクライアントに設定された値が 0 である場合にのみ、接続に適用されます。デフォルト値は
60
秒です。-1
の値は、ブローカーがクライアントのキープアライブ値を (その値が 0 であっても) 常に受け入れることを意味します。 - closeMqttConnectionOnPublishAuthorizationFailure
-
デフォルトでは、承認がないために PUBLISH パケットが失敗した場合、ブローカーはネットワーク接続を閉じます。ブローカーがネットワーク接続を閉じる代わりに完了通知を送信するようにする場合は、
closeMqttConnectionOnPublishAuthorizationFailure
をfalse
に設定します。
3.4. ネットワーク接続での OpenWire の使用
ブローカーは OpenWire protocol プロトコルをサポートします。これにより、JMS クライアントはブローカーと直接対話できます。このプロトコルを使用して、古いバージョンの AMQ Broker と通信します。
現在、AMQ Broker は標準の JMS API のみを使用する OpenWire クライアントをサポートします。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 以下の例にあるように、
acceptor
を追加または変更して、protocol
パラメーターの一部としてOPENWIRE
が含まれるようにします。<acceptors> <acceptor name="openwire-acceptor">tcp://localhost:61616?protocols=OPENWIRE</acceptor> ... </acceptors>
上記の例では、ブローカーは受信 OpenWire コマンドのポート 61616 でリッスンします。
詳細は、<install_dir>/examples/protocols/openwire
にある例を参照してください。
3.5. ネットワーク接続による STOMP の使用
STOMP は、STOMP クライアントが STOMP Broker と通信できるようにするテキスト指向のワイヤプロトコルです。ブローカーは STOMP 1.0、1.1、および 1.2 をサポートします。STOMP クライアントは複数の言語やプラットフォームで利用できます。これにより、相互運用性の選択肢があります。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
既存の
acceptor
を設定するか、新しいアクセプターを作成し、以下のようにSTOMP
の値を持つprotocols
パラメーターを追加します。
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP</acceptor> ... </acceptors>
上記の例では、ブローカーはポート 61613
の STOMP 接続を受け入れます。
STOMP を使用したブローカーの設定例については、& lt;install_dir>/examples/protocols
にある stomp
の例を参照してください。
3.5.1. STOMP の制限
STOMP を使用する場合、以下の制限が適用されます。
-
現在、ブローカーは仮想ホストをサポートしません。つまり、
host
フレーム のCONNECT
ヘッダーは無視されます。 -
メッセージの完了通知はトランザクションではありません。
ACK
フレームはトランザクションの一部にできず、transaction
ヘッダーが設定されている場合は無視されます。
3.5.2. STOMP メッセージの ID の提供
JMS コンシューマーまたは QueueBrowser を介して STOMP メッセージを受信する場合、メッセージには JMSMessageID
などの JMS プロパティーは含まれません。ただし、ブローカーパラメーターを使用して、各受信 STOMP メッセージにメッセージ ID を設定できます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
以下の例のように、STOMP 接続に使用される
acceptor
のstompEnableMessageId
パラメーターをtrue
に設定します。
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor> ... </acceptors>
stompEnableMessageId
パラメーターを使用することで、このアクセプターを使用して送信される各 stomp メッセージには追加のプロパティーが追加されます。次の例に示すように、プロパティーキーは amq-message-id
で、値は STOMP という接頭辞が付いた内部メッセージ ID の文字列表現です。
amq-message-id : STOMP12345
設定で stompEnableMessageId
が指定されていない場合、デフォルト値は false
になります。
3.5.3. 接続時間のライブの設定
STOMP クライアントは、接続を閉じる前に DISCONNECT
フレームを送信する必要があります。これにより、ブローカーはセッションやコンシューマーなどのサーバー側のリソースを閉じることができます。ただし、STOMP クライアントが DISCONNECT フレームを送信せずに終了する場合、または失敗すると、ブローカーにはクライアントが有効であるかどうかを即座に認識することができません。そのため、STOMP の接続は TTL(Time to Live) が 1 分となるように設定されています。複数の 1 分間の間アイドル状態であった場合、ブローカーは STOMP クライアントへの接続を停止します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
以下の例のように、STOMP 接続に使用される
acceptor
の URI にconnectionTTL
パラメーターを追加します。
<acceptors> <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTTL=20000</acceptor> ... </acceptors>
上記の例では、stomp -acceptor
を使用するすべての stomp 接続では、その TTL を 20 秒に設定します。
STOMP プロトコルのバージョン 1.0 には ハートビートフレーム が含まれていません。そのため、ユーザーは、データが connection-ttl 内に送信されることを確認するか、ブローカーがクライアントが停止されサーバー側のリソースをクリーンアップすることを想定します。バージョン 1.1 では、c he-beats を使用して stomp 接続のライフサイクルを維持することができます。
ブローカーのデフォルト時間の上書き
前述のように、STOMP 接続のデフォルトの TTL は 1 分です。この値は、connection-ttl-override
属性をブローカー設定に追加することで上書きできます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
connection-ttl-override
属性を追加し、新しいデフォルトの値をミリ秒単位で指定します。以下のように、<core>
スタンザに属します。
<configuration ...> ... <core ...> ... <connection-ttl-override>30000</connection-ttl-override> ... </core> <configuration>
上記の例では、STOMP 接続のデフォルトの Time to Live(TTL) は 30 秒 (30000
ミリ秒) に設定されます。
3.5.4. JMS からの STOMP メッセージの送受信
STOMP は主にテキスト指向のプロトコルです。JMS と相互運用を容易にするため、STOMP 実装は content-length
ヘッダーの有無を確認し、STOMP メッセージを JMS にマップする方法を決定します。
STOMP のメッセージを...にマッピングしたい場合。 | メッセージは下記の通りにしてください。 |
---|---|
JMS TextMessage |
|
JMS BytesMessage |
|
JMS メッセージを STOMP にマップする場合も、同じロジックが適用されます。STOMP クライアントは、content-length
ヘッダーが存在することを確認して、メッセージボディーのタイプ (文字列またはバイト) を判別できます。
メッセージヘッダーの詳細については、STOMP 仕様を参照してください。
3.5.5. STOMP 宛先の AMQ Broker アドレスおよびキューへのマッピング
メッセージを送信してサブスクライブする場合、STOMP クライアントには通常、destination
ヘッダーが含まれます。宛先名は文字列の値で、ブローカーの宛先にマッピングされます。AMQ Broker では、これらの宛先は アドレス および キュー にマッピングされます。宛先フレームの詳細は、STOMP 仕様を参照してください。
たとえば、以下のメッセージ (ヘッダーおよびボディー) を送信する STOMP クライアントの例を考えます。
SEND destination:/my/stomp/queue hello queue a ^@
この場合、ブローカーは /my/stomp/queue
アドレスに関連付けられたキューへメッセージを転送します。
たとえば、STOMP クライアントが (SEND
フレームを使用して) メッセージを送信する場合、指定された宛先がアドレスにマッピングされます。
これは、クライアントが SUBSCRIBE
または UNSUBSCRIBE
フレームを送信する場合 と同じように機能しますが、この場合は AMQ Broker は destination
をキューにマッピングします。
SUBSCRIBE destination: /other/stomp/queue ack: client ^@
上記の例では、ブローカーは destination
を キュー /other/stomp/queue
にマップします。
STOMP 宛先と JMS 宛先のマッピング
JMS 宛先は、ブローカーアドレスおよびキューにマッピングされます。STOMP を使用してメッセージを JMS 宛先に送信する場合、STOMP 宛先は同じ規則に従う必要があります。
JMS Queue を送受信するには、
jms.queue.
でキュー名を追加します。たとえば、JMS キューのorders
にメッセージを送信するには、STOMP クライアントはフレームを送信する必要があります。SEND destination:jms.queue.orders hello queue orders ^@
jms.topic.
でトピック名を追加し、JMS Topic を送信またはサブスクライブします。たとえば、stocks
JMS Topic をサブスクライブするには、STOMP クライアントは以下のようなフレームを送信する必要があります。SUBSCRIBE destination:jms.topic.stocks ^@
第4章 アドレスおよびキューの設定
4.1. アドレス、キュー、およびルーティングタイプ
AMQ Broker では、アドレスモデルには、addresses、queues、およびrouting typesの 3 つの主要な概念で設定されています。
アドレス はメッセージングエンドポイントを表します。設定内では、通常のアドレスには一意の名前、1 つ以上のキュー、およびルーティングタイプが指定されます。
キューがアドレスに関連付けられます。アドレスごとに複数のキューが存在する場合があります。受信メッセージがアドレスにマッチすると、設定されたルーティングタイプに応じて、メッセージは 1 つ以上のキューに送信されます。キューは、自動作成および削除ができるように設定できます。また、アドレス (およびその関連付けられたキュー) を 永続 として設定できます。キューのメッセージも永続永続キューにある限り、永続キューのメッセージも永続し、ブローカーのクラッシュや再起動を保ち続けることができます。一方、非永続キューのメッセージは、メッセージ自体が永続的であっても、ブローカーのクラッシュや再起動は維持されません。
ルーティングタイプ は、アドレスに関連付けられたキューへメッセージが送信される方法を決定します。AMQ Broker では、表に示すように、2 つの異なるルーティングタイプでアドレスを設定できます。
メッセージをルーティング先とルーティングする場合 | このルーティングタイプを使用する... |
---|---|
ポイントツーポイントのため、一致するアドレス内の単一キュー。 |
|
パブリッシュ/サブスクライブ方式で、一致するアドレス内のすべてのキュー。 |
|
アドレスには少なくとも 1 つのルーティングタイプが定義されている必要があります。
アドレスごとに複数のルーティングタイプを定義することも可能ですが、これは推奨されません。
アドレスに 両方の ルーティングタイプが定義されていて、クライアントがどちらかを優先していない場合、ブローカーはデフォルトで multicast
ルーティングタイプに設定されます。
関連情報
設定の詳細については、以下を参照してください。
-
anycast
ルーティングタイプを使用したポイントツーポイントメッセージング。を参照してください。 「ポイントツーポイントメッセージング用のアドレスの設定」 -
multicast
「パブリッシュサブスクライブメッセージングのアドレスの設定」
-
4.1.1. アドレスおよびキューの命名要件
アドレスおよびキューを設定する場合は、以下の要件に注意してください。
クライアントが使用するワイヤプロトコルに関係なく、クライアントがキューに接続できるようにするには、アドレスおよびキュー名には 以下のいずれの文字も含めないでください。
&
::
,
?
>
-
数字記号 (
#
) およびアスタリスク (*
) 文字はワイルドカード式用に予約されており、アドレスおよびキュー名で使用しないでください。詳細は、「AMQ Broker ワイルドカード構文」 を参照してください。 - アドレスおよびキュー名にはスペースを含めないでください。
-
アドレスまたはキュー名で単語を分離するには、設定した区切り文字を使用します。デフォルトの区切り文字はピリオド (
.
) です。詳細は、「AMQ Broker ワイルドカード構文」 を参照してください。
4.2. アドレスセットへのアドレス設定の適用
AMQ Broker では、ワイルドカード式を使用して一致するアドレス名を表すことで、address-setting
要素に指定された設定をアドレスセットに適用することができます。
以下のセクションでは、ワイルドカード式の使用方法を説明します。
4.2.1. AMQ Broker ワイルドカード構文
AMQ Broker は、アドレス設定でワイルドカードを表す特定の構文を使用します。ワイルドカードは、セキュリティー設定やコンシューマーの作成時に使用することもできます。
-
ワイルドカード式には、ピリオド (
.
) で区切られた単語が含まれます。 数字記号 (
#
) およびアスタリスク (*
) 文字には特別な意味があり、以下のように単語の代わりに使用できます。- 数字記号は、ゼロ以上の単語のシーケンスの一致を意味します。式の最後に使用します。
- アスタリスク文字は単一の単語と一致するを意味します。式内のどこかにこの変数を使用します。
マッチングは文字による文字は実行されませんが、各区切り文字境界では文字ごとに一致します。たとえば、名前に my
を持つキューと一致するよう設定された address-setting
要素は、myqueue
という名前のキューと 一致しません。
複数の address-setting
要素がアドレスと一致する場合、ブローカーオーバーレイ設定は、ベースラインとして最も具体的な一致の設定を使用します。リテラル式はワイルドカードより固有で、アスタリスク (*
) は数値記号 (#
) より具体的なものです。たとえば、my.destination
と my.*
の両方がアドレス my.destination
と一致します。この場合、ワイルドカード式はリテラルよりも具体的なため、ブローカーは最初に my.*
にある設定を適用します。次に、ブローカーは my.destination
アドレス設定要素の設定をオーバーレイし、my.*
と共有される設定を上書きします。たとえば、以下の設定では、my .destination
に関連付けられたキューは max-delivery-attempts
を 3
に設定し、last-value-queue
を false
に設定します。
<address-setting match="my.*"> <max-delivery-attempts>3</max-delivery-attempts> <last-value-queue>true</last-value-queue> </address-setting> <address-setting match="my.destination"> <last-value-queue>false</last-value-queue> </address-setting>
以下の表に示す例は、ワイルドカードを使用してアドレスセットを照合する方法を示しています。
例 | 説明 |
---|---|
|
|
|
|
|
|
|
|
4.2.2. ブローカーのワイルドカード構文の設定
以下の手順では、ワイルドカードアドレスに使用される構文をカスタマイズする方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 以下の例のように、
<wildcard-addresses>
セクションを設定に追加します。<configuration> <core> ... <wildcard-addresses> // <enabled>true</enabled> // <delimiter>,</delimiter> // <any-words>@</any-words> // <single-word>$</single-word> </wildcard-addresses> ... </core> </configuration>
enabled
-
true
に設定すると、カスタム設定を使用するようにブローカーに指示します。 delimiter
-
デフォルトの
.
の代わりにdelimiter
として使用するカスタム文字を指定します 。 any-words
-
any-words
の値として提供された文字は、ゼロ以上の単語のシーケンスに一致し、デフォルトの#
を置き換えます。式の最後にこの文字を使用します。 single-word
-
single-word
の値として提供された文字は、単一の単語の照合に使用され、デフォルトの*
を置き換えます。この文字は式内の任意の場所を使用します。
4.3. ポイントツーポイントメッセージング用のアドレスの設定
ポイントツーポイントメッセージングは、プロデューサーによって送信されたメッセージが 1 つのコンシューマーのみを持つ一般的なシナリオです。AMQP および JMS メッセージプロデューサーおよびコンシューマーは、たとえば、ポイントツーポイントメッセージングキューを使用できます。アドレスに関連付けられたキューがポイントツーポイントでメッセージを受信するようにするには、ブローカー設定で指定の address
要素に anycast
ルーティングタイプを定義します。
anycast
を使用してアドレスでメッセージを受信すると、ブローカーはアドレスに関連付けられたキューを見つけ、メッセージへメッセージをルーティングします。その後、コンシューマーはそのキューからメッセージを消費するよう要求される可能性があります。複数のコンシューマーが同じキューに接続する場合、コンシューマーはそれらを同等に処理できる場合、メッセージがコンシューマー間で均等に分散されます。
以下の図は、ポイントツーポイントメッセージングの例を示しています。
4.3.1. 基本的なポイントツーポイントメッセージングの設定
以下の手順は、ポイントツーポイントメッセージングに対して単一のキューを持つアドレスを設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address
の選択されたqueue
エレメントの周りに、anycast
設定エレメントをラップします。address
要素とqueue
要素の両方のname
属性の値が同じであることを確認します。以下に例を示します。<configuration ...> <core ...> ... <address name="my.anycast.destination"> <anycast> <queue name="my.anycast.destination"/> </anycast> </address> </core> </configuration>
4.3.2. 複数のキューのポイントツーポイントメッセージングの設定
anycast
ルーティングタイプを使用するアドレスで複数のキューを定義できます。ブローカーは関連するすべてのキューに、anycast
アドレスに送信されたメッセージを均等に分散します。Fully Qualified Queue Name(FQQN) を指定することで、クライアントを特定キューに接続できます。複数のコンシューマーが同じキューに接続する場合、ブローカーはコンシューマー間でメッセージを均等に分散します。
以下の図は、2 つのキューを使用したポイントツーポイントメッセージングの例を示しています。
以下の手順は、複数のキューを持つアドレスにポイントツーポイントメッセージングを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address
要素のqueue
要素でanycast
設定要素をラップします。以下に例を示します。<configuration ...> <core ...> ... <address name="my.anycast.destination"> <anycast> <queue name="q1"/> <queue name="q2"/> </anycast> </address> </core> </configuration>
クラスターの複数のブローカーにミラーリングされている設定がある場合、クラスターはプロデューサーおよびコンシューマーへの不透明な方法でポイントツーポイントメッセージングを負荷分散できます。正確な動作は、クラスターに対してメッセージ負荷分散ポリシーの設定方法によって異なります。
関連情報
詳細情報:
- 完全修飾キュー名の指定。「完全修飾キュー名の指定」 を参照してください。
- ブローカークラスターにメッセージの負荷分散を設定する方法は、「ブローカークラスターがメッセージ負荷のバランスを取る方法」 を参照してください。
4.4. パブリッシュサブスクライブメッセージングのアドレスの設定
パブリッシュ/サブスクライブのシナリオでは、メッセージはアドレスにサブスクライブしているすべてのコンシューマーに送信されます。JMS トピックおよび MQTT サブスクリプションは、パブリッシュ/サブスクライブメッセージングの 2 つの例です。アドレスに関連付けられたキューがパブリッシュサブスクライブの方法でメッセージを受信するようにするには、ブローカー設定で指定の address
要素に マルチキャストルーティング
タイプを定義します。
マルチキャスト
ルーティング タイプのアドレスでメッセージを受信すると、ブローカーはメッセージのコピーをアドレスに関連付けられた各キューにルーティングします。コピーのオーバーヘッドを減らすために、各キューにはメッセージへの参照のみが送信され、完全なコピーは送信されません。
以下の図は、パブリッシュ/サブスクライブメッセージングの例を示しています。
以下の手順は、パブリッシュサブスクライブメッセージングのアドレスを設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 空の
multicast
設定要素をアドレスに追加します。<configuration ...> <core ...> ... <address name="my.multicast.destination"> <multicast/> </address> </core> </configuration>
(オプション)1 つ以上の
queue
要素をアドレスに追加し、その中のmulticast
要素をラップします。ブローカーはクライアントがリクエストする各サブスクリプションのキューを自動的に作成するため、この手順は必要ありません。<configuration ...> <core ...> ... <address name="my.multicast.destination"> <multicast> <queue name="client123.my.multicast.destination"/> <queue name="client456.my.multicast.destination"/> </multicast> </address> </core> </configuration>
4.5. ポイントツーポイントおよびパブリッシュサブスクライブメッセージング両方のアドレスの設定
また、ポイントツーポイントとパブリッシュサブスクライブの両方のセマンティクスを持つアドレスを設定することもできます。
ポイントツーポイントとパブリッシュ/サブスクライブセマンティクスの両方を使用するアドレスの設定は、通常 推奨されません。しかし、例えば、orders
という名前の JMS キューと、同じく orders
という名前の JMS トピックが必要な場合には便利な場合もあります。異なるルーティングタイプにより、アドレスがクライアント接続で区別されます。このような状況では、JMS キュー・プロデューサーが送信するメッセージは、anycast
ルーティング・タイプを使用します。JMS トピックプロデューサーによって送信されるメッセージは、multicast
ルーティング タイプを使用します。JMS トピックコンシューマーがブローカーに接続すると、独自のサブスクリプションキューに割り当てられます。ただし、JMS キューコンシューマーは anycast
キューに割り当てられます。
以下の図は、ポイントツーポイントおよびパブリッシュサブスクライブメッセージングの例を示しています。
以下の手順は、ポイントツーポイントとパブリッシュ/サブスクライブメッセージングの両方にアドレスを設定する方法を示しています。
このシナリオの動作は、使用されるプロトコルによって異なります。JMS の場合、トピックとキュープロデューサーとコンシューマーの間に明確な区別があり、これによりロジックを簡単に転送できます。AMQP などの他のプロトコルはこの区別を行いません。AMQP 経由で送信されるメッセージは、anycast
および multicast
によってルーティングされ、コンシューマーデフォルトは anycast
です。詳細は、3章ネットワーク接続でのメッセージングプロトコルの設定 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address
要素のqueue
要素でanycast
設定要素をラップします。以下に例を示します。<configuration ...> <core ...> ... <address name="orders"> <anycast> <queue name="orders"/> </anycast> </address> </core> </configuration>
空の
multicast
設定要素をアドレスに追加します。<configuration ...> <core ...> ... <address name="orders"> <anycast> <queue name="orders"/> </anycast> <multicast/> </address> </core> </configuration>
注記通常、ブローカーはサブスクリプションキューをオンデマンドで作成します。したがって、
multicast
要素内に特定のキューを記述する必要はありません。
4.6. アクセプター設定へのルーティングタイプの追加
通常、anycast
と multicast
の両方を使用しているアドレスでメッセージを受信した場合、anycast
のいずれかのキューがメッセージを受信し、multicast
のすべてのキューが受信します。ただし、クライアントは、アドレスに接続する際に特別な接頭辞を指定して、anycast
と multicast
キャストのどちらで接続するかを指定することができます。接頭辞は、ブローカー設定のアクセプターの URL 内の anycastPrefix
および multicastPrefix
パラメーターを使用して指定されるカスタム値です。
以下の手順は、特定のアクセプターに接頭辞を設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 特定のアクセプターでは、
anycast
接頭辞を設定するには、設定済みの URL にanycastPrefix
を追加します。カスタム値を設定します。以下に例を示します。<configuration ...> <core ...> ... <acceptors> <!-- Acceptor for every supported protocol --> <acceptor name="artemis">tcp://0.0.0.0:61616?protocols=AMQP;anycastPrefix=anycast://</acceptor> </acceptors> ... </core> </configuration>
前述の設定により、アクセプタは
anycast
の接頭辞にanycast://
を使用するように設定されています。クライアントコードは、クライアントがanycast
キューの 1 つだけにメッセージを送信する必要がある場合は、anycast://<my.destination>/
を指定できます。特定のアクセプターでは、
multicast
接頭辞を設定するには、設定された URL にmulticastPrefix
を追加します。カスタム値を設定します。以下に例を示します。<configuration ...> <core ...> ... <acceptors> <!-- Acceptor for every supported protocol --> <acceptor name="artemis">tcp://0.0.0.0:61616?protocols=AMQP;multicastPrefix=multicast://</acceptor> </acceptors> ... </core> </configuration>
前述の設定に基づいて、アクセプターは
multicast
接頭辞にmulticast://
を使用するよう設定されます。クライアントコードは、クライアントがmulticast
キュー にのみ送信されたメッセージが必要な場合はmulticast://<my.destination>/
を指定できます。
4.7. サブスクリプションキューの設定
ほとんどの場合、サブスクリプションキューを手動で作成する必要はありません。なぜなら、プロトコルマネージャーは、クライアントが最初にアドレスへのサブスクライブを要求したときに、自動的にサブスクリプションキューを作成するからです。詳細は、「プロトコルマネージャーおよびアドレス」 を参照してください。永続サブスクリプションの場合、生成されたキュー名はクライアント ID とアドレスを連結したものです。
以下のセクションでは、必要に応じてサブスクリプションキューを手動で作成する方法を説明します。
4.7.1. 永続サブスクリプションキューの設定
キューが永続サブスクリプションとして設定されると、ブローカーは非アクティブなサブスクライバーのメッセージを格納し、再接続時にサブスクライバーに配信します。そのため、クライアントはサブスクライブ後にキューへ配信される各メッセージを受信することが保証されます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 選択した キューに
永続
設定要素を追加します。true
の値を設定します。<configuration ...> <core ...> ... <address name="my.durable.address"> <multicast> <queue name="q1"> <durable>true</durable> </queue> </multicast> </address> </core> </configuration>
注記キューはデフォルトで永続性があるため、永続性のあるキューを作成するために、
durable
要素を含めて値をtrue
に設定することは、厳密には必要ありません。ただし、要素を明示的に含むと、必要に応じてキューの動作を非永続状態に後で変更できます。
4.7.3. 非永続的なサブスクリプションキューの設定
非永続的なサブスクリプションは、通常、一時キューを作成および削除する関連するプロトコルマネージャーによって管理されます。
ただし、非永続サブスクリプションキューのように動作するキューを手動で作成する場合は、キューで purge-on-no-consumers
属性を使用できます。purge-on-no-consumers
が true
に設定されている場合、コンシューマーが接続されるまでキューはメッセージの受信を開始しません。さらに、最後のコンシューマーがキューから切断されると、キューは パージ され ます (つまり、メッセージが削除されます)。キューに新しいコンシューマーがキューに接続するまで、キューはそれ以上のメッセージを受信しません。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 選択した各キューに
purge-on-no-consumers
属性を追加します。true
の値を設定します。<configuration ...> <core ...> ... <address name="my.non.durable.address"> <multicast> <queue name="orders1" purge-on-no-consumers="true"/> </multicast> </address> </core> </configuration>
4.8. アドレスおよびキューの自動作成および削除
アドレスおよびキューを自動的に作成し、使用されなくなったら削除するようにブローカーを設定できます。これにより、クライアントが接続する前に各アドレスを事前に設定する必要がなくなります。
4.8.1. 自動キュー作成および削除用の設定オプション
以下の表は、address -setting
要素を設定してキューとアドレス を自動的に作成し、削除する際に利用できる設定要素のリストです。
address-setting を下記に設定したい場合 | この設定を追加してください |
---|---|
クライアントが存在しないアドレスにマッピングされたキューからメッセージを消費するか、消費しようとするとアドレスを作成します。 |
|
クライアントがキューからメッセージを消費するか、消費しようとするとキューを作成します。 |
|
キューがなくなったら、自動的に作成されたアドレスを削除します。 |
|
キューのコンシューマー 0 と 0 のメッセージがある場合に、自動作成されたキューを削除します。 |
|
クライアントが指定しない場合は、特定のルーティングタイプを使用します。 |
|
4.8.2. アドレスおよびキューの自動作成および削除の設定
以下の手順では、アドレスおよびキューの自動作成および削除を設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 自動作成および削除のための
address-setting
を設定します。以下の例では、前述の表に記載されているすべての設定要素を使用しています。<configuration ...> <core ...> ... <address-settings> <address-setting match="activemq.#"> <auto-create-addresses>true</auto-create-addresses> <auto-delete-addresses>true</auto-delete-addresses> <auto-create-queues>true</auto-create-queues> <auto-delete-queues>true</auto-delete-queues> <default-address-routing-type>ANYCAST</default-address-routing-type> </address-setting> </address-settings> ... </core> </configuration>
address-setting
-
address-setting
要素の設定は、ワイルドカードアドレスactivemq.#
にマッチするすべてのアドレスまたはキューに適用されます。 auto-create-addresses
- クライアントが存在しないアドレスへの接続を要求すると、ブローカーはアドレスを作成します。
auto-delete-addresses
- 自動作成されたアドレスは、キューに関連付けられなくなった時点で削除されます。
auto-create-queues
- クライアントが存在しないキューへの接続を要求すると、ブローカーはキューを作成します。
auto-delete-queues
- 自動作成されたキューは、コンシューマーまたはメッセージがないと削除されます。
default-address-routing-type
-
クライアントが接続時にルーティングタイプを指定しない場合、ブローカーはアドレスにメッセージを配信する際に
ANYCAST
を使用します。デフォルト値はMULTICAST
です。
関連情報
詳細情報:
- アドレスの設定時に使用できるワイルドカード構文。「アドレスセットへのアドレス設定の適用」 を参照してください。
- ルーティングタイプについては、「アドレス、キュー、およびルーティングタイプ」 を参照してください。
4.8.3. プロトコルマネージャーおよびアドレス
protocol manager と呼ばれるコンポーネントは、AMQ Broker アドレスモデル、キューおよびルーティングタイプで使用される概念にプロトコル固有の概念をマッピングします。特定の状況下では、プロトコルマネージャーが自動的にブローカー上にキューを作成することがあります。
例えば、クライアントが /house/room1/lights
と /house/room2/lights
のアドレスを持つ MQTT サブスクリプションパケットを送信した場合、MQTT プロトコルマネージャーは、この 2 つのアドレスが multicast
セマンティクスを必要とすることと理解します。そのため、プロトコルマネージャーはまず、両方のアドレスで multicast
が有効になっていることを確認します。そうでない場合は、動的に作成を試みます。成功すれば、プロトコル・マネージャーは、クライアントが要求した各サブスクリプションのために特別なサブスクリプションキューを作成します。
各プロトコルの動作は若干異なります。以下の表は、様々なタイプの queue
へのサブスクライブフレームが要求されたときに、典型的に起こることを説明しています。
キューがこのタイプのものである場合 | プロトコルマネージャーの通常のアクションは下記の通りです。 |
---|---|
永続性のあるサブスクリプションキュー |
適切なアドレスを検索し、 特別な名前を使用すると、プロトコルマネージャーは、必要なクライアントのサブスクリプションキューを迅速に特定し、クライアントの接続を解除し、後で再接続できるようにします。 クライアントがキューのサブスクライブを解除すると、キューが削除されます。 |
一時サブスクリプションキュー |
適切なアドレスを検索し、 クライアントがキューを切断すると、キューが削除されます。 |
ポイントツーポイントキュー |
適切なアドレスを探し、 キューが自動作成されると、コンシューマーがなく、メッセージがなければ自動的に削除されます。 |
4.9. 完全修飾キュー名の指定
内部的には、ブローカーはアドレスのクライアント要求を特定のキューにマッピングします。ブローカーは、メッセージの送信先となるキューまたはメッセージを受信するキューをクライアントに代わって決定します。ただし、より高度なユースケースでは、クライアントが直接キュー名を指定する必要がある場合があります。このような状況では、クライアントは 完全修飾キュー名 (FQQN) を使用できます。FQQN には、::
で区切られたアドレス名とキュー名の両方が含まれています。
以下の手順では、複数のキューを持つアドレスに接続する際に FQQN を指定する方法を説明します。
前提条件
以下の例のように、2 つ以上のキューが設定されているアドレスがあります。
<configuration ...> <core ...> ... <addresses> <address name="my.address"> <anycast> <queue name="q1" /> <queue name="q2" /> </anycast> </address> </addresses> </core> </configuration>
手順
クライアントコードで、ブローカーから接続を要求する際に、アドレス名とキュー名の両方を使用します。名前を区切りには、2 つのコロン (
::
) を使用します。以下に例を示します。String FQQN = "my.address::q1"; Queue q1 session.createQueue(FQQN); MessageConsumer consumer = session.createConsumer(q1);
4.10. シャードキューの設定
部分的な順序付けのみが必要とされるキュー全体のメッセージの処理には、queue shardingを使用するのが一般的なパターンです。つまり、単一の論理キューとして動作する anycast
アドレスを定義します。これは、多くの基礎となる物理キューでサポートされます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address
要素を追加し、name
属性を設定します。以下に例を示します。<configuration ...> <core ...> ... <addresses> <address name="my.sharded.address"></address> </addresses> </core> </configuration>
anycast
ルーティングタイプを追加し、希望するシャードキューの数を入力します。以下の例では、キューq1
、q2
、q3
がエニーキャスト
の宛先として追加されています。<configuration ...> <core ...> ... <addresses> <address name="my.sharded.address"> <anycast> <queue name="q1" /> <queue name="q2" /> <queue name="q3" /> </anycast> </address> </addresses> </core> </configuration>
前述の設定に基づき、my.sharded.address
に送られたメッセージは、q1
、q2
、q3
に均等に配分されます。クライアントは、完全修飾キュー名 (FQQN) の使用時に、特定の物理キューに直接接続して、その特定のキューにのみ送信されたメッセージを受け取ることができます。
特定のメッセージを特定のキューに結びつけるために、クライアントはメッセージごとにメッセージグループを指定できます。ブローカーは、グループ化されたメッセージを同じキューにルーティングし、1 つのコンシューマーはそれをすべて処理します。
関連情報
詳細情報:
- 完全修飾キュー名。「完全修飾キュー名の指定」を参照してください。
- メッセージのグループ化。AMQ Core Protocol JMS ドキュメントの Using message groups を参照してください。
4.11. 最後の値キューの設定
last value queueとは、同じラストバリューキーの値を持つ新しいメッセージがキューに入ると、キュー内のメッセージを破棄するタイプのキューです。この動作により、最後の値キューは同じキーの最後の値のみを保持します。
最終値キューに対する単純なユースケースは、株式の株価しか監視するためのものです。特定の株式の最新値のみが関心があります。
設定した最後の値キーのないメッセージが最後の値キューに送信される場合、ブローカーはこのメッセージを通常メッセージとして処理します。設定された最後の値キーを持つ新しいメッセージが到達すると、このようなメッセージはキューから消去されません。
最後の値キューを個別に、またはアドレスセットに関連付けられたすべてのキューに設定できます。
以下の手順では、以下の方法で最後の値キューを設定する方法を説明します。
4.11.1. 最後の値キューを個別に設定
以下の手順は、最後の値キューを個別に設定する方法を説明します。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 指定のキューに、
last-value-key
キーを追加し、カスタム値を指定します。以下に例を示します。<address name="my.address"> <multicast> <queue name="prices1" last-value-key="stock_ticker"/> </multicast> </address>
また、デフォルトのラストバリューキー名
_AMQ_LVQ_NAME
を使用するラストバリューキューを設定することもできます。これを行うには、与えられたキューにlast-value
のキーを追加します。この値はtrue
に設定します。以下に例を示します。<address name="my.address"> <multicast> <queue name="prices1" last-value="true"/> </multicast> </address>
4.11.2. アドレスの最後の値キューの設定
次の手順では、アドレスまたは一連のアドレスにラストバリューキューを設定します。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address-setting
要素に一致するアドレスの場合は、default-last-value-key
を追加します。カスタム値を指定します。以下に例を示します。<address-setting match="lastValue"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>
上記の設定に基づいて、
lastValue
アドレスに関連付けられたすべてのキューは、stock_ticker
の最後の値キーを使用します。デフォルトでは、default -last-value-key
の値は設定されていません。一連のアドレスに対してラストバリューキューを設定するには、アドレスのワイルドカードを指定することができます。以下に例を示します。
<address-setting match="lastValue.*"> <default-last-value-key>stock_ticker</default-last-value-key> </address-setting>
または、アドレスに関連付けられたすべてのキューや一連のアドレスを設定して、デフォルトの最後の値キー名である
_AMQ_LVQ_NAME
を使用することができます。これを行うには、default-last-value-key
の代わりにdefault-last-value-queue
を追加します。この値はtrue
に設定します。以下に例を示します。<address-setting match="lastValue"> <default-last-value-queue>true</default-last-value-queue> </address-setting>
関連情報
- アドレスの設定時に使用できるワイルドカード構文についての詳細は、「アドレスセットへのアドレス設定の適用」 を参照してください。
4.11.3. 最後の値のキュー動作の例
この例では、最後の値キューの動作を示しています。
broker.xml
設定ファイルで、以下のような設定が追加されているとします。
<address name="my.address"> <multicast> <queue name="prices1" last-value-key="stock_ticker"/> </multicast> </address>
上記の設定では、prices1
というキューを作成し、最終値のキーを stock_ticker
としています。
ここで、クライアントが 2 つのメッセージを送信するとします。各メッセージには、プロパティー stock_ticker
に同じ値 ATN
があります。各メッセージには stock_ price
というプロパティーに異なる値があります。各メッセージは、同じキュー prices1
に送信されます。
TextMessage message = session.createTextMessage("First message with last value property set"); message.setStringProperty("stock_ticker", "ATN"); message.setStringProperty("stock_price", "36.83"); producer.send(message);
TextMessage message = session.createTextMessage("Second message with last value property set"); message.setStringProperty("stock_ticker", "ATN"); message.setStringProperty("stock_price", "37.02"); producer.send(message);
stock_ticker
last value キーと同じ値を持つ 2 つのメッセージ (この場合は ATN
) が prices1 queue
に到達すると、最新のメッセージのみがキュー内に残り、最初のメッセージがパージされます。コマンドラインで以下の行を入力し、この動作を検証できます。
TextMessage messageReceived = (TextMessage)messageConsumer.receive(5000); System.out.format("Received message: %s\n", messageReceived.getText());
この例では、両方のメッセージが最後の値キーに同じ値を使用し、2 番目のメッセージがキューに受信されたため、2 つ目のメッセージが表示されます。
4.11.4. 最後の値キューに対して非破壊的な消費を強制する
コンシューマーがキューに接続すると、通常の動作として、そのコンシューマーに送信されたメッセージがコンシューマーによってのみ取得されます。コンシューマーがメッセージの受信を確認すると、ブローカーはキューからメッセージを削除します。
通常の消費動作の代わりに、非破壊的な消費を強制するようにキューを設定できます。この場合、キューがメッセージをコンシューマーに送信すると、他のコンシューマーによってメッセージを受信できます。さらに、コンシューマーが消費した場合でも、メッセージはキューに残ります。このような非破壊的な消費行動を強制する場合、コンシューマーはキューブラウザーと呼ばれます。
非破壊的な消費を実施すると、キューが特定の最後の値キーに関する最新値を保持するようにするため、最後の値キューでは便利な設定になります。
以下の手順は、最後の値キューに対して非破壊的な消費を強制する方法を示しています。
前提条件
すでに個別に、あるいは、アドレスや一連のアドレスに関連するすべてのキューに対して、最後の値のキューを設定しました。詳細は以下を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 キューを最後の値キューとして個別に設定している場合は、
non-destructive
キーを追加します。この値はtrue
に設定します。以下に例を示します。<address name="my.address"> <multicast> <queue name="orders1" last-value-key="stock_ticker" non-destructive="true" /> </multicast> </address>
以前、最後の値キューにアドレスまたは一連のアドレス を設定している場合は、
default-non-destructive
キーを追加します。この値はtrue
に設定します。以下に例を示します。<address-setting match="lastValue"> <default-last-value-key>stock_ticker </default-last-value-key> <default-non-destructive>true</default-non-destructive> </address-setting>
注記デフォルトでは、
default-non-destructive
の値はfalse
です。
4.12. 期限切れのメッセージを期限切れアドレスに移動する
最後の値キュー以外のキューでは、非破壊的なコンシューマーしかない場合、ブローカーはキューからメッセージを削除できず、キューのサイズが徐々に増加します。キューサイズで制約のない増加を防ぐには、メッセージの有効期限が切れるタイミングを設定し、ブローカーが期限切れのメッセージを移動するアドレスを指定します。
4.12.1. メッセージの有効期限の設定
以下の手順では、メッセージの有効期限を設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素で、message-expiry-scan-period
を設定して、ブローカーが期限切れのメッセージをスキャンする頻度を指定します。<configuration ...> <core ...> ... <message-expiry-scan-period>1000</message-expiry-scan-period> ...
前述の設定に基づいて、ブローカーは 1000 ミリ秒ごとに期限切れのメッセージのキューをスキャンします。
一致するアドレスまたは一連のアドレスの
address-setting
要素で、有効期限切れのアドレスを指定します。また、メッセージの有効期限を設定します。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="stocks"> ... <expiry-address>ExpiryAddress</expiry-address> <expiry-delay>10</expiry-delay> ... </address-setting> ... <address-settings> <configuration ...>
expiry-address
-
一致するアドレスや一連のアドレスの有効期限。前述の例では、ブローカーは
stocks
アドレスに対する期限切れメッセージをExpiryAddress
と呼ばれる期限切れアドレスに送信します。 expiry-delay
デフォルトの有効期限を使用するメッセージにブローカーが適用される有効期限 (ミリ秒単位)。デフォルトでは、メッセージの有効期限は
0
で、有効期限がないことを意味します。デフォルト以上の有効期限が設定されているメッセージに対しては、expiry-delay
は効果がありません。例えば、先ほどの例のように、アドレスの
expiry-delay
を10
に設定したとします。デフォルトの有効期限が0
のメッセージがこのアドレスのキューに到着した場合、ブローカーはメッセージの有効期限を0
から10
に変更します。しかし、有効期限を20
に設定している別のメッセージが到着した場合、その有効期限は変更されません。expiry-delay を-1
に設定した場合、この機能は無効になります。デフォルトでは、expiry-delay
は-1
に設定されます。
また、
expiry-delay
に値を指定する代わりに、expiry delay の最小値と最大値を指定することもできます。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="stocks"> ... <expiry-address>ExpiryAddress</expiry-address> <min-expiry-delay>10</min-expiry-delay> <max-expiry-delay>100</max-expiry-delay> ... </address-setting> ... <address-settings> <configuration ...>
min-expiry-delay
- ブローカーがメッセージに適用される最小有効期限 (ミリ秒単位)。
max-expiry-delay
ブローカーがメッセージに適用される最大有効期限 (ミリ秒単位)。
ブローカーは、以下のように
min-expiry-delay
とmax-expiry-delay
の値を適用します。-
デフォルトの有効期限が
0
のメッセージに対して、ブローカーは有効期限を指定された値のmax-expiry-delay
に設定します。max-expiry-delay
の値を指定していない場合、ブローカーは指定されたmin-expiry-delay
の値に満了時間を設定します。min-expiry-delay
の値を指定しない場合、ブローカーはメッセージの有効期限を変更しません。 -
max-expiry-delay
の値を上回る有効期限のあるメッセージの場合、ブローカーは有効期限をmax-expiry-delay
の指定値に設定します。 -
有効期限が
min-expiry-delay
の値以下のメッセージに対して、ブローカーは有効期限を指定されたmin-expiry-delay
の値に設定します。 -
min-expiry-delay
およびmax-expiry-delay
の値の間に有効期限のあるメッセージの場合、ブローカーはメッセージの有効期限を変更しません。 -
expiry-delay
の値 (すなわちデフォルト値の-1
以外) を指定すると、min-expiry-delay
およびmax-expiry-delay
に指定する値が上書きされます。 -
min-expiry-delay
とmax-expiry-delay
の両方のデフォルト値は-1
(つまり無効) です。
-
デフォルトの有効期限が
設定ファイルの
address
要素で、以前にexpiry-address
に指定したアドレスを設定します。このアドレスにキューを定義します。以下に例を示します。<addresses> ... <address name="ExpiryAddress"> <anycast> <queue name="ExpiryQueue"/> </anycast> </address> ... </addresses>
前述の設定例では、期限切れキュー
ExpiryQueue
と期限切れアドレスExpiryAddress
を関連付けています。
4.12.2. 期限切れリソースの自動作成
一般的なユースケースとして、期限切れのメッセージを元のアドレスに従って分離することです。例えば、stocks
というアドレスからの期限切れメッセージを EXP.stocks
という期限切れキューにルーティングすることを選択したとします。同様に、orders
というアドレスからの期限切れメッセージを EXP.orders
という期限切れキューにルーティングする場合もあるでしょう。
このタイプのルーティングパターンにより、期限切れのメッセージを簡単に追跡、検査、および管理できるようになります。ただし、このようなパターンは、主に自動作成されたアドレスおよびキューを使用する環境に実装するのが困難です。このような環境では、管理者は、期限切れのメッセージを保持するためにアドレスおよびキューを手動で作成するために必要な追加の作業を必要としません。
解決策として、特定のアドレスまたは一連のアドレス の期限切れのメッセージを処理するように、リソース (すなわちアドレスとキュー) を自動的に作成するようにブローカーを設定できます。以下の手順はその一例です。
前提条件
- 指定したアドレスまたは一連のアドレスに対して、すでに有効期限付きのアドレスを設定しています。詳細は、「メッセージの有効期限の設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 以前、設定ファイルに追加した
<address-setting>
要素を探して、一致するアドレスまたは一連のアドレスの有効期限を定義します。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="stocks"> ... <expiry-address>ExpiryAddress</expiry-address> ... </address-setting> ... <address-settings> <configuration ...>
<address-setting>
要素に、期限切れリソース (すなわちアドレスやキュー) を自動的に作成することや、これらのリソースにどのような名前を付けるかをブローカに指示する設定項目を追加します。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="stocks"> ... <expiry-address>ExpiryAddress</expiry-address> <auto-create-expiry-resources>true</auto-create-expiry-resources> <expiry-queue-prefix>EXP.</expiry-queue-prefix> <expiry-queue-suffix></expiry-queue-suffix> ... </address-setting> ... <address-settings> <configuration ...>
auto-create-expiry-resources
期限切れのメッセージを受信するため、ブローカーが期限切れアドレスとキューを自動的に作成するかどうかを指定します。デフォルト値は
false
です。パラメーターの値が
true
に設定されている場合、ブローカーは期限切れアドレスと関連付けられた期限切れキューを定義する<address>
要素を自動的に作成します。自動的に作成された<address>
要素の名前の値は、<expiry-address>
に指定された名前の値と一致します。自動作成された期限切れキューには、
multicast
ルーティングタイプがあります。デフォルトでは、ブローカは失効したメッセージが最初に送信されたアドレス (例えば、stocks
) と一致するように失効キューに名前を付けています。ブローカーは、
_AMQ_ORIG_ADDRESS
プロパティーを使用する期限切れキューのフィルターも定義します。このフィルターは、期限切れキューが対応する元のアドレスに送信されるメッセージのみを受け取るようになります。expiry-queue-prefix
ブローカーにより、自動作成された期限切れキューの名前に適用される接頭辞。デフォルト値は
EXP
です。接頭辞の値を定義した場合、またはデフォルト値を維持した場合、期限切れキューの名前は、接頭辞と元のアドレスを連結したものになります (例:
EXP.stocks
)。expiry-queue-suffix
- ブローカーが自動作成された期限切れキューの名前に適用される接尾辞。デフォルト値は定義されていません (つまり、ブローカーは接尾辞を適用しません)。
キュー名自体を使用して (AMQ Broker Core Protocol JMS クライアントを使用する場合など)、または完全修飾キュー名 (別の JMS クライアントを使用する場合など) を使用して、期限切れキューに直接アクセスできます。
期限切れアドレスとキューは自動的に作成され、自動作成されたアドレスやキューの削除に関連するアドレス設定もこれらの期限切れリソースに適用されます。
関連情報
- 自動作成されたアドレスやキューの自動削除を設定するためのアドレス設定については、「アドレスおよびキューの自動作成および削除の設定」 を参照してください。
4.13. 配信されていないメッセージをデッドレターアドレスへ移行
クライアントにメッセージの配信に失敗した場合は、ブローカーがメッセージの配信を継続しようとしない場合があります。無限配信を試行するのを防ぐために、dead letter address と 1 つ以上の dead letter queuesを定義できます。指定の数の配信試行後、ブローカーは元のキューから未配信メッセージを削除し、そのメッセージを設定済みの dead letter アドレスに送信します。システム管理者は、デッド文字キューから未配信メッセージを後で消費してメッセージを検査できます。
指定のキューに dead letter アドレスを設定しない場合、ブローカーは指定された数の配信試行後にキューから未配信メッセージを完全に削除します。
dead letter キューから消費される配信されていないメッセージには、以下のプロパティーがあります。
_AMQ_ORIG_ADDRESS
- メッセージの元のアドレスを指定する string プロパティー
_AMQ_ORIG_QUEUE
- メッセージの元のキューを指定する string プロパティー
4.13.1. デッドレターアドレスの設定
以下の手順は、デッドレターアドレスと関連するデッドレターキューを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 キュー名と一致する
<address-setting>
要素で、デッドレターのアドレス名と配信試行回数の最大値を設定します。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="exampleQueue"> <dead-letter-address>DLA</dead-letter-address> <max-delivery-attempts>3</max-delivery-attempts> </address-setting> ... <address-settings> <configuration ...>
match
-
ブローカーがこの
address-setting
セクションの設定を適用するアドレス。<address-setting>
要素のmatch
属性には、ワイルドカード式を指定できます。ワイルドカード式を使用すると、<address-setting>
要素に設定されたデッドレター設定を一致する一連のアドレスに関連付ける場合に便利です。 dead-letter-address
- dead letter アドレスの名前。この例では、ブローカーは未配信メッセージをキュー exampleQueue から dead letter address(DLA) に移動します。
max-delivery-attempts
-
配信不能メッセージを設定済みの dead letter アドレスに移動するまでの、ブローカーによる配信試行の最大数。この例では、ブローカーは配信に失敗した 3 回失敗した後、未配信メッセージを dead letter address に移動します。デフォルト値は
10
です。ブローカーが再配信の試行を無限にするには、-1
の値を指定します。
addresses
セクションに、dead letter アドレス (DLA) のaddress
要素を追加します。dead letter キューを dead letter アドレスに関連付けるには、queue
の名前を指定します。以下に例を示します。<configuration ...> <core ...> ... <addresses> <address name="DLA"> <anycast> <queue name="DLQ" /> </anycast> </address> ... </addresses> </core> </configuration>
上記の設定では、DLQ という名前の dead letter キューを dead letter アドレス (DLA) に関連付けます。
関連情報
- アドレス設定でワイルドカードを使用する方法は、「アドレスセットへのアドレス設定の適用」 を参照してください。
4.13.2. デッドレターキューの自動作成
一般的なユースケースは、元のアドレスに従って配信されていないメッセージを分離することです。たとえば、配信不能メッセージを stocks
というアドレスから、DLQ.stocks
という dead letter キューが関連付けられている DLA.stocks
という dead letter キューにルーティングすることを選択できます。同様に、orders
というアドレスから配信不能メッセージを DLA.orders
という dead letter アドレスにルーティングすることもできます。
このタイプのルーティングパターンにより、未配信のメッセージを追跡、検査、および管理が容易になります。ただし、このようなパターンは、主に自動作成されたアドレスおよびキューを使用する環境に実装するのが困難です。このタイプの環境のシステム管理者は、アドレスおよびキューを手動で作成するのに必要な追加の作業を必要としない可能性があります。
解決策として、以下に示すように、未配信メッセージを処理するよう addressees および キューを自動的に作成するようにブローカーを設定できます。
前提条件
- キューまたはキューのセットに dead letter アドレスがすでに設定されている。詳細は、「デッドレターアドレスの設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一致したキューまたはキューのセットのデッドレターアドレスを定義するために追加した
<address-setting>
要素を見つけます。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="exampleQueue"> <dead-letter-address>DLA</dead-letter-address> <max-delivery-attempts>3</max-delivery-attempts> </address-setting> ... <address-settings> <configuration ...>
<address-setting>
要素に、dead letter リソース (つまり、アドレスとキュー) を自動的に作成するようブローカーに指示する設定項目と、これらのリソースの命名方法を追加します。以下に例を示します。<configuration ...> <core ...> ... <address-settings> ... <address-setting match="exampleQueue"> <dead-letter-address>DLA</dead-letter-address> <max-delivery-attempts>3</max-delivery-attempts> <auto-create-dead-letter-resources>true</auto-create-dead-letter-resources> <dead-letter-queue-prefix>DLQ.</dead-letter-queue-prefix> <dead-letter-queue-suffix></dead-letter-queue-suffix> </address-setting> ... <address-settings> <configuration ...>
auto-create-dead-letter-resources
ブローカーが dead letter アドレスおよびキューを自動的に作成し、配信不能メッセージを受信するかどうかを指定します。デフォルト値は
false
です。auto-create-dead-letter-resources
がtrue
に設定されている場合、ブローカーは dead letter アドレスと関連する dead letter キューを定義する<address>
要素を自動的に作成します。自動作成された<address>
要素の名前は、<dead-letter-address>
に指定する name の値と一致します。ブローカーが自動作成された
<address>
要素で定義する dead letter キューには、multicast
ルーティングタイプがあります。デフォルトでは、ブローカーが dead letter キューに名前を付け、配信不能メッセージの元のアドレス (stocks
など) を照合します。ブローカーは、
_AMQ_ORIG_ADDRESS
プロパティーを使用する dead letter キューのフィルターも定義します。このフィルターは、dead letter キューが対応する元のアドレスに送信されるメッセージのみを受け取るようになります。dead-letter-queue-prefix
ブローカーにより、自動作成された dead letter キューの名前に適用される接頭辞。デフォルト値は
DLQ
です。接頭辞値を定義するか、デフォルト値をそのまま使用すると、配信不能キューの名前は接頭辞と元のアドレスを連結したものになります (例:
DLQ.stocks
)。dead-letter-queue-suffix
- ブローカーにより、自動作成された dead letter キューに適用される接尾辞。デフォルト値は定義されていません (つまり、ブローカーは接尾辞を適用しません)。
4.14. 期限切れまたは未配信の AMQP メッセージに対するアノテーションおよびプロパティー
ブローカーは、期限切れの AMQP メッセージまたは未配信の AMQP メッセージを、設定した期限切れまたはデッドレターキューに移動する前に、アノテーションおよびプロパティーをメッセージに適用します。クライアントは、これらのプロパティーまたはアノテーションに基づいてフィルターを作成し、有効期限または dad letter キューから消費する特定のメッセージを選択できます。
ブローカーが適用されるプロパティーは 内部 プロパティーです。これらのプロパティーは、通常の使用のためにクライアントに公開されませんが、フィルターのクライアントで指定できます。
以下の表は、ブローカーが期限切れの AMQP メッセージまたは配信されないアノテーションおよび内部プロパティーを表しています。
アノテーション名 | 内部プロパティー名 | 説明 |
---|---|---|
x-opt-ORIG-MESSAGE-ID | _AMQ_ORIG_MESSAGE_ID | メッセージが期限切れまたは dead letter キューに移動される前の、元のメッセージ ID。 |
x-opt-ACTUAL-EXPIRY | _AMQ_ACTUAL_EXPIRY | 最後のエポックの開始からの経過時間 (ミリ秒単位) に指定されたメッセージの有効期限。 |
x-opt-ORIG-QUEUE | _AMQ_ORIG_QUEUE | 期限切れまたは未配信メッセージの元のキュー名。 |
x-opt-ORIG-ADDRESS | _AMQ_ORIG_ADDRESS | 期限切れまたは未配信メッセージの元のアドレス名。 |
関連情報
- AMQP クライアントがアノテーションに基づいて AMQP メッセージをフィルターするように設定する例は、「アノテーションを基にした AMQP メッセージのフィルター」 を参照してください。
4.15. キューの無効化
ブローカー設定でキューを手動で定義すると、キューはデフォルトで有効になります。
ただし、クライアントがサブスクライブできるようにキューを定義するケースがありますが、メッセージルーティングにキューを使用する準備ができていません。または、キューにメッセージフローを停止しつつも、クライアントをキューにバインドさせる状況もある可能性があります。このような場合は、キューを無効にすることができます。
以下の例は、ブローカー設定で定義したキューを無効にする方法を示しています。
前提条件
- ブローカー設定でアドレスと関連付けられたキューを定義する方法について理解するようにしてください。詳細は、4章アドレスおよびキューの設定 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 以前に定義したキューには、
enabled
属性を追加します。キューを無効にするには、この属性の値をfalse
に設定します。以下に例を示します。<addresses> <address name="orders"> <multicast> <queue name="orders" enabled="false"/> </multicast> </address> </addresses>
enabled
プロパティーのデフォルト値はtrue
です。値をfalse
に設定すると、メッセージルーティングがキューへ無効になります。
アドレス上のキューを すべて無効にすると、そのアドレスに送信されたすべてのメッセージは警告なしで破棄されます。
4.16. キューに接続するコンシューマーの数の制限
max-consumers
属性を使用して、特定のキューに接続するコンシューマーの数を制限します。max-consumers
フラグを 1
に設定して、排他的コンシューマーを作成します。デフォルト値は -1
で、無制限のコンシューマーを設定します。
以下の手順では、キューに接続できるコンシューマーの数に制限を設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 指定のキューに、
max-consumers
キーを追加し、値を設定します。<configuration ...> <core ...> ... <addresses> <address name="my.address"> <anycast> <queue name="q3" max-consumers="20"/> </anycast> </address> </addresses> </core> </configuration>
上記の設定に基づいて、同時に 20 のコンシューマーのみが
q3
をキューに接続できます。排他的コンシューマーを作成するには、
max-consumers
を1
に設定します。<configuration ...> <core ...> ... <address name="my.address"> <anycast> <queue name="q3" max-consumers="1"/> </anycast> </address> </core> </configuration>
無制限のコンシューマーを許可するには、
max-consumers
を-1
に設定します。<configuration ...> <core ...> ... <address name="my.address"> <anycast> <queue name="q3" max-consumers="-1"/> </anycast> </address> </core> </configuration>
4.17. 排他的キューの設定
排他的キューは、すべてのメッセージを一度に 1 つのコンシューマーにのみルーティングする特別なキューです。この設定は、すべてのメッセージを同じコンシューマーによって順次処理する必要がある場合に便利です。キューに複数のコンシューマーがある場合は、1 つのコンシューマーのみがメッセージを受信します。コンシューマーがキューから切断されると、別のコンシューマーが選択されます。
4.17.1. 排他的キューの個別設定
以下の手順では、特定のキューを個別に排他的に設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 指定されたキューに、
exclusive
キーを追加します。この値はtrue
に設定します。<configuration ...> <core ...> ... <address name="my.address"> <multicast> <queue name="orders1" exclusive="true"/> </multicast> </address> </core> </configuration>
4.17.2. アドレスの排他的キューの設定
以下の手順では、関連するすべてのキューが排他的になるようにアドレスまたは一連のアドレス を設定する方法を説明します。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一致するアドレスの
address-setting
要素にdefault-exclusive-queue
キーを追加します。この値はtrue
に設定します。<address-setting match="myAddress"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting>
上記の設定に基づいて、
myAddress
に関連付けられたすべてのキューは排他的です。デフォルトでは、default-exclusive-queue
の値はfalse
です。アドレスセットに排他的キューを設定するには、アドレスワイルドカードを指定します。以下に例を示します。
<address-setting match="myAddress.*"> <default-exclusive-queue>true</default-exclusive-queue> </address-setting>
関連情報
- アドレスの設定時に使用できるワイルドカード構文についての詳細は、「アドレスセットへのアドレス設定の適用」 を参照してください。
4.18. 一時キューへの特定のアドレス設定の適用
たとえば、JMS を使用する場合、ブローカーはアドレス名とキュー名の両方として汎用一意識別子 (UUID) を割り当て、一時キュー を作成します。
デフォルトの <address-setting match="#">
は、一時的なアドレス設定を含む、設定済みのアドレス設定を すべてのキューに適用します。特定のアドレス設定を一時キューのみに適用する場合は、以下で説明されているように temporary-queue-namespace
をオプションで指定 することができます。次に、namespace に一致するアドレス設定を指定し、ブローカーはそれらの設定をすべての一時キューに適用することができます。
一時キューが作成され、一時キュー namespace が存在する場合、ブローカーは temporary-queue-namespace
値と、設定された区切り文字 (デフォルト .
) をアドレス名に追加します。それを使用して一致するアドレス設定を参照します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 temporary-queue-namespace
値を追加します。以下に例を示します。<temporary-queue-namespace>temp-example</temporary-queue-namespace>
一時キューの namespace に対応する
match
値を使用してaddress-setting
要素を追加します。以下に例を示します。<address-settings> <address-setting match="temp-example.#"> <enable-metrics>false</enable-metrics> </address-setting> </address-settings>
この例では、ブローカーによって作成されるすべての一時キューのメトリックを無効にします。
注記一時的なキュー namespace を指定しても、一時キューには影響を及ぼしません。たとえば、namespace は一時キューの名前を変更しません。namespace は、一時キューを参照するために使用されます。
関連情報
- アドレス設定でワイルドカードを使用する方法は、「アドレスセットへのアドレス設定の適用」 を参照してください。
4.19. リングキューの設定
通常、AMQ Broker のキューは first-in、first-out(FIFO) セマンティクスを使用します。これは、ブローカーがキューの末尾にメッセージを追加し、それらをヘッドから削除することを意味します。リングキューは、指定された数のメッセージを保持する特別なタイプのキューです。ブローカーは、新規メッセージが到達し、キューがすでに指定された数のメッセージを保持した場合にキューの先頭にメッセージを削除することで、固定キューのサイズを維持します。
たとえば、サイズ 3
で設定されたリングキューと、メッセージ A
、B
、C
、および D
を順番に送信するプロデューサーについて考えてみます。メッセージ C
がキューに到達すると、キュー内のメッセージ数が設定済みのリングサイズに達したことになります。この時点で、メッセージ A
はキューのヘッドにあり、メッセージ C
はテイールにあります。メッセージ D
がキューに到達すると、ブローカーはキューの末尾にメッセージを追加します。固定キューサイズを維持するために、ブローカーはキュー (メッセージ A)
の先頭にメッセージを削除します。メッセージ B
がキューの先頭にあるようになりました。
4.19.1. リングキューの設定
以下の手順では、リングキューを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 明示的なリングサイズが設定されていない一致するアドレスですべてのキューのデフォルトリングサイズを定義するには、address-
setting
要素にdefault-ring-size
の値を指定します。以下に例を示します。<address-settings> <address-setting match="ring.#"> <default-ring-size>3</default-ring-size> </address-setting> </address-settings>
default-ring-size
パラメーターは、自動作成されるキューのデフォルトサイズを定義する場合に特に便利です。default-ring-size
のデフォルト値は-1
(サイズ制限なし) です。特定のキューにリングサイズを定義するには、
queue
要素にring-size
キーを追加します。値を指定します。以下に例を示します。<addresses> <address name="myRing"> <anycast> <queue name="myRing" ring-size="5" /> </anycast> </address> </addresses>
ブローカーの実行中に ring-size
の値を更新できます。ブローカーは更新を動的に適用します。新しい ring-size
の値が以前の値よりも小さい場合、ブローカーはキューのヘッドからメッセージをすぐに削除し、新しいサイズを強制しません。キューに送信された新しいメッセージは、古いメッセージの削除を強制的に実行しますが、キューはクライアントによる通常の消費を介して、自然に決まるまで、新しいサイズに到達しません。
4.19.2. リングキューのトラブルシューティング
本セクションでは、リングキューの動作が設定とは異なる状況を説明します。
再配信メッセージおよびロールバック
メッセージがコンシューマーに配信されている場合、メッセージは in-between 状態になります。ここでは、メッセージはキューには技術的には表示されなくなりますが、まだ確認されていません。メッセージは、コンシューマーによって確認されるまで、再配信の状態のままになります。再配信状態のままのメッセージは、リングキューから削除できません。
ブローカーは再配信メッセージを削除できないため、クライアントは許可するリングサイズの設定よりもリングキューにより多くのメッセージを送信できます。たとえば、以下のシナリオについて考えてみましょう。
-
プロデューサーは、
ring-size="3"
で設定したリングキューに 3 つのメッセージを送信します。 すべてのメッセージは即座にコンシューマーにディスパッチされます。
この時点で、
messageCount=
3
およびdeliveryCount
=3
です。プロデューサーは別のメッセージをキューに送信します。その後、メッセージはコンシューマーにディスパッチされます。
現在、
messageCount
=4
およびdeliveryCount
=4
です。4
のメッセージ数は、設定されたリングサイズ3
を超えています。ただし、ブローカーはキューから再配信メッセージを削除できません。現在は、メッセージを承認せずにコンシューマーが閉じられているとします。
この場合、4 つのインポイントで承認されていないメッセージはブローカーにキャンセルされ、消費元の逆順でキューの先頭に追加されます。このアクションにより、設定されたリングサイズにキューが追加されます。リングキューはヘッドでメッセージの末尾にあるメッセージを優先するため、キューは最後のメッセージがキューの先頭に追加されていたため、プロデューサーによって送信された最初のメッセージを破棄します。トランザクションまたはコアセッションのロールバックは同じように処理されます。
コアクライアントを直接使用する場合や、AMQ Core Protocol JMS クライアントを使用する場合は、consumerWindowSize
パラメーターの値 (デフォルトでは 1024 * 1024 バイト) を減らすことで、配信中のメッセージ数を最小限に抑えることができます。
スケジュールされたメッセージ
スケジュールされたメッセージがキューに送信されると、メッセージは通常のメッセージのようにキューの末尾に即座に追加されません。代わりに、ブローカーはスケジュールされたメッセージを中間バッファーに保持し、メッセージの詳細に従ってキューのヘッドへ配信するようにメッセージをスケジュールします。ただし、スケジュールされたメッセージはキューのメッセージ数に反映されます。再配信メッセージの場合のように、この動作により、ブローカーがリングキューのサイズを強制していないことを確認できます。たとえば、以下のシナリオについて考えてみましょう。
12:00 では、プロデューサーはメッセージ
A
をring-size="3"
で設定されたリングキューに送信します。メッセージは 12:05 に対してスケジュールされます。この時点で、
messageCount
=1
およびscheduledCount
=1
になります。12:01 では、プロデューサーはメッセージ
B
を同じリングキューに送信します。現在、
messageCount
=2
およびscheduledCount
=1
。12:02 では、プロデューサーはメッセージ
C
を同じリングキューに送信します。現在、
messageCount
=3
およびscheduledCount
=1
。12:03 時、プロデューサーはメッセージ
D
を同じリングキューに送信します。現在、
messageCount
=4
およびscheduledCount
=1
。キューのメッセージ数は
4
で、設定されたリングサイズから3
よりも大きい ようになりました。ただし、スケジュールされたメッセージはキューでは技術的ではありません (つまり、ブローカーにあり、キューに配置するようにスケジュールされています)。スケジュールされた配信時間 12:05 にすると、ブローカーはメッセージをキューのヘッドに配置します。ただし、リングキューが設定サイズをすでに到達しているため、スケジュールされたメッセージA
はすぐに削除されます。
ページ化されたメッセージ
スケジュールされたメッセージや配信のメッセージと同様に、ページングされたメッセージは、キューレベルではなく、実際にはアドレスレベルでページングされるため、ブローカーによって実施されるリングキューのサイズにはカウントされません。ページ化されたメッセージはキューでは技術的ではありませんが、キューの messageCount
値に反映されます。
リングキューを持つアドレスにはページングを使用しないことが推奨されます。代わりに、アドレス全体をメモリーに収めるようにします。または、 address-full-policy
パラメーターを DROP
、BLOCK
または FAIL
の値に設定します。
関連情報
- ブローカーは、Retroactive アドレスを設定するときにリングキューの内部インスタンスを作成します。詳細は、「Retroactive アドレスの設定」 を参照してください。
4.20. Retroactive アドレスの設定
アドレスを retroactive として設定すると、アドレスに送信されたメッセージを保持することができます。これには、アドレスにキューがバインドされていない場合も含まれます。キューが後に作成され、アドレスにバインドされると、ブローカーはメッセージをこれらのキューにアクティブに配信します。アドレスが retroactive として設定されていない場合や、キューがバインドされていない場合、ブローカーはそのアドレスに送信されたメッセージを破棄します。
Retactive アドレスを設定する場合、ブローカーは ring queue と呼ばれるタイプのキューの内部インスタンスを作成します。リングキューは、指定された数のメッセージを保持する特別なタイプのキューです。キューが指定されたサイズに達すると、キューに到達する次のメッセージがキューから最も古いメッセージを強制的に強制的に実行します。Retroactive アドレスを設定する場合は、内部リングキューのサイズを間接的に指定します。デフォルトでは、内部キューは multicast
ルーティングタイプを使用します。
Retactive アドレスによって使用される内部リングキューは、管理 API 経由で公開されます。メトリックを検査し、キューが空など、その他の一般的な管理操作を実行できます。リングキューは、アドレスの全体的なメモリー使用量にも貢献し、メッセージのページングなどの動作に影響を与えます。
以下の手順では、アドレスを Retroactive として設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 address-setting
要素でretroactive-message-count
パラメーターの値を指定します。指定する値は、ブローカーによって保存されるメッセージの数を定義します。以下に例を示します。<configuration> <core> ... <address-settings> <address-setting match="orders"> <retroactive-message-count>100</retroactive-message-count> </address-setting> </address-settings> ... </core> </configuration>
注記broker.xml
設定ファイルまたは管理 API のいずれかで、ブローカーの実行中にretroactive-message-count
の値を更新できます。ただし、このパラメーターの値を減らす 場合は、Retroactive アドレスがリングキューで実装されるため、追加の手順が必要になります。ring-size
パラメーターが減少するリングキューは、新しいring-size
値を実現するためにキューからメッセージを自動的に削除しません。この動作は、意図しないメッセージ損失に対する安全なものです。この場合、管理 API を使用してリングキュー内のメッセージ数を手動で減らす必要があります。
関連情報
- リングキューの詳細は、「リングキューの設定」 を参照してください。
4.21. 内部管理のアドレスおよびキューのアドバイザリーメッセージの無効化
デフォルトでは、AMQ Broker は、OpenWire クライアントがブローカーに接続されているときにアドレスおよびキューに関するアドバイザリーメッセージを作成します。アドバイザリーメッセージは、ブローカーによって作成される内部で管理されたアドレスに送信されます。これらのアドレスは、ユーザーがデプロイされたアドレスおよびキューと同じ表示内の AMQ 管理コンソールに表示されます。有用な情報が提供されますが、ブローカーによって多数の宛先を管理する場合に、アドバイザリーメッセージにより不要な結果が生じる可能性があります。たとえば、メッセージはメモリー使用量やステンケーション接続リソースを増やす可能性があります。また、アドバイザリーメッセージを送信するために作成されたすべてのアドレスを表示しようとすると、AMQ 管理コンソールが明確になる可能性があります。このような状況を回避するには、以下のパラメーターを使用して、ブローカーでアドバイザリーメッセージの動作を設定できます。
supportAdvisory
-
アドバイザリーメッセージの作成を有効にするには、このオプションを
true
false
に設定します。デフォルト値はtrue
です。 suppressInternalManagementObjects
-
このオプションを
true
に設定して、アドバイザリーメッセージを JMX レジストリーや AMQ 管理コンソールなどの管理サービスに公開し、false
に設定して公開しないようにします。デフォルト値はtrue
です。
以下の手順では、ブローカーでアドバイザリーメッセージを無効にする方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 OpenWire コネクターの場合は、
supportAdvisory
パラメーターおよびsuppressInternalManagementObjects
パラメーターを設定済みの URL に追加します。本セクションで説明されているように値を設定します。以下に例を示します。<acceptor name="artemis">tcp://127.0.0.1:61616?protocols=CORE,AMQP,OPENWIRE;supportAdvisory=false;suppressInternalManagementObjects=false</acceptor>
4.22. アドレスおよびキューのフェデレーション
フェデレーションにより、ブローカーを共通のクラスターに入れることなく、ブローカー間のメッセージの転送が可能になります。ブローカーはスタンドアロンまたは個別のクラスターになります。さらに、ソースおよびターゲットブローカーはさまざまな管理ドメインに配置できます。つまり、ブローカーには異なる設定、ユーザー、およびセキュリティー設定を指定できます。ブローカーは、異なるバージョンの AMQ Broker を使用している場合もあります。
たとえば、フェデレーションは、メッセージをあるクラスターから別のクラスターへ確実に送信するのに適しています。この送信は、大規模なエリアネットワーク (WAN)、クラウドインフラストラクチャーの リージョン、またはインターネット上である可能性があります。ソースブローカーからターゲットブローカーへの接続が失われた場合 (ネットワーク障害などの理由により)、ソースブローカーはターゲットブローカーがオンラインに戻るまで接続を再確立しようとします。ターゲットブローカーがオンラインに戻ると、メッセージ送信が再開します。
管理者は、アドレスポリシーおよびキューポリシーを使用してフェデレーションを管理できます。ポリシー設定は特定のアドレスまたはキューに一致させることができます。また、ポリシーには、アドレスまたは キューのセットに対して設定に一致するワイルドカード式を含めることができます。そのため、フェデレーションは、一致するセットからキューまたはアドレスが追加されるか、削除されるため、動的に適用できます。ポリシーには、特定のアドレスやキューを含む、または除外する 複数の式を含めることができます。さらに、複数のポリシーをブローカーまたはブローカークラスターに適用できます。
AMQ Broker では、2 つの主なフェデレーションオプションは アドレスフェデレーション と キューフェデレーションです。これらのオプションは、これ以降のセクションで説明します。
ブローカーには、フェデレーションされたコンポーネントおよびローカルのみのコンポーネントの設定を含めることができます。つまり、ブローカーでフェデレーションを設定する場合は、そのブローカーですべてをフェデレーションする必要はありません。
4.22.1. アドレスフェデレーションについて
アドレスのフェデレーションは、接続されたブローカー間の完全なマルチキャスト分散パターンと似ています。たとえば、BrokerA
のアドレスに送信されたすべてのメッセージは、そのブローカーのすべてのキューに送信されます。さらに、各メッセージは BrokerB
および割り当てられたすべてのキューに配信されます。
アドレスフェデレーションは、ブローカーを動的にリモートブローカーのアドレスにリンクします。たとえば、ローカルブローカーがリモートブローカーのアドレスからメッセージをフェッチする場合は、リモートアドレスにキューが自動的に作成されます。その後、リモートブローカーのメッセージはこのキューによって使用されます。最後に、メッセージは最初にローカルアドレスに直接公開されていましたが、メッセージはローカルブローカーの対応するアドレスにコピーされます。
フェデレーションがアドレスを作成できるように、リモートブローカーを再設定する必要はありません。ただし、ローカルブローカーには リモートアドレスに対するパーミッションを付与する必要があります。
4.22.2. アドレスフェデレーションの一般的なトポロジー
アドレスフェデレーションを使用する一般的なトポロジーの一部を以下に示します。
- 対称トポロジー
対称トポロジーでは、プロデューサーとコンシューマーは各ブローカーに接続されます。キューとそのコンシューマーは、いずれかのプロデューサーによって公開されるメッセージを受信できます。対称トポロジーの例を以下に示します。
図4.1 対称トポロジーにおけるアドレスフェデレーション
対称トポロジーのアドレスフェデレーションを設定する場合は、アドレスポリシーの
max-hops
プロパティーの値を1
に設定することが重要です。これにより、メッセージが 1 回だけ コピーされ、cyclic レプリケーションは回避されます。このプロパティーを大きな値に設定すると、コンシューマーは同じメッセージの複数のコピーを受け取ります。- 完全なメッシュトポロジー
完全なメッシュトポロジーは対称設定と似ています。3 つ以上のブローカーは相互に対称的に分散し、完全なメッシュを作成します。この設定では、プロデューサーとコンシューマーは各ブローカーに接続されます。キューとそのコンシューマーは任意のプロデューサーによって公開されるメッセージを受信できます。このトポロジーの例を以下に示します。
図4.2 完全なメッシュトポロジーにおけるアドレスフェデレーション
対称設定の場合、完全なメッシュトポロジーのアドレスフェデレーションを設定する場合は、アドレスポリシーの
max-hops
プロパティーの値を1
に設定することが重要です。これにより、メッセージが 1 回だけ コピーされ、cyclic レプリケーションは回避されます。- リングトポロジー
ブローカーのリングでは、各フェデレーションされたアドレスは、リング内の 1 つだけに対してアップストリームになります。このトポロジーの例を以下に示します。
図4.3 リングトポロジーにおけるアドレスフェデレーション
リングトポロジーのフェデレーションを設定する場合は、循環レプリケーションを回避するために、アドレスポリシーの
max-hops
プロパティーをn-1
の値に設定することが重要です。ここで、nはリング内のノード数になります。たとえば、上記のリングトポロジーでは、max-hops
の値は5
に設定されます。これにより、リング内のすべてのアドレスがメッセージが 1 度だけ 見えるようになります。リングトポロジーの利点は、必要な物理接続の数において、チャイルがセットアップすることです。ただし、このタイプのトポロジーの欠点は、1 つのブローカーが失敗した場合にリング全体が失敗することです。
- fan-out トポロジー
ファンアウトトポロジーでは、単一のマスターアドレスはフェデレーションされたアドレスのツリーによってリンクされます。マスターアドレスに公開されたすべてのメッセージは、ツリー内の任意のブローカーに接続しているすべてのコンシューマーによって受信できます。ツリーは、深さに設定できます。ツリー内に既存のブローカーを再設定しなくても、ツリーを拡張することもできます。このトポロジーの例を以下に示します。
図4.4 ファンアウトトポロジーでのアドレスフェデレーション
ファンアウトトポロジーのフェデレーションを設定する場合は、アドレスポリシーの
max-hops
プロパティーをn-1
の値に設定します。ここで、n ツリー内のレベル数になります。たとえば、上記の fan-out トポロジーでは、max-hops
の値は2
に設定されます。これにより、ツリー内のすべてのアドレスがメッセージが 1 度だけ 見えるようになります。
4.22.3. アドレスフェデレーション設定での迂回バインディングのサポート
アドレスフェデレーションを設定する際に、アドレスポリシー設定に迂回バインディングのサポートを追加できます。このサポートを追加すると、フェデレーションが迂回バインディングに応答し、リモートブローカーの指定のアドレスのフェデレーションされたコンシューマーを作成できます。
たとえば、test.federation.source
というアドレスがアドレスポリシーに含まれ、test.federation.target
という別のアドレスが含まれていない場合は、通常、キューが test.federation.target
に作成されると、アドレスポリシーの一部ではないため、フェデレーションされたコンシューマーが作成されません。ただし、test.federation.source がソースアドレスで
test.federation.target
が転送アドレスに、永続コンシューマーを作成すると、転送アドレスに永続コンシューマーが作成されます。ソースアドレスは引き続き multicast
ルーティングタイプを使用する必要がありますが、ターゲットアドレスは multicast
または anycast
を使用できます。
ユースケースの例は、JMS トピック (multicast
アドレス) を JMS キュー (anycast
アドレス) にリダイレクトする迂回です。これにより、JMS 2.0 および共有サブスクリプションをサポートしないレガシーコンシューマーのトピックへのメッセージの負荷分散が可能になります。
4.22.4. ブローカークラスターのフェデレーションの設定
以下のセクションの例では、standaloneローカルブローカーとリモートブローカーとの間でアドレスとキューのフェデレーションを設定する方法について示しています。スタンドアロンブローカー間のフェデレーションの場合、フェデレーション設定の名前、およびアドレスおよびキューポリシー名はローカルブローカーとリモートブローカー間で一意である必要があります。
ただし、clusterでブローカーのフェデレーションを設定する場合は、追加の要件があります。クラスター化されたブローカーでは、フェデレーション設定の名前と、その設定内のアドレスおよびキューポリシーの名前 が、クラスター内の各ブローカーで同じである必要があります。
同じクラスターのブローカーが同じフェデレーション設定およびアドレスおよびキューポリシー名を使用するようにし、メッセージの重複を回避します。たとえば、同じクラスター内のブローカーに異なるフェデレーション設定名がある場合、複数の方法で名前が異なる転送キューが作成される場合があり、ダウンストリームのコンシューマーでメッセージの重複が生じます。一方、同じクラスターのブローカーが同じフェデレーション設定名を使用する場合、基本的にはダウンストリームのコンシューマーに負荷分散される複製された、クラスター転送キューを作成します。これにより、メッセージの重複が回避されます。
4.22.5. アップストリームのアドレスフェデレーションの設定
以下の例は、スタンドアロンブローカー間でアップストリームのアドレスフェデレーションを設定する方法を示しています。この例では、ローカル (つまりダウンストリーム) ブローカーから一部のリモート (つまりアップストリーム) ブローカーへのフェデレーションを設定します。
前提条件
- 以下の例は、スタンドアロンブローカー間でアドレスフェデレーションを設定する方法を示しています。ただし、ブローカー クラスター のフェデレーションを設定するための要件も理解している必要があります。詳細は、「ブローカークラスターのフェデレーションの設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <federation>
要素が含まれる新しい<federations >
要素を追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
name
- フェデレーション設定の名前。この例では、名前はローカルブローカーの名前に対応します。
user
- アップストリームブローカーに接続するための共有ユーザー名。
password
- アップストリームブローカーに接続するための共有パスワード。
注記ユーザーとパスワードの認証情報がリモートブローカーごとに異なる場合は、設定に追加する時にこれらのブローカーの認証情報を個別に指定できます。これは、この手順の後半で説明します。
federation
要素内に<address-policy>
要素を追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer"> </address-policy> </federation> </federations>
name
- アドレスポリシーの名前。ブローカーに設定されるアドレスポリシーはすべて一意の名前を指定する必要があります。
auto-delete
-
アドレスのフェデレーション時に、ローカルブローカーはリモートアドレスに永続キューを動的に作成します。
auto-delete
プロパティーの値は、ローカルブローカーの切断後にリモートキューを削除するかどうかを指定します。また、auto-delete-delay
およびauto- delete-message-count
プロパティーの値も到達するかどうかを指定します。動的に作成されたキューのクリーンアップを自動化する場合に便利なオプションです。また、ローカルブローカーが長時間切断されている場合に、リモートブローカーでメッセージをビルドできないようにする場合にも便利なオプションです。ただし、接続されていない間にメッセージをローカルブローカーに対して常にキューに入れる必要がある場合、このオプションをfalse
に設定します。これにより、ローカルブローカーでメッセージが失われないようにします。 auto-delete-delay
- ローカルブローカーが切断されると、このプロパティーの値は、動的に作成されるリモートキューが自動的に削除されるまでの時間 (ミリ秒単位) を指定します。
auto-delete-message-count
- ローカルブローカーが切断されると、このプロパティーの値は、キューが自動的に削除される前に動的に作成されたリモートキューにあるメッセージの最大数を指定します。
enable-divert-bindings
-
このプロパティーを
true
に設定すると、迂回バインディングは必要に応じてリッスンできます。アドレスポリシーに含まれるアドレスに一致するアドレスを持つ迂回バインディングがある場合、迂回の転送アドレスに一致するキューバインディングは要求を作成します。デフォルト値はfalse
です。 max-hops
- フェデレーション中にメッセージが実行できるホップの最大数。特定のトポロジーでは、このプロパティーに特定の値が必要です。これらの要件の詳細は、「アドレスフェデレーションの一般的なトポロジー」 を参照してください。
transformer-ref
- トランスフォーマー設定の名前。フェデレーションされたメッセージ送信時にメッセージを変換したい場合は、トランスフォーマー設定を追加することができます。トランスフォーマー設定は、この手順の後半で説明します。
<address-policy>
要素内に、アドレスポリシーからアドレスを追加し、アドレスを除外するためのアドレス一致パターンを追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> </federation> </federations>
include
-
この要素の
address-match
プロパティーの値は、アドレスポリシーに含めるアドレスを指定します。queue.bbc.new
やqueue.usatoday
など、正確なアドレスを指定できます。または、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、アドレスポリシーには文字列queue.news
で始まるすべての アドレス名も含まれています。 exclude
-
この要素の
address-match
プロパティーの値は、アドレスポリシーから除外するアドレスを指定します。正確なアドレス名を指定するか、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、アドレスポリシーは文字列queue.news.sport
で始まるすべてのアドレス名を除外します。
(任意)
federation
要素 では、transformer
要素を追加してカスタムトランスフォーマー実装を参照します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> </federations>
name
-
トランスフォーマー設定の名前。この名前は、ローカルブローカーで一意である必要があります。これは、アドレスポリシーの
transformer-ref
プロパティーの値として指定する名前です。 class-name
org.apache.activemq.artemis.core.server.transformer.Transformer
インターフェイスを実装するユーザー定義クラスの名前。トランスフォーマーの
transform()
メソッドは、メッセージが送信される前にメッセージで呼び出されます。これにより、メッセージヘッダーまたはボディーをフェデレーションする前に変換できます。プロパティー
- 特定のトランスフォーマー設定のキーと値のペアを保持するために使用されます。
federation
要素内に、upstream
要素を 1 つ以上追加します。各upstream
要素は、リモートブローカーへの接続と、その接続に適用するポリシーを定義します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <upstream name="eu-east-1"> <static-connectors> <connector-ref>eu-east-connector1</connector-ref> </static-connectors> <policy ref="news-address-federation"/> </upstream> <upstream name="eu-west-1" > <static-connectors> <connector-ref>eu-west-connector1</connector-ref> </static-connectors> <policy ref="news-address-federation"/> </upstream> <address-policy name="news-address-federation" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" enable-divert-bindings="false" max-hops="1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> </federations>
static-connectors
-
ローカルブローカーの
broker.xml
設定ファイルの他の場所で定義されるconnector
要素を参照するconnector-ref
要素のリストが含まれます。コネクターは、送信接続に使用するトランスポート (TCP、SSL、HTTP など) およびサーバー接続パラメーター (ホスト、ポートなど) を定義します。この手順の次のステップは、static-connectors
要素で参照されるコネクターを追加する方法を示しています。 policy-ref
- アップストリームブローカーに適用されるダウンストリームブローカーに設定されたアドレスポリシーの名前。
アップストリーム
要素に指定できる追加オプションを以下に示します。name
-
アップストリームブローカー設定の名前。この例では、名前は
eu-east-1
とeu-west-1
というアップストリームブローカーに対応します。 user
-
アップストリームブローカーへの接続の作成時に使用するユーザー名。指定のない場合は、
federation
要素の設定に指定された共有ユーザー名が使用されます。 password
-
アップストリームブローカーへの接続の作成時に使用するパスワード。指定のない場合は、
federation
要素の設定に指定された共有パスワードが使用されます。 call-failover-timeout
-
call-timeout
と同様ですが、フェイルオーバーの試行中に呼び出しが行われる場合に使用されます。デフォルト値は-1
で、タイムアウトが無効であることを意味します。 call-timeout
-
ブロック呼び出しであるパケットを送信すると、フェデレーション接続がリモートブローカーからの応答を待つ時間 (ミリ秒単位)。この時間が経過すると、接続によって例外が発生します。デフォルト値は
30000
です。 check-period
-
フェデレーション接続の健常性を確認するために、ローカルブローカがリモートブローカに送信する連続した“keep-alive"メッセージ間の期間 (ミリ秒)。フェデレーション接続が正常である場合、リモートブローカーは各キープアライブメッセージに応答します。接続が正常でないと、ダウンストリームブローカーがアップストリームブローカーから応答を受信できない場合に、サーキットブレーカー と呼ばれるメカニズムを使用してフェデレーションされたコンシューマーをブロックします。詳細は、
circuit-breaker-timeout
パラメーターの説明を参照してください。check-period
パラメーターのデフォルト値は30000
です。 circuit-breaker-timeout
- ダウンストリームとアップストリームブローカー間の単一の接続は、多くのフェデレーションされたキューとアドレスコンシューマーによって共有される可能性があります。ブローカー間の接続が失われた場合、フェデレーションされた各コンシューマーは同時に再接続を試みる可能性があります。これを回避するには、サーキットブレーカー と呼ばれるメカニズムはコンシューマーをブロックします。指定したタイムアウト値が経過すると、サーキットブレーカーは接続を再送します。成功すると、コンシューマーはブロックされません。それ以外の場合は、サーキットブレーカーが再度適用されます。
connection-ttl
-
リモートブローカーからのメッセージを受信しなくなった場合に、フェデレーション接続が存続する時間 (ミリ秒単位)。デフォルト値は
60000
です。 discovery-group-ref
-
アップストリームブローカーへの接続に静的コネクターを定義する代わりに、この要素を使用して
broker.xml
設定ファイルの別の場所で設定済みの検出グループを指定できます。具体的には、この要素のdiscovery-group-name
プロパティーの値として、既存の検出グループを指定します。検出グループの詳細は、「ブローカー検出メソッド」 を参照してください。 ha
-
アップストリームブローカーへの接続に対して、高可用性が有効であるかどうかを指定します。このパラメーターの値を
true
に設定すると、ローカルブローカーはアップストリームクラスターで利用可能なブローカーに接続でき、ライブアップストリームブローカーがシャットダウンすると、バックアップブローカーに自動フェイルオーバーされます。デフォルト値はfalse
です。 initial-connect-attempts
-
ダウンストリームブローカーがアップストリームブローカーに接続するようにする初期試行の数。接続を確立せずにこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は
-1
で、制限がないことを意味します。 max-retry-interval
-
リモートブローカーへの接続に失敗した場合に後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は
2000
です。 reconnect-attempts
-
接続が失敗した場合に、ダウンストリームブローカーがアップストリームブローカーへの再接続を試行する回数。接続が再確立されていない状態でこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は
-1
で、制限がないことを意味します。 retry-interval
-
リモートブローカーへの接続に失敗した場合に、後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は
500
です。 retry-interval-multiplier
-
retry-interval
パラメーターの値に適用される乗率。デフォルト値は1
です。 share-connection
-
同じブローカーにダウンストリーム接続とアップストリーム接続の両方が設定されている場合には、ダウンストリーム設定とアップストリーム設定の両方がこのパラメーターの値を
true
に設定している限り、同じ接続が共有されます。デフォルト値はfalse
です。
ローカルブローカーで、コネクターをリモートブローカーに追加します。これらは、フェデレーションされたアドレス設定の
static-connectors
要素で参照されるコネクターです。以下に例を示します。<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>
4.22.6. ダウンストリームアドレスフェデレーションの設定
以下の例は、スタンドアロンブローカーにダウンストリームアドレスフェデレーションを設定する方法を示しています。
ダウンストリームアドレスのフェデレーションにより、1 つ以上のリモートブローカーがローカルブローカーに接続するために使用するローカルブローカーに設定を追加できます。このアプローチの利点は、すべてのフェデレーション設定を単一のブローカーに維持できることです。これは、たとえば hub-and-spoke トポロジーに役立ちます。
ダウンストリームアドレスのフェデレーションは、フェデレーション接続の方向対アップストリームアドレス設定の方向を逆にします。したがって、リモートブローカーを設定に追加する際に、ダウンストリーム ブローカーとみなされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカルブローカーに接続し、アップストリームとみなされるようになりました。この例は、この後、リモートブローカーの設定を追加する際に説明します。
前提条件
- アップストリームアドレスフェデレーションの設定を理解している。「アップストリームのアドレスフェデレーションの設定」を参照してください。
- 以下の例は、スタンドアロンブローカー間でアドレスフェデレーションを設定する方法を示しています。ただし、ブローカー クラスター のフェデレーションを設定するための要件も理解している必要があります。詳細は、「ブローカークラスターのフェデレーションの設定」 を参照してください。
手順
-
ローカルブローカーで、
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <federation>
要素が含まれる<federations >
要素を追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
アドレスポリシー設定を追加します。以下に例を示します。
<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> </federation> ... </federations>
送信前にメッセージを変換する場合は、トランスフォーマー設定を追加します。以下に例を示します。
<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> ... </federations>
各リモートブローカーに
ダウンストリーム
要素を追加します。以下に例を示します。<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <downstream name="eu-east-1"> <static-connectors> <connector-ref>eu-east-connector1</connector-ref> </static-connectors> <upstream-connector-ref>netty-connector</upstream-connector-ref> <policy ref="news-address-federation"/> </downstream> <downstream name="eu-west-1" > <static-connectors> <connector-ref>eu-west-connector1</connector-ref> </static-connectors> <upstream-connector-ref>netty-connector</upstream-connector-ref> <policy ref="news-address-federation"/> </downstream> <address-policy name="news-address-federation" max-hops="1" auto-delete="true" auto-delete-delay="300000" auto-delete-message-count="-1" transformer-ref="news-transformer"> <include address-match="queue.bbc.new" /> <include address-match="queue.usatoday" /> <include address-match="queue.news.#" /> <exclude address-match="queue.news.sport.#" /> </address-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> ... </federations>
上記の設定で示されているように、リモートブローカーはローカルブローカーのダウンストリームであると見なされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカル (アップストリーム) ブローカーへ再度接続します。
ローカルブローカーで、ローカルブローカーおよびリモートブローカーによって使用されるコネクターとアクセプターを追加して、フェデレーション接続を確立します。以下に例を示します。
<connectors> <connector name="netty-connector">tcp://localhost:61616</connector> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors> <acceptors> <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor> </acceptors>
connector name="netty-connector"
- ローカルブローカーがリモートブローカーに送信するコネクター設定。リモートブローカーはこの設定を使用してローカルブローカーに接続し直します。
connector name="eu-west-1-connector"
,connector name="eu-east-1-connector"
- リモートブローカーへのコネクター。ローカルブローカーはこれらのコネクターを使用してリモートブローカーに接続し、リモートブローカーがローカルブローカーに接続するために必要な設定を共有します。
acceptor name="netty-acceptor"
- ローカルブローカーに接続するためにリモートブローカーによって使用されるコネクターに対応するローカルブローカーのアクセプター。
4.22.7. キューフェデレーションについて
キューフェデレーションは、他のリモートブローカー全体でローカルブローカーの単一キューの負荷を分散する方法を提供します。
負荷分散を実現するため、ローカルブローカーはローカルコンシューマーからのメッセージの要求を満たすために、リモートキューからメッセージを取得します。以下に例を示します。
図4.5 対称キューフェデレーション
リモートキューを再設定する必要はありません。同じブローカーまたは同じクラスター内に配置する必要はありません。リモートリンクおよびフェデレーションされたキューの作成に必要なすべての設定はローカルブローカーにあります。
4.22.7.1. キューフェデレーションの利点
以下は、キューのフェデレーションの設定を選択する理由です。
- 容量の増加
- キューフェデレーションは、多くのブローカーに分散される論理キューを作成できます。この論理分散キューは、単一のブローカーにある 1 つのキューよりもはるかに高い容量を持ちます。この設定では、最初に公開されていたブローカーから消費できるメッセージがいくつでも消費されます。システムは、負荷分散が必要な場合にのみ、フェデレーション中のメッセージを移動します。
- マルチリージョン設定のデプロイ
マルチリージョン設定では、メッセージプロデューサーが 1 つのリージョンまたは venue にあり、コンシューマーが別のリージョンにある可能性があります。ただし、プロデューサーとコンシューマー接続を指定のリージョンに対してローカルに維持することが理想的です。この場合、プロデューサーとコンシューマーが存在する各リージョンにブローカーをデプロイし、キューフェデレーションを使用して、リージョン間での Wide Area Network(WAN) でメッセージを移動できます。以下に例を示します。
図4.6 マルチリージョンキューフェデレーション
- 安全なエンタープライズ LAN と DMZ 間の通信
ネットワークセキュリティーでは、demilitarized zone (DMZ) は物理または論理のサブネットワークで、企業の外部向けサービスを含み、信頼できない外部向けのサービス (通常はインターネットなど、信頼されていない、より大規模なネットワーク) に公開します。その他の企業のローカルエリアネットワーク (LAN) は、ファイアウォールの背後でこの外部ネットワークから分離されます。
セキュアなエンタープライズ LAN の多くのメッセージプロデューサーが DMZ と多数のコンシューマーにある場合、プロデューサーが安全なエンタープライズ LAN のブローカーに接続できないことがあります。この場合、プロデューサーがメッセージを公開できる DMZ にブローカーをデプロイできます。その後、エンタープライズ LAN のブローカーは DMZ のブローカーに接続し、フェデレーションされたキューを使用して DMZ のブローカーからメッセージを受信します。
4.22.8. アップストリームキューフェデレーションの設定
以下の例は、スタンドアロンブローカーにアップストリームのキューフェデレーションを設定する方法を示しています。この例では、ローカル (つまりダウンストリーム) ブローカーから一部のリモート (つまりアップストリーム) ブローカーへのフェデレーションを設定します。
前提条件
- 以下の例は、スタンドアロンブローカー間でキューフェデレーションを設定する方法を示しています。ただし、ブローカー クラスター のフェデレーションを設定するための要件も理解している必要があります。詳細は、「ブローカークラスターのフェデレーションの設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 新しい
<federations>
要素に、<federation>
要素を追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
name
- フェデレーション設定の名前。この例では、名前はダウンストリームブローカーの名前に対応します。
user
- アップストリームブローカーに接続するための共有ユーザー名。
password
- アップストリームブローカーに接続するための共有パスワード。
注記- ユーザーとパスワードの認証情報がアップストリームブローカーごとに異なる場合は、設定に追加する時にこれらのブローカーの認証情報を個別に指定できます。これは、この手順の後半で説明します。
federation
要素内に<queue-policy>
要素を追加します。<queue-policy>
要素のプロパティー値を指定します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer"> </queue-policy> </federation> </federations>
name
- キューポリシーの名前。ブローカーに設定されるキューポリシーはすべて一意の名前である必要があります。
include-federated
このプロパティーの値を
false
に設定すると、設定は、すでにフェデレーションされたコンシューマー (つまりフェデレーションされたキューのコンシューマー) は統合しなおされません。これにより、対称または閉ループトポロジーで、フェデレーションされていないコンシューマーが存在せず、メッセージがシステム内を無限に流れる状況を回避できます。閉ループトポロジーが ない 場合は、このプロパティーの値を
true
に設定できます。たとえば、3 つのブローカー、BrokerA
、BrokerB
、およびBrokerC
のチェーンがあり、プロデューサーがBrokerA
のコンシューマーとBrokerC
のコンシューマーがあるとします。この場合、BrokerB
が コンシューマーをBrokerA
にフェデレーションしなおす必要があります。priority-adjustment
-
コンシューマーがキューに接続すると、その優先度は、アップストリーム (フェデレーションされた) コンシューマーの作成時に優先順位が使用されます。フェデレーションされたコンシューマーの優先度は、
priority-adjustment
プロパティーの値で調整します。このプロパティーのデフォルト値は-1
です。これにより、負荷分散時にローカルコンシューマーがフェデレーションされたコンシューマーよりも優先されます。ただし、必要に応じて優先順位の調整の値を変更できます。
ローカルコンシューマーに優先順位が与えられているにもかかわらず、フェでレーテッドコンシューマーが、フェデレーションコンシューマーに移動するメッセージが多すぎる速度でメッセージを消費する場合は、フェデレーテッドコンシューマーがメッセージを消費する速度を制限できます。メッセージ消費のレートを制限するには、フェデレーションコンシューマーのクライアント接続 URI で ConsumerMaxRate
フロー制御オプションを設定します。詳細は、AMQ コアプロトコル JMS クライアント ドキュメントに記載のフロー制御オプションを参照してください。
transformer-ref
トランスフォーマー設定の名前。フェデレーションされたメッセージ送信時にメッセージを変換したい場合は、トランスフォーマー設定を追加することができます。トランスフォーマー設定は、この手順の後半で説明します。
<queue-policy>
要素内に、キューポリシーからアドレスを追加し、除外する address-matching パターンを追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> </federation> </federations>
include
この要素の
address-match
プロパティーの値は、キューポリシーに含めるアドレスを指定します。queue.bbc.new
やqueue.usatoday
など、正確なアドレスを指定できます。または、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、アドレスポリシーには文字列queue.news
で始まるすべてのアドレス名も含まれています。address-match
プロパティーと組み合わせて、queue-match
プロパティーを使用して、キューポリシーにこれらのアドレスに特定のキューを含めることができます。address-match
プロパティーと同様に、正確なキュー名を指定するか、ワイルドカード式を使用して一連のキューを指定できます。上記の例では、番号記号 (#
) のワイルドカード文字は、各アドレスまたはアドレスセットにある すべて のキューがキューポリシーに含まれることを示しています。exclude
この要素の
address-match
プロパティーの値は、キューポリシーから除外するアドレスを指定します。正確なアドレスを指定するか、ワイルドカード式を使用して一致するアドレスの セット を指定できます。上記の例では、数字記号 (#
) ワイルドカード文字は、全 アドレスのqueue-match
プロパティーと一致するキューがすべて除外されることを意味します。この場合、.local
という文字列で終了するキューは除外されます。これは、特定のキューがローカルキューとして保持され、フェデレーションされていないことを示しています。federation
要素 では、transformer
要素を追加してカスタムトランスフォーマー実装を参照します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> </federations>
name
-
トランスフォーマー設定の名前。この名前は、対象となるブローカーで一意でなければなりません。この名前は、アドレスポリシーの
transformer-ref
プロパティーの値として指定します。 class-name
org.apache.activemq.artemis.core.server.transformer.Transformer
インターフェイスを実装するユーザー定義クラスの名前。トランスフォーマーの
transform()
メソッドは、メッセージが送信される前にメッセージで呼び出されます。これにより、メッセージヘッダーまたはボディーをフェデレーションする前に変換できます。プロパティー
特定のトランスフォーマー設定のキーと値のペアを保持するために使用されます。
federation
要素内に、upstream
要素を 1 つ以上追加します。各upstream
要素は、アップストリームブローカー接続と、その接続に適用するポリシーを定義します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <upstream name="eu-east-1"> <static-connectors> <connector-ref>eu-east-connector1</connector-ref> </static-connectors> <policy ref="news-queue-federation"/> </upstream> <upstream name="eu-west-1" > <static-connectors> <connector-ref>eu-west-connector1</connector-ref> </static-connectors> <policy ref="news-queue-federation"/> </upstream> <queue-policy name="news-queue-federation" include-federated="true" priority-adjustment="-5" transformer-ref="news-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> </federations>
static-connectors
-
ローカルブローカーの
broker.xml
設定ファイルの他の場所で定義されるconnector
要素を参照するconnector-ref
要素のリストが含まれます。コネクターは、送信接続に使用するトランスポート (TCP、SSL、HTTP など) およびサーバー接続パラメーター (ホスト、ポートなど) を定義します。以下の手順は、フェデレーションされたキュー設定のstatic-connectors
要素で参照されるコネクターを追加する方法を示しています。 policy-ref
- アップストリームブローカーに適用されるダウンストリームブローカーに設定されたキューポリシーの名前。
アップストリーム
要素に指定できる追加オプションを以下に示します。
name
-
アップストリームブローカー設定の名前。この例では、名前は
eu-east-1
とeu-west-1
というアップストリームブローカーに対応します。 user
-
アップストリームブローカーへの接続の作成時に使用するユーザー名。指定のない場合は、
federation
要素の設定に指定された共有ユーザー名が使用されます。 password
-
アップストリームブローカーへの接続の作成時に使用するパスワード。指定のない場合は、
federation
要素の設定に指定された共有パスワードが使用されます。 call-failover-timeout
-
call-timeout
と同様ですが、フェイルオーバーの試行中に呼び出しが行われる場合に使用されます。デフォルト値は-1
で、タイムアウトが無効であることを意味します。 call-timeout
-
ブロック呼び出しであるパケットを送信すると、フェデレーション接続がリモートブローカーからの応答を待つ時間 (ミリ秒単位)。この時間が経過すると、接続によって例外が発生します。デフォルト値は
30000
です。 check-period
-
フェデレーション接続の健常性を確認するために、ローカルブローカがリモートブローカに送信する連続した“keep-alive"メッセージ間の期間 (ミリ秒)。フェデレーション接続が正常である場合、リモートブローカーは各キープアライブメッセージに応答します。接続が正常でないと、ダウンストリームブローカーがアップストリームブローカーから応答を受信できない場合に、サーキットブレーカー と呼ばれるメカニズムを使用してフェデレーションされたコンシューマーをブロックします。詳細は、
circuit-breaker-timeout
パラメーターの説明を参照してください。check-period
パラメーターのデフォルト値は30000
です。 circuit-breaker-timeout
- ダウンストリームとアップストリームブローカー間の単一の接続は、多くのフェデレーションされたキューとアドレスコンシューマーによって共有される可能性があります。ブローカー間の接続が失われた場合、フェデレーションされた各コンシューマーは同時に再接続を試みる可能性があります。これを回避するには、サーキットブレーカー と呼ばれるメカニズムはコンシューマーをブロックします。指定したタイムアウト値が経過すると、サーキットブレーカーは接続を再送します。成功すると、コンシューマーはブロックされません。それ以外の場合は、サーキットブレーカーが再度適用されます。
connection-ttl
-
リモートブローカーからのメッセージを受信しなくなった場合に、フェデレーション接続が存続する時間 (ミリ秒単位)。デフォルト値は
60000
です。 discovery-group-ref
-
アップストリームブローカーへの接続に静的コネクターを定義する代わりに、この要素を使用して
broker.xml
設定ファイルの別の場所で設定済みの検出グループを指定できます。具体的には、この要素のdiscovery-group-name
プロパティーの値として、既存の検出グループを指定します。検出グループの詳細は、「ブローカー検出メソッド」 を参照してください。 ha
-
アップストリームブローカーへの接続に対して、高可用性が有効であるかどうかを指定します。このパラメーターの値を
true
に設定すると、ローカルブローカーはアップストリームクラスターで利用可能なブローカーに接続でき、ライブアップストリームブローカーがシャットダウンすると、バックアップブローカーに自動フェイルオーバーされます。デフォルト値はfalse
です。 initial-connect-attempts
-
ダウンストリームブローカーがアップストリームブローカーに接続するようにする初期試行の数。接続を確立せずにこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は
-1
で、制限がないことを意味します。 max-retry-interval
-
リモートブローカーへの接続に失敗した場合に後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は
2000
です。 reconnect-attempts
-
接続が失敗した場合に、ダウンストリームブローカーがアップストリームブローカーへの再接続を試行する回数。接続が再確立されていない状態でこの値に達すると、アップストリームブローカーは永続的にオフラインとみなされます。ダウンストリームブローカーは、メッセージをアップストリームブローカーにルーティングしなくなりました。デフォルト値は
-1
で、制限がないことを意味します。 retry-interval
-
リモートブローカーへの接続に失敗した場合に、後続の再接続試行の間隔 (ミリ秒単位)。デフォルト値は
500
です。 retry-interval-multiplier
-
retry-interval
パラメーターの値に適用される乗率。デフォルト値は1
です。 share-connection
同じブローカーにダウンストリーム接続とアップストリーム接続の両方が設定されている場合には、ダウンストリーム設定とアップストリーム設定の両方がこのパラメーターの値を
true
に設定している限り、同じ接続が共有されます。デフォルト値はfalse
です。ローカルブローカーで、コネクターをリモートブローカーに追加します。これらは、フェデレーションされたアドレス設定の
static-connectors
要素で参照されるコネクターです。以下に例を示します。<connectors> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors>
4.22.9. ダウンストリームキューフェデレーションの設定
以下の例は、ダウンストリームキューフェデレーションを設定する方法を示しています。
ダウンストリームキューのフェデレーションにより、1 つ以上のリモートブローカーがローカルブローカーに接続するために使用するローカルブローカーに設定を追加できます。このアプローチの利点は、すべてのフェデレーション設定を単一のブローカーに維持できることです。これは、たとえば hub-and-spoke トポロジーに役立ちます。
ダウンストリームキューのフェデレーションは、フェデレーション接続の方向対アップストリームキュー設定の方向を逆にします。したがって、リモートブローカーを設定に追加する際に、ダウンストリーム ブローカーとみなされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカルブローカーに接続し、アップストリームとみなされるようになりました。この例は、この後、リモートブローカーの設定を追加する際に説明します。
前提条件
- アップストリームキューフェデレーションの設定を理解する必要があります。「アップストリームキューフェデレーションの設定」 を参照してください。
- 以下の例は、スタンドアロンブローカー間でキューフェデレーションを設定する方法を示しています。ただし、ブローカー クラスター のフェデレーションを設定するための要件も理解している必要があります。詳細は、「ブローカークラスターのフェデレーションの設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <federation>
要素が含まれる<federations >
要素を追加します。以下に例を示します。<federations> <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> </federation> </federations>
キューポリシー設定を追加します。以下に例を示します。
<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> </federation> ... </federations>
送信前にメッセージを変換する場合は、トランスフォーマー設定を追加します。以下に例を示します。
<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="news-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> ... </federations>
各リモートブローカーに
ダウンストリーム
要素を追加します。以下に例を示します。<federations> ... <federation name="eu-north-1" user="federation_username" password="32a10275cf4ab4e9"> <downstream name="eu-east-1"> <static-connectors> <connector-ref>eu-east-connector1</connector-ref> </static-connectors> <upstream-connector-ref>netty-connector</upstream-connector-ref> <policy ref="news-address-federation"/> </downstream> <downstream name="eu-west-1" > <static-connectors> <connector-ref>eu-west-connector1</connector-ref> </static-connectors> <upstream-connector-ref>netty-connector</upstream-connector-ref> <policy ref="news-address-federation"/> </downstream> <queue-policy name="news-queue-federation" priority-adjustment="-5" include-federated="true" transformer-ref="new-transformer"> <include queue-match="#" address-match="queue.bbc.new" /> <include queue-match="#" address-match="queue.usatoday" /> <include queue-match="#" address-match="queue.news.#" /> <exclude queue-match="#.local" address-match="#" /> </queue-policy> <transformer name="news-transformer"> <class-name>org.myorg.NewsTransformer</class-name> <property key="key1" value="value1"/> <property key="key2" value="value2"/> </transformer> </federation> ... </federations>
上記の設定で示されているように、リモートブローカーはローカルブローカーのダウンストリームであると見なされます。ダウンストリームブローカーは、設定の接続情報を使用して、ローカル (アップストリーム) ブローカーへ再度接続します。
ローカルブローカーで、ローカルブローカーおよびリモートブローカーによって使用されるコネクターとアクセプターを追加して、フェデレーション接続を確立します。以下に例を示します。
<connectors> <connector name="netty-connector">tcp://localhost:61616</connector> <connector name="eu-west-1-connector">tcp://localhost:61616</connector> <connector name="eu-east-1-connector">tcp://localhost:61617</connector> </connectors> <acceptors> <acceptor name="netty-acceptor">tcp://localhost:61616</acceptor> </acceptors>
connector name="netty-connector"
- ローカルブローカーがリモートブローカーに送信するコネクター設定。リモートブローカーはこの設定を使用してローカルブローカーに接続し直します。
connector name="eu-west-1-connector"
,connector name="eu-east-1-connector"
- リモートブローカーへのコネクター。ローカルブローカーはこれらのコネクターを使用してリモートブローカーに接続し、リモートブローカーがローカルブローカーに接続するために必要な設定を共有します。
acceptor name="netty-acceptor"
- ローカルブローカーに接続するためにリモートブローカーによって使用されるコネクターに対応するローカルブローカーのアクセプター。
第5章 ブローカーのセキュリティー保護
5.1. 接続のセキュリティー保護
ブローカーがメッセージングクライアントに接続されている場合や、ブローカーが他のブローカーに接続されている場合は、Transport Layer Security(TLS) を使用してこれらの接続をセキュア化できます。
使用できる TLS 設定は 2 つあります。
- 一方向 TLS。証明書を表示するブローカーのみが表示されます。これが最も一般的な設定です。
- ブローカーとクライアント (または他のブローカー) の両方が証明書を提示する双方向 (または 相互)TLS。
5.1.1. 一方向 TLS の設定
以下の手順は、一方向 TLS に特定のアクセプターを設定する方法を示しています。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 特定のアクセプターでは、
sslEnabled
キーを追加し、値をtrue
に設定します。さらに、keyStorePath
キーおよびkeyStorePassword
キーを追加します。ブローカーキーストアに対応する値を設定します。以下に例を示します。<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!</acceptor>
5.1.2. 双方向 TLS の設定
以下の手順では、双方向 TLS を設定する方法を説明します。
前提条件
- 一方向 TLS に対して、指定のアクセプターを設定しておく必要があります。詳細は、「一方向 TLS の設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一方向 TLS 用に以前に設定したアクセプターの場合は、
needClientAuth
キーを追加します。この値はtrue
に設定します。以下に例を示します。<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true</acceptor>
前述の手順の設定は、クライアントの証明書が信頼できるプロバイダーによって署名されていることを前提としています。クライアントの証明書が信頼されるプロバイダー (自己署名の場合など) で署名されて いない 場合には、ブローカーはクライアントの証明書をトラストストアにインポートする必要があります。この場合は、
trustStorePath
キーおよびtrustStorePassword
キーを追加します。ブローカーのトラストストアに対応する値を設定します。以下に例を示します。<acceptor name="artemis">tcp://0.0.0.0:61616?sslEnabled=true;keyStorePath=../etc/broker.keystore;keyStorePassword=1234!;needClientAuth=true;trustStorePath=../etc/client.truststore;trustStorePassword=5678!</acceptor>
AMQ Broker は複数のプロトコルをサポートし、各プロトコルとプラットフォームには TLS パラメーターを指定する方法が異なります。ただし、コアプロトコル (ブリッジ) を使用するクライアントの場合、TLS パラメーターはブローカーのアクセプターと同様にコネクター URL に設定されます。
自己署名証明書が Java 仮想マシン (JVM) トラストストア内に信頼できる証明書としてリストされている場合、JVM は証明書の有効期限を検証しません。実稼働環境では、Red Hat は認証局によって署名された証明書を使用することを推奨します。
5.1.3. TLS 設定オプション
以下の表は、利用可能なすべての TLS 設定オプションを示しています。
オプション | 備考 |
---|---|
|
接続に対して SSL を有効にするかどうかを指定します。TLS を有効にするには |
| アクセプターで使用される場合: ブローカー証明書を保持するブローカーの TLS キーストアへのパス (自己署名または認証局による署名のいずれか)。
コネクターで使用される場合: クライアント証明書を保持するクライアントの TLS キーストアへのパス。これは、双方向の TLS を使用している場合にのみ、コネクターに関係します。この値はブローカーに設定できますが、ダウンロードされ、クライアントによって使用されます。クライアントがブローカーに設定されたものとは異なるパスを使用する必要がある場合は、標準の |
| アクセプターで使用される場合: ブローカーのキーストアのパスワード。
コネクターで使用される場合: クライアントのキーストアのパスワード。これは、双方向の TLS を使用している場合にのみ、コネクターに関係します。この値はブローカーに設定できますが、ダウンロードされ、クライアントによって使用されます。クライアントがブローカーに設定されたものとは異なるパスワードを使用する必要がある場合は、標準の |
| アクセプターで使用される場合: ブローカーが信頼するすべてのクライアントのキーを保持するブローカーの TLS トラストストアへのパス。これは、双方向の TLS を使用している場合にのみ、アクセプターに関係します。
コネクターで使用される場合: クライアントが信頼するすべてのブローカーの公開鍵を保持するクライアントの TLS トラストストアへのパス。この値はブローカーに設定できますが、ダウンロードされ、クライアントによって使用されます。クライアントでサーバーの設定と異なるパスを使用する必要がある場合は、標準の |
| アクセプターで使用される場合: ブローカーのトラストストアのパスワード。これは、双方向の TLS を使用している場合にのみ、アクセプターに関係します。
コネクターで使用される場合: クライアントのトラストストアのパスワード。この値はブローカーに設定できますが、ダウンロードされ、クライアントによって使用されます。クライアントがブローカーに設定されたものとは異なるパスワードを使用する必要がある場合は、標準の |
| アクセプターまたはコネクターの両方の TLS 通信に使用される暗号スイートのコンマ区切りリスト。
クライアントアプリケーションでサポートする最も安全な暗号スイートを指定します。コンマ区切りのリストを使用して、ブローカーとクライアントの両方に共通の暗号スイートのセットを指定する場合、または暗号スイートを指定しない場合には、ブローカーとクライアントは、使用する暗号スイートについて相互に交渉します。どの暗号スイートを指定すればよいかわからない場合は、まずクライアントをデバッグモードで実行してブローカーとクライアント間の接続を確立し、ブローカーとクライアントの両方に共通する暗号スイートを確認します。次に、ブローカーで
利用可能な暗号スイートは、ブローカーとクライアントによって使用される TLS プロトコルバージョンによって異なります。ブローカーをアップグレードした後にデフォルトの TLS プロトコルバージョンが変更された場合は、ブローカーとクライアントが共通の暗号スイートを使用できるようにするために、以前の TLS プロトコルバージョンを選択する必要がある場合があります。詳細は、 |
| アクセプターまたはコネクターで使用されるかに関係なく、TLS 通信に使用されるプロトコルのコンマ区切りリストになります。TLS プロトコルのバージョンを指定しない場合、ブローカーは JVM のデフォルトバージョンを使用します。
ブローカーが JVM のデフォルトの TLS プロトコルバージョンを使用しており、ブローカーのアップグレード後にそのバージョンが変更された場合、ブローカーとクライアントが使用する TLS プロトコルバージョンに互換性がない可能性があります。新しい TLS プロトコルバージョンを使用することを推奨しますが、新しい TLS プロトコルバージョンをサポートしていないクライアントと相互運用するために、 |
|
このプロパティーはアクセプター専用です。これは、双方向 TLS が必要であるアクセプターに接続するクライアントに指示します。有効な値は |
5.2. クライアントの認証
5.2.1. クライアント認証方法
ブローカーにクライアント認証を設定するには、以下の方法を使用できます。
- ユーザー名とパスワードベースの認証
以下のオプションのいずれかを使用して、ユーザーの認証情報を直接検証します。
- ブローカーにローカルに保存されるプロパティーファイルのセットに対して認証情報を確認します。また、ブローカーへのアクセスを限定して、ログインモジュールを組み合わせてより複雑なユースケースをサポートする ゲスト アカウントを設定することもできます。
- 中央の X.500 ディレクトリーサーバーに保存されているユーザーデータに対してクライアントクレデンシャルを確認するように、LDAP (Lightweight Directory Access Protocol) ログインモジュールを設定します。
- 証明書ベースの認証
- 双方向 Transport Layer Security (TLS) を設定して、ブローカーとクライアントの両方が相互認証の証明書を提示するようにします。管理者は、承認されたクライアントユーザーおよびロールを定義するプロパティーファイルも設定する必要があります。これらのプロパティーファイルはブローカーに保存されます。
- Kerberos ベースの認証
- Simple Authentication and Security Layer (SASL) フレームワークから GSSAPI メカニズムを使用し、クライアントの Kerberos セキュリティー認証情報を認証するようにブローカーを設定します。
次のセクションでは、ユーザーとパスワードと証明書ベースの認証の両方を設定する方法を説明します。
関連情報
LDAP および Kerberos の完全な認証 および 承認ワークフローの詳細は、以下を参照してください。
5.2.2. プロパティーファイルに基づくユーザーおよびパスワード認証の設定
AMQ Broker は、アドレスに基づいてキューにセキュリティーを適用するための柔軟なロールベースのセキュリティーモデルをサポートします。キューは、1 対 1(ポイントツーポイントメッセージングの場合) または多対 1(パブリッシュ/サブスクライブメッセージング用) のいずれかのアドレスにバインドされます。メッセージがアドレスに送信されると、ブローカーはそのアドレスにバインドされたキューのセットを検索し、メッセージをそのキューのセットにルーティングします。
基本的なユーザーとパスワード認証が必要な場合は、PropertiesLoginModule
を使用して定義します。このログインモジュールは、ブローカーにローカルに保存される以下の設定ファイルに対してユーザーの認証情報をチェックします。
artemis-users.properties
- ユーザーおよび対応するパスワードの定義に使用
artemis-roles.properties
- ロールを定義し、ユーザーをそれらのロールに割り当てるのに使用します。
login.config
- ユーザーおよびパスワード認証、およびゲストアクセス用のログインモジュールの設定に使用
artemis-users.properties
ファイルには、セキュリティーを確保するために、ハッシュ化されたパスワードを含めることができます。
以下のセクションでは、設定方法を説明します。
5.2.2.1. 基本的なユーザーとパスワード認証の設定
以下の手順は、基本的なユーザーとパスワード認証を設定する方法を説明します。
手順
<broker_instance_dir>/etc/login.config
設定ファイルを開きます。デフォルトでは、新しい AMQ Broker 7.11 インスタンスのこのファイルには次の行が含まれます。activemq { org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient debug=false reload=true org.apache.activemq.jaas.properties.user="artemis-users.properties" org.apache.activemq.jaas.properties.role="artemis-roles.properties"; };
activemq
- 設定のエイリアス。
org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule
- 実装クラス。
sufficient
PropertiesLoginModule
に必要とされる成功レベルを指定するフラグ。設定可能な値は次のとおりです。-
必須
: ログインモジュールが正常に実行される必要があります。認証は、成功または失敗に関係なく、指定のエイリアスで設定されたログインモジュールのリストの実行をそのまま継続します。 -
必須
: ログインモジュールが正常に実行される必要があります。失敗により、即座に制御がアプリケーションに返されます。認証は、指定のエイリアス下で設定されたログインモジュールのリストを実行しません。 -
sufficient
: ログインモジュールは正常に実行される必要はありません。成功した場合には、制御がアプリケーションに返り、認証はこれ以上続行しません。認証に失敗すると、認証試行により、指定のエイリアス下で設定されたログインモジュールのリストが続行されます。 -
オプション
: ログインモジュールは正常に実行される必要はありません。認証は、成功または失敗に関係なく、指定のエイリアスで設定されたログインモジュールのリストを継続します。
-
org.apache.activemq.jaas.properties.user
- ログインモジュール実装のユーザーとパスワードのセットを定義するプロパティーファイルを指定します。
org.apache.activemq.jaas.properties.role
- ユーザーをログインモジュール実装に定義されたロールにマップするプロパティーファイルを指定します。
-
<broker_instance_dir>/etc/artemis-users.properties
設定ファイルを開きます。 ユーザーを追加して、ユーザーにパスワードを割り当てます。以下に例を示します。
user1=secret user2=access user3=myPassword
-
<broker_instance_dir>/etc/artemis-roles.properties
設定ファイルを開きます。 artemis-users.properties
ファイルに追加したユーザーにロール名を割り当てます。以下に例を示します。admin=user1,user2 developer=user3
-
<broker_instance_dir>\etc\bootstrap.xml
設定ファイルを開きます。 必要に応じて、以下のようにセキュリティードメインエイリアス (このインスタンスでは activemq) をファイルに追加します。
<jaas-security domain="activemq"/>
5.2.2.2. ゲストアクセスの設定
ログイン認証情報がないユーザーや、認証情報が認証に失敗するユーザーの場合は、ゲストアカウントを使用してブローカーへの制限されたアクセスを付与できます。
コマンドラインの切り替えを使用して --allow-anonymous
(--require-login
の逆)、ゲストアクセスを有効にし、ブローカーインスタンスを作成できます。
以下の手順は、ゲストアクセスを設定する方法を説明します。
前提条件
- この手順では、基本的なユーザーとパスワード認証がすでに設定されていることを前提としています。詳細は、「基本的なユーザーとパスワード認証の設定」 を参照してください。
手順
-
基本的なユーザーとパスワード認証用に指定した
<broker_instance_dir>/etc/login.config
設定ファイルを開きます。 以前追加したプロパティーログインモジュール設定の後に、ゲストログインモジュール設定を追加します。以下に例を示します。
activemq { org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient debug=true org.apache.activemq.jaas.properties.user="artemis-users.properties" org.apache.activemq.jaas.properties.role="artemis-roles.properties"; org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient debug=true org.apache.activemq.jaas.guest.user="guest" org.apache.activemq.jaas.guest.role="restricted"; };
org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule
- 実装クラス。
org.apache.activemq.jaas.guest.user
- 匿名ユーザーに割り当てられたユーザー名。
org.apache.activemq.jaas.guest.role
- 匿名ユーザーに割り当てられたロール。
上記の設定に基づいて、ユーザーが認証情報を提供すると、ユーザーとパスワード認証モジュールがアクティブになります。ユーザーが認証情報を提供しない場合や、指定した認証情報が正しくない場合は、ゲスト認証がアクティブになります。
5.2.2.2.1. ゲストアクセスの例
以下の例は、認証情報がないユーザーだけがゲストとしてログインしているユースケースに対するゲストアクセスの設定を示しています。この例では、ログインモジュールの順序が以前の設定手順と照合されていることを確認します。また、プロパティーログインモジュールに割り当てられるフラグは requisite
に変更されています。
activemq { org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient debug=true credentialsInvalidate=true org.apache.activemq.jaas.guest.user="guest" org.apache.activemq.jaas.guest.role="guests"; org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite debug=true org.apache.activemq.jaas.properties.user="artemis-users.properties" org.apache.activemq.jaas.properties.role="artemis-roles.properties"; };
前述の設定に基づいて、ログイン認証情報が指定されていない場合は、ゲスト認証モジュールがアクティベートされます。
このユースケースでは、ゲストログインモジュールの設定で credentialsInvalidate
オプションを true
に設定する必要があります。
プロパティーログインモジュールは、認証情報が提供されているとアクティベートされます。クレデンシャルが有効である必要があります。
関連情報
-
Java Authentication and Authorization Service (JAAS) の詳細は、Java ベンダーのドキュメントを参照してください。たとえば、
login.config
の設定に関する Oracle のチュートリアルは、Oracle Java ドキュメントの JAAS Login Configuration File を参照してください。 - クライアントクレデンシャルを検証するように LDAP ログインモジュールを設定する方法は、「クライアント認証用の LDAP の設定」 を参照してください。
- 設定ファイルでパスワードを暗号化する方法は、「設定ファイルでのパスワードの暗号化」 を参照してください。
5.2.3. 証明書ベースの認証の設定
Java Authentication and Authorization Service (JAAS) 証明書ログインモジュールは、Transport Layer Security(TLS) を使用するクライアントの認証および承認を処理します。モジュールを使用するには、双方向の Transport Layer Security (TLS) の使用と、独自の証明書でクライアントを設定する必要があります。認証は、JAAS 証明書ログインモジュールから直接ではなく、TLS ハンドシェイク中に実行されます。
証明書ログインモジュールのロールは、以下のとおりです。
- 許可されるユーザーのセットを制限します。関連するプロパティーファイルに明示的にリスト表示されるユーザーの 識別名 (DN) のみが認証の対象となります。
- グループのリストを受信したユーザー ID に関連付けます。これにより、認証が容易になります。
- 受信クライアント証明書が必要です (デフォルトでは、TLS レイヤーは、クライアント証明書の存在をオプションとして扱うように設定されています)。
証明書ログインモジュールは、フラットテキストファイルのペアに証明書 DN のコレクションを保存します。このファイルは、ユーザー名とグループ ID のリストを各 DN に関連付けます。
証明書ログインモジュールは、org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
クラスで実装されます。
5.2.3.1. 証明書ベースの認証を使用するブローカーの設定
以下の手順では、証明書ベースの認証を使用するようにブローカーを設定する方法を説明します。
前提条件
- 双方向 Transport Layer Security(TLS) を使用するようにブローカーを設定している。詳細は、「双方向 TLS の設定」 を参照してください。
手順
以前ブローカーキーストアにインポートされたユーザー証明書からサブジェクト 識別名 (DN) を取得します。
キーストアファイルから一時ファイルに証明書をエクスポートします。以下に例を示します。
keytool -export -file <file_name> -alias broker-localhost -keystore broker.ks -storepass <password>
エクスポートされた証明書の内容を出力します。
keytool -printcert -file <file_name>
出力は以下のようになります。
Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Issuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Serial number: 4537c82e Valid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007 Certificate fingerprints: MD5: 3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37 SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C
Owner
エントリーは Subject DN です。Subject DN の入力の使用形式はプラットフォームによって異なります。上記の文字列は、以下のように表現することもできます。Owner: `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`
証明書ベースの認証を設定します。
<broker_instance_dir>/etc/login.config
設定ファイルを開きます。証明書ログインモジュールを追加し、ユーザーとロールのプロパティーファイルを参照します。以下に例を示します。activemq { org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule debug=true org.apache.activemq.jaas.textfiledn.user="artemis-users.properties" org.apache.activemq.jaas.textfiledn.role="artemis-roles.properties"; };
org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
- 実装クラス。
org.apache.activemq.jaas.textfiledn.user
- ログインモジュール実装のユーザーとパスワードのセットを定義するプロパティーファイルを指定します。
org.apache.activemq.jaas.textfiledn.role
- ユーザーをログインモジュール実装に定義されたロールにマップするプロパティーファイルを指定します。
<broker_instance_dir>/etc/artemis-users.properties
設定ファイルを開きます。ユーザーおよび対応する DN はこのファイルで定義されます。以下に例を示します。system=CN=system,O=Progress,C=US user=CN=humble user,O=Progress,C=US guest=CN=anon,O=Progress,C=DE
前述の設定に基づいて、
system
という名前のユーザーはCN=system,O=Progress,C=US
Subject DN にマッピングされます。<broker_instance_dir>/etc/artemis-roles.properties
設定ファイルを開きます。利用可能なロールと、それらのロールを保持しているユーザーは、このファイルで定義されています。以下に例を示します。admins=system users=system,user guests=guest
上記の設定では、
users
ロールに対して、複数のユーザーをコンマ区切りリストとしてリスト表示します。以下に示すように、セキュリティードメインエイリアス (このインスタンスでは activemq) が
bootstrap.xml
で参照されていることを確認します。<jaas-security domain="activemq"/>
5.2.3.2. AMQP クライアントの証明書ベースの認証の設定
Simple Authentication and Security Layer (SASL) EXTERNAL メカニズム設定パラメーターを使用して、ブローカーへの接続時に証明書ベースの認証用に AQMP クライアントを設定します。
ブローカーは、証明書の認証と同じ方法で、AMQP クライアントの Transport Layer Security (TLS)/Secure Sockets Layer (SSL) 証明書を認証します。
- ブローカーはクライアントの TLS/SSL 証明書を読み取り、証明書のサブジェクトからアイデンティティーを取得します。
- 証明書サブジェクトは、証明書ログインモジュールによってブローカー ID にマッピングされます。その後、ブローカーはロールを基にしてユーザーを承認します。
以下の手順では、AMQP クライアントに証明書ベースの認証を設定する方法を説明します。AMQP クライアントが証明書ベースの認証を使用できるようにするには、クライアントがブローカーへの接続に使用する URI に設定パラメーターを追加する必要があります。
前提条件
以下を設定している必要があります。
- 双方向 TLS詳細は、「双方向 TLS の設定」 を参照してください。
- 証明書ベースの認証を使用するブローカー。詳細は、「証明書ベースの認証を使用するブローカーの設定」 を参照してください。
手順
編集する URI が含まれるリソースを開きます。
amqps://localhost:5500
sslEnabled=true
パラメーターを追加して、接続の TSL/SSL を有効にします。amqps://localhost:5500?sslEnabled=true
クライアントトラストストアおよびキーストアに関連するパラメーターを追加して、ブローカーで TSL/SSL 証明書の交換を有効にします。
amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>
パラメーター
saslMechanisms=EXTERNAL
を追加し、TSL/SSL 証明書で見つかったアイデンティティーを使用してブローカーがクライアントを認証するよう要求します。amqps://localhost:5500?sslEnabled=true&trustStorePath=<trust_store_path>&trustStorePassword=<trust_store_password>&keyStorePath=<key_store_path>&keyStorePassword=<key_store_password>&saslMechanisms=EXTERNAL
関連情報
- AMQ Broker での証明書ベースの認証に関する詳細は、「証明書ベースの認証を使用するブローカーの設定」 を参照してください。
- AMQP クライアントの設定に関する詳細は、クライアント固有の製品ドキュメントについて Red Hat カスタマーポータル を参照してください。
5.3. クライアントの承認
5.3.1. クライアント承認方法
アドレスおよびキューの作成および削除、およびメッセージの送受信などのブローカーで操作を実行するためのクライアントを承認するには、以下の方法を使用できます。
- ユーザーおよびロールベースの承認
- 認証されたユーザーおよびロールのブローカーセキュリティー設定を設定します。
- クライアントを認証するように LDAP を設定
- 認証と承認の両方を処理するよう Lightweight Directory Access Protocol (LDAP) ログインモジュールを設定します。LDAP ログインモジュールは、中央の X.500 ディレクトリーサーバーに保存されているユーザーデータに対して受信認証情報をチェックし、ユーザーロールに基づいてパーミッションを設定します。
- クライアントを認証するように Kerberos を設定する
-
PropertiesLoginModule
に認証情報を渡す Java Authentication and Authorization Service (JAAS)Krb5LoginModule
ログインモジュール または AMQ Broker ロールに Keroberos 認証ユーザーをマッピングするLDAPLoginModule
ログインモジュールを設定します。
5.3.2. ユーザーおよびロールベースの承認の設定
5.3.2.1. パーミッションの設定
パーミッションは、broker.xml
設定ファイルの <security-setting>
要素でキュー (アドレスに基づく) に対して定義されます。設定ファイルの <security-settings>
要素に <security-setting>
のインスタンスを複数定義できます。アドレス完全一致を指定するか、数字記号 (#
) およびアスタリスク (*
) ワイルドカード文字を使用したワイルドカードの一致を定義できます。
アドレスに一致するキューのセットに異なるパーミッションを指定できます。これらのパーミッションを以下の表に示します。
ユーザーによるアクセス許可 | 以下のパラメーター... |
---|---|
アドレスの作成 |
|
アドレスの削除 |
|
一致するアドレスの永続キューの作成 |
|
一致するアドレスの永続キューの削除 |
|
一致するアドレスの非永続キューの作成 |
|
一致するアドレスの非永続キューの削除 |
|
一致するアドレスへのメッセージの送信 |
|
一致するアドレスにバインドされたキューからのメッセージの消費 |
|
管理アドレスに管理メッセージを送信して管理操作を呼び出します。 |
|
一致するアドレスにバインドされるキューの参照 |
|
パーミッションごとに、パーミッションを付与されたロールのリストを指定します。指定のユーザーにロールがある場合は、そのアドレスセットのパーミッションが付与されます。
次のセクションでは、パーミッションの設定例を示します。
5.3.2.1.1. 単一アドレス向けメッセージ実稼働の設定
以下の手順では、単一のアドレスに対してメッセージの実稼働パーミッションを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <security-settings>
要素内に単一の<security-setting>
要素を追加します。match
キーには、アドレスを指定します。以下に例を示します。<security-settings> <security-setting match="my.destination"> <permission type="send" roles="producer"/> </security-setting> </security-settings>
上記の設定に基づいて、
producer
ロールのメンバーにはアドレスmy.destination
の送信
パーミッションが割り当てられています。
5.3.2.1.2. 単一アドレスのメッセージ消費の設定
以下の手順では、単一のアドレスに対してメッセージ消費パーミッションを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <security-settings>
要素内に単一の<security-setting>
要素を追加します。match
キーには、アドレスを指定します。以下に例を示します。<security-settings> <security-setting match="my.destination"> <permission type="consume" roles="consumer"/> </security-setting> </security-settings>
上記の設定に基づいて、
consumer
ロールのメンバーには、アドレスmy.destination
のconsume
パーミッションが割り当てられています。
5.3.2.1.3. すべてのアドレスでの完全なアクセスの設定
以下の手順では、すべてのアドレスおよび関連するキューへの完全アクセスを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <security-settings>
要素内に単一の<security-setting>
要素を追加します。match
キーの場合は、全 アドレスへのアクセスを設定するには、番号記号 (#
) ワイルドカード文字を指定します。以下に例を示します。<security-settings> <security-setting match="#"> <permission type="createDurableQueue" roles="guest"/> <permission type="deleteDurableQueue" roles="guest"/> <permission type="createNonDurableQueue" roles="guest"/> <permission type="deleteNonDurableQueue" roles="guest"/> <permission type="createAddress" roles="guest"/> <permission type="deleteAddress" roles="guest"/> <permission type="send" roles="guest"/> <permission type="browse" roles="guest"/> <permission type="consume" roles="guest"/> <permission type="manage" roles="guest"/> </security-setting> </security-settings>
上記の設定に基づいて、すべてのキューの guest ロールのメンバーに、全パーミッションが付与されます。これは、すべてのユーザーに
guest
ロールを割り当てるように匿名認証を設定する開発のシナリオで役に立ちます。
関連情報
- より複雑なユースケースを設定する方法は、「複数のセキュリティー設定の設定」 を参照してください。
5.3.2.1.4. 複数のセキュリティー設定の設定
以下の手順の例は、一致するアドレスセットに複数のセキュリティー設定を個別に設定する方法を示しています。ここでは、本セクションの上記の例とは対照的で、すべて のアドレスに 全 アクセスを付与する方法を説明します。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 <security-settings>
要素内に単一の<security-setting>
要素を追加します。match
キーの場合は、一致するアドレス セット に設定を適用する番号記号 (#
) ワイルドカード文字を含めます。以下に例を示します。<security-setting match="globalqueues.europe.#"> <permission type="createDurableQueue" roles="admin"/> <permission type="deleteDurableQueue" roles="admin"/> <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/> <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/> <permission type="send" roles="admin, europe-users"/> <permission type="consume" roles="admin, europe-users"/> </security-setting>
match=globalqueues.europe.#
-
番号記号 (
#
) ワイルドカード文字は、ブローカーによって任意のシーケンスの単語として解釈されます。単語はピリオド (.
) で区切られています。この例では、セキュリティー設定は、文字列 globalqueues.europe で始まるアドレスに適用されます。 permission type="createDurableQueue"
-
admin
ロールが割り当てられたユーザーのみが、文字列 globalqueues.europe で始まるアドレスにバインドされた永続キューを作成したり、削除したりできます。 permission type="createNonDurableQueue"
-
admin
ロール、guest
、またはeurope-users
ロールが割り当てられたユーザーは、文字列 globalqueues.europe で始まるアドレスにバインドされた一時キューを作成したり、削除したりできます。 permission type="send"
-
admin
ロールまたはeurope-users
ロールが割り当てられたユーザーは、文字列 globalqueues.europe で始まるアドレスにバインドされたキューにメッセージを送信できます。 permission type="consume"
-
admin
ロールまたはeurope-users
ロールが割り当てられたユーザーは、文字列 globalqueues.europe で始まるアドレスにバインドされたキューからメッセージを消費できます。
(オプション) 異なるセキュリティー設定をアドレスのより限定的なセットに適用するには、別の
<security-setting>
要素を追加します。match
キーには、より具体的なテキスト文字列を指定します。以下に例を示します。<security-setting match="globalqueues.europe.orders.#"> <permission type="send" roles="europe-users"/> <permission type="consume" roles="europe-users"/> </security-setting>
2 つ目の
security-setting
要素では、globalqueues.europe.orders.#
の照合は、最初のsecurity-setting
要素で指定したglobalqueues.europe.#
照合に比べると、具体的です。globalqueues.europe.orders.#
に一致するアドレスの場合には、createDurableQueue
、deleteDurableQueue
、createNonDurableQueue
、deleteNonDurableQueue
はファイルの最初のsecurity-setting
要素から継承され ません。たとえば、globalqueues.europe.orders.plastics
アドレスの場合には、存在するパーミッションは、ロールeurope-users
のsend
とconsume
のみです。したがって、ある
security-setting
ブロックで指定されたパーミッションは、別のブロックに継承されないため、これらのアクセス許可を指定しないだけで、より詳細なsecurity-setting
ブロックのパーミッションを効果的に拒否できます。
5.3.2.1.5. ユーザーでのキューの設定
キューが自動的に作成されると、キューには接続クライアントのユーザー名が割り当てられます。このユーザー名は、キューのメタデータとして含まれます。名前は JMX および AMQ Broker 管理コンソールで公開されます。
以下の手順では、ブローカー設定で手動で定義したキューにユーザー名を追加する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 指定のキューに、
ユーザー
キーを追加します。値を割り当てます。以下に例を示します。<address name="ExampleQueue"> <anycast> <queue name="ExampleQueue" user="admin"/> </anycast> </address>
上記の設定に基づいて、
admin
ユーザーはキューExampleQueue
に割り当てられます。
- キューでユーザーを設定しても、そのキューのセキュリティーセマンティクスは変更されません。これはそのキューのメタデータにのみ使用されます。
ユーザー間のマッピングと、ユーザーに割り当てられたロールのマッピングは、セキュリティーマネージャー と呼ばれるコンポーネントによって処理されます。セキュリティーマネージャーは、ブローカーに保存されているプロパティーファイルからユーザーの認証情報を読み取ります。デフォルトでは、AMQ Broker は
org.apache.activemq.artemis.spi.core.security.ActiveMQJAASSecurityManager
セキュリティーマネージャーを使用します。このデフォルトのセキュリティーマネージャーは、JAAS および Red Hat JBoss Enterprise Application Platform(JBoss EAP) のセキュリティーとの統合を提供します。カスタム セキュリティーマネージャーの使用方法は、「カスタムセキュリティーマネージャーの指定」 を参照してください。
5.3.2.2. ロールベースアクセス制御の設定
ロールベースアクセス制御 (RBAC) は、MBean の属性およびメソッドへのアクセス制限すに使用されます。RBAC を使用すると、管理者はロールに基づいて Web コンソール、管理インターフェイス、コアメッセージなどの全ユーザーに正しいレベルのアクセスを付与できます。
5.3.2.2.1. ロールベースのアクセス設定
以下の手順の例は、ロールを特定の MBean とその属性およびメソッドにマッピングする方法を示しています。
前提条件
- 最初にユーザーとロールを定義する必要があります。詳細は、「基本的なユーザーとパスワード認証の設定」 を参照してください。
手順
-
<broker_instance_dir>/etc/management.xml
設定ファイルを開きます。 role-access
要素を検索し、設定を編集します。以下に例を示します。<role-access> <match domain="org.apache.activemq.artemis"> <access method="list*" roles="view,update,amq"/> <access method="get*" roles="view,update,amq"/> <access method="is*" roles="view,update,amq"/> <access method="set*" roles="update,amq"/> <access method="*" roles="amq"/> </match> </role-access>
-
この場合、ドメイン名が
org.apache.activemq.apache
の MBean 属性を照合検索します。 -
一致する MBean 属性に対する
view
、update
、またはamq
ロールへのアクセスは、ロールを追加するlist*
、get*
、set*
、is*
、および*
アクセスメソッドによって制御されます。method = "*"
(ワイルドカード) 構文は、設定にリストされていない他の前メソッドをすべて指定する方法として使用されます。設定の各アクセスメソッドが MBean メソッド呼び出しに変換されます。 -
呼び出された MBean メソッドは、設定に記載されているメソッドと照合されます。たとえば、ドメインが
org.apache.activemq.artemis
の MBean でlistMessages
というメソッドを呼び出すと、ブローカーはlist
メソッドの設定で定義されたロールと、アクセスの照合を行います。 MBean の完全なメソッド名を使用してアクセスを設定することもできます。以下に例を示します。
<access method="listMessages" roles="view,update,amq"/>
-
この場合、ドメイン名が
ブローカーを起動または再起動します。
-
Linux の場合:
<broker_instance_dir>/bin/artemis run
-
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
-
Linux の場合:
MBean プロパティーに一致する key
属性を追加して、ドメイン内の特定の MBean を照合することもできます。
5.3.2.2.2. ロールベースのアクセスの例
本セクションでは、ロールベースのアクセス制御を適用する以下の例を説明します。
以下の例は、key
属性を使用して、指定したドメインのすべてのキューにロールをマッピングする方法を示しています。
<match domain="org.apache.activemq.artemis" key="subcomponent=queues"> <access method="list*" roles="view,update,amq"/> <access method="get*" roles="view,update,amq"/> <access method="is*" roles="view,update,amq"/> <access method="set*" roles="update,amq"/> <access method="*" roles="amq"/> </match>
以下の例は、key
属性を使用して、特定の名前付きキューにロールをマッピングする方法を示しています。この例では、名前付きキューは exampleQueue
です。
<match domain="org.apache.activemq.artemis" key="queue=exampleQueue"> <access method="list*" roles="view,update,amq"/> <access method="get*" roles="view,update,amq"/> <access method="is*" roles="view,update,amq"/> <access method="set*" roles="update,amq"/> <access method="*" roles="amq"/> </match>
以下の例は、指定した接頭辞が含まれるすべてのキューにロールをマップする方法を示しています。この例では、アスタリスク (*
) のワイルドカード演算子を使用して、接頭辞 example で始まるすべてのキュー名を照合します。
<match domain="org.apache.activemq.artemis" key="queue=example*"> <access method="list*" roles="view,update,amq"/> <access method="get*" roles="view,update,amq"/> <access method="is*" roles="view,update,amq"/> <access method="set*" roles="update,amq"/> <access method="*" roles="amq"/> </match>
同じ属性を組み合わせた各種セット (例: さまざまなキューのセット) に対して、異なるロールをマッピングする場合などです。このような場合は、設定ファイルに複数の match
要素を含めることができます。ただし、同じドメイン内に複数の一致がある可能性があります。
たとえば、以下のように設定された 2 つ <match>
要素について考えてみましょう。
<match domain="org.apache.activemq.artemis" key="queue=example*">
および
<match domain="org.apache.activemq.artemis" key="queue=example.sub*">
この設定を基して、org.apache.activemq.artemis
ドメインの example.sub.queue
という名前のキューは、両方のワイルドカードキーの式にマッチします。したがって、ブローカーは、最初の match
要素で指定されたロール、または 2 番目の match
要素で指定されたロールなど、キューにマップするロールのセットを決定するための優先順位付けスキームを必要とします。
同じドメインに複数の一致がある場合、ブローカーはロールのマッピング時に以下の優先順位スキームを使用します。
- 完全一致がワイルドカードの一致よりも優先される
- ワイルドカードのより長い一致が、より短いワイルドカード一致よりも優先されます。
この例では、長いワイルドカード式が example.sub.queue
のキュー名と一致するため、ブローカーは 2 番目の <match>
要素に設定された role-mapping を適用します。
default-access
要素は、role-access
または whitelist
設定で処理されないすべてのメソッド呼び出しをすべて受け入れる要素です。default-access
要素および role-access
要素には、match
要素と同じセマンティクスがあります。
5.3.2.2.3. whitelist 要素の設定
whitelist は、ユーザー認証を必要としない事前承認済みのドメインまたは MBean のセットです。認証を省略する必要のあるドメインのリストまたは MBean のリスト、またはその両方を指定できます。たとえば、ホワイトリストを使用して、AMQ Broker 管理コンソールの実行に必要な MBean を指定できます。
以下の手順の例は、whitelist
要素を設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/management.xml
設定ファイルを開きます。 whitelist
要素を検索し、設定を編集します。<whitelist> <entry domain="hawtio"/> </whitelist>
この例では、ドメインが
hawtio
の MBean が、認証なしでアクセスできます。MBean プロパティーに一致させるために<entry domain="hawtio" key="type=*"/>
形式のワイルドカードエントリーを使用することもできます。ブローカーを起動または再起動します。
-
Linux の場合:
<broker_instance_dir>/bin/artemis run
-
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
-
Linux の場合:
5.3.2.3. リソース制限の設定
承認や認証に関連する通常のセキュリティー設定以外に、特定のユーザーが実行できる特定の制限を設定すると便利です。
5.3.2.3.1. 接続およびキュー制限の設定
以下の手順の例は、ユーザーが作成できる接続およびキューの数を制限する方法を示しています。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 resource-limit-settings
要素を追加します。max-connections
およびmax-queues
の値を指定します。以下に例を示します。<resource-limit-settings> <resource-limit-setting match="myUser"> <max-connections>5</max-connections> <max-queues>3</max-queues> </resource-limit-setting> </resource-limit-settings>
max-connections
-
一致したユーザーがブローカー上で作成できるセッションの数を定義します。デフォルトは
-1
で、制限がないことを意味します。セッション数を制限する場合は、AMQ コアプロトコル JMS クライアントからブローカーへの接続ごとに 2 つのセッションが作成されることを考慮してください。 max-queues
-
一致したユーザーが作成できるキューの数を定義します。デフォルトは
-1
で、制限がないことを意味します。
ブローカー設定の address-setting
要素に指定できる match
文字列とは異なり、resource-limit-settings
で指定した match
文字列はワイルドカード構文を使用することは できません。代わりに、match 文字列は、リソース制限の設定が適用される特定のユーザーを定義します。
5.4. 認証および承認での LDAP の使用
LDAP ログインモジュールは、中央の X.500 ディレクトリーサーバーに保存されているユーザーデータに対して受信認証情報を確認して、認証および承認を有効にします。これは org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule
で実装されます。
5.4.1. クライアント認証用の LDAP の設定
以下の手順の例は、LDAP を使用してクライアントを認証する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 security-settings
要素内にsecurity-setting
要素を追加してパーミッションを設定します。以下に例を示します。<security-settings> <security-setting match="#"> <permission type="createDurableQueue" roles="user"/> <permission type="deleteDurableQueue" roles="user"/> <permission type="createNonDurableQueue" roles="user"/> <permission type="deleteNonDurableQueue" roles="user"/> <permission type="send" roles="user"/> <permission type="consume" roles="user"/> </security-setting> </security-settings>
上記の設定では、すべて のキューに特定のパーミッションを
ユーザー
ロールのメンバーに割り当てます。-
<broker_instance_dir>/etc/login.config
ファイルを開きます。 使用しているディレクトリーサービスに基づいて、LDAP ログインモジュールを設定します。
Microsoft Active Directory ディレクトリーサービスを使用している場合は、以下の例のように設定を追加します。
activemq { org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required debug=true initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connectionURL="LDAP://localhost:389" connectionUsername="CN=Administrator,CN=Users,OU=System,DC=example,DC=com" connectionPassword=redhat.123 connectionProtocol=s connectionTimeout="5000" authentication=simple userBase="dc=example,dc=com" userSearchMatching="(CN={0})" userSearchSubtree=true readTimeout="5000" roleBase="dc=example,dc=com" roleName=cn roleSearchMatching="(member={0})" roleSearchSubtree=true ; };
注記Microsoft Active Directory を使用し、
connectionUsername
の属性に指定する必要のある値にスペース (例:OU=System Accounts
) が含まれている場合は、値を二重引用符 (""
) で囲み、バックスラッシュ (\
) を使用してペア内の各二重引用符をエスケープする必要があります。たとえば、connectionUsername="CN=Administrator,CN=Users,OU=\"System Accounts\",DC=example,DC=com"
などです。ApacheDS ディレクトリーサービスを使用している場合は、以下の例のような設定を追加します。
activemq { org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required debug=true initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connectionURL="ldap://localhost:10389" connectionUsername="uid=admin,ou=system" connectionPassword=secret connectionProtocol=s connectionTimeout=5000 authentication=simple userBase="dc=example,dc=com" userSearchMatching="(uid={0})" userSearchSubtree=true userRoleName= readTimeout=5000 roleBase="dc=example,dc=com" roleName=cn roleSearchMatching="(member={0})" roleSearchSubtree=true ; };
debug
-
デバッグをオン (
true
) またはオフ (false
) にします。デフォルト値はfalse
です。 initialContextFactory
-
常に
com.sun.jndi.ldap.LdapCtxFactory
に設定する必要があります。 connectionURL
-
LDAP URL (__<ldap://Host:Port>) を使用するディレクトリーサーバーの場所。オプションでこの URL を修飾するには、スラッシュ
/
とその後にディレクトリーツリーの特定ノードの DN を追加します。Apache DS のデフォルトポートは10389
で、Microsoft AD のデフォルト値は389
です。 connectionUsername
-
ディレクトリーサーバーへの接続を開くユーザーの識別名 (DN)たとえば、
uid=admin,ou=system
です。ディレクトリーサーバーでは、通常、クライアントが接続を開くためにユーザー名/パスワードの認証情報を提示する必要があります。 connectionPassword
-
connectionUsername
の DN に一致するパスワード。Directory Information Tree (DIT) のディレクトリーサーバーでは、パスワードは通常、対応するディレクトリーエントリーにuserPassword
属性として保存されます。 connectionProtocol
- すべての値はサポートされますが、実質的に使用されません。このオプションはデフォルト値がないために明示的に設定する必要があります。
connectionTimeout
ブローカーがディレクトリーサーバーに接続することができる最大時間をミリ秒単位で指定します。ブローカーがこの時間内にディレクトリーに接続できない場合、接続の試行を中止します。このプロパティーにゼロまたはそれよりも小さい値を指定すると、代わりに基盤の TCP プロトコルのタイムアウト値が使用されます。値を指定しない場合、ブローカーは接続を無期限に待機するか、基盤のネットワークがタイムアウトします。
接続に対して接続プールが要求された場合、このプロパティーは、最大プールサイズにすでに達し、プール内のすべての接続が使用されている場合に、ブローカーが接続を待つ最大時間を指定します。ゼロまたはそれよりも小さい値を指定すると、ブローカーは接続を無期限に利用可能になるまで待機します。それ以外の場合は、ブローカーは最大待機時間に達すると接続の試行を中止します。
authentication
-
LDAP サーバーにバインドする際に使用する認証方法を指定します。このパラメーターは
simple
(ユーザー名とパスワードが必要) またはnone
(匿名アクセスを許可) のいずれかに設定できます。 userBase
-
ユーザーエントリーを検索する DIT の特定のサブツリーを選択します。サブツリーは、サブツリーのベースノードを指定する DN で指定されます。たとえば、このオプションを
ou=User,ou=ActiveMQ,ou=system
に設定すると、ユーザーエントリーの検索はou=User,ou=ActiveMQ,ou=system
ノードの下にあるサブツリーに限定されます。 userSearchMatching
-
userBase
で選択したサブツリーに適用される LDAP 検索フィルターを指定します。詳細は、以下の 「一致するパラメーターの検索」 セクションを参照してください。 userSearchSubtree
-
userBase
で指定されたノードを基準にして、どの程度の深さまでユーザーエントリーの検索を掘り下げるかを指定します。このオプションはブール値です。false
の値を指定すると、userBase
ノードの子エントリーのいずれかに一致するものの検索を試行します (javax.naming.directory.SearchControls.ONELEVEL_SCOPE
にマップ)。true
の値を指定すると、userBase
ノードの サブ ツリーの配下にあるエントリーに一致するものの検索を試行します (javax.naming.directory.SearchControls.SUBTREE_SCOPE
にマップ)。 userRoleName
- ユーザーのロール名のリストを含むユーザーエントリーの属性の名前。ロール名は、ブローカーの承認プラグインによってグループ名として解釈されます。このオプションを省略すると、ユーザーエントリーからロール名は抽出されません。
readTimeout
- ブローカーがディレクトリーサーバーから LDAP 要求への応答を受信するまで待機する最大時間をミリ秒単位で指定します。この時間内にブローカーがディレクトリーサーバーから応答を受信しない場合、ブローカーは要求を中止します。0 または less の値を指定すると、値を指定しないと、ディレクトリーサーバーから LDAP 要求への応答が無期限に待機します。
roleBase
-
ロールデータをディレクトリーサーバーに直接保存する場合は、
userRoleName
オプションを指定する代わりに (または指定してその上に)、ロールオプション (roleBase
、roleSearchMatching
、roleSearchSubtree
、およびroleName
) の組み合わせを使用できます。このオプションは、ロール/グループエントリーを検索する DIT の特定のサブツリーを選択します。サブツリーは、サブツリーのベースノードを指定する DN で指定されます。たとえば、このオプションをou=Group,ou=ActiveMQ,ou=system
に設定すると、role/group エントリーの検索がou=Group,ou=ActiveMQ,ou=system
ノードの下にあるサブツリーに限定されます。 roleName
- ロール/グループの名前が含まれるロールエントリーの属性タイプ (C、O、OU など)。このオプションを省略すると、ロール検索機能は事実上無効になっています。
roleSearchMatching
-
roleBase
で選択したサブツリーに適用される LDAP 検索フィルターを指定します。詳細は、以下の 「一致するパラメーターの検索」 セクションを参照してください。 roleSearchSubtree
roleBase
で指定されたノードを基準にして、どの程度の深さまでロールエントリーの検索を掘り下げるかを指定します。false
(デフォルト) に設定すると、roleBase
ノードの子エントリー (javax.naming.directory.SearchControls.ONELEVEL_SCOPE
にマップ) のいずれかに一致するものの検索を試行します。true
の場合、roleBase ノードのサブツリーに属するエントリーに一致するものの検索を試行します (javax.naming.directory.SearchControls.SUBTREE_SCOPE
にマップ)。注記Apache DS は、DN パスの
OID
部分を使用します。Microsoft Active Directory はCN
部分を使用します。たとえば、Apache DS ではoid=testuser,dc=example,dc=com
などの DN パスを使用し、Microsoft Active Directory ではcn=testuser,dc=example,dc=com
などの DN パスを使用できます。
- ブローカーを起動または再起動します (サービスまたはプロセス)。
5.4.1.1. 一致するパラメーターの検索
userSearchMatching
LDAP 検索操作に渡す前に、この設定パラメーターで指定される文字列の値は
java.text.MessageFormat
クラスで実装される文字列置換の内容により異なります。
つまり、特別な文字列
{0}
は、受信クライアントの認証情報から抽出されたユーザー名に置き換えられます。置換後、この文字列は LDAP 検索フィルターとして解釈されます (構文は IETF 標準 RFC 2254 で定義されています)。
たとえば、このオプションが
(uid={0})
に設定され、受信したユーザー名がjdoe
の場合には、文字列置換後の検索フィルターは(uid=jdoe)
になります。
ユーザーベースが選択したサブツリー (
ou=User,ou=ActiveMQ,ou=system
) に、結果の検索フィルターが適用されると、エントリーuid=jdoe,ou=User,ou=ActiveMQ,ou=system
にマッチします。
roleSearchMatching
これは、2 つの置換文字列をサポートする点を除き、
userSearchMatching
オプションと同じように機能します。
置換文字列
{0}
は、一致したユーザーエントリーの DN をすべて置き換えます (つまり、ユーザー検索の結果)。たとえば、ユーザーjdoe
の場合には、置換された文字列はuid=jdoe,ou=User,ou=ActiveMQ,ou=system
になります。
置換文字列
{1}
は、受信したユーザー名を置き換えます。たとえば、jdoe
です。
このオプションを
(member=uid={1})
に設定し、受信したユーザー名がjdoe
の場合には、文字列の置換後に検索フィルターは(member=uid=jdoe)
になります (ApacheDS 検索フィルター構文を想定)。
ロールベース
ou=Group,ou=ActiveMQ,ou=system
で選択したサブツリーに、結果の検索フィルターが適用されると、uid=jdoe
と同等のmember
属性を持つすべてのロールエントリーがマッチします (member
属性の値は DN です)。
このオプションはデフォルト値がないため、ロールの検索が無効であっても常に設定する必要があります。OpenLDAP を使用すると、検索フィルターの構文は
(member:=uid=jdoe)
になります。
関連情報
- 検索フィルター構文の概要は、Oracle JNDI tutorial を参照してください。
5.4.2. LDAP 認証の設定
LegacyLDAPSecuritySettingPlugin
セキュリティー設定プラグインは、LDAPAuthorizationMap
および cachedLDAPAuthorizationMap
で過去に AMQ 6 で処理されたセキュリティー情報を読み取り、できるだけ、この情報を対応する AMQ 7 セキュリティー設定に変換します。
AMQ 6 および AMQ 7 のブローカーのセキュリティー実装は、完全に一致しません。そのため、プラグインは、2 つのバージョン間の翻訳を実行し、ほぼ同等の機能を実現します。
以下の例は、プラグインを設定する方法を示しています。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 security-settings
要素内にsecurity-setting-plugin
要素を追加します。以下に例を示します。<security-settings> <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin"> <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/> <setting name="connectionURL" value="ldap://localhost:1024"/>`ou=destinations,o=ActiveMQ,ou=system` <setting name="connectionUsername" value="uid=admin,ou=system"/> <setting name="connectionPassword" value="secret"/> <setting name="connectionProtocol" value="s"/> <setting name="authentication" value="simple"/> </security-setting-plugin> </security-settings>
class-name
-
この実装は
org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin
です。 initialContextFactory
-
LDAP への接続に使用される初期コンテキストファクトリー。これは、常に
com.sun.jndi.ldap.LdapCtxFactory
(デフォルト値) に設定する必要があります。 connectionURL
-
LDAP URL <ldap://Host:Port> を使用してディレクトリーサーバーの場所を指定します。オプションでこの URL を修飾するには、スラッシュ
/
とその後にディレクトリーツリーの特定ノードの識別名 (DN) を追加します。例:ldap://ldapserver:10389/ou=system
デフォルト値はldap://localhost:1024
です。 connectionUsername
-
ディレクトリーサーバーへの接続を開くユーザーの DN。たとえば、
uid=admin,ou=system
です。ディレクトリーサーバーでは、通常、クライアントが接続を開くためにユーザー名/パスワードの認証情報を提示する必要があります。 connectionPassword
-
connectionUsername
の DN に一致するパスワード。Directory Information Tree (DIT) のディレクトリーサーバーでは、パスワードは通常、対応するディレクトリーエントリーにuserPassword
属性として保存されます。 connectionProtocol
- 現在は使用されていません。今後、このオプションを使用すると、ディレクトリーサーバーへの接続に Secure Socket Layer(SSL) を選択できます。このオプションはデフォルト値がないために明示的に設定する必要があります。
authentication
LDAP サーバーにバインドする際に使用する認証方法を指定します。このパラメーターの有効な値は
simple
(ユーザー名とパスワード) またはnone
(匿名) です。デフォルト値はsimple
です。注記Simple Authentication and Security Layer(SASL) 認証はサポートされ ません。
前述の設定例に記載されていない他の設定は次のとおりです。
destinationBase
-
子がすべての宛先にパーミッションを提供するノードの DN を指定します。この場合、DN はリテラル値です (つまり、プロパティー値の文字列は置き換えられません)。たとえば、このプロパティーの通常の値は
ou=destinations,o=ActiveMQ,ou=system
で、デフォルト値はou=destinations,o=ActiveMQ,ou=system
です。 filter
-
あらゆる種類の宛先のパーミッションを検索するときに使用する LDAP 検索フィルターを指定します。検索フィルターは、キューまたはトピックノードの子孫の 1 つとの照合を試行します。デフォルト値は
(cn=*)
です。 roleAttribute
-
ロールの DN の値が
filter
に一致するノードの属性を指定します。デフォルト値はuniqueMember
です。 adminPermissionValue
-
admin
パーミッションに一致する値を指定します。デフォルト値はadmin
です。 readPermissionValue
-
read
パーミッションに一致する値を指定します。デフォルト値はread
です。 writePermissionValue
-
write
パーミッションに一致する値を指定します。デフォルト値はwrite
です。 enableListener
-
LDAP サーバーでのを自動的に受信し、ブローカーの認証設定をリアルタイムで更新するリスナーを有効にするかどうかを指定します。デフォルト値は
true
です。 mapAdminToManage
レガシー (AMQ 6) の
admin
パーミッションを AMQ 7 のmanage
パーミッションにマップするかどうかを指定します。以下の表のマッピングセマンティクスの詳細を参照してください。デフォルト値はfalse
です。LDAP で定義されたキューまたはトピックの名前は、セキュリティー設定の一致として機能し、パーミッション値は AMQ 6 タイプから AMQ 7 タイプにマッピングされ、ロールはそのままマッピングされます。LDAP で定義されたキューまたはトピックの名前はセキュリティー設定の一致として機能するため、セキュリティー設定は想定どおりに JMS 宛先に適用されない可能性があります。これは、必要に応じて、AMQ 7 は常に JMS 宛先を jms.queue.または jms.topic.で接頭辞を付けるためです。
AMQ 6 には、
read
、write
、およびadmin
の 3 つのパーミッションタイプがあります。これらのパーミッションタイプは、ActiveMQ の Web サイト (Security) に記載されています。AMQ 7 には以下のパーミッションタイプがあります。
-
createAddress
-
deleteAddress
-
createDurableQueue
-
deleteDurableQueue
-
createNonDurableQueue
-
deleteNonDurableQueue
-
send
-
consume
-
manage
browse
以下の表は、セキュリティー設定プラグインが AMQ 6 パーミッションタイプを AMQ 7 パーミッションタイプにマッピングする方法を示しています。
AMQ 6 パーミッションタイプ AMQ 7 のパーミッションタイプ read
consume, browse
write
send
admin
createAddress、deleteAddress、createDurableQueue、deleteDurableQueue、createNonDurableQueue、deleteNonDurableQueue、manage(
mapAdminToManage
がtrue
に設定されている場合)下記のとおり、プラグインが AMQ 6 と AMQ 7 のパーミッションタイプ間の変換を実行するケースがあります。これにより、同等の機能を実現できます。
-
AMQ 6 には同様のパーミッションタイプがないため、このマッピングにはデフォルトで、AMQ 7 の
manage
パーミッションタイプが含まれません。ただし、mapAdminToManage
がtrue
に設定されている場合、プラグインは AMQ 6admin
パーミッションを AMQ 7manage
にマップします。 -
AMQ 6 の
admin
パーミッションタイプは、宛先が存在しない場合にブローカーが宛先を自動作成し、ユーザーがその宛先にメッセージを送信するかどうかを決定します。AMQ 7 では、ユーザーが宛先にメッセージを送信するパーミッションがある場合に、自動的に宛先の自動作成を許可します。したがって、プラグインは、デフォルトで、レガシーadmin
パーミッションを上記の AMQ 7 パーミッションにマップします。また、このプラグインは、mapAdminToManage
がtrue
に設定されている場合に、AMQ 6admin
パーミッションを AMQ 7 のmanage
パーミッションにマップします。
-
AMQ 6 には同様のパーミッションタイプがないため、このマッピングにはデフォルトで、AMQ 7 の
-
allowQueueAdminOnRead
createDurableQueue、createNonDurableQueue、および deleteDurableQueue パーミッションにレガシー読み取りパーミッションをマッピングするかどうか。これにより、JMS クライアントが admin パーミッションなしに永続サブスクリプションと非永続サブスクリプションを作成できます。これは AMQ 6 で許可されます。デフォルト値は false です。
以下の表は、
allowQueueAdminOnRead
がtrue
の場合に、セキュリティー設定プラグインが AMQ 6 パーミッションタイプを AMQ 7 パーミッションタイプにマッピングする方法を示しています。AMQ 6 パーミッションタイプ AMQ 7 のパーミッションタイプ read
consume, browse, createDurableQueue, createNonDurableQueue, deleteDurableQueue
write
send
admin
createAddress、deleteAddress、deleteNonDurableQueue、manage(
mapAdminToManage
がtrue
に設定されている場合)
5.4.3. login.config ファイルでのパスワードの暗号化
組織は LDAP でデータを安全に保存することが多いので、login.config
ファイルには、ブローカーが組織の LDAP サーバーと通信するために必要な設定を含めることができます。この設定ファイルには、通常、LDAP サーバーにログインするパスワードが含まれるため、このパスワードを暗号化する必要があります。
前提条件
-
「LDAP 認証の設定」 の説明に従って、必要なプロパティーを追加するように
login.config
ファイルを修正している。
手順
以下の手順は、<broker_instance_dir>/etc/login.config
ファイルにある connectionPassword
パラメーターの値をマスクする方法を示しています。
コマンドプロンプトで、
mask
ユーティリティーを使用してパスワードを暗号化します。$ <broker_instance_dir>/bin/artemis mask <password>
result: 3a34fd21b82bf2a822fa49a8d8fa115d
<broker_instance_dir>/etc/login.config
ファイルを開きます。connectionPassword
パラメーターを見つけます。connectionPassword = <password>
プレーンテキストのパスワードは、暗号化された値に置き換えます。
connectionPassword = 3a34fd21b82bf2a822fa49a8d8fa115d
暗号化された値は、識別子
"ENC()"
でラップします。connectionPassword = "ENC(3a34fd21b82bf2a822fa49a8d8fa115d)"
login.config
ファイルにマスクされたパスワードが追加されました。パスワードは "ENC()"
識別子でラップされるため、AMQ Broker では使用前にこれを復号化します。
関連情報
- AMQ Broker に含まれる設定ファイルの詳細については、AMQ Broker の設定ファイルと場所 を参照してください。
5.4.4. 外部ロールのマッピング
LDAP などの外部認証プロバイダーからのロールを、ブローカーによって内部で使用されるロールにマップできます。
外部ロールをマッピングするには、broker.xml
設定ファイルの security-settings
要素に role-mapping エントリーを作成します。以下に例を示します。
<security-settings> ... <role-mapping from="cn=admins,ou=Group,ou=ActiveMQ,ou=system" to="my-admin-role"/> <role-mapping from="cn=users,ou=Group,ou=ActiveMQ,ou=system" to="my-user-role"/> </security-settings>
- ロールマッピングは加算されます。つまり、ユーザーは元のロールと、新たに割り当てられたロールを保持します。
- ロールマッピングは、キューアクセスを承認するロールにのみ影響し、Web コンソールアクセスを有効にする方法を提供しません。
5.5. 認証および承認での Kerberos の使用
AMQP プロトコルでメッセージを送受信する場合、クライアントは Simple Authentication and Security Layer (SASL) フレームワークの GSSAPI メカニズムを使用して、AMQ Broker が認証する Kerberos セキュリティー認証情報を送信できます。Kerberos 認証情報は、認証されたユーザーを LDAP ディレクトリーまたはテキストベースのプロパティーファイルで設定された割り当てられたロールにマッピングすることで、承認にも使用できます。
Transport Layer Security (TLS) と共に SASL を使用して、メッセージングアプリケーションのセキュリティーを確保できます。SASL はユーザー認証を行い、TLS はデータの整合性を確保します。
AMQ Broker が Kerberos 認証情報を認証および承認する前に、Kerberos インフラストラクチャーをデプロイし、設定する必要があります。Kerberos のデプロイメントに関する詳細は、オペレーティングシステムのドキュメントを参照してください。
- RHEL 7 については、Kerberos の使用 を参照してください。
- Windows の場合は、Kerberos Authentication Overview を参照してください。
- Oracle または IBM JDK のユーザーは、Java Cryptography Extension(JCE) をインストールする必要があります。詳細は、Oracle version of the JCE または IBM version of the JCE のドキュメントを参照してください。
以下の手順では、認証および承認に Kerberos を設定する方法を説明します。
5.5.1. Kerberos を使用するネットワーク接続の設定
AMQ Broker は、Simple Authentication and Security Layer (SASL) フレームワークの GSSAPI メカニズムを使用して、Kerberos セキュリティー認証情報と統合します。AMQ Broker で Kerberos を使用するには、Kerberos 認証情報を使用するクライアントを認証または承認する各アクセプターを GSSAPI メカニズムを使用するように設定する必要があります。
以下の手順では、Kerberos を使用するようにアクセプターを設定する方法を説明します。
前提条件
- AMQ Broker が Kerberos 認証情報を認証および承認する前に、Kerberos インフラストラクチャーをデプロイし、設定する必要があります。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 name-value ペアの
saslMechanisms=GSSAPI
をacceptor
の URL のクエリー文字列に追加します。<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI </acceptor>
上記の設定は、Kerberos クレデンシャルの認証時に、アクセプターが GSSAPI メカニズムを使用することを意味します。
(オプション)
PLAIN
およびANONYMOUS
SASL メカニズムもサポートされます。複数のメカニズムを指定するには、コンマ区切りリストを使用します。以下に例を示します。<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN </acceptor>
結果は、
GSSAPI
およびPLAIN
SASL メカニズムの両方を使用するアクセプターです。ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
関連情報
- アクセプターの詳細は、「アクセプターについて」 を参照してください。
5.5.2. Kerberos 認証情報を使用したクライアントの認証
AMQ Broker は、Simple Authentication and Security Layer (SASL) フレームワークからの GSSAPI メカニズムを使用する AMQP 接続の Kerberos 認証をサポートします。
ブローカーは、Java Authentication and Authorization Service (JAAS) を使用して Kerberos アクセプターの認証情報を取得します。Java インストールに含まれる JAAS ライブラリーは、Kerberos 認証情報を認証するログインモジュール Krb5LoginModule
でパッケージ化されています。Krb5LoginModule
の詳細は、Java ベンダーのドキュメントを参照してください。たとえば、Oracle は、Java 8 ドキュメント の一部として、Krb5LoginModule
ログインモジュールに関する情報を提供します。
前提条件
- Kerberos セキュリティー認証情報を使用して AMQP 接続を認証する前に、アクセプターの GSSAPI メカニズムを有効にする必要があります。詳細は、「Kerberos を使用するネットワーク接続の設定」 を参照してください。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/login.config
設定ファイルを開きます。 amqp-sasl-gssapi
という名前の設定スコープを追加します。以下の例は、Oracle および OpenJDK バージョンの JDK にあるKrb5LoginModule
の設定を示しています。amqp-sasl-gssapi { com.sun.security.auth.module.Krb5LoginModule required isInitiator=false storeKey=true useKeyTab=true principal="amqp/my_broker_host@example.com" debug=true; };
amqp-sasl-gssapi
-
デフォルトでは、ブローカーの GSSAPI メカニズム実装は
amqp-sasl-gssapi
という名前の JAAS 設定スコープを使用して Kerberos アクセプター認証情報を取得します。 Krb5LoginModule
-
このバージョンの
Krb5LoginModule
は、Oracle および OpenJDK バージョンの JDK で提供されます。Java ベンダーのドキュメントを参照して、Krb5LoginModule
の完全修飾クラス名とその利用可能なオプションを確認します。 useKeyTab
-
Krb5LoginModule
は、プリンシパルの認証時に Kerberos キータブを使用するように設定されます。キータブは、Kerberos 環境からツールを使用して生成されます。Kerberos キータブの生成に関する詳細は、ベンダーのドキュメントを参照してください。 principal
-
プリンシパルは
amqp/my_broker_host@example.com
に設定されます。この値は、Kerberos 環境で作成されたサービスプリンシパルに対応する必要があります。サービスプリンシパルの作成に関する詳細は、ベンダーのドキュメントを参照してください。
ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
5.5.2.1. 代替設定スコープの使用
AMQP アクセプターの URL にパラメーター saslLoginConfigScope
を追加して、 別の設定スコープを指定できます。以下の設定例では、saslLoginConfigScope
パラメーターに alternative-sasl-gssapi
の値が指定されています。結果は、<broker_instance_dir>/etc/login.config
で宣言される alternative-sasl-gssapi
という名前の代わりのスコープを使用するアクセプターです。
<acceptor name="amqp"> tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI,PLAIN;saslLoginConfigScope=alternative-sasl-gssapi` </acceptor>
5.5.3. Kerberos 認証情報を使用したクライアントの承認
AMQ Broker には、ロールのマッピング時に他のセキュリティーモジュールで使用される JAAS Krb5LoginModule
ログインモジュールの実装が含まれています。モジュールは、Kerberos 認証されていないピアプリンシパルを AMQ Broker UserPrincipal として設定された Subject のプリンシパルに追加します。その後、認証情報は PropertiesLoginModule
または LDAPLoginModule
モジュールに渡して、Kerberos 認証のピアプリンシパルを AMQ Broker ロールにマップできます。
Kerberos ピアプリンシパルはロールメンバーとしてのみ存在し、ブローカーユーザーとしては存在しません。
前提条件
- Kerberos セキュリティー認証情報を使用して AMQP 接続を承認する前に、アクセプターの GSSAPI メカニズムを有効にする必要があります。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/login.config
設定ファイルを開きます。 AMQ Broker
Krb5LoginModule
およびLDAPLoginModule
の設定を追加します。LDAP プロバイダーのドキュメントを参照して、設定オプションを確認します。以下は設定例です。
org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required ; org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connectionURL="ldap://localhost:1024" authentication=GSSAPI saslLoginConfigScope=broker-sasl-gssapi connectionProtocol=s userBase="ou=users,dc=example,dc=com" userSearchMatching="(krb5PrincipalName={0})" userSearchSubtree=true authenticateUser=false roleBase="ou=system" roleName=cn roleSearchMatching="(member={0})" roleSearchSubtree=false ;
注記上記の例で示される
Krb5LoginModule
のバージョンは AMQ Broker で配布され、Kerberos アイデンティティーをロールマッピングに使用できるブローカーアイデンティティーに変換します。ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
関連情報
- AMQ Broker で GSSAPI メカニズムを有効にする方法は、「Kerberos を使用するネットワーク接続の設定」 を参照してください。
-
PropertiesLoginModule
の詳細は、「基本的なユーザーとパスワード認証の設定」 を参照してください。 -
LDAPLoginModule
の詳細は、「クライアント認証用の LDAP の設定」 を参照してください。
5.6. セキュリティーマネージャーの指定
ブローカーは、セキュリティーマネージャー と呼ばれるコンポーネントを使用して認証および承認を処理します。
AMQ Broker には 2 つのセキュリティーマネージャーが含まれています。
-
ActiveMQJAASSecurityManager
セキュリティーマネージャー。このセキュリティーマネージャーは、JAAS および Red Hat JBoss Enterprise Application Platform(JBoss EAP) のセキュリティーとの統合を提供します。これは、AMQ Broker によって使用される デフォルト のセキュリティーマネージャーです。 -
ActiveMQBasicSecurityManager
セキュリティーマネージャー。この基本セキュリティーマネージャーは JAAS をサポートしません。代わりに、ユーザー名とパスワードの認証情報による認証および承認をサポートします。このセキュリティーマネージャーは、管理 API を使用したユーザーの追加、削除、および更新をサポートします。ユーザーとロールデータはブローカーバインディングジャーナルに保存されます。つまり、ライブブローカーに加えられた変更はバックアップブローカーでも利用できることになります。
含まれるセキュリティーマネージャーの代わりに、システム管理者はブローカーセキュリティーの実装をより詳細に制御することを推奨します。このような場合には、ブローカー設定で カスタム セキュリティーマネージャーを指定することもできます。カスタムセキュリティーマネージャーは、org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager5
インターフェイスを実装するユーザー定義のクラスです。
以下のサブセクションの例では、使用するブローカーを設定する方法を示しています。
- デフォルトの JAAS セキュリティーマネージャーではなく基本セキュリティーマネージャー
- カスタムセキュリティーマネージャー
5.6.1. 基本的なセキュリティーマネージャーの使用
AMQ Broker には、デフォルトの ActiveMQJAASSecurityManager
セキュリティーマネージャーの他に、ActiveMQBasicSecurityManager
セキュリティーマネージャーも含まれています。
基本的なセキュリティーマネージャーを使用する場合には、すべてのユーザーおよびロールデータはバインディングジャーナル (または JDBC 永続性を使用している場合は バインディング テーブル ) に保存されます。したがって、ライブバックアップブローカーグループを設定している場合、ライブブローカーで peform というユーザー管理は、フェイルオーバー時にバックアップブローカーに自動的に反映されます。これにより、LDAP サーバーを個別に管理する必要がなくなりました。これは、この動作を達成する代替方法です。
基本的なセキュリティーマネージャーを設定して使用する前に、以下の点に留意してください。
- 基本的なセキュリティーマネージャーは、デフォルトの JAAS セキュリティーマネージャーのようにプラグ可能でありません。
- 基本的なセキュリティーマネージャーは JAAS をサポートしません。代わりに、ユーザー名とパスワードの認証情報による認証および承認のみをサポートします。
-
AMQ 管理コンソールには JAAS が必要です。そのため、基本的なセキュリティーマネージャーを使用し、コンソールを使用する必要がある場合は、ユーザーおよびパスワード認証用の
login.config
設定ファイルも設定する必要があります。ユーザーおよびパスワード認証の設定に関する詳細は、「基本的なユーザーとパスワード認証の設定」 を参照してください。 - AMQ Broker では、ユーザー管理 はブローカー管理 API によって提供されます。この管理には、ユーザーとロールを追加、リスト表示、更新、および削除する機能が含まれます。これらの機能は、JMX、管理メッセージ、HTTP(Jolokia または AMQ 管理コンソール) および AMQ Broker コマンドラインインターフェイスを使用して実行できます。ブローカーはこのデータを直接格納するため、ユーザーを管理するためにブローカーを実行する必要があります。バインディングデータを手動で変更する方法はありません。
- HTTP(Jolokia または AMQ 管理コンソールを使用するなど) による管理アクセスは、コンソール JAAS ログインモジュールによって処理されます。JConsole またはその他のリモート JMX ツールによる MBean アクセスは、基本的なセキュリティーマネージャーによって処理されます。管理メッセージは、基本的なセキュリティーマネージャーによって処理されます。
5.6.1.1. 基本的なセキュリティーマネージャーの設定
以下の手順は、基本的なセキュリティーマネージャーを使用するようにブローカーを設定する方法を説明します。
手順
-
<broker-instance-dir>/etc/boostrap.xml
設定ファイルを編集します。 security-manager
要素のclass-name
属性に、ActiveMQBasicSecurityManager
クラス名をすべて指定します。<broker xmlns="http://activemq.org/schema"> ... <security-manager class-name="org.apache.activemq.artemis.spi.core.security.ActiveMQBasicSecurityManager"> </security-manager> ... </broker>
ユーザーおよびロールデータを保持するバインディングデータを手動で変更することはできず、ブローカーを実行してユーザーを管理する必要があるため、初回起動時にブローカーのセキュリティーを保護することを推奨します。これを行うには、認証情報を使用して他の ユーザーを追加できるブートストラップ ユーザーを定義します。
security-manager
要素にbootstrapUser
、bootstrapPassword
、およびbootstrapRole
プロパティーを追加し、値を指定します。以下に例を示します。<broker xmlns="http://activemq.org/schema"> ... <security-manager class-name="org.apache.activemq.artemis.spi.core.security.ActiveMQBasicSecurityManager"> <property key="bootstrapUser" value="myUser"/> <property key="bootstrapPassword" value="myPass"/> <property key="bootstrapRole" value="myRole"/> </security-manager> ... </broker>
bootstrapUser
- ブートストラップユーザーの名前。
bootstrapPassword
- boostrap ユーザーの Passsword。暗号化したパスワードを指定することもできます。
bootstrapRole
boostrap ユーザーのロール。
注記設定でブートストラップユーザーの前述のプロパティーを定義する場合、ブローカーの実行中に加える変更に関係なく、これらの認証情報はブローカーを起動するたびに設定されます。
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 broker.xml
設定ファイルで、activemq.management#
アドレス一致に対してデフォルトで定義されるaddress-setting
要素を見つけます。これらのデフォルトアドレス設定を以下に示します。<address-setting match="activemq.management#"> <dead-letter-address>DLQ</dead-letter-address> <expiry-address>ExpiryQueue</expiry-address> <redelivery-delay>0</redelivery-delay> <!--...--> <max-size-bytes>-1</max-size-bytes> <message-counter-history-day-limit>10</message-counter-history-day-limit> <address-full-policy>PAGE</address-full-policy> <auto-create-queues>true</auto-create-queues> <auto-create-addresses>true</auto-create-addresses> <auto-create-jms-queues>true</auto-create-jms-queues> <auto-create-jms-topics>true</auto-create-jms-topics> </address-setting>
activemq.management#
アドレス一致向けのアドレス設定内に、この手順で以前に指定したブートストラップロール名に対して、以下の必要なパーミッションを追加します。-
createNonDurableQueue
-
createAddress
-
consume
-
manage
-
send
以下に例を示します。
<address-setting match="activemq.management#"> ... <permission type="createNonDurableQueue" roles="myRole"/> <permission type="createAddress" roles="myRole"/> <permission type="consume" roles="myRole"/> <permission type="manage" roles="myRole"/> <permission type="send" roles="myRole"/> </address-setting>
-
関連情報
-
ActiveMQBasicSecurityManager
クラスの詳細は、ActiveMQ Artemis Core API ドキュメントの Class ActiveMQBasicSecurityManager を参照してください。 - 設定ファイルでパスワードを暗号化する方法は、「設定ファイルのパスワードの暗号化」 を参照してください。
5.6.2. カスタムセキュリティーマネージャーの指定
以下の手順では、ブローカー設定でカスタムセキュリティーマネージャーを指定する方法を説明します。
手順
-
<broker_instance_dir>/etc/boostrap.xml
設定ファイルを編集します。 security-manager
要素のclass-name
属性に、org.apache.activemq.artemis.spi.core.security.ActiveMQSecurityManager5
インターフェイスのユーザー定義の実装であるクラスを指定します。以下に例を示します。<broker xmlns="http://activemq.org/schema"> ... <security-manager class-name="com.myclass.MySecurityManager"> <property key="myKey1" value="myValue1"/> <property key="myKey2" value="myValue2"/> </security-manager> ... </broker>
関連情報
-
ActiveMQSecurityManager5
インターフェイスの詳細は、ActiveMQ Artemis Core API ドキュメントの Interface ActiveMQSecurityManager5 を参照してください。
5.6.3. カスタムセキュリティーマネージャーのサンプルプログラムの実行
AMQ Broker には、カスタムセキュリティーマネージャーの実装方法を実証するサンプルプログラムが含まれています。この例では、カスタムセキュリティーマネージャーは認証および承認の詳細をログに記録してから、その詳細を ActiveMQJAASSecurityManager
(デフォルトのセキュリティーマネージャー) のインスタンスに渡します。
以下の手順は、カスタムセキュリティーマネージャーのサンプルプログラムを実行する方法を示しています。
前提条件
- AMQ Broker サンプルプログラムを実行するようにマシンを設定する必要があります。詳細については、AMQ Broker のサンプルの実行 を参照してください。
手順
カスタムセキュリティーマネージャーの例が含まれるディレクトリーに移動します。
$ cd <install_dir>/examples/features/standard/security-manager
サンプルを実行します。
$ mvn verify
サンプルプログラムの実行時にブローカーインスタンスを手動で作成して起動する場合は、前の手順のコマンドを mvn -PnoServer verify
に置き換えてください。
関連情報
-
ActiveMQJAASSecurityManager
クラスの詳細は、ActiveMQ Artemis Core API ドキュメントの Class ActiveMQJAASSecurityManager を参照してください。
5.7. セキュリティーの無効化
セキュリティーはデフォルトで有効になっています。以下の手順では、ブローカーセキュリティーを無効にする方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素で、security-enabled
の値をfalse
に設定します。<security-enabled>false</security-enabled>
-
必要に応じて、
security-invalidation-interval
の新しい値をミリ秒単位で指定します。このプロパティーの値は、ブローカーが定期的にセキュアなログインを無効にするかどうかを指定します。デフォルト値は10000
です。
5.8. 検証済みユーザーからのメッセージの追跡
メッセージの発信元の追跡およびログを有効にするには (セキュリティー監査の目的など)、_AMQ_VALIDATED_USER
メッセージキーを使用できます。
broker.xml
設定ファイルで populate-validated-user
オプションが true
に設定されている場合には、ブローカーは _AMQ_VALIDATED_USER
キーを使用して検証済みユーザーの名前をメッセージに追加します。JMS および STOMP クライアントの場合には、このメッセージキーは JMSXUserID
キーにマッピングされます。
ブローカーは、AMQP JMS クライアントによって生成されたメッセージに、検証されたユーザー名を追加できません。クライアントによって送信された AMQP メッセージのプロパティーを変更すると、AMQP プロトコルの違反があります。
自分の SSL 証明書を基に認証されるユーザーの場合、ブローカーによって設定される検証されたユーザー名は、証明書の識別名 (DN) マップの名前です。
broker.xml
設定ファイルで security-enabled
が false
で、populate-validated-user
が true
の場合に、ブローカーはクライアントが指定するユーザー名 (ある場合) を指定します。populate-validated-user
オプションのデフォルトは false
です。
メッセージの送信時に、クライアントによりユーザー名 (つまり、JMSXUser ID
キー) がまだ入力されていないメッセージを拒否するようにブローカーを設定できます。ブローカーはこれらのクライアントによって送信されたメッセージについて検証されたユーザー名自体を設定できないため、このオプションが AMQP クライアントに役立ちます。
クライアントによって JMSXUserID
が設定されていないメッセージを拒否するようにブローカーを設定するには、以下の設定を broker.xml
設定ファイルに追加します。
<reject-empty-validated-user>true</reject-empty-validated-user>
デフォルトでは、reject-empty-validated-user
は false
に設定されます。
5.9. 設定ファイルのパスワードの暗号化
デフォルトでは、AMQ Broker はすべてのパスワードをプレーンテキストとして設定ファイルに保存します。承認されていないアクセスを防ぐために、適切なパーミッションですべての設定ファイルのセキュリティーを保護するようにしてください。また、プレーンテキストのパスワードを暗号化するか、マスク して、不要なビューアーが読み込まれないようにすることもできます。
5.9.1. 暗号化パスワードについて
暗号化 (マスクされた ) パスワードは、プレーンテキストのパスワードが暗号化されたバージョンです。暗号化バージョンは、AMQ Broker によって提供される mask
コマンドラインユーティリティーによって生成されます。mask
ユーティリティーの詳細は、コマンドラインのヘルプドキュメントを参照してください。
$ <broker_instance_dir>/bin/artemis help mask
パスワードをマスクするには、プレーンテキストの値を暗号化された値に置き換えます。マスクされたパスワードは、実際の値が必要になったときに復号化されるように、識別子 ENC()
でラップする必要があります。
以下の例では、<broker_instance_dir>/etc/bootstrap.xml
設定ファイルには、keyStorePassword
パラメーターおよび trustStorePassword
パラメーターのマスクされたパスワードが含まれます。
<web bind="https://localhost:8443" path="web" keyStorePassword="ENC(-342e71445830a32f95220e791dd51e82)" trustStorePassword="ENC(32f94e9a68c45d89d962ee7dc68cb9d1)"> <app url="activemq-branding" war="activemq-branding.war"/> </web>
以下の設定ファイルでは、マスクされたパスワードを使用できます。
- broker.xml
- bootstrap.xml
- management.xml
- artemis-users.properties
-
login.config(
LDAPLoginModule
で使用)
設定ファイルは <broker_instance_dir>/etc
にあります。
artemis-users.properties
は、ハッシュ化されたパスワードをマスクする場合のみサポートします。ブローカーの作成時にユーザーが作成されると、artemis-users.properties
にはデフォルトでハッシュ化されたパスワードが含まれます。デフォルトの PropertiesLoginModule
は artemis-users.properties
ファイルのパスワードを復号化しませんが、代わりに入力をハッシュ化してパスワード検証の 2 つのハッシュ値を比較します。ハッシュ化パスワードをマスクされたパスワードに変更しても、AMQ Broker 管理コンソールにはアクセスできません。
broker.xml
、bootstrap.xml
、management.xml
、および login.config
はマスクされているが、ハッシュ化されていないパスワードをサポートします。
5.9.2. 設定ファイルでのパスワードの暗号化
以下の例は、broker.xml
設定ファイルで cluster-password
の値をマスクする方法を示しています。
手順
コマンドプロンプトで、
mask
ユーティリティーを使用してパスワードを暗号化します。$ <broker_instance_dir>/bin/artemis mask <password>
result: 3a34fd21b82bf2a822fa49a8d8fa115d
マスクするプレーンテキストのパスワードが含まれる
<broker_instance_dir> /etc/broker.xml
設定ファイルを開きます。<cluster-password> <password> </cluster-password>
プレーンテキストのパスワードは、暗号化された値に置き換えます。
<cluster-password> 3a34fd21b82bf2a822fa49a8d8fa115d </cluster-password>
暗号化された値を識別子
ENC()
でラップします。<cluster-password> ENC(3a34fd21b82bf2a822fa49a8d8fa115d) </cluster-password>
設定ファイルには、暗号化されたパスワードが含まれるようになりました。パスワードは ENC()
識別子でラップされるため、AMQ Broker では使用前にこれを復号化します。
関連情報
- AMQ Broker に含まれる設定ファイルの詳細は、「AMQ Broker の設定ファイルおよび場所」 を参照してください。
5.9.3. パスワードを暗号化および復号化するためのコーデックキー設定
パスワードの暗号化と復号化にはコーデックが必要です。カスタムコーデックが設定されていない場合、mask
ユーティリティーはデフォルトのコーデックを使用してパスワードを暗号化し、AMQ Broker は同じデフォルトのコーデックを使用してパスワードを復号化します。コーデックは、パスワードを暗号化および復号化するために、基礎となる暗号化アルゴリズムに提供するデフォルトキーで設定されます。デフォルトキーを使用すると、悪意のあるアクターがそのキーを使用してパスワードを解読するリスクが生じます。
mask
ユーティリティーを使用してパスワードを暗号化する場合、独自のキー文字列を指定して、デフォルトコーデックキーの使用を回避できます。次に、同じキー文字列を ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
環境変数に設定して、ブローカーがパスワードを復号化できるようにする必要があります。環境変数にキーを設定すると、設定ファイルに保持されないため、よりセキュアになります。さらに、ブローカーを開始する直前にキーを設定し、ブローカーの開始直後に設定を解除できます。
手順
mask
ユーティリティーを使用して、設定ファイル内の各パスワードを暗号化します。key
パラメーターには、パスワードを暗号化する文字列を指定します。各パスワードの暗号化には同じキー文字列を使用してください。$ <broker_instance_dir>/bin/artemis mask --key <key> <password>
警告mask
ユーティリティーを実行してパスワードを暗号化するときに指定するキー文字列を記録しておいてください。ブローカーがパスワードを復号化できるようにするには、環境変数で同じキー値を設定する必要があります。設定ファイルでパスワードを暗号化する方法は、「設定ファイルでのパスワードの暗号化」 を参照してください。
コマンドプロンプトから、
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
環境変数を、各パスワードを暗号化したときに指定したキー文字列に設定します。$ export ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY= <key>
ブローカーを起動します。
$ ./artemis run
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
環境変数の設定を解除します。$ unset ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
注記ブローカの開始後に
ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY
環境変数の設定を解除した場合は、その後毎回ブローカを起動する前に、同じキー文字列に再度設定する必要があります。
5.10. 認証と認可のキャッシュの設定
デフォルトでは、AMQ ブローカーは、成功した認証応答および認可応答に関する情報を別のキャッシュに保存します。各キャッシュで許可されるデフォルトのエントリー数と、エントリーがキャッシュされる期間を変更できます。
-
<broker-instance-dir>/etc/broker.xml
設定ファイルを開きます。 各キャッシュで許可されるデフォルトの最大エントリー数 (
1000
) を変更するには、authentication-cache-size
パラメーターとauthorization-cache-size
パラメーターを設定します。以下に例を示します。<configuration> ... <core> ... <authentication-cache-size>2000</authentication-cache-size> <authorization-cache-size>1500</authorization-cache-size> ... </core> ... </configuration>
注記キャッシュが設定された上限に達すると、最近の使用頻度が最も低いエントリーがキャッシュから削除されます。
エントリーがキャッシュされるデフォルトの期間 (
10000
ミリ秒) を変更するには、security-invalidation-interval
パラメーターを設定します。以下に例を示します。<configuration> ... <core> ... <security-invalidation-interval>20000</security-invalidation-interval> ... </core> ... </configuration>
注記security-invalidation-interval
パラメーターを0
に設定すると、認証および認可のキャッシュが無効になります。
第6章 メッセージデータの永続化
AMQ Broker には、メッセージデータの永続化 (つまり 格納) の 2 つのオプションがあります。
- ジャーナルでのメッセージの永続化
- 以下はデフォルトのオプションになります。ジャーナルベースの永続性は、ファイルシステムのジャーナルにメッセージを書き込む高パフォーマンスオプションです。
- データベースのメッセージの永続化
- このオプションは、Java Database Connectivity (JDBC) 接続を使用して、選択したデータベースにメッセージを永続化します。
または、ブローカーを設定して、メッセージデータを永続化し ない ようにすることもできます。詳細は、「永続性の無効化」 を参照してください。
ブローカーは、メッセージジャーナル以外で大きなメッセージを永続化するために別のソリューションを使用します。詳細は、8章大きなメッセージの処理 を参照してください。
ブローカーは、メモリー不足の状況でメッセージをディスクにページングするように設定することもできます。詳細は、「メッセージのページングの設定」 を参照してください。
AMQ Broker でサポートされるデータベースおよびネットワークファイルシステムに関する現在の情報は、Red Hat カスタマーポータルの Red Hat AMQ 7 Supported Configurations を参照してください。
6.1. ジャーナルでのメッセージデータの永続化
ブローカージャーナルは、ディスク上の append-only のファイルセットです。各ファイルは固定サイズに事前作成され、最初にパディングが入力されます。メッセージング操作がブローカーで実行されると、レコードがジャーナルの最後に追加されます。レコードを追加すると、ブローカーはディスクヘッドの移動およびランダムアクセス操作を最小限に抑えることができます。これは通常、ディスク上で最も遅い操作です。1 つのジャーナルファイルが満杯になると、ブローカーは新しいジャーナルファイルを作成します。
ジャーナルファイルサイズは設定可能です。各ファイルによって使用されるディスクリプラーの数を最小限に抑えることができます。最新のディスクトポロジーは複雑で、ブローカーはファイルのマッピング先の cylinder を制御することはできません。そのため、ジャーナルファイルのサイジングは正確に制御するのが難しくなります。
ブローカーが使用するその他の永続性関連の機能は、以下のとおりです。
- 特定のジャーナルファイルがまだ使用中かどうかを判断する ガベージコレクション アルゴリズム。ジャーナルファイルが使用されなくなった場合、ブローカーはファイルを再利用できるように回収できます。
- ジャーナルからデッドスペースを削除し、データを圧縮する圧縮アルゴリズム。これにより、ジャーナルがディスク上のファイル数より小さくなります。
- ローカルトランザクションのサポート。
- JMS クライアントを使用する場合の Extended Architecture(XA) トランザクションのサポート。
ジャーナルのほとんどは Java で記述されています。ただし、実際のファイルシステムとの対話は抽象化されるため、さまざまなプラグ可能な実装を使用できます。AMQ Broker には以下の実装が含まれます。
- NIO
- NIO(New I/O) は標準の Java NIO を使用してファイルシステムとインターフェイスします。これにより、非常に優れたパフォーマンスを実現し、Java 6 以降のランタイムを備えたプラットフォーム上で稼働します。Java NIO の詳細は、Java NIO を参照してください。
- AIO
AIO(Aynshcronous I/O) は、シンネイティブラッパーを使用して、Linux Asynchronous I/O Library(
libaio
) と通信します。AIO では、ブローカーはデータがディスクの作成後に呼び出されるので、同期を明示的に回避できます。デフォルトでは、ブローカーは AIO ジャーナルの使用を試み、AIO が利用できない場合は NIO を使用するようにフォールバックします。通常 AIO は Java NIO よりもさらにパフォーマンスが優れています。
libaio
のインストール方法は、「Linux 非同期 I/O ライブラリーのインストール」 を参照してください。
以下のサブセクションにある手順は、ジャーナルベースの永続性をブローカーに設定する方法を表しています。
6.1.1. Linux 非同期 I/O ライブラリーのインストール
Red Hat は、永続性のパフォーマンスを向上させるために AIO ジャーナル (NIO ではなく) を使用することを推奨しています。
他のオペレーティングシステムや、それ以前のバージョンの Linux カーネルで AIO ジャーナルを使用することはできません。
AIO ジャーナルを使用するには、Linux Asynchronous I/O Library(libaio
) をインストールする必要があります。libaio
をインストールするには、以下のように yum
コマンドを使用します。
yum install libaio
6.1.2. ジャーナルベースの永続性の設定
以下の手順では、ブローカーがジャーナルベースの永続性に使用するデフォルト設定を確認する方法を説明します。この説明を使用すると、必要に応じて設定を調整できます。
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。デフォルトでは、ブローカーは以下のようにジャーナルベースの永続性を使用するように設定されています。
<configuration> <core> ... <persistence-enabled>true</persistence-enabled> <journal-type>ASYNCIO</journal-type> <bindings-directory>./data/bindings</bindings-directory> <journal-directory>./data/journal</journal-directory> <journal-datasync>true</journal-datasync> <journal-min-files>2</journal-min-files> <journal-pool-files>-1</journal-pool-files> <journal-device-block-size>4096</journal-device-block-size> <journal-file-size>10M</journal-file-size> <journal-buffer-timeout>12000</journal-buffer-timeout> <journal-max-io>4096</journal-max-io> ... </core> </configuration>
persistence-enabled
-
このパラメーターの値を
true
に設定すると、ブローカーはメッセージ永続性にファイルベースのジャーナルを使用します。 journal-type
-
使用するジャーナルのタイプ。
ASYNCIO
に設定されている場合には、ブローカーはまず AIO の使用を試行します。AIO が見つからない場合、ブローカーは NIO を使用します。 bindings-directory
-
バインディングジャーナルのファイルシステムの場所。デフォルト値は、
<broker_instance_dir>
ディレクトリーを起点とした相対パスです。 journal-directory
-
メッセージジャーナルのファイルシステムの場所。デフォルト値は、
<broker_instance_dir>
ディレクトリーを起点とした相対パスです。 journal-datasync
-
このパラメーターの値を
true
に設定すると、ブローカーはfdatasync
関数を使用してディスク書き込みを確認します。 journal-min-files
- ブローカーの起動時に最初に作成するジャーナルファイルの数。
journal-pool-files
-
未使用のファイルを回収した後に保持するファイルの数。デフォルト値の
-1
は、クリーンアップ中にファイルが削除されないことを意味します。 journal-device-block-size
- ストレージデバイスのジャーナルが使用するデータブロックの最大サイズ (バイト単位)。デフォルト値は 4096 バイトです。
journal-file-size
- 指定したジャーナルディレクトリーの各ジャーナルファイルの最大サイズ (バイト単位)。この制限に達すると、ブローカーは新規ファイルを起動します。このパラメーターは、バイト表記 (K、M、G など)、または同等のバイナリー (Ki、Mi、Gi) もサポートします。このパラメーターが設定で明示的に指定されていない場合、デフォルト値は 10485760 バイト (10MiB) になります。
journal-buffer-timeout
- ブローカーがジャーナルバッファーをフラッシュする頻度をナノ秒で指定します。通常、AIO は NIO よりも高いフラッシュレートを使用するため、ブローカーは NIO と AIO の異なるデフォルト値を維持します。このパラメーターが設定で明示的に指定されていない場合、NIO のデフォルト値は 3333333 ナノ秒 (つまり、1 秒あたり 300 回) になります。AIO のデフォルト値は 50000 ナノ秒 (例: 2000 回/秒) です。
journal-max-io
いつでも IO キューに格納できる書き込み要求の最大数。キューが満杯になると、ブローカーは領域が利用可能になるまで追加の書き込みをブロックします。
NIO を使用している場合、この値は常に
1
である必要があります。AIO を使用し、このパラメーターが明示的に設定されていない場合、デフォルト値は500
になります。
- 上記の説明に基づいて、ストレージデバイスの必要に応じて永続性設定を調整します。
関連情報
- ジャーナルベースの永続性設定に使用できる 全 パラメーターの詳細は、付録E メッセージングジャーナル設定要素 を参照してください。
6.1.3. バインディングジャーナルについて
バインディングジャーナルは、ブローカーにデプロイされたキューのセットや属性などのバインディング関連のデータを保存するために使用されます。また、ID シーケンスカウンターなどのデータも格納します。
バインディングジャーナルは常に NIO を使用します。これは通常、メッセージジャーナルと比べるとスループットが低くなるためです。このジャーナルのファイルには activemq-bindings
という接頭辞が付けられます。各ファイルには拡張子 .bindings
があり、デフォルトサイズは 1048576 バイトです。
バインディングジャーナルを設定するには、<broker_instance_dir>/etc/broker.xml
設定ファイルの core
要素に以下のパラメーターを追加します。
bindings-directory
-
バインディングジャーナルのディレクトリー。デフォルト値は
<broker_instance_dir>/data/bindings
です。 create-bindings-dir
-
このパラメーターの値を
true
に設定すると、ブローカーはbindings-directory
で指定された場所 (存在しない場合) にバインディングディレクトリーを自動的に作成します。デフォルト値はtrue
です。
6.1.4. JMS ジャーナルについて
JMS ジャーナルは、JMS キュー、トピック、接続ファクトリー、ならびにこれらのリソースの JNDI バインディングを含む JMS 関連のデータをすべて格納します。管理 API で作成された JMS リソースはこのジャーナルに永続化されますが、設定ファイルを介して設定されたリソースは永続化されません。ブローカーは、JMS が使用されている場合に のみ JMS ジャーナルを作成します。
JMS ジャーナルのファイルには activemq-jms
という接頭辞が付けられます。各ファイルには拡張子 .jms
があり、デフォルトサイズは 1048576 バイトです。
JMS ジャーナルはバインディングジャーナルと設定を共有します。
関連情報
- バインディングジャーナルの詳細は、「バインディングジャーナルについて」 を参照してください。
6.1.5. ジャーナル保持の設定
AMQ Broker は、作成された各ジャーナルファイルコピーを保持するように設定することができます。ジャーナル保持を設定した後、ジャーナルファイルコピーでメッセージを再生して、メッセージをブローカーに送信できます。
6.1.5.1. ジャーナル保持の設定
AMQ Broker は、ジャーナルファイルコピーを特定の期間、またはストレージの制限に達するまで、あるいはその両方について保持するように設定できます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
core
要素内に、journal-retention-directory
属性を追加します。ジャーナルファイルの保持を制御するために、period
またはstorage-limit
、あるいはその両方を指定します。さらに、ジャーナルファイルコピー用のファイルシステムの場所を指定します。次の例では、AMQ Broker が、ジャーナルファイルコピーをdata/retention
ディレクトリーに7
日間、またはファイルが10GB
のストレージを使用するまで保持するように設定します。
<configuration> <core> ... <journal-retention-directory period="7" unit="DAYS" storage-limit="10G">data/retention</journal-retention-directory> ... </core> </configuration>
period
- ジャーナルファイルコピーを保持する期間。期間が終了すると、AMQ Broker は指定された期間より古いファイルを削除します。
unit
-
保持期間に適用する測定単位。デフォルト値は
DAYS
です。その他の有効な値は、HOURS
、MINUTES
、SECONDS
です。 directory
- ジャーナルファイルコピーのファイルシステムの場所。指定されたディレクトリーは <broker_instance_dir> ディレクトリーに対して相対的です。
storage-limit
- すべてのジャーナルファイルコピーで使用できる最大ストレージ。ストレージの制限に達した場合、ブローカーは最も古いジャーナルファイルを削除して、新しいジャーナルファイルコピーのためのスペースを提供します。ストレージ制限を設定することは、ジャーナルファイルの保持によってブローカーがディスク容量を使い果たしてシャットダウンしないようにするための効果的な方法です。
6.1.5.2. ブローカー上に存在するアドレスのジャーナルファイルコピーのメッセージの再生
ジャーナルファイルコピーから再生したいメッセージのアドレスが AMQ Broker 上に存在する場合、以下の手順でメッセージを再生してください。ブローカーにある元のアドレス、または別のアドレスにメッセージを再生することができます。
手順
- AMQ Management Console にログインします。詳細については、AMQ 管理コンソールへのアクセス を参照してください。
- メインメニューの Artemis をクリックします。
- フォルダーツリーで、addresses をクリックすると、アドレスの一覧が表示されます。
- Addresses タブをクリックします。
- メッセージを再生するアドレスの Action 列で、operations をクリックします。
再生操作を選択します。
- 再生操作で、すべてのジャーナルファイルコピーで再生するメッセージを検索する場合は、replay(String,String) 操作をクリックしてください。
- 再生操作で、特定の期間内に作成されたジャーナルファイルコピーでのみ再生するメッセージを検索する場合は、replay(String,String, String,String) 操作を選択します。startScanDate および endScanDate フィールドで、期間を指定します。
再生オプションを指定します。
- target フィールドで、再生されたメッセージを送信するブローカー上のアドレスを指定します。このフィールドを空白にすると、メッセージはブローカー上の元のアドレスに再生されます。
-
(オプション) filter フィールドで、フィルター文字列に一致するメッセージのみを再生する文字列を指定します。たとえば、メッセージに storeID プロパティーがある場合、
storeID="1000"
のフィルターを使用して、ストア ID 値が 1000 のすべてのメッセージを再生できます。フィルターを指定しない場合、スキャンされたジャーナルファイルコピーのすべてのメッセージが AMQ Broker に再生されます。
- Execute をクリックします。
関連情報
- AMQ 管理コンソールの使用の詳細については、AMQ 管理コンソールの使用 を参照してください。
6.1.5.3. ブローカーから削除されたアドレスのジャーナルファイルコピーでのメッセージの再生
ジャーナルファイルコピーから再生したいメッセージのアドレスが AMQ Broker から削除された場合、以下の手順を使用して、ブローカーの別のアドレスにメッセージを再生します。
手順
- AMQ Management Console にログインします。詳細については、AMQ 管理コンソールへのアクセス を参照してください。
- メインメニューの Artemis をクリックします。
- フォルダーツリーで、トップレベルのサーバーをクリックします。
- Operations タブをクリックします。
再生操作を選択します。
- 再生操作で、すべてのジャーナルファイルコピーで再生するメッセージを検索する場合は、replay(String,String,String) 操作をクリックしてください。
- 再生操作で、特定期間内に作成されたジャーナルファイルコピーでのみ再生するメッセージを検索する場合は、replay(String,String, String,String,String) 操作を選択してください。startScanDate および endScanDate フィールドで、期間を指定します。
再生オプションを指定します。
- アドレス フィールドには、再生するメッセージのアドレスを指定します。
- target フィールドで、再生されたメッセージを送信するブローカー上のアドレスを指定します。
-
(オプション) filter フィールドで、フィルター文字列に一致するメッセージのみを再生する文字列を指定します。たとえば、メッセージに storeID プロパティーがある場合、
storeID="1000"
のフィルターを使用して、ストア ID 値が 1000 のすべてのメッセージを再生できます。フィルターを指定しない場合、スキャンされたジャーナルファイルコピーのすべてのメッセージが AMQ Broker に再生されます。
- Execute をクリックします。
関連情報
- AMQ 管理コンソールの使用の詳細については、AMQ 管理コンソールの使用 を参照してください。
6.1.6. ジャーナルファイルの圧縮
AMQ Broker には、ジャーナルからデッド領域を削除し、データの圧縮解除によりディスク領域が少なくなるようにする圧縮アルゴリズムが含まれています。
以下のサブセクションでは、以下の方法を示しています。
6.1.6.1. ジャーナルファイル圧縮の設定
ブローカーは以下の基準を使用して、圧縮を開始するタイミングを決定します。
- ジャーナル用に作成されたファイルの数。
- ジャーナルファイルのライブデータの割合。
これらの基準に設定された値に達した後、圧縮プロセスはジャーナルを解析し、デッドレコードをすべて削除します。そのため、ジャーナルにはファイルが少なくなります。
以下の手順は、ジャーナルファイルコンパクション にブローカーを設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内にjournal-compact-min-files
パラメーターおよびjournal-compact-percentage
パラメーターを追加し、値を指定します。以下に例を示します。<configuration> <core> ... <journal-compact-min-files>15</journal-compact-min-files> <journal-compact-percentage>25</journal-compact-percentage> ... </core> </configuration>
journal-compact-min-files
-
圧縮の開始前にブローカーが最小限作成する必要のあるジャーナルファイル数。デフォルト値は
10
です。値を0
に設定すると、圧縮が無効になります。ジャーナルのサイズが無限に増加する可能性があるため、コンパクションの無効化に注意する必要があります。 journal-compact-percentage
-
ジャーナルファイルのライブデータの割合。この割合より少ない場合にはライブデータとみなされ、 (
journal-compact-min-files
の設定値に達した場合)、圧縮が開始されます。デフォルト値は30
です。
6.1.6.2. コマンドラインインターフェイスからの圧縮の実行
以下の手順では、コマンドラインインターフェイス (CLI) を使用してジャーナルファイルを圧縮する方法を説明します。
手順
<broker_instance_dir>
ディレクトリーの所有者として、ブローカーを停止します。以下の例は、ユーザーamq-broker
を示しています。su - amq-broker cd <broker_instance_dir>/bin $ ./artemis stop
(オプション) 以下の CLI コマンドを実行して、データツールのパラメーターの全リストを取得します。デフォルトでは、このツールは
<broker_instance_dir>/etc/broker.xml
にある設定を使用します。$ ./artemis help data compact.
以下の CLI コマンドを実行して、データを圧縮します。
$ ./artemis data compact.
ツールがデータを正常に圧縮したら、ブローカーを再起動します。
$ ./artemis run
関連情報
- AMQ Broker には、ジャーナルファイル管理用の CLI コマンドが多数含まれています。詳細は、付録の コマンドラインツール を参照してください。
6.1.7. ディスク書き込みキャッシュの無効化
ほとんどのディスクには、ハードウェア書き込みキャッシュが含まれます。書き込みキャッシュは、後でディスクに遅延書き込みされるため、ディスクの見かけのパフォーマンスを向上させることができます。多くのシステムでは、ディスク書き込みキャッシュがデフォルトで有効になっています。つまり、オペレーティングシステムから同期した後であっても、データが実際にディスクに書き込まれる保証はありません。したがって障害が発生した場合は、重大なデータが失われることがあります。
一部の高価なディスクには、非揮発性、またはバッテリー駆動の書き込みキャッシュがあります。これらを使用した場合は、障害発生時に必ずしもデータが失われるわけではありませんが、テストが必要になります。ディスクにこのような機能がない場合は、書き込みキャッシュを必ず無効にする必要があります。ディスク書き込みキャッシュを無効にすると、パフォーマンスに悪影響を及ぼす可能性があることに注意してください。
以下の手順は、Windows 上の Linux でディスク書き込みキャッシュを無効にする方法を示しています。
手順
-
Linux で、ディスク書き込みキャッシュ設定を管理するには、
hdparm
(IDE ディスクの場合) またはsdparm
またはsginfo
(SDSI/SATA ディスクの場合) ツールを使用します。 - Windows でディスクライターキャッシュ設定を管理するには、ディスクを右クリックします。Properties を選択します。
6.2. データベースのメッセージデータの永続化
メッセージのデータをデータベースで永続化すると、ブローカーは Java Database Connectivity (JDBC) 接続を使用して、メッセージおよびバインディングデータをデータベーステーブルに保存します。テーブルのデータは AMQ Broker ジャーナルエンコーディングを使用してエンコードされます。サポートされるデータベースの詳細は、Red Hat カスタマーポータルの Red Hat AMQ 7 Supported Configurations を参照してください。
管理者は、組織の IT インフラストラクチャーの要件に基づいて、メッセージデータをデータベースに保管できます。ただし、データベースを使用すると、メッセージングシステムのパフォーマンスに悪影響を及ぼす可能性があります。具体的には、JDBC 経由でメッセージングデータをデータベーステーブルに書き込むと、ブローカーのパフォーマンスに大きなオーバーヘッドが発生します。
6.2.1. JDBC 永続性の設定
以下の手順では、メッセージおよびバインディングデータをデータベーステーブルに保存するようにブローカーを設定する方法を説明します。
手順
-
適切な JDBC クライアントライブラリーをブローカーランタイムに追加します。これを実行するには、関連する
.jar
ファイルを<broker_instance_dir>/lib
ディレクトリーに追加します。 -
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内に、database-store
要素が含まれるstore
要素を追加します。<configuration> <core> <store> <database-store> </database-store> </store> </core> </configuration>
database-store
要素内に JDBC 永続化の設定パラメーターを追加し、値を指定します。以下に例を示します。<configuration> <core> <store> <database-store> <jdbc-connection-url>jdbc:oracle:data/oracle/database-store;create=true</jdbc-connection-url> <jdbc-user>ENC(5493dd76567ee5ec269d11823973462f)</jdbc-user> <jdbc-password>ENC(56a0db3b71043054269d11823973462f)</jdbc-password> <bindings-table-name>BIND_TABLE</bindings-table-name> <message-table-name>MSG_TABLE</message-table-name> <large-message-table-name>LGE_TABLE</large-message-table-name> <page-store-table-name>PAGE_TABLE</page-store-table-name> <node-manager-store-table-name>NODE_TABLE</node-manager-store-table-name> <jdbc-driver-class-name>oracle.jdbc.driver.OracleDriver</jdbc-driver-class-name> <jdbc-network-timeout>10000</jdbc-network-timeout> <jdbc-lock-renew-period>2000</jdbc-lock-renew-period> <jdbc-lock-expiration>20000</jdbc-lock-expiration> <jdbc-journal-sync-period>5</jdbc-journal-sync-period> <jdbc-max-page-size-bytes>100K</jdbc-max-page-size-bytes> </database-store> </store> </core> </configuration>
- jdbc-connection-url
- データベースサーバーの完全な JDBC 接続 URL。接続 URL には、すべての設定パラメーターとデータベース名が含まれている必要があります。
- jdbc-user
- データベースサーバー用に暗号化されたユーザー名。設定ファイルで使用するユーザー名とパスワードの暗号化に関する詳細は、「設定ファイルのパスワードの暗号化」 を参照してください。
- jdbc-password
- データベースサーバー用に暗号化されたパスワード。設定ファイルで使用するユーザー名とパスワードの暗号化に関する詳細は、「設定ファイルのパスワードの暗号化」 を参照してください。
- bindings-table-name
- データのバインディングが保存されるテーブルの名前。テーブル名を指定すると、干渉なしに複数のサーバー間で単一のデータベースを共有できます。
- message-table-name
- メッセージデータが保存されるテーブルの名前。このテーブル名を指定すると、干渉なしに複数のサーバー間で単一のデータベースを共有できます。
- large-message-table-name
- サイズの大きいメッセージと関連データが永続化されるテーブルの名前。さらに、クライアントがサイズの大きいメッセージをチャンクでストリーミングする場合に、チャンクはこのテーブルに保存されます。このテーブル名を指定すると、干渉なしに複数のサーバー間で単一のデータベースを共有できます。
- page-store-table-name
- ページストアディレクトリー情報が格納されるテーブルの名前。このテーブル名を指定すると、干渉なしに複数のサーバー間で単一のデータベースを共有できます。
- node-manager-store-table-name
- 共有ストア高可用性 (HA) がライブおよびバックアップブローカー向けにロックされ、他の HA 関連のデータがブローカーサーバーに保存されているテーブルの名前。このテーブル名を指定すると、干渉なしに複数のサーバー間で単一のデータベースを共有できます。共有ストア HA を使用する各ライブ/バックアップペアは、同じテーブル名を使用する必要があります。複数の (および関連性のない) ライブ/バックアップペア間で同じテーブルを共有できません。
- jdbc-driver-class-name
- JDBC データベースドライバーの完全修飾クラス名。サポートされるデータベースの詳細は、Red Hat カスタマーポータルの Red Hat AMQ 7 Supported Configurations を参照してください。
- jdbc-network-timeout
-
JDBC ネットワーク接続のタイムアウト (ミリ秒単位)。デフォルト値は 20000 ミリ秒です。共有ストア HA に JDBC を使用する場合は、
jdbc-lock-expiration
未満の値にタイムアウトを設定することが推奨されます。 - jdbc-lock-renew-period
-
現在の JDBC ロックの更新期間の長さ (ミリ秒単位)。この時間が経過すると、ブローカーはロックを更新できます。
jdbc-lock-expiration
の値の数分の 1 の値を設定することを推奨します。これにより、ブローカーはリースを延長するのに十分な時間を確保でき、接続に問題が発生した場合にブローカーがロックの更新を試みる時間を確保できます。デフォルト値は 2000 ミリ秒です。 - jdbc-lock-expiration
jdbc-lock-renew-period
の値が経過した場合でも、現在の JDBC ロックが所有 ( 取得または更新 ) されているとみなされる時間 ( ミリ秒単位 )。ブローカーは、
jdbc-lock-renew-period
の値に従って、所有するロックの定期更新を試みます。ブローカーがロックの更新に 失敗 した場合 ( 接続の問題などにより )、ブローカーはロックが最後に正常に取得または更新されてからjdbc-lock-expiration
の値が経過するまでロックの更新を試み続けます。上記の更新動作の例外は、別のブローカーがロックを取得する場合です。これは、Database Management System (DBMS) とブローカー間の時間の不整合が発生した場合や、ガベージコレクションの一時停止期間が長い場合に発生する可能性があります。この場合、最初にロックを所有していたブローカーは、ロックが失われたと判断し、更新を試行しません。
有効期限の経過後、現在 JDBC ロックを所有しているブローカーによって JDBC ロックが更新されない場合、別のブローカーが JDBC ロックを確立できます。
jdbc-lock-expiration
のデフォルト値は 20000 ミリ秒です。- jdbc-journal-sync-period
- ブローカージャーナルが JDBC と同期する期間 ( ミリ秒単位 )。デフォルト値は 5 ミリ秒です。
- jdbc-max-page-size-bytes
-
AMQ Broker がメッセージを JDBC データベースで永続化するときの各ページファイルの最大サイズ (バイト単位)。デフォルト値は
102400
、つまり 100 KB です。指定する値は、K、MB、GB などのバイト表記もサポートします。
6.2.2. JDBC 接続プールの設定
JDBC 永続化のブローカーを設定した場合、ブローカーは JDBC 接続を使用してメッセージおよびバインディングデータをデータベーステーブルに保存します。
JDBC 接続が失敗した場合に、失敗時にアクティブな接続アクティビティー (データベースの読み取りや書き込みなど) がないことを確認した場合、ブローカーは実行中のままとなり、データベース接続の再確立を試みます。そのために、AMQ Broker は JDBC 接続プール を使用します。
通常、接続プール は、複数のアプリケーション間で共有できる指定のデータベースにオープン接続のセットを提供します。ブローカーの場合、ブローカーとデータベース間の接続に失敗すると、ブローカーはプールからの異なる接続を使用してデータベースへの再接続を試みます。プールは、ブローカーが受信する前に新しい接続をテストします。
以下の例は、JDBC 接続プールを設定する方法を示しています。
明示的に JDBC 接続プールを設定しない場合、ブローカーはデフォルト設定で接続プールを使用します。デフォルト設定では、既存の JDBC 設定の値が使用されます。詳細は、Default connection pooling configuration を参照してください。
前提条件
- この例は JDBC 永続性を設定する例をもとにしています。「JDBC 永続性の設定」 を参照してください。
接続プールを有効にするには、AMQ Broker は Apache Commons DBCP パッケージを使用します。ブローカーの JDBC 接続プールを設定する前に、このパッケージが提供する内容を理解する必要があります。詳細は以下を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 以前に JDBC 設定に追加した
database-store
要素内で、jdbc-driver-class-name
、jdbc-connection-url
、jdbc-user
、jdbc-password パラメーター
を削除します。この手順の後半で、これらの設定は、対応する DBCP 設定パラメーターに置き換えます。注記上記のパラメーターを明示的に削除しない場合には、この手順の後半で追加する対象の DBCP パラメーターが優先されます。
database-store
要素内にdata-source-properties
要素を追加します。以下に例を示します。<store> <database-store> <data-source-properties> </data-source-properties> <bindings-table-name>BINDINGS</bindings-table-name> <message-table-name>MESSAGES</message-table-name> <large-message-table-name>LARGE_MESSAGES</large-message-table-name> <page-store-table-name>PAGE_STORE</page-store-table-name> <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name> <jdbc-network-timeout>10000</jdbc-network-timeout> <jdbc-lock-renew-period>2000</jdbc-lock-renew-period> <jdbc-lock-expiration>20000</jdbc-lock-expiration> <jdbc-journal-sync-period>5</jdbc-journal-sync-period> </database-store> </store>
新しい
data-source-properties
要素内で、接続プールに DBCP データソースプロパティーを追加します。キーと値のペアを指定します。以下に例を示します。<store> <database-store> <data-source-properties> <data-source-property key="driverClassName" value="com.mysql.jdbc.Driver" /> <data-source-property key="url" value="jdbc:mysql://localhost:3306/artemis" /> <data-source-property key="username" value="ENC(5493dd76567ee5ec269d1182397346f)"/> <data-source-property key="password" value="ENC(56a0db3b71043054269d1182397346f)"/> <data-source-property key="poolPreparedStatements" value="true" /> <data-source-property key="maxTotal" value="-1" /> </data-source-properties> <bindings-table-name>BINDINGS</bindings-table-name> <message-table-name>MESSAGES</message-table-name> <large-message-table-name>LARGE_MESSAGES</large-message-table-name> <page-store-table-name>PAGE_STORE</page-store-table-name> <node-manager-store-table-name>NODE_MANAGER_STORE</node-manager-store-table-name> <jdbc-network-timeout>10000</jdbc-network-timeout> <jdbc-lock-renew-period>2000</jdbc-lock-renew-period> <jdbc-lock-expiration>20000</jdbc-lock-expiration> <jdbc-journal-sync-period>5</jdbc-journal-sync-period> </database-store> </store>
driverClassName
- JDBC データベースドライバーの完全修飾クラス名。
url
- データベースサーバーの完全な JDBC 接続 URL。
username
- データベースサーバー用に暗号化されたユーザー名。この値は、暗号化されていないプレーンテキストとして指定することもできます。設定ファイルで使用するユーザー名とパスワードの暗号化に関する詳細は、「設定ファイルのパスワードの暗号化」 を参照してください。
password
- データベースサーバー用に暗号化されたパスワード。この値は、暗号化されていないプレーンテキストとして指定することもできます。設定ファイルで使用するユーザー名とパスワードの暗号化に関する詳細は、「設定ファイルのパスワードの暗号化」 を参照してください。
poolPreparedStatements
-
このパラメーターの値を
true
に設定すると、プールには、無制限の準備済みキャッシュステートメントを追加できます。これにより、初期化コストが削減されます。 maxTotal
-
プールの最大接続数。このパラメーターの値を
-1
に設定すると、制限はありません。
明示的に JDBC 接続プールを設定しない場合、ブローカーはデフォルト設定で接続プールを使用します。デフォルト設定は、表で説明されています。
DBCP 設定パラメーター | デフォルト値 |
---|---|
|
既存の |
|
既存の |
|
既存の |
|
既存の |
|
|
|
|
再接続は、クライアントがブローカーにメッセージを送信していない場合に のみ 機能します。再接続時にデータベーステーブルへの書き込みを試みると、ブローカーは失敗し、シャットダウンします。
関連情報
- AMQ Broker でサポートされるデータベースの詳細は、Red Hat カスタマーポータルの Red Hat AMQ 7 Supported Configurations を参照してください。
- Apache Commons DBCP パッケージで利用可能なすべての設定オプションについては、Apache Commons DBCP Configuration Parameters を参照してください。
6.3. 永続性の無効化
場合によっては、メッセージングシステムがデータを保存し ない という要件がある可能性があります。このような状況では、ブローカーで永続性を無効にすることができます。
以下の手順では、永続性を無効にする方法を示します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内で、persistence-enabled
パラメーターの値をfalse
に設定します。<configuration> <core> ... <persistence-enabled>false</persistence-enabled> ... </core> </configuration>
メッセージデータ、バインディングデータ、大きなメッセージデータ、重複 ID キャッシュ、またはページングデータは永続化されません。
第7章 アドレスのメモリー使用量の設定
AMQ Broker は、ブローカーをホストするマシンが制限されたメモリーで実行されている場合でも、数百万のメッセージが含まれる膨大なキューを透過的にサポートします。
このような状況では、すべてのキューを 1 度にメモリーに保存できない可能性があります。超過したメモリー消費から保護するため、ブローカーの各アドレスに許可される最大メモリー使用量を設定できます。さらに、アドレスのメモリー使用量が設定された制限に達したときに、次のいずれかのアクションを実行するようにブローカーを設定できます。
- メッセージをページ化
- メッセージを通知せずに破棄
- メッセージを破棄および送信クライアントへ通知
- クライアントのメッセージ送信をブロック
アドレスの最大メモリー使用量に達したときにメッセージをページングするようにブローカーを設定する場合、特定のアドレスの制限を次のように設定できます。
- 受信メッセージのページングに使用されるディスク容量を制限する
- クライアントがメッセージを消費する準備ができたときに、ブローカーがディスクからメモリーに転送するページングされたメッセージに使用されるメモリーを制限します。
また、ディスク使用量のしきい値を設定して、設定されているすべてのページング制限をオーバーライドすることもできます。ディスク使用量のしきい値に達すると、ブローカーはページングを停止し、すべての受信メッセージをブロックします。
トランザクションを使用すると、ブローカーはトランザクションの一貫性を確保するために追加のメモリーを割り当てる可能性があります。この場合、ブローカーによって報告されるメモリー使用量は、メモリーで使用される合計バイト数を反映しない可能性があります。そのため、指定された最大メモリー使用量に基づいてメッセージをページ化、破棄、またはブロックするようにブローカーを設定する場合、トランザクションも使用しないでください。
7.1. メッセージのページングの設定
最大メモリー使用量制限が指定されたアドレスに対して、使用量制限に達した際にブローカーが実行するアクションを指定することもできます。設定可能なオプションの 1 つが ページング です。
ページングオプションを設定する場合は、アドレスの最大サイズに達すると、ブローカーは、ディスク上のそのアドレスのメッセージを、ページファイル と呼ばれるファイルに保存します。各ページファイルには設定可能な最大サイズがあります。この方法で設定する各アドレスには、ページ化されたメッセージを格納するためにファイルシステム内に専用のフォルダーがあります。
キューのメッセージを検査する際に、キューブラウザーとコンシューマーの両方がページファイルに移動できます。ただし、非常に特殊なフィルターを使用しているコンシューマーは、キュー内の既存のメッセージが最初に消費されるまで、ページファイルに保存されているメッセージを消費できない可能性があります。たとえば、コンシューマーフィルターに "color='red'"
などの文字列式が含まれているとします。この条件を満たすメッセージがプロパティー "color='blue'"
の 100 万メッセージに従う場合、コンシューマーは "color='blue'"
のメッセージが最初に消費されるまで、メッセージを消費できません。
ブローカーは、クライアントが消費する準備ができたときに、ディスクからメモリーにメッセージを転送 ( 非ページ化 ) します。ファイルのすべてのメッセージが確認されると、ブローカーはディスクからページファイルを削除します。
以下の手順は、メッセージのページングを設定する方法を示しています。
7.1.1. ページングディレクトリーの指定
以下の手順では、ページングディレクトリーの場所を指定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内にpaging-directory
要素を追加します。ファイルシステムのページングディレクトリーの場所を指定します。<configuration ...> <core ...> ... <paging-directory>/path/to/paging-directory</paging-directory> ... </core> </configuration>
その後ページング用に設定するアドレスごとに、ブローカーは指定したページングディレクトリーに専用のディレクトリーを追加します。
7.1.2. ページングのアドレスの設定
以下の手順では、ページング用のアドレスを設定する方法を説明します。
前提条件
- アドレスおよびアドレス設定の設定方法を理解している。詳細は、4章アドレスおよびキューの設定 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一致するアドレスまたはアドレス セット 用に設定した
address-setting
要素の場合は、設定要素を追加して最大メモリー使用量を指定し、ページング動作を定義します。以下に例を示します。<address-settings> <address-setting match="my.paged.address"> ... <max-size-bytes>104857600</max-size-bytes> <max-size-messages>20000</max-size-messages> <page-size-bytes>10485760</page-size-bytes> <address-full-policy>PAGE</address-full-policy> ... </address-setting> </address-settings>
max-size-bytes
-
ブローカーが
address-full-policy
属性に指定されたアクションを実行する前に、アドレスに許可されるメモリーの最大サイズ (バイト単位)。デフォルト値は-1
で、制限がないことを意味します。指定する値は、K、MB、GB などのバイト表記もサポートします。 max-size-messages
-
ブローカーが
address-full-policy
属性に指定されたアクションを実行する前に、アドレスに許可されるメッセージの最大数。デフォルト値は -1 で、メッセージ制限がないことを意味します。 page-size-bytes
-
ページングシステムで使用される各ページファイルのサイズ ( バイト単位 )。デフォルト値は
10485760
( つまり 10 MiB ) です。指定する値は、K、MB、GB などのバイト表記もサポートします。 address-full-policy
アドレスの最大サイズに達したときにブローカーが実行するアクション。デフォルト値は
PAGE
です。有効な値は以下のとおりです。PAGE
- ブローカーは、追加のメッセージをディスクにページングします。
DROP
- ブローカーは追加のメッセージを通知せずに破棄します。
FAIL
- ブローカーは、クライアントメッセージプロデューサーに対して追加のメッセージおよび例外をドロップします。
BLOCK
- 追加のメッセージを送信しようとすると、クライアントメッセージプロデューサーがブロックされます。
max-size-bytes
属性とmax-size-message
属性に制限を設定した場合、いずれかの制限に達すると、ブローカーはaddress-full-policy
属性に指定されたアクションを実行します。前の例の設定では、メモリー内のアドレスのメッセージの合計が 20,000 を超えるか、使用可能なメモリーを 104857600 バイト使用すると、ブローカーはmy.paged.address
アドレスのメッセージのページングを開始します。前述の例に示されて いない 追加のページング設定要素は以下のとおりです。
page-sync-timeout
-
定期的なページ同期の間隔 ( ナノ秒単位 )。非同期 IO ジャーナルを使用している場合 ( つまり、
journal-type
がbroker.xml
設定ファイルでASYNCIO
に設定されている場合 )、デフォルト値は3333333
です。標準の Java NIO ジャーナルを使用している場合 (journal-type
がNIO
に設定されている場合 )、デフォルト値はjournal-buffer-timeout
パラメーターの設定済みの値です。
前述の例では、my.paged.address
アドレスに送信されたメッセージがメモリーの 104857600 バイトを超えると、ブローカーはページングを開始します。
address-setting
要素で max-size-bytes
を指定すると、一致する 各 アドレスに値が適用されます。この値を指定すると、一致するすべてのアドレスの 合計 サイズが max-size-bytes
の値に制限されるわけでは ありません。
7.1.3. グローバルページングサイズの設定
たとえば、ブローカーで使用パターンが異なるアドレスを多数管理する場合など、アドレスごと のメモリー制限の設定は実用的ではない場合があります。このような状況では、グローバルメモリー制限を指定できます。グローバル制限は、ブローカーがすべてのアドレスに使用できるメモリーの 合計 量です。このメモリー制限に達すると、ブローカーは、新しい各受信メッセージに関連付けられたアドレスの address-full-policy
属性に指定されたアクションを実行します。
以下の手順では、グローバルページングサイズを設定する方法を説明します。
前提条件
- ページングのアドレスの設定方法を理解している必要があります。詳細は、「ページングのアドレスの設定」 を参照してください。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内にglobal-max-size
要素を追加し、値を指定します。以下に例を示します。<configuration> <core> ... <global-max-size>1GB</global-max-size> <global-max-messages>900000</global-max-messages> ... </core> </configuration>
global-max-size
ブローカーがすべてのアドレスに使用できるメモリーの合計量 ( バイト単位 )。この制限に達すると、ブローカーは各受信メッセージに関連付けられたアドレスの
address-full-policy
属性に指定されたアクションを実行します。global-max-size
のデフォルト値は、ブローカーをホストする Java 仮想マシン (JVM) で利用可能な最大メモリーの半分です。global-max-size
の値はバイト単位ですが、バイト表記にも対応します ( 例 : "K"、"Mb"、"GB")。上記の例では、ブローカーはメッセージの処理時に利用可能な最大 1 ギガバイトのメモリーを使用するように設定されています。
global-max-messages
すべてのアドレスに許可されるメッセージの合計数。この制限に達すると、ブローカーは各受信メッセージに関連付けられたアドレスの
address-full-policy
属性に指定されたアクションを実行します。デフォルト値は -1 で、メッセージ制限がないことを意味します。global-max-size
属性とglobal-max-messages
属性に制限を設定した場合、いずれかの制限に達すると、ブローカーはaddress-full-policy
属性に指定されたアクションを実行します。前の例の設定では、メモリー内のメッセージ数が 900,000 を超えるか、使用可能なメモリーが 1 GB を使用すると、ブローカはすべてのアドレスに対してメッセージのページングを開始します。注記max-size-bytes
属性またはmax-size-message
属性を使用して個々のアドレスに設定された制限が、global-max-size
属性またはglobal-max-messages
属性に設定された制限よりも先に達した場合、ブローカーはそのアドレスのaddress-full-policy
属性に指定されたアクションを実行します。
ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
7.1.4. 特定のアドレスのページング中のディスク使用量を制限する
ブローカーが個々のアドレスまたはアドレスのセットに対する受信メッセージのページングを停止する前に、ブローカーが使用できるディスク領域の量を制限できます。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内に属性を追加して、ディスク使用量またはメッセージ数、あるいはその両方に基づいてページング制限を指定し、いずれかの制限に達した場合に実行するアクションを指定します。以下に例を示します。<address-settings> <address-setting match="match="my.paged.address""> ... <page-limit-bytes>10G</page-limit-bytes> <page-limit-messages>1000000</page-limit-messages> <page-full-policy>FAIL</page-full-policy> ... </address-setting> </address-settings>
page-limit-bytes
-
ブローカーが
page-full-policy
属性に指定されたアクションを実行する前に、アドレスの受信メッセージをページングするために許可されるディスク領域の最大サイズ (バイト単位)。指定する値は、K、MB、GB などのバイト表記をサポートしています。デフォルト値は -1 で、制限がないことを意味します。 page-limit-messages
-
ブローカーが
page-full-policy
属性に指定されたアクションを実行する前に、アドレスに対してページングできる受信メッセージの最大数。デフォルト値は -1 で、メッセージ制限がないことを意味します。 page-full-policy
アドレスが
page-limit-bytes
属性またはpage-limit-messages
属性で設定された制限に達したときにブローカーが実行するアクション。有効な値は以下のとおりです。DROP ブローカーは、それ以降のメッセージをサイレントにドロップします。
FAIL ブローカーはそれ以上のメッセージを削除し、送信側クライアントに通知します。
前述の例では、ページングで 10GB のディスク領域が使用されるか、合計 100 万個のメッセージがページングされるまで、ブローカーは
my.paged.address
アドレスのメッセージをページングします。
ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
7.1.5. ページングされたメッセージのメモリーへのフローの制御
AMQ Broker がメッセージをディスクにページングするように設定されている場合、ブローカーはページングされたメッセージを読み取り、クライアントがメッセージを消費する準備ができたときにメッセージをメモリーに転送します。メッセージが過剰なメモリーを消費しないように、ブローカーがディスクからメモリーに転送するメッセージの各アドレスで使用されるメモリーを制限できます。
クライアントアプリケーションが、完了通知待ちのメッセージをあまりにも多く残す場合、ブローカーは保留中のメッセージが承認されるまでページングされたメッセージを読み取らないため、ブローカー上でメッセージ枯渇が発生する可能性があります。
たとえば、ページングされたメッセージのメモリーへの転送の制限 (デフォルトでは 20MB) に達すると、ブローカーはそれ以上のメッセージを読み取る前にクライアントからの確認応答を待ちます。同時に、クライアントがブローカーに確認応答を送信する前に十分なメッセージの受信を待機している場合 (クライアントが使用するバッチサイズによって決まります)、ブローカーはメッセージが不足します。
枯渇を回避するには、メモリーへのページングメッセージの転送を制御するブローカーの制限を増やすか、配信メッセージの数を減らします。クライアントがメッセージ確認応答をより早くコミットするか、タイムアウトを使用してブローカーからメッセージを受信しなくなったときに確認応答をコミットするようにすることで、配信メッセージの数を減らすことができます。
配信メッセージの数とサイズは、AMQ 管理コンソールのキューの Delivering Count
メトリクスと Delivering Bytes
メトリクスで確認できます。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 -
一致するアドレスまたはアドレスのセットに対して設定した
address-settings
要素については、ページングされたメッセージのメモリーへの転送に対する制限を指定します。以下に例を示します。
address-settings> <address-setting match="my.paged.address"> ... <max-read-page-messages>104857600</max-read-page-messages> <max-read-page-bytes>20MB</max-read-page-bytes> ... </address-setting> </address-settings>
Max-read-page-messages
ブローカーがアドレスごとにディスクからメモリーに読み取ることができるページングメッセージの最大数。デフォルト値は -1 で、制限が適用されないことを意味します。
Max-read-page-bytes
ブローカーがアドレスごとにディスクからメモリーに読み取ることができるページングメッセージの最大サイズ (バイト単位)。デフォルト値は 20MB です。
max-read-page-messages
属性と max-read-page-bytes
属性の両方に制限を指定した場合、いずれかの制限に達すると、ブローカーはメッセージの読み取りを停止します。
7.1.6. ディスク使用量のしきい値の設定
ディスク使用量のしきい値を設定できます。しきい値に達すると、ブローカーはページングを停止し、すべての受信メッセージをブロックします。
手順
ブローカーを停止します。
Linux の場合:
<broker_instance_dir>/bin/artemis stop
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe stop
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内にmax-disk-usage
設定要素を追加し、値を指定します。以下に例を示します。<configuration> <core> ... <max-disk-usage>80</max-disk-usage> ... </core> </configuration>
max-disk-usage
ブローカーが使用できる利用可能なディスク領域の最大パーセンテージ。この制限に達すると、ブローカーは受信メッセージをブロックします。デフォルト値は
90
です。前述の例では、ブローカーは利用可能なディスク領域の 80 パーセントの使用に制限されています。
ブローカーを起動します。
Linux の場合:
<broker_instance_dir>/bin/artemis run
Windows の場合:
<broker_instance_dir>\bin\artemis-service.exe start
7.2. メッセージドロップの設定
「ページングのアドレスの設定」 では、ページングのアドレスの設定方法を示します。この手順の一環として、 address-full-policy
の値を PAGE
に設定します。
アドレスが指定された最大サイズに達した際に ( ページングではなく ) メッセージを ドロップ するには、address-full-policy
の値を以下のいずれかに設定します。
DROP
- 指定のアドレスの最大サイズに達すると、ブローカーは追加のメッセージを通知せずにドロップします。
FAIL
- 特定のアドレスの最大サイズに達すると、ブローカーは追加のメッセージを削除し、プロデューサーに例外を発行します。
7.3. メッセージブロックの設定
以下の手順では、指定のアドレスが指定した最大サイズ制限に達した際に、メッセージブロックを設定する方法を説明します。
メッセージブロックは、Core、OpenWire、および AMQP プロトコルに対して のみ 設定できます。
7.3.1. Core および OpenWire プロデューサーのブロック
以下の手順は、指定のアドレスが指定した最大サイズ制限に達した際の、Core および OpenWire メッセージプロデューサーのメッセージブロックを設定する方法を示しています。
前提条件
- アドレスおよびアドレス設定の設定方法を理解している。詳細は、4章アドレスおよびキューの設定 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一致するアドレスまたはアドレス セット 用に設定した
address-setting
要素の場合は、メッセージブロック動作を定義する設定要素を追加します。以下に例を示します。<address-settings> <address-setting match="my.blocking.address"> ... <max-size-bytes>300000</max-size-bytes> <address-full-policy>BLOCK</address-full-policy> ... </address-setting> </address-settings>
max-size-bytes
ブローカーが
address-full-policy
に指定されたポリシーを実行する前に、アドレスに許可されるメモリーの最大サイズ ( バイト単位 )。指定する値は、K、MB、GB などのバイト表記もサポートします。注記address-setting
要素でmax-size-bytes
を指定すると、一致する 各 アドレスに値が適用されます。この値を指定すると、一致するすべてのアドレスの 合計 サイズがmax-size-bytes
の値に制限されるわけでは ありません。address-full-policy
- アドレスの最大サイズに達したときにブローカーが取るアクション。
上記の例では、アドレス
my.blocking.address
に送信されたメッセージがメモリーの 300000 バイトを超えると、ブローカーは Core または OpenWire メッセージプロデューサーからの追加のメッセージをブロックします。
7.3.2. AMQP プロデューサーのブロック
Core や OpenWire などのプロトコルは、ウィンドウサイズのフロー制御システムを使用します。このシステムでは、クレジットはバイトを表し、プロデューサーに割り当てられます。プロデューサーがメッセージを送信する場合、プロデューサーはメッセージのサイズに対して十分なクレジットがあるまで待機する必要があります。
対照的に、AMQP フロー制御のクレジットはバイトを表します。代わりに、AMQP クレジットは、メッセージサイズに関係なく、プロデューサーが送信できるメッセージの数を表します。そのため、AMQP プロデューサーがアドレスの max-size-bytes
の値を大幅に超過することがあります。
そのため、AMQP プロデューサーをブロックするには、別の設定要素 max-size-bytes-reject-threshold
を使用する必要があります。一致するアドレスまたはアドレスセットの場合、この要素はメモリーのすべての AMQP メッセージの最大サイズをバイト単位で指定します。メモリーのすべてのメッセージの合計サイズが指定の制限に達すると、ブローカーは AMQP プロデューサーが追加のメッセージを送信しなくなります。
以下の手順では、AMQP メッセージプロデューサーのメッセージブロックを設定する方法を説明します。
前提条件
- アドレスおよびアドレス設定の設定方法を理解している。詳細は、4章アドレスおよびキューの設定 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 一致するアドレスまたはアドレス セット に設定した
address-setting
要素の場合は、メモリーのすべての AMQP メッセージの最大サイズを指定します。以下に例を示します。<address-settings> <address-setting match="my.amqp.blocking.address"> ... <max-size-bytes-reject-threshold>300000</max-size-bytes-reject-threshold> ... </address-setting> </address-settings>
max-size-bytes-reject-threshold
ブローカーが AMQP メッセージをさらにブロックする前に、アドレスに許可されるメモリーの最大サイズ ( バイト単位 )。指定する値は、K、MB、GB などのバイト表記もサポートします。デフォルトでは、
max-size-bytes-reject-threshold
は-1
に設定されます。これは、最大サイズがないことを意味します。注記address-setting
要素でmax-size-bytes-reject-threshold
を指定する場合、値は一致する 各 アドレスに適用されます。この値を指定すると、一致するすべてのアドレスの 合計 サイズがmax-size-bytes-reject-threshold
の値に制限されるわけでは ありません。
上記の例では、my.amqp.blocking.address
アドレスに送信されたメッセージがメモリーの 300000 バイトを超えると、ブローカーは AMQP プロデューサーからの追加のメッセージをブロックし始めます。
7.4. マルチキャストアドレスでのメモリー使用量について
マルチキャストのキューがバインドされているアドレスへメッセージが転送されると、メッセージのコピーはメモリー内に 1 つだけ存在します。各キューにはメッセージへの 参照 のみがあります。このため、関連付けられたメモリーは、メッセージを参照する すべて のキューがメッセージを配信した後にのみ解放されます。
このような状況では、コンシューマーの速度が遅いと、アドレス全体がパフォーマンスに悪影響を及ぼす可能性があります。
たとえば、以下のシナリオについて考えてみましょう。
- アドレスには、マルチキャストルーティングタイプを使用する 10 個のキューがあります。
- 低速なコンシューマーにより、キューの 1 つがメッセージを配信しません。他の 9 つのキューは引き続きメッセージの配信を継続し、空になっています。
- メッセージはアドレスに到達し続けます。低速なコンシューマーを持つキューはメッセージへの参照を蓄積し続け、ブローカーはメッセージをメモリーに保持します。
- アドレスの最大サイズに達すると、ブローカーはメッセージのページングを開始します。
このシナリオでは、低速なコンシューマーが 1 つあるため、すべて のキューのコンシューマーはページシステムからメッセージを消費することが強制され、追加の IO が必要になります。
関連情報
- ブローカーとプロデューサーとコンシューマー間のデータのフローを調整するようにフロー制御を設定する方法は、AMQ Core Protocol JMS ドキュメントの Flow control を参照してください。
第8章 大きなメッセージの処理
クライアントは、ブローカーの内部バッファーのサイズを超える大きなメッセージを送信する可能性があり、予期せぬエラーが発生する可能性があります。この状態を回避するには、メッセージが指定の最小値よりも大きい場合にメッセージをファイルとして保存するようにブローカーを設定できます。このように大きなメッセージを処理すると、ブローカーはメモリー内にメッセージを保持しません。代わりに、ディスクまたはブローカーが大きなメッセージファイルを保存するデータベーステーブルのディレクトリーを指定します。
ブローカーがメッセージを大きなメッセージとして保存すると、キューは大きなメッセージディレクトリーまたはデータベーステーブルのファイルへの参照を保持します。
大規模なメッセージ処理は、Core Protocol、AMQP、OpenWire、および STOMP プロトコルで利用できます。
Core Protocol および OpenWire プロトコルの場合、クライアントは接続設定でメッセージの最小サイズを指定します。AMQP および STOMP プロトコルの場合は、ブローカー設定のプロトコルごとに定義されたアクセプターに大きなメッセージの最小サイズを指定します。
大きなメッセージを生成および消費するのに、異なるプロトコルを使用 しない ことが推奨されます。これには、ブローカーはメッセージの複数の変換を実行する必要がある場合があります。たとえば、AMQP プロトコルを使用してメッセージを送信し、OpenWire を使用して受信したいとします。この場合、ブローカーは最初に大きなメッセージのボディー全体を読み取り、Core プロトコルを使用するように変換する必要があります。次に、ブローカーは別の変換を実行し、今回は OpenWire プロトコルへ変換する必要があります。このようなメッセージ変換により、ブローカーに大きな処理のオーバーヘッドが発生します。
前述のプロトコルに指定した最小大きなメッセージサイズは、利用可能なディスク領域やメッセージのサイズなどのシステムリソースの影響を受けます。適切なサイズを決定するために、いくつかの値を使用してパフォーマンステストを実行することが推奨されます。
本セクションの手順では以下の方法を説明します。
- 大きなメッセージを格納するようにブローカーを設定します。
- 大きなメッセージ処理のための AMQP および STOMP プロトコルのアクセプター設定
このセクションでは、大きなメッセージと連携する AMQ Core Protocol および AMQ OpenWire JMS クライアントの設定に関する追加リソースへのリンクも提供します。
8.1. 大きなメッセージ処理のためのブローカーの設定
以下の手順では、ブローカーが大きなメッセージファイルを保存するディスクまたはデータベーステーブルにディレクトリーを指定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 ブローカーが大きなメッセージファイルを保存する場所を指定します。
ディスクに大きなメッセージを保存する場合は、
core
要素にlarge-messages-directory
パラメーターを追加し、ファイルシステムの場所を指定します。以下に例を示します。<configuration> <core> ... <large-messages-directory>/path/to/my-large-messages-directory</large-messages-directory> ... </core> </configuration>
注記large-messages-directory
の値を明示的に指定しない場合、ブローカーは<broker_instance_dir> /data/largemessages
のデフォルト値を使用します。大きなメッセージをデータベーステーブルに保存する場合は、
database-store
要素にlarge-message-table
パラメーターを追加して値を指定します。以下に例を示します。<store> <database-store> ... <large-message-table>MY_TABLE</large-message-table> ... </database-store> </store>
注記large-message-table
の値を明示的に指定しない場合、ブローカーはLARGE_MESSAGE_TABLE
のデフォルト値を使用します。
関連情報
- データベースストアの設定に関する詳細は、「データベースのメッセージデータの永続化」 を参照してください。
8.2. 大規模なメッセージ処理のための AMQP アクセプターの設定
以下の手順は、指定したサイズよりも大きい AMQP メッセージを大規模メッセージとして処理するように AMQP アクセプターを設定する方法を説明します。
手順
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。ブローカー設定ファイルのデフォルトの AMQP アクセプターは以下のようになります。
<acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor> ... </acceptors>
デフォルトの AMQP アクセプター ( または設定した別の AMQP アクセプター ) で、
amqpMinLargeMessageSize
プロパティーを追加し、値を指定します。以下に例を示します。<acceptors> ... <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300;amqpMinLargeMessageSize=204800</acceptor> ... </acceptors>
上記の例では、ブローカーはポート 5672 で AMQP メッセージを受け入れるように設定されます。
amqpMinLargeMessageSize
の値に基づいて、アクセプターが 204800 バイトよりも大きい AMQP メッセージ (200 キロバイト以上) を受信する場合、ブローカーはメッセージを大きなメッセージとして格納します。このプロパティーの値を明示的に指定しない場合、 ブローカーは 102400 (100 キロバイト) のデフォルト値を使用します。
-
amqpMinLargeMessageSize
を -1 に設定すると、AMQP メッセージに対するサイズの大きいメッセージ処理が無効になります。 -
ブローカーが
amqpMinLargeMessageSize
の値を超えない永続的な AMQP メッセージを受信する場合で、これがメッセージングジャーナルバッファーのサイズ (journal-buffer-size
設定パラメーターを使用して指定 ) を 超える 場合、ブローカーはメッセージをジャーナルに保存する前に大きな Core Protocol メッセージに変換します。
8.3. サイズの大きいメッセージ処理向けの STOMP アクセプターの設定
以下の手順は、指定したサイズよりも大きい STOMP メッセージをサイズの大きいメッセージとして処理するように STOMP アクセプターを設定する方法を説明します。
手順
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。ブローカー設定ファイルのデフォルトの AMQP アクセプターは以下のようになります。
<acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor> ... </acceptors>
デフォルトの STOMP アクセプター ( または設定した別の STOMP アクセプター ) で、
stompMinLargeMessageSize
プロパティーを追加し、値を指定します。以下に例を示します。<acceptors> ... <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true;stompMinLargeMessageSize=204800</acceptor> ... </acceptors>
前の例では、ブローカーはポート 61613 で STOMP メッセージを受け入れるように設定されています。stompMinLargeMessageSize
の値に基づいて、アクセプターが 204800 バイトよりも大きい STOMP メッセージ (200 キロバイト以上) を受信する場合、ブローカーはメッセージを大きなメッセージとして格納します。このプロパティーの値を明示的に指定しない場合、 ブローカーは 102400 (100 キロバイト) のデフォルト値を使用します。
大きなメッセージを STOMP コンシューマーに配信するために、ブローカーは自動的にメッセージを大きなメッセージから通常のメッセージに変換してからクライアントに送信します。大きなメッセージが圧縮されている場合、ブローカーはこれを STOMP クライアントに送信する前に圧縮します。
8.4. 大きなメッセージと Java クライアント
大きなメッセージを使用するクライアントを作成している Java 開発者には、2 つのオプションがあります。
1 つのオプションとして、InputStream
および OutputStream
のインスタンスを使用することができます。たとえば、FileInputStream
を使用して、物理ディスク上の大きなファイルから作成されたメッセージを送信します。その後、受信者が FileOutputStream
を使用して、メッセージをローカルファイルシステムの場所にストリーミングできます。
別のオプションとして、JMS BytesMessage
または StreamMessage
を直接ストリーミングする方法もあります。以下に例を示します。
BytesMessage rm = (BytesMessage)cons.receive(10000); byte data[] = new byte[1024]; for (int i = 0; i < rm.getBodyLength(); i += 1024) { int numberOfBytes = rm.readBytes(data); // Do whatever you want with the data }
関連情報
AMQ Core Protocol JMS クライアントでの大きなメッセージの使用方法は、以下を参照してください。
AMQ OpenWire JMS クライアントでの大きなメッセージの使用方法は、以下を参照してください。
-
大きなメッセージの例については、AMQ Broker インストールの
<install_dir> /examples/features/standard/
ディレクトリーのlarge-message
の例を参照してください。サンプルプログラムの実行の詳細については、AMQ Broker のサンプルの実行 を参照してください。
第9章 デッド接続の検出
クライアントが予期せずに停止し、それらのリソースをクリーンアップする機会がないことがあります。これが発生すると、リソースが faulty 状態のままになり、ブローカーがメモリー不足または他のシステムリソースで実行されている可能性があります。ブローカーは、ガベージコレクション時にクライアントの接続が適切にシャットダウンされなかったことを検出します。その後、コネクションは閉じられ、以下のようなメッセージがログに書き込まれます。ログは、クライアントセッションがインスタンス化されたコードの正確な行を取得します。これにより、エラーを特定し、これを修正できます。
[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.artemis.core.client.impl.DelegatingSession] I'm closing a JMS Conection you left open. Please make sure you close all connections explicitly before let
ting them go out of scope!
[Finalizer] 20:14:43,244 WARNING [org.apache.activemq.artemis.core.client.impl.DelegatingSession] The session you didn't close was created here:
java.lang.Exception
at org.apache.activemq.artemis.core.client.impl.DelegatingSession.<init>(DelegatingSession.java:83)
at org.acme.yourproject.YourClass (YourClass.java:666) 1
- 1
- 接続がインスタンス化されたクライアントコードの行。
9.1. 接続 Time-To-Live
クライアントとサーバー間のネットワーク接続に失敗してオンラインに戻る可能性があるため、AMQ Broker は非アクティブなサーバー側のリソースをクリーンアップします。この待機時間は Time-to-live (TTL) と呼ばれます。ネットワークベースの接続のデフォルトの TTL は 60000
ミリ秒 (1 分 ) です。in-VM 接続のデフォルトの TTL は -1
です。つまり、ブローカーはブローカー側で接続をタイムアウトしません。
ブローカーでの Time-To-Live の設定
クライアントが独自の接続 TTL を指定しないようにするには、ブローカー側でグローバル値を設定します。これは、ブローカー設定で connection-ttl-override
要素を指定して実行できます。
connection-ttl-check-interval
要素によって決定されるように、TTL 違反の接続をチェックするロジックはブローカーで定期的に実行されます。
手順
以下の例のように、
connection-ttl-override
設定要素を追加し、time-to-live の値を指定して<broker_instance_dir> /etc/broker.xml
を編集します。<configuration> <core> ... <connection-ttl-override>30000</connection-ttl-override> 1 <connection-ttl-check-interval>1000</connection-ttl-check-interval> 2 ... </core> </configuration>
9.2. 非同期接続実行の無効化
サーバー側で受信されたパケットの多くは、リモート
スレッドで実行されます。これらのパケットは短時間実行される操作を表し、パフォーマンス上の理由から常に リモーティング
スレッドで実行されます。ただし、一部のパケットタイプは リモーティング
スレッドではなくスレッドプールを使用して実行され、ネットワークのレイテンシーが少し追加されます。
スレッドプールを使用するパケットタイプは、以下に示す Java クラス内に実装されます。クラスはすべて org.apache.actiinvemq.artemis.core.protocol.core.impl.wireformat
パッケージにあります。
- RollbackMessage
- SessionCloseMessage
- SessionCommitMessage
- SessionXACommitMessage
- SessionXAPrepareMessage
- SessionXARollbackMessage
手順
非同期接続実行を無効にするには、以下の例のように
async-connection-execution-enabled
設定要素を<broker_instance_dir> /etc/broker.xml
に追加し、false
に設定します。デフォルト値はtrue
です。<configuration> <core> ... <async-connection-execution-enabled>false</async-connection-execution-enabled> ... </core> </configuration>
関連情報
- デッド接続を検出する AMQ Core Protocol JMS クライアントを設定する方法は、AMQ Core Protocol JMS ドキュメントの Detecting dead connections を参照してください。
- AMQ Core Protocol JMS クライアントで接続の存続時間を設定する方法については、AMQ Core Protocol JMS ドキュメントの Configuring time-to-live を参照してください。
第10章 重複メッセージの検出
複製メッセージを自動的に検出し、フィルタリングするようにブローカーを設定できます。つまり、独自の重複検出ロジックを実装する必要はありません。
重複検出がないと、予期しない接続障害が発生した場合、クライアントはブローカーに送信されたメッセージが受信されたかどうかを判断できません。この場合、クライアントはブローカーがメッセージを受信しなかったことを仮定し、再送信します。これにより、メッセージが複製されます。
たとえば、クライアントがブローカーにメッセージを送信するとします。ブローカーまたは接続がブローカーによって受信および処理される 前 に失敗すると、メッセージはそのアドレスに到達しません。失敗により、クライアントはブローカーから応答を受信しません。ブローカーによってメッセージが受信および処理された 後 にブローカーまたは接続が失敗すると、メッセージは正しくルーティングされますが、クライアントは応答を受信しません。
また、トランザクションを使用して成功を判断することは、必ずしも役立つとは限りません。トランザクションコミットの処理中にブローカーまたは接続が失敗する場合、クライアントはメッセージに正常に送信されたかどうかを判断できません。
このような状況では、クライアントが直近のメッセージを再送信して、想定された障害を修正します。その結果、システムに悪影響を及ぼす重複メッセージが表示される可能性があります。たとえば、注文可能なシステムでブローカーを使用している場合、重複メッセージは、発注書が 2 回処理されることを意味します。
以下の手順では、このような状況から保護するように重複メッセージ検出を設定する方法を説明します。
10.1. 重複 ID キャッシュの設定
ブローカーが重複メッセージを検出できるようにするには、プロデューサーは各メッセージの送信時にメッセージプロパティー _AMQ_DUPL_ID
に一意の値を提供する必要があります。ブローカーは、_AMQ_DUPL_ID
プロパティーの受信値のキャッシュを維持します。ブローカーがアドレスで新しいメッセージを受信すると、そのアドレスのキャッシュをチェックし、このプロパティーに同じ値でメッセージが処理されていないことを確認します。
各アドレスには独自のキャッシュがあります。各キャッシュのサイズは円形で固定されます。つまり、新しいエントリーはキャッシュ領域の要求に合わせて最も古いエントリーを置き換えます。
以下の手順では、ブローカーの各アドレスによって使用される ID キャッシュをグローバルに設定する方法を説明します。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内にid-cache-size
プロパティーおよびpersist-id-cache
プロパティーを追加し、値を指定します。以下に例を示します。<configuration> <core> ... <id-cache-size>5000</id-cache-size> <persist-id-cache>false</persist-id-cache> </core> </configuration>
id-cache-size
キャッシュ内の個別のエントリー数として指定される ID キャッシュの最大サイズ。デフォルト値は 20,000 エントリーです。この例では、キャッシュサイズは 5,000 エントリーに設定されます。
注記キャッシュの最大サイズに達すると、ブローカーが重複メッセージの処理を開始できます。たとえば、キャッシュのサイズを
3000
に設定するとします。以前のメッセージが、_AMQ_DUPL_ID
が同じ値を持つ新しいメッセージの到着前に 3,000 を 超える メッセージを受信すると、ブローカーは重複を検出できません。これにより、両方のメッセージがブローカーによって処理されます。persist-id-cache
-
このプロパティーの値を
true
に設定すると、ブローカーは ID の受信時にディスクに永続化します。デフォルト値はtrue
です。上記の例では、値をfalse
に設定して永続性を無効にします。
関連情報
- AMQ Core Protocol JMS クライアントを使用して重複 ID メッセージプロパティーを設定する方法は、AMQ Core Protocol JMS クライアントドキュメントの Using duplicate message detection を参照してください。
10.2. クラスター接続の複製検出の設定
クラスター接続を設定して、クラスター全体で移動するメッセージごとに重複 ID ヘッダーを挿入できます。
前提条件
- ブローカークラスターがすでに設定されている必要があります。詳細は、「ブローカークラスターの作成」 を参照してください。
手順
-
<broker_instance_dir>/etc/broker.xml
設定ファイルを開きます。 core
要素内に、指定のクラスター接続にuse-duplicate-detection
プロパティーを追加し、値を指定します。以下に例を示します。<configuration> <core> ... <cluster-connections> <cluster-connection name="my-cluster"> <use-duplicate-detection>true</use-duplicate-detection> ... </cluster-connection> ... </cluster-connections> </core> </configuration>
use-duplicate-detection
-
このプロパティーの値を
true
に設定すると、クラスターコネクションは、処理するメッセージごとに重複する ID ヘッダーを挿入します。
第11章 メッセージの傍受
AMQ Broker では、ブローカーに出入りするパケットを傍受して、パケットの監査やメッセージのフィルターを実行できます。インターセプターはインターセプトするパケットを変更できます。これにより、強力になりますが、潜在的に危険性があります。
ビジネス要件を満たすためのインターセプターを開発できます。インターセプターはプロトコル固有であるため、適切なインターフェイスを実装する必要があります。
インターセプターは、ブール値を返す intercept()
メソッドを実装する必要があります。値が true
の場合、メッセージパケットは続行されます。false
の場合、プロセスは中止され、他のインターセプターは呼び出されず、メッセージパケットはこれ以上処理されません。
11.1. インターセプターの作成
独自の受信インターセプターおよび発信インターセプターを作成できます。すべてのインターセプターはプロトコル固有で、サーバーに出入りするパケットに対して呼び出されます。これにより、監査パケットなどのビジネス要件を満たすインターセプターを作成できます。インターセプターは、傍受するパケットを変更できます。これにより、危険が伴います。そのため、注意して使用してください。
インターセプターとその依存関係は、ブローカーの Java クラスに配置する必要があります。<broker_instance_dir>/lib
ディレクトリーは、デフォルトでクラスパスに含まれているため、使用することができます。
手順
以下の例は、渡された各パケットのサイズをチェックするインターセプターを作成する方法を示しています。この例では、プロトコルごとに特定のインターフェイスを実装します。
適切なインターフェイスを実装し、その
intercept()
メソッドをオーバーライドします。AMQP プロトコルを使用している場合は、
org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor
インターフェイスを実装してください。package com.example; import org.apache.activemq.artemis.protocol.amqp.broker.AMQPMessage; import org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor; import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; public class MyInterceptor implements AmqpInterceptor { private final int ACCEPTABLE_SIZE = 1024; @Override public boolean intercept(final AMQPMessage message, RemotingConnection connection) { int size = message.getEncodeSize(); if (size <= ACCEPTABLE_SIZE) { System.out.println("This AMQPMessage has an acceptable size."); return true; } return false; } }
Core Protocol を使用している場合、インターセプターは、
org.apache.artemis.activemq.api.core.Interceptor
インターフェイスを実装する必要があります。package com.example; import org.apache.artemis.activemq.api.core.Interceptor; import org.apache.activemq.artemis.core.protocol.core.Packet; import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; public class MyInterceptor implements Interceptor { private final int ACCEPTABLE_SIZE = 1024; @Override boolean intercept(Packet packet, RemotingConnection connection) throws ActiveMQException { int size = packet.getPacketSize(); if (size <= ACCEPTABLE_SIZE) { System.out.println("This Packet has an acceptable size."); return true; } return false; } }
MQTT プロトコルを使用している場合は、
org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor
インターフェイスを実装してください。package com.example; import org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor; import io.netty.handler.codec.mqtt.MqttMessage; import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; public class MyInterceptor implements Interceptor { private final int ACCEPTABLE_SIZE = 1024; @Override boolean intercept(MqttMessage mqttMessage, RemotingConnection connection) throws ActiveMQException { byte[] msg = (mqttMessage.toString()).getBytes(); int size = msg.length; if (size <= ACCEPTABLE_SIZE) { System.out.println("This MqttMessage has an acceptable size."); return true; } return false; } }
STOMP プロトコルを使用している場合は、
org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor
インターフェイスを実装してください。package com.example; import org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor; import org.apache.activemq.artemis.core.protocol.stomp.StompFrame; import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection; public class MyInterceptor implements Interceptor { private final int ACCEPTABLE_SIZE = 1024; @Override boolean intercept(StompFrame stompFrame, RemotingConnection connection) throws ActiveMQException { int size = stompFrame.getEncodedSize(); if (size <= ACCEPTABLE_SIZE) { System.out.println("This StompFrame has an acceptable size."); return true; } return false; } }
11.2. インターセプターを使用するためのブローカーの設定
インターセプターを作成したら、それを使用するようにブローカーを設定する必要があります。
前提条件
ブローカーで使用するために、インターセプタークラスを作成し、ブローカーの Java クラスパス ( およびその依存関係 ) に追加する必要があります。<broker_instance_dir>/lib
ディレクトリーは、デフォルトでクラスパスに含まれているため、使用することができます。
手順
ブローカーがインターセプターを使用するように設定するには、
<broker_instance_dir>/etc/broker.xml
に設定を追加します。インターセプターが着信メッセージを対象としている場合は、その
class-name
をremoting-incoming-interceptors
のリストに追加します。<configuration> <core> ... <remoting-incoming-interceptors> <class-name>org.example.MyIncomingInterceptor</class-name> </remoting-incoming-interceptors> ... </core> </configuration>
インターセプターが発信メッセージを対象としている場合は、その
class-name
をremoting-outgoing-interceptors
のリストに追加します。<configuration> <core> ... <remoting-outgoing-interceptors> <class-name>org.example.MyOutgoingInterceptor</class-name> </remoting-outgoing-interceptors> </core> </configuration>
関連情報
- AMQ Core Protocol JMS クライアントでインターセプターを設定する方法は、AMQ Core Protocol JMS ドキュメントの Using message interceptors を参照してください。
第12章 メッセージの迂回およびメッセージフローの分割
AMQ Broker では、迂回 と呼ばれるオブジェクトを設定できます。これにより、クライアントアプリケーションロジックを変更せずにメッセージをあるアドレスから別のアドレスに透過的に迂回できます。迂回を設定してメッセージの コピー を指定された転送アドレスに転送し、メッセージフローを効果的に分割することもできます。
12.1. メッセージの迂回の仕組み
迂回により、クライアントアプリケーションロジックを変更せずに、あるアドレスにルーティングされたメッセージを他のアドレスに透過的に迂回できます。ブローカーサーバーの迂回のセットをメッセージのルーティングテーブルの種類と見なすことができます。
迂回は 排他的 にすることができます。つまり、メッセージは元のアドレスに入りずに指定されたフォワードアドレスに迂回されます。
迂回は 排他的 ではない場合もあります。つまり、ブローカーはメッセージのコピーを指定された転送アドレスに送信する一方で、メッセージを元のアドレスに引き続き送信します。そのため、メッセージフローを分割するのに排他的でない迂回を使用できます。たとえば、注文キューに送信された全順序を個別に監視する場合は、メッセージフローを分割できます。
単一のアドレスに対して複数の迂回を設定できます。アドレスに排他的な迂回と非排他的な迂回の両方が設定されている場合、ブローカーは特別な迂回を最初に処理します。特定のメッセージがすでに特別な迂回によって迂回されている場合、ブローカーはそのメッセージの特別でない迂回を処理しません。この場合、メッセージは元のアドレスには決して送信されません。
ブローカーがメッセージを迂回すると、ブローカーは新しいメッセージ ID を割り当て、メッセージアドレスを新しい転送アドレスに設定します。元のメッセージ ID およびアドレスの値は、_AMQ_ORIG_ADDRESS
( 文字列タイプ ) および _AMQ_ORIG_MESSAGE_ID
(long タイプ ) メッセージプロパティーから取得できます。コア API を使用している場合は、Message.HDR_ORIGINAL_ADDRESS
プロパティーおよび Message.HDR_ORIG_MESSAGE_ID
プロパティーを使用します。
同じブローカーサーバーのアドレスにのみメッセージを迂回できます。別のサーバーのアドレスに迂回したい場合は、最初にメッセージをローカルストアアンドフォワードキューに迂回する一般的な解決策があります。次に、そのキューから消費し、メッセージを別のブローカーのアドレスに転送するブリッジを設定します。迂回とブリッジを組み合わせると、地理的に分散したブローカーサーバー間のルーティング接続の分散ネットワークを作成できます。これにより、グローバルメッセージングメッシュを作成できます。
12.2. メッセージ迂回の設定
ブローカーインスタンスで迂回を設定するには、broker.xml
設定ファイルの core
要素に divert
要素を追加します。
<core> ... <divert name= > <address> </address> <forwarding-address> </forwarding-address> <filter string= > <routing-type> </routing-type> <exclusive> </exclusive> </divert> ... </core>
- divert
-
迂回の名前付きインスタンス。各迂回に一意の名前がある限り、複数の
divert
要素をbroker.xml
設定ファイルに追加できます。 - address
- メッセージを迂回するアドレス
- forwarding-address
- メッセージを転送する アドレス
- filter
- オプションのメッセージフィルター。フィルターを設定すると、フィルター文字列に一致するメッセージのみが迂回されます。フィルターを指定しない場合、すべてのメッセージは迂回と一致すると見なされます。
- routing-type
迂回されたメッセージのルーティングタイプ。迂回は以下に設定できます。
-
anycast
またはマルチキャスト
ルーティングのタイプのメッセージへの適用 - 既存のルーティングタイプを 削除 します。
- 既存のルーティングタイプを 通過 します (つまり保持されます)。
-
ルーティングタイプの制御は、メッセージにルーティングタイプがすでに設定されているものの、別のルーティングタイプを使用するアドレスにメッセージを迂回する必要がある場合に役立ちます。たとえば、ブローカーは、迂回の routing-type
パラメーターを MULTICAST
に設定しない限り、anycast
ルーティングタイプのメッセージを マルチキャスト
を使用するキューにルーティングできません。迂回の routing-type
パラメーターの有効な値は ANYCAST
、MULTICAST
、PASS
、および STRIP
です。デフォルト値は STRIP
です。
- exclusive
-
迂回が排他的であるか ( プロパティーを
true
に設定 ) または非排他的であるかを指定します ( プロパティーをfalse
に設定 )。
以下のサブセクションは、排他的な迂回および排他的でない迂回の設定例を示しています。
12.2.1. 排他的な迂回の例
以下は、排他的な迂回の設定例です。排他的な迂回により、一致するメッセージはすべて最初に設定されたアドレスから新しいアドレスに迂回されます。一致するメッセージは元のアドレスにルーティングされません。
<divert name="prices-divert"> <address>priceUpdates</address> <forwarding-address>priceForwarding</forwarding-address> <filter string="office='New York'"/> <exclusive>true</exclusive> </divert>
上記の例では、prices-divert
と呼ばれる迂回を定義します。これは、アドレス priceUpdates
に送信されたメッセージを別のローカルアドレスである priceForwarding
に迂回します。メッセージフィルター文字列も指定します。メッセージプロパティー office
と値 New York
を持つメッセージのみが迂回されます。その他のメッセージはすべて元のアドレスにルーティングされます。最後に、迂回が排他的であることを指定します。
12.2.2. 排他的でない迂回の例
以下は、排他的でない迂回の設定例です。排他的でない迂回では、メッセージは元のアドレスに送信されますが、ブローカーはメッセージのコピーを指定された転送アドレスにも送信します。したがって、排他的でない迂回は、メッセージフローを分割する方法です。
<divert name="order-divert"> <address>orders</address> <forwarding-address>spyTopic</forwarding-address> <exclusive>false</exclusive> </divert>
上記の例では、order-divert
という迂回を定義し、アドレスの 順序
に送信されたすべてのメッセージのコピーを取り、spyTopic
と呼ばれるローカルアドレスに送信します。また、迂回が排他的ではないように指定します。
関連情報
排他的な迂回と非排他的な迂回の両方を使用する詳細な例は、Divert Example (外部) を参照してください。
第13章 メッセージのフィルタリング
AMQ Broker は、SQL 92 式構文のサブセットに基づいて強力なフィルター言語を提供します。フィルター言語は JMS セレクターに使用されるものと同じ構文を使用しますが、事前定義された識別子は異なります。以下の表は、AMQ Broker メッセージに適用される識別子を示しています。
識別子 | 属性 |
---|---|
AMQPriority |
メッセージの優先度。メッセージの優先度は、 |
AMQExpiration | メッセージの有効期限。値は長い整数です。 |
AMQDurable |
メッセージが永続化されているかどうか。値は文字列です。有効な値は |
AMQTimestamp | メッセージが作成された時点のタイムスタンプです。値は長い整数です。 |
AMQSize |
メッセージの |
コアフィルター式で使用される他の識別子はメッセージのプロパティーであると考えられます。JMS メッセージのセレクター構文に関するドキュメントは、Java EE API を参照してください。
13.1. フィルターを使用するようにキューを設定する
<broker_instance_dir> /etc/broker.xml
で設定するキューにフィルターを追加できます。フィルター式に一致するメッセージのみがキューに格納されます。
手順
filter
要素を希望のキュー
に追加し、要素の値として適用するフィルターを追加します。以下の例では、フィルターNEWS='technology'
がキューtechnologyQueue
に追加されます。<configuration> <core>