Backing up a controller

A controller backup takes a snapshot of the controller state, and includes the following in a single file:

NOTE: Applications using Cassandra in a teamed mode cannot use the backup and restore services in the SDN Controller. In this case, off-the-shelf solutions are recommended, such as rsync or Amanda.

Examples of cURL commands in this guide use the --noproxy option, which is appropriate where execution of cURL commands do not need a proxy to access controllers. If your network is set up such that a proxy is needed to access controllers, use the --proxy option. For details on cURL proxy options, visit

Backup operation

A controller backup includes the controller configuration and databases in one *.zip file.

  • Backups run in the background, and, except for locking the Cassandra database to prevent writes, do not interrupt system operation.

  • Whether operating in a team or operating in standalone mode, each controller is backed-up as a single system.

  • When the controller is deployed in a VM, standard VM backup/restore tools (such as Snapshot or Clone) can be used.

  • When the controller is deployed on bare metal, standard Linux server-based backup/restore tools (such as rsync, LVM snapshot, and Amanda/Zmanda) can be used.

  • To complete a teamed backup, no controller can be in a failed state. (A controller team must have three controllers.)

  • On any controller or controller team, only one operation can run at any given time (backup, restore, upload, or download). Also, starting a new backup while another backup is being downloaded creates an error condition and halts the new backup.

  • Only authenticated users are allowed to create and restore backups. In some cases the domain name is also required.

NOTE: The default domain name is sdn. The default username is also sdn. The default password is skyline.

The controller does not save a non-default domain, user name, or pass-word across a backup. Changing these settings to non-default values and later backing up the controller, resets these settings to their defaults in the backup file. Later restoring the backup to the controller resets the domain, user name, and password to their default settings in the controller.

For backup and restore of the Keystone configuration and database, see “Backing up and restoring the keystone configuration and database”.

  • If uploading a backup fails, then no backup version remains on the system.

  • Starting a new backup replaces any earlier backup remaining in the controller. If a backup is being downloaded when a new backup is started, the new backup halts.

  • Metering time-series data is not encompassed by the controller backup process. There can be a large amount of data, possibly tens of GBs in size, which is keyed to time. Not only is the time series data impractical to back up because of its size, but upon restoring it there is a likelihood that some of the restored data will not be usable because it will be older than the sliding window of time that metrics are retained for on the controller. However, there is one metering file that is backed up and restored. It contains a mapping of metric descriptor information (such as the ID of the application that created a metric and the metric's primary tag, secondary tag, and name) to the UID that was assigned to each metric. When a restore is performed, this file is restored, and any existing metering time-series data is deleted because it might not match the restored file. The mappings that are restored might, depending upon time elapsed since the backup was taken, be used to assign the same UID to a metric created following the restore (and subsequent controller restart) that was assigned to the metric before the backup was taken. This provides continuity for a metric across the time spanned between backup and restore because all data for the metric is keyed to the same UID. Thus, while time-series data from before the restore was not retained during the restore, UIDs used to key time-series data that was exported to external tools or storage before the restore will continue to be used for the same metrics.

Backing up a controller

  1. 1. Acquire the authentication token for the controller backup:

    url --noproxy controller_ip X POST --fail -ksSfL 
    -url "https://controller_ip:8443/sdn/v2.0/auth" 
    -H "Content-Type: application/json" --data-binary '{"login": 
    {"domain": "domain","user": 
    "user","password": "password"}}'

    CAUTION: Credential information (user name, password, domain, and authentication tokens) used in cURL commands might be saved in the command history. For security reasons, HP recommends that you disable command history prior to executing commands containing credential information.

  2. Acquire the controller uid:

    curl --noproxy controller_ip 
    --header "X-Auth-Token:auth_token" --fail -ksSfL --request GET
    --url "https://controller_ip:8443/sdn/v2.0/systems"
  3. Set the IP address of the controller using the following cURL command:

    curl --noproxy controller_ip> 
    --header "X-Auth-Token:auth_token" --fail -ksSfL --request PUT 
    --data-binary '{"system":{"ip":"controller_ip"}}'
  4. Perform the actual backup using the following cURL command:

    curl --noproxy controller_ip 
    --header "X-Auth-Token:auth_token" --fail -ksS --request POST 
    --url "https://controller_ip:8443/sdn/v2.0/backup"
  5. Get the checksum to verify the backup file has not been corrupted. The REST command to get the checksum is as follows:

     curl --noproxy <controller_ip> --header "X-Auth-Token:<auth_token>" --fail -ksS --request GET --url "https://<controller_ip>:8443/sdn/v2.0/backup/checksum"
  6. Check on the status of a backup.

    curl --noproxy controller_ip 
    --header "X-Auth-Token:auth_token" --fail -ksSfL --request GET
    --url "https://controller_ip:8443/sdn/v2.0/backup/status"

Downloading a backup from the controller to another location

The backup file should be downloaded to a secure location. Choose the correct name now; you cannot rename the files later or you will get a file corruption error when you attempt to upload it for a restore.

NOTE: The file name must begin with sdn_controller_backup.

  • Download the File:

    curl --noproxy controller_ip 
    --header "X-Auth-Token:auth_token" --fail -ksSfL --request GET 
    --url "https://system_ip:8443/sdn/v2.0/backup>

Recommended backup practices

  • Do not run backup while making configuration changes. Instead, run the backup after completing configuration changes. Otherwise, an inconsistent system state could result with a subsequent restore.

  • Always back up all of the controllers in a team after a configuration change. Just backing up a subset of the controllers is not sufficient.

  • Back up all of controllers in a team at approximately the same time. (Team backups can be in sequence or in parallel). Do not allow days to pass in-between backups of different controllers in the same team.

  • A completed backup should be downloaded from the controller to another location for safekeeping. Include the IP address in the backup filename, so you can easily determine which backup belongs to which controller in a team. Recommended file naming is:


  • Store the backup files you take off each controller in the team together, so they can easily be retrieved for a future restore.

NOTE: If any controller in a team fails to complete the backup, start the backup over for all members of the controller team.

Examples of cURL commands in this guide use the --noproxy option, which is appropriate where execution of cURL commands do not need a proxy to access controllers. If your network is set up such that a proxy is needed to access controllers, use the --proxy option. For details on cURL proxy options, visit