Self-hosted Linux agents

Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, service connections are called service endpoints, stages are called environments, and jobs are called phases.

To run your jobs, you'll need at least one agent. A Linux agent can build and deploy different kinds of apps, including Java and Android apps. We support Ubuntu, Red Hat, and CentOS.

Before you begin:

  • If your pipelines are in Azure Pipelines and a Microsoft-hosted agent meets your needs, you can skip setting up a private Linux agent.
  • Otherwise, you've come to the right place to set up an agent on Linux. Continue to the next section.

Learn about agents

If you already know what an agent is and how it works, feel free to jump right in to the following sections. But if you'd like some more background about what they do and how they work, see Azure Pipelines agents.

Check prerequisites

Azure Pipelines: The agent is based on CoreCLR 2.0. You can run this agent on several Linux distributions. Make sure your machine is prepared with our prerequisites.

TFS 2018 RTM and older: The agent is based on CoreCLR 1.0. Make sure your machine is prepared with our prerequisites for either of the supported distributions:

Subversion

If you're building from a Subversion repo, you must install the Subversion client on the machine.

You should run agent setup manually the first time. After you get a feel for how agents work, or if you want to automate setting up many agents, consider using unattended config.

Prepare permissions

Decide which user you'll use

As a one-time step, you must register the agent. Someone with permission to administer the agent queue must complete these steps. The agent will not use this person's credentials in everyday operation, but they're required to complete registration. Learn more about how agents communicate.

Authenticate with a personal access token (PAT)

  1. Sign in with the user account you plan to use in either your Azure DevOps organization (https://dev.azure.com/{your_organization}) or your Team Foundation Server web portal (https://{your-server}:8080/tfs/).

  2. From your home page, open your profile. Go to your security details.

    test

  3. Create a personal access token.

    test

  4. For the scope select Agent Pools (read, manage) and make sure all the other boxes are cleared. If it's a deployment group agent, for the scope select Deployment group (read, manage) and make sure all the other boxes are cleared.

  5. Copy the token. You'll use this token when you configure the agent.

Authenticate as a Windows user (TFS 2015 and TFS 2017)

As an alternative, on TFS 2017, you can use either a domain user or a local Windows user on each of your TFS application tiers.

On TFS 2015, for macOS and Linux only, we recommend that you create a local Windows user on each of your TFS application tiers and dedicate that user for the purpose of deploying build agents.

Confirm the user has permission

Make sure the user account that you're going to use has permission to register the agent.

Is the user an Azure DevOps organization owner or TFS server administrator? Stop here, you have permission.

Otherwise:

  1. Open a browser and navigate to the Agent pools tab for your Azure Pipelines organization or TFS server:
    • Azure Pipelines: https://dev.azure.com/{your_organization}/_settings/agentpools
    • Azure DevOps Server 2019: https://dev.azure.com/{your_collection}/_settings/agentpools
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool
    • That didn't work: Get the correct URL
  2. Click the pool on the left side of the page and then click Roles.
  3. If the user account you're going to use is not shown, then get an administrator to add it. The administrator can be an agent pool administrator, an Azure DevOps organization owner, or a TFS server administrator. If it's a deployment group agent, the administrator can be an deployment group administrator, an Azure DevOps organization owner, or a TFS server administrator. You can add a user to the deployment group administrator role in the Security tab on the Deployment Groups page in Azure Pipelines.

If you see a message like this: Sorry, we couldn't add the identity. Please try a different identity., you probably followed the above steps for an organization owner or TFS server administrator. You don't need to do anything; you already have permission to administer the agent queue.

Download and configure the agent

Azure Pipelines

  1. Log on to the machine using the account for which you've prepared permissions as explained above.
  2. In your web browser, sign in to Azure Pipelines, and navigate to the Agent pools tab:
    • Azure Pipelines: https://dev.azure.com/{your_organization}/_settings/agentpools
    • Azure DevOps Server 2019: https://dev.azure.com/{your_collection}/_settings/agentpools
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool
    • That didn't work: Get the correct URL
  3. Click Download agent.
  4. On the Get agent dialog box, click Linux.
  5. On the left pane, select the specific flavor. We offer x64 or ARM for most Linux distributions. We also offer a specific build for Red Hat Enterprise Linux 6.
  6. On the right pane, click the Download button.
  7. Follow the instructions on the page.
  8. Unpack the agent into the directory of your choice. cd to that directory and run ./config.sh.

TFS 2017 and TFS 2018

  1. Log on to the machine using the account for which you've prepared permissions as explained above.
  2. In your web browser, sign in to TFS, and navigate to the Agent pools tab:
    • Azure Pipelines: https://dev.azure.com/{your_organization}/_settings/agentpools
    • Azure DevOps Server 2019: https://dev.azure.com/{your_collection}/_settings/agentpools
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool
    • That didn't work: Get the correct URL
  3. Click Download agent.
  4. On the Get agent dialog box, click Linux.
  5. Click the Download button.
  6. Follow the instructions on the page.
  7. Unpack the agent into the directory of your choice. cd to that directory and run ./config.sh. Make sure that the path to the directory contains no spaces because tools and scripts don't always properly escape spaces.

TFS 2015

  1. Browse to the latest release on GitHub.

  2. Follow the instructions on that page to download the agent.

  3. Configure the agent.

    ./config.sh
    

Server URL

Azure Pipelines: https://dev.azure.com/{your-organization}

TFS 2017 and newer: https://{your_server}/tfs

TFS 2015: http://{your_server}:8080/tfs

Authentication type

Azure Pipelines

Choose PAT, and then paste the PAT token you created into the command prompt window.

Note

When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent. Learn more at Communication with Azure Pipelines or TFS.

TFS

Important

Make sure your server is configured to support the authentication method you want to use.

When you configure your agent to connect to TFS, you've got the following options:

  • Alternate Connect to TFS using Basic authentication. After you select Alternate you'll be prompted for your credentials.

  • Integrated Not supported on macOS or Linux.

  • Negotiate (Default) Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate you'll be prompted for credentials.

  • PAT Supported only on Azure Pipelines and TFS 2017 and newer. After you choose PAT, paste the PAT token you created into the command prompt window. Use a personal access token (PAT) if your TFS instance and the agent machine are not in a trusted domain. PAT authentication is handled by your TFS instance instead of the domain controller.

Note

When using PAT as the authentication method, the PAT token is used only for the initial configuration of the agent on newer versions of TFS. Learn more at Communication with Azure Pipelines or TFS.

Run interactively

For guidance on whether to run the agent in interactive mode or as a service, see Agents: Interactive vs. service.

To run the agent interactively:

  1. If you have been running the agent as a service, uninstall the service.

  2. Run the agent.

    ./run.sh
    

To use your agent, run a job using the agent's pool. If you didn't choose a different pool, your agent will be in the Default pool.

Run as a systemd service

If your agent is running on these operating systems you can run the agent as a systemd service:

  • Ubuntu 16 LTS or newer
  • Red Hat 7.1 or newer

We provide the ./svc.sh script for you to run and manage your agent as a systemd service. This script will be generated after you configure the agent.

Note

If you have a different distribution, or if you prefer other approaches, you can use whatever kind of service mechanism you prefer. See Service files.

Commands

Change to the agent directory

For example, if you installed in the myagent subfolder of your home directory:

cd ~/myagent$

Install

Command:

sudo ./svc.sh install

This command creates a service file that points to ./runsvc.sh. This script sets up the environment (more details below) and starts the agents host.

Start

sudo ./svc.sh start

Status

sudo ./svc.sh status

Stop

sudo ./svc.sh stop

Uninstall

You should stop before you uninstall.

sudo ./svc.sh uninstall

Update environment variables

When you configure the service, it takes a snapshot of some useful environment variables for your current logon user such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software):

  1.  

    ./env.sh
    
  2.  

    sudo ./svc.sh stop
    
  3.  

    sudo ./svc.sh start
    

The snapshot of the environment variables is stored in .env file under agent root directory, you can also change that file directly to apply environment variable changes.

Run instructions before the service starts

You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts.

  1. Edit runsvc.sh.

  2. Replace the following line with your instructions:

    # insert anything to setup env when running as a service
    

Service files

When you install the service, some service files are put in place.

systemd service file

A systemd service file is created:

/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

For example, you have configured an agent (see above) with the name our-linux-agent. The service file will be either:

  • Azure Pipelines: the name of your organization. For example if you connect to https://dev.azure.com/fabrikam, then the service name would be /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service

  • TFS: the name of your on-premises TFS AT server. For example if you connect to http://our-server:8080/tfs, then the service name would be /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service

sudo ./svc.sh install generates this file from this template: ./bin/vsts.agent.service.template

.service file

sudo ./svc.sh start finds the service by reading the .service file, which contains the name of systemd service file described above.

Alternative service mechanisms

We provide the ./svc.sh script as a convenient way for you to run and manage your agent as a systemd service. But you can use whatever kind of service mechanism you prefer (for example: initd or upstart).

You can use the template described above as to facilitate generating other kinds of service files.

Use a cgroup to avoid agent failure

It's important to avoid situations in which the agent fails or become unusable because otherwise the agent can't stream pipeline logs or report pipeline status back to the server. You can mitigate the risk of this kind of problem being caused by high memory pressure by using cgroups and a lower oom_score_adj. After you've done this, Linux reclaims system memory from pipeline job processes before reclaiming memory from the agent process. Learn how to configure cgroups and OOM score.

Replace an agent

To replace an agent, follow the Download and configure the agent steps again.

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, then make sure you remove the agent (see below) that you're replacing. Otherwise, after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent:

  1. Stop and uninstall the service as explained above.

  2. Remove the agent.

    ./config.sh remove
    
  3. Enter your credentials.

After you've removed the agent, you can configure it again.

Unattended config

The agent can be set up from a script with no human intervention. You must pass --unattended and the answers to all questions.

To configure an agent, it must know the URL to your organization or collection and credentials of someone authorized to set up agents. All other responses are optional. Any command-line parameter can be specified using an environment variable instead: put its name in upper case and prepend VSTS_AGENT_INPUT_. For example, VSTS_AGENT_INPUT_PASSWORD instead of specifying --password.

Required options

  • --unattended - agent setup will not prompt for information, and all settings must be provided on the command line
  • --url <url> - URL of the server. For example: https://dev.azure.com/myorganization or http://my-azure-devops-server:8080/tfs
  • --auth <type> - authentication type. Valid values are:
    • pat (Personal access token)
    • negotiate (Kerberos or NTLM)
    • alt (Basic authentication)
    • integrated (Windows default credentials)

Authentication options

  • If you chose --auth pat:
    • --token <token> - specifies your personal access token
  • If you chose --auth negotiate or --auth alt:
    • --userName <userName> - specifies a Windows username in the format domain\userName or userName@domain.com
    • --password <password> - specifies a password

Pool and agent names

  • --pool <pool> - pool name for the agent to join
  • --agent <agent> - agent name
  • --replace - replace the agent in a pool. If another agent is listening by the same name, it will start failing with a conflict

Agent setup

  • --work <workDirectory> - work directory where job data is stored. Defaults to _work under the root of the agent directory. The work directory is owned by a given agent and should not share between multiple agents.
  • --acceptTeeEula - accept the Team Explorer Everywhere End User License Agreement (macOS and Linux only)
  • --once - accept only one job and then spin down gracefully (useful for running on a service like Azure Container Instances)

Windows-only startup

  • --runAsService - configure the agent to run as a Windows service (requires administrator permission)
  • --runAsAutoLogon - configure auto-logon and run the agent on startup (requires administrator permission)
  • --windowsLogonAccount <account> - used with --runAsService or --runAsAutoLogon to specify the Windows user name in the format domain\userName or userName@domain.com
  • --windowsLogonPassword <password> - used with --runAsService or --runAsAutoLogon to specify Windows logon password
  • --overwriteAutoLogon - used with --runAsAutoLogon to overwrite the existing auto logon on the machine
  • --noRestart - used with --runAsAutoLogon to stop the host from restarting after agent configuration completes

Deployment group only

  • --deploymentGroup - configure the agent as a deployment group agent
  • --deploymentGroupName <name> - used with --deploymentGroup to specify the deployment group for the agent to join
  • --projectName <name> - used with --deploymentGroup to set the project name
  • --addDeploymentGroupTags - used with --deploymentGroup to indicate that deployment group tags should be added
  • --deploymentGroupTags <tags> - used with --addDeploymentGroupTags to specify the comma separated list of tags for the deployment group agent - for example "web, db"

./config.sh --help always lists the latest required and optional responses.

Help on other options

To learn about other options:

./config.sh --help

The help provides information on authentication alternatives and unattended configuration.

Capabilities

Your agent's capabilities are cataloged and advertised in the pool so that only the builds and releases it can handle are assigned to it. See Build and release agent capabilities.

In many cases, after you deploy an agent, you'll need to install software or utilities. Generally you should install on your agents whatever software and tools you use on your development machine.

For example, if your build includes the npm task, then the build won't run unless there's a build agent in the pool that has npm installed.

Important

After you install new software on an agent, you must restart the agent for the new capability to show up in the pool so that the build can run.

Q & A

How do I make sure I have the latest v2 agent version?

  1. Go to the Agent pools control panel tab:

    • Azure Pipelines: https://dev.azure.com/{your_organization}/_settings/agentpools
    • Azure DevOps Server 2019: https://dev.azure.com/{your_collection}/_settings/agentpools
    • TFS 2018: https://{your_server}/DefaultCollection/_admin/_AgentPool
    • TFS 2017: https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
    • TFS 2015: http://{your_server}:8080/tfs/_admin/_AgentPool
    • That didn't work: Get the correct URL
  2. Click the pool that contains the agent.

  3. Make sure the agent is enabled.

  4. Click Agents.

  5. Click Capabilities.

  6. Look for the Agent.Version capability.

    You can check this value against the latest published agent version. See Azure Pipelines Agent and check the page for the highest version number listed.

  7. Each agent automatically updates itself when it runs a task that requires a newer version of the agent. But if you want to manually update some agents, right-click the pool, and then choose Update all agents.

Can I update my v2 agents that are part of an Azure DevOps Server pool?

Yes. Beginning with Azure DevOps Server 2019, you can configure your the server to look for the agent package files on a local disk. This will override the default version that came with the server at the time of its release. This scenario also applies when the server does not have access to the Internet.

  1. From a computer with Internet access, download the latest version of the agent package files (in .zip or .tar.gz form) from the Azure Pipelines Agent GitHub Releases page.

  2. Transfer the downloaded package files to each Azure DevOps Server Application Tier, via a method of your choice (e.g. USB drive, Network transfer). Place the agent files under the %ProgramData%\Microsoft\Azure DevOps\Agents folder.

  3. You're all set! Your Azure DevOps Server will now use the local files whenever the agents need to be updated. Each agent automatically updates itself when it runs a task that requires a newer version of the agent. But if you want to manually update some agents, right-click the pool, and then choose Update all agents.

Why is sudo needed to run the service commands?

./svc.sh uses systemctl, which requires sudo.

Source code: systemd.svc.sh.template on GitHub

I'm running a firewall and my code is in Azure Repos. What URLs does the agent need to communicate with?

If you're running an agent in a secure network behind a firewall, make sure the agent can initiate communication with the following URLs and IP addresses.

For organizations using the *.visualstudio.com domain:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

For organizations using the dev.azure.com domain:

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net

To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com and *dev.azure.com are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the 13.107.6.183 and 13.107.9.183 IP addresses, leave them in place, as you don't need to remove them.

IPv4 ranges

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 ranges

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

How do I run the agent with self-signed certificate?

Run the agent with self-signed certificate

How do I run the agent behind a web proxy?

Run the agent behind a web proxy

How do I configure the agent to bypass a web proxy and connect to Azure Pipelines?

If you want the agent to bypass your proxy and connect to Azure Pipelines directly, then you should configure your web proxy to enable the agent to access the following URLs.

For organizations using the *.visualstudio.com domain:

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

For organizations using the dev.azure.com domain:

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net

To ensure your organization works with any existing firewall or IP restrictions, ensure that dev.azure.com and *dev.azure.com are open and update your allow-listed IPs to include the following IP addresses, based on your IP version. If you're currently allow-listing the 13.107.6.183 and 13.107.9.183 IP addresses, leave them in place, as you don't need to remove them.

IPv4 ranges

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 ranges

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

Note

This procedure enables the agent to bypass a web proxy. Your build pipeline and scripts must still handle bypassing your web proxy for each task and tool you run in your build.

For example, if you are using a NuGet task, you must configure your web proxy to support bypassing the URL for the server that hosts the NuGet feed you're using.

I'm using TFS and the URLs in the sections above don't work for me. Where can I get help?

Web site settings and security

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.