+

Search Tips | Advanced Search

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 we want to send files to and receive files from.

Important: On IBM MQ for Multiplatforms, 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, we 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 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 we 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
  • SYSTEM.FTE.HA.agent_name

These queues are internal system queues that we must not modify, delete, or read messages from unless we 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.

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 we 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 (parameter -bt), this default server is contained in the ProtocolBridgeProperties.xml file and its host name is used for the server name. With the -bt parameter, we need to specify the following parameters:

  • -bh
  • -btz
  • -bm
  • -bsl
  • -bfe
  • -bts

If we do not specify a default server, there are no entries in the ProtocolBridgeProperties.xml file; we 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 The agent.properties file. If you see unexpected behavior in the protocol bridge, review these protocol properties and ensure that we have set these properties correctly for the 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 MQ reason code for why. This information message can indicate that the coordination queue manager is currently unavailable or that we have defined the configuration incorrectly.


Special characters

Take care when we use parameter values that contain special characters so that you avoid the command shell interpreting the characters in a way we 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


fteCreateBridgeAgent

fteCreateBridgeAgent -agentName agent_name -agentQMgr agent_qmgr_name -bt protocol_file_server_type-bh server_host_name-btz server_time_zone-bm server_platform_type-bsl server_locale-bfe server_file_encoding -bts truststore_file -bp server_port_number-blw-blf server listing format-agentQMgrHost agent_qmgr_host_name-agentQMgrPort agent_qmgr_port-agentQMgrChannel agent_qmgr_channel-agentDesc agent_description-ac-authorityChecking-sservice_name-suuser_name-sppassword-sjoptions-sloptions-n-mquseriduserID-mqpasswordpassword-credentialsFilefilePath-useridusername-p configuration-options-f-x


Parameters

    -agentName (agent_name)
    Required. The name of the agent we 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 we 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 we 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.

    We 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

      OS400
      IBM i platformNote: We 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.

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

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

    We 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 we 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 platform

      WINDOWS
      Generic Windows platform

      OS400IFS
      Root file system on IBM i platformNotes:
      1. We 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.
      2. We can use Managed File Transfer to send and receive files on the root (/) file system only. Other file systems do not work.

    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
    IBM i displays the following type of listing:
     OS400IFS  -rwxrwsrwx  3 USERID  0       8192 Mar  7 08:33 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 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 we 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.

    -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. 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 we 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 we 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 we 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 we want to use configuration options different from your defaults. If we 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 we can use as input for the -btz parameter.

    -hcs
    Optional. Displays a list of supported character sets that we 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.

    -mquserid (userID)
    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. We must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, we 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, we must use the -f force parameter.

    -userid (username)
    Optional. The user ID used to associate the credential details. If we do not specify a user ID, the credential details will apply to all users. We 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.
    Specify this parameter adds a new option highlyAvailable to the agent.properties file.


Deprecated parameters

The following parameters have been deprecated and are not supported on IBM WebSphere MQ Version 7.5 or on WebSphere MQ File Transfer Edition Version 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
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
Note: The above does not apply to Managed File Transfer Agent redistributable. The scenario here is that the Managed File Transfer Agent is running on a Linux or Windows box but configured to communicate with an FTP server running IBM i. If you require the destination file to be in the native code page of IB, we must use the -dce code page parameter while submitting the transfer request. For example:
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 we used the -bt parameter (and the additional parameters that are required) there will be a default server name in the ProtocolBridgeProperties.xml file.

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.

Parent topic: MFT commands


Related reference


Related information

Last updated: 2020-10-04