1. Homepage
  2. Microsoft MSMQ Connector (2.0)

  3. Windows ゲートウェイサービスガイド

All Connectors

Windows ゲートウェイサービスガイド - Mule 4

Windows ゲートウェイサービス用 Anypoint Connector は、Windows プラットフォームの専用機能への接続を実現します。

始める前に

Mule がインストールされているサーバーに Java 暗号化拡張機能をインストールしてください。コネクタが HTTPS を使用して安全に通信するためには、JCE パッケージが必要です。

Windows Server 2008 R2 が動作しているサーバー上で TLS 1.2 を有効にしてネゴシエートするためには、適切なサブキー (Client や Server) で DisabledByDefault エントリを作成して、「0」に設定する必要があります。デフォルトではこのエントリはレジストリには表示されず、「1」に設定されています。

Windows ゲートウェイサービスのインストール

インストールには、Windows 2008 Server、Windows 2008 R2 Server、Windows 2012 Server、および .NET Framework 4.5 以降が必要です。

インストール手順は次のとおりです。

  1. このドキュメントの「関連情報」セクションに記載されているリンクから Windows ゲートウェイサービスインストーラーをダウンロードします。

  2. ソフトウェアディストリビューションを展開します。

  3. Anypoint-Windows-Gateway-Service.exe ファイルをダブルクリックします。

  4. [Options (オプション)] をクリックしてインストール場所を変更するか、または [Install (インストール)] をクリックしてインストールを開始します。

  5. ゲートウェイで MSMQ Connector を使用する場合は、Anypoint Studio で接続を設定する際に使用しますので、表示される認証トークンをコピーします。使用しない場合は、このステップをスキップしてください。トークンをコピーしたら [Install (インストール)] をクリックします。

  6. インストールが完了すると、readme.txt ファイルを開いて追加の説明を表示するためのオプションが表示されます。

  7. [Finish (完了)] をクリックして終了します。

  8. インストールによって Anypoint ゲートウェイ Windows サービスが作成され、インストーラーによって起動されます。

ゲートウェイインストールウィザード

Windows 7 で実行中のサービスを表示するには、コントロールパネルの表示オプションが小さいアイコンに設定されている状態で、[Control Panel (コントロールパネル)] > [Administrative Tools (管理ツール)] > [Services (サービス)] をクリックします。サービスは次のように表示されます。

サービスツール

Anypoint ゲートウェイの設定

インストール時に他のフォルダーを指定しない限り、Windows サービスはデフォルトで ​c:\Program Files(x86)\Anypoint Gateway for Windows​ にインストールされます。このフォルダーには、Mule.SelfHost.exe 実行ファイル、Mule.SelfHost.exe.config 設定ファイル、および設定を自動化する PowerShell スクリプトが入っています。

注意:​ このフォルダーに設定ファイルが表示されない場合、Windows 7 では、コントロールパネルの表示オプションが小さいアイコンに設定されている状態で、[Control Panel (コントロールパネル)] > [Folder Options (フォルダーオプション)] > [View (表示)] > [Show hidden files folders, and drives (隠しファイル、フォルダー、および隠しドライブを表示する)] をクリックします。

実行ファイルは、新しい Web サーバーをポート 9333 (デフォルト) で開始します。このポートは、HTTPS を使用した安全な接続のみを受け入れます。ゲートウェイがリッスンするポート番号は、Mule.SelfHost.exe.config 設定ファイルの次の場所で変更できます。

<appSettings>
    <!-- Configure the service to listen on the following address. -->
    <add key="OwinHostAddress" value="https://+:9333/"/>
    ...
</appSettings>
 ...
<system.serviceModel>
    <services>
      <service behaviorConfiguration="routing"
          name="System.ServiceModel.Routing.RoutingService">
        <host>
          <baseAddresses>
            <add baseAddress="https://*:9333/router"/>
          </baseAddresses>
    ...
</system.serviceModel>

この Web サーバーは、インストール時に自動的に生成される自己署名 SSL 証明書を使用します。証明書は、ローカルコンピューター証明書ストアの Personal フォルダーに入っています。

ローカルコンピューター証明書ストア

Windows サービスは、自己ホスト型 Web サーバーの http.sys に依存するため、ポート番号や SSL 証明書を変更した場合は、Windows の再設定が必要です。この作業は、インストールディレクトリにある Register-SslCert.ps1 PowerShell スクリプトが行います。ポートまたは証明書を変更した場合は、PowerShell コンソールから次のコマンドを実行してください。

Register-SslCert.ps1 <certificate-thumbprint> <windows-account> <port>

  • <certificate-thumbprint>​: SSL 証明書のサムプリント。ローカルストアアカウントの Personal フォルダーに格納する必要があります。

  • <windows-account>​: ポートを登録する権限を受け取る Windows ユーザーまたはグループ。Windows サービスやコンソールアプリケーションを偽装するアカウントは、このグループに属している必要があります。

  • <port>​: HTTP ポート – 9333 (デフォルト) または設定ファイルで記述したポートを指定する必要があります。

例:

Register-SslCert.ps1 a495cbf8c4af496f1ef81efb224c8097d039f922 everyone 9333

MSMQ Connector 設定について

セキュリティの考慮事項について

Mule Runtime で実行中の MSMQ Connector について、サービスは最初に RFC 2616 の指定に従って HTTP 認証ヘッダーを調べることで、呼び出しを認証します。

認証は、MSMQ Connector が使用する、この一意のセキュリティトークンによって行われます。このトークンは、Mule スキームを使用してゲートウェイに送信されるすべての HTTP 要求に含まれます。次の例では、MSMQ がゲートウェイを活用して、このセクションで指定されているようにセキュリティトークンを送信することで特定のキューに接続しています。

GET: https://localhost:9333/msmq?count=50
Authorization: mule 3nGdw7W+G1fSO2YBEHDmpo4N1Tg=
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1.0

認証トークンは、コネクタとゲートウェイ設定ファイルで一致する必要があります。次の例は、ゲートウェイ設定ファイルの Mule.SelfHost.exe.config でトークンがどのように設定されるかを示しています。

<appSettings>
    <!-- Token that must be sent by the Mule connector's client in the Authorization header when accessing the Rest Api. -->
    <add key="mule-auth-token" value="3nGdw7W+G1fSO2YBEHDmpo4N1Tg="/>
</appSettings>

Mule Runtime で実行されるコネクタを設定する際には、ゲートウェイアクセストークン設定 (コネクタの XML 設定にある accessToken 属性) で認証トークン値を設定してください。

注意:​ Windows ゲートウェイサービスのインストーラーは、最初のインストール時に、コーラーが使用する暗号化されたセキュアトークンを自動的に生成します。このトークンは、Mule アプリケーションに簡単にコピーできるように、インストール中に表示され、クリップボードに格納されます。

カスタム HTTP ヘッダーによる Windows ユーザーの偽装について

ゲートウェイが処理するコネクタの代わりにコールを実行するユーザーは、2 つのカスタム HTTP ヘッダーである mule-impersonate-username と mule-impersonate-password によって認証されます。

これらの 2 つのヘッダーは、Windows ゲートウェイサービスが動作している Active Directory フォレストにある既存ユーザーの Windows ログイン情報、またはサービスをホストしているマシンのローカルアカウントの Windows ログイン情報を表します。これらの HTTP ヘッダーが HTTP 要求に含まれている場合、Windows ゲートウェイサービスはこのユーザーを認証して偽装してから、コネクタが必要とする操作を実行します。これにより、Windows ログイン情報を使用して正しいアクセス制御リスト権限を設定できます。

MSMQ Connector とゲートウェイとのインタラクションについて

次の図は、MSMQ Connector とゲートウェイとのインタラクションと、使用する主なコンポーネントを示しています。

Windows ゲートウェイ

設定について

MSMQ Connector にのみ関連する設定を次の表に示します。

プロパティ 使用方法

invalid-queue-name

読めないメッセージの移動先となるキューの名前。

transaction-timeout

コネクタによって取得された時点からのメッセージの処理タイムアウト。クリーンアップタスクがタイムアウトの時間切れになったメッセージを見つけると、メインキューに戻して再び処理の対象とします (詳細については、コネクタガイドの 2 段階コミットの説明を参照してください)。

invalid-message-timeout

メッセージのペイロードが不適切なフォーマッターで解析された場合の無効なメッセージのタイムアウト。

cleanup-delay

メッセージが処理用に取得されてから、クリーンアップタスクが時間切れになったメッセージを探し始めるまでの遅延時間 (詳細については、コネクタガイドの 2 段階コミットの説明を参照してください)。

cleanup-username

(省略可能) クリーンアップタスクを実行する際に偽装するユーザー。この設定を空白にすると、サービスを実行しているユーザーアカウントが使用されます。

cleanup-password

(省略可能) クリーンアップタスクを実行する際に偽装するユーザーのパスワード。

リモートキューからの Windows ユーザーの偽装について

キューで認証が必要であるとマークされている場合、上記のようにコーラーユーザーを (同じ一般セクションで) 偽装することができます。これに加えて、リモートキューを使用している場合は、この動作を上書きするための特別なヘッダーがコネクタにあります。

負荷分散設定について

Windows ゲートウェイサービスは、フォールトトレランスを高めるために負荷分散設定での動作をサポートしています。複数のゲートウェイサービスインスタンスを実行する場合は、重複しない間隔で MSMQ バックグラウンドジョブを実行するように各メンバーを設定する必要があります。

MSMQ バックグラウンドジョブの処理は、デフォルトでは正時から 10 分間隔で実行されます。負荷分散設定において、複数のゲートウェイインスタンスが同時にキューのクリーンアップを実行しないようにするには、cleanup-delay と呼ばれる設定を、ゲートウェイインスタンスごとに行う必要があります。この場合に各マシンで推奨される値は (10 / instanceCount) * (instanceNumber - 1) で、instanceNumber は 1 …​ n の整数です。

たとえば、マシンが 2 台のクラスターでは、cleanup-delay をマシン 1 では 0、マシン 2 では 5 に設定します。マシンが 3 台のクラスターでは、cleanup-delay をマシン 1 では 0、マシン 2 では 3、マシン 3 では 6 に設定します。このオフセットが正しく適用されるように、NTP や同等のメカニズムでマシンのクロックを同期させる必要があります。

cleanup-delay 設定は Mule.SelfHost.config ファイルにあります。

<appSettings>
    <!-- MSMQ: Delay in minutes to launch the cleanup process for sub-queues -->
    <add key="cleanup-delay" value="0"/>
</appSettings>

注意:​ LB 設定において、関与するノード (MSMQ、ゲートウェイ) がワークグループに属していてドメインには結合されていない場合には、ゲートウェイサービスを「管理者として実行」するように設定する必要があります。同じドメインに結合した場合は、ドメイン管理者は関与する各ノードとオブジェクト (キュー) の権限を適切に設定する必要があります。

Windows ゲートウェイサービスのトラブルシューティング

Windows ゲートウェイサービスは、組み込み .NET トレースシステムを活用します。基本的な仕組みはシンプルで、トレースメッセージがスイッチ経由でリスナーに送信され、特定のストレージメディアに連結されます。コネクタが使用するトレースソースのリスナーは、設定ファイルで指定します。

<sharedListeners>
   <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
   <add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="mule.gateway.log" />
   <add name="etw" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}" />
</sharedListeners>

<sources>
    <source name="mule.gateway">
        <listeners>
            <clear />
            <add name="console" />
            <add name="etw"/>
        </listeners>
    </source>
</sources>

上の例では、出力コンソール用、ファイル用、そして Windows イベントトレーシング (ETW) 用に 3 つのリスナーを設定しています。mule.gateway コネクタ用のトレースソースは、コンソールと ETW にのみトレースを出力するように設定されています。

トレースレベルの変更方法

Windows ゲートウェイサービスは、情報イベントをログに記録するように設定されています。この設定は ​<switches>​ 要素で行います。すべてをログに記録する場合は、トレースレベルを下記の設定要素で Verbose (冗長) レベルに変更してください。

設定ファイルのスイッチレベルでレベルを設定します。

<switches>
    <add name="mule.gateway" value="Information" />
</switches>

他にも次のレベルが使用できます。

  • Error (エラー): エラー処理メッセージを出力

  • Warning (警告): 警告とエラー処理メッセージを出力

  • Information (情報): 情報メッセージ、警告、およびエラー処理メッセージを出力

  • Off (オフ): トレースを無効化

Windows ゲートウェイサービス内のルーティングサービスをトレースまたはデバッグする場合は、ルーティングサービスのヒット時に生成されたエラーの詳細を取得するための設定を有効にします。この情報をトレースリスナーで取得する場合は、serviceDebug 要素の includeExceptionDetailInFaults 属性で有効にします。この設定を有効にするには、次のように設定を true にします。

<serviceBehaviors>
  <behavior name="routing">
    ...
    <serviceDebug includeExceptionDetailInFaults="true" />
  </behavior>
</serviceBehaviors>

この設定は、サービスが返すエラーメッセージを拡張して、原因の内部スタックトレースを追加します。このことが、場合によっては問題を理解するのに役立つ可能性があります。

コマンドラインからコンソールトレースを有効にする方法

問題のトラブルシューティングに役立つ手段の 1 つは、コンソールリスナーを有効にして (デフォルトでは有効ですが、有効ではない場合には、上記のリスナーセクションに追加する必要があります)、Windows ゲートウェイサービスをコマンドラインから実行することです。

コンソールでは、要求、応答、警告、エラーなど、トレースされている情報をリアルタイムで見ることができます。コネクタがゲートウェイに正しく接続されているかどうかを確認したり、障害につながる可能性がある、考えられる他の原因を確認したりするのに便利です。

  1. コンソールリスナーが有効になっていない場合は、リスナーコレクションに追加することで有効にします。

    <sources>
    <source name="mule.gateway">
        <listeners>
            <clear />
            <add name="console" />
            ...
        </listeners>
    </source>
</sources>

  2. コマンドラインから実行するには、Anypoint ゲートウェイサービスを停止します。

  3. Anypoint ゲートウェイサービスがインストールされているフォルダー (デフォルトでは ​c:\Program Files(x86)\Anypoint Gateway for Windows​) に移動します。

  4. Mule.SelfHost.exe アプリケーションを実行します。コンソールが実行され、イベントのトレース結果がリアルタイムで表示されます。

  5. トラブルシューティングが完了したら、コンソールを閉じて Windows サービスを再起動してください。

Windows イベントトレーシングを有効化する方法

Windows イベントトレーシング (ETW) は、カーネルレベルでイベントのトレースを実行する非常に効率的な組み込みパブリッシュ/サブスクライブメカニズムです。I/O に依存してファイルやデータベースなどに永続的に保存する従来のトレースソリューションと比較して、この機能を使用するにあたってオーバーヘッドはほとんどありません。Windows の組み込みメカニズムであるため、オペレーティングシステムの多くのサービスやコンポーネントもこの機能を使用しています。そのため、トラブルシューティングの対象は、アプリケーションだけではなく、同じ実行中に関与する多くの OS コンポーネントにも及びます。

ETW では、一部のアプリケーションがイベントをキュー (プロバイダー) にパブリッシュし、他のアプリケーションが ETW セッションを介してリアルタイムでこれらのキューからイベントをコンシュームします。プロバイダーでイベントがパブリッシュされると、そのキューからイベントを収集するセッションが発生しない限り、イベントはどこにも行きません。(イベントは持続的ではありません。)

​.NET のトレースシステムには、ETW 用のトレースリスナーである EventProviderTraceListener があり、ETW がトレースを収集するために使用するセッション識別子で設定できます。

<sharedListeners>
   <add name="etw"type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}"/>
</sharedListeners>

この例では、この識別子にセッションが関連付けられています。
{47EA5BF3-802B-4351-9EED-7A96485323AC}​

セッショントレースの収集方法

  1. Windows コンソールを開いて、次のコマンドで新しいセッションを開始します。

    logman start mysession -p {47EA5BF3-802B-4351-9EED-7A96485323AC} -o etwtrace.etl -ets

  2. 次のコマンドを実行してセッションを停止します。

    logman stop mysession -ets

    トレースセッションデータが入った etwtrace.etl ファイルが生成されます。

  3. 次のコマンドで、人間が読めるファイルを生成します。

    tracerpt etwtrace.etl

このコマンドは、有益な情報を dumpfile.xml というテキストファイルに転送します。詳細については、「Tracerpt」を参照してください。

関連情報