How to install

System Administrators can download the runAs.zip from here and install it on the TeamCity server as usual.

Configuring TeamCity Agents

On Windows

The teamcity-runas plugin requires the TeamCity agent’s account to have certain permissions. Depending on the way you run the agent, granting additional privileges may be required.

• If you are running the TeamCity agent as a Windows service under the Local System account, it has all required permissions and the teamcity-runas plugin works out-of-the-box.

• If you are starting the agent as a Windows service using a specified Windows account (for example BuildUser)

  • it must have administrative privileges
  • must have the ability to replace a process level token (SeAssignPrimaryTokenPrivilege)
  • and act as a part of the operating system (SeTcbPrivilege)

  These privileges can be added via a security policy using Control Panel | Administrative Tools | Local Security Policy | Local Policies | User Rights Assignment | Replace a process level token. See Microsoft documentation for details You can also do it using the provided scripts under an administrative Windows user account, e.g.:

  runGrantAccess.cmd BuildUser
  

  ⚠️ The changes will not take effect until the next login, so you'll have to restart the agent.

• If you are starting the TeamCity agent as a Windows console application, your Windows user account must have administrative privileges.

On Mac

• With Mac, the recommended setup is to run the TeamCity agent as a user different from ROOT, you need to install socat using the following command:

  brew install socat
  

  ⚠️ Make sure that any runAs users have permissions to write and to execute files in the TeamCity agent's temporary directory: chmod a+rwx and to search in all its parent directories: chmod a+X.

On Linux

• With Debian/Ubuntu/Linux, the recommended setup is to run the TeamCity agent as ROOT, as in this case the account has all the required privileges and the teamcity-runas plugin works out-of-the-box.

• If you run the TeamCity agent as a user different from ROOT, you need to install socat using the following command:

  sudo apt-get update && sudo apt-get install socat
  

  ⚠️ Make sure that any runAs users have permissions to write and to execute files in the TeamCity agent's temporary directory: chmod a+rwx and to search in all its parent directories: chmod a+X.