Protocol bridge properties file format

The ProtocolBridgeProperties.xml file in the agent configuration directory defines properties for protocol file servers.

The ProtocolBridgeProperties.xml file must conform to the ProtocolBridgeProperties.xsd schema. The ProtocolBridgeProperties.xsd schema document is located in the MQ_INSTALLATION_PATH/mqft/samples/schema directory of the Managed File Transfer installation. A template file, ProtocolBridgeProperties.xml, is created by the fteCreateBridgeAgent command in the agent configuration directory.

The ProtocolBridgeProperties.xml file is periodically reloaded by the agent and any valid changes to the file will affect the behavior of the agent. The default reload interval is 30 seconds. This interval can be changed by specifying the agent property xmlConfigReloadInterval in the agent.properties file.

Schema

The following schema describes the ProtocolBridgeProperties.xml file.

Note: The maxReconnectRetry and reconnectWaitPeriod attributes are not supported on IBM® WebSphere MQ Version 7.5, or on WebSphere MQ File Transfer Edition Version 7.0.2, or later.

<schema targetNamespace="http://wmqfte.ibm.com/ProtocolBridgeProperties" elementFormDefault="qualified"
	xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://wmqfte.ibm.com/ProtocolBridgeProperties">

	<!--
		Example: ProtocolBridgeProperties.xml
		
		<?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="myserver" />
		    <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:sftpServer name="server1" host="myhost.hursley.ibm.com" platform="windows"
		         		    fileEncoding="UTF-8" limitedWrite="false">
		    	<limits maxListFileNames="10" />
		    </tns:sftpServer>
		</tns:serverProperties>
	-->

	<!-- Root element for the document -->
	<element name="serverProperties" type="tns:serverPropertiesType"></element>

	<!--
		A container for all protocol bridge server properties
	-->
	<complexType name="serverPropertiesType">
		<sequence>
			<element name="credentialsFile" type="tns:credentialsFileName" minOccurs="0" maxOccurs="1" />
			<element name="defaultServer" type="tns:serverName" minOccurs="0" maxOccurs="1" />
			<choice minOccurs="0" maxOccurs="unbounded">
				<element name="ftpServer" type="tns:ftpServerType" />
				<element name="sftpServer" type="tns:sftpServerType" />
				<element name="ftpsServer" type="tns:ftpsServerType" />
				<element name="ftpsfgServer" type="tns:ftpsfgServerType" />
				<element name="ftpssfgServer" type="tns:ftpssfgServerType" />
			</choice>
		</sequence>
	</complexType>

	<!--
		A container for a server name
	-->
	<complexType name="serverName">
		<attribute name="name" type="tns:serverNameType" use="required" />
	</complexType>
	
	<!--
		A container for a credentials file name
	-->
	<complexType name="credentialsFileName">
		<attribute name="path" type="string" use="required" />
	</complexType>
	
	<!--
		A container for all the information about an FTP server
	-->
	<complexType name="ftpServerType">
		<sequence>
			<element name="limits" type="tns:generalLimitsType" minOccurs="0" maxOccurs="1"  />
		</sequence>
		<attributeGroup ref="tns:ftpServerAttributes"/>
        <attribute name="passiveMode" type="boolean" use="optional" />		
	</complexType>
	
	<!--
		A container for all the information about an SFG FTP server
	-->
	<complexType name="ftpsfgServerType">
		<sequence>
			<element name="limits" type="tns:generalLimitsType" minOccurs="0" maxOccurs="1"  />
		</sequence>
		<attributeGroup ref="tns:ftpServerAttributes"/>
	</complexType>
	
	<!--
		A container for all the information about an SFTP server
	-->
	<complexType name="sftpServerType">
		<sequence>
			<element name="limits" type="tns:sftpLimitsType" minOccurs="0" maxOccurs="1"  />
		</sequence>
		<attributeGroup ref="tns:sftpServerAttributes"/>
	</complexType>
	
	<!--
		A container for all the information about a FTPS server
	-->
	<complexType name="ftpsServerType">
		<sequence>
			<element name="limits" type="tns:generalLimitsType" minOccurs="0" maxOccurs="1"  />
		</sequence>
		<attributeGroup ref="tns:ftpsServerAttributes"/>
	</complexType>

	<!--
		A container for all the information about a SFG FTPS server
	-->
	<complexType name="ftpssfgServerType">
		<sequence>
			<element name="limits" type="tns:generalLimitsType" minOccurs="0" maxOccurs="1"  />
		</sequence>
		<attributeGroup ref="tns:ftpsServerAttributes"/>
	</complexType>

	
	<!--
		Attributes common to all server types
	-->
	<attributeGroup name="generalServerAttributes">
		<attribute name="name" type="tns:serverNameType" use="required" />
		<attribute name="host" type="string" use="required" />
		<attribute name="port" type="nonNegativeInteger" use="optional" />
		<attribute name="platform" type="tns:platformType" use="required" />
		<attribute name="fileEncoding" type="string" use="required" />
		<attribute name="limitedWrite" type="boolean" use="optional" />
		<attribute name="controlEncoding" type="string" use="optional" />
	</attributeGroup>
	
	<!--
		Attributes common to ftp and ftps server types
	-->
	<attributeGroup name="ftpServerAttributes">
		<attributeGroup ref="tns:generalServerAttributes"/>
		<attribute name="timeZone" type="string" use="required" />
		<attribute name="locale" type="tns:localeType" use="required" />
		<attribute name="listFormat" type="tns:listFormatType" use="optional" />
		<attribute name="listFileRecentDateFormat" type="tns:dateFormatType" use="optional" />		
		<attribute name="listFileOldDateFormat" type="tns:dateFormatType" use="optional" />
		<attribute name="monthShortNames" type="tns:monthShortNamesType" use="optional" />
	</attributeGroup>
	
	<!--
		Attributes common to ftps server types
	-->
	<attributeGroup name="ftpsServerAttributes">
		<attributeGroup ref="tns:ftpServerAttributes"/>
		<attribute name="ftpsType" type="tns:ftpsTypeType" use="optional" />
		<attribute name="trustStore" type="string" use="required" />
		<attribute name="trustStoreType" type="string" use="optional" />
	    <attribute name="keyStore" type="string" use="optional" />
		<attribute name="keyStoreType" type="string" use="optional" />
		<attribute name="ccc" type="boolean" use="optional" />
		<attribute name="protFirst" type="boolean" use="optional" />
		<attribute name="auth" type="string" use="optional" />
		<attribute name="connectTimeout" type="nonNegativeInteger" use="optional"/>
	</attributeGroup>
	
	
	<!--
		A container for limit-type attributes for a server. Limit parameters
		are optional, and if not specified a system default will be used.
	-->
	<complexType name="generalLimitsType">
		<attributeGroup ref="tns:generalLimitAttributes"/>
	</complexType>
	
	<complexType name="sftpLimitsType">
		<attributeGroup ref="tns:generalLimitAttributes"/>
		<attribute name="connectionTimeout" type="nonNegativeInteger" use="optional" />
	</complexType>
	
	<!--
		Attributes for limits common to all server types
	-->
	<attributeGroup name="generalLimitAttributes">
		<attribute name="maxListFileNames" type="positiveInteger" use="optional" />
		<attribute name="maxListDirectoryLevels" type="nonNegativeInteger" use="optional" />
		<attribute name="maxReconnectRetry" type="nonNegativeInteger" use="optional" />
		<attribute name="reconnectWaitPeriod" type="nonNegativeInteger" use="optional" />
		<attribute name="maxSessions" type="positiveInteger" use="optional" />
		<attribute name="socketTimeout" type="nonNegativeInteger" use="optional" />
	</attributeGroup>
		
	<!--
		The type for matching valid server names. Server names must be at least 2 characters in length and 
		are limited to alphanumeric characters and the following characters: ".", "_", "/" and "%".
	-->
	<simpleType name="serverNameType">
        <restriction base="string">
            <pattern value="[0-9a-zA-Z\._/%]{2,}"/>
        </restriction>
    </simpleType>
    
	<!--
		The types of platform supported.
	-->
	<simpleType name="platformType">
		<restriction base="string">
		</restriction>
	</simpleType>
	
	<!--
		The type for matching a locale specification.
	-->
	<simpleType name="localeType">
        <restriction base="string">
            <pattern value="(..)[-_](..)"/>
        </restriction>
    </simpleType>

	<!--
		The types of list format supported (for FTP servers). 
	-->
	<simpleType name="listFormatType">
		<restriction base="string">
		</restriction>
	</simpleType>
	
	<!--
		Date format for FTP client directory listing on an FTP server. This is
		the format to be passed to methods setDefaultDateFormatStr and 
		setRecentDateFormatStr for Java class:
		org.apache.commons.net.ftp.FTPClientConfig
	-->
	<simpleType name="dateFormatType">
		<restriction base="string">
		</restriction>
	</simpleType>
	
	<!--
		A list of language-defined short month names can be specified. These are
		used for translating the directory listing received from the FTP server.
		The format is a string of three character month names separated by "|"
	-->
	<simpleType name="monthShortNamesType">
        <restriction base="string">
            <pattern value="(...\|){11}(...)"/>
        </restriction>
    </simpleType>
    
    <!--
		The enumerations of the allowed FTPS types: "implicit" & "explicit"
		If not specified the default is "explicit"
	-->
	<simpleType name="ftpsTypeType">
        <restriction base="string">
            <enumeration value="explicit"/>
            <enumeration value="implicit"/>
        </restriction>
    </simpleType>
    
    <!--
    	Attribute Group for SFTP Servers
    -->
    <attributeGroup name="sftpServerAttributes">
		<attributeGroup ref="tns:generalServerAttributes"/>
		<attribute name="cipherList" type="string" use="optional" />
	</attributeGroup>
</schema>

Understanding the ProtocolBridgeProperties.xml file

The elements and attributes that are used in the ProtocolBridgeProperties.xml file are described in the following list:

<serverProperties>

Root element of the XML document

<credentialsFile>

Path to the file containing credentials. For IBM WebSphere MQ Version 7.5 or later, the value of this property can contain environment variables. For more information, see The use of environment variables in MFT properties

<defaultServer>

The protocol file server that acts as the default server for file transfers

<ftpServer>

An FTP file server

<sftpServer>

An SFTP file server

<ftpsServer>

An FTPS file server

General server attributes that apply to all types of protocol file server:

Attribute	Description
name	Required. The name of the protocol file server. Protocol server names must be at least two characters in length, are not case-sensitive, and are limited to alphanumeric characters and the following characters: period (.) underscore (_) forward slash (/) percent sign (%)
host	Required. The host name or IP address of the protocol file server to send files to or receive files from.
port	Optional. The port number of the protocol file server to send files to or receive files from.
platform	Required. The platform of the protocol file server to send files to or receive files from. Specify either UNIX or WINDOWS.Set this property according to how you enter paths on your FTP, FTPS, or SFTP server. For example, if you are running an FTP server on Windows but when you log in to the server, you must enter UNIX-style paths (that is, with forward slashes), set this value to UNIX and not WINDOWS. Servers running on Windows often present a UNIX-style file system.
fileEncoding	Required. Defines the character encoding that is used by the file server. This property is used when you transfer files in text mode so that the correct encoding sequences are changed when the files are moved between platforms. For example, UTF-8.
limitedWrite	Optional. The default mode when writing to a file server 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 default is false.
controlEncoding	Optional. The control encoding value for control messages being sent to the protocol file server. This property affects the encoding of the file name that is used and must be compatible with the control encoding of the protocol file server. The default is UTF-8.

General attributes that apply to FTP and FTPS servers only:

Attribute	Description
timeZone	Required. The time zone of the protocol file server to send files to or receive files from. For example: America/New_York or Asia/Tokyo.
locale	Required. The language that is used on the protocol file server to send files to or receive files from. For example: en_US or ja_JP
listFormat	Optional. The listing format that defines the format of the file-listed information that is returned from the protocol file server. Use either Windows or UNIX. The default is UNIX.
listFileRecentDateFormat	Optional. The recent date format (less than a year) for FTP client directory listing on an FTP server. This attribute and the listFileOldDateFormat attribute allow you to redefine the expected date formats that are returned by the protocol file server. The default is as defined by the protocol file server.
listFileOldDateFormat	Optional. The old date format (more than a year) for FTP client directory listing on an FTP server. This attribute and the listFileRecentDateFormat attribute allow you to redefine the expected date formats that are returned by the protocol file server. The default is as defined by the protocol file server.
monthShortNames	Optional. A replacement list of month names that are used to decode date information returned from the protocol file server. This property consists of a list of 12 comma-separated names to override the default locale month values. The default is as defined by the protocol file server.

General attributes that apply to FTP servers only:

Attribute	Description
passiveMode	Optional. Controls whether the connection to the FTP server is passive or active. If you set the value of this property to false, the connection is active. If you set the value to true, the connection is passive. The default is false.

General attributes that apply to FTPS servers only:

Attribute	Description
ftpsType	Optional. Specifies whether the explicit or implicit form of the FTPS protocol is used. The default is explicit.
trustStore	Required. The location of the truststore that is used to determine whether the certificate presented by the FTPS server is trusted.
trustStoreType	Optional. The format of the truststore file. The default is JKS.
keyStore	Optional. The location of the keystore that is used to provide certificate information if challenged by the FTPS server. The default is for the protocol bridge to not be able to connect to FTPS servers that are configured to require the authentication of clients.
keyStoreType	Optional. The format of the keystore file. The default is JKS.
ccc	Optional. Selects whether a clear (unencrypted) command channel is used when authentication has completed. The default value is false, which means that the command channel remains encrypted for the entire duration of the FTPS session. This attribute is applicable only when the ftpsType is set to explicit.
protFirst	Optional. Specifies whether the USER/PASS commands are issued to the FTPS server before or after the PBSZ/PROT commands. The default value is false, which means USER/PASS commands are sent first followed by PBSZ/PROT commands. This attribute is applicable only when the ftpsType is set to explicit.
auth	Optional. Specifies the protocol that is specified as part of the AUTH command. A specified protocol will be tried first, then the default is to try TLS, SSL, TLS-C, or TLS-P until the FTPS server does not reject with a 504 reply code. This attribute is applicable only when the ftpsType is set to explicit.

<limits>

Container element for attributes that are common to all types of server and for attributes that are specific to a type of server:

General limit attributes that apply to all types of protocol file server:

Attribute	Description
maxListFileNames	Optional. The maximum number of names that are collected when scanning a directory on the protocol file server for file names. The default is 999999999.
maxListDirectoryLevels	Optional. The maximum number of directory levels on the protocol server to recursively scan for file names. The default is 1000.
maxReconnectRetry (This attribute is now deprecated.)	Deprecated. This attribute is not supported on IBM WebSphere MQ Version 7.5, or on WebSphere MQ File Transfer Edition Version 7.0.2, or later. Optional. The maximum number of times a protocol server tries to reconnect before the protocol bridge agent stops trying. The default is 2.
reconnectWaitPeriod (This attribute is now deprecated.)	Deprecated. This attribute is not supported on IBM WebSphere MQ Version 7.5, or on WebSphere MQ File Transfer Edition Version 7.0.2 or later. Optional. The time period, in seconds, to wait to before attempting to reconnect. The default is 10 seconds.
maxSessions	Optional. The maximum number of sessions for the protocol server. This number must be greater than or equal to the sum of the maximum number of source and destination transfers for the protocol bridge agent. The default is the sum of the values for the agent properties maxSourceTransfers, maxDestinationTransfers, and maxCommandHandlerThreads, plus 1. If these three properties are using their default values of 25, 25, and 5, the maxSessions default is then 56.
socketTimeout	Optional. The socket timeout in seconds. The value of this attribute is used during file streaming. The default is 30 seconds.

Limit attribute that applies to SFTP servers only:

Attribute	Description
connectionTimeout	Optional. The time, in seconds, to wait for a response from the protocol file server to a connection request. A timeout indicates that the protocol file server is not available. The default value is 30 seconds.
cipherList	Optional. Specifies a comma-separated list of ciphers that are used to communicate between the protocol bridge agent and the SFTP server. The ciphers are called in the order that they are specified in this list. The cipher must be available on the server and the client before it can be used. The ciphers that the protocol bridge agent supports are as follows: blowfish-cbc 3des-cbc aes128-cbc aes192-cbc aes256-cbc aes128-ctr aes192-ctr aes256-ctr 3des-ctr arcfour arcfour128 arcfour256 By default, the list of ciphers used by protocol bridge agents is aes128-cbc,aes192-cbc,aes256-cbc.