# Linux Username Migration Guide for Linux Collector v1.82

### 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:

```bash
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`:

```bash
sudo systemctl edit observiq-otel-collector
```

Replace the existing content with:

```ini
[Service]
User=bdot
```

{% hint style="info" %}
**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.
{% endhint %}

#### Step 2: Reload Systemd Configuration

After updating the override file, reload the systemd configuration:

```bash
sudo systemctl daemon-reload
```

{% hint style="warning" %}
**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.
{% endhint %}

#### Step 3: Upgrade the Collector Package

Upgrade the collector package using your preferred method:

**Using the install script:**

```bash
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):**

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

**Using package manager (RHEL/CentOS):**

```bash
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:

```bash
sudo systemctl restart observiq-otel-collector
```

### Verification

#### Check User Migration

Verify that the user has been successfully migrated:

```bash
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:

```bash
sudo systemctl status observiq-otel-collector
```

#### Check Process User

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

```bash
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:**

   ```bash
   id bdot
   ```
2. **Check service logs:**

   ```bash
   journalctl -u observiq-otel-collector -f
   ```
3. **Verify systemd override:**

   ```bash
   sudo systemctl cat observiq-otel-collector
   ```
4. **Check file permissions:** Ensure the `bdot` user has access to the collector configuration and data directories:

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

#### Rollback (if necessary)

If you need to rollback the migration:

1. **Stop the service:**

   ```bash
   sudo systemctl stop observiq-otel-collector
   ```
2. **Revert the systemd override:**

   ```bash
   sudo systemctl edit observiq-otel-collector
   ```

   Replace the content with:

   ```ini
   [Service]
   User=observiq-otel-collector
   ```

   Then reload systemd:

   ```bash
   sudo systemctl daemon-reload
   ```
3. **Revert the user migration (if possible):**

   ```bash
   sudo usermod -l observiq-otel-collector bdot
   sudo groupmod -n observiq-otel-collector bdot
   ```
4. **Restart the service:**

   ```bash
   sudo systemctl restart observiq-otel-collector
   ```

{% hint style="info" %}
**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.
{% endhint %}