The MFT agent.properties file

Each Managed File Transfer Agent has its own properties file, agent.properties, that must contain the information that an agent uses to connect to its queue manager. The agent.properties file can also contain properties that alter the behavior of the agent.

The agent.properties file is created by the installer or by the fteCreateAgent, fteCreateBridgeAgent or fteCreateCDAgent command. We can use any of these commands with the -f flag to change the basic agent queue manager properties and those advanced agent properties that are associated with the type of agent that you are creating. To change or add advanced agent properties, you must edit the file in a text editor.

The agent.properties file for an agent is in your MQ_DATA_PATH/mqft/config/coordination_qmgr_name/agents/agent_name directory.

On z/OS®, the agent.properties file location is $BFG_CONFIG variable/mqft/config/coordination_qmgr_name/agents/agent_name.

If you change the agent.properties file you must restart the agent to pick up the changes.

For IBM® WebSphere MQ Version 7.5, or later, we can use environment variables in some Managed File Transfer properties that represent file or directory locations. This allows you to use the locations of files or directories when running parts of the product to vary depending on environment changes, such as which user is running the process. For more information, see The use of environment variables in MFT properties.


Basic agent properties

Each agent.properties file contains the following basic properties.
Table 1. Basic agent properties
Property name Description Default value
agentName The name of the agent. The name of the agent must conform to the IBM MQ object naming conventions. For more information, see MFT object naming conventions. No default
agentDesc The description of the agent - if you choose to create a description. No default
agentQMgr The agent queue manager name. No default
agentQMgrHost The host name or IP address of the agent queue manager. No default
agentQMgrPort The port number that is used for client connections to the agent queue manager. 1414
agentQMgrChannel The SVRCONN channel name that is used to connect to the agent queue manager. SYSTEM.DEF.SVRCONN
agentType The type of agent:

  • Standard non-bridge agent (STANDARD)
  • Protocol bridge agent (BRIDGE)
  • Connect:Direct® bridge agent (CD_BRIDGE)
  • Embedded agent as used by IBM Integration Bus (EMBEDDED)
  • Sterling File Gateway embedded agent (SFG)
STANDARD

If we do not specify a value for the agentQMgrHost property, bindings mode is used by default.

If you specify a value for the agentQMgrHost property but do not specify values for the agentQMgrPort and agentQMgrChannel properties, a port number of 1414 and a channel of SYSTEM.DEF.SVRCONN are used by default.


Advanced agent properties

Managed File Transfer also provides more advanced agent properties that help you configure agents. If you want to use any of the following properties, manually edit the agent.properties file to add the required advanced properties. When you specify file paths on Windows, ensure the separator character backslash (\) is entered as double backslashes (\\), that is, escaped backslash (\). Alternatively, we can use a single forward slash (/) character as a separator. For more information about character escaping in Java properties files, see the Oracle documentation Javadoc for the Properties class.

Table 2. Advanced agent properties
Property name Description Default value
Agent size properties:
agentCheckpointInterval

The interval in complete frames of data between which a checkpoint is taken for recovery purposes. This is an advanced property and for most Managed File Transfer configurations it is not necessary to modify its value.

If there is a problem which causes the transfer to go into recovery, the transfer can recover only to a checkpoint boundary. Hence, the larger this value (with large agentChunkSize, agentWindowSize, and agentFrameSize values), the longer the time that is needed for the agent to recover transfers. For reliable Managed File Transfer networks where transfers rarely enter a recovery state, it may be beneficial to increase this value to increase overall performance.

1
agentChunkSize

The size of each transfer chunk for the transport of file data. Hence, denotes the maximum size of the IBM MQ messages that are transferred between the source and the destination agents. This is an advanced property and for most Managed File Transfer configurations it is not necessary to modify its value.

This value is negotiated between the source agent and the destination agent, and the larger of the two values is used. If you want to change the value of this property, change the value at both the source agent and at the destination agent.

agentChunkSize is an integer value. For example: agentChunkSize = 10240 sets the chunk size to 10 KB.

262144-byte (which is equivalent to 256 KB)
agentFrameSize

The number of windows for the transfer frame. This is an advanced property and for most Managed File Transfer configurations it is not necessary to modify its value.

For networks that have high latency, increasing this value may improve overall performance as it causes the agent to have more message chunks active concurrently.

The value of this property, multiplied by agentWindowSize, multiplied by agentChunkSize, denotes the upper limit of the memory consumption of the agent for each transfer. For example, 262144-byte chunks x 10 x 5 = 12.5 MB for each transfer.

Note: If the size of the files that is transferred in a single transfer is less than 12.5 MB increasing this property has no effect on the performance of the transfer.

5
agentWindowSize

The number of chunks for each window. This is an advanced property and for most Managed File Transfer configurations it is not necessary to modify its value.

For networks that have high latency, increasing this value may improve overall performance. This is because it causes the agent to have more message chunks active concurrently and reduces the frequency that acknowledgment messages are sent back to the source agent.

The value of this property, multiplied by agentFrameSize, multiplied by agentChunkSize, denotes the upper limit of the memory consumption of the agent for each transfer, and denotes the upper limit of the IBM MQ message data on the command queue of the destination agent. For example, 262144-byte chunks x 10 x 5 = an upper limit of 12.5 MB, for each transfer.

Note: If the size of the files that is transferred in a single transfer is less than 12.5 MB increasing the value of this property has no effect on the performance of the transfer.

10
Code page properties:
agentCcsid The code page the agent connects to its agent queue manager with. If you specify a value for agentCcsid, you must also specify a value for agentCcsidName. For information on how to view the known code pages for the JVM, see the -hsc parameter in the fteCreateBridgeAgent command. 1208
agentCcsidName The Java representation of the agentCcsid. If you specify a value for agentCcsidName, you must also specify a value for agentCcsid. UTF8
Command properties:
maxCommandHandlerThreads Controls the number of threads available for the initial parsing and processing of transfer command messages. When active, the threads require a connection to the queue manager but the threads release the connection when idle. 5
maxCommandOutput The maximum number of bytes stored for command output. This property applies to commands specified for a managed call and preSource, postSource, preDestination, and postDestination commands for a managed transfer. This limits the length of command output that is written to the transfer log on the SYSTEM.FTE topic. 10240
maxCommandRetries The maximum number of retries for a command that the agent permits. This property applies to commands specified for a managed call and the preSource, postSource, preDestination, and postDestination commands for a managed transfer. 9
maxCommandWait The maximum wait, in seconds, between retries that the agent permits. This property applies to commands specified for a managed call and the preSource, postSource, preDestination, and postDestination commands for a managed transfer. 60
immediateShutdownTimeout For an immediate shutdown of an agent, we can use this property to specify the maximum amount of time in seconds an agent waits for its transfers to complete before forcing a shutdown. Note: Do not change the value of this property to less than the default of 10 seconds. An immediate shutdown of an agent requires sufficient time to end any external processes. If the value of this property is too low, processes might be left running.

If the value 0 is specified for this property, the agent waits for all outstanding transfers to stop. If an invalid value is specified for this property, the default value is used.

10
Connection properties:
javaLibraryPath When connecting to a queue manager in bindings mode, Managed File Transfer must have access to the IBM MQ Java bindings libraries. By default Managed File Transfer looks for the bindings libraries in the default location that is defined by IBM MQ. If the bindings libraries are in a different location, use this property to specify the location of the bindings libraries. None
Connect:Direct bridge properties:
cdNode Required property if you want to use the Connect:Direct bridge.

The name of the Connect:Direct node to use to transfer messages from the Connect:Direct bridge agent to destination Connect:Direct nodes. This node is part of the Connect:Direct bridge, not the remote node that is the source or destination of the transfer. For more information, see The Connect:Direct bridge.

No default
cdNodeHost The host name or IP address of the Connect:Direct node to use to transfer files from the Connect:Direct bridge agent to destination nodes (the Connect:Direct bridge node).

In most cases, the Connect:Direct bridge node is on the same system as the Connect:Direct bridge agent. In these cases, the default value of this property, which is the IP address of the local system, is correct. If your system has multiple IP addresses, or your Connect:Direct bridge node is on a different system to your Connect:Direct bridge agent and their systems share a file system, use this property to specify the correct host name for the Connect:Direct bridge node.

If we have not set the cdNode property, this property is ignored.

The host name or IP address of the local system
cdNodePort The port number of the Connect:Direct bridge node that client applications use to communicate with the node. In Connect:Direct product documentation, this port is referred to as the API port.

If we have not set the cdNode property, this property is ignored.

1363
cdTmpDir The location to store files temporarily on the system where the Connect:Direct bridge agent is running before they are transferred to the destination Connect:Direct node.

This property specifies the full path of the directory where files are temporarily stored. For example, if cdTmpDir is set to /tmp then the files are temporarily placed in the /tmp directory.

The Connect:Direct bridge agent and the Connect:Direct bridge node must be able to access the directory specified by this parameter using the same path name. Consider this when planning the installation of your Connect:Direct bridge. If possible, create the agent on the system where the Connect:Direct node that is part of the Connect:Direct bridge is located. If your agent and node are on separate systems, the directory must be on a shared file system and be accessible from both systems using the same path name. For more information about the supported configurations, see The Connect:Direct bridge.

If we have not set the cdNode property, this property is ignored.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

value_of_java.io.tmpdir
/cdbridge-agentName
On Windows,
value_of_java.io.tmpdir
\cdbridge-agentName
cdTrace Whether the agent traces data that is sent between the Connect:Direct bridge agent and its Connect:Direct node. The value of this property can be true or false. false
cdMaxConnectionRetries The maximum number of Connect:Direct connection attempts, for a file transfer where a successful connection has not yet been made, before the transfer fails. -1 (an infinite number of attempts)
cdMaxPartialWorkConnectionRetries The maximum number of Connect:Direct connection attempts, for a file transfer where a previous connection attempt has been successful and transfer work has completed, before the transfer fails. -1 (an infinite number of attempts)
cdMaxWaitForProcessEndStats The maximum time in milliseconds to wait for Connect:Direct process completion information to become available within the Connect:Direct node statistics information, after the process has ended, before the file transfer is judged to have failed. Typically the information is available immediately, but under certain failure conditions the information is not published. In these conditions the file transfer fails after waiting for the amount of time that is specified by this property. 60000
cdAppName The application name that the Connect:Direct bridge agent uses to connect to the Connect:Direct node that is part of the bridge. Managed File Transfer current version, where current version is the version number of the product.
cdNodeLocalPortRange The range of local ports to use for socket connections between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge. The format of this value is a comma-separated list of values or ranges.

By default, the operating system selects the local port numbers.

None
cdNodeProtocol The protocol that the Connect:Direct bridge agent uses to connect to the Connect:Direct node that is part of the bridge. The following values are valid:

  • TCPIP
  • SSL
  • TLS
TCPIP
cdNodeKeystore The path to the keystore that is used for secure communications between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge.

If we have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

None
cdNodeKeystoreType The file format of the keystore that is specified by the cdNodeKeystore property. The following values are valid: jks and pkcs12.

If we have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

jks
cdNodeKeystoreCredentialsFile The path to the file that contains the cdNodeKeystore credentials.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

For details on creating the Authentication Credentials File see Creating an MFT credentials file

See Configure MQMFTCredentials.xml for information on the location and permissions of this file.

Further details on creating the Authentication Credentials File are in MFT and IBM MQ connection authentication

cdNodeTruststore The path to the truststore that is used for secure communications between the Connect:Direct bridge agent and the Connect:Direct node that is part of the bridge.

If we have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

None
cdNodeTruststoreType The file format of the truststore that is specified by the cdNodeTruststore property. The following values are valid: jks and pkcs12.

If we have not set the cdNodeProtocol property to SSL or TLS, this property is ignored.

jks
cdNodeTruststoreCredentialsFile The path to the file that contains the cdNodeTruststore credentials.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

See Creating an MFT credentials file and Configure MQMFTCredentials.xml

Further details on creating the Authentication Credentials File are also in Creating an MFT credentials file

Further details on creating the Authentication Credentials File are in MFT and IBM MQ connection authentication

logCDProcess The level of Connect:Direct process logging that is recorded in the agent event log in the output0.log file. The values that this property can have are None or Failures or All. None
File to message and message to file agent properties:
deleteTmpFileAfterRenameFailure Set this property to a value of false ensures that temporary files are not deleted from the destination if the rename operation fails. In this case, the transferred data remains at the destination in a temporary (.part) file. We can manually rename this file later. By default this property has the value of true. This property applies to both message-to-file and file-to-file transfers. true
enableQueueInputOutput By default, the agent cannot read data from a source queue or write data to a destination queue as part of a transfer. Setting this value to true enables the agent to perform file to message, and message to file transfers. The value of this property can be true or false. false
enableSystemQueueInputOutput Specifies whether the agent can read from or write to IBM MQ system queues. System queues are prefixed with the qualifier SYSTEM.Note: System queues are used by IBM MQ, Managed File Transfer, and other applications to transmit important information. Changing this property enables the agent to access these queues. If you enable this property, use user sandboxing to limit the queues that the agent can access. false
enableClusterQueueInputOutput Specifies whether the agent can read from or write to IBM MQ clustered queues. Note: You must specify the enableClusterQueueInputOutput agent property in addition to the enableQueueInputOutput property. false
maxDelimiterMatchLength The maximum number of characters that can be matched by the Java regular expression that is used to split a text file into multiple messages as part of a file-to-message transfer. 5
maxInputOutputMessageLength The maximum length, in bytes, of a message that is read from a source queue or written to a destination queue by an agent. The maxInputOutputMessageLength property of the source agent in a transfer determines how many bytes can be read from a message on the source queue. The maxInputOutputMessageLength property of the destination agent in a transfer determines how many bytes can be written to a message on the destination queue. If the length of the message exceeds the value of this property the transfer fails with an error. This property does not affect the Managed File Transfer internal queues. For information about changing this property, see Guidance for setting MQ attributes and MFT properties associated with message size. 1048576
monitorGroupRetryLimit The maximum number of times that a monitor triggers a message-to-file transfer again if the message group still exists on the queue. The number of times that the message-to-file transfer triggers is determined from the MQMD backout count of the first message in the group.

If the agent is restarted the monitor triggers a transfer again even if the number of times the transfer triggers exceeds the value of monitorGroupRetryLimit. If this behavior causes the number of times that the transfer triggers to exceed the value of monitorGroupRetryLimit, the agent writes an error to its event log.

If the value -1 is specified for this property, the monitor triggers the transfer again an unlimited number of times until the trigger condition is not satisfied.

10
General agent properties:
agentStatusPublishRateLimit The maximum rate in seconds that the agent republishes its status because of a change in file transfer status.

If you set this property to too small a value, the performance of the IBM MQ network might be negatively affected.

30
agentStatusPublishRateMin The minimum rate in seconds that the agent publishes its status. This value must be greater than or equal to the value of the agentStatusPublishRateLimit property. 300
enableMemoryAllocationChecking

Determines whether the Managed File Transfer Agent checks that there is sufficient memory available to run a transfer before a transfer is accepted. The check is made on both the source and destination agents. If there is insufficient memory available, the transfer is rejected.

When calculating the memory required for a transfer, the maximum memory that is required by the transfer is used. Therefore, the value might be greater than the actual memory that is used by the transfer. For this reason, the number of concurrent transfers that can run might be reduced if the enableMemoryAllocationChecking property is set to true. You are recommended to set the property to true only if you are experiencing problems with Managed File Transfer failing with out-of-memory errors. The transfers that are likely to consume large amounts of memory are file-to-message and message-to-file transfers where the sizes of the messages are large.

false
enableDetailedReplyMessages Set this property to true enables managed transfer request replies to contain detailed information about the transferred files. The detailed information and format is the same as that published to the transfer log in the progress messages, that is, the <transferSet> element. For more information, see File transfer log message formats.

The detailed reply information is included only when the managed transfer request specifies that detailed reply information is required. To specify this requirement, set the detailed attribute of the <reply> element of the managedTransfer XML request message sent to the source agent. For more information, see File transfer request message format.

Multiple reply messages can be generated for each transfer request. This number is equal to the number of transfer log progress messages for the transfer plus 1 (where the first reply message is a simple ACK reply). Detailed information is included in all messages, except for the ACK reply messages, but the overall transfer result is included only in the last detailed reply message.

true
enableUserMetadataOptions Determines whether we can use known keys for user-defined metadata in new transfer requests to provide more transfer options. These known keys always start with the following prefix com.ibm.wmqfte.. As a consequence when the enableUserMetadataOptions property is set true, keys that use this prefix are not supported for user-defined use. When the enableUserMetadataOptions property is set to true, the keys that are supported currently are as follows:

  • com.ibm.wmqfte.insertRecordLineSeparator
  • com.ibm.wmqfte.newRecordOnLineSeparator
  • com.ibm.wmqfte.convertLineSeparators
For information about what these keys mean, see fteCreateTransfer: start a new file transfer.

The value of this property can be true or false.

false
failTransferOnFirstFailure Allows an agent to be configured to fail a managed transfer as soon as a transfer item within that managed transfer fails.

To enable this feature, APAR IT03450 must be applied for both the source agent and the destination agent, and the failTransferOnFirstFailure property must be set to true in the source agent's agent.properties file. Setting the property to true true on the destination agent is optional.

When the failTransferOnFirstFailure property is set to true, the agent starts processing managed transfer requests as normal. However, as soon as a transfer item fails, then the managed transfer is marked as failed and no further transfer items are processed. Transfer items that were successfully processed before the managed transfer failed are handled in the following way:

  • The source disposition for those transfer items is honored. For example, if the source disposition for the transfer item was set to delete, then the source file is deleted.
  • The destination files that were written remain on the destination file system and are not deleted.

If the failTransferOnFirstFailure property is not set to true and a managed file transfer contains multiple files and one of these files fails to transfer, for example because the destination file already exists and the overwrite property is set to error, the source agent continues and attempts to transfer any remaining files in the request.

false
itemsPerProgressMessage

The number of files that are transferred before an agent publishes its next progress log message. Use this property to control the rate that progress log messages are published to the coordination queue manager during a transfer.

The maximum value this property can be set to is 1000.

Note: Progress messages include information about every file that is transferred since the last progress message was published. Increasing this value increases the size of the progress messages, which might affect performance.
50
maxInlineFileSize

For single file-to-file, or file-to-message transfers, the maximum file size (in bytes) that can be automatically included in the initial transfer request message.

We can use this property to improve the speed of your transfers, but if you set the file size to too large a value, this might degrade performance. A suggested initial size for this property is 100 KB but you are recommended to thoroughly test different values until you find the best file size for your system.

0
Input/output properties:
doNotUseTempOutputFile

By default, the agent writes to a temporary file at the destination and renames this temporary file to the required file name after the file transfer is complete. Setting this value to true causes the agent to write directly to the final destination file.

On z/OS systems, this behavior does not apply to sequential data sets, but does apply to PDS data set members.

The value of this property for a transfer is defined by the destination agent.

false
enableMandatoryLocking When accessing normal files, Managed File Transfer takes a shared lock for reading and an exclusive lock for writing.

On Windows file locking is advisory only. When this property is set to true, Managed File Transfer enforces file locking. On Windows this means that if another application has a file open, monitoring of that file does not trigger until the file is closed. Managed File Transfer transfers involving that file fail.

On UNIX type platforms, file locking is fulfilled across processes. For UNIX type platforms, setting this property has no effect.

This property applies to normal Managed File Transfer agents only. Managed File Transfer does not support the file locking mechanism on a file server. This property therefore does not work for a protocol bridge agent because protocol bridge agent does not lock a file on a file server when transferring a file.

The value of this property can be true or false.

false
ioIdleThreadTimeout Time in milliseconds for a file system input/output thread to remain idle before the thread shuts down. 10000
ioQueueDepth The maximum number of input/output requests to queue up. 10
ioThreadPoolSize Maximum number of file system input/output threads available. Typically each transfer uses its own file system input/output thread, but if the number of concurrent transfers exceeds this limit, the file system input/output threads are shared between transfers.

If you think you are likely to regularly have more concurrent transfers in progress than the ioThreadPoolSize value, you might see an improvement by increasing this value, so that each transfer has its own file system input/output thread.

10
textReplacementCharacterSequence For text mode transfer, if any of the data bytes cannot be converted from the source code page to the destination code page, the default behavior is for the file transfer to fail.

Set this property to allow the transfer to complete successfully by inserting the specified character value. This property value is a single character. Typically, a question mark (?) is used for any unmappable characters. For example, use this format textReplacementCharacterSequence=? where the question mark (?) is the replacement character. We cannot use a white space character as a replacement character.

None
Multi-channel support:
agentMultipleChannelsEnabled Set this property to true enables a Managed File TransferManaged File Transfer Agent to send transfer data messages across multiple IBM MQ channels. In some scenarios, setting this property might improve performance. However, only enable multi-channel support only if there is a demonstrable performance benefit. Only messages that are put to the SYSTEM.FTE.DATA.destinationAgentName queue are sent across multiple channels. The behavior for all other messages remains unchanged. When you set this property to true, you must also complete the IBM MQ configuration steps in one of the following topics to enable multi-channel support:

Additionally, you must also complete the standard IBM MQ configuration steps that are required for a Managed File Transfer agent, which are detailed in Configure MFT for first use.

The value of this property can be true or false.

false
agentMessageBatchSize When configured with multiple channels, a source agent sends data messages for a transfer across each channel on a round-robin basis. This property controls the number of messages that are sent down each channel at a time. 5
Multi-instance queue manager properties:
agentQMgrStandby The host name and the port number that are used for client connections, in IBM MQ CONNAME format, for the standby instance of a multi-instance agent queue manager that is defined by agentQMgr. For example, host_name(port_number) No default
Process controller properties:
agentQMgrRetryInterval The interval, in seconds, between checks on the availability of the queue manager by the agent's process controller. 30
maxRestartCount The maximum number of restarts that can happen within the time interval that is specified by the value of the maxRestartInterval property. When this value is exceeded the agent's process controller stops restarting the agent, and instead makes an action that is based on the value of the maxRestartDelay property. 4
maxRestartInterval The interval, in seconds, that the agent's process controller measures agent restarts over. If the number of restarts in this interval exceeds the value of the maxRestartCount property, the agent's process controller stops restarting the agent. Instead the agent's process controller makes an action that is based on the value of the maxRestartDelay property. 120
maxRestartDelay Determines the behavior of the agent's process controller when the rate of agent restarts exceeds the value of the maxRestartCount and maxRestartInterval properties. If you specify a value less than or equal to zero, the agent's process controller is stopped. If you specify a value greater than zero, it is the number of seconds to wait before the restart history information held by the agent's process controller is reset and the agent is restarted. -1
Protocol bridge properties:
protocolBridgeCredentialConfiguration The value of this property is passed in as a string to the initialize() method of the exit classes that are specified by protocolBridgeCredentialExitClasses. null
protocolBridgeCredentialExitClasses Specifies a comma-separated list of classes that implement a protocol bridge credential user exit routine. For more information, see Mapping credentials for a file server by using exit classes. No default.
protocolBridgeDataTimeout

The timeout in milliseconds that the protocol bridge agent waits to either establish a data connection to an FTP server or to receive data from an FTP server over a connection that is already established. If you set this property to a value of 0, the protocol bridge agent waits indefinitely. If the timeout elapses, the protocol bridge agent closes any existing data connections to the FTP server and attempts to establish a new data connection before resuming the current transfer. If the attempt to establish the new data connection fails, the current transfer also fails.

0
protocolBridgeLogoutBeforeDisconnect Specifies whether the protocol bridge agent logs the user out of the file server before closing the FTP session and disconnecting. If you set this property to true, the protocol bridge agent issues an FTP QUIT command to the file server. false
protocolBridgePropertiesConfiguration

Passed as one of the bridge properties to the initialize() method of the exit classes that are specified by the protocolBridgeServerPropertiesExitClasses property.

No default
protocolBridgePropertiesExitClasses

Specifies a comma-separated list of classes that implement a protocol bridge server properties user exit routine.

For more information, see ProtocolBridgePropertiesExit2: Looking up protocol file server properties.
No default
Protocol bridge agent logging properties:
agentLog Key value pair component and operation to enable or disable logging of FTP commands and responses between the Protocol Bridge Agent and FTP/SFTP/FTPS file servers.

For example:

    agentLog=on
    Turn on logging for all components

    agentLog=off
    Turn off logging for all components

    agentLog=ftp=on, sftp=on, ftps=off
    Turn on logging for FTP and SFTP, and turn off for FTPS

No default
agentLogFileSize Defines the maximum size of a capture file in megabytes. Same as the default for regular trace default file size. 20
agentLogFiles Defines the maximum number of capture files that are retained before the oldest file is discarded. 10
agentLogFilter By default captures communication with all FTP servers the agent is connecting to.For example:

  • Filter on host/ip address
    host=ftpprod.ibm.com, ftp2.ibm.com
    host=9.182.*
  • Filter based on metadata
    metadata="outbound files to xyz corp"
*
Queue properties:
publicationMDUser The MQMD user ID to associate with messages sent to be published by the coordination queue manager. If we do not set this property, the MQMD user ID is set based on the IBM MQ rules for setting MQMD user IDs. No default
Resource monitoring properties:
monitorFilepathPlatformSeparator Specifies whether to use platform-specific path separators within the $FILEPATH variable. A value of true uses platform-specific path separators. A value of false uses a UNIX style forward slash (/) path separator on all platforms. true
monitorMaxResourcesInPoll Specifies the maximum number of monitored resources to be triggered in each poll interval. For example, if you specify a monitor pattern of *.txt, a poll interval of 10 seconds, and set the monitorMaxResourcesInPoll property to 10, the monitorMaxResourcesInPoll property limits the agent to trigger on a maximum of 10 matches for each poll interval. Matching resources beyond the limit of 10 are triggered in later poll intervals.

In addition, we can use the monitorMaxResourcesInPoll property in combination with a matching -bs parameter on the fteCreateMonitor command, for example, to restrict each poll interval to triggering one transfer only.

A value less than or equal to zero means that the number of monitor resources that are triggered in a polling interval is unlimited.
-1
monitorReportTriggerFail Specifies whether failure conditions, in the environment and configuration, that are detected in the monitor are reported as a log message to the SYSTEM.FTE topic. A value of true logs messages. A value of false does not log messages. true
monitorReportTriggerNotSatisfied Specifies whether a non-satisfied trigger sends a log message to the SYSTEM.FTE topic that contains the details. A value of true logs messages. A value of false does not log messages. false
monitorReportTriggerSatisfied Specifies whether a satisfied trigger sends a log message to the SYSTEM.FTE topic that contains the details. A value of true logs messages. A value of false does not log messages. false
monitorSilenceOnTriggerFailure The number of consecutive failures of the resource monitor trigger before the failures are no longer reported. 5
monitorStopOnInternalFailure The number of consecutive internal FFDC conditions of the resource monitor before the monitor changes its state to stop. 10
Root directory properties:
commandPath Specifies the set of paths that commands can be called by, using one of the following methods:

  • Agent Ant call, filecopy, or filemove tasks
  • In an XML message passed to an agent, using one of the supported Managed File Transfer Agent command XML schemas (for example, managedCall or managedTransfer).

For information about the valid syntax of the value of the commandPath property, see commandPath MFT property.

Important: Take extreme care when you set this property because any command in one of the specified commandPaths can effectively be called from a remote client system that is able to send commands to the agent. For this reason, by default, when you specify a commandPath:

  • Any existing agent sandbox is configured by the agent when it starts up so that all commandPath directories are automatically added to the list of directories that have denied access for a transfer.
  • Any existing user sandboxes are updated when the agent starts up so that all the commandPath directories (and their subdirectories) are added as <exclude> elements to the <read> and <write> elements.
  • If the agent is not configured to use either an agent sandbox, or user sandboxes, then a new agent sandbox is created when the agent starts up that has the commandPath directories specified as denied directories.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

We can set the addCommandPathToSandbox property to false to override this default behavior for compatibility with the following releases:

  • IBM WebSphere MQ File Transfer Edition.
  • The IBM WebSphere MQ Version 7.5.0, Fix Pack 1 Managed File Transfer component (or earlier).
  • The IBM WebSphere MQ Version 7.5.0, Fix Pack 2 Managed File Transfer component (or later) on an installation that does not have the installation property enableFunctionalFixPack=7502 set.
Important: Be aware that this override effectively enables a client to transfer any command to the agent system and call the command, and so should be used with extreme care.
None - no commands can be called
addCommandPathToSandbox Specifies whether the directories specified by the commandPath property (and all of their subdirectories) should be added to:

  • The denied directories for an existing agent sandbox.
  • The <exclude> elements for the <read> and <write> elements for any user sandboxes that have been defined.
  • A new agent sandbox, if an agent has not been configured with either an agent sandbox, or one or more user sandboxes.
This provides compatibility with the following releases:

  • IBM WebSphere MQ File Transfer Edition.
  • The IBM WebSphere MQ Version 7.5.0, Fix Pack 1 Managed File Transfer component (or earlier).
  • The IBM WebSphere MQ Version 7.5.0, Fix Pack 2 Managed File Transfer component (or later) on an installation that does not have the installation property enableFunctionalFixPack=7502 set.
For more information, see commandPath MFT property.
True
additionalWildcardSandboxChecking Specifies whether additional checks are to be made on wildcard transfers for an agent that has been configured with a user or agent sandbox in order to restrict the locations that the agent can transfer files to and from.

When this property is set to true, the additional checking is enabled. If a transfer request attempts to read a location that is outside of the defined sandbox for file matching of the wildcard, the transfer fails. If there are multiple transfers within one transfer request, and one of these requests fails due to it attempting to read a location outside of the sandbox, the entire transfer fails. If checking fails, the reason for failure is given in an error messages (see Additional checks for wildcard transfers).

If the property is omitted or set to false then no additional checks are made on wildcard transfers.

None
sandboxRoot Specifies the set of root paths to include and exclude when we use sandboxing. See Working with MFT agent sandboxes for information about this feature.

Separate paths with a platform-specific path separator. Prefix paths with an exclamation point (!) character to denote paths as excluded from the sandbox. This feature is useful if you want to exclude a subdirectory under an included root path.

The sandboxRoot property is not supported on protocol bridge agents.

We cannot specify the sandboxRoot property and the userSandboxes property together.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

None - no sandbox
transferRoot Default root directory for relative paths that are specified to the agent.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

The home directory for the user that started the agent process.
transferRootHLQ Default HLQ (user ID) for non-fully qualified data sets specified to the agent The user name of the user that started the agent process.
userSandboxes Restrict the area of the file system that files can be transferred to and from based on the MQMD user name of the user that requests the transfer. For more information, see Working with MFT user sandboxes.

The userSandboxes property is not supported on protocol bridge agents.

We cannot specify the sandboxRoot property and the userSandboxes property together.

false
Scheduler property:
maxSchedulerRunDelay The maximum interval, in minutes, that the agent waits to check for scheduled transfers. Specify a positive integer to enable this property. For more information about why you might want to use this property, see What to do if your scheduled file transfer does not run or is delayed.

Because the agent might be reading a command from its command queue at the time that scheduled transfers are due to run, there may be an additional delay before the scheduled transfers are started. In this case, the scheduler runs immediately after that command completes.

-1
Security properties:
agentQMgrAuthenticationCredentialsFile The path to the file that contains the MQ connection credentials.

For details on creating the Authentication Credentials File see Creating an MFT credentials file

See Configure MQMFTCredentials.xml for information on the location and permissions of this file.

Further details on creating the Authentication Credentials File are in MFT and IBM MQ connection authentication

authorityChecking Specifies whether the security features described in Restricting user authorities on MFT agent actions are enabled.

From IBM MQ Version 9.0.0, Fix Pack 3 and IBM MQ Version 9.0.4, inquire is a required permission on all of the agent authority queues.

false
logAuthorityChecks The level of authority check logging that is recorded in the agent event log in the output0.log file. The values that this property can have are None or Failures or All. None
userIdForClientConnect The user ID that gets flowed through the client connections to IBM MQ. If java is specified, the user name reported by the JVM is flowed as part of the IBM MQ connection request. The values that this property can have are None or java. None
Timeout properties:
maxTransferNegotiationTime The maximum time in milliseconds that a transfer waits for a destination agent to complete negotiation. If negotiation does not complete in this time, the transfer is put into a resynchronization state and allows another transfer, when available, to run.

In scenarios where the source or destination agent is under heavy load it is possible that the default value is too low for the agent to respond quickly enough to the negotiation request. This is most likely when a source agent has a large number of resource monitors defined or when its resource monitors are monitoring directories that contain large numbers of files. However, it can also occur when a large number of transfer requests is submitted to an agent. Increasing the value of this property to 200,000 or more may be necessary in such scenarios.

30 000
recoverableTransferRetryInterval The time to wait in milliseconds between detecting a recoverable transfer error and attempting to resume the transfer. 60 000
senderTransferRetryInterval The time in milliseconds to wait until a rejected transfer is retried because the destination is already running the maximum number of transfers. Minimum value is 1000. 30 000
transferAckTimeout Timeout in milliseconds that a transfer waits for acknowledgment or data from the other end before a retry is issued. This is an advanced property and for most Managed File Transfer configurations it is not necessary to modify its value.

Acknowledgments are sent from the receiving agent to the sending agent whenever a complete window of data is received. For bandwidth-constrained or unreliable networks and large agentWindowSize and agentChunkSize settings, it is possible that the default is not long enough. This can cause unnecessary retransfer of data between the agents. Therefore increasing this value might be beneficial and may reduce the likelihood of a transfer going into recovery mode because of a slow network.

60 000
transferAckTimeoutRetries Maximum number of acknowledgment retries for a transfer without a response before the agent gives up and moves the transfer into a recovery state 5
xmlConfigReloadInterval The interval in seconds between the agent reloading XML configuration files during runtime. To prevent the agent from reloading XML configuration files during runtime set this property to -1. The following XML configuration files are affected by this property:

  • ConnectDirectCredentials.xml
  • ConnectDirectNodeProperties.xml
  • ConnectDirectProcessDefinitions.xml
  • ProtocolBridgeCredentials.xml
  • ProtocolBridgeProperties.xml
  • UserSandboxes.xml
30
Tracing and logging properties:
javaCoreTriggerFile The full path to a file location that the agent monitors. If you create or update a file at this location, the agent triggers a Javacore file. A separate thread polls this file every 30 seconds to check whether the file has been created or updated. If the file has been created or updated since the last poll, the agent generates a Javacore file in one of the following directories:

  • UNIX: MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name
  • Linux : MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name
  • Windows: MQ_DATA_PATH\mqft\logs\coordination_qmgr_name\agents\agent_name
When you specify this property, the agent outputs the following message at startup:
BFGAG0092I The <insert_0> file will be used to
request JVM diagnostic information.

For IBM WebSphere MQ Version 7.5, or later, the value of this property can contain environment variables.

See The use of environment variables in MFT properties for more information.

None
trace Trace specification when agent is to be run with trace enabled at agent start. The trace specification is a comma-separated list of classes, the equals character, and a trace level. For example, com.ibm.wmqfte.agent.Agent,com.ibm.wmqfte.commandhandler=all. We can specify multiple trace specifications in a colon-separated list. For example, com.ibm.wmqfte.agent.Agent=all:com.ibm.wmqfte.commandhandler=moderate. None
outputLogFiles The total number of output.log files to keep. This value applies to an agent's process controller and the agent itself. 5
outputLogSize The maximum size in MB of each output.log file before output wraps onto the next file. This value applies to an agent's process controller and the agent itself. 1
outputLogEncoding The character encoding that the agent uses when it writes to the output.log file. The default character encoding of the platform that the agent is running on.
traceFiles The total number of trace files to keep. This value applies to an agent's process controller as well and the agent itself. 5
traceSize The maximum size in MB of each trace file before trace wraps onto the next file. This value applies to an agent's process controller and the agent itself. 20
traceMaxBytes The limit to the amount of message data that is output in the trace file. 4096 bytes
logTransferRecovery When this property is set to a value of true, whenever a transfer enters recovery diagnostic events are reported to the agent's event log in the output0.log file.

For IBM MQ Version 9.0.0.0, the default value is true

logCapture Captures transfer request messages that are submitted to this agent and log messages that are published by the agent to the coordination queue manager. These captured messages can be helpful when debugging transfer problems. Captured messages are stored in files in the agent log directory called capture?.log. The ? is a numeric value. The file that contains the number 0 holds the newest captured messages. false
logCaptureFileSize Defines the maximum size of a capture file in megabytes. 10
logCaptureFiles Defines the maximum number of capture files that are retained before the oldest file is discarded. 10
logCaptureFilter A Java regular expression that the agent uses to match the topic name of the message. Only those messages that match the regular expression are captured. .* (match all)
resourceMonitorLog Key value pair of resource monitor and operation to turn on, or turn off, logging.The possible values are:

  • info
  • moderate
  • verbose
For example:

  • resourceMonitorLog=MON1,MON2=info:MON3=off

    Turn on logging for MON1 and MON2, and turn off logging for MON3.

  • resourceMonitorLog=info

    Turn on info level logging for all resource monitors.

The resource monitor logs are written to a file, named resmoneventsN.log, where N stands for a number; for example, resmonevents0.log. Attention: All resource monitors of an agent write to the same log file. See Logging MFT resource monitors for more information.
info
resourceMonitorLogFileSize Defines the maximum size of a capture file in megabytes. 20
resourceMonitorLogFiles Defines the maximum number of capture files that are retained before the oldest file is discarded. 10
Transfer limit properties:
maxDestinationTransfers The maximum number of concurrent transfers that the destination agent processes at any point in time. Each transfer request that is submitted to an agent counts against this total regardless of the number of files that are transferred to satisfy the request. This means that a transfer request that transfers a single file counts in the same way as a transfer request that transfers 10 files.

The agent queues transfers when the destination agent reaches the limit that is specified by the maxDestinationTransfers property.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

25 (for all agents except Connect:Direct

5 (for Connect:Direct bridge agents)

maxFilesForTransfer The maximum number of transfer items that are allowed for a single managed transfer. If a managed transfer contains more items than the value of maxFilesForTransfer, the managed transfer fails and no transfer items are processed.

Set this property prevents you from accidentally transferring too many files because of a bad transfer request, for example, if a user accidentally specifies the transfer of the root directory / on a UNIX system.

5000
maxSourceTransfers The maximum number of concurrent transfers that the source agent processes at any point in time. Each transfer request that is submitted to an agent counts against this total regardless of the number of files that are transferred to satisfy the request. This means that a transfer request that transfers a single file counts in the same way as a transfer request that transfers 10 files.

The source agent queues transfers when the destination agent reaches the limit that is specified by the maxSourceTransfers property.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

25 (for all agents except Connect:Direct bridge agents)

5 (for Connect:Direct bridge agents)

maxQueuedTransfers The maximum number of pending transfers that can be queued by an agent until the agent rejects a new transfer request. We can set this property so that despite of the limits of maxDestinationTransfers and maxSourceTransfers being met or exceeded, any new transfer requests that you make now are accepted, queued and then carried out later.

The order that queued transfer requests are processed in is a factor of their priority and how long they have been queued. Old and high priority pending transfers are selected first. Transfers with a low priority that have been on the queue for a long time are selected in preference to newer, higher priority transfers.

If the sum of the following agent property values: maxSourceTransfers + maxDestinationTransfers + maxQueuedTransfers exceeds the value of the MAXDEPTH setting of the state store queue (SYSTEM.FTE.STATE.agent name), the agent does not start.

1000
Transfer recovery timeout properties:
transferRecoveryTimeout Set amount of time, in seconds, during which a source agent keeps trying to recover a stalled file transfer. When the property is not set, the default behavior of the agent is to keep retrying until it successfully recovers the transfer. We can set the following values for the transfer recovery timeout property:

    -1
    The agent continues to attempt to recover the stalled transfer until the transfer is complete. Using this option is the equivalent of the default behavior of the agent when the property is not set.

    0
    The agent stops the file transfer as soon as it enters recovery.

    >0
    The agent continues to attempt to recover the stalled transfer for the amount of time in seconds as set by the positive integer value specified. For example, transferRecoveryTimeout=21600 indicates that the agent keeps trying to recover the transfer for 6 hours from when it enters recovery. Maximum value for this parameter is 999999999.

-1
User exit routine properties:
agentForceConsistentPathDelimiters Force the path delimiter in the source file and destination file information that is provided to the transfer exits to be the UNIX style: forward slash (/). Valid options are true and false. false
destinationTransferEndExitClasses Specifies a comma-separated list of classes that implement a destination transfer user exit routine. No default
destinationTransferStartExitClasses Specifies a comma-separated list of classes that implement a destination transfer start user exit routine. No default
exitClassPath Specifies a platform-specific, character-delimited list of directories that act as the class path for user exit routines.

The agent exit directory is searched before any entries in this class path.

Agent's exits directory
exitNativeLibraryPath Specifies a platform-specific, character-delimited list of directories that act as the native library path for user exit routines. Agent's exits directory
ioMaxRecordLength

The maximum record length, in bytes, that can be supported for a record-oriented file. Managed File Transfer can support writing to record-oriented files with any record length. However, large record lengths might cause out-of-memory errors, so to avoid these errors the maximum record length is restricted by default to 64 K. When reading from record-oriented files an entire record must fit into a single transfer chunk, therefore the record length is additionally limited by the transfer chunk size. This property is used only for I/O user exit record-oriented files.

64 KB
monitorExitClasses Specifies a comma-separated list of classes that implement a monitor exit routine. For more information, see MFT resource monitor user exits. No default
protocolBridgeCredentialExitClasses Specifies a comma-separated list of classes that implement a protocol bridge credential user exit routine. For more information, see Mapping credentials for a file server by using exit classes. No default.
sourceTransferEndExitClasses Specifies a comma-separated list of classes that implement a source transfer end exit routine. No default
sourceTransferStartExitClasses Specifies a comma-separated list of classes that implement a source transfer start exit routine. No default
IOExitClasses

Specifies a comma-separated list of classes that implement an I/O user exit routine. List only the classes that implement the IOExit interface, that is, do not list classes that implement the other I/O user exit interfaces, for example IOExitResourcePath and IOExitChannel. For more information, see Use MFT transfer I/O user exits.

No default.
IBM MQ client compression:
agentDataCompression This property is supported for client connections only.

A comma-separated list of the compression types for the transfer of file data to negotiate with the remote IBM MQ server. We can find information about these compression types in the following topic: Message data compression list.

The values are checked for validity and then passed through in order of appearance as properties to the agent client channel. The IBM MQ client then handles negotiation between this client channel and the remote server channel to find the matching lowest common denominator between the compression properties on the two channels. If no match is found, MQCOMPRESS_NONE is always selected.

MQCOMPRESS_NONE
agentHeaderCompression This property is supported for client connections only.

A comma-separated list of the compression types for the transfer of header data to negotiate with the remote IBM MQ server. Accepted values are MQCOMPRESS_NONE or MQCOMPRESS_SYSTEM. We can find information about these compression types in the following topic: Message header compression list.

The values are checked for validity and then passed through in order of appearance as properties to the agent client channel. The IBM MQ client then handles negotiation between this client channel and the remote server channel to find the matching lowest common denominator between the compression properties on the two channels. If no match is found, MQCOMPRESS_NONE is always selected.

MQCOMPRESS_NONE
z/OS-specific:
adminGroup A security manager group. Members of this group can:

  • Start the agent by using the fteStartAgent command.
  • Stop the agent by using the fteStopAgent command.
  • Enable or disable trace for the agent by using the fteSetAgentTraceLevel command.
  • Display details of a local agent by running the fteShowAgentDetails command with the -d parameter specified.
Define a security manager group, for example MFTADMIN and then add the started task userid and administrator TSO ids to this group. Edit the agent properties file and set the adminGroup property to be the name of this security manager group.
adminGroup=MFTADMIN
None
bpxwdynAllocAdditionalOptions Managed File Transfer uses the BPXWDYN text interface to create and open z/OS data sets. When BPXWDYN is used for data set allocation by default Managed File Transfer ensures, when possible, the data device is mounted (not required for disk-based data sets but is required for tape data sets). Because the options might not be supported for certain environments, use this property to change this behavior. Also when transferring to a data set it is also possible to specify options for BPXWDYN on the command line; these options are in addition to those options specified by this property.

Some BPXWDYN options must not be specified when using the bpxwdynAllocAdditionalOptions property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with MFT.

Default is as follows:

  • MOUNT for z/OS V1R8 and later
armELEMTYPE

Optional property. If the agent is configured for restart by the Automatic Restart Manager (ARM), then set this property to the ARM ELEMTYPE parameter value specified in the associated ARM policy. For an agent, set ELEMTYPE to SYSBFGAG.

Not set
armELEMENT

Optional property. If the agent is configured for restart by the Automatic Restart Manager (ARM), then set this property to the ARM ELEMENT parameter value specified in the associated ARM policy. We can set the ELEMENT value to correspond to the agent name.

Not set
Other properties:
legacyXMLMessageMQMDFormat Managed File Transfer XML messages that are generated by the agent (for example, log and transfer progress messages), are now sent to a queue with a blank MQMD format field. Previous versions of the product set the MQMD format field to MQSTR (a text message string). Setting this property to true enables the Managed File Transfer XML messages generated by the agent to be sent to a queue with MQMD format field of MQSTR. Note: Agent reply messages to commands will be sent with a message format matching the corresponding command request.

If the MQMD format field is set to MQSTR, there is potential for Managed File Transfer command XML messages to be corrupted if there are channels in the MQ network with data conversion enabled.

false