Migrate to an Ubuntu orchestrator

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. To maintain a secure environment, follow these steps to migrate to the new Ubuntu orchestrator.

Step 1: Install the Ubuntu orchestrator

Follow the steps to Install the Ubuntu orchestrator.

Ensure you switch off the orchestrator services on Ubuntu by running the command: orch-stop

Step 2: Switch off the CentOS 7 orchestrator

To switch off the CentOS 7 orchestrator:

1. In the CentOS 7 orchestrator, use these commands from the linux command line:

   • sudo systemctl stop rapid7-orchestrator
   • sudo systemctl disable rapid7-orchestrator
   • sudo systemctl mask rapid7-orchestrator
   • sudo systemctl disable rapid7-orchestrator-motd

   This will stop and disable the orchestrator service from starting on boot as well as remove the scheduled job that automatically updates the orchestrator code.

2. Validate the orchestrator has been switched off by checking the health of any CentOS 7 orchestrator in the Orchestrator management page.

   • The orchestrator shows as unhealthy when CentOS 7 has been turned off.
   • It will switch to healthy when Ubuntu is turned on.

Step 3: Copy the CentOS 7 files to the Ubuntu Orchestrator

To copy your files over:

1. Elevate to the root user by running: sudo su
2. Navigate to the Orchestrator directory in CentOS 7 using the command: cd /opt/rapid7
3. Archive the Orchestrator files by running the command: tar --exclude="orchestrator/bin" --exclude="orchestrator/var/log" -zcvf orchestrator.tar.gz orchestrator/
4. Transfer the backup file to the Ubuntu orchestrator with secure shell (SSH) by running scp <backupfile> <user>@<VM address>:<directory> on your CentOS orchestrator. For example, running scp orchestrator.tar.gz <user>@<VM address>:/opt/rapid7 will transfer the file to your Ubuntu orchestrator directory.
5. On the Ubuntu Orchestrator, elevate to the root user by running: sudo su
6. Navigate to the Orchestrator directory in Ubuntu by using the command: cd /opt/rapid7
7. Paste the orchestrator.tar.gz file you copied into the directory in the previous step.
8. Extract the tar.gz file by running the command: tar -xvzf orchestrator.tar.gz
9. Ensure that the output from extracting includes at least the following files:
   • orchestrator/var/bolt-log
   • orchestrator/var/cache/ (this directory may be empty)
   • orchestrator/var/enrollment
   • orchestrator/var/executordb
   • orchestrator/var/keypair
   • orchestrator/var/tmp/ (this directory might be empty)
   • orchestrator/etc/enrollment-text
   • orchestrator/etc/executor.conf
   • orchestrator/etc/plugins.conf
   • orchestrator/etc/restartable-triggers (may not exist)
   • orchestrator/etc/trigger-statistics
   • orchestrator/etc/ca-cert-mirror/ (this directory may be empty)

There may be more files in the archive but those are the minimum required set to properly migrate.

Step 4: Switch on the Ubuntu orchestrator

To switch on the Ubuntu orchestrator:

1. In the Ubuntu Orchestrator, run the command orch-start to start the Ubuntu orchestrator.
2. Validate the orchestrator has been switched on by checking the health of any previous CentOS 7 orchestrator in the Orchestrator management page.
3. Check these fields to identify if the correct orchestrator is being used:
   • IP Address
   • Host Name

Step 5: Test the connection

Test the connection to validate that everything is running smoothly.

1. Navigate to Settings > Plugins & Tools and click the Connections tab.
2. Click the 3 dots (•••) on any healthy connection and select Test. A blue indicator will appear on the connections card to show the test is in progress. If the indicator turns red, it means the test failed.

Troubleshooting

My CentOS and Ubuntu orchestrators are both active in my environment

If both the CentOS 7 orchestrator and Ubuntu orchestrator are active in your environment, you’ll need to go through the migration process to ensure you are using only the Ubuntu orchestrator.

1. Navigate to the Insight Platform > Data Collection > Orchestrators.
2. Delete the Ubuntu orchestrator.
3. Switch off the orchestrator services on Ubuntu by running the command: orch-stop
4. Follow the migration steps from Step 2: Switch off the CentOS 7 orchestrator.

Note: Do not activate the new Ubuntu orchestrator during migration. The migration will move the existing activation from the CentOS 7 orchestrator to the new Ubuntu orchestrator.