fteCreateBridgeAgent (create and configure an MFT protocol bridge agent)
The fteCreateBridgeAgent command creates a Managed File Transfer 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.
- 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
- 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
- SYSTEM.FTE.HA.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.
Users are responsible for manually creating the ProtocolBridgeCredentials.xml file, it is no longer created by the fteCreateBridgeAgent command.
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.
- -bh
- -btz
- -bm
- -bsl
- -bfe
- -bts
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.
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 Advanced agent properties: Protocol bridge and Advanced agent properties: Protocol bridge agent logging. 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.
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 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.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.
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.
- -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
- -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.
- -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 and Linux platform
- WINDOWS
- Generic Windows platform
- OS400
- IBM i platformNote: You must set the both the bm parameter to OS400 and the blf parameter to OS400IFS if the bridge agent is to communicate with an FTP server running IBM i.
- -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.
- -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.
- -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, 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 and Linux platform
- WINDOWS
- Generic Windows platform
- OS400IFS
- Root file system on IBM i platformNotes:
- You must set the both the bm parameter to OS400 and the blf parameter to OS400IFS if the bridge agent is to communicate with an FTP server running IBM i.
- You can use Managed File Transfer to send and receive files on the root (/) file system only. Other file systems do not work.
- -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 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.
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). Password for the user account set by the -su parameter.
- -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.
- -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.
- -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.
- -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.
- -? or -h
- Optional. Displays command syntax.
- -x
- Optional. Creates an agent configuration to run in a high availability mode.
Deprecated parameters
The following parameters have been deprecated and are not supported on IBM WebSphere® MQ 7.5 or on IBM WebSphere MQ File Transfer Edition 7.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.
Examples
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
fteCreateTransfer -rt -1 -sa SRC -sm MFTQM -da OS400FTP -dm MFTQM -dce 37 -sce 1252
-t text -de overwrite -df "<your-domain>:/home/mft/text/uploadwcp.log"
"C:\temp\os400\Text\uploadwcp.log"
and, if you require the receiving file in the native
code page from IBM i:
fteCreateTransfer -rt -1 -da SRC -dm MFTQM -sa OS400FTP -sm MFTQM -sce 37 -dce 1252
-t text -de overwrite -df "C:\temp\os400\Text\downloadwcp.log"
"<your-domain>:/home/mft/text/uploadwcp.log"
Additional customizing
If you used the -bt parameter (and the additional parameters that are required) there will be a default server name in the ProtocolBridgeProperties.xml file.
If you want to add additional ftp servers, or change the location of the credentials file, see Defining properties for protocol file servers using the ProtocolBridgeProperties.xml file.
Return codes
- 0
- Command completed successfully.
- 1
- Command ended unsuccessfully.
Use the fteStartAgent command to start your protocol bridge agent. For more information, see fteStartAgent (start an MFT agent). See also Starting an MFT agent on z/OS.