How can I move a self-hosted runZero server?

Sometimes you may need to move a self-hosted runZero server console to a different machine with a different IP address.

In the easiest case, you have a permanent DNS entry for the console (e.g. runzero.example.com), and a TLS certificate for that name from either an internal CA or a public one. In that case, you can redirect the DNS entry to the new IP, the certificate will still be valid, and everything should just keep working.

In the case where there's no domain name, or the domain name needs to change, things get more complicated. Here's an outline of the process.

Preparations

Before you begin moving the server:

• Enable non-SSO logins on the server, as your SSO system will likely refuse to allow login to the new address, and you will need to reconfigure it.
• Enable login without MFA, as WebAuthn tokens are locked to the hostname where they were registered, and cannot be updated.
• Create a superuser account with a non-SSO password, and verify that the account can log in.
• Pause all scheduled and recurring scans.
• Stop all scans that are in progress.
• Ensure that both the old and new servers have an SSH user set up with sudo permissions or the ability to su to root.

Updating the console installation

The next step will be to change the IP address of the server.

After that, you can update the runZero server configuration for the new IP address:

• First you'll need to edit /etc/runzero/config (/etc/rumble/config on older installs) to update the value of RUNZERO_CONSOLE (RUMBLE_CONSOLE on older installs), so the new server instance generates valid URLs pointing back to itself (and also configures Explorers correctly).

• The TLS certificate will also need to be replaced for the new hostname and/or IP address. The TLS_CERT and TLS_KEY variables in the config file point at the PEM files for that, they're in regular OpenSSL format.

  • You can also remove the TLS cert and key from /etc/runzero/certs//etc/rumble/certs, and then use runzeroctl generate-cert to generate new ones.

Redeploying explorers

Next, the Explorers will need to be redeployed to use the reconfigured server, since during download they are preconfigured with the name of the console/hub to connect to, and with the TLS certificate. (You can override the certificate at run time, but not the server URL.) 

Redeploying explorers using two running consoles

The easiest way to redeploy the Explorers is if you can have the old server and the new server running simultaneously. Then you can use the reassign Explorer feature on the old server, and give it the URL of the new server, and the Explorer will move across. (This assumes that the machines hosting the Explorers can connect to both the old and new servers.)

If you're running two instances and using the reassign function to move the Explorers across, the Explorer host systems will need to accept the new server's TLS certificates as trusted, otherwise the Explorer won't be willing to download and install the new binary. This might require adding the new certificate to the OS trusted certificate store, or setting up a suitable certificate chain and overriding the Explorer TLS config at run time.

Redeploying explorers manually

If running two server instances temporarily to reassign the Explorers isn't possible, a regular Explorer download and install from the new server will work. The new binary will replace the existing one because they're named based on the organization ID they talk to, and it'll have updated URL and certificate information embedded.

• Delete the existing Explorers in the console UI, so you don't get confused about which ones have been redeployed.

• Use the copy/paste commands provided on the Deploy page of your console to redeploy the Explorers on their host systems.

Setting up SSO

If you change hostname and you've set up SSO, you'll need to reconfigure that for the new hostname/address. Both the SAML SSO server and the runZero console will need reconfiguring, because according to the standards the server has to authenticate the client login request by checking the URL it redirects the user back to. The best way to handle reconfiguring SSO is to make sure you have a non-SSO admin account you can log in with, disable SSO, log in when the server has been moved, and then set up SSO again.

Setting up MFA

If you've set up WebAuthn tokens, there's no way to reassign them to a different domain name once they have been set up; it's a limitation of the standards. You will need to unlink the tokens from each user account if you haven't already done so, and set them up again once the server has been moved and you've navigated to the new URL.