fteCreateAgent (create an MFT agent)

The fteCreateAgent command creates a Managed File Transfer Agent and its associated configuration.

You can control access to the agent. See Restricting user authorities on MFT agent actions for further information. You need to use the -ac parameter, and give permissions to access some queues.

Important: [UNIX, Linux, Windows]

On IBM® MQ for UNIX, Linux®, and Windows, only users who are IBM MQ administrators (and members of the mqm group) can run this command. If you try to run this command as a user who is not an IBM MQ administrator, you will receive the error message BFGCL0502E: You are not authorized to perform the requested operation. and the command will not run.

On z/OS® systems, the user must satisfy (at least) one of these conditions in order to run the migrate command:

Be a member of the mqm group (if the mqm group is defined on the system).
Be a member of the group named in the BFG_GROUP_NAME environment variable (if one is named).
Have no value set in the BFG_GROUP_NAME environment variable when the command is run.

Purpose

Use the fteCreateAgent command to create an agent. This command provides you with the MQSC commands that you must run against your agent queue manager to create the following agent queues:

SYSTEM.FTE.AUTHADM1.agent_name
SYSTEM.FTE.AUTHAGT1.agent_name
SYSTEM.FTE.AUTHMON1.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

These queues are internal system queues that you must not modify, delete, or read messages from unless you are deleting the agent. The MQSC commands to run are also supplied in a file in the following location: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc.

If you later want to delete the agent, this command also provides you with the MQSC commands you must run to clear then delete the queues used by the agent. The MQSC commands are in a file in the following location: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc.

Managed File Transfer provides advanced agent properties that help you configure agents. These properties are described in The agent.properties file.

You might need to create a MQMFTCredentials.xml credentials file in order to work with your agent. A sample of this file is located in MQ_INSTALLATION_PATH/mqft/samples/credentials/. For more information and examples, see MFT credentials file format.

Important:

On UNIX platforms and Linux Managed File Transfer commands use socket files to communicate with the agent process running on the same host machine.

These socket files are created in the log directory of the agent and are deleted when an agent stops. In the IBM MQ Managed File Transfer installation, this socket file is created with a file path of: <MQ_DATA_PATH>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME> where MQ_DATA_PATH is /var/mqm by default.

For a re-distributable agent, this socket file is created under the directory: <RE_DISTRIBUTABLE_DIRECTORY>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME>.

For example, if the agent name is SRCAGENT, the agent queue manager name is SRCAGENTQM, the coordination queue manager name is COORDQM, and the redistributable agent is running from the directory /home/myuser/mqmft-redist, the full path of this socket file is: /home/myuser/mqmft-redist/mqft/logs/COORDQM/agents/SRCAGENT/logs/SRCAGENT@SRCAGENTQM

which is a total file path length of 85 characters.

The maximum path length allowed by these operating systems for a socket file is 107 characters. Therefore, when creating an agent, take care to ensure that the socket file path does not exceed 107 characters. This is particularly important with a redistributable agent where the log directory of the agent can be located in an arbitrary directory location. See the fteCreateEnvironment command for details on setting up the configuration directory.

If you start an agent, or other commands that connect to the agent are run, and your path length exceeds 107 characters you receive the following message:

BFGNV0159E: Failed trying to bind to socket file with FFDC

Special characters

Take care when you use parameter values that contain special characters so that you avoid the command shell interpreting the characters in a way you do not expect. For example, fully qualified file paths and names that contains such characters as space, quotation mark (single or double), forward-slash or back-slash characters, might be interpreted by the command shell rather than being passed through directly to the command itself. To avoid characters being interpreted by the command shell, enclose the entire parameter in double/single quotation marks or escape the special characters by using the escape sequence of the command shell.

Syntax

fteCreateAgent

Parameters

-agentName (agent_name)

Required. The name of the agent you want to create. The agent name must be unique to its coordination queue manager.

For more information about naming agents, see Object naming conventions.

-agentQMgr (agent_qmgr_name)

Required. The name of the agent queue manager.

-agentQMgrHost (agent_qmgr_host)

Optional. The host name or IP address of the agent queue manager.

-agentQMgrPort (agent_qmgr_port)

Optional. The port number used for client connections to the agent queue manager.

-agentQMgrChannel (agent_qmgr_channel)

Optional. The channel name used to connect to the agent queue manager.

-agentDesc (agent_description)

Optional. A description of the agent, which is displayed in IBM MQ Explorer.

-ac or -authorityChecking

Optional. This parameter enables authority checking. If you specify this parameter, the agent checks that users who are submitting requests are authorized to perform the requested action. For more information, see Restricting user authorities on MFT agent actions.

-s (service_name)

Optional (Windows only). Indicates that the agent is to run as a Windows service, the command must be run from a Windows administrator user ID. If you do not specify service_name, the service is named mqmftAgentAGENTQMGR, where AGENT is the agent name and QMGR is your agent queue manager name.

The display name for the service, which is shown in the Windows Services window in the Name column, is always Managed File Transfer Agent AGENT@QMGR.

Note: If the redistributable agent is going to run as a Windows service, then the BFG_DATA environment variable needs to be set in the system environment for the service to work.

-su (user_name)

Optional (Windows only). When the agent is to run as a Windows service, this parameter specifies the name of the account under which the service runs. To run the agent using a Windows domain user account specify the value in the form DomainName\UserName. To run the service using an account from the local built-in domain specify the value in the form UserName.

The Windows user account that you specify using the -su parameter must have the Log on as a service right. For information about how to grant this right, see Guidance for running an MFT agent or logger as a Windows service.

Required when -s specified.

-sp (password)

Optional (Windows only).

This parameter is only valid when -s is specified. If you do not specify this parameter when you specify the -s parameter, a warning message is produced. This message warns you that you must set the password using the Windows Services tool before the service starts successfully.

-sj (options)

Optional (Windows only). When the agent is started as a Windows service, defines a list of options in the form of -D or -X that are passed to the JVM. The options are separated using a number sign (#) or semicolon (;) character. If you must embed any # or semicolon (;) characters, put them inside single quotation marks.

This parameter is only valid when -s is specified.

-sl (options)

Optional (Windows only). Sets the Windows service log level. Valid options are: error, info, warn, debug. The default is info. This option can be useful if you are having problems with the Windows service. Setting it to debug gives more detailed information in the service log file.

This parameter is only valid when -s is specified.

-n

Optional (Windows only). Indicates that the agent is to be run as a normal process. This is mutually exclusive with the -s option. If neither one of the -s parameter and the -n parameter is specified, then the agent is configured as a normal Windows process.

-p (configuration_options)

Optional. This parameter determines the set of configuration options that is used to create an agent. By convention use the name of a non-default coordination queue manager as the input for this parameter. The fteCreateAgent command then uses the set of properties files associated with this non-default coordination queue manager.

Specify the optional -p parameter only if you want to use configuration options different from your defaults. If you do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

-mquserid (userID)

Optional. Specifies the user ID to authenticate with the coordination queue manager.

-mqpassword (password)

Optional. Specifies the password to authenticate with the coordination queue manager. You must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, you will be prompted to supply the associated password. The password will not be displayed.

-credentialsFile (filePath)

Optional. The full file path of an existing or new credentials file, to which the IBM MQ authentication details are added.

This command supports the addition of a set of IBM MQ authentication details, to a named Managed File Transfer credentials file. Use this command when IBM MQ connection authentication has been enabled. If you update the existing details, you must use the -f force parameter.

-credentialPath (credentials_path).

This command defines the location to migrate the credential information to. This parameter can be a directory path to an existing credential file, or a directory path to a new credential file. [z/OS]

On z/OS platforms the credential file can be a pre-existing partitioned data set extended (PDSE). The PDSE can include existing members, or a new member for the credential file. Existing members of the PDSE must be updated to include the credential file. The format of the PDSE must be variable blocked.

-f

Optional. Forces the command to overwrite non-matching existing parameters. Specifying this parameter does not force the replacement of an existing Windows service agent.

-? or -h

Optional. Displays command syntax.

Example

In this example, AGENT3 is created with an agent queue manager QM_NEPTUNE and uses the default coordination queue manager:


fteCreateAgent -agentName AGENT3 -agentQMgr QM_NEPTUNE
 -agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1

Return codes

0: Command completed successfully.
1: Command ended unsuccessfully.