fteCreateBridgeAgent ( MFT プロトコル・ブリッジ・エージェントの作成および構成)

fteCreateBridgeAgent コマンドは、 Managed File Transfer プロトコル・ブリッジ・エージェントとその関連構成を作成します。 プロトコル・ブリッジ・エージェントは、ファイルを送受信するファイル・サーバーごとに作成します。

重要: [UNIX、Linux、Windows] IBM® MQ for UNIX, Linux®, and Windowsでは、 IBM MQ 管理者 (および mqm グループのメンバー) であるユーザーのみがこのコマンドを実行できます。 IBM MQ 管理者以外のユーザーとしてこのコマンドを実行しようとすると、次のエラー・メッセージが表示されます。BFGCL0502E: You are not authorized to perform the requested operation.コマンドは実行されません。
[z/OS] z/OS® システムでは、コマンドを実行するために、ユーザーは以下の条件の (少なくとも) 1 つを満たす必要があります。
  • mqm グループのメンバーである (システムに mqm グループが定義されている場合)。
  • BFG_GROUP_NAME 環境変数で名前が指定されたグループのメンバーである (名前が指定されている場合)。
  • コマンド実行時に BFG_GROUP_NAME 環境変数に値が設定されていない。

目的

fteCreateBridgeAgent コマンドは、プロトコル・ブリッジ・エージェントを作成するために使用します。 プロトコル・ブリッジの使用方法の概要については、 プロトコル・ブリッジを参照してください。 この fteCreateBridgeAgent コマンドは MQSC コマンドを提供します。これをエージェントのキュー・マネージャーに対して実行し、以下のエージェント・キューを作成する必要があります。
  • SYSTEM.FTE.AUTHADM1。agent_name
  • SYSTEM.FTE.AUTHAGT1.agent_name
  • SYSTEM.FTE.AUTHMON1.agent_name
  • SYSTEM.FTE.AUTHOPS1.agent_name (SYSTEM.FTE.AUTHOPS1. agent_name)
  • SYSTEM.FTE.AUTHSCH1.agent_name
  • SYSTEM.FTE.AUTHTRN1。agent_name
  • SYSTEM.FTE.COMMAND.agent_name
  • SYSTEM.FTE.DATA。agent_name
  • SYSTEM.FTE.EVENT。agent_name
  • SYSTEM.FTE.REPLY.agent_name
  • SYSTEM.FTE.STATE.agent_name
  • [V9.1.4 2019 年 12 月]SYSTEM.FTE.HA。agent_name
これらのキューは、内部システム・キューであるため、エージェントを削除しない限り、メッセージの変更、削除、または読み取りを行うことはできません。 実行する MQSC コマンドは、MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc にあるファイルでも提供されます。

エージェントを後で削除する場合は、 このコマンドはまた、エージェントが使用するキューをクリアし、続いて削除するために実行する必要がある MQSC コマンドも提供します。 MQSC コマンドは、MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc にあるファイルに含まれています。

fteCreateBridgeAgent コマンドは、ディレクトリー MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_nameに ProtocolBridgeProperties.xml XML ファイルを作成します。

ProtocolBridgeCredentials.xml ファイルは、ユーザーが手動で作成する必要があります。このファイルは fteCreateBridgeAgent コマンドでは作成されなくなりました。

ProtocolBridgeCredentials.xml ファイルには、プロトコル・ブリッジ・エージェントがプロトコル・サーバーに対する権限を自分に与えるために使用するユーザー名および資格情報を定義でき、ProtocolBridgeProperties.xml ファイルには、複数のプロトコル・ファイル・サーバーを定義できるため、複数のエンドポイントに転送可能になります。

MQ_INSTALLATION_PATH/mqft/samples/credentials/ ディレクトリー内にサンプルの ProtocolBridgeCredentials.xml があります。 詳しくは、 プロトコル・ブリッジ資格情報ファイルのフォーマット および プロトコル・ブリッジ・プロパティー・ファイルのフォーマットを参照してください。

fteCreateBridgeAgent コマンドを実行して、デフォルト・プロトコル・ファイル・サーバー (パラメーター -bt) を指定する場合、このデフォルト・サーバーが ProtocolBridgeProperties.xml ファイルに含まれ、そのホスト名がサーバー名として使用されます。 -bt パラメーターとともに、以下のパラメーターを指定する必要があります。
  • -bh
  • -btz
  • -bm
  • -bsl
  • -ブフ
  • -bts

デフォルト・サーバーを指定しない場合、ProtocolBridgeProperties.xml ファイルには項目がありません。転送が実行される前に、手動で少なくとも 1 つのサーバーを追加する必要があります。

Managed File Transfer には、プロトコル・ブリッジ・エージェントの構成に役立つ拡張エージェント・プロパティーが用意されています。 プロトコル・ブリッジに関連するプロパティーは、先頭が protocol になっています。 これらのプロパティーについては、 『agent.properties ファイル』で説明しています。 プロトコル・ブリッジで予期しない動作が発生した場合は、それらの protocol プロパティーがシステムで正しく設定されていることを確認してください。

fteCreateBridgeAgent コマンドから、次の出力が表示された場合:
BFGMQ1007I: The coordination queue manager cannot be contacted or has refused a connection attempt.
The WebSphere MQ reason code was 2058. The agent's presence will not be published.
調整キュー・マネージャーに接続できないことを示し、理由として IBM MQ 理由コードを提供します。 この情報メッセージは、調整キュー・マネージャーが現在使用不可であるか、構成が誤って定義されたことを示す可能性があります。
重要:

UNIX プラットフォームおよび Linux Managed File Transfer コマンドでは、ソケット・ファイルを使用して、同じホスト・マシン上で実行されているエージェント・プロセスと通信します。

これらのソケット・ファイルは、エージェントのログ・ディレクトリーに作成され、エージェントが停止すると削除されます。 IBM MQ Managed File Transfer インストール済み環境では、このソケット・ファイルは <MQ_DATA_PATH>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME> というファイル・パスで作成されます。ここで、MQ_DATA_PATH はデフォルトで /var/mqm です。

再配布可能エージェントの場合、このソケット・ファイルはディレクトリー <RE_DISTRIBUTABLE_DIRECTORY>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME>の下に作成されます。

例えば、エージェント名が SRCAGENT、エージェント・キュー・マネージャー名が SRCAGENTQM、調整キュー・マネージャー名が COORDQM、再配布可能エージェントがディレクトリー /home/myuser/mqmft-redistから実行されている場合、このソケット・ファイルの絶対パスは /home/myuser/mqmft-redist/mqft/logs/COORDQM/agents/SRCAGENT/logs/SRCAGENT@SRCAGENTQM です。

これは、85 文字の合計ファイル・パス長です。

これらのオペレーティング・システムで許可されるソケット・ファイルの最大パス長は 107 文字です。 したがって、エージェントの作成時には、ソケット・ファイル・パスが 107 文字を超えないように注意してください。 これは、エージェントのログ・ディレクトリーを任意のディレクトリー・ロケーションに配置できる再配布可能エージェントでは特に重要です。 構成ディレクトリーのセットアップについて詳しくは、 fteCreateEnvironment コマンドを参照してください。

エージェントを開始した場合、またはエージェントに接続する他のコマンドを実行した場合に、パスの長さが 107 文字を超えると、以下のメッセージを受け取ります。
BFGNV0159E: FFDC を使用してソケット・ファイルにバインドしようとして失敗しました。

特殊文字

特殊文字が含まれているパラメーター値を使用する場合には、予期しない形で特殊文字がコマンド・シェルで解釈されないように注意してください。 例えば、スペース、引用符 (単一または二重)、スラッシュ、バックスラッシュ文字などを含む完全修飾ファイル・パスや名前は、直接コマンド自体に渡されずに、コマンド・シェルで解釈されてしまう可能性があります。 文字がコマンド・シェルによって解釈される動作を回避するには、パラメーター全体を二重/単一引用符で囲むか、またはコマンド・シェルのエスケープ・シーケンスを使用して特殊文字をエスケープします。

Syntax

fteCreateBridgeAgent

Read syntax diagramSkip visual syntax diagram fteCreateBridgeAgent -agentNameagent_name -agentQMgragent_qmgr_name -btprotocol_file_server_type-bhserver_host_name-btzserver_time_zone-bmserver_platform_type-bslserver_locale-bfeserver_file_encoding -btstruststore_file -bpserver_port_number-blw-blfserver listing format-agentQMgrHostagent_qmgr_host_name-agentQMgrPortagent_qmgr_port-agentQMgrChannelagent_qmgr_channel-agentDescagent_description-ac-authorityChecking-sservice_name-suuser_name-sppassword-sjoptions-sloptions-n-mquseriduserID-mqpasswordpassword-credentialsFilefilePath-useridusername-pconfiguration-options-f-x

パラメーター

-agentName (agent_name)
必須。 作成するエージェントの名前。 エージェント名は管理可能ドメイン内で固有でなければなりません。

エージェントの命名について詳しくは、 オブジェクトの命名規則を参照してください。

-agentQMgr (agent_qmgr_name)
必須。 エージェントのキュー・マネージャーの名前。

-bt (protocol_file_server_type)
オプション。 デフォルトのプロトコル・ファイル・サーバーを定義することを指定します。 以下のいずれかのオプションを指定します。
FTP
標準 FTP サーバー
SFTP
SSH FTP サーバー
FTPS
SSL または TLS を使用して保護された FTP サーバー

このパラメーターを指定しなかった場合、デフォルトのプロトコル・サーバーは定義されません。

-bh (server_host_name)
-btパラメーターを使用してデフォルトのプロトコル・ファイル・サーバーも指定する場合にのみ必要です。 プロトコル・ファイル・サーバーの IP ホスト名または IP アドレス。

-btz (server_time_zone)
-btパラメーターも指定する場合にのみ必要です (FTP および FTPS サーバーのみ)。 プロトコル・ファイル・サーバーのタイム・ゾーン。 タイム・ゾーンは地域/ロケーション形式で指定します。 例えば、Europe/London のように指定します。

-htzパラメーターを使用して、-btzに指定可能な値をリストできます。 例えば、fteCreateBridgeAgent -htzです

-bm (server_platform)
-btパラメーターを使用してデフォルトのプロトコル・ファイル・サーバーも指定する場合にのみ必要です。 プロトコル・ファイル・サーバーのプラットフォーム・タイプ。 以下のいずれかのオプションを指定します。
UNIX
汎用 UNIX および Linux プラットフォーム
WINDOWS
汎用 Windows プラットフォーム
[V9.1.3 2019 年 7 月]OS400
IBM iプラットフォーム
注: ブリッジ・エージェントが IBM iを実行する FTP サーバーと通信する場合は、 bm パラメーターを OS400 に設定し、 blf パラメーターを OS400IFS に設定する必要があります。

-bsl (server_locale)
-btパラメーターも指定する場合にのみ必要です (FTP および FTPS サーバーのみ)。 プロトコル・ファイル・サーバーのロケール。 xx_XXの形式でロケールを指定します。 例えば、en_GB のように指定します。

-bfe (server_file_encoding)
-btパラメーターを使用してデフォルトのプロトコル・ファイル・サーバーも指定する場合にのみ必要です。 プロトコル・ファイル・サーバーに保管されるファイルの文字エンコード方式。 例: UTF-8。

-hcsパラメーターを使用して、-bfeに指定可能な値をリストできます。 例えば、fteCreateBridgeAgent -hcsです

-bts (truststore_file)
-btパラメーターを指定する場合は必須です (FTPS サーバーのみ)。 FTPS サーバーによって提示される証明書を妥当性検査するためのトラストストアへのパスを指定します。

-btsパラメーターは、-btパラメーターで FTPS オプションも指定した場合にのみ指定できます。

-bp (server_port)
オプション。 プロトコル・ファイル・サーバーが接続される IP ポート。 このパラメーターは、プロトコル・ファイル・サーバーがそのプロトコル用のデフォルト・ポートを使用しない場合のみ指定します。 このパラメーターを指定しない場合、 Managed File Transfer はファイル・サーバーのプロトコル・タイプのデフォルト・ポートを使用します。

-blw
オプション。 書き込み機能が制限されるようにプロトコル・ファイル・サーバーを定義します。 デフォルトで、プロトコル・ブリッジ・エージェントは、プロトコル・ファイル・サーバーには、ファイルの削除、ファイルの名前変更、および書き込み付加用のファイルのオープンが許可されていることを想定しています。 このパラメーターは、プロトコル・ファイル・サーバーにこれらのファイル・アクションが許可されていないことを示すために指定します。 代わりに、ファイル・サーバーにはファイルの読み書きだけが許可されます。 このパラメーターを指定した場合、転送が中断されたときはそれらの転送はリカバリーできなくなる可能性があり、結果的に実行中のファイル転送が失敗することがあります。

-blf (サーバー・リスト・フォーマット)
オプション (FTP サーバーおよび FTPS サーバーの場合のみ)。 デフォルトのプロトコル・ファイル・サーバーからリストで返されるファイル情報のサーバー・リスト形式を定義します。 オプションは以下のとおりです。
UNIX
汎用 UNIX および Linux プラットフォーム
WINDOWS
汎用 Windows プラットフォーム
[V9.1.3 2019 年 7 月]OS400IFS
IBM i プラットフォーム上のルート・ファイル・システム
注:
  1. ブリッジ・エージェントがIBM iを実行する FTP サーバーと通信する場合は、bmパラメーターをOS400 に設定し、blfパラメーターを OS400IFS に設定する必要があります。
  2. Managed File Transfer を使用して、ルート (/) ファイル・システムでのみファイルを送受信できます。 その他のファイル・システムではできません。

選択する形式を識別するには、FTP クライアント・プログラムを使用し、ディレクトリーをリスト表示し、最適な形式を選択します。 例:

[UNIX]UNIX は、以下のタイプのリストを表示します。

-rwxr-xr-x 2 userid groupId 4096 2009-07-23 09:36 filename
[Windows]Windows は、以下のタイプのリストを表示します。

437,909 filename
[IBM i]IBM i は、以下のタイプのリストを表示します。
 OS400IFS  -rwxrwsrwx  3 USERID  0       8192 Mar  7 08:33 filename

デフォルトは UNIX です。これは、ほとんどのサーバーで使用される形式です。

-agentQMgrホスト (agent_qmgr_host)
オプション。 エージェントのキュー・マネージャーのホスト名または IP アドレス。

-agentQMgrポート (agent_qmgr_port)
オプション。 エージェントのキュー・マネージャーとのクライアント接続で使用されるポート番号。

-agentQMgrチャネル (agent_qmgr_channel)
オプション。 エージェントのキュー・マネージャーとの接続に使用されるチャネル名。

-agentDesc (agent_description)
オプション。 エージェントの説明。これは、 IBM MQ Explorerに表示されます。

-ac または -authorityChecking
オプション。 このパラメーターは、権限検査を有効にします。 このパラメーターを指定すると、 エージェントは、要求を実行依頼しているユーザーにその要求アクションの実行権限があることを検査します。 詳しくは、 MFT エージェント・アクションでのユーザー権限の制限を参照してください。

[Windows]-s (サービス名)
オプション (Windows のみ)。 エージェントを Windows サービスとして実行するように指示します。 service_name を指定しない場合、サービスの名前はmqmftAgentAGENTQMGRになります。ここで、AGENT はエージェント名、QMGR はエージェント・キュー・マネージャー名です。

Windows の「サービス」ウィンドウの「名前」列に示されるサービスの表示名は、常に「Managed File Transfer Agent AGENT@QMGR」です。

[Windows]-su (ユーザー名)
オプション (Windows のみ)。 エージェントが Windows サービスとして実行される場合、このパラメーターは、サービスが実行されるアカウントの名前を指定しま す。 Windowsドメイン・ユーザー・アカウントを使用してエージェントを実行するには、DomainName\UserNameの形式で値を指定します。 ローカル組み込みドメインのアカウントを使用してサービスを実行するには、UserNameの形式で値を指定します。

-suパラメーターを使用して指定するWindowsユーザー・アカウントには、Log on as a service権限が必要です。 この権限を付与する方法については、 MFT エージェントまたはロガーを Windows サービスとして実行するためのガイダンスを参照してください。

-sが指定されている場合は必須です。

[Windows]-sp (パスワード)
オプション (Windows のみ)。 -suパラメーターによって設定されたユーザー・アカウントのパスワード。

このパラメーターは、-sが指定されている場合にのみ有効です。 -sパラメーターを指定するときにこのパラメーターを指定しないと、警告メッセージが生成されます。 このメッセージは、サービスを正常に開始するには、Windows サービス・ツールを使用してパスワードを設定する必要があることを警告します。

[Windows]-sj (オプション)
オプション (Windows のみ)。 エージェントが Windows サービスとして開始される場合は、JVM に渡されるオプションのリストを -D または -X の形式で定義します。 オプションは、番号記号 (#) またはセミコロン (;) 文字を使用して区切られます。 # またはセミコロン (;) 文字を組み込む必要がある場合は、それらを単一引用符で囲みます。

このパラメーターは、-sが指定されている場合にのみ有効です。

[Windows]-sl (オプション)
オプション (Windows のみ)。 Windows サービスのログ・レベルを設定します。 有効なオプションは、 error、 info、 warn、 debugです。 デフォルトは info です。 このオプションは、Windows サービスに関して問題が発生した場合に便利です。 これを debug に設定すると、より詳細な情報がサービス・ログ・ファイルに記録されます。

このパラメーターは、-sが指定されている場合にのみ有効です。

[Windows]-n
オプション (Windows のみ)。 エージェントを通常のプロセスとして実行するように指示します。 これは、-sオプションと同時に指定することはできません。 -sパラメーターと-nパラメーターのどちらも指定されていない場合、エージェントは通常のWindowsプロセスとして構成されます。

-p (構成オプション)
オプション。 このパラメーターは、エージェントを作成するために使用される構成オプションのセットを決定します。 慣例として、このパラメーターの入力には、デフォルト調整キュー・マネージャー以外の名前を使用します。 これで、fteCreateBridgeAgent コマンドは、デフォルト以外の調整キュー・マネージャーと関連付けられたプロパティー・ファイルのセットを使用します。

オプションの-pパラメーターは、デフォルト以外の構成オプションを使用する場合にのみ指定してください。 -pを指定しない場合は、installation.propertiesファイルに定義されている構成オプションが使用されます。 詳しくは、 構成オプション を参照してください。

-f
オプション。 コマンドに強制的に既存の構成を上書きさせます。

-htz
オプション。 -btzパラメーターの入力として使用できる、サポートされる時間帯のリストを表示します。

-hcs
オプション。 -bfeパラメーターの入力として使用できる、サポートされる文字セットのリストを表示します。
fteCreateBridgeAgent -hcs コマンドを実行して、JVM にとって既知のコード・ページをリストします。 既知のコード・ページは JVM によって異なるので、この情報を外部ソースから利用することはできません。

-mquserid (userID)
オプション。 コマンド・キュー・マネージャーで認証するユーザー ID を指定します。
-mqpassword (パスワード)
オプション。 コマンド・キュー・マネージャーで認証するパスワードを指定します。 -mquseridパラメーターも指定する必要があります。 -mquseridを指定し、-mqpasswordを指定しない場合は、関連付けられたパスワードの入力を求めるプロンプトが出されます。 パスワードは表示されません。
-credentialsFile (filePath)
オプション。 IBM MQ 認証の詳細が追加される既存または新規の資格情報ファイルの絶対ファイル・パス。

このコマンドは、指定されたManaged File Transfer資格情報ファイルへの一連のIBM MQ認証詳細の追加をサポートします。 このコマンドは、 IBM MQ 接続認証が有効になっている場合に使用します。 既存の詳細を更新する場合は、-fforce パラメーターを使用する必要があります。

-userid (ユーザー名)
オプション。 資格情報の詳細を関連付けるために使用するユーザー ID。 ユーザー ID を指定しない場合、資格情報の詳細はすべてのユーザーに適用されます。 -credentialsFileパラメーターも指定する必要があります。
- ? または -h
オプション。 コマンド構文を表示します。
[V9.1.4 2019 年 12 月]-x
オプション。 高可用性モードで実行するエージェント構成を作成します。
このパラメーターを指定すると、新規オプション highlyAvailable が agent.properties ファイルに追加されます。

推奨されないパラメーター

以下のパラメーターは非推奨になっており、 IBM WebSphere® MQ 7.5 または IBM WebSphere MQ File Transfer Edition 7.0.2 以降ではサポートされません。

-brd (reconnect_delay)
非推奨。 オプション。 プロトコル・ファイル・サーバーとの失われた接続の再確立を次に試行するまでの遅延時間を秒単位で指定します。 デフォルト値は 10 秒です。

-brr (reconnect_retries)
非推奨。 オプション。 デフォルト・プロトコル・ファイル・サーバーとの失われた接続の再確立を試行する再試行の最大回数を指定します。 この最大値に達すると、現在のファイル転送は失敗として分類されます。 デフォルト値は 2 です。

例

以下の例では、エージェント・キュー・マネージャー QM_ACCOUNTS を使用して新規のプロトコル・ブリッジ・エージェント ACCOUNTS1 が作成され、このエージェントはデフォルトの調整キュー・マネージャーを使用します。 ACCOUNTS1 は、FTP サーバー accountshost.ibm.com に接続します。 この FTP サーバーは、タイム・ゾーン Europe/Berlin、ロケール de_DE、ファイル・エンコード方式 UTF-8 を使用して、Windows 上で稼働します。 再接続の再試行回数は 4 回です。

fteCreateBridgeAgent -agentName ACCOUNTS1 -agentQMgr QM_ACCOUNTS -bt FTP
 -bh accountshost.ibm.com -bm WINDOWS -btz Europe/Berlin -bsl de_DE -bfe UTF8
 -agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1
以下の例では、エージェント・キュー・マネージャー QM_ACCOUNTS を使用して新規のプロトコル・ブリッジ・エージェント ACCOUNTS2 が作成され、このエージェントはデフォルトの調整マネージャーを使用します。 ACCOUNTS2 はデフォルトのプロトコル・ファイル・サーバーを使用せずに作成されます。

fteCreateBridgeAgent -agentName ACCOUNTS2 -agentQMgr QM_ACCOUNTS
注: 上記は、 Managed File Transfer Agent 再配布可能パッケージには適用されません。
[V9.1.3 2019 年 7 月]このシナリオでは、 Managed File Transfer Agent は Linux または Windows ボックス上で実行されていますが、 IBM iを実行している FTP サーバーと通信するように構成されています。 宛先ファイルのコード・ページを IB のネイティブ・コード・ページにする必要がある場合は、転送要求を送信するときに -dce コード・ページ・パラメーターを使用する必要があります。 以下に例を示します。

fteCreateTransfer -rt -1 -sa SRC -sm MFTQM -da OS400FTP -dm MFTQM -dce 37 -sce 1252 
-t text -de overwrite -df "<your-domain>:/home/mft/text/uploadwcp.log"
 "C:\temp\os400\Text\uploadwcp.log"
また、 IBM iからのネイティブ・コード・ページの受信ファイルが必要な場合は、以下のようにします。

fteCreateTransfer -rt -1 -da SRC -dm MFTQM -sa OS400FTP -sm MFTQM -sce 37 -dce 1252 
-t text -de overwrite -df "C:\temp\os400\Text\downloadwcp.log" 
"<your-domain>:/home/mft/text/uploadwcp.log"

追加のカスタマイズ

- bt パラメーター (および必要な追加パラメーター) を使用した場合、ProtocolBridgeProperties.xml ファイルにデフォルトのサーバー名が表示されます。

FTP サーバーを追加する場合、または資格情報ファイルの場所を変更する場合は、 ProtocolBridgeProperties.xml ファイルを使用したプロトコル・ファイル・サーバーのプロパティーの定義を参照してください。

戻りコード

0
コマンドは正常に完了しました。
1
コマンドは失敗しました。

プロトコル・ブリッジ・エージェントを開始するには、fteStartAgent コマンドを使用します。 詳しくは、 fteStartエージェント: MFT エージェントの開始を参照してください。 [z/OS] z/OSも参照してください。