Installing and updating Yandex Unified Agent

Unified Agent is distributed as a deb package for Ubuntu 16.04 or higher and Debian 9 or higher. The package contains a binary file with the agent and a configuration file located at /etc/yandex/unified_agent/config.yml.

To install Unified Agent:

1. Download the latest deb package version:

   ubuntu_name="<OS_version>" \
   ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
   bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/${ua_version}/deb/${ubuntu_name}/yandex-unified-agent_${ua_version}_amd64.deb'
   

   Where ubuntu_name is the operating system version:

   • ubuntu-16.04-xenial
   • ubuntu-18.04-bionic
   • ubuntu-20.04-focal
   • ubuntu-22.04-jammy (starting with 23.03.02)
   • ubuntu-24.04-noble

   Note

   When installing Unified Agent on Debian 9, only deb packages for ubuntu-16.04-xenial and lower are supported; on Debian 10, only packages for ubuntu-18.04-bionic and lower are supported.

   You can also download a specific Unified Agent version. Do it by looking up the available versions and specifying the one you need instead of latest-version:

   curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions
   

2. Check the downloaded deb package version using the ls command.

   Result:

   yandex-unified-agent_<version>_amd64.deb
   

   Where <version> is the downloaded deb package version, e.g., 24.12.01.

3. To install the downloaded deb package, run this command:

   sudo dpkg -i yandex-unified-agent_<version>_amd64.deb
   

4. To make sure Unified Agent is successfully installed and started, run this command:

   systemctl status unified-agent
   

   Result:

   ● unified-agent.service - Yandex Unified Agent service
        Loaded: loaded (/lib/systemd/system/unified-agent.service; enabled; vendor preset: enabled)
        Active: active (running) since Wed 2025-10-01 08:49:44 UTC; 27min ago
      Main PID: 1106 (unified_agent)
         Tasks: 8 (limit: 2308)
        Memory: 5.2M
           CPU: 136ms
        CGroup: /system.slice/unified-agent.service
                └─1106 /usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml --log-priority NOTICE
   

The Unified Agent installation involves the following steps:

• Installing the unified_agent executable.

• Installing the main configuration file. The configuration file is set up to send basic VM metrics and agent health metrics. You will be charged for metric delivery.

  You can also configure the delivery of custom metrics or logs to Cloud Logging.

• Configuring the initialization system and adding the new unified-agent service. This service runs at system startup.

• Creating the unified_agent user with uid 1515 and a group with the same name and gid 1515.

  If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid.

• Creating and configuring access to the /etc/yandex/unified_agent/conf.d custom configuration directory.

• Creating and configuring access to the /var/lib/yandex/unified_agent custom storage directory.

Unified Agent is distributed as a binary file built for the x86-64/amd64 architecture for Ubuntu 16.04 or higher.

To download the latest version of the agent's binary file, run:

ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'

You can install Unified Agent when creating a VM through the management console, CLI, API, or Terraform.

To install the agent from the management console, enable Monitoring under Agent for delivering metrics.

To install the agent via the CLI, API, or Terraform, provide the following string in the user metadata (user-data):

#cloud-config\nruncmd:\n  - wget -O - https://monitoring.api.cloud.yandex.net/monitoring/v2/unifiedAgent/config/install.sh | bash

To install the agent and send metrics, make sure the VM has access to the internet.

The Unified Agent installation involves the following steps:

• Installing the unified_agent executable.

• Installing the main configuration file. The configuration file is set up to send basic VM metrics and agent health metrics. You will be charged for metric delivery.

  You can also configure the delivery of custom metrics or logs to Cloud Logging.

• Configuring the initialization system and adding the new unified-agent service. This service runs at system startup.

• Creating the unified_agent user with uid 1515 and a group with the same name and gid 1515.

  If these uid and gid are not available (already in use), the user and group are created without explicitly specifying any uid and gid.

• Creating and configuring access to the /etc/yandex/unified_agent/conf.d custom configuration directory.

• Creating and configuring access to the /var/lib/yandex/unified_agent custom storage directory.

Once the VM is deployed, Unified Agent will be started automatically and begin delivering basic VM metrics to Yandex Monitoring.

Update the agent manually via a binary file.

Re-download and install the latest deb package.

1. Delete the existing agent binary file.

2. Download the latest version of the agent as a binary file:

   ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
   bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'
   

3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

4. Move the downloaded file to the /bin/unified_agent folder.

5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions

1. Delete the existing agent binary file.

2. Download the latest version of the agent as a binary file:

   ua_version=$(curl --silent https://storage.yandexcloud.net/yc-unified-agent/latest-version) \
   bash -c 'curl --silent --remote-name https://storage.yandexcloud.net/yc-unified-agent/releases/$ua_version/unified_agent && chmod +x ./unified_agent'
   

3. Once you have downloaded the agent executable, create a configuration file, e.g., with settings for delivering Linux system metrics. For more information on agent configuration, see Configuration.

4. Move the downloaded file to the /bin/unified_agent folder.

5. Restart the agent.

To find out all available versions of the agent, run this command:

curl --silent https://storage.yandexcloud.net/yc-unified-agent/all-versions