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

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, you 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; 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 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 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 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 -agentNameagent_name -agentQMgragent_qmgr_name -btprotocol_file_server_type
  • -bhserver_host_name
  • -btzserver_time_zone
  • -bmserver_platform_type
  • -bslserver_locale
  • -bfeserver_file_encoding
  • -btstruststore_file -bpserver_port_number
  • -blw
  • -blfserver listing format
  • -agentQMgrHostagent_qmgr_host_name
  • -agentQMgrPortagent_qmgr_port
  • -agentQMgrChannelagent_qmgr_channel
  • -agentDescagent_description
  • -ac-authorityChecking
  • -sservice_name
  • -suuser_name
  • -sppassword
  • -sjoptions
  • -sloptions
  • -n
  • -mquseriduserID
  • -mqpasswordpassword
  • -credentialsFilefilePath
  • -useridusername
  • -pconfiguration-options
  • -f


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

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

      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 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 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 we do not specify -p, the configuration options defined in the installation.properties file are used. See MFT configuration options on Multiplatforms 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. 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 (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, you 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. You must also specify the -credentialsFile parameter.
      -? or -h
      Optional. Displays command syntax.


    Deprecated parameters

    The following parameters have been deprecated and are not supported on IBM MQ V7.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.


    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
    Note: The above does not apply to Managed File Transfer Agent redistributable.


    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.

    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. See also Starting an MFT agent on z/OS.