granicus.if.org Git - zfs/blob - man/man8/zdb.8

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