From 4fe9cc54374479652aed431f54c44bb209f6635f Mon Sep 17 00:00:00 2001 From: Rob N Date: Wed, 1 Mar 2023 12:35:33 +1100 Subject: [PATCH] man: note that zdb operates directly on pool storage A frequent misunderstanding is that zdb accesses the pool through the kernel or filesystem, leading to confusion particularly when it can't access something that it seems like it should be able to. I've seen this confusion recently when zdb couldn't access a pool because the user didn't have permission to read directly from the block devices, and when it couldn't show attributes of encrypted files even though the dataset was unlocked. The manpage already speaks to another symptom of this, namely that zdb may "behave erratically" on an active pool; here I'm trying to make that a little more explicit. Reviewed-by: Richard Yao Reviewed-by: Brian Behlendorf Reviewed-by: George Melikov Signed-off-by: Rob Norris Closes #14539 --- man/man8/zdb.8 | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/man/man8/zdb.8 b/man/man8/zdb.8 index db99ff65d..a1447a132 100644 --- a/man/man8/zdb.8 +++ b/man/man8/zdb.8 @@ -103,6 +103,12 @@ characters, it is interpreted as a pool name. The root dataset can be specified as .Qq Ar pool Ns / . .Pp +.Nm +is an +.Qq offline +tool; it accesses the block devices underneath the pools directly from +userspace and does not care if the pool is imported or datasets are mounted +(or even if the system understands ZFS at all). When operating on an imported and active pool it is possible, though unlikely, that zdb may interpret inconsistent pool data and behave erratically. .