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