Install and Configure Linux Custom Hives

Linux Custom Hives in Beta

This feature is still in Beta. To join the Beta program, contact your ControlUp representative.

This article explains how to install, configure, and manage a Synthetic Monitoring Custom Hive on a Linux host.

Custom Hives let you run supported Scouts from your own infrastructure.

For more information, see:

Supported Platforms

Linux Custom Hives are available for:

Linux x64
Linux ARM64
Linux hybrid devices with a 64-bit kernel and 32-bit userspace, such as some Raspberry Pi devices
IGEL OS 12 (manual installation only)

Linux x64, ARM64, and hybrid deployments are supported on systemd-based Linux distributions from the Debian and RHEL families, such as Debian, Ubuntu, Raspberry Pi OS, RHEL, AlmaLinux, and Amazon Linux.

Non-GLIBC distributions, such as Alpine Linux, are not supported.

The Linux Custom Hive is not yet available in the IGEL App Portal. For IGEL OS installation requirements, see IGEL OS Installation Requirements.

Supported Scout Types

Linux Custom Hives support all Scout types except the following Windows-native Scouts:

Citrix Desktop for App
Omnissa Horizon native app

To run these Scouts, use a Windows Custom Hive.

Before You Begin

Before you install a Linux Custom Hive, make sure that the host meets the following requirements:

A supported Linux platform.
Root privileges or sudo access.
Outbound HTTPS connectivity to your ControlUp Synthetic Monitoring region.
A Hive key for interactive installation, or a registration token for silent installation.
At least 1.6 GB of storage for installed files and working space, plus an additional 1.6 GB of temporary storage required only during installation. Allow additional space for logs, which grow over time.

IGEL OS Installation Requirements

IGEL OS installation is manual and uses a separate IGEL installation package. Contact your ControlUp representative to receive:

The IGEL installation package (.ipkg)
The intermediate certificate
The leaf certificate
The installation command

Before installing the package, deploy both certificates through IGEL UMS:

Upload the intermediate certificate as a File object.
Set Classification to Undefined.
Set Device file location to:
```
/wfs/cmty/im-certs/
```
Upload the leaf certificate as a File object.
Set Classification to Undefined.
Set Device file location to:
```
/wfs/cmty/certs/
```

Do not use the SSL Certificate or Common certificate classification. These classifications place the certificates under /wfs/ca-certs/, which prevents IGEL app signature verification from working correctly.

After the certificates are deployed, copy the .ipkg package to the IGEL OS endpoint using an approved file-transfer method, such as SCP, and run the installation command provided by ControlUp.

If installation fails with Failed to verify IGEL APP signature, check the system journal for certificate-loading errors such as:

add_key: Required key not available
cmty-apps-load-certs.sh ... could not be loaded

Dependencies

Depending on the host environment and the Scout types you use, the Linux Custom Hive might require additional dependencies. The installer checks for missing dependencies and prompts for approval before installing them.

Component	Purpose	Notes
Xvfb	Provides a virtual X11 display for browser-based Scouts	Required for browser-based Scouts on servers without a physical display or desktop session.
Chromium runtime libraries	Provides the shared libraries required by the bundled browser	Required for browser-based Scouts. Includes libraries such as NSS, GLib, ATK, Cairo, GBM, and ALSA.
`libcap2-bin` / `setcap`	Grants network capabilities to the Scout runner	Required for Ping and Traceroute Scouts.

The installer can install missing dependencies when a supported package manager is available.

Supported package managers include:

apt
dnf
yum
zypper
pacman

Install and Configure a Linux Custom Hive

The following procedure applies to standard Linux x64, ARM64, and hybrid-device installations. For IGEL OS, see IGEL OS Installation Requirements.

To install and register a Linux Custom Hive, download the installer, create the Hive in Synthetic Monitoring, run the installer on the Linux host, and register the Hive with its Hive key.

In Synthetic Monitoring, go to the Hives tab.
Download the Linux Custom Hive installer:
1. Click Download Custom Hive.
2. Select the installer for your Linux host architecture. The installer is downloaded as a .run file:
  - Linux x64
  - Linux ARM64
Create the Custom Hive and its Hive key:
1. Click Add Custom Hive.
2. In the Add Custom Hive window, enter a name for the Custom Hive.
3. Optionally, provide the physical Hive Location. You can pin the location on the map or click Enter manually to enter coordinates.
4. Optionally, under Tags, click Add Tag and select the tags to assign to the Hive. To create tags, go to Settings > Tags Management. To learn more, see Centralized Tags Management.
5. Click Add. A unique Hive key is created.
6. Copy the Hive key. You need it when you configure the Linux Custom Hive.
Locate the downloaded scoutbees-hive-linux-installer.run file. If you downloaded it on another computer, use SCP, SFTP, or your organization's file-transfer tool to copy it to a folder on the Linux machine, such as ~/Downloads.
On the Linux machine, open a terminal and go to the folder that contains the installer. For example:
```
cd ~/Downloads
```

Make the installer executable:

chmod +x scoutbees-hive-linux-installer.run

Run the installer:
```
./scoutbees-hive-linux-installer.run
```
If the installer requires root privileges, it prompts for sudo and relaunches.

If the default temporary directory does not have enough space, set TMPDIR to another existing directory when you run the installer. For example:
```
sudo TMPDIR=/path/to/temporary-directory ./scoutbees-hive-linux-installer.run
```
Replace /path/to/temporary-directory with the path to an existing directory that has sufficient free space.
When prompted, select how to run the installer:
- Text GUI: Interactive terminal UI. This is the default option.
- Text mode: Plain terminal prompts.
Enter the installation directory. The default is /opt/scoutbees-hive.
Select the service account. Keep the default sbhive option unless your environment requires a different account.
Review the installation settings and select install to continue.
When prompted to run Hive configuration (sb-config), select Yes.
Select how to run the Hive configuration tool:
- Text GUI: Interactive terminal UI. This is the default option.
- Text mode: Plain terminal prompts.
Select API Key.
Select the Hive region for your tenant.
Paste the Hive key that you copied from Synthetic Monitoring.
Optionally, configure Enrichment Credentials, Proxy, or Advanced settings.
Select Review & Save.
Review the configuration and save it. The sb-hive service starts automatically.
In Synthetic Monitoring, confirm that the Custom Hive status changes to Connected.

For automated deployments, you can use silent install instead of the interactive installation procedure.

Silent Install

Silent install lets you install and register a Linux Custom Hive from a script without interactive prompts. Use silent install for automated deployments or when you need to deploy Custom Hives across multiple hosts.

Before you run a silent install, create a temporary registration token. For instructions, see Silent Install for Custom Hives.

Run the installer with /VERYSILENT and the registration token:

sudo bash scoutbees-hive-linux-installer.run /VERYSILENT \
  /token="<registration-token>" \
  /name="<hive-name>" \
  /setup_dir=/opt/scoutbees-hive

You can also provide silent-install parameters in a JSON configuration file instead of passing each parameter in the command.

Silent install does the following:

Creates the sbhive service account if it does not exist.
Installs the Linux Custom Hive files in the target directory.
Registers the Custom Hive with Synthetic Monitoring.
Runs a setup validation check.
Enables and starts the sb-hive systemd service.

To view all silent-install parameters and JSON configuration options, run:

sudo bash scoutbees-hive-linux-installer.run /gethelp

Manage a Linux Custom Hive

After the Linux Custom Hive is installed and connected, you can manage the Hive service, review logs, upgrade the Hive, migrate an existing Windows Custom Hive, or uninstall the Hive.

Manage the Linux Custom Hive Service

The Linux Custom Hive runs as a systemd service named sb-hive. Run service-management commands with root privileges or sudo.

Action	Command
Check service status	`sudo systemctl status sb-hive`
Start the service	`sudo systemctl start sb-hive`
Stop the service	`sudo systemctl stop sb-hive`
Restart the service	`sudo systemctl restart sb-hive`

The service is enabled on boot after installation.

View Logs

Use Linux Custom Hive logs to troubleshoot service startup, registration, configuration, and Scout execution issues. Start with the log source that matches the issue you are investigating.

Log Source	Location or Command	Use For
systemd journal	`sudo journalctl -u sb-hive`	Service start, stop, failure, crash, and other system-level events affecting the Hive service.
Hive service log	`/opt/scoutbees-hive/logs/hive-service.log`	Hive registration, setup checks, Scout scheduling, and service messages.
Configuration log	`/opt/scoutbees-hive/logs/config.log`	Configuration changes and `sb-config` errors.
Scout worker logs	`/opt/scoutbees-hive/logs/runner-*.log`	Individual Scout run details.

To follow Hive service events:

sudo journalctl -u sb-hive -f

To view recent Hive service messages:

sudo tail -n 100 /opt/scoutbees-hive/logs/hive-service.log

To view recent configuration messages:

sudo tail -n 100 /opt/scoutbees-hive/logs/config.log

To list Scout worker logs:

sudo ls -lt /opt/scoutbees-hive/logs/

Upgrade a Linux Custom Hive

Upgrade a Linux Custom Hive by running the latest Linux installer on the host where the Hive is installed. The installer detects the existing installation, preserves the local database file, updates the Hive binaries and certificates, and restarts the service automatically.

In Synthetic Monitoring, confirm that the Custom Hive reconnects and that Scouts continue to run as expected.

Migrate a Windows Custom Hive to Linux

You can migrate an existing Windows Custom Hive to Linux by copying the ls.db database file from the Windows installation to the Linux installation. This keeps the same Hive identity and configuration.

Do not run the Windows Custom Hive and Linux Custom Hive with the same Hive identity at the same time. If two Hives use the same identity, the backend disconnects the previous one.

Stop the Windows Custom Hive service on the source machine.
Install the Linux Custom Hive on the target host.
Stop the Linux Custom Hive service:
```
sudo systemctl stop sb-hive
```
Copy ls.db from the Windows installation folder to the Linux installation directory, replacing the default file.

Typical source location on Windows:
```
C:\Program Files\Scoutbees Custom Hive\ls.db
```
Default target location on Linux:
```
/opt/scoutbees-hive/ls.db
```
Set ownership and permissions for the Linux service account:
```
sudo chown sbhive:sbhive /opt/scoutbees-hive/ls.db
sudo chmod 644 /opt/scoutbees-hive/ls.db
```
If you configured a different service account during installation, use that account instead of sbhive.
If you copied additional files into the installation directory, update ownership for the full directory:
```
sudo chown -R sbhive:sbhive /opt/scoutbees-hive
```
Start the Linux Custom Hive service:
```
sudo systemctl start sb-hive
```
In Synthetic Monitoring, confirm that the Custom Hive appears correctly and that Scouts run as expected.

Uninstall a Linux Custom Hive

Uninstall the Linux Custom Hive when you no longer want the host to run Scouts. The uninstaller removes the systemd unit and installation files, including local logs.

To uninstall a Linux Custom Hive, run the uninstaller from the installation directory:

sudo bash /opt/scoutbees-hive/scoutbees-hive-linux-uninstaller.sh

To run the uninstaller without interactive prompts:

sudo bash /opt/scoutbees-hive/scoutbees-hive-linux-uninstaller.sh --yes

Documentation Index