Install and Activate the Ochestrator

This page will walk 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.

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:
  3. Log in to your Insight Platform account and open InsightConnect.
  4. To find the orchestrator installer, open the dropdown menu under the Settings tab and click Orchestrators. Then click Install Orchestrator.

Linux shell script installation method requirements

You must provision a new CentOS 7 or a RHEL 7/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 CE (Community Edition). 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.

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. We recommend 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

From the Orchestrator page in InsightConnect, 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.

Install using the .ova file

  1. From the Orchestrator page in InsightConnect, click Install Orchestrator and select Virtual Appliance Installation. Download the .ova file.

Install Orchestrator

  1. Import the rapid7-orchestrator-latest.ova disk image into the virtual machine (VM) solution of your choice, such as VirtualBox or VMWare.
  2. When the import is complete, boot the machine and log in with the credentials provided:
    • Username: rapid7
    • Password: changeme
  3. 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.

Install using the script-based installer package

You can install an orchestrator yourself using the Linux command line on a CentOS 7 or RHEL 7/8 machine.

  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 CentOS 7 or RHEL 7/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 CentOS 7 or RHEL 7/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 if 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.