Installing Collector on Linux

Before starting, review the Realm Collector overview 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

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

lsblk

b. Format the volume (skip if already formatted)

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

c. Get the UUID and filesystem type

sudo blkid /dev/<YOUR-DEVICE>

d. Create the systemd mount unit

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

e. Copy the contents below into your new file

[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

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)

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:

sudo restorecon -v /usr/local/bin/realm-collector

Step 4. Verify the binary was copied correctly

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

Step 5. Login as the realm user

sudo su - realm

Step 6. Configure collector

Bootstrap the collector with the install token Standard:

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

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

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

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

/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

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

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:

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

[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

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

4. Verify the service is running

systemctl status realm-collector

sudo systemctl show -pUser,UID realm-collector

Note: If you are running on Oracle SELinux, see the troubleshooting section 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)

sudo ufw allow <PORT>

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

systemctl status firewalld

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

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.

# 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

sudo systemctl stop realm-collector

2. Set up the storage volume by completing step 2 above (substeps a-f)

3. Move existing data to the new mount

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

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

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)

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:

sudo restorecon -v /usr/local/bin/realm-collector

2. Restart the systemd service

systemctl restart realm-collector

3. Verify the service is up and running

systemctl status realm-collector

Troubleshooting

View OTel config

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

View collector logs

journalctl -u realm-collector | less

Export collector logs to a file

journalctl -u realm-collector > collector.log

Error starting the collector service

On Oracle linux, if you see the following error starting collector service,

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

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.

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

Restart the collector service to trigger the policy violations.

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

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

sudo systemctl stop realm-collector

3. Delete collector binary and cleanup state

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