From 308444f3ede8c5dee8d9c6ede4bac7fa063e4f1c Mon Sep 17 00:00:00 2001
From: Axel Burri <axel@tty0.ch>
Date: Sat, 20 Jan 2018 18:05:33 +0100
Subject: [PATCH] documentation: FAQ.md: add warning on "dd" usage for disk
 cloning

---
 doc/FAQ.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/FAQ.md b/doc/FAQ.md
index 2b82d6e..53fb57d 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -262,6 +262,28 @@ if a single stream gets corrupted, making all subsequent streams
 unusable.
 
 
+### Warning: Avoid using "dd" on btrfs filesystems!
+
+If you use `dd` (e.g. in order to clone a partition), make sure you
+don't mount the cloned filesystem at the same time as the original
+one. You will end up having multiple filesystems **sharing identical
+UUID**, which will break things. If you _really_ want to do this, make
+sure to run:
+
+    btrfstune -u /dev/sdaX
+
+which changes the UUID of the given device. Note that the btrfs
+subvolumes still share identical UUID's, but at least the kernel can
+cope with it (see
+[this post on stackexchange](https://unix.stackexchange.com/questions/246976/btrfs-subvolume-uuid-clash)
+).
+
+Btrbk on the other hand relies on subvolume UUID's being *universally
+unique*, and uses them as hash keys for identifying and caching
+filesystem and subvolume trees, which leads to undefined behavior if
+multiple identical UUID's are processed.
+
+
 I'm getting an error: Aborted: "Received UUID" is set
 -----------------------------------------------------