From c58266504ea2af09b12e9dae1f6e93a4880cc8c4 Mon Sep 17 00:00:00 2001 From: Qu Wenruo Date: Mon, 8 Jul 2024 13:17:06 +0930 Subject: [PATCH] btrfs-progs: docs: add warning for -s option of btrfs-image The filename sanitization is not recommended as it introduces mismatches between DIR_ITEM and INODE_REF. Even hash collision mode (double "-s" option) is not ensured to always find a hash collision, and when fails to find one, a mismatch happens. And when a mismatch happens, the kernel will not resolve the path correctly since kernel uses the hash from DIR_ITEM to lookup the child inode. So add a warning into the "-s" option of btrfs-image. Signed-off-by: Qu Wenruo --- Documentation/btrfs-image.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/Documentation/btrfs-image.rst b/Documentation/btrfs-image.rst index a63b0da2..d2d17608 100644 --- a/Documentation/btrfs-image.rst +++ b/Documentation/btrfs-image.rst @@ -37,13 +37,17 @@ OPTIONS file system will not be able to be mounted. -s - Sanitize the file names when generating the image. One -s means just - generate random garbage, which means that the directory indexes won't match up - since the hashes won't match with the garbage filenames. Using *-s* will - calculate a collision for the filename so that the hashes match, and if it - can't calculate a collision then it will just generate garbage. The collision - calculator is very time and CPU intensive so only use it if you are having - problems with your file system tree and need to have it mostly working. + Sanitize the file names when generating the image. Not recommended as + this would introduce new file name hash mismatches, thus if your + problem involves subvolume tress, it can even mask existing problems. + Furthermore kernels can not do proper path resolution due to the + introduced hash mismatches. + + One *-s* means just generate random garbage, which means that the + directory hash won't match its file names. Using two *-s* will + calculate a collision for the file name so that the hashes match, and + if it can't calculate a collision then it will just generate garbage. + The collision calculator is very time and CPU intensive. -w Walk all the trees manually and copy any blocks that are referenced. Use this