Configure a bundled Agent package

The bundled SolarWinds Observability Agent is a unified monitoring package designed to seamlessly integrate with SolarWinds Observability SaaS. It is specifically designed for environments with restricted internet access. It contains all necessary components for host and database monitoring, including:

SolarWinds Observability Agent: Sends collected telemetry data to SolarWinds Observability SaaS and manages the agent's lifecycle.
OpenTelemetry Collector (OTel) for standardized metrics and logs collection: Gathers metrics using the standardized OpenTelemetry framework. See Monitor with OTel.
Database Observability plugin for enhanced database performance insights: Provides in-depth performance insights for your databases, including detailed metrics and query-level analysis.

The bundled Agent operates exclusively in locally managed mode. See Run Agent in locally managed mode.

This package is designed for restricted environments and includes all necessary components for host and database monitoring. It does not download plugin binaries from SolarWinds repositories, which are based on TUF (The Update Framework).

See the following for detailed instructions:

Run the bundled Agent

Compatibility notice

You cannot directly switch between the standard Agent and the bundled Agent, as they use different configurations and binaries. See Troubleshooting for more information.

To switch from the standard SolarWinds Observability Agent to the bundled Agent, or from the bundled Agent to the standard Agent, you must first uninstall the currently installed version.

Coexistence or reinstallation without uninstalling an agent may cause service conflicts, telemetry disruption, or data corruption.

Download and install the package

Download the package that matches your system's package manager.

RPM: https://agent-binaries.cloud.solarwinds.com/uams/bundle/latest/uamsclient-bundle.rpm

DEB: https://agent-binaries.cloud.solarwinds.com/uams/bundle/latest/uamsclient-bundle.deb
Select the tab that matches your package / package manager. Install the package using the command for your package / package manager.
- Replace YourApiToken in UAMS_ACCESS_TOKEN with the ingestion token you prepared earlier.
- Replace YourSwoBaseUrl in SWO_URL with the base URL for your organization's endpoints. The base URL is in the form of xx-yy.cloud.solarwinds.com, where xx-yy represents the data center your organization uses. See Find the data center and endpoints for your organization.
RPM / RPM
```
env UAMS_ACCESS_TOKEN="YourApiToken" UAMS_MANAGED_LOCALLY="true" SWO_URL="YourSwoBaseUrl" rpm -i uamsclient-bundle.rpm
```
RPM / YUM
```
env UAMS_ACCESS_TOKEN="YourApiToken" UAMS_MANAGED_LOCALLY="true" SWO_URL="YourSwoBaseUrl" yum localinstall -y uamsclient-bundle.rpm
```
RPM/ DNF
```
env UAMS_ACCESS_TOKEN="YourApiToken" UAMS_MANAGED_LOCALLY="true" SWO_URL="YourSwoBaseUrl" dnf install -y uamsclient-bundle.rpm
```
RPM / ZYPPER
```
env UAMS_ACCESS_TOKEN="YourApiToken" UAMS_MANAGED_LOCALLY="true" SWO_URL="YourSwoBaseUrl" zypper install uamsclient-bundle.rpm
```
DEB / DPKG
```
env UAMS_ACCESS_TOKEN="YourApiToken" UAMS_MANAGED_LOCALLY="true" SWO_URL="YourSwoBaseUrl" dpkg -i uamsclient-bundle.deb
```
The UAMS_MANAGED_LOCALLY=true parameter is required to install the bundled SolarWinds Observability Agent. Otherwise, the following error occurs:

WARNING: When using uamsclient-bundle you must specify UAMS_MANAGED_LOCALLY=true environment variable.

For now, only local configuration is supported. If you see this error, reinstall with UAMS_MANAGED_LOCALLY=true
Prepare a local_config.yaml file. See Run Agent in locally managed mode.

Uninstall the bundled Agent

RPM package:

rpm -e uamsclient-bundle

DEB package:

dpkg --purge uamsclient-bundle

Update the bundled Agent

To update the bundled Agent, download a new package and repeat the installation steps manually. This ensures version consistency across the core agent and its plugins.

Automatic or in-place updates are not supported.

Run the bundled Agent as a Docker image deployment

You can deploy the bundled Agent as a Docker image. See Docker for more information on starting a Docker container in locally managed mode.

Download and run the Docker image

Run the following command to download the docker image.
- Replace <link> with the link to the dockerhub Agent bundle image.
```
docker pull <link>
```
Prepare a local_config.yaml file to run the container. See Run Agent in locally managed mode.
- Replace <client id>with your identity ID.
- Replace <token> with the ingestion token you prepared earlier.
- Replace <xx-yy.cloud.solarwinds.com> with the base URL for your organization's endpoints, where xx-yy represents the data center your organization uses. See Find the data center and endpoints for your organization.
- Replace <custom hostname> with the hostname with the Docker container.
- Replace <link> with the link to the dockerhub Agent bundle image.
```
docker run \
-e UAMS_CLIENT_ID_OVERRIDE=<client id>  \
-e UAMS_ACCESS_TOKEN=<token>  \
-e SWO_URL=<xx-yy.cloud.solarwinds.com> \
-e UAMS_CONTAINER_HOSTNAME=<custom hostname> \
-e UAMS_LOCAL_CONFIGURATION_FILE_PATH=/uamsclient/workdir/local_config.yaml \
-v ./local_config.yaml:/uamsclient/workdir/local_config.yaml:ro \
-d <link>
```
Do not attach the volume to the workdir directory ( -v uams-volume:/uamsclient/workdir).

Using this volume can prevent the latest plugin version from starting correctly, potentially breaking the deployment after the image is updated.

See Install SolarWinds Observability Agent as a Docker image for more information.

Use credentials in docker containers

Information for how to configure credentials providers are described in Locally managed mode credential providers.

The following is an example of the credentials_config.yaml file with the password stored in an environment variable.

Replace <client id>with your identity ID.
Replace <token> with the ingestion token you prepared earlier.
Replace <xx-yy.cloud.solarwinds.com> with the base URL for your organization's endpoints, where xx-yy represents the data center your organization uses. See Find the data center and endpoints for your organization.
Replace <custom hostname> with the hostname with the Docker container.
Replace <link> with the link to the dockerhub Agent bundle image.

docker run \
-e UAMS_CLIENT_ID_OVERRIDE=<client id> \
-e UAMS_ACCESS_TOKEN=<token>  \
-e SWO_URL=<xx-yy.cloud.solarwinds.com>
-e UAMS_CONTAINER_HOSTNAME=<custom hostname> \
-e UAMS_LOCAL_CONFIGURATION_FILE_PATH=/uamsclient/workdir/local_config.yaml \
-e UAMS_CREDENTIALS_CONFIGURATION_FILE_PATH=/uamsclient/workdir/credentials_config.yaml \
-e MYSQL_PASSWORD_ENV="mypassword" \
-v ./local_config.yaml:/uamsclient/workdir/local_config.yaml:ro \
-v ./my_passwords.yaml:/uamsclient/workdir/my_passwords.yaml:ro \
-v ./credentials_config.yaml:/uamsclient/workdir/credentials_config.yaml:ro \
-d <link>

Persist logs

To save agent logs outside the container, mount a local directory to /var/log/solarwinds/uamsclient.

Replace <client id>with your identity ID.
Replace <token> with the ingestion token you prepared earlier.
Replace <xx-yy.cloud.solarwinds.com> with the base URL for your organization's endpoints, where xx-yy represents the data center your organization uses. See Find the data center and endpoints for your organization.
Replace <custom hostname> with the hostname with the Docker container.
Replace <link> with the link to the dockerhub Agent bundle image.

docker run \
  -e UAMS_CLIENT_ID_OVERRIDE=<client id> \
  -e UAMS_ACCESS_TOKEN=<token> \
  -e SWO_URL=<xx-yy.cloud.solarwinds.com> \
  -e UAMS_CONTAINER_HOSTNAME=<custom hostname> \
  -e UAMS_LOCAL_CONFIGURATION_FILE_PATH=/uamsclient/workdir/local_config.yaml \
  -v ${PWD}/uamsclient:/var/log/solarwinds/uamsclient \
  -v ./local_config.yaml:/uamsclient/workdir/local_config.yaml:ro \
  -d <link>

Replace ${PWD} with the global path to your local directory where you want save the logs from the container.

Use docker-compose

To run the bundled agent container using docker-compose, use the following compose.yaml file:

Start the agent container by running docker compose up.

Replace <link> with the link to the dockerhub Agent bundle image.
Replace <client id>with your identity ID.
Replace <token> with the ingestion token you prepared earlier.
Replace <xx-yy.cloud.solarwinds.com> with the base URL for your organization's endpoints, where xx-yy represents the data center your organization uses. See Find the data center and endpoints for your organization.
Replace <custom hostname> with the hostname with the Docker container.
Replace <mypassword> with the password stored in an environmental variable. See Locally managed mode credential providers for more information.

services: 
uams-uamsclient-bundle:
    image: <link>
    environment:
      UAMS_CLIENT_ID_OVERRIDE: <client id>
      UAMS_ACCESS_TOKEN: <token>
      SWO_URL: <xx-yy.cloud.solarwinds.com>
      UAMS_CONTAINER_HOSTNAME: <custom hostname>
      UAMS_LOCAL_CONFIGURATION_FILE_PATH: /uamsclient/workdir/local_config.yaml
      MYSQL_PASSWORD_ENV: <mypassword>
    ports:
      - "2114:2113"
    volumes:
      - ./local_config.yaml:/uamsclient/workdir/local_config.yaml:ro
      - ./my_passwords.yaml:/uamsclient/workdir/my_passwords.yaml:ro
      - ./credentials_config.yaml:/uamsclient/workdir/credentials_config.yaml:ro

Troubleshooting

Installation issues

The bundled SolarWinds Observability Agent conflicts with the standard SolarWinds Observability Agent.

Issue: The standard SolarWinds Observability Agent is installed and you try to install the bundled SolarWinds Observability Agent. You receive the following error:

uamsclient-bundle conflicts with uamsclient uamsclient (version 2.10.226-0) is present and installed.

Resolution: Uninstall the package you previously installed. See Delete Agents for more information.

Issue: The bundled SolarWinds Observability Agent is installed and you try to install the standard SolarWinds Observability Agent. You receive the following error:

uamsclient conflicts with uamsclient-bundle uamsclient-bundle (version 0.0.23-1) is present and installed.

Resolution: Uninstall the package you previously installed. See Uninstall the bundled Agent for more information.

Search SolarWinds Support