sys/contrib/openzfs/man/man8/zdb.8

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