+

Search Tips | Advanced Search

Working 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 you 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 we do not specify the userPattern=regex attribute or value the user attribute is interpreted as a pattern with the following wildcard characters:

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 you 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:

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

For example:


Symbolic links

You 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 we have a symbolic link where /var maps to /SYSTEM/var, you 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:

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>