The agent.properties file
Each 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, fteCreateWebAgent, fteCreateBridgeAgent or fteCreateCDAgent command. You can use any of these commands with the -f flag to change the basic agent queue manager properties and those advanced agent properties 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 located in your config_directory/coordination_qmgr_name/agents/agent_name directory.
If you change the agent.properties file you must restart the agent to pick up the changes.
Property name | Description | Default value |
---|---|---|
agentName | The name of the agent. The name of the agent must conform to the WebSphere® MQ object naming conventions. For more information, see Object naming conventions for WebSphere MQ File Transfer Edition. | No default |
agentDesc | The description of the agent - if you have chosen 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 used for client connections to the agent queue manager. | 1414 |
agentQMgrChannel | The SVRCONN channel name used to connect to the agent queue manager. | SYSTEM.DEF.SVRCONN |
agentType | The type of agent: either a protocol bridge agent (BRIDGE) or a standard non-protocol bridge agent (STANDARD). | STANDARD |
If you 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
WebSphere MQ File Transfer Edition 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, you can use a single forward slash (/) character as a separator. For further information about character escaping in Java™ properties files, see the Oracle documentation Javadoc for the Properties class.
- Agent size properties
- Code page properties
- Command properties
- Connection properties
- Connect:Direct® bridge properties
- File to message and message to file agent properties
- General agent properties
- Input/output properties
- Multi-channel support properties
- Multi-instance properties
- Protocol bridge properties
- Queue properties
- Resource monitoring properties
- Root directory properties
- Security properties
- Timeout properties
- Tracing and logging properties
- Transfer limit properties
- User exit routine properties
- WebSphere MQ client compression properties
- z/OS-specific 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 WebSphere MQ File Transfer Edition 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 WebSphere MQ File Transfer Edition 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 WebSphere MQ messages that are transferred between the source and the destination agents. This is an advanced property and for most WebSphere MQ File Transfer Edition 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 = 10,240 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 WebSphere MQ File Transfer Edition 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, multipled 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 WebSphere MQ File Transfer Edition 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 acknowledgement 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 WebSphere 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 written to the transfer log on the SYSTEM.FTE topic. | 10 KB |
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, you 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 WebSphere MQ File Transfer Edition must have access to the WebSphere MQ Java bindings libraries. By default WebSphere MQ File Transfer Edition looks for the bindings libraries in the default location defined by WebSphere MQ. If the bindings libraries are in a different location, use this property to specify the location of the bindings libraries. | /opt/mqm/java/lib |
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 you 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 you 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 you have not set the cdNode property, this property is ignored. |
value_of_java.io.tmpdir/cdbridge-agentName On Windows, value_of_java.io.tmpdir\cdbridge-agentName |
cdTrace | Whether the agent traces data 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 been performed, 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 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. | WebSphere MQ File Transfer Edition current version, where current version is the version number of the product. For example, 7.0.4. |
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 |
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 you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
None |
cdNodeKeystorePassword | The password for the keystore specified by the
cdNodeKeystore property. If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
None |
cdNodeKeystoreType | The file format of the keystore specified by
the cdNodeKeystore property. The following values are valid: jks and
pkcs12. If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
jks |
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 you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
None |
cdNodeTruststorePassword | The password for the truststore specified by
the cdNodeTruststore property. If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
None |
cdNodeTruststoreType | The file format of the truststore specified
by the cdNodeTruststore property. The following values are valid:
jks and pkcs12. If you have not set the cdNodeProtocol property to SSL or TLS, this property is ignored. |
jks |
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 | Setting 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. You 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. This property is not available on IBM i. |
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 WebSphere MQ
system queues. System queues are prefixed with the qualifier SYSTEM. Note: System queues are used by WebSphere MQ, WebSphere MQ
File Transfer Edition, 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 |
maxDelimiterMatchLength | The maximum number of characters that can be matched by the Java regular expression 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 WebSphere MQ File Transfer Edition internal queues. For information about changing this property, see Guidance for setting WebSphere MQ attributes and WebSphere MQ File Transfer Edition 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
has been triggered 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 has been triggered has exceeded the value of monitorGroupRetryLimit. If this behavior causes the number of times that the transfer has been triggered 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 WebSphere 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 |
agentStatusJitterTolerance | The maximum amount of time an agent status message publication can be delayed by before the message is considered as overdue. This value is measured in milliseconds. The age of a status message is based on the time at which it was published at the coordination queue manager. However, the message is emitted by the agent some time before it is received at the coordination queue manager, to allow for the time required travel across the WebSphere MQ network. If this transit always takes the same amount of time then messages created 60 seconds apart are published 60 seconds apart, regardless of the actual time in transit. However, if the transit time varies between messages, they might be created at 60 second intervals but published at intervals of, for example, 61, 59, 58, and 62 seconds. The maximum deviation from 60, 2 seconds in this example, is the jitter. This property determines the maximum delay due to jitter before the message is treated as overdue. |
3000 |
enableDetailedReplyMessages | Setting 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 |
enableMemoryAllocationChecking | This property is available only if you have
enabled the function for Version 7.0.4.3, or later. Determines whether the WMQFTE agent checks that there is sufficient memory available to run a transfer before a transfer is started. The check is made on both the source and destination agents. If there is insufficient memory available, the transfer is put into recovery, which prevents the agent from failing with an out-of-memory error. 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 WMQFTE 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 |
enableUserMetadataOptions | Determines whether you can use known keys for
user-defined metadata in new transfer requests to provide additional
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 using this prefix
are not supported for user-defined use. When the enableUserMetadataOptions
property is set to true, the keys supported currently are as follows:
The value of this property can be true or false. |
false |
maxInlineFileSize | This property is available only if you have
enabled the function for Version 7.0.4.3, or later. 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. You 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 | Not setting a value for this property means 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 property to any value means the agent will not use a temporary 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. |
No default |
enableMandatoryLocking | When accessing normal files WebSphere MQ
File Transfer Edition takes a shared lock for
reading and an exclusive lock for writing. On UNIX type platforms, file locking is honored
across processes. However, on Windows file
locking is advisory only. When this property is set to true, WebSphere MQ
File Transfer Edition 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. WebSphere MQ
File Transfer Edition transfers involving that
file fail. For UNIX type platforms,
setting this property has no effect. 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. You cannot use a white space character as a replacement character. |
None |
Multi-channel support: | ||
agentMultipleChannelsEnabled | Setting this property to true enables
a WebSphere MQ
File Transfer Edition agent to send
transfer data messages across multiple WebSphere MQ channels. In some scenarios,
this might improve performance. However, you should only enable multi-channel
support if there is a demonstrable performance benefit. Only messages
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 WebSphere MQ configuration
steps in one of the following topics to enable multi-channel support:
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 sent down each channel at a time. | 5 |
Multi-instance queue manager properties: | ||
agentQMgrStandby | The host name and the port number used for client connections, in WebSphere MQ CONNAME format, for the standby instance of a multi-instance agent queue manager defined by agentQMgr. For example, host_name(port_number) | No default |
Protocol bridge properties: | ||
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 using exit classes. | No default. |
protocolBridgeCredentialConfiguration | The value of this property is passed in as a string to the initialize() method of the exit classes specified by protocolBridgeCredentialExitClasses. | null |
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 | This property is available only if you have
enabled the Version 7.0.4.1 function. Passed as one of the bridge properties to the initialize() method of the exit classes specified by the protocolBridgeServerPropertiesExitClasses property. |
No default |
protocolBridgePropertiesExitClasses | This property
is available only if you have enabled the Version 7.0.4.1 function. Specifies a comma-separated list of classes that implement a protocol bridge server properties user exit routine. For more information, see Looking up protocol file server properties by using exit classes. |
No default |
protocolServerType | Required property if you want to use the protocol
bridge. The type of network protocol that the server you want to send files to or receive files from is using. The value of this property can be FTP or SFTP. |
No default |
protocolServerHost | Required property if you want to use the protocol
bridge. The host name or IP address of the protocol file server that you want to send files to or receive files from. |
No default |
protocolServerPort | The port number of the protocol file server that you want to send files to or receive files from. If you do not provide a value for this property, the FTP, SFTP, or FTPS standard default port numbers are used. FTPS is available only if you have enabled the 7.0.4.1 function. |
No default |
protocolServerPlatform | Required property if you want to use the protocol
bridge. The platform of the protocol file server that you want to send files to or receive files from. Set this property according to how you enter paths on your FTP, FTPS, or SFTP server. For example, if you are running an FTP server on Windows but when you log in to the server, you must enter UNIX-style paths (that is, with forward slashes), set this value to UNIX and not WINDOWS. Servers running on Windows often present a UNIX-style file system. Specify either UNIX or WINDOWS. |
No default |
protocolServerTimeZone | Required property if you want to use the protocol bridge with an FTP server. This property is invalid for SFTP servers. The time zone of the protocol file server that you want to send files to or receive files from. For example: America/New_York or Asia/Tokyo. The value of this property is a time zone as defined by the Internet Assigned Numbers Authority (IANA). |
No default |
protocolServerLocale | Required property if you want to use the protocol bridge with an FTP server. This property is invalid for SFTP servers. The language used on the protocol file server that you want to send files to or receive files from. For example: en_US or ja_JP The value of this property is a language tag as defined by the Internet Engineering Task Force (IETF). |
No default |
protocolServerFileEncoding | Required property if you want to use the protocol
bridge. Defines the character encoding used by the file server. This property is used when you transfer files in text mode so that the correct encoding sequences are changed when the files are moved between platforms. For example, UTF-8. |
No default |
protocolServerListFormat | Optional and applies to FTP servers only The listing format that defines the format of
the file listed information returned from the protocol file server.
The options are:
For example, the UNIX format
is as follows:
The Windows format
is as follows:
|
UNIX |
protocolServerLimitedWrite | The default mode when writing to a file server is to create a temporary file and then rename that file when the transfer has completed. For a file server that is configured as write only, the file is created directly with its final name. The value of this property can be true or false. | false |
Queue properties: | ||
publicationMDUser | The MQMD user ID to associate with messages sent to be published by the coordination queue manager. If you do not set this property, the MQMD user ID is set based on the WebSphere MQ rules for setting MQMD user IDs. | No default |
Resource monitoring properties: | ||
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, you 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. |
No default |
monitorReportTriggerFail | Specifies whether failure conditions regarding 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 the agent Ant call, filecopy, or filemove tasks,
or by specifying in an XML message passed to an agent, by using one
of the supported WebSphere MQ
File Transfer Edition agent command XML schemas (for example, managedCall
or managedTransfer). For information about the valid syntax of the value of the commandPath property, see The commandPath property. 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, sandboxing is enabled so that all commandPath directories are automatically denied access for a transfer. You can set the sandboxRoot property to override this default behavior, but you are not recommended to do so, because this override effectively enables a client to transfer any command to the agent system and call the command. |
None - no commands can be called |
sandboxRoot | Specifies the set of root paths to include and
exclude when you use sandboxing. See Working in a sandbox 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. You cannot specify the sandboxRoot property and the userSandboxes property together. |
None - no sandbox |
transferRoot | Default root directory for relative paths specified to the agent | 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 user sandboxes. The userSandboxes property is not supported on protocol bridge agents. You 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 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 could be an additional delay before the scheduled transfers are started. In this case the scheduler will run immediately after that command has been completed. |
No default |
Security properties: | ||
authorityChecking | Specifies whether the security features described in User authorities on WebSphere MQ File Transfer Edition actions are enabled. | 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 WebSphere MQ. If java is specified the user name reported by the JVM is flowed as part of the WebSphere MQ connection request. The values that this property can have are None or java. | None |
advancedSecurityPath | The location of one or more Java archive (jar) files containing the WebSphere MQ Advanced Message
Security Java Interceptor. If
multiple jar files are specified, you must separate the file names
with semi-colon characters. If this property is not set then WebSphere MQ Advanced Message
Security is not used. This parameter is not used with embedded WebSphere MQ Advanced Message Security. |
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 WebSphere MQ
File Transfer Edition 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 |
Tracing and logging properties: | ||
ITLMTraceLevel | ITLM trace level. Controls the amount of trace
and log information that is output by Tivoli® License
Manager. Possible values (in increasing level of verbosity) are: MIN, MID, and MAX |
MIN |
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 the following directories:
When you specify this property, the agent outputs the
following message at startup:
|
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. You 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 applies to an agent's process controller as well as the agent itself. | 5 |
outputLogSize | The maximum size in MB of each output.log file, before output wraps onto the next file. This applies to an agent's process controller as well as the agent itself. | 1 |
outputLogEncoding | The character encoding that the agent uses when writing its 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 applies to an agent's process controller as well as the agent itself. | 5 |
traceSize | The maximum size in MB of each trace file, before trace wraps onto the next file. This applies to an agent's process controller as well as 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. | Before Version 7.0.4.5, the default value is false. From Version 7.0.4.5, the default value is true. |
Transfer limit properties: | ||
maxDestinationTransfers | The maximum number of concurrent transfers that the destination
agent processes at any given point in time. Each transfer request 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. When a Version 7.0.0 or Version 7.0.1 agent is acting as the source agent, if you attempt to start additional transfers, these additional transfers fail if the destination agent has reached the limit specified by the maxDestinationTransfers property. When a Version 7.0.2 or later agent is acting as the source agent, the agent queues transfers when the destination agent has reached the limit 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 bridge
agents) 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. Setting 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 given point in time.
Each transfer request 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. When a V7.0.0 or V7.0.1 agent is acting as a source agent, if you attempt to start additional transfers, these additional transfers fail if this agent has reached the limit specified by the maxSourceTransfers property. When a V7.0.2 or later agent is acting as the source agent, the source agent queues transfers when the destination agent has reached the limit 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 | For WebSphere MQ
File Transfer Edition V7.0.2
and later, the maximum number of pending transfers that can be queued
by an agent until the agent rejects a new transfer request. You can
set this property so that in spite of the limits of maxDestinationTransfers
and maxSourceTransfers being met or exceeded, any new transfer requests
you make at this time 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 |
User exit routine properties: | ||
agentForceConsistentPathDelimiters | Force the path delimiter in the source file and destination file information 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 end 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. The agent exit directory is not searched before any entries in this native library path. |
Agent's exits directory |
ioMaxRecordLength | This property is available only if you have enabled the Version
7.0.4.1 function. The maximum record length, in bytes, that can be supported for a record-oriented file. WebSphere MQ File Transfer Edition 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 currently 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 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 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 | This property is available
only if you have enabled the Version 7.0.4.1 function. 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 Using WebSphere MQ File Transfer Edition transfer I/O user exits. |
No default. |
WebSphere MQ client compression: | ||
agentDataCompression | This property is supported for client connections to WebSphere MQ Version 7.0.1 or later queue managers only.
A comma-separated list of the compression types for the transfer of file data to negotiate with the remote WebSphere MQ server. You can find information about these compression types in the following topic in the WebSphere MQ product documentation: 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 WebSphere 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 available only if you have enabled the Version 7.0.4.1
function and is supported for client connections to WebSphere MQ Version
7.0.1 or later queue managers only. A comma-separated list of the compression types for the transfer of header data to negotiate with the remote WebSphere MQ server. Accepted values are MQCOMPRESS_NONE or MQCOMPRESS_SYSTEM. You can find information about these compression types in the following topic in the WebSphere MQ product documentation: 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 WebSphere 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: | ||
bpxwdynAllocAdditionalOptions | WebSphere MQ
File Transfer Edition uses
the BPXWDYN text interface to create and open z/OS data sets. When BPXWDYN is used for data
set allocation by default WebSphere MQ
File Transfer Edition 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 fteCreateTemplate command, the fteCreateTransfer command or the bpxwdynAllocAdditionalProperties property in the agent.properties file. For a list of these properties, see BPXWDYN properties you must not use with WebSphere MQ File Transfer Edition. |
Default is as follows:
|