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