Configure Agent Installation
A build agent can be configured by adjusting in the <TeamCity Agent Home>/conf/buildAgent.properties
file.
This Java properties configuration file can store properties that will be published on the server as agent properties and can participate in the Agent Requirements expressions. All system and environment properties defined in the file will be passed to every build run on the agent.
Syntax reference:
Use
property_name=value<newline>
syntax.Use
#
in the first position of the line for a comment.Use
/
instead of\
as the path separator. If you need to include\
, escape it with another\
.Whitespaces are processed as any other symbol.
Example agent configuration file:
## The address of the TeamCity server. The same as is used to open the TeamCity web interface in the browser.
## Must include the protocol specification (https:// is recommended).
serverUrl=http://localhost:8111/
## The unique name of the agent used to identify this agent on the TeamCity server
## Use blank name to let server generate it.
## By default, this name would be created from the build agent's host name
name=Default agent
## Container directory to create default checkout directories for the build configurations.
workDir=../work
## Container directory for the temporary directories.
## Please note that the directory may be cleaned between the builds.
tempDir=../temp
## Container directory for agent state files and caches.
## TeamCity agent assumes ownership of the directory and can delete the content inside.
systemDir=../system
######################################
# Optional Agent Properties #
######################################
## A token which is used to identify this agent on the TeamCity server for agent authorization purposes.
## It is automatically generated and saved back on the first agent connection to the server.
authorizationToken=1234567890abcdefghijklml
Make sure the file is writable for the build agent process itself. For example, that the file is updated to store its authorization token generated on the server-side.
If you install multiple TeamCity nodes behind a reverse proxy, serverUrl
should be set to the proxy URL.
If the name
property is not specified, the server will generate a build agent name automatically. By default, this name will be created from the build agent's host name.
The file can be edited while the agent is running: the agent detects the change and (upon finishing a running build, if any) restarts automatically loading the new settings.
The port where the TeamCity build agent starts and where it listens for the incoming data from the server is determined via the ownPort
property (9090 by default). If the firewall is configured, make sure that the incoming connections for this port are allowed on the agent machine.
ownPort=9090
If more than one build agent is hosted on the same machine, different ports must be assigned to them via the ownPort
property in the buildAgent.properties
file of every agent.
When an agent connects to the TeamCity server for the first time, the agent automatically determines its IP address to use for connection, unless the ownAddress
property is defined. If the agent machine has several network interfaces, automatic detection may fail. In this case, it is recommended to specify the ownAddress
property:
ownAddress=<own IP address or server-accessible domain name>
If you have a self-updating Git repository proxy that is significantly closer than the original Git repository for certain agents, you can allow these agents to download sources from this mirror. To do so, add the teamcity.git.fetchUrlMapping.<name>=<original URL> => <proxy URL>
setting to the agent configuration file. See this section for more information: Git VCS Root | General Settings.
To set up the buildAgent.properties file, you can run the <Agent_folder>/bin/agent.bat
or <Agent_folder>/bin/agent.sh
script with the configure
command. This command allows you to set up core agent properties and save them to the target configuration file. If no configuration file path is specified, the changes will be saved to the default <Agent_folder>/conf/buildAgent.properties
properties.
To view the list of available parameters, run this command with the --help
flag.
./agent.sh configure --help
Java executable is found: '/Library/Java/JavaVirtualMachines/amazon-corretto-11.jdk/Contents/Home/bin/java'
Configuring TeamCity build agent...
TeamCity Agent configurator
Usage:
configure PROPERTIES_FILE
configure -f PROPERTIES_FILE
configure [PROPERTIES]
configure --usage
status
status short
Where PROPERTIES format is --key=value or --key value
Supported properties:
* --agent-config-file=PATH - path to build agent properties file (<Agent Root>/conf/buildAgent.properties by default)
* All default properties that can be configured in buildAgent.properties file
Also there are aliases for some of them:
address = ownAddress
auth-token = authorizationToken
logs-dir = logsDir
name = name
port = ownPort
server-url = serverUrl
system-dir = systemDir
temp-dir = tempDir
work-dir = workDir
Sample command that writes the server URL and sets up the custom agent name:
./agent.sh configure --server-url http://localhost:8111/ --name AG2
note
The
configure
command writes the required parameters to.properties
file, but does not automatically create it if no such file is present. Make sure the target properties file exists when specifying a custom file location.Adding and changing custom properties (for example,
./agent.sh configure --myCustomProperty=newValue
) is not supported.
It is possible to configure a forward proxy server for agent-to-server connections.
On the TeamCity agent side, specify the proxy to connect to the TeamCity server using the following properties in the buildAgent.properties
file:
## The domain name or the IP address of the proxy host and the port
teamcity.http.proxyHost=123.45.678.9
teamcity.http.proxyPort=8080
## If the proxy requires authentication, specify the login and password
teamcity.http.proxyLogin=login
teamcity.http.proxyPassword=password
To access HTTPS endpoints (for example, GitHub-hosted repositories), configure the teamcity.https.*
properties as well.
tip
The proxy has to be configured not to cache any TeamCity server responses. For example, if you use Squid, add "cache deny all" line to the
squid.conf
file.If you're using a custom artifact storage, make sure the agent can connect to the required service. For example, if you use S3 buckets to store artifacts, the proxy should allow
*.amazonaws.com
traffic.
Thanks for your feedback!