---
url: https://docs.realmsec.info/integration/collector-linux.md
---

# Installing Collector on Linux

Before starting, review the [Realm Collector overview](/integration/collector) for VM requirements, the outbound firewall allow-list, and Realm Console setup — you'll need the install token generated there.

> **Optional:** You can configure the collector to store its data on a separately mounted volume when the root volume will not suffice for the collector buffer. Both configuration and buffer data will be stored on this mount. Look for **"Dedicated Storage"** callouts in the steps below.

## Step 1. Create realm user

Create a `realm` user to run the collector service

```shell
sudo adduser realm
```

## Step 2. Setup Dedicated Storage (Optional)

Set up the storage volume. Skip this step if not using dedicated storage.

a. Attach an additional EBS volume (or equivalent) to your VM and identify it

```shell
lsblk
```

b. Format the volume (skip if already formatted)

```shell
sudo mkfs.ext4 /dev/<YOUR-DEVICE>
```

c. Get the UUID and filesystem type

```shell
sudo blkid /dev/<YOUR-DEVICE>
```

d. Create the systemd mount unit

```shell
sudo vim /etc/systemd/system/mnt-rlmcol.mount
```

e. Copy the contents below into your new file

```ini
[Unit]
Description=Mount Realm Collector Volume
After=local-fs.target

[Mount]
What=/dev/disk/by-uuid/<YOUR-UUID-HERE>
Where=/mnt/rlmcol
Type=ext4
Options=defaults,nofail

[Install]
WantedBy=multi-user.target
```

> **Note:** Replace `<YOUR-UUID-HERE>` with your volume's UUID from the previous step. Change `ext4` to your filesystem type if different.

f. Enable, verify the mount, and set ownership

```shell
sudo systemctl daemon-reload && \
sudo systemctl enable --now mnt-rlmcol.mount && \
mount | grep rlmcol && \
sudo chown realm:realm /mnt/rlmcol
```

## Step 3. Download collector binary

Download the latest Realm Collector binary to `/usr/local/bin` (v0.137.0-rlm4)

```shell-vue
curl https://gitlab.com/api/v4/projects/realm-security-public%2Fcollectors/packages/generic/realm-collector/v0.137.0-rlm4/realm-collector-linux-amd64 -o realm-collector && \
chmod 555 realm-collector && \
sudo chown realm:realm realm-collector && \
sudo mv realm-collector /usr/local/bin
```

> **Note:** If you are using SELinux, run the following command after moving the binary:
>
> ```shell
> sudo restorecon -v /usr/local/bin/realm-collector
> ```

## Step 4. Verify the binary was copied correctly

```shell
sudo /usr/local/bin/realm-collector --version
```

## Step 5. Login as the realm user

```shell
sudo su - realm
```

## Step 6. Configure collector

Bootstrap the collector with the install token
**Standard:**

```shell
/usr/local/bin/realm-collector --config realm:<YOUR_TOKEN_HERE>
```

**(Dedicated Storage)** Use this command instead. Skip if not using dedicated storage.

```shell
REALM_STORAGE_PATH=/mnt/rlmcol /usr/local/bin/realm-collector --config realm:<YOUR_TOKEN_HERE>
```

## Step 7. Verify collector output

If the collector install is successful, you should see output like this

```text-vue
Installing Realm Collector v0.137.0-rlm4
Finalizing install with server
Fetching collector configuration
Realm Collector installed successfully
```

## Step 8. Test collector

Test the collector by starting it via CLI

```shell
/usr/local/bin/realm-collector --config realm: --set=service.telemetry.logs.level=DEBUG 2>&1 | tee collector-debug.log
```

If the collector started successfully, you should see a log similar to this along with debug output

```shell
info	service@v0.126.0/service.go:289	Everything is ready. Begin running and processing data.	{"resource": {}}
```

## Step 9. Stop the collector

Stop the collector using ctrl-c and follow the steps below to configure it to run as a service.

## Step 10. Run as a Service

Create a service for the collector (systemd). You must be logged in as **root** or a user with sudo permissions.

> If you are logged in as the realm user, logout and login as root or a user with sudo permissions.

1. Create a systemd service file

```shell
sudo vim /etc/systemd/system/realm-collector.service
```

2. Copy the contents below into your new file

> **Note:** Replace the `User=realm` field with the username of the user the collector service should run as.

**Standard service file:**

```ini
[Unit]
Description=Realm Collector
After=network.target

[Service]
Type=simple
User=realm
ExecStart=/usr/local/bin/realm-collector --config realm:
Restart=always
RestartSec=1
# When healthy, the collector is quiet by design and logs
# very infrequently. Suppression can be helpful to avoid
# overwhelming journald in the event of a misconfigured
# integration causing errors receiving events.
LogRateLimitIntervalSec=1h
LogRateLimitBurst=100
# The following line can be commented out or deleted if
# all collector streams are configured with port > 1024.
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
```

**(Dedicated Storage)** Add these two lines to the service file. Skip if not using dedicated storage.

* In the `[Unit]` section, add: `After=mnt-rlmcol.mount`
* In the `[Service]` section, add: `Environment="REALM_STORAGE_PATH=/mnt/rlmcol"`

Example service file with dedicated storage:

```ini
[Unit]
Description=Realm Collector
After=network.target
After=mnt-rlmcol.mount

[Service]
Type=simple
User=realm
ExecStart=/usr/local/bin/realm-collector --config realm:
Restart=always
RestartSec=1
# When healthy, the collector is quiet by design and logs
# very infrequently. Suppression can be helpful to avoid
# overwhelming journald in the event of a misconfigured
# integration causing errors receiving events.
LogRateLimitIntervalSec=1h
LogRateLimitBurst=100
# The following line can be commented out or deleted if
# all collector streams are configured with port > 1024.
AmbientCapabilities=CAP_NET_BIND_SERVICE
# Dedicated buffer storage mount
Environment="REALM_STORAGE_PATH=/mnt/rlmcol"

[Install]
WantedBy=multi-user.target
```

3. Reload systemd, enable and start the collector service

```shell
sudo systemctl daemon-reload && \
sudo systemctl enable --now realm-collector
```

4. Verify the service is running

```shell
systemctl status realm-collector

sudo systemctl show -pUser,UID realm-collector
```

> **Note:** If you are running on Oracle SELinux, see the [troubleshooting section](#troubleshooting) below.

## Step 11. Update Host Firewall

You will need to open a firewall port for each collector stream.

**Ubuntu** ships with UFW by default, albeit in a disabled state.

`sudo ufw status` -> if `Status: inactive`, no action required. Otherwise:

Allow collector port (replace `<PORT>` with the collector stream port from Realm)

```shell
sudo ufw allow <PORT>
```

**Oracle SE Linux** ships with firewalld.
Check if firewalld is running:

```shell
systemctl status firewalld
```

Find the zone that applies to your network interface. If you don't have a specific zone requirement, use `public`.

```shell
sudo firewall-cmd --get-active-zones
```

Replace `<ZONE>` in the following commands with your zone, then replace `<PORT>` and `<PROTOCOL>` with the collector stream values from Realm.

```shell
# Allow inbound traffic on the collector stream port (persistent)
sudo firewall-cmd --permanent --zone=<ZONE> --add-port=<PORT>/<PROTOCOL>

# Reload firewalld to apply the changes
sudo firewall-cmd --reload

# Verify the rule is active for that zone
sudo firewall-cmd --zone=<ZONE> --list-ports
```

## Migrating to Dedicated Storage

To add dedicated buffer storage to an existing collector installation:

1. Stop the collector

```shell
sudo systemctl stop realm-collector
```

2. Set up the storage volume by completing [step 2](#step-2-setup-dedicated-storage-optional) above (substeps a-f)

3. Move existing data to the new mount

```shell
sudo -u realm bash -c 'mv ~/.local/state/realmsec/* /mnt/rlmcol/'
```

> **Note:** If no data exists yet, skip this step.

4. Update the service file

```shell
sudo vim /etc/systemd/system/realm-collector.service
```

Add these two lines:

* In the `[Unit]` section, add: `After=mnt-rlmcol.mount`
* In the `[Service]` section, add: `Environment="REALM_STORAGE_PATH=/mnt/rlmcol"`

5. Restart the collector

```shell
sudo systemctl daemon-reload && \
sudo systemctl restart realm-collector && \
systemctl status realm-collector
```

## Upgrading

1. Replace the Realm Collector binary in `/usr/local/bin` with the latest version (v0.137.0-rlm4)

```shell-vue
curl https://gitlab.com/api/v4/projects/realm-security-public%2Fcollectors/packages/generic/realm-collector/v0.137.0-rlm4/realm-collector-linux-amd64 -o realm-collector && \
chmod 555 realm-collector && \
sudo chown realm:realm realm-collector && \
sudo mv realm-collector /usr/local/bin
```

> **Note:** If you are using SELinux, run the following command after moving the binary:
>
> ```shell
> sudo restorecon -v /usr/local/bin/realm-collector
> ```

2. Restart the systemd service

```shell
systemctl restart realm-collector
```

3. Verify the service is up and running

```shell
systemctl status realm-collector
```

## Troubleshooting

### View OTel config

```shell
sudo su - realm
cat ~/.local/state/realmsec/otelcol.yaml
```

### View collector logs

```shell
journalctl -u realm-collector | less
```

### Export collector logs to a file

```shell
journalctl -u realm-collector > collector.log
```

### Error starting the collector service

On **Oracle linux**, if you see the following error starting collector service,
![alt text](image-1.png)

```shell
# view audit logs that might be preventing the collector binary from executing
journalctl -b | grep audit
```

![alt text](image.png)
The above audit logs indicates that the SELinux is blocking the binary. We need to add SELinux rule to allow the realm collector binary to execute.

```shell
sudo audit2allow -w -a
yum install policycoreutils-python-utils audit
```

Restart the collector service to trigger the policy violations.

```shell
# this should show several violations from realm-collector - if you see other stuff, STOP!
sudo systemctl restart realm-collector

# list recent audit violations (should be for realm-collector)
sudo audit2allow -w -a
# create a policy file to allow execution of collector binary
sudo audit2allow -a -M realm-collector
# load the new policy
sudo semodule -i realm-collector.pp

# refresh the path in SELinux
restorecon -R -v /usr/local/bin/realm-collector
```

Restart the collector service and check the status.

```shell
sudo systemctl restart realm-collector
sudo systemctl status realm-collector
```

### Uninstall the collector

1. To uninstall the collector, login as the root user
2. Stop the collector service

```shell
sudo systemctl stop realm-collector
```

3. Delete collector binary and cleanup state

```shell
sudo rm /usr/local/bin/realm-collector
sudo rm -r /home/realm/.local/state/realmsec
```