Networked Media Open Specifications

Backup & restore

←IS-04 interactions · Index↑

Supporting backup & restore is a key feature of IS-14. In addition to supporting full back and full restore to the same device, IS-14 enables partial backup and partial restore to the same device or a different device. To discuss the various possible combinations of backup and restore, this section utilizes terms explained in the Definitions section.

The Configuration API defines a bulkProperties endpoint which allows:

These mechanisms are used for enabling backup and restore functionality and this section of the specification aims to cover the expectations, behaviour and requirements for the following scenarios:

Note: This does not mean that the backup & restore functionality can only be used in these scenarios.

Definitions

A device, for the purposes of this section, is a physical or logical entity that can be backed up and restored using the procedures described. It may or may not correspond to an IS-04 Device or IS-04 Node.

Backup data set is the set of data retrieved from a device using the backup procedures described. This is represented as an NcBulkValuesHolder object.

Device revision represents any combination of software versions (this includes firmware) and hardware revision that dictates the functionality of the device. As a vendor evolves a product through its lifecycle the hardware, software and/or firmware that make up a device is likely to change. From time to time customers install new software or firmware issued by the vendor that changes how a device behaves. Changes to a device’s hardware, such a peripherals or plug-in cards added or removed, could also change its behaviour. Each of these changes can affect how easily a backup data set is restored to a device. The device revision is used to represent the ensemble of the versions of all the various components that affect a device’s functionality. It is up to a vendor to decide what changes to a device represent a change of device revision. A software upgrade will likely result in a device being considered to have a different device revision but a vendor could decide that a change in, for example, PCB colour does not represent a different device revision.

Backup validation fingerprint is an optional string in a backup data set that can be used to capture the various versions of the hardware, software and/or firmware that made up a device at the time the backup was performed. The backup validation fingerprint can be used by a device to help decide whether the backup data set being restored to it is compatible. The format of the string is defined by the vendor and is opaque to other systems. This could contain information such as:

A compatible revision is a change of device revision such that all of the backup data set taken before the revision can be successfully validated by the modified device. If the backup data set can not be successfully validated it is said to be an incompatible revision.

A device model in the context of this specification refers to all the objects and their properties which are exposed in the configuration API.

A full backup is a backup data set that includes all properties for all role paths of a device model. This is achieved by using the /bulkProperties endpoint.

A partial backup is a backup data set that includes only a subset of role paths of a device model. This is achieved by using the /bulkProperties endpoint.

A modified backup is a full backup or partial backup where the backup data set has been modified by a client. Examples of modified backups include: updating values of existing backup data set properties, adding/removing device model role paths from the backup data set.

A complete restore occurs when all properties for all role paths in a full backup or partial backup are successfully applied to a device. This is achieved by using the /bulkProperties endpoint.

An incomplete restore occurs when some properties of a full backup or partial backup are not successfully applied to a device. This might occur when a backup data set is restored to an incompatible revision. This is achieved by using the /bulkProperties endpoint.

A selective restore is a restore in which a subset from a backup data set is applied to a device. This is achieved by using the /bulkProperties endpoint.

1. Performing a backup

Creating a backup is performed by using the bulkProperties endpoint of a device alongside the Get verb.

In order to retrieve the whole device model (full backup), requests MUST use root as the rolePath. The response contains a validationFingerprint and the values of all the role paths in the device model.

Performing a full backup
Performing a full backup

Partial backups can be created by choosing other role paths. The scope of backups can further be restricted by using a query parameter of recurse=false which will only include the properties of the targeted role path.

It is RECOMMENDED to store the backup file in its entirety and not remove elements from the data set as they might contain dependencies required by some of the role paths.

2. Restoring on a device with a compatible revision

Assuming a full backup of the device was created and is intended to be restored on a device with a compatible revision then the first step is to perform a Validation request to check if the backup can be successfully restored.

In order to validate the whole device model (validating a full backup), requests MUST use root as the rolePath.

The request body MUST include:

Validating a full backup
Validating a full backup

The response MUST include a collection of all target device model role paths with a validation status property. For role paths which have a status other than Ok the response MUST also include a statusMessage with details of why the validation failed.

The backup can be restored by performing a Set request to restore the backup.

In order to restore the whole device model (restoring a full backup), requests MUST use root as the rolePath.

The request body MUST include:

Restoring a full backup
Restoring a full backup

The response MUST include a collection of all target device model role paths with a restore status property. For role paths which have a status other than Ok the response MUST also include a statusMessage with details of why the restore failed.

Devices MUST allow fully restoring backups created from a compatible revision.

Devices MUST allow an incomplete restore of backups when the validation response has at least one role path status of Ok when supplying the allowIncomplete argument of true in the request.

Devices MUST allow a complete restore of modified backups when all the role paths have an Ok status in the validation response.

Devices MUST allow an incomplete restore of modified backups when the validation response has at least one role path status of Ok when supplying the allowIncomplete argument of true in the request.

If devices require a system reboot in order to apply a complete restore or an incomplete restore then they MUST perform this immediately after responding to the restore request.

3. Restoring on a device with an incompatible revision

Restoring follows a similar workflow with the difference that the restore device does not have a compatible revision.

Restoring on a different device revision
Restoring on a different device revision

Devices MUST allow an incomplete restore of backups when the validation response has at least one role path status of Ok when supplying the allowIncomplete argument of true in the request.

// TBD: Facilities can have a multitude of instances of the same device type. Backups performed on a device instance can be used to bootstrap other instances of the same device type. What if the new device overwrites things like IP addresses? Are we saying the restore should be used as a bootstrap mechanism (do we need a isTemplate boolean flag when restoring)?

←IS-04 interactions · Index↑