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