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