man/man1m/zdb.1m

   1 '\" t
   2 .\"
   3 .\" This file and its contents are supplied under the terms of the
   4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\" You may only use this file in accordance with the terms of version
   6 .\" 1.0 of the CDDL.
   7 .\"
   8 .\" A full copy of the text of the CDDL should have accompanied this
   9 .\" source.  A copy of the CDDL is also available via the Internet at
  10 .\" http://www.illumos.org/license/CDDL.
  11 .\"
  12 .\"
  13 .\" Copyright 2012, Richard Lowe.
  14 .\" Copyright (c) 2012, 2016 by Delphix. All rights reserved.
  15 .\" Copyright 2016 Nexenta Systems, Inc.
  16 .\"
  17 .TH "ZDB" "1M" "April 9, 2016"
  18
  19 .SH "NAME"
  20 \fBzdb\fR - Display zpool debugging and consistency information
  21
  22 .SH "SYNOPSIS"
  23 \fBzdb\fR [-CmdibcsDvhLMXFPAG] [-e [-p \fIpath\fR...]] [-t \fItxg\fR]
  24     [-U \fIcache\fR] [-I \fIinflight I/Os\fR] [-x \fIdumpdir\fR]
  25     [-o \fIvar\fR=\fIvalue\fR] ... [\fIpoolname\fR [\fIobject\fR ...]]
  26
  27 .P
  28 \fBzdb\fR [-divPA] [-e [-p \fIpath\fR...]] [-U \fIcache\fR]
  29     \fIdataset\fR [\fIobject\fR ...]
  30
  31 .P
  32 \fBzdb\fR -m [-MLXFPA] [-t \fItxg\fR] [-e [-p \fIpath\fR...]] [-U \fIcache\fR]
  33     \fIpoolname\fR [\fIvdev\fR [\fImetaslab\fR ...]]
  34
  35 .P
  36 \fBzdb\fR -R [-A] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] \fIpoolname\fR
  37     \fIvdev\fR:\fIoffset\fR:\fIsize\fR[:\fIflags\fR]
  38
  39 .P
  40 \fBzdb\fR -S [-AP] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] \fIpoolname\fR
  41
  42 .P
  43 \fBzdb\fR -l [-Aqu] \fIdevice\fR
  44
  45 .P
  46 \fBzdb\fR -C [-A] [-U \fIcache\fR]
  47
  48 .SH "DESCRIPTION"
  49 The \fBzdb\fR utility displays information about a ZFS pool useful for
  50 debugging and performs some amount of consistency checking. It is a not a
  51 general purpose tool and options (and facilities) may change. This is neither
  52 a fsck(1M) nor an fsdb(1M) utility.
  53
  54 .P
  55 The output of this command in general reflects the on-disk structure of a ZFS
  56 pool, and is inherently unstable. The precise output of most invocations is
  57 not documented, a knowledge of ZFS internals is assumed.
  58
  59 .P
  60 If the \fIdataset\fR argument does not contain any \fB/\fR or \fB@\fR
  61 characters, it is interpreted as a pool name.  The root dataset can be
  62 specified as \fIpool\fB/\fR (pool name followed by a slash).
  63
  64 .P
  65 When operating on an imported and active pool it is possible, though unlikely,
  66 that zdb may interpret inconsistent pool data and behave erratically.
  67
  68 .SH "OPTIONS"
  69 Display options:
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB-b\fR
  75 .ad
  76 .sp .6
  77 .RS 4n
  78 Display statistics regarding the number, size (logical, physical and
  79 allocated) and deduplication of blocks.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB-c\fR
  86 .ad
  87 .sp .6
  88 .RS 4n
  89 Verify the checksum of all metadata blocks while printing block statistics
  90 (see \fB-b\fR).
  91 .sp
  92 If specified multiple times, verify the checksums of all blocks.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB-C\fR
  99 .ad
 100 .sp .6
 101 .RS 4n
 102 Display information about the configuration. If specified with no other
 103 options, instead display information about the cache file
 104 (\fB/etc/zfs/zpool.cache\fR). To specify the cache file to display, see
 105 \fB-U\fR.
 106 .P
 107 If specified multiple times, and a pool name is also specified display both
 108 the cached configuration and the on-disk configuration.  If specified multiple
 109 times with \fB-e\fR also display the configuration that would be used were the
 110 pool to be imported.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB-d\fR
 117 .ad
 118 .sp .6
 119 .RS 4n
 120 Display information about datasets. Specified once, displays basic dataset
 121 information: ID, create transaction, size, and object count.
 122 .sp
 123 If specified multiple times provides greater and greater verbosity.
 124 .sp
 125 If object IDs are specified, display information about those specific objects only.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB-D\fR
 132 .ad
 133 .sp .6
 134 .RS 4n
 135 Display deduplication statistics, including the deduplication ratio (dedup),
 136 compression ratio (compress), inflation due to the zfs copies property
 137 (copies), and an overall effective ratio (dedup * compress / copies).
 138 .sp
 139 If specified twice, display a histogram of deduplication statistics, showing
 140 the allocated (physically present on disk) and referenced (logically
 141 referenced in the pool) block counts and sizes by reference count.
 142 .sp
 143 If specified a third time, display the statistics independently for each deduplication table.
 144 .sp
 145 If specified a fourth time, dump the contents of the deduplication tables describing duplicate blocks.
 146 .sp
 147 If specified a fifth time, also dump the contents of the deduplication tables describing unique blocks.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB-h\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 Display pool history similar to \fBzpool history\fR, but include internal
 158 changes, transaction, and dataset information.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB-i\fR
 165 .ad
 166 .sp .6
 167 .RS 4n
 168 Display information about intent log (ZIL) entries relating to each
 169 dataset. If specified multiple times, display counts of each intent log
 170 transaction type.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB-l\fR \fIdevice\fR
 177 .ad
 178 .sp .6
 179 .RS 4n
 180 Read the vdev labels from the specified device. \fBzdb -l\fR will return 0 if
 181 valid label was found, 1 if error occured, and 2 if no valid labels were found.
 182 .P
 183 If the \fB-u\fR option is also specified, also display the uberblocks on this
 184 device.
 185 .P
 186 If the \fB-q\fR option is also specified, don't print the labels.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB-L\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 Disable leak tracing and the loading of space maps.  By default, \fBzdb\fR
 197 verifies that all non-free blocks are referenced, which can be very expensive.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB-m\fR
 204 .ad
 205 .sp .6
 206 .RS 4n
 207 Display the offset, spacemap, and free space of each metaslab.
 208 When specified twice, also display information about the on-disk free
 209 space histogram associated with each metaslab. When specified three time,
 210 display the maximum contiguous free space, the in-core free space histogram,
 211 and the percentage of free space in each space map.  When specified
 212 four times display every spacemap record.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB-M\fR
 219 .ad
 220 .sp .6
 221 .RS 4n
 222 Display the offset, spacemap, and free space of each metaslab.
 223 When specified twice, also display information about the maximum contiguous
 224 free space and the percentage of free space in each space map.  When specified
 225 three times display every spacemap record.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB-R\fR \fIpoolname\fR \fIvdev\fR:\fIoffset\fR:\fIsize\fR[:\fIflags\fR]
 232 .ad
 233 .sp .6
 234 .RS 4n
 235 Read and display a block from the specified device. By default the block is
 236 displayed as a hex dump, but see the description of the \'r\' flag, below.
 237 .sp
 238 The block is specified in terms of a colon-separated tuple \fIvdev\fR (an
 239 integer vdev identifier) \fIoffset\fR (the offset within the vdev) \fIsize\fR
 240 (the size of the block to read) and, optionally, \fIflags\fR (a set of flags,
 241 described below).
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fBb\fR \fIoffset\fR
 247 .ad
 248 .sp .6
 249 .RS 4n
 250 Print block pointer
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fBd\fR
 257 .ad
 258 .sp .6
 259 .RS 4n
 260 Decompress the block
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fBe\fR
 267 .ad
 268 .sp .6
 269 .RS 4n
 270 Byte swap the block
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fBg\fR
 277 .ad
 278 .sp .6
 279 .RS 4n
 280 Dump gang block header
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fBi\fR
 287 .ad
 288 .sp .6
 289 .RS 4n
 290 Dump indirect block
 291 .RE
 292
 293 .sp
 294 .ne 2
 295 .na
 296 \fBr\fR
 297 .ad
 298 .sp .6
 299 .RS 4n
 300 Dump raw uninterpreted block data
 301 .RE
 302 .RE
 303
 304 .sp
 305 .ne 2
 306 .na
 307 \fB-s\fR
 308 .ad
 309 .sp .6
 310 .RS 4n
 311 Report statistics on \fBzdb\fR\'s I/O. Display operation counts, bandwidth,
 312 and error counts of I/O to the pool from \fBzdb\fR.
 313 .RE
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB-S\fR
 319 .ad
 320 .sp .6
 321 .RS 4n
 322 Simulate the effects of deduplication, constructing a DDT and then display
 323 that DDT as with \fB-DD\fR.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fB-u\fR
 330 .ad
 331 .sp .6
 332 .RS 4n
 333 Display the current uberblock.
 334 .RE
 335
 336 .P
 337 Other options:
 338
 339 .sp
 340 .ne 2
 341 .na
 342 \fB-A\fR
 343 .ad
 344 .sp .6
 345 .RS 4n
 346 Do not abort should any assertion fail.
 347 .RE
 348
 349 .sp
 350 .ne 2
 351 .na
 352 \fB-AA\fR
 353 .ad
 354 .sp .6
 355 .RS 4n
 356 Enable panic recovery, certain errors which would otherwise be fatal are
 357 demoted to warnings.
 358 .RE
 359
 360 .sp
 361 .ne 2
 362 .na
 363 \fB-AAA\fR
 364 .ad
 365 .sp .6
 366 .RS 4n
 367 Do not abort if asserts fail and also enable panic recovery.
 368 .RE
 369
 370 .sp
 371 .ne 2
 372 .na
 373 \fB-e\fR [-p \fIpath\fR]...
 374 .ad
 375 .sp .6
 376 .RS 4n
 377 Operate on an exported pool, not present in \fB/etc/zfs/zpool.cache\fR. The
 378 \fB-p\fR flag specifies the path under which devices are to be searched.
 379 .RE
 380
 381 .sp
 382 .ne 2
 383 .na
 384 \fB-x\fR \fIdumpdir\fR
 385 .ad
 386 .sp .6
 387 .RS 4n
 388 All blocks accessed will be copied to files in the specified directory.
 389 The blocks will be placed in sparse files whose name is the same as
 390 that of the file or device read.  zdb can be then run on the generated files.
 391 Note that the \fB-bbc\fR flags are sufficient to access (and thus copy)
 392 all metadata on the pool.
 393 .RE
 394
 395 .sp
 396 .ne 2
 397 .na
 398 \fB-F\fR
 399 .ad
 400 .sp .6
 401 .RS 4n
 402 Attempt to make an unreadable pool readable by trying progressively older
 403 transactions.
 404 .RE
 405
 406 .sp
 407 .ne 2
 408 .na
 409 \fB-G\fR
 410 .ad
 411 .sp .6
 412 .RS 4n
 413 Dump the contents of the zfs_dbgmsg buffer before exiting zdb. zfs_dbgmsg is
 414 a buffer used by ZFS to dump advanced debug information.
 415 .RE
 416
 417 .sp
 418 .ne 2
 419 .na
 420 \fB-I \fIinflight I/Os\fR \fR
 421 .ad
 422 .sp .6
 423 .RS 4n
 424 Limit the number of outstanding checksum I/Os to the specified value. The
 425 default value is 200. This option affects the performance of the \fB-c\fR
 426 option.
 427 .RE
 428
 429 .sp
 430 .ne 2
 431 .na
 432 \fB-o \fIvar\fR=\fIvalue\fR ... \fR
 433 .ad
 434 .sp .6
 435 .RS 4n
 436 Set the given global libzpool variable to the provided value. The value must
 437 be an unsigned 32-bit integer. Currently only little-endian systems are
 438 supported to avoid accidentally setting the high 32 bits of 64-bit variables.
 439 .RE
 440
 441 .sp
 442 .ne 2
 443 .na
 444 \fB-P\fR
 445 .ad
 446 .sp .6
 447 .RS 4n
 448 Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather
 449 than 1M.
 450 .RE
 451
 452 .sp
 453 .ne 2
 454 .na
 455 \fB-t\fR \fItransaction\fR
 456 .ad
 457 .sp .6
 458 .RS 4n
 459 Specify the highest transaction to use when searching for uberblocks. See also
 460 the \fB-u\fR and \fB-l\fR options for a means to see the available uberblocks
 461 and their associated transaction numbers.
 462 .RE
 463
 464 .sp
 465 .ne 2
 466 .na
 467 \fB-U\fR \fIcachefile\fR
 468 .ad
 469 .sp .6
 470 .RS 4n
 471 Use a cache file other than \fB/etc/zfs/zpool.cache\fR.
 472 .RE
 473
 474 .sp
 475 .ne 2
 476 .na
 477 \fB-v\fR
 478 .ad
 479 .sp .6
 480 .RS 4n
 481 Enable verbosity. Specify multiple times for increased verbosity.
 482 .RE
 483
 484 .sp
 485 .ne 2
 486 .na
 487 \fB-X\fR
 488 .ad
 489 .sp .6
 490 .RS 4n
 491 Attempt \'extreme\' transaction rewind, that is attempt the same recovery as
 492 \fB-F\fR but read transactions otherwise deemed too old.
 493 .RE
 494
 495 .P
 496 Specifying a display option more than once enables verbosity for only that
 497 option, with more occurrences enabling more verbosity.
 498 .P
 499 If no options are specified, all information about the named pool will be
 500 displayed at default verbosity.
 501
 502 .SH "EXAMPLES"
 503 .LP
 504 \fBExample 1 \fRDisplay the configuration of imported pool 'rpool'
 505 .sp
 506 .in +2
 507 .nf
 508 # zdb -C rpool
 509
 510 MOS Configuration:
 511         version: 28
 512         name: 'rpool'
 513  ...
 514 .fi
 515 .in -2
 516 .sp
 517
 518 .LP
 519 \fBExample 2 \fRDisplay basic dataset information about 'rpool'
 520 .sp
 521 .in +2
 522 .nf
 523 # zdb -d rpool
 524 Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
 525 Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
 526  ...
 527 .fi
 528 .in -2
 529 .sp
 530
 531 .LP
 532 \fBExample 3 \fRDisplay basic information about object 0 in 'rpool/export/home'
 533 .sp
 534 .in +2
 535 .nf
 536 # zdb -d rpool/export/home 0
 537 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
 538
 539     Object  lvl   iblk   dblk  dsize  lsize   %full  type
 540          0    7    16K    16K  15.0K    16K   25.00  DMU dnode
 541 .fi
 542 .in -2
 543 .sp
 544
 545 .LP
 546 \fBExample 4 \fRDisplay the predicted effect of enabling deduplication on 'rpool'
 547 .sp
 548 .in +2
 549 .nf
 550 # zdb -S rpool
 551 Simulated DDT histogram:
 552
 553 bucket              allocated                       referenced
 554 ______   ______________________________   ______________________________
 555 refcnt   blocks   LSIZE   PSIZE   DSIZE   blocks   LSIZE   PSIZE   DSIZE
 556 ------   ------   -----   -----   -----   ------   -----   -----   -----
 557      1     694K   27.1G   15.0G   15.0G     694K   27.1G   15.0G   15.0G
 558      2    35.0K   1.33G    699M    699M    74.7K   2.79G   1.45G   1.45G
 559  ...
 560 dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
 561 .fi
 562 .in -2
 563 .sp
 564
 565 .SH "SEE ALSO"
 566 zfs(1M), zpool(1M)