fteCreateBridgeAgent（创建并配置 "MFT协议桥代理）

fteCreateBridgeAgent 命令将创建 Managed File Transfer 协议网桥代理及其关联的配置。 针对您要与之进行文件的发送和接收操作的每个文件服务器，创建一个协议网桥代理。

重要说明：
[AIX、Linux 和 Windows]在 AIX®, Linux®, and Windows 系统上，如果您使用的是 IBM® MQ 服务器安装镜像，则必须同时满足以下两个条件才能运行该命令：
  • 成为 IBM MQ 管理员。
  • 是 mqm 组的成员（如果在系统上定义了 mqm 组）。
否则，您将收到错误信息BFGCL0502E: You are not authorized to perform the requested operation。如果您使用的是 Redistributable Managed File Transfer Agent 存档，则不受此限制。
[z/OS]在 z/OS® 系统上，您必须满足以下条件中的至少一个才能运行该命令：
  • 是 mqm 组的成员（如果在系统上定义了 mqm 组）。
  • 成为 BFG_GROUP_NAME环境变量 （如果有）中指定的群组成员。
  • 运行命令时 ，BFG_GROUP_NAME环境变量中没有设置任何值。

用途

使用 fteCreateBridgeAgent 命令可创建协议网桥代理。 有关如何使用协议网桥的概述，请参阅 协议网桥。 该 fteCreateBridgeAgent 命令向您提供 MQSC 命令，您必须针对代理队列管理器运行这些命令以创建以下代理队列：
  • SYSTEM.FTE.AUTHADM1.代理名称
  • SYSTEM.FTE.AUTHAGT1.代理名称
  • SYSTEM.FTE.AUTHMON1.代理名称
  • SYSTEM.FTE.AUTHOPS1.代理名称
  • SYSTEM.FTE.AUTHSCH1.代理名称
  • SYSTEM.FTE.AUTHTRN1.代理名称
  • SYSTEM.FTE.COMMAND。代理名称
  • SYSTEM.FTE.DATA.agent_name
  • SYSTEM.FTE.EVENT。代理名称
  • SYSTEM.FTE.REPLY。代理名称
  • SYSTEM.FTE.STATE.代理名称
  • SYSTEM.FTE.HA.代理名称
这些队列是内部系统队列，除非您要删除该代理，否则不得修改、删除或读取这些队列中的消息。 以下位置的文件中也提供了要运行的 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 命令在以下目录中创建 ProtocolBridgeProperties.xml XML 文件：MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name。

用户负责手动创建 ProtocolBridgeCredentials.xml 文件，该文件不再由 fteCreateBridgeAgent 命令创建。

ProtocolBridgeCredentials.xml 文件允许您定义用户名和凭证信息以供协议网桥代理用于请求协议服务器对自已进行授权，而 ProtocolBridgeProperties.xml 文件允许您定义多个协议文件服务器，以便您可以传输到多个端点。

MQ_INSTALLATION_PATH/mqft/samples/credentials/ 目录中有一个样本 ProtocolBridgeCredentials.xml 。 更多信息，请参阅协议桥证书文件格式和协议桥属性文件格式。

如果运行 fteCreateBridgeAgent 命令并指定缺省协议文件服务器（参数 -bt），那么该缺省服务器包含在 ProtocolBridgeProperties.xml 文件中且其主机名将用于服务器名称。 使用 -bt 参数时，您必须指定以下参数：
  • -bh
  • -btz
  • -bm
  • -bsl
  • -bfe
  • -bts

如果不指定缺省服务器，那么在 ProtocolBridgeProperties.xml 文件中没有条目；您必须手动添加至少一个服务器，然后才能进行传输。

Managed File Transfer 提供了帮助您配置协议网桥代理的高级代理属性。 与协议网桥相关的属性以 protocol 开头。 Advanced agent properties: Protocol bridge 和 Advanced agent properties: Protocol bridge agent logging中描述了这些属性。 如果您在协议网桥中发现意外的行为，请复审这些 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 原因码以说明原因。 此参考消息可能指示协调队列管理器当前不可用或者您未正确定义配置。
重要说明：

在 AIX 和 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 绑定到套接字文件失败

特殊字符

请谨慎使用包含特殊字符的参数值，从而避免命令 shell 以您不期望的方式解析字符。 例如，包含空格，引号 (单引号或双引号) ，反斜杠或正斜杠字符等字符的标准文件路径和名称可能由命令 shell 解释，而不是直接传递到命令本身。 为了避免命令 shell 解释字符，请使用双引号或单引号将整个参数括起来，或者使用命令 shell 的转义序列对特殊字符进行转义。 在 Windows 上指定文件路径时，请确保将分隔符反斜杠 (\) 输入为双反斜杠 (\\) ，即转义反斜杠 (\)。  或者，可以使用单个正斜杠 (/) 字符作为分隔符。"

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-mquseriduser_id-nolpw-mqpasswordpassword-nolpw-credentialsFilefile_path-useridusername-pconfiguration_options-f-x

参数

--agentName agent_name
必需。 要创建的代理的名称。 代理名称在其管理域中必须是唯一的。
有关命名代理程序的更多信息，请参阅 对象命名约定。
--agentQMgr agent_qmgr_name
必需。 代理队列管理器的名称。
-bt 协议文件服务器类型
可选。 指定您想要定义缺省协议文件服务器。 指定以下某个选项：
FTP
标准 FTP 服务器
SFTP
SSH FTP 服务器
FTPS
由 SSL 或 TLS 提供保护的 FTP 服务器
如果未指定该参数，那么不会定义缺省协议服务器。
-bh 服务器主机名
只有当您同时使用 -bt 参数指定缺省协议文件服务器时，该参数才为必需参数。 协议文件服务器的 IP 主机名或 IP 地址。
-btz 服务器时区
只有当您同时指定 -bt 参数时，该参数才为必需参数（仅限 FTP 和 FTPS 服务器）。 协议文件服务器的时区。 请按以下格式指定时区：区域/位置。 例如：欧洲/伦敦。
您可以使用 -htz 参数来列出 -btz 的可能值。 例如：fteCreateBridgeAgent -htz
-bm 服务器平台
只有当您同时使用 -bt 参数指定缺省协议文件服务器时，该参数才为必需参数。 协议文件服务器的平台类型。 指定以下某个选项：
UNIX
通用 UNIX 和 Linux 平台
Windows
类属 Windows 平台
OS400
IBM i 平台
注: 如果网桥代理要与运行 IBM i的 FTP 服务器进行通信，那么必须将 bm 参数设置为 OS400 和 blf 参数设置为 OS400IFS 。
-bsl server_locale
只有当您同时指定 -bt 参数时，该参数才为必需参数（仅限 FTP 和 FTPS 服务器）。 协议文件服务器的语言环境。 请按以下格式指定语言环境：xx_XX。 例如：en_GB。
-bfe 服务器文件编码
只有当您同时使用 -bt 参数指定缺省协议文件服务器时，该参数才为必需参数。 存储在协议文件服务器上的文件的字符编码格式。 例如：UTF-8。
您可以使用 -hcs 参数来列出 -bfe 的可能值。 例如：fteCreateBridgeAgent -hcs
-bts truststore_file
当您指定 -bt 参数时，该参数为必需参数（仅限 FTPS 服务器）。 指定用于验证 FTPS 服务器所提供证书的信任密钥库的路径。
仅当您在 -bt 参数上还指定了 FTPS 选项时，才能指定 -bts 参数。
-bp 服务器端口
可选。 协议文件服务器连接到的 IP 端口。 仅当协议文件服务器不使用该协议的缺省端口时，才指定该参数。 如果未指定此参数，那么 Managed File Transfer 会将缺省端口用于文件服务器的协议类型。
-blw
可选。 将协议文件服务器定义为具有受限的写入能力。 缺省情况下，协议网桥代理期望协议文件服务器允许删除文件、重命名文件以及打开文件进行附加写入。 指定此参数以指示协议文件服务器不允许这些文件操作。 相反，文件服务器只允许从文件读取和写入文件。 如果指定此参数，那么任何传输在中断后可能都无法恢复，并且可能导致当前的文件传输失败。
-blf 服务器列表格式
可选，仅限 FTP 和 FTPS 服务器。 定义从缺省协议文件服务器返回的已列出文件信息的服务器列表格式。 选项如下：
UNIX
通用 UNIX 和 Linux 平台
Windows
类属 Windows 平台
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，这是大多数服务器使用的格式。

--agentQMgrHost agent_qmgr_host
可选。 代理队列管理器的主机名或 IP 地址。
--agentQMgrPort agent_qmgr_port
可选。 用于客户机与代理队列管理器的连接的端口号。
--agentQMgrChannel agent_qmgr_channel
可选。 用于连接到代理队列管理器的通道名称。
--agentDesc agent_description
可选。 代理程序的描述，显示在 IBM MQ Explorer中。
-ac 或 -authorityChecking
可选。 此参数允许进行权限检查。 如果指定该参数，那么代理将检查提交请求的用户是否有权执行请求的操作。 有关更多信息，请参阅 限制用户对 MFT 代理程序操作的权限。
[Windows]- 服务名称
可选（仅限 Windows）。 指示代理程序将作为 Windows 服务运行。 如果不指定 service_name，那么服务将命名为 mqmftAgentAGENTQMGR，其中 AGENT 是代理名称；而 QMGR 是代理队列管理器名称。
服务的显示名称 (显示在 " Windows 服务 " 窗口的 名称 列中) 始终为 Managed File Transfer Agent AGENT@QMGR。
[Windows]- su user_name
可选（仅限 Windows）。 如果该代理程序将作为 Windows 服务运行，那么该参数指定作为该服务运行身份的帐户的名称。 要使用 Windows 域用户帐户运行代理程序，请以 DomainName\UserName格式指定值。 要使用本地内置域中的帐户来运行该服务，请以 UserName 格式指定该值。
您使用 -su 参数指定的 Windows 用户帐户必须具有 Log on as a service 权限。 有关如何授予此权限的信息，请参阅 对作为 Windows 服务运行的 MFT 代理或记录器进行故障诊断。
在指定 -s 时为必需项。
[Windows]- sp 密码
可选（仅限 Windows）。 -su 参数设置的用户帐户的密码。
该参数仅在指定 -s 时才有效。 如果在指定 -s 参数时不指定该参数，将生成警告消息。 该消息提醒您必须使用 Windows“服务”工具来设置密码，然后该服务才会成功启动。
[Windows]- sj选项
可选（仅限 Windows）。 当代理作为 Windows 服务启动时，以 -D 或 -X 格式来定义要传递到 JVM 的选项列表。 这些选项使用井号 (#) 或分号 (;) 字符进行分隔。 如果您必须嵌入任何 # 或分号 (;) 字符，请将其置于单引号内。
仅当指定了 -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 user_id
可选。 指定要向命令队列管理器进行认证的用户标识。
-mqpassword 密码
可选。 指定通过协调队列管理器进行认证时所使用的密码。
指定 -mqpassword 参数时，还必须指定 -mquserid 参数。 如果指定 -mquserid，但未指定 -mqpassword，那么系统将提示您提供关联的密码，不会显示该密码。

[MQ 9.3.0 2022 年 6 月][MQ 9.3.0 2022 年 6 月]从 IBM MQ 9.3 开始，命令默认使用 MQCSP 身份验证，并将用户ID和密码以MQCSP结构发送给队列管理器进行身份验证。

[MQ 9.3.0 2022 年 6 月][MQ 9.3.0 2022 年 6 月]-nolpw
可选。 如果命令连接到不支持长度超过 12 个字符的密码的队列管理器，请指定此参数。
指定 -nolpw 参数时，还必须指定 -mquserid 参数。 如果指定 -mquserid 和 -nolpw，但未指定 -mqpassword，那么系统会提示您提供关联的密码，不会显示该密码。
注: 如果指定 -nolpw 选项，并且密码长度超过 12 个字符，那么命令将失败并返回错误消息 BFGCL0829E。
--credentialsFile 文件
可选。 现有凭证文件或新凭证文件的完整文件路径，将向其添加 IBM MQ 认证详细信息。
此命令支持将一组 IBM MQ 认证详细信息添加到指定的 Managed File Transfer 凭证文件中。 当已启用 IBM MQ 连接认证时，请使用此命令。 如果要更新现有的详细信息，则必须使用 -f 强制参数。
-userid 用户名
可选。 用于关联凭证详细信息的用户标识。 如果未指定用户标识，将向所有用户应用凭证详细信息。 此外，还必须指定 -credentialsFile 参数。
-或-h
可选。 显示命令语法。
-x
可选。 创建要以高可用性方式运行的代理程序配置。
指定此参数会向 agent.properties 文件添加新选项 highlyAvailable 。

示例

在此示例中，新协议网桥代理程序 ACCOUNTS1 是使用代理程序队列管理器 QM_ACCOUNTS 创建的，并且使用缺省协调队列管理器。 ACCOUNTS1 连接到 FTP 服务器 accountshost.ibm.com。 此 FTP 服务器使用时区“欧洲/柏林”、语言环境 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
在此示例中，新协议网桥代理 ACCOUNTS2 是使用代理队列管理器 QM_ACCOUNTS 创建的，并且使用缺省协调管理器。 ACCOUNTS2 是在没有缺省协议文件服务器的情况下创建的。
fteCreateBridgeAgent -agentName ACCOUNTS2 -agentQMgr QM_ACCOUNTS
注: 以上内容不适用于 Managed File Transfer Agent 可再分发产品。
此处的方案是 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 命令可启动协议网桥代理。 更多信息，请访问 fteStartAgent （启动 MFT 代理 ）。 [z/OS]另请参阅在 z/OS 上启动MFT代理。