Install and activate the Insight Orchestrator

This page walks you through how to install and activate the Insight Orchestrator within InsightConnect. If you use other Rapid7 Insight products and have already installed an orchestrator for any of them, you do not have to install another just for InsightConnect's use. One orchestrator will work across all Insight products, but you can install multiple orchestrators if needed to suit your network topology.

CentOS 7 orchestrator is no longer supported

On June 1, 2024, the CentOS 7 Insight Orchestrator reached end-of-life. As a result, orchestrators using this operating system will no longer receive security updates or patches from CentOS Linux.

To keep your environment secure, it is highly recommended that you install the new Ubuntu orchestrator or migrate to Ubuntu if you have existing CentOS 7 orchestrators in your environment.

Before you begin

  1. Read our system and network requirements and provision a server that meets the production hardware requirements.
  2. Decide which installation method works best for you.

Cross-product installation

If you purchased and have access to InsightConnect, you can obtain the .ova file or installation script from the product itself or with help from a sales or support representative. It is recommended that you get your file or script from the product to ensure you’re starting with the most recent version.

If you purchased any other Insight product, have not directly purchased a license for InsightConnect, but are utilizing the built-in automation features powered by the orchestrator, it’s important that you only download the orchestrator using the in-product links to prevent issues when registering.

Install the orchestrator

To install an orchestrator, navigate to the Orchestrator page in InsightConnect and click Install Orchestrator.

Install Orchestrator

You can install the orchestrator yourself, or email installation instructions straight from InsightConnect to your IT team so they can perform the installation.

Installation Options

If you choose to install the orchestrator yourself, you can do so using an .ova file or using our script-based installer package.

Email installation instructions to your IT team

  1. From the installation choices in the orchestrator tab, choose Send an email to my IT team.
  2. A mailto window will open on your machine with the email body pre-filled with installation instructions and download links.
  3. Add your IT team's email addresses, then send the email.

Do not join the Insight Orchestrator to Active Directory

The Orchestrator relies on built-in user accounts to facilitate the installation & ongoing execution of important services. Joining the Orchestrator to Active Directory has been observed to cause interference with local user accounts and groups, leading to improper permissions for Orchestrator services. Therefore, it is not considered a supported configuration to join your Orchestrator to Active Directory.

Install the orchestrator yourself

Depending on your operating system, you can install the orchestrator by downloading the .ova file or by using a script-based installer package.

Install the Ubuntu orchestrator

You can install the orchestrator on a machine running Ubuntu 20.04 or 22.04 by downloading the .ova file or by using a script-based installer package.

Looking to migrate a CentOS 7 orchestrator?

If you are setting up an Ubuntu orchestrator to replace an existing CentOS 7 orchestrator, refer to the migration steps to copy over your data.

To install by downloading the .ova file:

  1. From the Orchestrator page in InsightConnect, click Install Orchestrator and select Virtual Appliance Installation. Download the Ubuntu .ova file.
  2. Import the rapid7-orchestrator-latest.ova disk image into the virtual machine (VM) solution of your choice, such as VirtualBox or VMWare.
  3. When the import is complete, boot the machine and log in with the credentials provided:
    • Username: rapid7
    • Password: changeme
  4. When the installation is complete, copy the activation key provided.

Change initial username and password

We recommend you change the password provided to you for initial access to the OS and manage it locally in accordance with your own password management policies.

To install by using a script-based installer package:

Requirements for the Linux shell script installation method

You must provision a new Ubuntu image in alignment with our production hardware requirements to install an orchestrator with a Linux shell script. If you repurpose an existing machine or underprovision disk space, you will get errors later.

All supported methods of running the orchestrator require the presence of Docker Community Edition (CE). When using the script-based installer, the Docker Apt repository and Docker CE engine will be installed on your behalf. No other container engines are supported at this time. More details about this dependency can be found as part of our software requirements.

  1. From the Orchestrator page in InsightConnect, click Install Orchestrator and select Script Installation.
  2. Download the r7-orchestrator-installer.sh file.
  3. Import the .sh file to your Ubuntu machine with secure shell (SSH) by running scp <installer file> <user>@<VM address>:<directory> on your local machine. For example, running scp r7-orchestrator-install.sh <user>@<VM address>:/tmp/ will upload the file to your machine’s /tmp directory.
  4. In your Ubuntu instance, run cd until you are in the directory where you imported the installation file, then change permissions on the installer file by running a command like chmod +x r7-orchestrator-installer.sh.
  5. Run the installer as root with sudo ./<installer file>. For example, if you copied the file to /tmp, typing cd /tmp && sudo ./r7-orchestrator-install.sh will begin the installation.
  6. Follow the instructions provided in the installer to continue. If you require further assistance, run ./<installer> --help to view more information.
  7. The installer will run a network test first to make sure the orchestrator connects properly. If the network test fails, the installation will not run.
  8. When the installation is complete, copy the activation key provided.
Install the RHEL orchestrator

You can install the orchestrator on a machine running RHEL 7 or 8 by using the Linux command line with a script-based installer package.

Requirements for the Linux shell script installation method

You must provision a new RHEL 7 or 8 image in alignment with our production hardware requirements to install an orchestrator with a Linux shell script. If you repurpose an existing machine or underprovision disk space, you will get errors later.

All supported methods of running the orchestrator require the presence of Docker Community Edition (CE). When using the script-based installer, the Docker Yum repository and Docker CE engine will be installed on your behalf. No other container engines are supported at this time. More details about this dependency can be found as part of our software requirements.

  1. From the Orchestrator page in InsightConnect, click Install Orchestrator and select Script Installation. Download the r7-orchestrator-installer.sh file.

Install Orchestrator

  1. Import the .sh file to your RHEL 7 or 8 machine with secure shell (SSH) by running scp <installer file> <user>@<VM address>:<directory> on your local machine. For example, running scp r7-orchestrator-install.sh <user>@<VM address>:/tmp/ will upload the file to your machine’s /tmp directory.
  2. In your RHEL 7 or 8 instance, run cd until you are in the directory where you imported the installation file, then change permissions on the installer file by running a command like chmod +x r7-orchestrator-installer.sh.
  3. Run the installer as root with sudo ./<installer file>. For example, if you copied the file to /tmp, typing cd /tmp && sudo ./r7-orchestrator-install.sh will begin the installation.
  4. Follow the instructions provided in the installer to continue. If you require further assistance, run ./<installer> --help to view more information.
  5. The installer will first run a network test to make sure the orchestrator connects properly. If the network test fails, the installation will not run.
  6. When the installation is complete, copy the activation key provided.

Configure proxies for orchestrator success

The Insight Orchestrator fully supports using proxies in networked environments that mandate them. If your organization uses one, you'll need to configure your proxy in order for your newly installed orchestrators to run properly.

Activate the orchestrator

After you install your orchestrator and log into the OS, you receive several pieces of information, including a large base64 encoded blob of data. That’s your activation key. Copy the activation key and use it to activate the orchestrator.

Activation key troubleshooting

If you didn’t copy the activation key after installing your orchestrator, you can retrieve it by using secure shell (SSH) protocol to access your orchestrator’s VM and print the activation key from there.

If you’re having issues copying and pasting your activation key, you can download the key as a .txt file and copy and paste it from there.

To activate an orchestrator, you'll need to log back into your Insight product. If you don't have access, send the activation key to an Insight product user and have them follow these steps to complete the activation:

  1. Go to Settings > Orchestrator.
  2. Name your orchestrator. Orchestrators in your organization must have unique names. If you try to reuse a name, you will receive an error and won’t be able to activate it.
  3. Paste your activation key into the Key field.
  4. Click Activate Orchestrator.

Activation troubleshooting

If you followed the steps to activate your orchestrator, but your activation key doesn’t seem to be working, take a look at our orchestrator activation troubleshooting information for common scenarios and resolutions.