fteCreateAgent（创建 "MFT代理）

fteCreateAgent 命令创建 Managed File Transfer Agent 及其关联的配置。

您可以控制对代理的访问。 有关更多信息，请参阅 限制用户对 MFT 代理程序操作的权限 。 您必须使用 -ac 参数，并提供许可权来访问一些队列。

重要说明：
[UNIX、Linux、Windows]在 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]在 z/OS® 系统上，您必须满足以下条件中的至少一项才能运行该命令：
  • 是 mqm 组的成员（如果在系统上定义了 mqm 组）。
  • 成为 BFG_GROUP_NAME环境变量 （如果有）中指定的组成员。
  • 运行命令时 ，BFG_GROUP_NAME环境变量中没有设置任何值。

用途

使用 fteCreateAgent 命令可创建代理。 该命令向您提供 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.代理名称
  • [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。

Managed File Transfer 提供了帮助您配置代理程序的高级代理程序属性。 agent.properties 文件中描述了这些属性。

您可能需要创建 MQMFTCredentials.xml 凭证文件才能使用您的代理。 此文件的样本位于 MQ_INSTALLATION_PATH/mqft/samples/credentials/ 中。 更多信息和示例，请参阅 MFT证书文件格式。

重要说明：

在 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

fteCreateAgent

Read syntax diagramSkip visual syntax diagramfteCreateAgent-agentName agent_name -agentQMgr agent_qmgr_name -agentQMgrHost agent_qmgr_host-agentQMgrPort agent_qmgr_port-agentQMgrChannel agent_qmgr_channel-agentDesc agent_description-ac-authorityChecking-s service_name-su user_name -sp password-sj options-sl options -n-mquseriduserID-mqpasswordpassword-credentialsFilefilePath-p configuration_options -f-x

参数

--agentName（代理名称）
必需。 要创建的代理的名称。 代理名称对其协调队列管理器必须唯一。

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

--agentQMgr(agent_qmgr_name)
必需。 代理队列管理器的名称。
--agentQMgrHost(agent_qmgr_host)
可选。 代理队列管理器的主机名或 IP 地址。

--agentQMgrPort(agent_qmgr_port)
可选。 用于客户机与代理队列管理器的连接的端口号。

--agentQMgrChannel(agent_qmgr_channel)
可选。 用于连接到代理队列管理器的通道名称。

--agentDesc(agent_description)
可选。 代理程序的描述，显示在 IBM MQ Explorer中。

-ac 或 -authorityChecking
可选。 此参数允许进行权限检查。 如果指定该参数，那么代理将检查提交请求的用户是否有权执行请求的操作。 有关更多信息，请参阅 限制用户对 MFT 代理程序操作的权限。

[Windows]-s (service_name )
可选（仅限 Windows）。 指示代理将作为 Windows 服务运行，必须使用 Windows 管理员用户标识运行该命令。 如果不指定 service_name，那么服务将命名为 mqmftAgentAGENTQMGR，其中 AGENT 是代理名称；而 QMGR 是代理队列管理器名称。

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

注: 如果可再分发代理程序将作为 Windows 服务运行，那么需要在系统环境中设置 BFG_DATA 环境变量才能使服务工作。
[Windows]-su （用户名 ）
可选（仅限 Windows）。 如果该代理程序将作为 Windows 服务运行，那么该参数指定作为该服务运行身份的帐户的名称。 要使用 Windows 域用户帐户运行代理程序，请以 DomainName\UserName格式指定值。 要使用本地内置域中的帐户来运行该服务，请以 UserName 格式指定该值。

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

在指定 -s 时为必需项。

[Windows]-sp （密码 ）
可选（仅限 Windows）。

该参数仅在指定 -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(配置选项)
可选。 该参数确定用于创建代理程序的配置选项集。 按照约定，请使用非缺省协调队列管理器的名称作为该参数的输入。 然后， fteCreateAgent 命令将使用与此非缺省协调队列管理器相关联的属性文件集。

仅在您希望使用不同于缺省值的配置选项时，才指定可选的 -p 参数。 如果未指定该参数，那么将使用基于缺省协调队列管理器的配置选项集。

-mquserid (userID)
可选。 指定通过协调队列管理器进行认证时所使用的用户标识。
-mqpassword (password)
可选。 指定通过协调队列管理器进行认证时所使用的密码。 此外，还必须指定 -mquserid 参数。 如果指定了 -mquserid，但未指定 -mqpassword，将会提示您提供相关联的密码。 将不会显示密码。
-credentialsFile (filePath)
可选。 现有凭证文件或新凭证文件的完整文件路径，将向其添加 IBM MQ 认证详细信息。

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

--credentialPath（credentials_path）。
该命令定义要将凭证信息迁移到的位置。 此参数可以是现有凭证文件的目录路径，也可以是新凭证文件的目录路径。 [z/OS]在 z/OS 平台上，证书文件可以是预先存在的分区数据集扩展（PDSE）。 PDSE 可以包含现有成员，或凭证文件的新成员。 必须更新 PDSE 的现有成员，以包含凭证文件。 PDSE 的格式必须为分块变量。
-f
可选。 强制命令覆盖不匹配的现有参数。 指定此参数不会强制替换现有 Windows 服务代理。

-或-h
可选。 显示命令语法。
[V9.1.4 2019 年 12 月]-x
可选。 创建要以高可用性方式运行的代理程序配置。
指定此参数会向 agent.properties 文件添加新选项 highlyAvailable 。

示例

在此示例中，AGENT3 是使用代理队列管理器 QM_NEPTUNE 创建的，并且使用缺省协调队列管理器：
fteCreateAgent -agentName AGENT3 -agentQMgr QM_NEPTUNE
 -agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1
[V9.1.4 2019 年 12 月]在这个示例中， AGHA 是在高可用性模式下创建的，并使用代理队列管理器 QMHA。
fteCreateAgent -agentName AGHA -agentQMgr QMHA -x

返回码

0
命令成功完成。
1
命令结束但未成功。