---
title: "Insights On-Premises Linux-Based Installation"
slug: "insights-on-premises-linux-based-installation"
tags: ["ControlUp for VDI"]
updated: 2026-09-06T08:11:52Z
published: 2026-09-06T08:11:52Z
canonical: "support.controlup.com/insights-on-premises-linux-based-installation"
---

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

# Insights On-Premises Linux-Based Installation

The following article walks you through the installation of the Linux-based deployment of Insights On-Premises (IOP). This installation type provides an alternative to the [OVA-based deployment](/on-premises/docs/insights-on-premises-virtual-appliance-installation-version-86), which requires a dedicated vCenter machine. The advantage of the Linux-based deployment is that you can choose any [supported Linux distribution](/on-premises/docs/insights-on-premises-linux-based-installation-version-86#supported-operating-systems) and run the installation from the CLI.

Upgrades and New Installations Unsupported

Upgrades and new installations of IOP for Linux are not currently supported or provided. The latest available release for Linux is IOP **8.8 MR2** (released March 2025).

## Installation Files

Contact our support team at [support@controlup.com](mailto:support@controlup.com) to receive the latest on-premises installation files and guidance through the installation.

## Prerequisites

Verify that your Linux machine meets the [general IOP prerequisites](/docs/insights-on-premises-prerequisites).

- The Linux `/var` directory must have at least 25 GB available.
- The Docker Engine must be installed and running properly.

### Supported Operating Systems

- Photon OS 5.0
- Ubuntu 22.04.1. Note that this is the final Linux that IOP will deploy.

### Installed Software on the Linux machine

- Docker 20.10.14 or later

To check the Docker version installed, run the following command prompt:

```
sudo docker info
```

If missing, install the required Docker version:

```
sudo apt install docker.io
```

## Installation

Throughout the following section, we walk you through the installation of both [standalone](/on-premises/docs/insights-on-premises-linux-based-installation-version-86#standalone-machine) and [clustered](/on-premises/docs/insights-on-premises-linux-based-installation-version-86#iop-cluster) IOP servers. Before you install the IOP server, you must decide which mode to install:

- For small environments with fewer than 5,000 sessions, we recommend a standalone installation.
- For environments with more than 5,000 sessions, we recommend a clustered IOP infrastructure.

Follow the installation instructions according to your preferred deployment mode.

Version 8.9 MR3

The Linux-based deployment of IOP supports data migration **only** from IOP versions 8.7 or 8.8 to **8.9**. To perform the migration, follow the steps [here](/v1/docs/insights-on-premises-upgrade#migrate-data-to-iop-89).

### IOP CMD Tool

You must deploy the IOP CMD tool on every machine:

1. Download the ***iopcmd-8.x.[xxx.xx].tgz*** archived file to your local folder.
2. Move the ***.tgz*** file to the **/opt** folder in the target **Linux** machine. Note that for the **clustered** installation, you must deploy the IOP CMD tool on the **master** machine.
3. From the **/opt** folder, extract the content of the ***.tgz*** archive file. A new **IOP CMD** folder is created with files inside it.
4. To extract the IOP CMD tool files, run the following command prompt:

```
sudo tar zxvf /opt/iopcmd-8.9.1.1003.88.tgz -C /opt/
```

1. Grant the execution permission:

```
sudo chmod 755 /opt/iopcmd && sudo chmod 644 /opt/iopcmd/iopcmd.conf && sudo chmod 755 /opt/iopcmd/iopcmd
```

1. Run the IOP CMD tool:

```
sudo /opt/iopcmd/iopcmd
```

If you receive the following help text, the tool was installed correctly:

```
usage: iopcmd [-h] [-v] [--debug] {install,upgrade,update,start,stop,restart,clean,show,run,set,test} ...
iopcmd <command> arguments
positional arguments:
  {install,upgrade,update,start,stop,restart,clean,show,run,set,test}
...
```

1. Remove the archive file:

```
sudo rm /opt/iopcmd-8.x.[xxx.xx].tgz
```

### IOP Images

You must deploy the IOP Docker Images on every machine:

- If your target machine has internet access, you can download the images from the ControlUp Docker Hub storage.
- If your target machine doesn’t have internet access, use the ControlUp images in the ***iop_8.x_images.tgz*** archive file.

### Standalone Machine

1. Deploy IOP Docker images:

- If the machine has internet access, extract the IOP Docker images from the ControlUp Docker Hub:

```
 sudo /opt/iopcmd/iopcmd update repo -iopv stable --force
```

- If the machine doesn’t have internet access:
  1. Download the ***iop_8.x_images.tgz*** archive file.
  2. Move the ***.tgz*** file to to the **/opt/** folder in the target Linux machine.
  3. Load the IOP Docker images from the archive file:

```
sudo docker load -i /opt/iop_8.x_images_stable.tgz
```

1. Verify that the IOP Docker images are installed in the system:

```
sudo docker images
```

1. To install the IOP standalone machine, provide a strong Splunk admin password:

```
sudo /opt/iopcmd/iopcmd install local -t standalone -pwd <SplunkAdminPassword>
```

1. Check the IOP running status:

```
sudo docker ps
```

If the "iop_search" Docker container doesn't start after several minutes, see [here](/v1/docs/insights-on-premises-linux-based-installation#known-issue). 5. Monitor the IOP components running status:

```
sudo /opt/iopcmd/iopcmd show -all
```

1. Clean the archive file:

```
sudo rm /opt/iop_8.x_images_stable.tgz
```

### IOP Cluster

There are 2 types of machines in the IOP clustered mode installation:

- Master node machine
- Data node machine

An IOP cluster consists of one master node and at least two data nodes. Install the master node first, and then each data node sequentially.

#### Install the Master Node

1. Perform steps 1-3 for the standalone machine [above](/v1/docs/insights-on-premises-linux-based-installation#standalone-machine). In step 3, use the following command to create, configure, and start the IOP Docker containers:

```
sudo /opt/iopcmd/iopcmd install local -t master -pwd <Splunk admin password>
```

1. Perform steps 4-5 for the standalone machine above.
2. Save the IP address of the master node machine for the following installation of the data node machines.

#### 2. Install the Data Nodes

1. Perform steps 1-3 for the standalone machine [above](/v1/docs/insights-on-premises-linux-based-installation#standalone-machine). In step 3, use the following command to create, configure, and start the IOP Docker containers:

```
sudo /opt/iopcmd/iopcmd install local --password <Splunk admin password> --type data --master <IP address of the master node>
```

1. Perform steps 4-5 for the standalone machine above.

## Known Issue

### “File not found … splunk.version“

If the “iop_search“ Docker container doesn't start after several minutes, check the container logs by running the following command:

```
sudo docker logs iop_search
```

If you see *“File not found … splunk.version“* errors, run the following commands to fix:

```
# Stop the iop_search container
sudo docker stop iop_search
# Fix permissions for the Splunk config folder
sudo find /opt/iop_volumes/config/ -type d -exec chmod 755 {} \;
# Fix permissions for the Splunk config files
sudo find /opt/iop_volumes/config/ -type f -exec chmod 644 {} \;
# Start the iop_search container
sudo docker start iop_search
# Check the running status of the container
#  (It takes a few minutes to change the status from "starting")
sudo docker ps
```