Work with MFT user sandboxes

We can restrict the area of the file system that files can be transferred into and out of based on the MQMD user name that requests the transfer.

User sandboxes are not supported when the agent is a protocol bridge agent or a Connect:Direct bridge agent.

To enable user sandboxing, add the following property to the agent.properties file for the agent that we want to restrict:

userSandboxes=true

When this property is present and set to true the agent uses the information in the MQ_DATA_PATH/mqft/config/coordination_qmgr_name/agents/agent_name/UserSandboxes.xml file to determine which parts of the file system the user who requests the transfer can access.

The UserSandboxes.xml XML is composed of an <agent> element that contains zero or more <sandbox> elements. These elements describe which rules are applied to which users. The user attribute of the <sandbox> element is a pattern that is used to match against the MQMD user of the request.

The file UserSandboxes.xml is periodically reloaded by the agent and any valid changes to the file will affect the behavior of the agent. The default reload interval is 30 seconds. This interval can be changed by specifying the agent property xmlConfigReloadInterval in the agent.properties file.

If you specify the userPattern=regex attribute or value, the user attribute is interpreted as a Java regular expression. For more information, see Regular expressions used by MFT.

If you do not specify the userPattern=regex attribute or value the user attribute is interpreted as a pattern with the following wildcard characters:

asterisk (*), which represents zero or more characters
question mark (?), which represents exactly one character

Matches are performed in the order that the <sandbox> elements are listed in the file. Only the first match is used, all following potential matches in the file are ignored. If none of the <sandbox> elements specified in the file match the MQMD user associated with the transfer request message, the transfer cannot access the file system. When a match has been found between the MQMD user name and a user attribute, the match identifies a set of rules inside a <sandbox> element that are applied to the transfer. This set of rules is used to determine which files, or data sets, can be read from or written to as part of the transfer.

Each set of rules can specify a <read> element, which identifies which files can be read, and a <write> element which identifies which files can be written. If we omit the <read> or <write> elements from a set of rules, it is assumed that the user associated with that set of rules is not allowed to perform any reads or any writes, as appropriate.Note: The <read> element must be before the <write> element, and the <include> element must be before the <exclude> element, in the UserSandboxes.xml file. Each <read> or <write> element contains one or more patterns that are used to determine whether a file is in the sandbox and can be transferred. Specify these patterns by using the <include> and <exclude> elements. The name attribute of the <include> or <exclude> element specifies the pattern to be matched. An optional type attribute specifies whether the name value is a file or queue pattern. If the type attribute is not specified, the agent treats the pattern as a file or directory path pattern. For example:

<tns:read>
	<tns:include name="/home/user/**"/>
	<tns:include name="USER.**" type="queue"/>
	<tns:exclude name="/home/user/private/**"/>
</tns:read>

The <include> and <exclude> name patterns are used by the agent to determine whether files, data sets, or queues can be read from or written to. An operation is allowed if the canonical file path, data set, or queue name matches at least one of the included patterns and exactly zero of the excluded patterns. The patterns specified by using the name attribute of the <include> and <exclude> elements use the path separators and conventions appropriate to the platform that the agent is running on. If you specify relative file paths, the paths are resolved relative to the transferRoot property of the agent. When specifying a queue restriction, a syntax of QUEUE@QUEUEMANAGER is supported, with the following rules:

If the at character (@) is missing from the entry, the pattern is treated as a queue name that can be accessed on any queue manager. For example, if the pattern is name it is treated the same way as name@**.
If the at character (@) is the first character in the entry, the pattern is treated as a queue manager name and all queues on the queue manager can be accessed. For example, if the pattern is @name it is treated the same way as **@name..

The following wildcard characters have special meaning when you specify them as part of the name attribute of the <include> and <exclude> elements:

*: A single asterisk matches zero or more characters in a directory name, or in a qualifier of a data set name orqueue name.
?: A question mark matches exactly one character in a directory name, or in a qualifier of a data set name orqueue name.
**: Two asterisk characters match zero or more directory names, or zero or more qualifiers in a data set name orqueue name. Also, paths that end with a path separator have an implicit ** added to the end of the path. So /home/user/ is the same as /home/user/**.

For example:

/**/test/** matches any file that has a test directory in its path
/test/file? matches any file inside the /test directory that starts with the string file followed by any single character
c:\test\*.txt matches any file inside the c:\test directory with a .txt extension
c:\test\**\*.txt matches any file inside the 'c:\test directory, or one of its subdirectories that has a .txt extension
//'TEST.*.DATA' matches any data set that has the first qualifier of TEST, has any second qualifier, and a third qualifier of DATA.
TEST.*.QUEUE@QM1 matches any queue on the queue manager QM1 that has the first qualifier of TEST, has any second qualifier, and a third qualifier of QUEUE.

Symbolic links

We must fully resolve any symbolic links that we use in file paths in the UserSandboxes.xml file by specifying hard links in the <include> and <exclude> elements. For example, if you have a symbolic link where /var maps to /SYSTEM/var, we must specify this path as <tns:include name="/SYSTEM/var"/>, otherwise the intended transfer fails with a user sandbox security error.

Example

This example shows how to allow the user with the MQMD user name guest to transfer any file from the /home/user/public directory or any of its subdirectories on the system where the agent AGENT_JUPITER is running, by adding the following <sandbox> element to the file UserSandboxes.xml in AGENT_JUPITER's configuration directory:

<?xml version="1.0" encoding="UTF-8"?>
<tns:userSandboxes
		xmlns:tns="http://wmqfte.ibm.com/UserSandboxes"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://wmqfte.ibm.com/UserSandboxes UserSandboxes.xsd">
	<tns:agent>
		<tns:sandbox user="guest">
			<tns:read>
				<tns:include name="/home/user/public/**"/>
 			</tns:read>
		</tns:sandbox>
	</tns:agent>
</tns:userSandboxes>

Example

This example shows how to allow any user with the MQMD user name account followed by a single digit, for example account4, to complete the following actions:

Transfer any file from the /home/account directory or any of its subdirectories, excluding the /home/account/private directory on the system where the agent AGENT_SATURN is running
Transfer any file to the /home/account/output directory or any of its subdirectories on the system where the agent AGENT_SATURN is running
Read messages from queues on the local queue manager starting with the prefix ACCOUNT. unless it starts with ACCOUNT.PRIVATE. (that is has PRIVATE at the second level).
Transfer data onto queues starting with the prefix ACCOUNT.OUTPUT. on any queue manager.

To allow a user with the MQMD user name account to complete these actions, add the following <sandbox> element to the file UserSandboxes.xml, in AGENT_SATURN's configuration directory:

<?xml version="1.0" encoding="UTF-8"?>
<tns:userSandboxes
			xmlns:tns="http://wmqfte.ibm.com/UserSandboxes"
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:schemaLocation="http://wmqfte.ibm.com/UserSandboxes UserSandboxes.xsd">
	<tns:agent>
		<tns:sandbox user="account[0-9]" userPattern="regex">
			<tns:read>
				<tns:include name="/home/account/**"/>
				<tns:include name="ACCOUNT.**" type="queue"/>
				<tns:exclude name="ACCOUNT.PRIVATE.**" type="queue"/>
				<tns:exclude name="/home/account/private/**"/>
                               						</tns:read>
			<tns:write>
				<tns:include name="/home/account/output/**"/>
				<tns:include name="ACCOUNT.OUTPUT.**" type="queue"/>
			</tns:write>
		</tns:sandbox>
	</tns:agent>
</tns:userSandboxes>

Parent topic: MFT sandboxes

Related reference

Additional checks for wildcard transfers

Related information

The MFT agent.properties file