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. 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 the 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 our 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 Create 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.

For details on creating the Authentication Credentials File see Create 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 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 we 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

For information about what these keys mean, see fteCreateTransfer: start a new file transfer.

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 our 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 we are recommended to thoroughly test different values until you find the best file size for the system.

This feature is turned off by default, or by setting the maxInlineFileSize property to 0.

This property is read during agent startup and if set to the value true, the agent is started in high availability mode. If we do not specify the property, or set the value to false, the agent starts as a non-highly available agent.

This property is used by the standby instance to attempt to open the shared queue at specified intervals. The attempts are repeated until the standby instance opens the SYSTEM.FTE.HA.<agent name> queue, or is stopped by the fteStopAgent command.

This property sets the time duration for which the active instance waits for a status publication from a standby instance.

If no publication is received from a standby instance, even after this ait time, the active instance removes the standby instance information from its list of standby instances.

The default value is twice that of the standbyStatusPublishInterval property, so that the active instance waits longer before removing the standby instance from its list.

This property sets the expiry time of the standby status message put to the command queue of an agent. The message expires if the active instance of an agent does not process this message.

This property is used to set the frequency at which the standby instance publishes its state.

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

Additionally, we 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.

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.

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 fte:call Ant task, fte:filecopy, or fte: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.

• IBM WebSphere MQ File Transfer Edition. Note that IBM WebSphere MQ File Transfer Edition (FTE) is no longer a supported product. To migrate from FTE to the Managed File Transfer component in IBM MQ, see Migrating Managed File Transfer.
• 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.

• 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. Note that IBM WebSphere MQ File Transfer Edition (FTE) is no longer a supported product. To migrate from FTE to the Managed File Transfer component in IBM MQ, see Migrating Managed File Transfer.
• 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.

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 we 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 Create 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

The inquire permission 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

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.

For IBM MQ Version 9.0.0.0 and later, the default value is true.

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

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

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: HdrCompList [2] (MQLONG).

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.

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

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