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.
- maxActiveDestinationTransfers (global property)
- maxActiveDestinationTransfers (individual server property)
- failTransferWhenCapacityReached
See Changes to the sequence group, Changes to the limits group for changes these attributes make to the schema, and Scenarios and examples for limiting the number of file transfers to individual file servers for information on how the changes affect the working of the protocol bridge agent.
<schema targetNamespace="http://wmqfte.ibm.com/ProtocolBridgeProperties" elementFormDefault="qualified"
xmlns="https://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="https://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>
Changes to the sequence
group
sequence
group under ComplexType
is as follows, with the changes shown in bold
text:
<!--
A container for all protocol bridge server properties
-->
<complexType name="serverPropertiesType">
<sequence>
<element name="credentialsFile" type="tns:credentialsFileName" minOccurs="0" maxOccurs="1" />
<element name="credentialsKeyFile" type="tns:credentialsKeyFileName" minOccurs="0" maxOccurs="1" />
<element name="maxActiveDestinationTransfers"
type="tns:maxActiveDestinationTransfersValue" minOccurs="0"
maxOccurs="1" />
<element name="failTransferWhenCapacityReached"
type="tns:failTransferWhenCapacityReachedValue" 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 default value for maxActiveDestinationTransfers
-->
<complexType name="maxActiveDestinationTransfersValue">
<attribute name="value" type="positiveInteger" use="required" />
</complexType>
<!--
A container for a boolean value to decide to fail a transfer if max capacity is reached
-->
<complexType name="failTransferWhenCapacityReachedValue">
<attribute name="value" type="boolean" use="required" />
</complexType>
Changes to the limits
group
limits
group is as follows, with the changes shown in bold
text:
<!--
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"
/>
<attribute name="connectionTimeout" type="nonNegativeInteger"
use="optional" />
<attribute name="maxActiveDestinationTransfers" type="nonNegativeInteger"
use="optional" />
</attributeGroup>
Example XML file
<tns:serverProperties
xmlns:tns="http://wmqfte.ibm.com/ProtocolBridgeProperties"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://wmqfte.ibm.com/ProtocolBridgeProperties
ProtocolBridgeProperties.xsd">
<tns:maxActiveDestinationTransfers value="5" />
<tns:failTransferWhenCapacityReached value="true"/>
<tns:defaultServer name="guestServer" />
<tns:sftpServer name="guestServer" host="9.202.177.44" port="22"
platform="unix" fileEncoding="UTF-8" limitedWrite="false">
<tns:limits connectionTimeout="60"
maxActiveDestinationTransfers="2"/>
</tns:sftpServer>
<tns:sftpServer name="nixonServer" host="9.199.145.33" port="22"
platform="unix" fileEncoding="UTF-8" limitedWrite="false">
<tns:limits connectionTimeout="60"/>
</tns:sftpServer>
<tns:sftpServer name="mySFTPserver" host="Harrison.hursley.ibm.com"
port="22" platform="unix" fileEncoding="UTF-8 limitedWrite="false"
>
<tns:limits connectionTimeout="60" />
</tns:sftpServer>
</tns:serverProperties>
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 7.5 or later, the value of this property can contain environment variables. For more information, see 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 that you want to send files to or receive files from. port Optional. The port number of the protocol file server that you want to send files to or receive files from. platform Required. The platform of the protocol file server that you want 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.