Documentation:

ubos-admin restore

See also Command reference.

This command:

% sudo ubos-admin restore <arguments>

supports a number of different use cases:

  • Restore all Sites and all Apps contained in the backup to the same configuration as at the time of the backup. This includes hostnames, context paths, other customization, and even TLS keys and certificates (assuming the backup file contains all of those)
  • Restore only some Sites or Apps contained in the backup.
  • Restore Sites or Apps to different hostnames and/or context paths than they had been deployed to at the time the backup was created.
  • Restore an App and its data, installed at one Site, to a different Site.

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

Generally, UBOS 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 those Apps and Accessories. Depending on the command-line options, this may involve creating an entirely new Site, or modifying an existing Site.
  • While a new Site is created or an existing Site is modified, UBOS suspends the Site and replaces it 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. (See also ubos-admin backup.)
  • 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.
  • The App‘s and Accessoriesupgraders are run (see Roles section), 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 than it currently installed on the device.
  • The Site is resumed, and the placeholder 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.

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, the App or Accessory, 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.

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

See also: ubos-admin backup, ubos-admin backupinfo.