Backing up a controller

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

Controller databases
License compliance history and metrics log data
In a teaming environment, the teaming configuration
User repository folder (for user-installed applications)
Controller configuration folder
Application data for applications that have implemented backup/restore functionality.


	CAUTION: The controller does not back up the `sdnjar_trust.jks` file or existing keystore and truststore files in the `/opt/sdn/admin` directory. If you have CA signed certificates or you have added third party applications to the controller, you must back these files up separately and recover them after restoration.

For backing up and restoring, Hewlett Packard Enterprise recommends that you use off-the-shelf solutions such as rsync or Amanda. If your applications use the controller's backup and restore service and you are using Cassandra, then consider the following:

To back up Cassandra, set the backupLockSeconds configurable Cassandra lock timer parameter to the size of the data being backed up, the default is 10 minutes. Depending on the size of the backup, Cassandra could be locked for up to 10 minutes.
If the applications that are using Cassandra encounter a lock timed out failure during the backup, increase the timer. The failure will generate an error message Cassandra lock timed out before backup was finished. in the /var/log/sdn/virgo/logs/log.log file.
To configure the backupLockSeconds parameter:
1. Login to the GUI.
2. Click Configurations.
3. From the list of configurations, click com.hp.sdn.teaming.impl.CassandraProcessManager.
4. Click Modify.
See Configuration components.

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 http://curl.haxx.se/docs/manpage.html.

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 gigabytes 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. Acquire the authentication token for the controller backup:

curl --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, Hewlett Packard Enterprise recommends that you disable command history prior to executing commands containing credential information.

If needed, increase the Cassandra backupLockSeconds configuration using the GUI. See Configuration components.

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"

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 
"https://controller_ip:8443/sdn/v2.0/systems/controller_uid" 
--data-binary '{"system":{"ip":"controller_ip"}}'

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"

Get the checksum to verify the backup file has not been corrupted.

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

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 Backup.zip File:

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

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:
- sdn_controller_backup_ip-address.zip
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.

prev	up	next
Backing up and restoring	home	Restoring a controller from a backup