|
Key
This line was removed.
This word was removed. This word was added.
This line was added.
|
Comment:
Changes (2)
View Page History
...
*This page covers:* {toc:maxLevel=3}
Before you can start customizing projects and creating build configurations, you need to configure build agents.
{info}
* If you install TeamCity bundled with a Tomcat servlet container, or opt to install an agent for Windows, both the server and one build agent are installed. This is not a recommended setup for production purposes, since the build procedure can slow down the responsiveness of the web UI and overall TeamCity server functioning. If you need more build agents, perform the procedure described below.
* For production installations it is recommended to adjust [Agent's JVM parameters|Configuring Build Agent Startup Properties] to include {{\-server}} option.
{info}
h2. Installing Additional Build Agents
Before the installation, please review [Known Issues#Conflicting Software] section.
{anchor:agent_permissions}
h3. Necessary OS and environment permissions
Please note that in order to run a TeamCity build agent, user account that is running the agent should have the privileges described below.
*Network*
- Agent should be able to open HTTP connections to the server (to the same URL as server web UI)
- Server should be able to open HTTP connections to the agent. The port is determined by "ownPort" property of {{buildAgent.properties}} file (9090 by default) and the following hosts are tried:
-* host specified in the "ownAddress" property of {{buildAgent.properties}} file (if any)
-* source host of the request received by the server when agent establishes connection to the server
-* address of the network interfaces on the agent machine
If the agent is behind NAT and cannot be accessed by any of addresses of agent machine network interfaces, please specify ownAddress in the agent config.
*Common*
- agent process (java) should be able to open outbound HTTP connections to the server address (the same address you use in the browser to view TeamCity UI) and accept inbound HTTP connections from the server to the port specified as "ownPort" property in "<TeamCity agent home>/conf/buildAgent.properties" file (9090 by default). Please ensure that any firewalls installed on agent, server machine or in the network and network configuration comply with these requirements.
- have full permissions (read/write/delete) to the following directories: {{[<agent home>|Agent Home Directory]}} (necessary for automatic agent upgrade), {{[<agent work>|Agent Work Directory]}}, and {{[<agent temp>|Agent Home Directory#agentTempDir]}}.
- launch processes (to run builds).
{anchor:WindowsServicePermissions}
*Windows*
- Log on as a service (to run as Windows service)
- Start/Stop service (to run as Windows service, necessary for agent upgrade to work, see also [Microsoft KB article|http://support.microsoft.com/default.aspx?scid=kb;en-us;288129])
- Debug programs (for take process dump functionality to work)
- Reboot the machine (for agent reboot functionality to work)
For granting necessary permissions for unprivileged users, see Microsoft [SubInACL|http://www.microsoft.com/downloads/details.aspx?FamilyID=e8ba3e56-d8fe-4a91-93cf-ed6985e3927b&displaylang=en] utility. For example, to grant Start/Stop rights you might need to execute {{subinacl.exe /service browser /grant=<login name>=PTO}} command.
*Linux*
- user should be able to run {{shutdown}} command (for agent machine reboot functionality and machine shutdown functionality when running in Amazon EC2)
*Build-related Permissions*
The build process is launched by TeamCity agent and thus shares the environment and is executed under the same OS user that TeamCity agent runs under. Please ensure that TeamCity agent is configured accordingly.
See [Known Issues|Known Issues#Agent running as Windows Service Limitations] for related Windows Service Limitations.
h3. Server-Agent Data Transfers
{note}Please be sure to read through this section is you plan to deploy agent and server into non-secure network environments.{note}
During TeamCity operations, both server establishes connections to the agents and agents establish connections to the server.
Please note that by default, these connections are not secured and thus are exposing possibly sensitive data to any third party that can 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 can in theory trick agent into executing arbitrary command and perform other actions with a security impact.
It is recommended to deploy agents and the server into a secure environment and use plain HTTP for agents-to-server communications as this reduces transfer overhead.
It is possible to setup a server to be available via HTTPS protocol, so all the data traveling through the connections established from an agent to the server (incl. download of build's sources, artifacts of builds, build progress messages and build log) can be secured. See [Using HTTPS to access TeamCity server] for configuration details.
However, the data that is transferred via the connections established by the server to agents (build configuration settings (all the settings configured on the web UI including VCS root data) is passed via unsecured HTTP connection. For the time being TeamCity does not provide internal means to secure this data transfers (see/vote for [TW-5815|http://youtrack.jetbrains.net/issue/TW-5815]). If you want to secure the data you need to establish appropriate network security configurations like VPN connections between agent and server machines.
h3. Installing Procedure
You can install build agent using any of the following installation options available:
* [Via Java Web Start |#installingBuildAgentsJavaWebStart]
* [Using MS Windows installer |#installingBuildAgentsViaMSWindowsInstaller]
* [Download zip file and install manually|#installingBuildAgentsZip]
After installation, please configure the agent specifying it's name and address of TeamCity server in it's {{conf/buildAgent.properties}} [file|Build Agent Configuration].
Then [start|#Starting the Build Agent] the agent.
When the newly installed agent connects to the server for the first time, it appears on the {{Unauthorized agents}} tab under {{Agents}}, where administrators can authorize it. This will connect the agent to the server for the first time.
{note}Agents will not run builds until they are authorized in the TeamCity web UI. The agent running on the same computer as the server is authorized by default.
{note}
If the agent does not seem to run correctly, please check the [agent logs|http://confluence.jetbrains.net/display/TCD6/Viewing+Build+Agent+Logs].
{anchor: installingBuildAgentsJavaWebStart}
h3. Installing via Java Web Start
# Make sure JDK 1.6\+ is properly installed on the computer.
# On the agent computer, set up the {{JAVA_HOME}} environment variable to point to the JDK 1.6\+ installation directory.
# Navigate to the *Agents* tab in the TeamCity web UI.
# Click the "Install Build Agents" link and then click "Via Java Web Start".
# Follow the instructions.
{info}You can install the build agent Windows service during the installation process or [manually|#buildAgentsWindowsService].
{info}
{anchor: installingBuildAgentsViaMSWindowsInstaller}
h3. Installing via a MS Windows installer
# Navigate to the *Agents* tab in the TeamCity web UI.
# Click the "Install Build Agents" link and then click *MS Windows Installer* link to download the installer.
# Run the {{agentInstaller.exe}} Windows Installer and follow the installation instructions.
{note}Please ensure the user under whom the agent service is running has appropriate [permissions|#agent_permissions]
{note}{anchor: installingBuildAgentsZip}
h3. Installing via ZIP File
# In TeamCity Web UI, navigate to the *Agents* tab
# Click the *Install Build Agents* link and then click *download zip file*
# Unzip the downloaded file into the desired directory.
# Make sure that you have a JDK or JRE 1.6\+ installed (You will need JDK (not JRE) for some build runners like IntelliJ IDEA, Java Inspections and Duplicates). Please ensure that the JRE_HOME or JAVA_HOME environment variables are set (pointing to the installed JRE or JDK directory respectively) for the shell in which the agent will be started.
# Navigate to the {{<installation path>\conf}} directory, locate the file called {{buildAgent.dist.properties}} and rename it to {{buildAgent.properties}}.
# Edit the {{buildAgent.properties}} file to specify the TeamCity server URL and the name of the agent. Please refer to [Build Agent Configuration] section for more details on agent configuration
# Under Linux, you may need to give execution permissions to the bin/agent.sh shell script.
{info}On Windows you may also want to install the [build agent windows service|#buildAgentsWindowsService] instead of manual agent startup.
{info}
{anchor:agentPush}
h3. Installing via Agent Push
TeamCity provide functionality that allows to install a build agent to a remote host. Currently supported combinations of server host platform and targets for build agents are:
* from Unix based TeamCity server build agents can be installed to Unix hosts only(via SSH).
* from Windows based TeamCity server build agents can be installed to Unix (via SSH) or Windows(via psexec) hosts.
{note}{*}SSH note*
Make sure "Password" or "Public key" authentication is enabled on the target host according to preferred authentication method.
{note}
There are several requirements for the remote host that should be met:
|| Platform || Prerequisites ||
| Unix | Installed JDK(JRE) 1.6\+ required. JVM should be reachable with JAVA_HOME(JRE_HOME) environment variables or be in paths. |
| Windows | * Installed JDK/JRE 1.6\+ is recommended. No preinstalled JRE required. Zipped JRE will be downloaded from the TeamCity server during the installation phase (there is no JRE's zip bundled to TC Server now, you have to put "agent-jre-win32.zip" archive under "TEAMCITY_SERVER_ROOT/webapps/ROOT/update" folder).
* {{Sysinternals psexec.exe}} on TeamCity server required. It has to be accessible in paths. You can install it at *Administration* \| *Tools* page.\\
Note, that PsExec applies additional requirements to remote Windows host ([for example, administrative share on remote host must be accessible|http://en.wikipedia.org/wiki/Administrative_share#How_to_enable_in_Windows_Vista_and_Windows_7]). Read more about [PsExec|http://technet.microsoft.com/en-us/sysinternals/bb897553]. |
h4. Installation Procedure
# In the TeamCity Server web UI navigate to *Agents* \| *Agent Push* tab, and click *Install Agent...*.
{info}Note, that if you are going to use same settings for several target hosts, you can create a preset with these settings, and use it next time when installing an agent to another remote host.{info}
# In the *Install agent* dialog, if you don't yet have any presets saved, select "Use custom settings", specify target host platform and configure corresponding settings.
# You may need to download {{Sysinternals psexec.exe}}, in which case you will see corresponding warning and a link to *Administration* \| *Tools* page where you can download it.
{tip}You can use Agent Push presets in Amazon EC2 Cloud profile settings to automatically install build agent to started cloud instance. {tip}
{anchor: afterInstallingAgents}
h2. Starting the Build Agent
*To start the agent manually*, run the following script:
* {{{*}for Windows:*}} {{<installation path>\bin\agent.bat start}}
* {{{*}for Linux and MacOS X:*}} {{<installation path>\bin\agent.sh start}}
{note} If you're running build agent on MacOS X and you're going to run Inspection builds, you may need to use the *StartupItemContext* utility:
{code}
sudo /usr/libexec/StartupItemContext agent.sh start
{code}
{note}
To configure agent to be *started automatically*, see corresponding sections:
[Windows|#agent_start_windows]
[Mac OS X|#Using LaunchDaemons Startup Files on MacOSx]
Linux: configure daemon process with {{agent.sh start}} command to start it and {{agent.sh stop}} command to stop it.
{anchor:agentStop}
h2. Stopping the Build Agent
*To stop the agent manually*, run the {{<Agent home>\agent}} script with a {{stop}} parameter.
Use {{stop}} to request stopping after current build finished.
Use {{stop force}} to request immediate stop (if a build is running on the agent, it will be stopped abruptly (canceled))
Under Linux, you have one more option top use: {{stop kill}} to kill the agent process.
If the agent runs with a console attached, you may also press *Ctrl+C* in the console to stop the agent (if a build is running it will be canceled).
{anchor:agent_start_windows}
h2. Automatic Agent Start under Windows
To run agent automatically on machine boot under Windows you can either setup agent to be run as Windows service or use another way of automatic process start.
Using Windows service approach is the easiest way, but Windows applies some constraints to the processes run in this way.
TeamCity agent can work OK under Windows service (provided all the [requirements|#agent_permissions] are met), but is often not the case for the build processes that you will configure to be run on the agent.
That is why it is advised to run TeamCity agent as use Windows service only if all the build scripts support this.
Otherwise, it is advices to use alternative ways to start TeamCity agent automatically.
One of the ways is to configure automatic user logon on Windows start and then configure TeamCity agent start (via {{agent.bat start}}) on user logon.
{anchor: buildAgentsWindowsService}
h4. Build Agent as a Windows Service
In Windows, you may want to use the build agent Windows service to allow the build agent to run without any user logged on.
If you use Windows agent installer you have an option to install the service in the installation wizard.
{warning:title=Service system account}To run builds, the build agent should be started under a user with enough permissions for performing a build and [managing|#WindowsServicePermissions] the service. By default, Windows service in started under SYSTEM account. To change it, use the standard Windows Services applet (Control Panel\|Administrative Tools\|Services) and change the user for {{TeamCity Build Agent}} service.
{warning}
The following instruction can be used to install the service manually. This procedure should also be performed to install second and following agents on the same machine as Windows services
*To install the service:*
# Make sure there is no *TeamCity Build Agent Service <build number>* service already installed, if installed, uninstall the agent.
# Check {{wrapper.java.command}} property in {{<agent home>\launcher\conf\wrapper.conf}} file to contain valid path to Java executable in the JDK installation directory. You can use {{wrapper.java.command=../jre/bin/java}} for agent installed with Windows distribution.
# Run the {{<agent home>/bin/service.install.bat}} file.
*To start the service:*
* Run {{<agent home>/bin/service.start.bat}}
(or use Windows standard Services applet)
*To stop the service:*
* Run {{<agent home>/bin/service.stop.bat}}
(or use Windows standard Services applet)
You can also use Windows {{net.exe}} utility to manage the service once it is installed.
For example (assuming the default service name):
{code}
net start TCBuildAgent
{code}
The file {{<agent home>\launcher\conf\wrapper.conf}} can also be used to alter agent JVM parameters.
User account that is used to run build agent service should have enough rights to start/stop agent service.
{note}
A method for assigning rights to manage services is to use the Subinacl.exe utility from the Windows 2000 Resource Kit. The syntax for this is:
SUBINACL /SERVICE \\MachineName\ServiceName /GRANT=[DomainName\]UserName\[=Access\]
See [http://support.microsoft.com/default.aspx?scid=kb;en-us;288129]
{note}
h2. Using LaunchDaemons Startup Files on MacOSx
For MacOSx, TeamCity provides ability to load a build agent automatically at the system startup using LaunchDaemons {{plist}} file.
*To use LaunchDaemons* {{{*}plist{*}}} *file*:
# Install build agent on Mac either via {{buildAgent.zip}} or via Java web-start
# Prepare {{conf/buildAgent.properties}} file
# Fix launcher permissions, if needed: {{chmod \+x buildAgent/launcher/bin/\*}}
# Load build agent to LaunchDaemon via command:
{code}
sh buildAgent/bin/mac.launchd.sh load
{code}
{note}You have to wait several minutes for the build agent to auto-upgrade from the TeamCity server.
{note}
{note}
# Add a symbolic link to {{buildAgent/bin/jetbrains.teamcity.BuildAgent.plist}} file with the same name in {{~/Library/LaunchAgents}} directory for automatic startup under current user (you may need to create this directory, if it doesn't exists). To run under root you can create a link in {{/Library/LaunchDaemons}} instead.
# To start the build agent on reboot, you have to copy {{buildAgent/bin/jetbrains.teamcity.BuildAgent.plist}} file to the {{/Library/LaunchDaemons}} directory. And if you don't want to run your agent as root (and you probably don't), you have to edit {{/Library/LaunchDaemons/jetbrains.teamcity.BuildAgent.plist}} file and add section like
{code}<key>UserName></key>
<string>your_user</string>{code} Also, make sure that all files under {{buildAgent}} directory are owned by {{your_user}} to ensure proper agent upgrade process.
{code}<key>UserName></key>
<string>your_user</string>{code} Also, make sure that all files under {{buildAgent}} directory are owned by {{your_user}} to ensure proper agent upgrade process.
# To stop build agent, run the following command:
{code}
{code}
...sh buildAgent/bin/mac.launchd.sh unload {code}
If you need to configure TeamCity agent environment you can change {{<TeamCity Agent Home>/launcher/conf/wrapper.conf}} ([JSW configuration|http://wrapper.tanukisoftware.org/doc/english/properties.html]). For example, to make the agent see Mono installed using MacPorts on Mac OS X agent you will need to add the following line:
{code}
set.PATH=/opt/local/bin%WRAPPER_PATH_SEPARATOR%%PATH%
{code}
h2. Configuring Java
TeamCity Agent is a Java application and it requires JDK version 1.6 or later to work. Oracle JDK is recommended.
(Windows) .exe TeamCity distribution comes with appropriate Java bundled. If you run previous version of TeamCity agent you might need to repeat agent installation to update used Java.
For .zip agent installation you need install appropriate Java version (make it available via PATH) or available in one of the following places:
- {{<Agent home>/jre}}
- in the directory pointed to by {{JAVA_HOME}} or {{JRE_HOME}} environment variables.
You can download Java installation from [Oracle|http://java.sun.com], select Java SE, JDK, version 1.6.
If you do not have Java builds, you may install JRE instead of JDK.
h2. Upgrading Java on Agents
If a build agent uses a Java version older than it is required by agent (Java 1.6 currently), you will see the corresponding warning at the agent's page. This may happen when upgrading to a newer TeamCity version, which doesn't support an old Java version anymore. To update Java on agents you can do one of the following:
* If appropriate Java version is detected on the agent, the agent page provides an action to upgrade the Java automatically. Apon action invocation the agent will restart using another JVM installation.
* (Windows) Since build agent {{.exe}} installation comes bundled with required Java, you can just reinstall the agent using {{.exe}} installer obtained from TeamCity server | *Agents* page.
* Install required Java on the agent and restart the agent - it should then detect it and provide an action to use newer Java in web UI.
* Install required Java on the agent and [configure agent|#Configuring Java] to use it.
h2. Installing Several Build Agents on the Same Machine
TeamCity treats equally all agents no matter if they are installed on the same or on different machines. However, before installing several TeamCity build agents on the same machine, please consider the following:
- Builds running on such agents should not conflict by any resource (common disk directories, OS processes, OS temp directories).
- Depending on the hardware and the builds you may experience degraded builds' performance. Ensure there are no disk, memory, or CPU bottlenecks when several builds are run at the same time.
After having one agent installed, you can install additional agents by following the regular installation procedure (see exception for the Windows service below), but make sure that:
- The agents are installed in the separate directories.
- The agents have distinctive {{workDir}} and {{tempDir}} directories in {{[buildAgent.properties|Build Agent Configuration]}} file.
- Values for {{name}} and {{ownPort}} properties of {{[buildAgent.properties|Build Agent Configuration]}} are unique.
- No builds running on the agents have absolute checkout directory specified.
Moreover, make sure you don't have build configurations with absolute [checkout directory|Build Checkout Directory] specified (alternatively, make sure such build configurations have "[clean checkout|Clean Checkout]" option enabled and they cannot be run in parallel).
Usually, for a new agent installation you can just copy the directory of existing agent to a new place with the exception of its "temp", "work", "logs" and "system" directories. Then, modify {{conf/buildAgent.properties}} with a new "name" and "ownPort" values. Please also clear (delete or remove value) for "authorizationToken" property.
If you want to install additional agents as services under Windows, do not opt for service installation during installer wizard or install manually (see also a [feature request|http://youtrack.jetbrains.net/issue/TW-4962]), then
modify the {{<agent>\launcher\conf\wrapper.conf}} file so that {{wrapper.console.title}}, {{wrapper.ntservice.name}}, {{wrapper.ntservice.displayname}} and {{wrapper.ntservice.description}} properties have unique values within the computer. Then run {{<agent>\bin\service.install.bat}} script under user with sufficient privileges to register the new agent service.
See [above|#Installing and Running a Build Agent as a Windows Service] for the service start/stop instructions.
\\
\\ {color:#003366}{*}See also:*{color}
{panel:borderStyle=dashed|bgColor=#FFFFFF}
*Concepts*: [Build Agent]
{panel}