From c2022a5b2f9b58c59259423427547b8ba7360652 Mon Sep 17 00:00:00 2001
From: Axel Burri <axel@tty0.ch>
Date: Mon, 9 Jul 2018 16:01:07 +0200
Subject: [PATCH] documentation: add text for "subvolume ." configuration

---
 ChangeLog                 |  1 +
 doc/FAQ.md                | 65 ++++++++++++++++-----------------------
 doc/btrbk.conf.5.asciidoc |  9 ++++++
 3 files changed, 36 insertions(+), 39 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 177aa5c..e500c87 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,6 +4,7 @@ btrbk-0.27.0-dev
     - update ssh_filter_btrbk.sh on remote hosts (btrbk always calls
       "readlink" and "cat /proc/self/mounts").
   * Add "preserve_hour_of_day" configuration option (close #202).
+  * Allow backup of filesystem root using "subvolume ." (close #240).
   * Bugfix: correct scheduling of "first weekly backup in month/year"
     (close #217). Note that this change may result in (previously
     preserved) backups to be deleted!
diff --git a/doc/FAQ.md b/doc/FAQ.md
index 53fb57d..48f2c1a 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -35,35 +35,22 @@ nothing is deleted, add the btrbk command line options `--preserve
 --override=snapshot_create=always`.
 
 
-Why is it not possible to backup '/' (btrfs root) ?
+Why is "subvolume ." configuration not recommended?
 ---------------------------------------------------
 
-or in other words: why does this config not work:
-
-/etc/btrbk/btrbk.conf:
+Referring to a btrbk configuration like this:
 
     volume /
-      subvolume /
+      subvolume .
         snapshot_name rootfs
 
-*ERROR: Only relative files allowed for option "subvolume"*.
+Btrbk is designed to operate on the subvolumes *within* a root
+subvolume. In the config above, the btrbk snapshots would be created
+*inside* the source subvolume, altering it (from user perspective).
+From btrfs perspective this is not a problem, as the snapshots are
+separate subvolumes referring to the source subvolume and mapped into
+the file system tree below the source subvolume.
 
-
-### Answer
-
-btrbk is designed to never alter your source subvolume. In the config
-above, the btrbk snapshots would be created *inside* the source
-subvolume, altering it.
-
-The same applies to **any "btrfs root" mount point** (subvolid=5). In
-the example below, you will **not be able to backup** `/mnt/data`
-using btrbk:
-
-/etc/fstab:
-
-    /dev/sda1  /mnt/data  btrfs  subvolid=5 [...]
-
-btrbk is designed to operate on the subvolumes *within* `/mnt/data`.
 The recommended way is to split your data into subvolumes, e.g.:
 
      # btrfs subvolume create /mnt/data/www
@@ -86,23 +73,6 @@ The btrbk configuration for this would be:
         [...]
 
 
-### Tech Answer
-
-While *btrfs root* (subvolid=5) is a regular subvolume, it is still
-special: being the root node, it does not have a "name" inside the
-subvolume tree.
-
-Here, `/mnt/btr_pool` is mounted with `subvolid=5`:
-
-    # btrfs sub show /mnt/btr_pool/
-    /mnt/btr_data is toplevel subvolume
-
-    # btrfs sub show /mnt/btr_pool/rootfs
-    /mnt/btr_pool/rootfs
-            Name:    rootfs
-            uuid:    [...]
-
-
 How should I organize my btrfs filesystem?
 ------------------------------------------
 
@@ -323,3 +293,20 @@ Finally, don't forget to delete the broken source subvolume:
 
 You should now have a clean environment, and btrbk will not complain
 any more.
+
+
+I'm getting an error: Aborted: subvolume has no UUID
+----------------------------------------------------
+
+If your file system was created with btrfs-progs < 4.16, the btrfs
+root subvolume (id=5) has no UUID. You can check this by calling:
+
+    # btrfs subvolume show /mnt/btr_pool
+    /
+        Name:    <FS_TREE>
+        UUID:    -
+        [...]
+
+Without a UUID, the snapshots would get no parent_uuid, leaving btrbk
+unable to track parent/child relationships. In this case, btrbk
+refuses to create snapshots and backups.
diff --git a/doc/btrbk.conf.5.asciidoc b/doc/btrbk.conf.5.asciidoc
index cb17aba..7b2f719 100644
--- a/doc/btrbk.conf.5.asciidoc
+++ b/doc/btrbk.conf.5.asciidoc
@@ -52,6 +52,15 @@ SECTIONS
     specified in the 'volume' section. Multiple 'subvolume' sections
     are allowed within 'volume' sections. Accepts wildcard character
     "*".
++
+--
+If set to ".", the subvolume at '<volume-directory>' is used as backup
+source, and the snapshots will be created within the source subvolume
+itself (see 'snapshot_dir' option below), which is not recommended.
+Note that if this subvolume is btrfs root (id=5), it needs to have a
+valid UUID, which is not the case for file systems created with
+btrfs-progs < 4.16.
+--
 
 *target* <type> <target-directory>|<url>::
     Target type and directory where the backup subvolumes are to be