fteCreateBridgeAgent (create and configure WebSphere MQ Managed File Transfer protocol bridge agent)

The fteCreateBridgeAgent command creates a protocol bridge agent and its associated configuration. Create a protocol bridge agent for each file server that you want to send files to and receive files from.

Important: Only users who are WebSphere® 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 a WebSphere MQ administrator, you will receive an error message and the command will not run.

Purpose

Use the fteCreateBridgeAgent command to create a protocol bridge agent. For an overview of how to use the protocol bridge, see The protocol bridge. This fteCreateBridgeAgent 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 use 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.

The fteCreateBridgeAgent command creates a ProtocolBridgeProperties.xml XML file in the following directory: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name. The user must manually create a ProtocolBridgeCredentials.xml file. The ProtocolBridgeCredentials.xml file allows you to define user names and credential information that the protocol bridge agent uses to authorize itself with the protocol server and the ProtocolBridgeProperties.xml file allows you to define multiple protocol file servers so you can transfer to multiple endpoints. There is a sample ProtocolBridgeCredentials.xml in the MQ_INSTALLATION_PATH/mqft/samples/credentials/ directory. For more information, see Protocol bridge credentials file format and Protocol bridge properties file format. If you run the fteCreateBridgeAgent command and specify a default protocol file server, this default server is contained in the ProtocolBridgeProperties.xml file and its hostname is used for the server name. If you do not specify a default server, there are no entries in the ProtocolBridgeProperties.xml file; you must add at least one server manually before transfers can take place.

WebSphere MQ Managed File Transfer provides advanced agent properties that help you configure protocol bridge agents. The properties that relate to the protocol bridge start with protocol. These properties are described in The agent.properties file. If you see unexpected behavior in the protocol bridge, review these protocol properties and ensure that you have set these properties correctly for your system.

If you see the following output from the fteCreateBridgeAgent command:

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.

it indicates that the coordination queue manager can not be contacted and provides the IBM® WebSphere MQ reason code for why. This information message can indicate that the coordination queue manager is currently unavailable or that you have defined the configuration incorrectly.

Syntax

fteCreateBridgeAgent

Parameters

-agentName(agent_name)

Required. The name of the agent you want to create. The agent name must be unique in its administrative domain.

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

-agentQMgr(agent_qmgr_name)

Required. The name of the agent queue manager.

-bt(protocol_file_server_type)

Optional. Specifies that you want to define a default protocol file server. Specify one of the following options:

FTP: Standard FTP server
SFTP: SSH FTP server
FTPS: FTP server secured using SSL or TLS

If you do not specify this parameter, no default protocol server is defined.

-bh(server_host_name)

Required only if you also specify a default protocol file server using the -bt parameter. The IP host name or IP address of the protocol file server.

-btz(server_time_zone)

Required only if you also specify the -bt parameter (FTP and FTPS servers only). The time zone of the protocol file server. Specify the time zone in the following format: Area/Location. For example: Europe/London.

You can use the -htz parameter to list the possible values for -btz. For example: fteCreateBridgeAgent -htz

-bm(server_platform)

Required only if you also specify a default protocol file server using the -bt parameter. The platform type of the protocol file server. Specify one of the following options:

UNIX: Generic UNIX platform
WINDOWS: Generic Windows platform

-bsl(server_locale)

Required only if you also specify the -bt parameter (FTP and FTPS servers only). The locale of the protocol file server. Specify the locale in the following format: xx_XX. For example: en_GB.

xx is the ISO Language Code. For a list of valid values, see Codes for the Representation of Names of Languages
XX is the ISO Country Code. For a list of valid values, see Country names and code elements

-bfe(server_file_encoding)

Required only if you also specify a default protocol file server using the -bt parameter. The character encoding format of the files stored on the protocol file server. For example: UTF-8.

You can use the -hcs parameter to list the possible values for -bfe. For example: fteCreateBridgeAgent -hcs

-bts(truststore_file)

Required when you specify the -bt parameter (FTPS servers only). Specifies the path to a truststore that is used to validate the certificate presented by the FTPS server.

You can specify the -bts parameter only if you have also specified the FTPS option on the -bt parameter.

-bp(server_port)

Optional. The IP port that the protocol file server is connected to. Specify this parameter only if your protocol file server does not use the default port for that protocol. If you do not specify this parameter, WebSphere MQ Managed File Transfer uses the default port for the protocol type of file server.

-blw

Optional. Defines the protocol file server as having limited write abilities. By default, a protocol bridge agent expects the protocol file server to permit file deletion, file renaming, and file opening for append writing. Specify this parameter to indicate that the protocol file server does not permit these file actions. Instead the file server permits read from and write to file only. If you specify this parameter, any transfers might not be recoverable if they are interrupted and might result in a failure for the file currently being transferred.

-blf(server listing format)

Optional and for FTP and FTPS servers only. Defines the server listing format of the listed file information returned from the default protocol file server. The options are as follows:

UNIX: Generic UNIX platform
WINDOWS: Generic Windows platform

To identify which format to select, use a FTP client program and perform a listing of a directory and select which format is the best fit. For example,

UNIX displays the following type of listing:

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

Windows displays the following type of listing:

437,909 filename

The default is UNIX, which is the format used by most servers.

-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 the IBM WebSphere 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 User authorities on WebSphere MQ Managed File Transfer actions.

-s(service_name)

Optional (Windows only). Indicates that the agent is to run as a Windows service. If you do not specify service_name, the service is named mqmftAgent<AGENT><QMGR>, 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 WebSphere MQ Managed File Transfer agent <AGENT>@<QMGR>.

-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 agent or logger as a Windows service.

Required when -s specified. Equivalent to -serviceUser.

-sp(password)

Optional (Windows only). Password for the user account set by -su or -serviceUser parameter.

This parameter is only valid when -s is specified. Equivalent to -servicePassword. 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. Equivalent to -serviceJVMOptions.

-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. Equivalent to -serviceLogLevel.

-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.

Equivalent to -normal.

-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 fteCreateBridgeAgent 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 -p, the configuration options defined in the installation.properties file are used. See Configuration options for more information.

-f

Optional. Forces the command to overwrite the existing configuration.

-htz

Optional. Displays a list of supported time zones that you can use as input for the -btz parameter.

-hcs

Optional. Displays a list of supported character sets that you can use as input for the -bfe parameter.

Run the fteCreateBridgeAgent -hcs command to list the known code pages for the JVM. This information is not available from an external source because the known code pages vary between JVMs.

-? or -h

Optional. Displays command syntax.

Deprecated parameters

The following parameters have been deprecated and are not supported on IBM WebSphere MQ V7.5 or on WebSphere MQ Managed File Transfer V7.0.2, or later.

-brd(reconnect_delay): Deprecated. Optional. Specifies in seconds the delay period between attempts to re-establish a lost connection with the protocol file server. The default value is 10 seconds.
-brr(reconnect_retries): Deprecated. Optional. Specifies the maximum number of times to try again when attempting to re-establish a lost connection with the default protocol file server. When this maximum number is reached, the current file transfer is classed as failed. The default value is 2.

Example

In this example, a new protocol bridge agent ACCOUNTS1 is created with an agent queue manager QM_ACCOUNTS and uses the default coordination queue manager. ACCOUNTS1 connects to the FTP server accountshost.ibm.com. This FTP server runs on Windows using a time zone of Europe/Berlin, a locale of de_DE, and a file encoding of UTF-8. The number of reconnect retries is 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

In this example, a new protocol bridge agent ACCOUNTS2 is created with an agent queue manager QM_ACCOUNTS and uses the default coordination manager. ACCOUNTS2 is created without a default protocol file server.

fteCreateBridgeAgent -agentName ACCOUNTS2 -agentQMgr QM_ACCOUNTS

Return codes

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