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

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

重要说明：

在 UNIX, 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® 系统上，您必须满足以下条件中的至少一个才能运行该命令：

是 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.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 命令在以下目录中创建 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 原因码以说明原因。此参考消息可能指示协调队列管理器当前不可用或者您未正确定义配置。

重要说明：

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

特殊字符

请谨慎使用包含特殊字符的参数值，从而避免命令 shell 以您不期望的方式解析字符。例如，包含空格、引号（单或双）、正斜杠或反斜杠之类字符的标准文件路径和名称可能由命令 shell 进行解释，而不是直接传递到命令本身。为避免命令 shell 解释字符，请将整个参数括在双引号/单引号中，或者使用命令 shell 的转义序列来转义特殊字符。

Syntax

fteCreateBridgeAgent

参数

--agentName（代理名称）

必需。要创建的代理的名称。代理名称在其管理域中必须是唯一的。

有关命名代理程序的更多信息，请参阅对象命名约定。

--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 服务器）。协议文件服务器的时区。请按以下格式指定时区：区域/位置。例如：欧洲/伦敦。

您可以使用 -htz 参数来列出 -btz 的可能值。例如：fteCreateBridgeAgent -htz

-bm (server_platform)

只有当您同时使用 -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。

xx 是 ISO 语言代码。有效值列表请参见《语言名称表示法代码》。
XX 是 ISO 国家或地区代码。有效值列表请参见国家名称和代码元素

-bfe (server_file_encoding)

只有当您同时使用 -bt 参数指定缺省协议文件服务器时，该参数才为必需参数。存储在协议文件服务器上的文件的字符编码格式。例如：UTF-8。

您可以使用 -hcs 参数来列出 -bfe 的可能值。例如：fteCreateBridgeAgent -hcs

-bts (truststore_file)

当您指定 -bt 参数时，该参数为必需参数（仅限 FTPS 服务器）。指定用于验证 FTPS 服务器所提供证书的信任密钥库的路径。

仅当您在 -bt 参数上还指定了 FTPS 选项时，才能指定 -bts 参数。

-bp (server_port)

可选。协议文件服务器连接到的 IP 端口。仅当协议文件服务器不使用该协议的缺省端口时，才指定该参数。如果未指定此参数，那么 Managed File Transfer 会将缺省端口用于文件服务器的协议类型。

-blw

可选。将协议文件服务器定义为具有受限的写入能力。缺省情况下，协议网桥代理期望协议文件服务器允许删除文件、重命名文件以及打开文件进行附加写入。指定此参数以指示协议文件服务器不允许这些文件操作。相反，文件服务器只允许从文件读取和写入文件。如果指定此参数，那么任何传输在中断后可能都无法恢复，并且可能导致当前的文件传输失败。

-blf (服务器列表格式)

可选，仅限 FTP 和 FTPS 服务器。定义从缺省协议文件服务器返回的已列出文件信息的服务器列表格式。选项如下：

UNIX

通用 UNIX 和 Linux 平台

Windows

类属 Windows 平台

OS400IFS

IBM i 平台上的根文件系统

注：

如果网桥代理要与运行 IBM i的 FTP 服务器通信，那么必须将 bm 参数设置为 OS400 和 blf 参数设置为 OS400IFS 。
只能使用 Managed File Transfer 在根 (/) 文件系统上发送和接收文件。其他文件系统不起作用。

要确定将要选择的格式，请使用 FTP 客户机程序，列出目录并选择最适合的格式。例如

UNIX 显示以下类型的列表：

-rwxr-xr-x 2 userid groupId 4096 2009-07-23 09:36 filename

Windows 显示以下类型的列表：

437,909 filename

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 代理程序操作的权限。

-s (service_name )

可选（仅限 Windows）。指示代理程序将作为 Windows 服务运行。如果不指定 service_name，那么服务将命名为 mqmftAgentAGENTQMGR，其中 AGENT 是代理名称；而 QMGR 是代理队列管理器名称。

服务的显示名称 (显示在 " Windows 服务 " 窗口的名称列中) 始终为 Managed File Transfer Agent AGENT@QMGR。

-su （用户名 ）

可选（仅限 Windows）。如果该代理程序将作为 Windows 服务运行，那么该参数指定作为该服务运行身份的帐户的名称。要使用 Windows 域用户帐户运行代理程序，请以 DomainName\UserName格式指定值。要使用本地内置域中的帐户来运行该服务，请以 UserName 格式指定该值。

您使用 -su 参数指定的 Windows 用户帐户必须具有 Log on as a service 权限。有关如何授予此权限的信息，请参阅有关将 MFT 代理程序或记录器作为 Windows 服务运行的指南。

在指定 -s 时为必需项。

-sp （密码 ）

可选（仅限 Windows）。 -su 参数设置的用户帐户的密码。

该参数仅在指定 -s 时才有效。如果在指定 -s 参数时不指定该参数，将生成警告消息。该消息提醒您必须使用 Windows“服务”工具来设置密码，然后该服务才会成功启动。

-sj （选项 ）

可选（仅限 Windows）。当代理作为 Windows 服务启动时，以 -D 或 -X 格式来定义要传递到 JVM 的选项列表。这些选项使用井号 (#) 或分号 (;) 字符进行分隔。如果您必须嵌入任何 # 或分号 (;) 字符，请将其置于单引号内。

仅当指定了 -s 时，此参数才有效。

-sl （选项 ）

可选（仅限 Windows）。设置 Windows 服务日志级别。有效选项是：error、info、warn、debug。缺省值为 info。如果 Windows 服务出现问题，那么该选项可能很有用。如果将其设置为 debug，那么会在服务日志文件中提供更详细的信息。

该参数仅在指定 -s 时才有效。

-n

可选（仅限 Windows）。指示代理将作为正常进程运行。这与 -s 选项互斥。如果 -s 参数和 -n 参数均未指定，那么该代理程序将配置为正常 Windows 进程。

--p(配置-选项)

可选。该参数确定用于创建代理程序的配置选项集。按照约定，请使用非缺省协调队列管理器的名称作为该参数的输入。然后，fteCreateBridgeAgent 命令使用与此非缺省协调队列管理器关联的属性文件集。

仅在您希望使用不同于缺省值的配置选项时，才指定可选的 -p 参数。如果未指定 -p，那么将使用 installation.properties 文件中定义的配置选项。请参阅配置选项以获取更多信息。

-f

可选。强制该命令覆盖现有配置。

-htz

可选。显示受支持时区（您可以将其用作 -btz 参数的输入）的列表。

-hcs

可选。显示受支持字符集（您可以将其用作 -bfe 参数的输入）的列表。

运行 fteCreateBridgeAgent -hcs 命令以列出 JVM 的已知代码页。通过外部源无法使用此信息，因为已知代码页在 JVM 之间有所变化。

-mquserid (userID)

可选。指定要向命令队列管理器进行认证的用户标识。

-mqpassword (password)

可选。指定要向命令队列管理器进行认证的密码。此外，还必须指定 -mquserid 参数。如果指定了 -mquserid，但未指定 -mqpassword，将会提示您提供相关联的密码。将不会显示密码。

-credentialsFile (filePath)

可选。现有凭证文件或新凭证文件的完整文件路径，将向其添加 IBM MQ 认证详细信息。

此命令支持将一组 IBM MQ 认证详细信息添加到指定的 Managed File Transfer 凭证文件中。当已启用 IBM MQ 连接认证时，请使用此命令。如果要更新现有的详细信息，则必须使用 -f 强制参数。

-userid (username)

可选。用于关联凭证详细信息的用户标识。如果未指定用户标识，将向所有用户应用凭证详细信息。此外，还必须指定 -credentialsFile 参数。

-或-h

可选。显示命令语法。

-x

可选。创建要以高可用性方式运行的代理程序配置。

指定此参数会向 agent.properties 文件添加新选项 highlyAvailable 。

不推荐使用的参数

以下参数已不推荐使用，并且在 IBM WebSphere® MQ 7.5 或 IBM WebSphere MQ File Transfer Edition 7.0.2 或更高版本上不受支持。

-brd (reconnect_delay): 不推荐使用。可选。指定重新建立与协议文件服务器之间所丢失连接的相邻尝试之间的延迟时间段（以秒为单位）。缺省值为 10 秒。
-brr (reconnect_retries): 不推荐使用。可选。指定尝试重新建立与缺省协议文件服务器之间丢失的连接时的最大重试次数。达到此最大次数之后，当前文件传输将归类为失败。缺省值为 2。

示例

在此示例中，新协议网桥代理程序 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] 另请参阅启动 MFT 代理程序，地址为 z/OS。