Backup and Restore (B&R)
Introduction
A supported feature of cesapp is backing up and restoring the most important thing in a Cloudogu EcoSystem (CES): The user's data as well as data that is vital to a running CES instance. Backup and restore is powered by restic which features fast backup cycles combined with strong encryption.
This document describes some aspects of B&R that go beyond day-to-day usage.
What is a Backup?
This chapter describes what makes a backup created by the cesapp.
In terms of backing up data, a CES consists of several individual points of data:
- Dogu meta data (
dogu.json) - Dogu volumes that contain the dogu's production data
- CES instance configuration
- registry data for dogus and the instance
As a cesapp design decision, each point of data is backed up with a single restic snapshot in order to gain precise control. A snapshot is restic's own way to make saved files and directories addressable. A snapshot ID identifies uniquely a single snapshot. In a way a snapshot ID is roughly comparable to Git commit hashes.
The result of a CES backup is a list of many snapshots. The cesapp hides this complexity by grouping all snapshots so a backup can be easily addressed by the administrator. Technically, all restic snapshots are tagged with a uniquely generated Backup ID. When listing existing backups or even restoring to an earlier state, Backup IDs are the way to visualize and address the data from single backup runs.
Handling uninitialized backup repositories
This chapter describes how cesapp detects an uninitialized backup repository and how a necessary initialization is automated for the ease of use.
The cesapp supports the administrator in many ways and removes unnecessary and repetitive tasks while working with backups, including initializing a backup repository when necessary.
A restic repository is the place in which the backup data reside. Independently of the way where the backup data should be stored (local, S3, SFTP), a backup repository needs to be initialized in order to securely store data. This can be done exactly once and (the storage parameters aside) needs at least an encryption key.
restic does not provide a dedicated command to test if a backup repository has already been initialized. The usual way is to test it with restic snapshots, which may have two different outcomes, and how the cesapp reacts:
| Repository state | Exit code | Output | Reaction |
|---|---|---|---|
| uninitialized | 1 | unable to open config file or Is there a repository at the following location? |
cesapp initializes a backup repository at the configured address with the configured encryption key. |
| initialized | 0 | a list with zero or more snapshots | cesapp keeps the configured backup repository as-is, neglects the snapshot information, and proceeds with the original backup command. |
Any cesapp command that touches a backup repository will check if a backup repository has been initialized beforehand in such a way. If this is not the case, the cesapp will automatically initialize the repository with the data provided by the CES registry.
Handling wrong encryption keys
This chapter describes what happens if a wrong encryption key was provided.
In the previous chapter we learned that a backup repository must be secured with an encryption key. restic does not provide a dedicated command to test if the given encryption key matches with that of the backup repository. Given the repository was already initialized, a usual way to test the correctness of the encryption key is to execute restic snapshots.
Since we do not know if the repository was initialized beforehand, that call may result in these different outcomes, and how the cesapp reacts:
| Repository state | encryption key | Exit code | Output | Reaction |
|---|---|---|---|---|
| uninitialized | * | 1 | Fatal: unable to open config file or Is there a repository at the following location? |
cesapp initializes a backup repository; see above |
| initialized | incorrect | 1 | Fatal: wrong password or no key found |
cesapp fails the backup command with an appropriate error message |
| initialized | correct | 0 | a list with zero or more snapshots | cesapp keeps the configured backup repository as-is, neglects the snapshot information, and proceeds with the original backup command. |