Install and activate the Insight Orchestrator

Before you can use your Insight Orchestrator, you have to get it up and running on a CentOS 7 instance.

Before you begin

  • Be sure to read our system and network requirements and provision a server that meets the production hardware requirements.
  • To find the installer, open the dropdown menu under the Settings tab and click Orchestrator.
  • We currently only support CentOS 7 for orchestrator installation. Red Hat Enterprise Linux (RHEL) has technical issues with Docker's free Community Edition, which means you have to purchase and install Docker Enterprise Edition if you want to attempt to use RHEL. Because of this, and because RHEL is not currently supported for orchestrator installation, we recommend you use the CentOS .ova file installation method to get started.
  • You must provision a new CentOS 7 installation in alignment with our production hardware requirements to install an orchestrator with a Linux shell script. If you repurpose an existing CentOS machine or underprovision disk space, you will get errors later.
  • If you use other Rapid7 Insight products and already installed an orchestrator on any of them, you don’t have to install one for InsightConnect. You only need one installed orchestrator for it to work across all Insight products. That said, you can install multiple orchestrators if needed, for example, if you want to run different orchestrators in different parts of your network based on network topology.

Install the orchestrator

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

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

Cross-product installation

If you purchased and have access to InsightConnect, you can use the .ova file or installation script from the product itself, or from a sales or support representative without any issue. We recommend you get your file or script from the product itself to ensure you’re starting with the most recent version.

If you purchased any other Insight product, but have not directly purchased a license for InsightConnect, and are utilizing the 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.

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 the option to download the 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.

Install using the script-based installer package

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

To install an orchestrator using the command line:

  1. Download the r7-orchestrator-installer.sh file by secondary-clicking the link for your region from this list and selecting Save Link As or Download Link As.
  2. Import the .sh file to your CentOS 7 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 CentOS7 machine’s /tmp directory.
  3. In your CentOS 7 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.
  4. 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.
  5. Follow the instructions provided in the installer to continue. If you require further assistance, run ./<installer> --help to view more information.
  6. 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.
  7. 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.