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.
Purpose
- 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
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.
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
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:
The default is UNIX, which is the format used by most servers.437,909 filename
- -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 formUserName
.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.
- -? 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
fteCreateBridgeAgent -agentName ACCOUNTS2 -agentQMgr QM_ACCOUNTS
Return codes
- 0
- Command completed successfully.
- 1
- Command ended unsuccessfully.