The MFT agent.properties file

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

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.

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.

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.

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.

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.

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.

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.

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

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

value_of_java.io.tmpdir
\cdbridge-agentName

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

• TCPIP
• SSL
• TLS

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.

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.

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

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.

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.

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

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.

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

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.

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.

• com.ibm.wmqfte.insertRecordLineSeparator
• com.ibm.wmqfte.newRecordOnLineSeparator
• com.ibm.wmqfte.convertLineSeparators

The value of this property can be true or false.

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.

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

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.

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.

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.

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.

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.

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.

• Configure an MFT agent for multiple channels in a cluster
• Configure an MFT agent for multiple channels: non-clustered

The value of this property can be true or false.

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.

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

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

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

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

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.

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

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

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

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

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.

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.

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 userSandboxes property is not supported on protocol bridge agents.

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

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.

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

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.

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.

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.

• ConnectDirectCredentials.xml
• ConnectDirectNodeProperties.xml
• ConnectDirectProcessDefinitions.xml
• ProtocolBridgeCredentials.xml
• ProtocolBridgeProperties.xml
• UserSandboxes.xml

• 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

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.

For IBM MQ Version 9.0.0.0, the default value is true

• info
• moderate
• verbose

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

5 (for Connect:Direct bridge agents)

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.

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.

5 (for Connect:Direct bridge agents)

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.

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

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

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.

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.

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.

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.

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

adminGroup=MFTADMIN

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.

• MOUNT for z/OS V1R8 and later

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.

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.

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.