Restore a CloudBees CD/RO server

Preparing for a Restore

Before you attempt to restore a CloudBees CD/RO server:

You must have a backup of your source CloudBees CD/RO server.
If you are restoring your data to the exact same database or the same database type (for example, from one MySQL database to another MySQL database on a different system), a database backup is sufficient.
If you are switching to a different database type, you will need an XML export.

Any activity on the source server after the backup was created will not exist on the destination server.

The destination system must have a CloudBees CD/RO server already installed and running, and this server must be running the same version or newer version than the source server.

Restore the same CloudBees CD/RO server and database

Use the following procedure to restore your CloudBees CD/RO server because of a catastrophic failure or unsuccessful upgrade.

Obtain a backup of the source system.
Restore the database using one of the following methods:
- Database dump - Use this method if the source and destination databases are the same type.
  1. Stop the destination CloudBees CD/RO server. Refer to Start and stop servers and agents manually for platform-specific commands.
  2. Use database-specific commands to load the source database information into the destination database.
- XML export file.
  1. Use the ectool import command to import the source backup into the destination CloudBees CD/RO server.
    
    If you receive an invalid passkey error, refer to Resolve the XML import invalid passkey error.
  2. Use the ectool shutdownServer --restart 1 command to restart the destination server.

Keep the same CloudBees CD/RO server but switch the database

Use the following procedure to restore your CloudBees CD/RO server if you are switching from the built-in database installation to an external database or upgrading to a higher performance system.

Obtain a backup of the source system.
Disable the source database.
Restore the database using one of the following methods:
- Database dump - Use this method if the source and destination databases are the same type.
  1. Stop the destination CloudBees CD/RO server. For more information, refer to Start and stop servers and agents manually for platform-specific commands.
  2. Use database-specific commands to load source database information into destination database.
  3. Start the destination CloudBees CD/RO server.
  4. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
- XML export file.
  1. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
  2. Run the ectool import command to import the source backup into the destination CloudBees CD/RO server.
    
    If you receive an invalid passkey error, refer to Resolve the XML import invalid passkey error.
  3. Use the ectool shutdownServer --restart 1 command to restart the destination server.

Switch the CloudBees CD/RO server but keep the same database

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

You should consider the following before you begin this procedure:

All files and directories copied to the destination CloudBees CD/RO server should be owned by the user configured to run the CloudBees CD/RO server daemon.
Ensure the host name of the local agent is set to 127.0.0.1 using Cloud Resources Local Resource Details on the destination server.
When you install CloudBees CD/RO without a built-in database, you must use ectool to configure the database.

Use the following procedure to restore CloudBees CD/RO if you are upgrading to a higher performance CloudBees CD/RO server system.

Obtain a backup copy of the source system.
On the source server, view the Server IP Address system property by selecting Administration > Server > Settings > System Settings. Do one of the following:
- If the field is empty, do nothing. This is the default setting which enables dynamic connections between the CloudBees CD/RO server and agents.
- If the field is not empty, enter the IP address for the destination CloudBees CD/RO Server.
Install the CloudBees CD/RO service on the destination CloudBees CD/RO server.
Stop the destination CloudBees CD/RO server. Refer to Starting and Stopping Servers and Agents Manually for platform-specific commands.
Stop and disable the source CloudBees CD/RO server.
Copy the keystore to a temporary location on the destination server from one of the following locations on the source server:
- Linux: /opt/cloudbees/sda/conf/keystore
- Windows: C:\ProgramData\CloudBees\Software Delivery Automation\conf\keystore
Copy the passkey to a temporary location on the destination server from one of the following locations on the source server:
- Linux: installation-directory/conf/passkey
- Windows: installation-directory\conf\passkey
Copy the ./conf/security folder to the destination system from one of the following locations on the source server:
- Linux: /opt/cloudbees/sda/conf/security
- Windows: C:\ProgramData\CloudBees\Software Delivery Automation\conf\security

Copy any plugins that were backed up to the destination system, based upon the following scenarios:

If the /server/settings/pluginsDirectory property does not exist, copy source plugins into the default location on the destination server: /server/settings/pluginsDirectory
If the source plugins are stored in a local directory that is valid on both systems, copy the source plugin into the same directory on the destination server.
If the source plugins are stored in a shared directory that is valid on both servers, do nothing.
If the source plugins are stored in a directory that is not accessible on the destination server, copy the source plugins into the destination server’s default location: /server/settings/pluginsDirectory

If the plugin’s directory on the source system is on a drive that does not exist on the destination system, copy the source plugins into the default directory on the destination server.

If you choose to copy plugins into a location other than the default, use the ectool setProperty command.

Set the /server/settings/pluginsDirectory property to point to the custom directory. Then, restart the CloudBees CD/RO server.

If you use a MySQL database, execute these steps on the destination system:
1. Install the MySQL JDBC driver. For details, refer to Install the MySQL JDBC connector.
2. Configure access to the CloudBees CD/RO database user from the IP address or FQDN on the destination system.
Start the destination CloudBees CD/RO server.
Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host using one of the following:
- ectool:
  1. Use ectool setDatabaseConfiguration to set the --ignoreServerMismatch option
  2. Restart the destination server: ectool shutdownServer --restart 1.
- The UI: You will be automatically directed to the Database configuration page.
  1. Enter the appropriate database configuration.
  2. Select Ignore server hostname mismatch.
  3. Select Same instance on a new host.
  4. Select Save and restart server.
If you copied the plugins directory to a directory that does not match the plugins directory on the source system:
1. Use ectool to set the /server/settings/pluginsDirectory property to this new directory.
2. Restart the destination server: ectool shutdownServer --restart 1.
On the destination server, view the Server IP Address system property by selecting Administration Server Settings System Settings. Do one of the following:
- If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
- If the field is not empty, enter the IP address for the destination CloudBees CD/RO Server.

Switch both the CloudBees CD/RO server and database

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

Use the following procedure to restore CloudBees CD/RO if you are upgrading to higher performance systems for both the CloudBees CD/RO server and the database.

Obtain a backup copy of the source system.
On the source server, view the Server IP Address system property by selecting Administration Server Settings System Settings. Do one of the following:
- If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
- If the field is not empty, enter the IP address for the destination CloudBees CD/RO server.
Install the CloudBees CD/RO service on the destination CloudBees CD/RO server.
Stop the destination CloudBees CD/RO server. Refer to Starting and Stopping Servers and Agents Manually for platform-specific commands.
Stop and disable the source CloudBees CD/RO server.
Stop and disable the source database.
Copy the keystore to a temporary location on the destination server from one of the following locations on the source server:
- Linux: /opt/cloudbees/sda/conf/keystore
- Windows: C:\ProgramData\CloudBees\Software Delivery Automation\conf\keystore
Copy the passkey to a temporary location on the destination server from one of the following locations on the source server:
- Linux: installation-directory/conf/passkey
- Windows: installation-directory\conf\passkey
Copy the ./conf/security folder to the destination system from one of the following locations on the source server:
- Linux: /opt/cloudbees/sda/conf/security
- Windows: C:\ProgramData\CloudBees\Software Delivery Automation\conf\security

Copy any plugins that were backed up to the destination system, based upon the following scenarios:

If the /server/settings/pluginsDirectory property does not exist, copy the source plugins into the default location on the destination server: /server/settings/pluginsDirectory
If the source plugins are stored in a local directory that is valid on both systems, copy the source plugin into the same directory on the destination server.
If the source plugins are stored in a shared directory that is valid on both servers, do nothing.
If the source plugins are stored in a directory that is not accessible on the destination server, copy the source plugins into the destination server’s default location: /server/settings/pluginsDirectory

If the plugins directory on the source system is on a drive that does not exist on the destination system, copy the source plugins into the default directory on the destination server.

If you choose to copy plugins into a location other than the default, use the ectool setProperty command.

Set the /server/settings/pluginsDirectory property to point to the custom directory. Then, restart the CloudBees CD/RO server.

Restore the database using one of the following methods:
- Database dump - Use this method if the source and destination databases are the same type.
  1. Use database-specific commands to load the source database information into the destination database.
  2. Start the destination CloudBees CD/RO server.
  3. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
  4. Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host using one of the following:
    
    ectool:
    
    Run the ectool setDatabaseConfiguration command to set the --ignoreServerMismatch option.
    
    Run the ectool shutdownServer --restart 1 command to restart the destination server.
    
    The UI: You are automatically directed to the Database configuration page.
    
    Enter the appropriate database configuration.
    
    Select Ignore server hostname mismatch.
    
    Select Same instance on a new host.
    
    Select Save and restart server.
  5. On the destination server, view the Server IP Address system property by selecting Administration Server Settings System Settings. Do one of the following:
    
    If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
    
    If the field is not empty, enter the IP address for the destination CloudBees CD/RO Server.
- XML export file.
  1. Start the destination CloudBees CD/RO server.
  2. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
  3. Use the ectool import command to import the source backup into the destination CloudBees CD/RO server.
    
    If you receive an invalid passkey error, refer to Resolve the XML import invalid passkey error.
  4. Restart the destination server: ectool shutdownServer --restart 1.
  5. Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host using one of the following:
    
    ectool:
    
    Run the ectool setDatabaseConfiguration command to set the --ignoreServerMismatch option.
    
    Run the ectool shutdownServer --restart 1 command to restart the destination server.
    
    The UI: You are automatically directed to the Database configuration page.
    
    Enter the appropriate database configuration.
    
    Select Ignore server hostname mismatch.
    
    Select Same instance on a new host.
    
    Select Save and restart server.
  6. On the destination server, view the Server IP Address system property by selecting Administration Server Settings System Settings. Do one of the following:
    
    If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
    
    If the field is not empty, enter the IP address for the destination CloudBees CD/RO server.

Create a clone of the CloudBees CD/RO server and the database

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

Use the following procedure to restore your CloudBees CD/RO server if you are setting up a production-like environment for testing.

Obtain a backup copy of the source system.
Install the CloudBees CD/RO service on the destination CloudBees CD/RO server.
Stop the destination CloudBees CD/RO server. Refer to Starting and Stopping Servers and Agents Manually for platform-specific commands.
Copy the passkey to a temporary location on the destination server from one of the following locations on the source server:
- Linux: installation-directory/conf/passkey
- Windows: installation-directory\conf\passkey

Copy any plugins that were backed up to the destination system based upon the following scenarios:

If the /server/settings/pluginsDirectory property does not exist, copy the source plugins into the default location on the destination server: /server/settings/pluginsDirectory
If the source plugins are stored in a local directory that is valid on both systems, copy the source plugin into the same directory on the destination server.
If the source plugins are stored in a shared directory that is valid on both servers, do nothing.
If the source plugins are stored in a directory that is not accessible on the destination server, copy the source plugins into the destination server’s default location: /server/settings/pluginsDirectory

If the plugins directory on the source system is on a drive that does not exist on the destination system, copy the source plugins into the default directory on the destination server.

If you choose to copy plugins into a location other than the default, use the ectool setProperty command.

Set the /server/settings/pluginsDirectory property to point to the custom directory. Then, restart the CloudBees CD/RO server.

Restore the database using one of the following methods:
- Database dump - Use this method if the source and destination databases are the same type.
  1. Use database-specific commands to load the source database information into the destination database.
    
    Two servers should never communicate with the same agent. These two servers share the same identity because they share exact copies of the database.
  2. Disable schedules and resources on both servers by using:
    
    UPDATE ec_schedule SET disabled = 1 to disable schedules which prevents jobs from launching unexpectedly.
    
    UPDATE ec_resource SET disabled = 1 to disable resources which prevents scheduled or manually launched jobs from running on production agents.
  3. Start the destination CloudBees CD/RO server.
  4. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
  5. Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host using one of the following:
    
    ectool:
    
    Run the ectool setDatabaseConfiguration command to set the --ignoreServerMismatch option.
    
    Run the ectool shutdownServer --restart 1 command to restart the destination server.
    
    The UI: You are automatically directed to the Database configuration page.
    
    Enter the appropriate database configuration.
    
    Select the Ignore server hostname mismatch.
    
    Select Same instance on a new host.
    
    Select Save and restart server.
  6. On the destination server, view the Server IP Address system property by selecting Administration Server Settings System Settings. Do one of the following:
    
    If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
    
    If the field is not empty, enter the IP address for the destination CloudBees CD/RO server.
- XML export file.
  1. Start the destination CloudBees CD/RO server.
  2. Set the CloudBees CD/RO server database configuration to point to the new database using one of the following:
    
    The CloudBees CD/RO UI. Refer to Configure CloudBees CD/RO to use an alternate database.
    
    The ectool setDatabaseConfiguration command.
  3. Disable schedules and resources on both servers.
    
    Two servers should never communicate with the same agent. These two servers share the same identity because they share exact copies of the database.
    
    Modify the import file by replacing <resourceDisabled>0</resourceDisabled> with <resourceDisabled>1</resourceDisabled>.
    
    Use the ectool import command with the --disableSchedules flag turned on to disable schedules.
    
    If you receive an invalid passkey error, refer to Resolve the XML import invalid passkey error.
  4. Use the ectool shutdownServer --restart 1 command to restart the destination server.
  5. Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host using one of the following:
    
    ectool:
    
    Run the ectool setDatabaseConfiguration command to set the --ignoreServerMismatch option.
    
    Run the ectool shutdownServer --restart 1 command to restart the destination server.
    
    The UI: You are automatically directed to the Database configuration page.
    
    Enter the appropriate database configuration.
    
    Select Ignore server hostname mismatch.
    
    Select Same instance on a new host.
    
    Select Save and restart server.
  6. On the destination server, view the Server IP Address system property by selecting Administration > Server > Settings > System Settings. Do one of the following:
    
    If the field is empty, do nothing. This is the default setting which enables a dynamic connection between the CloudBees CD/RO server and agents.
    
    If the field is not empty, enter the IP address for the destination CloudBees CD/RO server.

Resolve the XML import invalid passkey error

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

An error occurs when the source and destination servers have different passkeys. To resolve the error, you must create a new XML file with the destination passkey. Complete the following steps to create the new XML file.

Copy the source XML export file to a temporary location on the destination server.
Copy the passkey from one of the following locations on the source server to a temporary location on the destination server:
- Linux: installation-directory/conf/passkey
- Windows: installation-directory\conf\passkey
Compare the source server passkey to the XML passkey:
1. Open the XML file.
2. Note the passkey in the header.
  
  Figure 1. XML file passkey
3. Run the following script to locate the source server passkey. Use the temporary folder on the destination server as the source path.
  /TempLocation/SourcePasskey sha1sum passkey
  ▼
4. Compare the source server passkey to the XML file passkey.
  
  Figure 2. Source server passkey
5. Do one of the following:
  - If both passkeys are the same, go to the next step.
  - If the passkeys are different, contact CloudBees CD/RO support.
Navigate to the destination server location:

/opt/cloudbees/sda/server/bin

Modify the script below to include the locations of the source XML, source passkey, destination passkey, and new XML file.

../../jre/bin/java -jar convert-credentials-jar-with-dependencies.jar \
--oldPasskeyFile /tmp/passkey_10.0.2 \
--sourceXmlFile /tmp/CD10.0.2_fullExport.xml \
--newPasskeyFile ../../conf/passkey \
--targetXmlFile /tmp/CD10.0.2_fullExport_PasskeyChanged.xml▼

Restart the restore process by running ectool import using the new XML file.
Complete the restore by executing the remaining XML restore steps from the applicable section.