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
 178 directories.
 179 .Pp
 180 .Bl -tag -compact -width Ds
 181 .It Sy A
 182 Dump all objects (this is the default)
 183 .It Sy d
 184 Dump ZFS directory objects
 185 .It Sy f
 186 Dump ZFS plain file objects
 187 .It Sy m
 188 Dump SPA space map objects
 189 .It Sy z
 190 Dump ZAP objects
 191 .It Sy -
 192 Negate the effect of next flag
 193 .El
 194 .It Fl D , -dedup-stats
 195 Display deduplication statistics, including the deduplication ratio
 196 .Pq Sy dedup ,
 197 compression ratio
 198 .Pq Sy compress ,
 199 inflation due to the zfs copies property
 200 .Pq Sy copies ,
 201 and an overall effective ratio
 202 .Pq Sy dedup No \(mu Sy compress No / Sy copies .
 203 .It Fl DD
 204 Display a histogram of deduplication statistics, showing the allocated
 205 .Pq physically present on disk
 206 and referenced
 207 .Pq logically referenced in the pool
 208 block counts and sizes by reference count.
 209 .It Fl DDD
 210 Display the statistics independently for each deduplication table.
 211 .It Fl DDDD
 212 Dump the contents of the deduplication tables describing duplicate blocks.
 213 .It Fl DDDDD
 214 Also dump the contents of the deduplication tables describing unique blocks.
 215 .It Fl E , -embedded-block-pointer Ns = Ns Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15
 216 Decode and display block from an embedded block pointer specified by the
 217 .Ar word
 218 arguments.
 219 .It Fl h , -history
 220 Display pool history similar to
 221 .Nm zpool Cm history ,
 222 but include internal changes, transaction, and dataset information.
 223 .It Fl i , -intent-logs
 224 Display information about intent log
 225 .Pq ZIL
 226 entries relating to each dataset.
 227 If specified multiple times, display counts of each intent log transaction type.
 228 .It Fl k , -checkpointed-state
 229 Examine the checkpointed state of the pool.
 230 Note, the on disk format of the pool is not reverted to the checkpointed state.
 231 .It Fl l , -label Ns = Ns Ar device
 232 Read the vdev labels and L2ARC header from the specified device.
 233 .Nm Fl l
 234 will return 0 if valid label was found, 1 if error occurred, and 2 if no valid
 235 labels were found.
 236 The presence of L2ARC header is indicated by a specific
 237 sequence (L2ARC_DEV_HDR_MAGIC).
 238 If there is an accounting error in the size or the number of L2ARC log blocks
 239 .Nm Fl l
 240 will return 1.
 241 Each unique configuration is displayed only once.
 242 .It Fl ll Ar device
 243 In addition display label space usage stats.
 244 If a valid L2ARC header was found
 245 also display the properties of log blocks used for restoring L2ARC contents
 246 (persistent L2ARC).
 247 .It Fl lll Ar device
 248 Display every configuration, unique or not.
 249 If a valid L2ARC header was found
 250 also display the properties of log entries in log blocks used for restoring
 251 L2ARC contents (persistent L2ARC).
 252 .Pp
 253 If the
 254 .Fl q
 255 option is also specified, don't print the labels or the L2ARC header.
 256 .Pp
 257 If the
 258 .Fl u
 259 option is also specified, also display the uberblocks on this device.
 260 Specify multiple times to increase verbosity.
 261 .It Fl L , -disable-leak-tracking
 262 Disable leak detection and the loading of space maps.
 263 By default,
 264 .Nm
 265 verifies that all non-free blocks are referenced, which can be very expensive.
 266 .It Fl m , -metaslabs
 267 Display the offset, spacemap, free space of each metaslab, all the log
 268 spacemaps and their obsolete entry statistics.
 269 .It Fl mm
 270 Also display information about the on-disk free space histogram associated with
 271 each metaslab.
 272 .It Fl mmm
 273 Display the maximum contiguous free space, the in-core free space histogram, and
 274 the percentage of free space in each space map.
 275 .It Fl mmmm
 276 Display every spacemap record.
 277 .It Fl M , -metaslab-groups
 278 Display all "normal" vdev metaslab group information - per-vdev metaslab count,
 279 fragmentation,
 280 and free space histogram, as well as overall pool fragmentation and histogram.
 281 .It Fl MM
 282 "Special" vdevs are added to -M's normal output.
 283 .It Fl O , -object-lookups Ns = Ns Ar dataset path
 284 Also display information about the maximum contiguous free space and the
 285 percentage of free space in each space map.
 286 .It Fl MMM
 287 Display every spacemap record.
 288 .It Fl N
 289 Same as
 290 .Fl d
 291 but force zdb to interpret the
 292 .Op Ar dataset Ns | Ns Ar objset-ID
 293 in
 294 .Op Ar poolname Ns Op / Ns Ar dataset Ns | Ns Ar objset-ID
 295 as a numeric objset ID.
 296 .It Fl O Ar dataset path
 297 Look up the specified
 298 .Ar path
 299 inside of the
 300 .Ar dataset
 301 and display its metadata and indirect blocks.
 302 Specified
 303 .Ar path
 304 must be relative to the root of
 305 .Ar dataset .
 306 This option can be combined with
 307 .Fl v
 308 for increasing verbosity.
 309 .It Fl r , -copy-object Ns = Ns Ar dataset path destination
 310 Copy the specified
 311 .Ar path
 312 inside of the
 313 .Ar dataset
 314 to the specified destination.
 315 Specified
 316 .Ar path
 317 must be relative to the root of
 318 .Ar dataset .
 319 This option can be combined with
 320 .Fl v
 321 for increasing verbosity.
 322 .It Xo
 323 .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
 324 .Xc
 325 Read and display a block from the specified device.
 326 By default the block is displayed as a hex dump, but see the description of the
 327 .Sy r
 328 flag, below.
 329 .Pp
 330 The block is specified in terms of a colon-separated tuple
 331 .Ar vdev
 332 .Pq an integer vdev identifier
 333 .Ar offset
 334 .Pq the offset within the vdev
 335 .Ar size
 336 .Pq the physical size, or logical size / physical size
 337 of the block to read and, optionally,
 338 .Ar flags
 339 .Pq a set of flags, described below .
 340 .Pp
 341 .Bl -tag -compact -width "b offset"
 342 .It Sy b Ar offset
 343 Print block pointer at hex offset
 344 .It Sy c
 345 Calculate and display checksums
 346 .It Sy d
 347 Decompress the block.
 348 Set environment variable
 349 .Nm ZDB_NO_ZLE
 350 to skip zle when guessing.
 351 .It Sy e
 352 Byte swap the block
 353 .It Sy g
 354 Dump gang block header
 355 .It Sy i
 356 Dump indirect block
 357 .It Sy r
 358 Dump raw uninterpreted block data
 359 .It Sy v
 360 Verbose output for guessing compression algorithm
 361 .El
 362 .It Fl s , -io-stats
 363 Report statistics on
 364 .Nm zdb
 365 I/O.
 366 Display operation counts, bandwidth, and error counts of I/O to the pool from
 367 .Nm .
 368 .It Fl S , -simulate-dedup
 369 Simulate the effects of deduplication, constructing a DDT and then display
 370 that DDT as with
 371 .Fl DD .
 372 .It Fl u , -uberblock
 373 Display the current uberblock.
 374 .El
 375 .Pp
 376 Other options:
 377 .Bl -tag -width Ds
 378 .It Fl A , -ignore-assertions
 379 Do not abort should any assertion fail.
 380 .It Fl AA
 381 Enable panic recovery, certain errors which would otherwise be fatal are
 382 demoted to warnings.
 383 .It Fl AAA
 384 Do not abort if asserts fail and also enable panic recovery.
 385 .It Fl e , -exported Ns = Ns Oo Fl p Ar path Oc Ns …
 386 Operate on an exported pool, not present in
 387 .Pa /etc/zfs/zpool.cache .
 388 The
 389 .Fl p
 390 flag specifies the path under which devices are to be searched.
 391 .It Fl x , -dump-blocks Ns = Ns Ar dumpdir
 392 All blocks accessed will be copied to files in the specified directory.
 393 The blocks will be placed in sparse files whose name is the same as
 394 that of the file or device read.
 395 .Nm
 396 can be then run on the generated files.
 397 Note that the
 398 .Fl bbc
 399 flags are sufficient to access
 400 .Pq and thus copy
 401 all metadata on the pool.
 402 .It Fl F , -automatic-rewind
 403 Attempt to make an unreadable pool readable by trying progressively older
 404 transactions.
 405 .It Fl G , -dump-debug-msg
 406 Dump the contents of the zfs_dbgmsg buffer before exiting
 407 .Nm .
 408 zfs_dbgmsg is a buffer used by ZFS to dump advanced debug information.
 409 .It Fl I , -inflight Ns = Ns Ar inflight-I/O-ops
 410 Limit the number of outstanding checksum I/O operations to the specified value.
 411 The default value is 200.
 412 This option affects the performance of the
 413 .Fl c
 414 option.
 415 .It Fl o , -option Ns = Ns Ar var Ns = Ns Ar value Ns …
 416 Set the given global libzpool variable to the provided value.
 417 The value must be an unsigned 32-bit integer.
 418 Currently only little-endian systems are supported to avoid accidentally setting
 419 the high 32 bits of 64-bit variables.
 420 .It Fl P , -parseable
 421 Print numbers in an unscaled form more amenable to parsing, e.g.\&
 422 .Sy 1000000
 423 rather than
 424 .Sy 1M .
 425 .It Fl t , -txg Ns = Ns Ar transaction
 426 Specify the highest transaction to use when searching for uberblocks.
 427 See also the
 428 .Fl u
 429 and
 430 .Fl l
 431 options for a means to see the available uberblocks and their associated
 432 transaction numbers.
 433 .It Fl U , -cachefile Ns = Ns Ar cachefile
 434 Use a cache file other than
 435 .Pa /etc/zfs/zpool.cache .
 436 .It Fl v , -verbose
 437 Enable verbosity.
 438 Specify multiple times for increased verbosity.
 439 .It Fl V , -verbatim
 440 Attempt verbatim import.
 441 This mimics the behavior of the kernel when loading a pool from a cachefile.
 442 Only usable with
 443 .Fl e .
 444 .It Fl X , -extreme-rewind
 445 Attempt
 446 .Qq extreme
 447 transaction rewind, that is attempt the same recovery as
 448 .Fl F
 449 but read transactions otherwise deemed too old.
 450 .It Fl Y , -all-reconstruction
 451 Attempt all possible combinations when reconstructing indirect split blocks.
 452 This flag disables the individual I/O deadman timer in order to allow as
 453 much time as required for the attempted reconstruction.
 454 .It Fl y , -livelist
 455 Perform validation for livelists that are being deleted.
 456 Scans through the livelist and metaslabs, checking for duplicate entries
 457 and compares the two, checking for potential double frees.
 458 If it encounters issues, warnings will be printed, but the command will not
 459 necessarily fail.
 460 .El
 461 .Pp
 462 Specifying a display option more than once enables verbosity for only that
 463 option, with more occurrences enabling more verbosity.
 464 .Pp
 465 If no options are specified, all information about the named pool will be
 466 displayed at default verbosity.
 467 .
 468 .Sh EXAMPLES
 469 .Ss Example 1 : No Display the configuration of imported pool Ar rpool
 470 .Bd -literal
 471 .No # Nm zdb Fl C Ar rpool
 472 MOS Configuration:
 473         version: 28
 474         name: 'rpool'
 475  …
 476 .Ed
 477 .
 478 .Ss Example 2 : No Display basic dataset information about Ar rpool
 479 .Bd -literal
 480 .No # Nm zdb Fl d Ar rpool
 481 Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
 482 Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
 483  …
 484 .Ed
 485 .
 486 .Ss Example 3 : No Display basic information about object 0 in Ar rpool/export/home
 487 .Bd -literal
 488 .No # Nm zdb Fl d Ar rpool/export/home 0
 489 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
 490
 491     Object  lvl   iblk   dblk  dsize  lsize   %full  type
 492          0    7    16K    16K  15.0K    16K   25.00  DMU dnode
 493 .Ed
 494 .
 495 .Ss Example 4 : No Display the predicted effect of enabling deduplication on Ar rpool
 496 .Bd -literal
 497 .No # Nm zdb Fl S Ar rpool
 498 Simulated DDT histogram:
 499
 500 bucket              allocated                       referenced
 501 ______   ______________________________   ______________________________
 502 refcnt   blocks   LSIZE   PSIZE   DSIZE   blocks   LSIZE   PSIZE   DSIZE
 503 ------   ------   -----   -----   -----   ------   -----   -----   -----
 504      1     694K   27.1G   15.0G   15.0G     694K   27.1G   15.0G   15.0G
 505      2    35.0K   1.33G    699M    699M    74.7K   2.79G   1.45G   1.45G
 506  …
 507 dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
 508 .Ed
 509 .
 510 .Sh SEE ALSO
 511 .Xr zfs 8 ,
 512 .Xr zpool 8