CloudBees CD/RO Server Restores

9 minute readReference

This section describes common restore related procedures for recovering CloudBees CD/RO data.

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.

Restoring Your CloudBees CD/RO Server

The following section contains various procedures for restoring CloudBees CD/RO data.

All ectool commands used in the following scenarios are fully documented in the CloudBees CD/RO online help system. See the “Using ectool and the CloudBees CD/RO API” help topic.

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.

  1. Obtain a backup of the source system.

  2. Stop the destination CloudBees CD/RO server. For more information, see Starting and Stopping Servers and Agents Manually for platform-specific commands.

  3. If you are using a database dump (where the source and destination systems must both be using the same type of database), load the backup into the destination database.

    This will be done with a command specific to the database you are using.

  4. Start the destination CloudBees CD/RO server.

  5. If you are using an XML export file, use the ectool import command to import the data into the destination CloudBees CD/RO server.

  6. 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 doing one of these tasks:

  • Switching from the built-in database installation to an external database.

  • Upgrading to a higher performance system for the database.

    1. Obtain a backup of the source system.

    2. Stop the destination CloudBees CD/RO server. For more information, see Starting and Stopping Servers and Agents Manually for platform-specific commands.

    3. Stop and disable the original database.

    4. If you are using a database backup (where the source and destination systems must both be using the same type of database), load the database dump into the destination database.

      This will be done with a command specific to the database you are using.

    5. Start the destination CloudBees CD/RO server.

    6. Set the server database configuration to point to the new database. Point to the new database one of these ways:

      See the “Database Configuration” help topic in the CloudBees CD/RO web interface.

      Use the ectool setDatabaseConfiguration command.

    7. If you are using an XML export file, use the ectool import command to import the data into the destination CloudBees CD/RO server.

    8. Use the ectool shutdownServer --restart 1 command to restart the destination server.

Switch the CloudBees CD/RO Server but Keep the Same Database

Before switching the server, be aware of the following:

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

  • Make sure that the host name of local agent is set to 127.0.0.1 using Cloud > Resources > Local > Resource Details.

  • When you install CloudBees CD/RO without a built-in database, you can configure the database only by using ectool.

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

  1. Make sure you have a backup of the source system.

  2. Check the IP Address System property by selecting Administration > Server > Settings on the old (source) CloudBees CD/RO system.

    This field is empty by default to enable dynamic connections between the CloudBees CD/RO server and agents.

    If the field is not empty, you must enter the IP address for the Destination CloudBees CD/RO Server.

  3. Install a fresh CloudBees CD/RO service on the destination CloudBees CD/RO server.

  4. Stop the destination CloudBees CD/RO server.

    For more information, see Starting and Stopping Servers and Agents Manually for platform-specific commands.

  5. Stop and disable the source CloudBees CD/RO server.

  6. Copy the passkey and keystore files from the source CloudBees CD/RO backup to the destination system. These files are in /opt/cloudbees/sda/conf/ in Linux and in C:\ProgramData\CloudBees\Software Delivery Automation\conf\ in Windows.

  7. Copy the backed-up plugins to the destination system.

    You may encounter one of these scenarios: ** If the /server/settings/pluginsDirectory property does not exist, the server uses the default location (the `plugins ` subdirectory in the data directory).

    + Copy the backed-up plugins to that directory on the destination system.

    • The plugins are stored in a local directory valid on both systems.

      Copy the backed-up plugins to the same directory on the destination system.

    • The plugins are stored in a shared directory valid on both systems.

      You do not need to do anything.

    • The plugins are stored in a directory not accessible on the destination system.

      This can happen * If the source and destination systems have different operating systems (such as Windows to Linux). * If the plugins directory on the source system is on a drive that does not exist on the destination system.

      + Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, set the /server/settings/pluginsDirectory property to the new directory and restart the CloudBees CD/RO server.

  8. If you use a MySQL database, do these steps on destination system:

    1. Install the MySQL JDBC driver. For details, see Installing the MySQL JDBC Driver .

    2. Configure access to the CloudBees CD/RO database user from the IP address or FQDN on the destination system.

  9. Start the destination CloudBees CD/RO server.

  10. Because the CloudBees CD/RO host changed, connect the CloudBees CD/RO database to the new host:

    On the command-line: .. Use ectool setDatabaseConfiguration to specify a database configuration and set the ` --ignoreServerMismatch` option. .. Use the following command to restart the destination server: ectool shutdownServer --restart 1.

    + In the web interface, you should automatically be redirected to the Database Configuration page.

    1. Enter the appropriate database configuration.

    2. Select the Ignore server hostname mismatch check box.

    3. Select Same instance on a new host.

    4. Click Save and Restart.

  11. If you copied the plugins directory to a directory that does not match the plugins directory on the source system:

    1. Set the /server/settings/pluginsDirectory property to this new directory.

      You can use the ectool setProperty command to set this value.

    2. Restart the CloudBees CD/RO server.

Switch Both the CloudBees CD/RO Server and Database

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.

  1. Make sure you have a backup of the source system.

  2. Check the IP Address System property by selecting Administration > Server > Settings on the old CloudBees CD/RO system.

    This field is empty by default to enable dynamic connections between the CloudBees CD/RO server and agents.

    If the field is not empty, you must enter the IP address for the new CloudBees CD/RO server.

  3. Stop the destination CloudBees CD/RO server.

    For more information, see Starting and Stopping Servers and Agents Manually for platform-specific commands.

  4. Stop and disable the source CloudBees CD/RO server.

  5. Stop and disable the original database.

  6. Copy the passkey file from the backup to the destination system. The full path name of this file is include::cloudbees-common-sda::partial$passkey-dir.adoc[] .

  7. Copy the backed-up plugins to the destination system.

    You may encounter one of these scenarios: ** If the /server/settings/pluginsDirectory property does not exist, the server uses the default location (the `plugins ` subdirectory in the data directory).

    + Copy the backed-up plugins to that directory on the destination system.

    • The plugins are stored in a local directory valid on both systems.

      Copy the backed-up plugins to the same directory on the destination system.

    • The plugins are stored in a shared directory valid on both systems.

      You do not need to do anything.

    • The plugins are stored in a directory not accessible on the destination system.

      This can happen: * If the source and destination systems have different operating systems (such as Windows to Linux). * If the plugins directory on the source system is on a drive that does not exist on the destination system.

      + Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, set the /server/settings/pluginsDirectory property to the new directory and restart the CloudBees CD/RO server.

  8. If you are using a database backup (where the source and destination systems must both be using the same type of database), load the database dump into the destination database.

    This operation is completed with a command specific to the database you are using.

  9. Start the destination CloudBees CD/RO server.

  10. Because we have replaced the passkey, the database password is no longer valid. You need to reset the database password (default: commander ) and ignore the passkey mismatch either from the command-line or the web interface.

    • On the command-line, use ectool setDatabaseConfiguration to specify the password and set the --ignoreServerMismatch and --ignorePasskeyMismatch options.

    • In the web interface, you should automatically be redirected to the Database Configuration page. Enter the database password and select the ignore invalid passkey check box.

  11. If you are using an XML export file, use the ectool import command to import the data into the destination CloudBees CD/RO server.

  12. Use the ectool shutdownServer --restart 1 to restart the destination server.

  13. If you copied the plugins directory to a directory that does not match the plugins directory on the source system, set the /server/settings/pluginsDirectory property to this new directory and restart the CloudBees CD/RO server.

    You can use the ectool setProperty command to set this value.

Create a Clone of the CloudBees CD/RO Server and the Database

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

  1. Make sure you have a backup of the source system.

  2. Check the IP Address System property by selecting Administration > Server > Settings on the old CloudBees CD/RO system.

    This field is empty by default to enable dynamic connections between the CloudBees CD/RO server and agents.

    If the field is not empty, you must enter the IP address for the new CloudBees CD/RO server.

  3. Stop the destination CloudBees CD/RO server.

    For more information, see Starting and Stopping Servers and Agents Manually for platform-specific commands.

  4. Copy the passkey file from the backup to the destination system. The full path name of this file is include::cloudbees-common-sda::partial$passkey-dir.adoc[] .

  5. Copy the backed-up plugins to the destination system.

    You may encounter one of these scenarios: ** If the /server/settings/pluginsDirectory property does not exist, the server uses the default location (the `plugins ` subdirectory in the data directory).

    + Copy the backed-up plugins to that directory on the destination system.

    • The plugins are stored in a local directory valid on both systems.

      Copy the backed-up plugins to the same directory on the destination system.

    • The plugins are stored in a shared directory valid on both systems.

      You do not need to do anything.

    • The plugins are stored in a directory not accessible on the destination system.

      This can happen: * If the source and destination systems have different operating systems (such as Windows to Linux). * If the plugins directory on the source system is on a drive that does not exist on the destination system.

      + Copy the backed-up plugins to a new directory accessible to the destination system. When the server starts, set the /server/settings/pluginsDirectory property to the new directory and restart the CloudBees CD/RO server.

  6. If you are using a database backup (the source and destination systems must be using the same type of database), create the destination database, give the appropriate database user permissions to the schema (as mentioned in External Database Configuration ), and load the database dump into the destination database.

    This operation is completed with a command specific to the database you are using.

  7. If you are using a database backup, disable schedules, resources, or both on both servers.

    • Two servers should never talk to the same agent. The two servers share the same identity because they share exact copies of the database.

    • Disabling schedules prevents jobs from launching unexpectedly.

    • Disabling resources prevents scheduled or manually launched jobs from running on production agents. This operation is completed with a command specific to the database you are using.

  8. Start the destination CloudBees CD/RO server.

  9. Because we have replaced the passkey, the database password is no longer valid. You need to reset the database password (default: commander ) and ignore the passkey mismatch either from the command-line or the web interface.

    • On the command-line, use ectool setDatabaseConfiguration to specify the password and set the --ignoreServerMismatch and --ignorePasskeyMismatch options.

    • In the web interface, you should automatically be redirected to the Database Configuration page. Enter the database password and select the ignore invalid passkey check box.

  10. If you are using an XML export file, disable schedules, resources, or both on both servers.

    • Two servers should never “talk” to the same agent. The two servers share the same identity because they share exact copies of the database.

    • Disabling schedules prevents jobs from being launched unexpectedly.

    • Disabling resources prevents scheduled or manually launched from running on production agents.

      Disable the schedules and resources one of these ways:

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

  11. Use the ectool shutdownServer --restart 1 command to restart the destination server.

  12. If you copied the plugins directory to a directory that does not match the plugins directory from the source system,set the /server/settings/pluginsDirectory property to the new directory and restart the CloudBees CD/RO server.

    You can use the ectool setProperty command to set this value.