> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/how-to-guides/collector-management/downgrade-collector-privileges.md).

# Downgrade Collector Privileges

By default, the Bindplane OTel Collector runs with full privileges: as the `root` user on Linux, and with admin privileges on Windows. This guide explains how to run the collector with fewer privileges, and how to give it access to the resources it still needs.

### Linux

By default, the `observiq-otel-collector` service runs as the `root` user. Some sources need root, for example to read log files owned by other users, collect per-process host metrics, bind to ports below 1024, or capture packets.

Collectors that don't need access to host resources, such as gateways that receive OTLP on port 4317, are good candidates for running as non-root.

On Linux, the `observiq-otel-collector` service runs as the user chosen when the collector is first installed. The user is set with the [package configuration file](https://docs.bindplane.com/configuration/bindplane-otel-collector/linux-package-configuration.md): the collector runs as `root` by default, or as the `bdot` user when `BDOT_UNPRIVILEGED=true` is set. The user can't be changed on an installed collector. To switch, uninstall the collector and install it again.

{% hint style="info" %}
**Upgrades from Bindplane**

Upgrades from Bindplane work for non-root collectors running v1.113.0 or later, on systemd hosts with `sudo` installed. A non-root collector running an earlier version must first be upgraded to v1.113.0 or later with the Linux package, or by re-running the install script with `sudo`, setting `--version` to the target version or omitting it to install the latest. This upgrade writes the sudoers rule that upgrades from Bindplane need. Later upgrades can be made from Bindplane.
{% endhint %}

Running as non-root requires:

* systemd. On hosts without systemd, the collector runs as `root`.
* The `sudo` package, so that the collector can be upgraded from Bindplane.
* Collector v1.113.0 or later, for upgrades from Bindplane.

#### Install a Collector as Non-Root

1. Install the `sudo` package if it isn't installed, for example with `apt-get install sudo` or `dnf install sudo`.
2. Create the package configuration file with `BDOT_UNPRIVILEGED=true`.

   On Debian-based distributions:

   ```bash
   echo 'BDOT_UNPRIVILEGED=true' | sudo tee /etc/default/observiq-otel-collector
   sudo chmod 0644 /etc/default/observiq-otel-collector
   ```

   On RHEL-based distributions:

   ```bash
   echo 'BDOT_UNPRIVILEGED=true' | sudo tee /etc/sysconfig/observiq-otel-collector
   sudo chmod 0644 /etc/sysconfig/observiq-otel-collector
   ```

   To run as a user other than `bdot`, also set `BDOT_USER` and `BDOT_GROUP`. See [Linux Package Configuration](https://docs.bindplane.com/configuration/bindplane-otel-collector/linux-package-configuration.md). Keep this file in place for as long as the collector is installed.
3. Install the collector with the install command from Bindplane. See [Install Your First Collector](https://docs.bindplane.com/readme/install-your-first-collector.md).

**Verifying**

Check that the collector is running as the `bdot` user:

```bash
ps -o user=,pid=,cmd= -C observiq-otel-collector
```

Check that the package wrote the sudoers rule that lets the collector be upgraded from Bindplane:

```bash
sudo -l -U bdot
```

The output lists `systemctl start observiq-otel-collector.service` and `systemctl stop observiq-otel-collector.service`.

#### Switch an Existing Collector to or from Non-Root

Once the collector is installed, the user it runs as can't be changed. As of collector v1.113.0, the package refuses an install or upgrade that would change the user, and prints an error that starts with `ERROR: The collector service runs as`.

If you see this error and didn't mean to change the user, set the values the error prints in the package configuration file, and run the install or upgrade again.

To switch between root and non-root, reinstall the collector:

1. Uninstall the collector.
2. Remove any `User=` or `Group=` settings you added to the service's systemd drop-ins.
3. Delete `/opt/observiq-otel-collector`.
4. Write the package configuration file with the new values.
5. Install the collector with the install command from Bindplane.

Reinstalling gives the collector a new agent ID, and deletes its persistent queue data. For the full procedure, see [Switch Between Root and Non-Root](https://docs.bindplane.com/configuration/bindplane-otel-collector/linux-package-configuration.md#switch-between-root-and-non-root).

{% hint style="danger" %}
After uninstalling a non-root collector, always delete `/opt/observiq-otel-collector` before installing again, whichever user the new install runs as. Otherwise the package works as root on files the former runtime user controlled.
{% endhint %}

#### Hand-Written Systemd Overrides (Deprecated)

Earlier versions of this guide ran the collector as non-root with a systemd override written by hand (`sudo systemctl edit observiq-otel-collector`) that set `User=observiq-otel-collector` or `User=bdot`. This is deprecated, and these docs no longer describe how to set it up or maintain it. The package doesn't see a hand-written override, so it doesn't write the sudoers rule, and upgrades from Bindplane fail.

To check whether your collector uses one, read the service's unit and drop-ins:

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

If the output has a `User=` line in a file other than the main unit file and `10-package-customizations-username.conf`, usually `/etc/systemd/system/observiq-otel-collector.service.d/override.conf`, the collector uses a hand-written override.

For new non-root collectors, use `BDOT_UNPRIVILEGED=true` as described in [Install a Collector as Non-Root](#install-a-collector-as-non-root).

#### Grant the Collector Access

A non-root collector can only reach what the runtime user can. Give it access to what it needs without running it as root.

**Log files owned by other users.** Add the runtime user to a group that can read the files, with a systemd drop-in:

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

```ini
[Service]
SupplementaryGroups=adm systemd-journal
```

On Debian-based distributions, the `adm` group can read most files in `/var/log`, and the `systemd-journal` group can read the systemd journal. Restart the collector to apply the change:

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

**Ports below 1024.** Give the service the `CAP_NET_BIND_SERVICE` capability with a drop-in:

```ini
[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
```

Don't use `setcap` on the collector binary. Every upgrade replaces the binary, which clears the capability.

**Packet capture and per-process host metrics.** These need the collector to run as `root`. Use a root install for them.

{% hint style="warning" %}
Drop-ins like these are fine. Never set `User=` or `Group=` in them, and never add settings that turn on `no_new_privs`, such as `NoNewPrivileges=`, because they stop upgrades from Bindplane from working. See [Remote Upgrade Fails on a Non-Root Collector](https://docs.bindplane.com/configuration/bindplane-otel-collector/linux-package-configuration.md#remote-upgrade-fails-on-a-non-root-collector) for the full list.
{% endhint %}

#### Important Considerations

* Ensure the `bdot` user has the necessary permissions to access any required resources
* Some collector components may not function properly without root access
* If you experience issues, check the collector logs for permission-related errors

Common examples of operations that require specific permissions:

* Binding to network ports below 1024 (e.g., syslog on port 514) requires root privileges or the `CAP_NET_BIND_SERVICE` capability
* Reading log files owned by other users requires the collector user to be added to the appropriate group that has read access to those files

#### Troubleshooting

If you encounter permission issues after installing the collector as non-root:

1. Check the collector logs:

   ```bash
   sudo tail -F /opt/observiq-otel-collector/log/collector.log
   journalctl -u observiq-otel-collector
   ```
2. Verify the user has access to required directories and files. See [Grant the Collector Access](#grant-the-collector-access).
3. If upgrades from Bindplane fail, see [Remote Upgrade Fails on a Non-Root Collector](https://docs.bindplane.com/configuration/bindplane-otel-collector/linux-package-configuration.md#remote-upgrade-fails-on-a-non-root-collector).
4. If the collector needs root, reinstall it as root by following [Switch an Existing Collector to or from Non-Root](#switch-an-existing-collector-to-or-from-non-root).

### Windows

By default, the `observIQ Distro for OpenTelemetry Collector` service runs with admin privileges. Some OpenTelemetry components require elevated permissions to read certain logs and metrics.

To run the collector as a less privileged user:

1. Create a dedicated service account with the minimum required permissions
2. Open the Windows Services console (services.msc)
3. Find and right-click on the `observIQ Distro for OpenTelemetry Collector` service
4. Select "Properties"
5. Go to the "Log On" tab
6. Select "This account"
7. Enter the service account credentials
8. Click "Apply" and "OK"
9. Restart the service

#### Verifying

Check that the collector is running as the new user:

```powershell
Get-WmiObject Win32_Service -Filter "Name='observIQ Distro for OpenTelemetry Collector'" | Select-Object Name, StartName
```

#### Important Considerations

* Ensure the service account has the necessary permissions to access any required resources
* Some collector components may not function properly without admin privileges
* The service account should be a member of the `Event Log Readers` group if collecting Windows Events
* If collecting Windows Events remotely, the account needs DCOM and WMI permissions
* If you experience issues, check the Windows Event Logs for permission-related errors

#### Troubleshooting

If you encounter permission issues after downgrading privileges:

1. Check the Windows Event Logs:
   * Open Event Viewer
   * Look under "Windows Logs" > "Application" for collector-related errors
2. Verify the service account has access to required resources:
   * Event Logs
   * Performance Counters
   * Configuration files
   * Network resources
3. If problems persist, you may need to revert to admin privileges:
   * Open Services (services.msc)
   * Find the collector service
   * Set it back to "Local System Account" in the Log On tab
   * Restart the service

### macOS

*Not currently supported*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bindplane.com/how-to-guides/collector-management/downgrade-collector-privileges.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
