Migrate an orchestrator to a new host

Migrating your orchestrator to a new host might be necessary if you are:

• Changing operating systems
• Moving to cloud infrastructure
• Replacing hardware
• Reinstalling on the same host

The two available methods for migration are:

• Migrate using built-in commands
• Migrate manually

Before you migrate an orchestrator, it’s important to know that the orchestrator stores the encryption keys that protect connection credentials.

Therefore, to preserve existing connections, you must ensure that you migrate the orchestrator data and encryption keys to the new host.

Requirements

Before you begin:

• Ensure the new host is running a supported operating system, as outlined in the system and network requirements.
• Set up SSH or another file transfer method between the two hosts.
• The new orchestrator must be the same version or later than the original: downgrading is not supported.

Migrate the orchestrator using built-in commands

This procedure uses the built-in orch-backup and orch-restore commands.

Task 1: Back up the original orchestrator

To create a backup of the original orchestrator:

1. Stop the orchestrator by running the command:

sudo orch-stop

2. Create a backup archive by running the command:

sudo orch-backup -o /tmp/orchestrator-backup.tar.gz

3. Prevent the original orchestrator from restarting by running the command:

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

Task 2: Install the orchestrator on the new host

1. Install the orchestrator on the new host using a supported installation method.

2. After the installation completes, run this command to stop the orchestrator:

sudo orch-stop

Task 3: Transfer and restore the backup

The restoration process has the following outcomes:

• Backs up the fresh installation
• Restores enrollment data, encryption keys, configuration files, and state data
• Preserves binaries from the new installation
• Sets file ownership
• Validates required files

To restore the orchestrator on the new host:

1. Transfer the backup archive by running the command:

scp /tmp/orchestrator-backup.tar.gz <user>@<new-host>:/tmp/

2. Restore the backup on the new host by running the command:

sudo orch-restore /tmp/orchestrator-backup.tar.gz

Task 4: Start and verify the orchestrator

To start the restored orchestrator:

1. Start the orchestrator by running the command:

sudo orch-start

2. In Automation (InsightConnect), go to Data Connectors > Orchestrators.
3. Verify that the orchestrator status is healthy.
4. Confirm that the displayed hostname and IP address match the new host.
5. Go to Automation > Plugins > Connections.
6. Test several connections to verify that credentials migrated successfully.

Revert the migration

If the migration fails, you can revert and restore the previous state.

1. Roll back the new host by running the command:

sudo orch-restore-rollback

2. Restore the original orchestrator by running the command:

sudo systemctl unmask rapid7-orchestrator
sudo systemctl enable rapid7-orchestrator
sudo systemctl enable rapid7-orchestrator-motd
sudo systemctl start rapid7-orchestrator

Migrate the orchestrator manually

Use this procedure only if the orch-backup and orch-restore commands are unavailable.

Task 1: Install the orchestrator on the new host

1. Install the orchestrator on the new host using a supported installation method.

2. Stop the service by running the command:

orch-stop

Task 2: Stop the original orchestrator

Stop the original orchestrator by running the command:

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

Task 3: Archive and transfer orchestrator data

1. On the original host, run the command:

sudo su
cd /opt/rapid7
 
tar --exclude="orchestrator/bin" \
    --exclude="orchestrator/var/log" \
    -zcvf orchestrator.tar.gz orchestrator/
 
scp orchestrator.tar.gz <user>@<new-host>:/tmp/

2. On the new host, run the command:

sudo su
 
mv /opt/rapid7/orchestrator /opt/rapid7/orchestrator.fresh-install
 
tar -xvzf /tmp/orchestrator.tar.gz -C /opt/rapid7/
 
cp -a /opt/rapid7/orchestrator.fresh-install/bin /opt/rapid7/orchestrator/bin
 
chown -R rapid7:rapid7 /opt/rapid7/orchestrator
 
rm /tmp/orchestrator.tar.gz

3. Verify that the restored data includes the enrollment and keypair files.

Task 4: Start the orchestrator

1. Start the orchestrator by running the command:

orch-start

2. Verify orchestrator health and test connections in Automation (InsightConnect).

Revert the installation

If you need to revert the installation on either host, follow these steps.

To revert the installation on the original host:

sudo systemctl unmask rapid7-orchestrator
sudo systemctl enable rapid7-orchestrator
sudo systemctl enable rapid7-orchestrator-motd
sudo systemctl start rapid7-orchestrator

To revert the installation on the new host:

orch-stop
sudo rm -rf /opt/rapid7/orchestrator
sudo mv /opt/rapid7/orchestrator.fresh-install /opt/rapid7/orchestrator

Troubleshoot a migration

If any issues occur during migration, use the information in this table to identify the possible causes and resolutions.