---
title: "Insights On-Premises Linux-Based Installation"
slug: "insights-on-premises-linux-based-installation"
updated: 2026-04-05T12:34:43Z
published: 2026-04-05T12:34:43Z
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.

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