Build Agent’s user “home” folder permissions considerations

The past days, while I was trying the configuration of a deployment of the Build System Toolkit and the Build Agent (based on version 4.0.4), in a test system using the Money that Matters sample, I faced the following error running a build:

PTY allocated pseudo-tty *PtyPipe
EXEC Unable to set working directory to '"/u/<userX>"' (111).

I want to blog about this error and its resolution, taking the opportunity meanwhile to provide links to important configuration information.

My test was consisting in running some sanity check builds to verify that the different components were successfully deployed, and to validate the definitions needed from the build system. The steps I took were:

  • Deploy the Money That Matters sample in a RTC test server
  • Configure the definitions in the sample for the environment
  • Run a verification build

I may blog in the future about some of these steps, but in this post I want to focus on the error I faced; as I think it is not enough advertised.

Environment Configuration

Let’s first briefly discuss the topology of the environment I was using for this testing … I was using a personal test sandbox with a distribution like the standard Evaluation Topology, connecting to and building using, the new configured system; in which the Build Toolkit was installed and the Build Agent was running. Summarizing:


If you are in the process of installing the Build System Toolkit and the Build Agent on Z, you will be interested in checking the information in Installing and configuring the Build System Toolkit on z/OS systems and Installing and configuring the Rational Build Agent on a z/OS system.

An important consideration in this configuration is the identity under you run the Build Agent. You can find information in the topic around Security for the Rational Build Agent and this wiki topic. In this environment we had the Build Agent started with a super user ID, while a different user ID was specified to connect to it in Build Agent tab of the Build Engine (“” of the sample).

Running a test build – issue faced

Once I had the environment ready for accepting builds, and right after I configured the Money That Matters sample definitions, I executed the “” build resulting in the referred error:

PTY allocated pseudo-tty *PtyPipe
EXEC Unable to set working directory to '"/u/<userX>"' (111).

I have masked the actual user ID in that message, but it was the one used to start the Build Agent on the host. A quick checklist lead us to the root cause while reviewing some other configuration decisions:

  • The Build Agent was started under <userX> ID, which is a super-user
  • The Build Engine’s Build Agent tab (“” Build Engine) was configured to connect under a user identity different of <userX>, let’s say <userY>
  • The connection test of the Build Engine connecting to the Build Agent using <userY> was successful, and this user ID has a proper HOME variable set on USS
  • “/u/<userX>” is the HOME directory of <userX> but it’s not referenced on any of the Build Agent configuration files

OK, let’s see, what are the permissions on “/u/<userX>”? Yes, they are rwx — —- (no permission to others but the actual user ID). A little modification of the permissions allowing the execution for others (rwx — —x), and re-running the build ended up in a good build result.

Therefore, we needed at least execution permission over the HOME folder of the user ID running the Build Agent on the host, when builds are to be executed under a different authority (i.e., a different user specified in the Build Agent tab of the Build Engine).

Adoption tip

Based on the permission needs, we can think of, at least, two solutions:

  1. Make sure that the user under which the Build Agent is started allows execution on its HOME directory to the user IDs that will be specified for connecting in the Build Agent tab of the Build Engine. This will allow the process to attach to the directory to begin the execution, then change to the Build Engine configured user ID and continue the execution on the proper folder.
  2. Modify the Build Agent’s shell script defining a HOME variable to point to a different folder. Note that configuring a HOME in that script is only necessary when the user has no proper environment variable set, but in our case we can use it as a workaround to force the process attach to a different folder and avoid granting execution permissions over a real HOME folder. For example setting in the shell script something like:
export HOME=/u/dummybuilder

Will use “/u/dummybuilder” as the Build Agent’s process init folder.

I hope you find this useful and this little tip can help others that face this error!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s