[lxc-devel] [lxd/master] doc: Rework backup documentation

[stgraber on Github]

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 370 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20181009/36baa0d6/attachment.bin>
-------------- next part --------------
From 88088f4f407331fed42ae5dd7c90b1eba2b234fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber at ubuntu.com>
Date: Tue, 9 Oct 2018 17:12:39 -0400
Subject: [PATCH] doc: Rework backup documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #5113

Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>
---
 doc/backup.md | 94 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 52 insertions(+), 42 deletions(-)

diff --git a/doc/backup.md b/doc/backup.md
index 29664f30fd..e8bfdff841 100644
--- a/doc/backup.md
+++ b/doc/backup.md
@@ -1,58 +1,68 @@
-# LXD Backup Strategies
+# Backing up a LXD server
+## What to backup
+When planning to backup a LXD server, consider all the different objects
+that are stored/managed by LXD:
 
-To backup a LXD instance different strategies are available.
+ - Containers (database records and filesystems)
+ - Images (database records, image files and filesystems)
+ - Networks (database records and state files)
+ - Profiles (database records)
+ - Storage volumes (database records and filesystems)
+
+Only backing up the database or only backing up the container filesystem
+will not get you a fully functional backup.
+
+In some disaster recovery scenarios, that may be reasonable but if your
+goal is to get back online quickly, consider all the different pieces of
+LXD you're using.
 
 ## Full backup
-This requires that the whole `/var/lib/lxd` or
-`/var/snap/lxd/common/lxd` (for the snap) folder be backuped up.
-Additionally, it is necessary to backup all storage pools as well.
+A full backup would include the entirety of `/var/lib/lxd` or
+`/var/snap/lxd/common/lxd` for snap users.
 
-In order to restore the LXD instance the old `lxd` folder needs to be
-removed and replaced with the `lxd` snapshot. All storage pools need to
-be restored as well.
+You will also need to appropriately backup any external storage that you
+made LXD use, this can be LVM volume groups, ZFS zpools or any other
+resource which isn't directly self-contained to LXD.
 
-## Secondary LXD
-This requires a second LXD instance to be setup and reachable from the LXD
-instance that is to be backed up. Then, all containers can be copied to the
-secondary LXD instance for backup.
+Restoring involves stopping LXD on the target server, wiping the lxd
+directory, restoring the backup and any external dependency it requires.
 
-## Container backup and restore
-Additionally, LXD maintains a `backup.yaml` file in each container's storage
-volume. This file contains all necessary information to recover a given
-container, such as container configuration, attached devices and storage.
-This file can be processed by the `lxd import` command.
+Then start LXD again and check that everything works fine.
+
+## Secondary backup LXD server
+LXD supports copying and moving containers and storage volumes between two hosts.
 
-Running 
+So with a spare server, you can copy your containers and storage volumes
+to that secondary server every so often, allowing it to act as either an
+offline spare or just as a storage server that you can copy your
+containers back from if needed.
 
-```bash
-lxd import <container-name>
-```
+## Container backups
+The `lxc export` command can be used to export containers to a backup tarball.
+Those tarballs will include all snapshots by default and an "optimized"
+tarball can be obtained if you know that you'll be restoring on a LXD
+server using the same storage pool backend.
 
-will restore the specified container from its `backup.yaml` file.  This
-recovery mechanism is mostly meant for emergency recoveries and will try to
-re-create container and storage database entries from a backup of the storage
-pool configuration.
+Those tarballs can be saved any way you want on any filesystem you wan
+and can be imported back into LXD using the `lxc import` command.
 
-Note that the corresponding storage volume for the container must exist and be
-accessible before the container can be imported.  For example, if the
-container's storage volume got unmounted the user is required to remount it
-manually.
+## Disaster recovery
+Additionally, LXD maintains a `backup.yaml` file in each container's storage
+volume. This file contains all necessary information to recover a given
+container, such as container configuration, attached devices and storage.
 
-The container must be available under
-`/var/lib/lxd/storage-pools/POOL-NAME/containers/NAME` or
-`/var/snap/lxd/common/lxd/storage-pools/POOL-NAME/containers/NAME`
-in the case of the LXD snap.
+This file can be processed by the `lxd import` command, not to
+be confused with `lxc import`.
 
-LXD will then locate the container and read its `backup.yaml` file,
-creating any missing database entry.
+To use the disaster recovery mechanism, you must mount the container's
+storage to its expected location, usually under
+`storage-pools/NAME-OF-POOL/containers/NAME-OF-CONTAINER`.
 
+Depending on your storage backend you will also need to do the same for
+any snapshot you want to restore (needed for `dir` and `btrfs`).
+
+Once everything is mounted where it should be, you can now run `lxd import NAME-OF-CONTAINER`.
 
 If any matching database entry for resources declared in `backup.yaml` is found
 during import, the command will refuse to restore the container.  This can be
-overridden running 
-
-```bash
-lxd import --force <container-name>
-```
-
-which causes LXD to delete and replace any currently existing db entries.
+overridden by passing `--force`.