Setting up and Running Additional Build Agents

Common

The agent process (java) must

• be able to open outbound HTTP connections to the server URL configured via the serverUrl property in the buildAgent.properties file (typically the same address you use in the browser to view the TeamCity UI). Sending requests to the paths under the configured URL should not be limited. See also the recommended reverse proxy settings. Ensure that any firewalls installed on the agent or server machines, network configuration and proxies (if any) comply with these requirements.

• have full permissions (read/write/delete) to the following directories recursively: <agent home> (necessary for automatic agent upgrade and agent tools support), <agent work>, <agent temp>, and agent system directory (set by workDir, tempDir, and systemDir parameters in the buildAgent.properties file)

• be able to launch processes (to run builds).

• be able to launch nested processes with the following parent process exit (this is used during agent upgrade)

Windows

• Log on as a service (to run as Windows service)

• Start/Stop service (to run as Windows service, necessary for the agent upgrade to work, see also Microsoft KB article)

• Debug programs (required for take process dump functionality)

• Reboot the machine (required for agent reboot functionality)

• To be able to monitor performance of a build agent run as a Windows service, the user starting the agent must be a member of the Performance Monitor Users group

note

For granting necessary permissions for unprivileged users, see Microsoft documentation. You can assign rights to manage services with Microsoft SubInACL utility, a command-line tool enabling administrators to directly edit security information. The tool uses the following syntax:

SUBINACL /SERVICE \\MachineName\ServiceName /GRANT=[DomainName]UserName[=Access]

For example, to grant Start/Stop rights, you might need to execute the command:

subinacl.exe /service TCBuildAgent /grant=<user login name>=PTO

Linux

• the user must be able to run the shutdown command (for the agent machine reboot functionality and the machine shutdown functionality when running in a cloud environment)

• if you are using systemd, it should not kill the processes on the main process exit (use RemainAfterExit=yes)

Build-related Permissions

The build process is launched by a TeamCity agent and thus shares the environment and is executed under the OS user used by the TeamCity agent. Ensure that the TeamCity agent is configured accordingly. See Known Issues for related Windows Service Limitations.

Unidirectional Agent-to-Server Communication

Agents use unidirectional agent-to-server connection via the polling protocol: the agent establishes an HTTP(S) connection to the TeamCity Server, and polls the server periodically for server commands.

It is recommended to use HTTPS for agent to server communications (check related server configuration notes). If the agents and the server are deployed into a secure environment, agents can be configured to use plain HTTP URL for connections to the server as this reduces transfer overhead. Note that the data travelling through the connection established from an agent to the server includes build settings, repository access credentials and keys, repository sources, build artifacts, build progress messages and build log. In case of using the HTTP protocol that data can be compromised via the "man in the middle" attack.

Bidirectional Communication

The bidirectional communication is a legacy connection between the agent and the server and it needs to be specifically enabled (see the example below). When enabled, it requires the agent to connect to the server via HTTP (or HTTPS) and the server to connect to the agent via HTTP.

The data that is transferred via the connections established by the server to agents is passed via an unsecured HTTP channel and thus is potentially exposed to any third party that may listen to the traffic between the server and the agents. Moreover, since the agent and server can send "commands" to each other, an attacker that can send HTTP requests and capture responses may in theory trick the agent into executing an arbitrary command and perform other actions with a security impact.

The communication protocol used by TeamCity agents is determined by the value of the teamcity.agent.communicationProtocols server internal property. The property accepts a comma-separated ordered list of protocols (polling and xml-rpc are supported protocol names) and is set to teamcity.agent.communicationProtocols=polling by default. If several protocols are specified, the agent tries to connect using the first protocol from this list and if it fails, it will try to connect via the second protocol in the list. polling means unidirectional protocol, xml-rpc - older, bidirectional communication.

Changing Communication Protocol

• To change the communication protocol for all agents, set the TeamCity server teamcity.agent.communicationProtocols server internal property. The new setting will be used by all agents which will connect to the server after the change. To change the protocol for the existing connections, restart the TeamCity server.

• By default, the agent's property is not configured; when the agent first connects to the server, it receives it from the TeamCity server. To change the protocol for an individual agent after the initial agent configuration, change the value of the teamcity.agent.communicationProtocols property in the agent's properties. The agent's property overrides the server property. After the change the agent will restart automatically upon finishing a running build, if any.

• When connecting TeamCity agents of version 2018.1+ to TeamCity server of version before 9.1 (e.g. after roll back following an upgrade), the agents will need to be updated to use xml-rpc protocol (or they can be reinstalled) to be able to connect to an older server to perform the self-update procedure.

Remote Host Requirements

There are several requirements for the remote host:

Installation

1. In the TeamCity Server web UI navigate to the Agents | Agent Push tab, and click Install Agent....
   If you are going to use same settings for several target hosts, you can create a preset with these settings, and use it each time when installing an agent to another remote host.

2. In the Install agent dialog, either select a saved preset or choose "Use custom settings", specify the target host platform and configure corresponding settings. Agent push to a Linux system via SSH supports custom ports (the default is 22) specified as the SSH port parameter. The port specified in a preset can be overridden in the host name, e.g. hostname.domain:2222, during the actual agent installation.

3. You may need to download Sysinternals psexec.exe, in which case you will see the corresponding warning and a link to the Administration | Tools page where you can download it.

You can use Agent Push presets in Agent Cloud profile settings to automatically install a build agent to a started cloud instance.

Automatic Agent Start under Windows

To run an agent automatically on the machine boot under Windows, you can either set up the agent to be run as a Windows service or use another way of the automatic process start.
Using the Windows service approach is the easiest way, but Windows applies some constraints to the processes run this way.
A TeamCity agent works reliably under Windows service provided all the requirements are met, but is often not the case for the build processes configured to be run on the agent.

That is why it is recommended to run a TeamCity agent as a Windows service only if all the build scripts support this. Otherwise, it is advised to use alternative OS-specific ways to start a TeamCity agent automatically.
One of the ways is to configure an automatic user logon on Windows start and then configure the TeamCity agent start (via agent.bat start) on the user logon (for example, via Windows Task Scheduler).

Build Agent as a Windows Service

In Windows, you may want to run TeamCity agent as a Windows service to allow it running without any user logged on. If you use the Windows agent installer, you have an option to install the service in the installation wizard.

warning

To run builds, the build agent must be started under a user with sufficient permissions for performing a build and managing the service. By default, a Windows service is started under the SYSTEM account which is not recommended for production use due to extended permissions the account uses. To change it, use the standard Windows Services applet (Control Panel|Administrative Tools|Services) and change the user for the TeamCity Build Agent service.

tip

If you start an Amazon EC2 cloud agent as a Windows service, check the related notes.

The following instructions can be used to install the Windows service manually (for example, after .zip agent installation). This procedure should also be performed to create Windows services for the second and following agents on the same machine.

To install the service:

1. Check if the service with the required name and id (see #4 below, service name is TeamCity Build Agent by default) is not present; if installed, remove it.

2. Check that the wrapper.java.command property in the <agent home>\launcher\conf\wrapper.conf file contains a valid path to the Java executable in the JDK installation directory. You can use wrapper.java.command=../jre/bin/java for the agent installed with the Windows distribution. Make sure to specify the path of the java.exe file without any quotes.

3. If you want to run the agent under user account (recommended) and not "System", add the wrapper.ntservice.account and wrapper.ntservice.password properties to the <agent home>\launcher\conf\wrapper.conf file with appropriate credentials

4. (for second and following installations) modify the <agent>\launcher\conf\wrapper.conf file so that the wrapper.console.title, wrapper.ntservice.name, wrapper.ntservice.displayname, and wrapper.ntservice.description properties have unique values within the computer.

5. Run the <agent home>\bin\service.install.bat script under a user with sufficient privileges to register the new agent service. Make sure to start the agent for the first time only after it is configured as described.

To start the service:

• Run <agent home>/bin/service.start.bat (or use standard Windows Services applet)

To stop the service:

• Run <agent home>/bin/service.stop.bat (or use standard Windows Services applet)

You can also use the standard Windows net.exe utility to manage the service once it is installed.
For example (assuming the default service name):

net start TCBuildAgent

The <agent home>\launcher\conf\wrapper.conf file can also be used to alter the agent JVM parameters.

The user account used to run the build agent service must have enough rights to start/stop the agent service, as described above.

Automatic Agent Start under Linux

To run an agent automatically on the machine boot under Linux, configure daemon process with the agent.sh start command to start it and agent.sh stop command to stop it.

For systemd, see the example teamcityagent.service configuration file:

[Unit]
Description=TeamCity Build Agent
After=network.target

[Service]
Type=oneshot

User=teamcityagent
Group=teamcityagent
ExecStart=/home/teamcityagent/agent/bin/agent.sh start
ExecStop=-/home/teamcityagent/agent/bin/agent.sh stop

# Support agent upgrade as the main process starts a child and exits then
RemainAfterExit=yes
# Support agent upgrade as the main process gets SIGTERM during upgrade and that maps to exit code 143
SuccessExitStatus=0 143

[Install]
WantedBy=default.target

For init.d, refer to an example procedure:

1. Navigate to the services start/stop services scripts directory:

cd /etc/init.d/

2. Open the build agent service script:

sudo vim buildAgent

3. Paste the following into the file :

#!/bin/sh
### BEGIN INIT INFO
# Provides:          TeamCity Build Agent
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start build agent daemon at boot time
# Description:       Enable service provided by daemon.
### END INIT INFO
#Provide the correct user name:
USER="agentuser"

case "$1" in
start)
 su - $USER -c "cd BuildAgent/bin ; ./agent.sh start"
;;
stop)
 su - $USER -c "cd BuildAgent/bin ; ./agent.sh stop"
;;
*)
  echo "usage start/stop"
  exit 1
 ;;

esac

exit 0

4. Set the permissions to execute the file:

sudo chmod 755 buildAgent

5. Make links to start the agent service on the machine boot and on restarts using the appropriate tool:

• For Debian/Ubuntu:

sudo update-rc.d buildAgent defaults

• For Red Hat/CentOS:

sudo chkconfig buildAgent on

Automatic Agent Start under macOS

For macOS, TeamCity provides the ability to load a build agent automatically when a build user logs in.

LaunchAgent Approach

To configure an automatic build agent startup via LaunchAgent, follow these steps:

1. Install a build agent on a Mac via buildAgent.zip.

2. Prepare the conf/buildAgent.properties file (set agent name there, at least).

3. Make sure that all files under the buildAgent directory are owned by your_build_user to ensure a proper agent upgrade process.

4. Load the build agent via the command:

mkdir buildAgent/logs  # Directory should be created under your_build_user user
sh buildAgent/bin/mac.launchd.sh load

Run these commands under the your_build_user account.

Wait several minutes for the build agent to auto-upgrade from the TeamCity server. You can watch the process in the logs:

tail -f buildAgent/logs/teamcity-agent.log

5. When the build agent upgrades and successfully connects to TeamCity server, stop the agent:

sh buildAgent/bin/mac.launchd.sh unload

6. After the build agent upgrades from the TeamCity server, copy the buildAgent/bin/jetbrains.teamcity.BuildAgent.plist file to the $HOME/Library/LaunchAgents/ directory. If you don't want TeamCity to start under the root permissions, specify the UserName key in the .plist file, for example:

<key>UserName</key>
<string>teamcity_user</string>

7. Configure your Mac system to automatically login as a build user, as described here.

8. Reboot.

On the system startup, the build user should automatically log in, and the build agent should start.

To quickly check that the build agent is running, use the following command:

launchctl list | grep BuildAgent
69722	0	jetbrains.teamcity.BuildAgent

Configure a Second Build Agent on Mac OS

If you want to start several build agents, repeat the procedure of installing and starting build agent with the following changes:

• Install the second build agent in a different directory.

• In conf/buildAgent.properties specify a different agent name.

• Do not run buildAgent/bin/mac.launchd.sh; instead

  • Create a copy of the $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent.plist file as $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist.

  • Edit the $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist file and set the following parameters:

    • the Label parameter to jetbrains.teamcity.BuildAgent2

    • the WorkingDirectory parameter to the correct path to the second build agent home

  • Start the second agent with the command launchctl load $HOME/Library/LaunchAgents/jetbrains.teamcity.BuildAgent2.plist

To check that both build agents are running, use the following command:

launchctl list | grep BuildAgent
70599	0	jetbrains.teamcity.BuildAgent2
69722	0	jetbrains.teamcity.BuildAgent