fteCreateCDAgent (create a Connect:Direct bridge agent)
The fteCreateCDAgent command creates a Managed File Transfer Agent and its associated configuration for use with the Connect:Direct® bridge.
- 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 fteCreateCDAgent command to create a Connect:Direct bridge agent. This type of agent is dedicated to transferring files to and from Connect:Direct nodes. For more information, see The Connect:Direct bridge. For details of the supported operating system versions for the Connect:Direct bridge, see the web page System Requirements for IBM MQ.
- 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 belonging to 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 MFT agent.properties file.
The fteCreateCDAgent command creates two XML files in the agent properties directory. ConnectDirectNodeProperties.xml, which is used to define information about the remote nodes in a transfer, and ConnectDirectProcessDefinitions.xml, which is used to specify which user-defined Connect:Direct processes are started by transfers.
To define user names and passwords that the Connect:Direct bridge agent uses to connect to Connect:Direct nodes, you must manually create a ConnectDirectCredentials.xml file. Sample XML files are located in MQ_INSTALLATION_PATH/mqft/samples/credentials/. For more information and examples, see Connect:Direct credentials file format.
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.
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.
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.
- -agentQMgr agent_qmgr_name
- Required. The name of the agent queue manager.
- -cdNode cd_node_name
- Required. The name of the Connect:Direct node to use to transfer messages from this agent to destination Connect:Direct nodes. The value of this parameter is used for logging and not to specify to the Connect:Direct bridge agent which node to connect to. The values of the -cdNodeHost and -cdNodePort specify the Connect:Direct node that is part of the Connect:Direct bridge.
- -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.
- -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
fteCreateCDAgent 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.
- -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.
- -cdNodeHost cd_node_host_name
- Optional. The host name or IP address of the system where the Connect:Direct node, specified by the -cdNode parameter, is located. If you do not specify the -cdNodeHost parameter, a default of the host name or IP address of the local system is used.
- -cdNodePort cd_node_port_name
- Optional. The port number of the Connect:Direct node that client applications use to communicate with the node that is specified by the -cdNode parameter. In Connect:Direct product documentation, this port is referred to as the API port. If you do not specify the -cdNodePort parameter, a default port number of 1363 is assumed.
- -cdTmpDir cd_tmp_directory
- Optional. The directory to be used by this agent to store files temporarily before they are
transferred to the destination Connect:Direct node. This
parameter specifies the full path of the directory where files are temporarily stored. For example,
if cdTmpDir is set to /tmp then the files are temporarily
placed in the /tmp directory. If you do not specify the
-cdTmpDir parameter, the files are stored temporarily in a directory named
cdbridge-agent_name. This default directory is created in
the location that is defined by the value of the
java.io.tmpdir
property.The Connect:Direct bridge agent and the Connect:Direct bridge node must be able to access the directory specified by this parameter using the same path name. Consider this when planning the installation of your Connect:Direct bridge. If possible, create the agent on the system where the Connect:Direct node that is part of the Connect:Direct bridge is located. If your agent and node are on separate systems, the directory must be on a shared file system and be accessible from both systems using the same path name. For more information about the supported configurations, see The Connect:Direct bridge.
Note: If you run the fteCleanAgent command, all files in this directory are deleted. - -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. - -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 formUserName
. - -sp password
- Optional (Windows only).
- -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.
- -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.
- -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.
- -mquserid user_id
- Optional. Specifies the user ID to authenticate with the command queue manager.
- -mqpassword password
- Optional. Specifies the password to authenticate with the command 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 file_path
- Optional. The full file path of an existing or new credentials file, to which the IBM MQ authentication details are added.
- -userid username
- Optional. The user ID used to associate the credential details. If you do not specify a user ID, the credential details will apply to all users. You must also specify the -credentialsFile parameter.
Example
In this example, a new Connect:Direct bridge agent CD_BRIDGE is created with an agent queue manager QM_NEPTUNE. The agent uses the Connect:Direct node BRIDGE_NODE to transfer files to other Connect:Direct nodes. The BRIDGE_NODE node is located on the same system as the agent and uses the default port for client connections. Files that are transferred to or from Connect:Direct are temporarily stored in the directory /tmp/cd-bridge.
fteCreateCDAgent -agentName CD_BRIDGE -agentQMgr QM_NEPTUNE
-cdNode BRIDGE_NODE -cdTmpDir /tmp/cd-bridge
Return codes
- 0
- Command completed successfully.
- 1
- Command ended unsuccessfully.