Working with user sandboxes
You 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.
userSandboxes=true
When
this property is present and set to true the agent uses the information
in the configuration_directory/coordination_queue_manager/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.
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 WebSphere MQ File Transfer Edition.
- 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.
<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 queue
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.- 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..
- *
- A single asterisk matches zero or more characters in a directory name, or in a qualifier of a data set name or queue name.
- ?
- A question mark matches exactly one character in a directory name, or in a qualifier of a data set name or queue name.
- **
- Two asterisk characters match zero or more directory names, or
zero or more qualifiers in a data set name or queue 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/**.
- /**/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
You must fully resolve any symbolic links that you 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, you must specify this path as <tns:include name="/SYSTEM/var"/>, otherwise the intended transfer fails with a user sandbox security error.Example
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, add 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
- 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.
<?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>