Install the CentOS 7 orchestrator

Centos 7 Orchestrator End-of-Life

The end-of-life (EOL) process has started for the CentOS 7 Orchestrator, meaning it will no longer receive security updates or patches after June 2024. While you can install it, you may be exposed to potential cybersecurity threats from June 2024 onwards. Rapid7 recommends that you install the new Ubuntu Orchestrator instead. To migrate an existing CentOS 7 orchestrator, refer to the migration steps to easily copy over your data.

You can install the CentOS 7 Orchestrator using the .ova file or the script-based installer package.

Install using the .ova file

  1. From the Orchestrator page in InsightConnect, click Install Orchestrator and select Virtual Appliance Installation. Download the CentOS 7 .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.

Install using the script-based installer package

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

Linux shell script installation method requirements

You must provision a new CentOS 7 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.

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