Command: ubos-admin restore

Running

To see the supported options, invoke ubos-admin restore --help.

This command must be run as root (sudo ubos-admin restore).

Understanding

This command:

% sudo ubos-admin restore <arguments>

supports a number of different use cases:

• Restore all Sites (including all Apps and Accessories contained in the provided UBOS backup file to the same configuration as at the time of when the backup file had been created. This includes Hostnames, Context Paths, Customization Points, and even SSL/TLS keys and certificates (assuming the backup file contains all of those).

• Restore only some Sites contained in the backup file.

• Restore only some of the AppConfigurations of some of the Sites contained in the backup file.

• Restore Sites or AppConfigurations to different hostnames and/or context paths than they had been deployed to at the time the backup file had been created.

• Restore an AppConfiguration and its data that had been deployed to one Site at the time the backup file had been created, to a different Site on the current Device.

• Restore an AppConfiguration that ran some App A at the time the backup file had been created, to an AppConfiguration running some other App B on the current Device. This allows migration of data from one App to another; however, it assumes that App B understands what to do with data that comes in the form App would have expected it.

During restore, UBOS generally performs the following actions:

• It examines the meta-data contained in the backup file, to determine which Apps and Accessories are required to use the to-be-restored data.

• It installs the Packages for the required Apps and Accessories, and their dependencies, unless they are already installed.

• It deploys the relevant Sites. Depending on the command-line options, this may recreate Sites as they were in the backup file, create an entirely new Site, or modify an existing Site.

• Whenever a new Site is created or an existing Site is modified, UBOS suspends the Site and replaces its web interface with a placeholder page.

• UBOS walks through the UBOS Manifest of the involved Apps and Accessories, and restores each of the AppConfigItems whose retention fields have been set.

• The actual restore performed depends on the type of AppConfigItem. For example, a MySQL database will be created and imported, while files and directories are simply copied into the right place, potentially adjusting permissions according to the UBOS Manifest.

• The upgraders of the Apps and Accessories are run, so the imported data can be migrated to the structure needed by the current versions of the Apps and Accessories. This supports the situation where the backup was created with an older version of an App or Accessory than is currently installed on the Device and some form of data migration needs to be performed before the new version can run.

• The Site is resumed, and the placeholder web page is removed.

This command internally uses a plug-in architecture, which allows the support of alternate backup formats without changing the invocation by the user.

Restoring to different versions of the App or Accessory

When a backup is restored, it is possible (likely?) that the version of the App or Accessory currently available is different (newer) than the version of the App or Accessory that ran at the time the backup was created: after all, likely some time has passed between when a backup was created and when it needs to be restored.

UBOS itself does not (and in fact cannot) migrate data from old versions of Apps or Accessories to new ones. This is the responsibility of the App or Accessory developer. This is what the upgraders field in the UBOS Manifest is for: run code that will upgrade the data.

Renaming retention buckets

Particular care needs to be take when an App or Accessory changes the numbers or names of its retention buckets. UBOS matches the content of a bucket by name, and does NOT restore the content of buckets whose name is not specified in the UBOS Manifest any more. Conversely, when adding an additional bucket from one version to another, the App or Accessory must be tolerant of the situation that during upgrades or restores, that bucket will be empty as UBOS cannot restore any data into it.

A good strategy for a developer is to never rename retention buckets.

Multi-step upgrades

Developers are encouraged to support multi-step upgrades, in which their upgrade scripts are able to migrate the data from older versions (and not just the most recent previous version) of their App or Accessory to the most recent one. This enables users to restore their data even from older backups.

See also:

• Command reference
• Command: ubos-admin backup
• Command: ubos-admin restore