Working with user sandboxes

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.

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

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.

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.