| blob | ae35454ad0836d19f1c1698c3cc426bef4506b4f |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\" Copyright 2012, Richard Lowe.
12 .\" Copyright (c) 2012, 2019 by Delphix. All rights reserved.
13 .\" Copyright 2017 Nexenta Systems, Inc.
14 .\" Copyright (c) 2017 Lawrence Livermore National Security, LLC.
15 .\" Copyright (c) 2017 Intel Corporation.
16 .\"
17 .Dd October 27, 2024
18 .Dt ZDB 8
19 .Os
20 .
21 .Sh NAME
22 .Nm zdb
23 .Nd display ZFS storage pool debugging and consistency information
24 .Sh SYNOPSIS
25 .Nm
26 .Op Fl AbcdDFGhikLMNPsTvXYy
27 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
28 .Op Fl I Ar inflight-I/O-ops
29 .Oo Fl o Ar var Ns = Ns Ar value Oc Ns …
30 .Op Fl t Ar txg
31 .Op Fl U Ar cache
32 .Op Fl x Ar dumpdir
33 .Op Fl K Ar key
34 .Op Ar poolname Ns Op / Ns Ar dataset Ns | Ns Ar objset-ID
35 .Op Ar object Ns | Ns Ar range Ns …
36 .Nm
37 .Op Fl AdiPv
38 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
39 .Op Fl U Ar cache
40 .Op Fl K Ar key
41 .Ar poolname Ns Op Ar / Ns Ar dataset Ns | Ns Ar objset-ID
42 .Op Ar object Ns | Ns Ar range Ns …
43 .Nm
44 .Fl B
45 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
46 .Op Fl U Ar cache
47 .Op Fl K Ar key
48 .Ar poolname Ns Ar / Ns Ar objset-ID
49 .Op Ar backup-flags
50 .Nm
51 .Fl C
52 .Op Fl A
53 .Op Fl U Ar cache
54 .Op Ar poolname
55 .Nm
56 .Fl E
57 .Op Fl A
58 .Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15
59 .Nm
60 .Fl l
61 .Op Fl Aqu
62 .Ar device
63 .Nm
64 .Fl m
65 .Op Fl AFLPXY
66 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
67 .Op Fl t Ar txg
68 .Op Fl U Ar cache
69 .Ar poolname Op Ar vdev Oo Ar metaslab Oc Ns …
70 .Nm
71 .Fl O
72 .Op Fl K Ar key
73 .Ar dataset path
74 .Nm
75 .Fl r
76 .Op Fl K Ar key
77 .Ar dataset path destination
78 .Nm
79 .Fl R
80 .Op Fl A
81 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
82 .Op Fl U Ar cache
83 .Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags
84 .Nm
85 .Fl S
86 .Op Fl AP
87 .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns …
88 .Op Fl U Ar cache
89 .Ar poolname
90 .
91 .Sh DESCRIPTION
92 The
93 .Nm
94 utility displays information about a ZFS pool useful for debugging and performs
95 some amount of consistency checking.
96 It is a not a general purpose tool and options
97 .Pq and facilities
98 may change.
99 It is not a
100 .Xr fsck 8
101 utility.
102 .Pp
103 The output of this command in general reflects the on-disk structure of a ZFS
104 pool, and is inherently unstable.
105 The precise output of most invocations is not documented, a knowledge of ZFS
106 internals is assumed.
107 .Pp
108 If the
109 .Ar dataset
110 argument does not contain any
111 .Qq Sy /
112 or
113 .Qq Sy @
114 characters, it is interpreted as a pool name.
115 The root dataset can be specified as
116 .Qq Ar pool Ns / .
117 .Pp
118 .Nm
119 is an
120 .Qq offline
121 tool; it accesses the block devices underneath the pools directly from
122 userspace and does not care if the pool is imported or datasets are mounted
123 (or even if the system understands ZFS at all).
124 When operating on an imported and active pool it is possible, though unlikely,
125 that zdb may interpret inconsistent pool data and behave erratically.
126 .
127 .Sh OPTIONS
128 Display options:
129 .Bl -tag -width Ds
130 .It Fl b , -block-stats
131 Display statistics regarding the number, size
132 .Pq logical, physical and allocated
133 and deduplication of blocks.
134 .It Fl B , -backup
135 Generate a backup stream, similar to
136 .Nm zfs Cm send ,
137 but for the numeric objset ID, and without opening the dataset.
138 This can be useful in recovery scenarios if dataset metadata has become
139 corrupted but the dataset itself is readable.
140 The optional
141 .Ar flags
142 argument is a string of one or more of the letters
143 .Sy e ,
144 .Sy L ,
145 .Sy c ,
146 and
147 .Sy w ,
148 which correspond to the same flags in
149 .Xr zfs-send 8 .
150 .It Fl c , -checksum
151 Verify the checksum of all metadata blocks while printing block statistics
152 .Po see
153 .Fl b
154 .Pc .
155 .Pp
156 If specified multiple times, verify the checksums of all blocks.
157 .It Fl C , -config
158 Display information about the configuration.
159 If specified with no other options, instead display information about the cache
160 file
161 .Pq Pa /etc/zfs/zpool.cache .
162 To specify the cache file to display, see
163 .Fl U .
164 .Pp
165 If specified multiple times, and a pool name is also specified display both the
166 cached configuration and the on-disk configuration.
167 If specified multiple times with
168 .Fl e
169 also display the configuration that would be used were the pool to be imported.
170 .It Fl d , -datasets
171 Display information about datasets.
172 Specified once, displays basic dataset information: ID, create transaction,
173 size, and object count.
174 See
175 .Fl N
176 for determining if
177 .Ar poolname Ns Op / Ns Ar dataset Ns | Ns Ar objset-ID
178 is to use the specified
179 .Ar dataset Ns | Ns Ar objset-ID
180 as a string (dataset name) or a number (objset ID) when
181 datasets have numeric names.
182 .Pp
183 If specified multiple times provides greater and greater verbosity.
184 .Pp
185 If object IDs or object ID ranges are specified, display information about
186 those specific objects or ranges only.
187 .Pp
188 An object ID range is specified in terms of a colon-separated tuple of
189 the form
190 .Ao start Ac : Ns Ao end Ac Ns Op : Ns Ao flags Ac .
191 The fields
192 .Ar start
193 and
194 .Ar end
195 are integer object identifiers that denote the upper and lower bounds
196 of the range.
197 An
198 .Ar end
199 value of -1 specifies a range with no upper bound.
200 The
201 .Ar flags
202 field optionally specifies a set of flags, described below, that control
203 which object types are dumped.
204 By default, all object types are dumped.
205 A minus sign
206 .Pq -
207 negates the effect of the flag that follows it and has no effect unless
208 preceded by the
209 .Ar A
210 flag.
211 For example, the range 0:-1:A-d will dump all object types except for
212 directories.
213 .Pp
214 .Bl -tag -compact -width Ds
215 .It Sy A
216 Dump all objects (this is the default)
217 .It Sy d
218 Dump ZFS directory objects
219 .It Sy f
220 Dump ZFS plain file objects
221 .It Sy m
222 Dump SPA space map objects
223 .It Sy z
224 Dump ZAP objects
225 .It Sy -
226 Negate the effect of next flag
227 .El
228 .It Fl D , -dedup-stats
229 Display deduplication statistics, including the deduplication ratio
230 .Pq Sy dedup ,
231 compression ratio
232 .Pq Sy compress ,
233 inflation due to the zfs copies property
234 .Pq Sy copies ,
235 and an overall effective ratio
236 .Pq Sy dedup No \(mu Sy compress No / Sy copies .
237 .It Fl DD
238 Display a histogram of deduplication statistics, showing the allocated
239 .Pq physically present on disk
240 and referenced
241 .Pq logically referenced in the pool
242 block counts and sizes by reference count.
243 .It Fl DDD
244 Display the statistics independently for each deduplication table.
245 .It Fl DDDD
246 Dump the contents of the deduplication tables describing duplicate blocks.
247 .It Fl DDDDD
248 Also dump the contents of the deduplication tables describing unique blocks.
249 .It Fl E , -embedded-block-pointer Ns = Ns Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15
250 Decode and display block from an embedded block pointer specified by the
251 .Ar word
252 arguments.
253 .It Fl h , -history
254 Display pool history similar to
255 .Nm zpool Cm history ,
256 but include internal changes, transaction, and dataset information.
257 .It Fl i , -intent-logs
258 Display information about intent log
259 .Pq ZIL
260 entries relating to each dataset.
261 If specified multiple times, display counts of each intent log transaction type.
262 .It Fl k , -checkpointed-state
263 Examine the checkpointed state of the pool.
264 Note, the on disk format of the pool is not reverted to the checkpointed state.
265 .It Fl l , -label Ns = Ns Ar device
266 Read the vdev labels and L2ARC header from the specified device.
267 .Nm Fl l
268 will return 0 if valid label was found, 1 if error occurred, and 2 if no valid
269 labels were found.
270 The presence of L2ARC header is indicated by a specific
271 sequence (L2ARC_DEV_HDR_MAGIC).
272 If there is an accounting error in the size or the number of L2ARC log blocks
273 .Nm Fl l
274 will return 1.
275 Each unique configuration is displayed only once.
276 .It Fl ll Ar device
277 In addition display label space usage stats.
278 If a valid L2ARC header was found
279 also display the properties of log blocks used for restoring L2ARC contents
280 (persistent L2ARC).
281 .It Fl lll Ar device
282 Display every configuration, unique or not.
283 If a valid L2ARC header was found
284 also display the properties of log entries in log blocks used for restoring
285 L2ARC contents (persistent L2ARC).
286 .Pp
287 If the
288 .Fl q
289 option is also specified, don't print the labels or the L2ARC header.
290 .Pp
291 If the
292 .Fl u
293 option is also specified, also display the uberblocks on this device.
294 Specify multiple times to increase verbosity.
295 .It Fl L , -disable-leak-tracking
296 Disable leak detection and the loading of space maps.
297 By default,
298 .Nm
299 verifies that all non-free blocks are referenced, which can be very expensive.
300 .It Fl m , -metaslabs
301 Display the offset, spacemap, free space of each metaslab, all the log
302 spacemaps and their obsolete entry statistics.
303 .It Fl mm
304 Also display information about the on-disk free space histogram associated with
305 each metaslab.
306 .It Fl mmm
307 Display the maximum contiguous free space, the in-core free space histogram, and
308 the percentage of free space in each space map.
309 .It Fl mmmm
310 Display every spacemap record.
311 .It Fl M , -metaslab-groups
312 Display all "normal" vdev metaslab group information - per-vdev metaslab count,
313 fragmentation,
314 and free space histogram, as well as overall pool fragmentation and histogram.
315 .It Fl MM
316 "Special" vdevs are added to -M's normal output.
317 Also display information about the maximum contiguous free space and the
318 percentage of free space in each space map.
319 .It Fl MMM
320 Display every spacemap record.
321 .It Fl N
322 Same as
323 .Fl d
324 but force zdb to interpret the
325 .Op Ar dataset Ns | Ns Ar objset-ID
326 in
327 .Op Ar poolname Ns Op / Ns Ar dataset Ns | Ns Ar objset-ID
328 as a numeric objset ID.
329 .It Fl O , -object-lookups Ns = Ns Ar dataset path
330 Look up the specified
331 .Ar path
332 inside of the
333 .Ar dataset
334 and display its metadata and indirect blocks.
335 Specified
336 .Ar path
337 must be relative to the root of
338 .Ar dataset .
339 This option can be combined with
340 .Fl v
341 for increasing verbosity.
342 .It Fl r , -copy-object Ns = Ns Ar dataset path destination
343 Copy the specified
344 .Ar path
345 inside of the
346 .Ar dataset
347 to the specified destination.
348 Specified
349 .Ar path
350 must be relative to the root of
351 .Ar dataset .
352 This option can be combined with
353 .Fl v
354 for increasing verbosity.
355 .It Xo
356 .Fl R , -read-block Ns = Ns Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags
357 .Xc
358 Read and display a block from the specified device.
359 By default the block is displayed as a hex dump, but see the description of the
360 .Sy r
361 flag, below.
362 .Pp
363 The block is specified in terms of a colon-separated tuple
364 .Ar vdev
365 .Pq an integer vdev identifier
366 .Ar offset
367 .Pq the offset within the vdev
368 .Ar size
369 .Pq the physical size, or logical size / physical size
370 of the block to read and, optionally,
371 .Ar flags
372 .Pq a set of flags, described below .
373 .Pp
374 .Bl -tag -compact -width "b offset"
375 .It Sy b Ar offset
376 Print block pointer at hex offset
377 .It Sy c
378 Calculate and display checksums
379 .It Sy d
380 Decompress the block.
381 Set environment variable
382 .Nm ZDB_NO_ZLE
383 to skip zle when guessing.
384 .It Sy e
385 Byte swap the block
386 .It Sy g
387 Dump gang block header
388 .It Sy i
389 Dump indirect block
390 .It Sy r
391 Dump raw uninterpreted block data
392 .It Sy v
393 Verbose output for guessing compression algorithm
394 .El
395 .It Fl s , -io-stats
396 Report statistics on
397 .Nm zdb
398 I/O.
399 Display operation counts, bandwidth, and error counts of I/O to the pool from
400 .Nm .
401 .It Fl S , -simulate-dedup
402 Simulate the effects of deduplication, constructing a DDT and then display
403 that DDT as with
404 .Fl DD .
405 .It Fl T , -brt-stats
406 Display block reference table (BRT) statistics, including the size of uniques
407 blocks cloned, the space saving as a result of cloning, and the saving ratio.
408 .It Fl TT
409 Display the per-vdev BRT statistics, including total references.
410 .It Fl TTT
411 Display histograms of per-vdev BRT refcounts.
412 .It Fl TTTT
413 Dump the contents of the block reference tables.
414 .It Fl u , -uberblock
415 Display the current uberblock.
416 .El
417 .Pp
418 Other options:
419 .Bl -tag -width Ds
420 .It Fl A , -ignore-assertions
421 Do not abort should any assertion fail.
422 .It Fl AA
423 Enable panic recovery, certain errors which would otherwise be fatal are
424 demoted to warnings.
425 .It Fl AAA
426 Do not abort if asserts fail and also enable panic recovery.
427 .It Fl e , -exported Ns = Ns Oo Fl p Ar path Oc Ns …
428 Operate on an exported pool, not present in
429 .Pa /etc/zfs/zpool.cache .
430 The
431 .Fl p
432 flag specifies the path under which devices are to be searched.
433 .It Fl x , -dump-blocks Ns = Ns Ar dumpdir
434 All blocks accessed will be copied to files in the specified directory.
435 The blocks will be placed in sparse files whose name is the same as
436 that of the file or device read.
437 .Nm
438 can be then run on the generated files.
439 Note that the
440 .Fl bbc
441 flags are sufficient to access
442 .Pq and thus copy
443 all metadata on the pool.
444 .It Fl F , -automatic-rewind
445 Attempt to make an unreadable pool readable by trying progressively older
446 transactions.
447 .It Fl G , -dump-debug-msg
448 Dump the contents of the zfs_dbgmsg buffer before exiting
449 .Nm .
450 zfs_dbgmsg is a buffer used by ZFS to dump advanced debug information.
451 .It Fl I , -inflight Ns = Ns Ar inflight-I/O-ops
452 Limit the number of outstanding checksum I/O operations to the specified value.
453 The default value is 200.
454 This option affects the performance of the
455 .Fl c
456 option.
457 .It Fl K , -key Ns = Ns Ar key
458 Decryption key needed to access an encrypted dataset.
459 This will cause
460 .Nm
461 to attempt to unlock the dataset using the encryption root, key format and other
462 encryption parameters on the given dataset.
463 .Nm
464 can still inspect pool and dataset structures on encrypted datasets without
465 unlocking them, but will not be able to access file names and attributes and
466 object contents. \fBWARNING:\fP The raw decryption key and any decrypted data
467 will be in user memory while
468 .Nm
469 is running.
470 Other user programs may be able to extract it by inspecting
471 .Nm
472 as it runs.
473 Exercise extreme caution when using this option in shared or uncontrolled
474 environments.
475 .It Fl o , -option Ns = Ns Ar var Ns = Ns Ar value Ns …
476 Set the given global libzpool variable to the provided value.
477 The value must be an unsigned 32-bit integer.
478 Currently only little-endian systems are supported to avoid accidentally setting
479 the high 32 bits of 64-bit variables.
480 .It Fl P , -parseable
481 Print numbers in an unscaled form more amenable to parsing, e.g.\&
482 .Sy 1000000
483 rather than
484 .Sy 1M .
485 .It Fl t , -txg Ns = Ns Ar transaction
486 Specify the highest transaction to use when searching for uberblocks.
487 See also the
488 .Fl u
489 and
490 .Fl l
491 options for a means to see the available uberblocks and their associated
492 transaction numbers.
493 .It Fl U , -cachefile Ns = Ns Ar cachefile
494 Use a cache file other than
495 .Pa /etc/zfs/zpool.cache .
496 .It Fl v , -verbose
497 Enable verbosity.
498 Specify multiple times for increased verbosity.
499 .It Fl V , -verbatim
500 Attempt verbatim import.
501 This mimics the behavior of the kernel when loading a pool from a cachefile.
502 Only usable with
503 .Fl e .
504 .It Fl X , -extreme-rewind
505 Attempt
506 .Qq extreme
507 transaction rewind, that is attempt the same recovery as
508 .Fl F
509 but read transactions otherwise deemed too old.
510 .It Fl Y , -all-reconstruction
511 Attempt all possible combinations when reconstructing indirect split blocks.
512 This flag disables the individual I/O deadman timer in order to allow as
513 much time as required for the attempted reconstruction.
514 .It Fl y , -livelist
515 Perform validation for livelists that are being deleted.
516 Scans through the livelist and metaslabs, checking for duplicate entries
517 and compares the two, checking for potential double frees.
518 If it encounters issues, warnings will be printed, but the command will not
519 necessarily fail.
520 .El
521 .Pp
522 Specifying a display option more than once enables verbosity for only that
523 option, with more occurrences enabling more verbosity.
524 .Pp
525 If no options are specified, all information about the named pool will be
526 displayed at default verbosity.
527 .
528 .Sh EXAMPLES
529 .Ss Example 1 : No Display the configuration of imported pool Ar rpool
530 .Bd -literal
531 .No # Nm zdb Fl C Ar rpool
532 MOS Configuration:
533 version: 28
534 name: 'rpool'
535 …
536 .Ed
537 .
538 .Ss Example 2 : No Display basic dataset information about Ar rpool
539 .Bd -literal
540 .No # Nm zdb Fl d Ar rpool
541 Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
542 Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
543 …
544 .Ed
545 .
546 .Ss Example 3 : No Display basic information about object 0 in Ar rpool/export/home
547 .Bd -literal
548 .No # Nm zdb Fl d Ar rpool/export/home 0
549 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
551 Object lvl iblk dblk dsize lsize %full type
552 0 7 16K 16K 15.0K 16K 25.00 DMU dnode
553 .Ed
554 .
555 .Ss Example 4 : No Display the predicted effect of enabling deduplication on Ar rpool
556 .Bd -literal
557 .No # Nm zdb Fl S Ar rpool
558 Simulated DDT histogram:
560 bucket allocated referenced
561 ______ ______________________________ ______________________________
562 refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE
563 ------ ------ ----- ----- ----- ------ ----- ----- -----
564 1 694K 27.1G 15.0G 15.0G 694K 27.1G 15.0G 15.0G
565 2 35.0K 1.33G 699M 699M 74.7K 2.79G 1.45G 1.45G
566 …
567 dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
568 .Ed
569 .
570 .Sh SEE ALSO
571 .Xr zfs 8 ,
572 .Xr zpool 8