Defining properties for protocol file servers using the ProtocolBridgeProperties.xml file

Define the properties of one or more protocol file servers to transfer files to and from using the ProtocolBridgeProperties.xml file, which is provided by Managed File Transfer in the agent configuration directory.

The fteCreateBridgeAgent command creates the ProtocolBridgeProperties.xml file in the agent configuration directory MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name. The command also creates an entry in the file for the default protocol file server, if a default was specified when the command was run.

The message BFGCL0392I gives the location of the ProtocolBridgeProperties.xml file.

<?xml version="1.0" encoding="IBM-1047"?>
<!--
This ProtocolBridgeProperties.xml file determines the protocol servers that will be accessed by the
MQMFT protocol bridge agent.

Each protocol server is defined using either a <tns:ftpServer>, <tns:ftpsServer>, or <tns:sftpServer>
element - depending on the protocol used to communicate with the server.  When the protocol
bridge agent participates in a managed file transfer it will determine which server to used based on
the prefix (if any) present on the file path.  For example a file path of 'server1:/home/user/file.txt' would
be interpreted as a request to transfer /home/user/file.txt using 'server1'.  The server name is compared
to the 'name' attribute of each <tns:ftpServer>, <tns:ftpsServer> or <tns:sftpServer> element in this
XML document and the first match is used to determine which protocol server the protocol bridge
agent will connect to.  If no match is found then the managed file transfer operation will fail.

If a file path is not prefixed with a server name, for example '/home/user/file.txt' then this XML
document can specify a default server to use for the managed file transfer.  To specify a
default server use the <tns:defaultServer> element as the first element inside the <tns:serverProperties>
element.  The default server will be used whenever the protocol bridge agent participates in
a managed file transfer for file names which do not specify a prefix.

An optional <tns:limits> element can be specified within each server definition. This element contains 
attributes that govern the amount of resources used by each defined server.

An optional <tns:credentialsFile> element can be specified within each serverProperties definition. This
element contains a path to a file containing credentials to be used when connecting to defined servers.

An example ProtocolBridgeProperties.xml file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<tns:serverProperties xmlns:tns="http://wmqfte.ibm.com/ProtocolBridgeProperties"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://wmqfte.ibm.com/ProtocolBridgeProperties  ProtocolBridgeProperties.xsd">

	<tns:credentialsFile path="$HOME/ProtocolBridgeCredentials.xml" />

	<tns:defaultServer name="myFTPserver" />

	<tns:ftpServer name="myFTPserver" host="windows.hursley.ibm.com" port="1234" platform="windows"
		timeZone="Europe/London" locale="en_GB" fileEncoding="UTF-8"
		listFormat="unix" limitedWrite="false">

		<tns:limits maxListFileNames="100" maxListDirectoryLevels="999999999"
			maxReconnectRetry="2"  reconnectWaitPeriod="10"
			maxSessions="60" socketTimeout="30" />

	</tns:ftpServer>

	<tns:ftpsServer name="myFTPSserver" host="unix.hursley.ibm.com" platform="unix"
		timeZone="Europe/London" locale="en_GB" fileEncoding="UTF8"
		listFormat="unix" limitedWrite="false" ftpsType="explicit"
		trustStore="C:\FTE\keystores\myFTPSserver\FTPSKeyStore.jks" trustStorePassword="password">

		<tns:limits maxReconnectRetry="10" connectionTimeout="10"/>

	</tns:ftpsServer>

	<tns:sftpServer name="mySFTPserver" host="windows.hursley.ibm.com" platform="windows"
		timeZone="Europe/London" locale="en_GB" fileEncoding="UTF-8"
		limitedWrite="false">

		<tns:limits connectionTimeout="60"/>

	</tns:sftpServer>

</tns:serverProperties>

This example shows the outermost <tns:serverProperties> element which must exist for the document to
be valid, an optional <tns:defaultServer> element, as well as definitions for an FTP, FTPS and SFTP server.

The attributes of the <tns:ftpServer>, <tns:ftpsServer> and <tns:sftpServer> elements determine the
characteristics of the connection established to the server.  These attributes correspond to the command
line parameters for the 'fteCreateBridgeAgent' command.

The following attributes are valid for all of the <tns:ftpServer>, <tns:ftpsServer> and <tns:sftpServer>
elements: name, host, port, platform, fileEncoding, limitedWrite and controlEncoding.

The following attributes are valid for the <tns:ftpServer> and <tns:ftpsServer> elements: timezone, locale,
listFormat, listFileRecentDateFormat, listFileOldDateFormat, and monthShortNames.

The following attributes are valid for the <tns:ftpServer> element only: passiveMode

The following attributes are valid for the <tns:ftpsServer> element only: ftpsType, trustStore, trustStorePassword,
trustStoreType, keyStore, keyStorePassword, keyStoreType, ccc, protFirst, auth, and connectTimeout.

The following attributes are valid for the <tns:limits> element within all of the <tns:ftpServer>, <tns:ftpsServer>
and <tns:sftpServer> elements: maxListFileNames, maxListDirectoryLevels, maxReconnectRetry, reconnectWaitPeriod,
maxSessions and socketTimeout

-->
<tns:serverProperties xmlns:tns="http://wmqfte.ibm.com/ProtocolBridgeProperties"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://wmqfte.ibm.com/ProtocolBridgeProperties ProtocolBridgeProperties.xsd">

    <!-- By default the location of the credentials file is in the home directory of the user that started the -->
    <!-- protocol bridge agent. If you wish to specify a different location use the credentialsFile element to -->
    <!-- do this. For example:                                                                                 -->
    <!-- <tns:credentialsFile path="/test/ProtocolBridgeCredentials.xml"/>                                   -->

    <tns:defaultServer name="WINMVSCA.HURSLEY.IBM.COM" />
    <tns:ftpServer name="WINMVSCA.HURSLEY.IBM.COM" host="WINMVSCA.HURSLEY.IBM.COM" platform="UNIX" 
                timeZone="Europe/London" locale="en-GB" fileEncoding="US-ASCII"
                listFormat="unix" limitedWrite="false"  />

    <!-- Define servers here -->
</tns:serverProperties>

The command can produce the following message:BFGCL0532I:

For this agent to function an additional credentials file must be created manually. 
By default this file is called ProtocolBridgeCredentials.xml and is located in the home 
directory of the user who starts the agent. For example,if this user started the agent 
the location would be: $HOME/ProtocolBridgeCredentials.xml

If we use a credentials file:

See the following text for further information on how to create one.
The credentials file must be in a directory with restricted permissions. For example, there must be no read access for other users.
Specify the location of the directory for the credentials file in the $HOME environment variable for the user ID of the started agent, or edit the ProtocolBridgeProperties.xml file and specify the location in:
```
<tns:credentialsFile path="/test/ProtocolBridgeCredentials.xml"/>
```

If you want to add further non-default protocol servers, edit this file to define their properties. This example adds an additional FTP server. Note: The protocol bridge agent does not support file locking. This is because Managed File Transfer does not support the file locking mechanism on a file server.

Procedure

Define a protocol file server by inserting the following lines into the file as a child element of <tns:serverProperties>:

<tns:ftpServer name="myserver" host="myhost.hursley.ibm.com" port="1234" 
   platform="windows"
		         		   timeZone="Europe/London" locale="en-GB" fileEncoding="UTF-8"
		        		   listFormat="unix" limitedWrite="false" >
<tns:limits maxListFileNames="10" maxListDirectoryLevels="500"/>

Then change the value of the attributes:
- name is the name of your protocol file server
- host is the host name or IP address of the protocol file server
- port is the port number of the protocol file server
- platform is the platform that the protocol file server runs on
- timeZone is the time zone that the protocol file server runs in
- locale is the language used on the protocol file server
- fileEncoding is the character encoding of the protocol file server
- listFormat is the file listing format returned from the protocol file server
- limitedWrite determines whether to follow the default mode when writing to a file server, which is to create a temporary file and then rename that file when the transfer has completed. For a file server that is configured as write only, the file is created directly with its final name. The value of this property can be true or false. The limitedWrite attribute and the doNotUseTempOutputFile agent property are used together in the case of protocol bridge agents. If you want to use temporary files, then you must not set the value of doNotUseTempOutputFile, and you must set the value of limitedWrite to false. Any other combination of settings means that temporary files will not be used.
- maxListFileNames is the maximum number of names collected when scanning a directory on the protocol file server for file names.
- maxListDirectoryLevels is the maximum number of directory levels to recurse when scanning a directory on the protocol file server for file names.
For more details about these attributes, including whether they are required or optional and their default values, see Protocol bridge properties file format.