Linux Username Migration Guide for Linux Collector v1.82

Migrate from observiq-otel-collector user to bdot during collector v1.82 upgrade

Overview

When upgrading to Bindplane OTEL Collector v1.82, the system user observiq-otel-collector will be renamed to bdot. This migration is performed automatically by the package installer using the usermod command.

This guide is for Linux users only. macOS and Windows users do not need to take any action.

This guide is only required if you are running the collector as a non-root user. The Bindplane OTEL Collector runs as root by default. If you have not explicitly configured your collector to run as a non-root user, you can ignore this guide and proceed with the normal upgrade process.

If you previously followed the Downgrade Collector Privileges guide to run the collector as the observiq-otel-collector user, you will need to follow this migration guide.

Prerequisites

Before starting the migration process, verify that you are currently running the collector as the observiq-otel-collector user:

sudo systemctl cat observiq-otel-collector

Look for the User= line in the output. The main unit file will always show User=root, but if you have a systemd override file, you'll see an additional section near the bottom of the output that shows User=observiq-otel-collector. If you see this override with User=observiq-otel-collector, you need to follow this guide. If you only see User=root (no override), you can skip this guide.

Migration Steps

Step 1: Update Systemd Override

If you have a systemd override file that specifies the observiq-otel-collector user, you need to update it to use bdot:

sudo systemctl edit observiq-otel-collector

Replace the existing content with:

[Service]
User=bdot

NOTE

The group is set to observiq-otel-collector in the main unit file, but it will be automatically migrated to bdot by the package upgrade process, so you don't need to specify it in the override.

Step 2: Reload Systemd Configuration

After updating the override file, reload the systemd configuration:

sudo systemctl daemon-reload

IMPORTANT

Do not restart the service at this point. The service should continue running with the current configuration because the user migration has not happened yet. The migration will occur during the package upgrade process.

Step 3: Upgrade the Collector Package

Upgrade the collector package using your preferred method:

Using the install script:

sudo sh -c "$(curl -fsSlL 'https://github.com/observIQ/bindplane-agent/releases/download/v1.82.0/install_unix.sh')" install_unix.sh

Using package manager (Debian/Ubuntu):

sudo apt install -f ./observiq-otel-collector_v1.82.0_linux_amd64.deb

Using package manager (RHEL/CentOS):

sudo yum install ./observiq-otel-collector_v1.82.0_linux_amd64.rpm
# or for newer systems:
sudo dnf install ./observiq-otel-collector_v1.82.0_linux_amd64.rpm

The package upgrade process will:

1. Stop the service before migrating the user

2. Perform the user migration from observiq-otel-collector to bdot

3. Restart the service automatically before the binary upgrade

Step 4: Restart the Service

After the package upgrade completes, restart the service to ensure it picks up the new collector version:

sudo systemctl restart observiq-otel-collector

Verification

Check User Migration

Verify that the user has been successfully migrated:

id bdot

You should see output similar to:

uid=1001(bdot) gid=1001(bdot) groups=1001(bdot)

Check Service Status

Verify that the service is running correctly:

sudo systemctl status observiq-otel-collector

Check Process User

Confirm that the collector process is running as the bdot user:

ps aux | grep observiq-otel-collector

The output should show the process running as the bdot user.

Troubleshooting

Service Fails to Start

If the service fails to start after the migration, check the following:

1. Verify user exists:

   id bdot

2. Check service logs:

   journalctl -u observiq-otel-collector -f

3. Verify systemd override:

   sudo systemctl cat observiq-otel-collector

4. Check file permissions: Ensure the bdot user has access to the collector configuration and data directories:

   ls -la /opt/observiq-otel-collector/

Rollback (if necessary)

If you need to rollback the migration:

1. Stop the service:

   sudo systemctl stop observiq-otel-collector

2. Revert the systemd override:

   sudo systemctl edit observiq-otel-collector

   Replace the content with:

   [Service]
   User=observiq-otel-collector

   Then reload systemd:

   sudo systemctl daemon-reload

3. Revert the user migration (if possible):

   sudo usermod -l observiq-otel-collector bdot
   sudo groupmod -n observiq-otel-collector bdot

4. Restart the service:

   sudo systemctl restart observiq-otel-collector

NOTE

This rollback only reverts the systemd configuration. The collector will still be running version v1.82. If you encountered issues during the migration process, contact support for assistance. The next package upgrade will attempt the same user migration again.