--- title: "Install and Configure Linux Custom Hives" slug: "linux-custom-hives" updated: 2026-09-17T17:25:31Z published: 2026-09-17T17:25:31Z canonical: "support.controlup.com/linux-custom-hives" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.controlup.com/llms.txt > Use this file to discover all available pages before exploring further. # 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: - [Custom Hive Overview](https://support.controlup.com/docs/custom-hive-overview) - [Install and Configure Windows Custom Hives](https://support.controlup.com/docs/installing-custom-hives) ## 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](/docs/linux-custom-hives#igel-os-installation-requirements). ## Supported Scout Types Linux Custom Hives support the following Scout types: | Scout Type | Support on Linux | | --- | --- | | Citrix EUC | Supported using the HTML5 web client | | Omnissa Horizon EUC | Supported using the HTML5 web client | | Azure Virtual Desktop (AVD) | Supported using the HTML5 web client | | All other Scout types | Supported | AVD Scouts support only the HTML5 web client on all Hive platforms. Tests using the native Citrix Workspace app or Omnissa Horizon Client are not supported on Linux Custom Hives. This restriction also applies to the Linux versions of these clients. To test using native clients, use their Windows versions on a [Windows Custom Hive](https://support.controlup.com/docs/installing-custom-hives). ## 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: 1. Upload the intermediate certificate as a **File** object. 2. Set **Classification** to **Undefined**. 3. Set **Device file location** to: ``` /wfs/cmty/im-certs/ ``` 4. Upload the leaf certificate as a **File** object. 5. Set **Classification** to **Undefined**. 6. 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 Linux Custom Hives are currently available in Beta. The following procedure applies to Linux x64, Linux ARM64, and Linux hybrid-device installations. For IGEL OS, see [IGEL OS Installation Requirements](/docs/linux-custom-hives#igel-os-installation-requirements). 1. Go to **Synthetic Monitoring** > **Hives**. 2. Click **Download Custom Hive** and select the installer for your host architecture: - **Linux x64** - **Linux ARM64**. Select this option for Linux ARM64 and supported Linux hybrid devices. 3. 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](/v1/docs/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. 4. 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`. 5. On the Linux machine, open a terminal and go to the folder that contains the installer. For example: ``` cd ~/Downloads ``` 6. Make the installer executable: ``` chmod +x scoutbees-hive-linux-installer.run ``` 7. 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. 8. When prompted, select how to run the installer: - **Text GUI**: Interactive terminal UI. This is the default option. - **Text mode**: Plain terminal prompts. 9. Enter the installation directory. The default is `/opt/scoutbees-hive`. 10. Select the service account. Keep the default `sbhive` option unless your environment requires a different account. 11. Review the installation settings and select `install` to continue. 12. When prompted to run Hive configuration (`sb-config`), select **Yes**. 13. Select how to run the Hive configuration tool: - **Text GUI**: Interactive terminal UI. This is the default option. - **Text mode**: Plain terminal prompts. 14. Select **API Key**. 15. Select the Hive region for your tenant. 16. Paste the Hive key that you copied from Synthetic Monitoring. 17. Optionally, configure **Enrichment Credentials**, **Proxy**, or **Advanced** settings. 18. Select **Review & Save**. 19. Review the configuration and save it. The `sb-hive` service starts automatically. 20. 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](/v1/docs/silent-install-for-synthetic-monitoring-custom-hives). Run the installer with `/VERYSILENT` and the registration token: ``` sudo bash scoutbees-hive-linux-installer.run /VERYSILENT \ /token="" \ /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: 1. Creates the `sbhive` service account if it does not exist. 2. Installs the Linux Custom Hive files in the target directory. 3. Registers the Custom Hive with Synthetic Monitoring. 4. Runs a setup validation check. 5. 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. 1. Stop the Windows Custom Hive service on the source machine. 2. Install the Linux Custom Hive on the target host. 3. Stop the Linux Custom Hive service: ``` sudo systemctl stop sb-hive ``` 4. 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 ``` 5. 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`. 6. If you copied additional files into the installation directory, update ownership for the full directory: ``` sudo chown -R sbhive:sbhive /opt/scoutbees-hive ``` 7. Start the Linux Custom Hive service: ``` sudo systemctl start sb-hive ``` 8. 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 ```