cddl/contrib/opensolaris/cmd/zdb/zdb.8

   1 '\" te
   2 .\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>.
   3 .\" All Rights Reserved.
   4 .\"
   5 .\" This file and its contents are supplied under the terms of the
   6 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   7 .\" You may only use this file in accordance with the terms of version
   8 .\" 1.0 of the CDDL.
   9 .\"
  10 .\" A full copy of the text of the CDDL should have accompanied this
  11 .\" source.  A copy of the CDDL is also available via the Internet at
  12 .\" http://www.illumos.org/license/CDDL.
  13 .\"
  14 .\"
  15 .\" Copyright 2012, Richard Lowe.
  16 .\" Copyright (c) 2012, Marcelo Araujo <araujo@FreeBSD.org>.
  17 .\" Copyright (c) 2012, 2014 by Delphix. All rights reserved.
  18 .\" Copyright 2016 Nexenta Systems, Inc.
  19 .\" All Rights Reserved.
  20 .\"
  21 .\" $FreeBSD$
  22 .\"
  23 .Dd October 1, 2017
  24 .Dt ZDB 8
  25 .Os
  26 .Sh NAME
  27 .Nm zdb
  28 .Nd Display zpool debugging and consistency information
  29 .Sh SYNOPSIS
  30 .Nm
  31 .Op Fl CmdibcsDvhLMXFPA
  32 .Op Fl e Op Fl p Ar path...
  33 .Op Fl t Ar txg
  34 .Op Fl U Ar cache
  35 .Op Fl I Ar inflight I/Os
  36 .Op Fl x Ar dumpdir
  37 .Op Fl o Ar var=value
  38 .Ar poolname
  39 .Op Ar object ...
  40 .Nm
  41 .Op Fl divPA
  42 .Op Fl e Op Fl p Ar path...
  43 .Op Fl U Ar cache
  44 .Ar dataset
  45 .Op Ar object ...
  46 .Nm
  47 .Fl m Op Fl MLXFPA
  48 .Op Fl t Ar txg
  49 .Op Fl e Op Fl p Ar path...
  50 .Op Fl U Ar cache
  51 .Ar poolname
  52 .Nm
  53 .Fl R Op Fl A
  54 .Op Fl e Op Fl p Ar path...
  55 .Op Fl U Ar cache
  56 .Ar poolname
  57 .Ar poolname
  58 .Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
  59 .Nm
  60 .Fl S
  61 .Op Fl AP
  62 .Op Fl e Op Fl p Ar path...
  63 .Op Fl U Ar cache
  64 .Ar poolname
  65 .Ar poolname
  66 .Nm
  67 .Fl l
  68 .Op Fl Aqu
  69 .Ar device
  70 .Nm
  71 .Fl C
  72 .Op Fl A
  73 .Op Fl U Ar cache
  74 .Sh DESCRIPTION
  75 The
  76 .Nm
  77 utility displays information about a ZFS pool useful for debugging and
  78 performs some amount of consistency checking.
  79 It is a not a general purpose tool and options (and facilities) may change.
  80 This is neither a
  81 .Xr fsck 8
  82 nor a
  83 .Xr fsdb 8
  84 utility.
  85 .Pp
  86 The output of this command in general reflects the on-disk structure of a ZFS
  87 pool, and is inherently unstable.
  88 The precise output of most invocations is not documented, a knowledge of ZFS
  89 internals is assumed.
  90 .Pp
  91 If the
  92 .Ar dataset
  93 argument does not contain any
  94 .Sy /
  95 or
  96 .Sy @
  97 characters, it is interpreted as a pool name.
  98 The root dataset can be specified as
  99 .Pa pool Ns Sy /
 100 (pool name followed by a slash).
 101 .Pp
 102 When operating on an imported and active pool it is possible, though unlikely,
 103 that zdb may interpret inconsistent pool data and behave erratically.
 104 .Sh OPTIONS
 105 Display options:
 106 .Bl -tag -width indent
 107 .It Fl b
 108 Display statistics regarding the number, size (logical, physical and
 109 allocated) and deduplication of blocks.
 110 .It Fl c
 111 Verify the checksum of all metadata blocks while printing block statistics
 112 (see
 113 .Fl b Ns ).
 114 .Pp
 115 If specified multiple times, verify the checksums of all blocks.
 116 .It Fl C
 117 Display information about the configuration. If specified with no other
 118 options, instead display information about the cache file
 119 .Po Pa /etc/zfs/zpool.cache Pc .
 120 To specify the cache file to display, see
 121 .Fl U
 122 .Pp
 123 If specified multiple times, and a pool name is also specified display both
 124 the cached configuration and the on-disk configuration.
 125 If specified multiple times with
 126 .Fl e
 127 also display the configuration that would be used were the pool to be
 128 imported.
 129 .It Fl d
 130 Display information about datasets. Specified once, displays basic dataset
 131 information: ID, create transaction, size, and object count.
 132 .Pp
 133 If specified multiple times provides greater and greater verbosity.
 134 .Pp
 135 If object IDs are specified, display information about those specific objects only.
 136 .It Fl D
 137 Display deduplication statistics, including the deduplication ratio (dedup),
 138 compression ratio (compress), inflation due to the zfs copies property
 139 (copies), and an overall effective ratio (dedup * compress / copies).
 140 .Pp
 141 If specified twice, display a histogram of deduplication statistics, showing
 142 the allocated (physically present on disk) and referenced (logically
 143 referenced in the pool) block counts and sizes by reference count.
 144 .Pp
 145 If specified a third time, display the statistics independently for each deduplication table.
 146 .Pp
 147 If specified a fourth time, dump the contents of the deduplication tables describing duplicate blocks.
 148 .Pp
 149 If specified a fifth time, also dump the contents of the deduplication tables describing unique blocks.
 150 .It Fl h
 151 Display pool history similar to
 152 .Cm zpool history ,
 153 but include internal changes, transaction, and dataset information.
 154 .It Fl i
 155 Display information about intent log (ZIL) entries relating to each
 156 dataset.
 157 If specified multiple times, display counts of each intent log transaction
 158 type.
 159 .It Fl l Ar device
 160 Read the vdev labels from the specified device.
 161 Return 0 if a valid label was found, 1 if an error occurred, and 2 if no valid
 162 labels were found.
 163 If the
 164 .Fl u
 165 option is also specified, also display the uberblocks on this device.
 166 If the
 167 .Fl q
 168 option is also specified, also display the uberblocks on this device.
 169 .It Fl L
 170 Disable leak tracing and the loading of space maps.
 171 By default,
 172 .Nm
 173 verifies that all non-free blocks are referenced, which can be very expensive.
 174 .It Fl m
 175 Display the offset, spacemap, and free space of each metaslab.
 176 When specified twice, also display information about the on-disk free
 177 space histogram associated with each metaslab. When specified three time,
 178 display the maximum contiguous free space, the in-core free space histogram,
 179 and the percentage of free space in each space map.  When specified
 180 four times display every spacemap record.
 181 .It Fl M
 182 Display the offset, spacemap, and free space of each metaslab.
 183 When specified twice, also display information about the maximum contiguous
 184 free space and the percentage of free space in each space map.
 185 When specified three times display every spacemap record.
 186 .It Xo
 187 .Fl R Ar poolname
 188 .Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
 189 .Xc
 190 Read and display a block from the specified device. By default the block is
 191 displayed as a hex dump, but see the description of the
 192 .Fl r
 193 flag, below.
 194 .Pp
 195 The block is specified in terms of a colon-separated tuple
 196 .Ar vdev
 197 (an integer vdev identifier)
 198 .Ar offset
 199 (the offset within the vdev)
 200 .Ar size
 201 (the size of the block to read) and, optionally,
 202 .Ar flags
 203 (a set of flags, described below).
 204 .Bl -tag -width indent
 205 .It Sy b offset
 206 Print block pointer
 207 .It Sy d
 208 Decompress the block
 209 .It Sy e
 210 Byte swap the block
 211 .It Sy g
 212 Dump gang block header
 213 .It Sy i
 214 Dump indirect block
 215 .It Sy r
 216 Dump raw uninterpreted block data
 217 .El
 218 .It Fl s
 219 Report statistics on
 220 .Nm Ns 's
 221 I/O.
 222 Display operation counts, bandwidth, and error counts of I/O to the pool from
 223 .Nm .
 224 .It Fl S
 225 Simulate the effects of deduplication, constructing a DDT and then display
 226 that DDT as with \fB-DD\fR.
 227 .It Fl u
 228 Display the current uberblock.
 229 .El
 230 .Pp
 231 Other options:
 232 .Bl -tag -width indent
 233 .It Fl A
 234 Do not abort should any assertion fail.
 235 .It Fl AA
 236 Enable panic recovery, certain errors which would otherwise be fatal are
 237 demoted to warnings.
 238 .It Fl AAA
 239 Do not abort if asserts fail and also enable panic recovery.
 240 .It Fl e Op Fl p Ar path...
 241 Operate on an exported pool, not present in
 242 .Pa /etc/zfs/zpool.cache .
 243 The
 244 .Fl p
 245 flag specifies the path under which devices are to be searched.
 246 .It Fl x Ar dumpdir
 247 All blocks accessed will be copied to files in the specified directory.
 248 The blocks will be placed in sparse files whose name is the same as
 249 that of the file or device read.  zdb can be then run on the generated files.
 250 Note that the
 251 .Fl bbc
 252 flags are sufficient to access (and thus copy)
 253 all metadata on the pool.
 254 .It Fl F
 255 Attempt to make an unreadable pool readable by trying progressively older
 256 transactions.
 257 .It Fl I Ar inflight I/Os
 258 Limit the number of outstanding checksum I/Os to the specified value.
 259 The default value is 200. This option affects the performance of the
 260 .Fl c
 261 option.
 262 .It Fl o Ar var=value
 263 Set the given global libzpool variable to the provided value. The value must be
 264 an unsigned 32-bit integer. Currently only little-endian systems are supported
 265 to avoid accidentally setting the high 32 bits of 64-bit variables.
 266 .It Fl P
 267 Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather
 268 than 1M.
 269 .It Fl t Ar transaction
 270 Specify the highest transaction to use when searching for uberblocks.
 271 See also the
 272 .Fl u
 273 and
 274 .Fl l
 275 options for a means to see the available uberblocks and their associated
 276 transaction numbers.
 277 .It Fl U Ar cachefile
 278 Use a cache file other than
 279 .Pa /boot/zfs/zpool.cache .
 280 .It Fl v
 281 Enable verbosity.
 282 Specify multiple times for increased verbosity.
 283 .It Fl X
 284 Attempt
 285 .Ql extreme
 286 transaction rewind, that is attempt the same recovery as
 287 .Fl F
 288 but read transactions otherwise deemed too old.
 289 .El
 290 .Pp
 291 Specifying a display option more than once enables verbosity for only that
 292 option, with more occurrences enabling more verbosity.
 293 .Pp
 294 If no options are specified, all information about the named pool will be
 295 displayed at default verbosity.
 296 .Sh EXAMPLES
 297 .Bl -tag -width 0n
 298 .It Sy Example 1 Display the configuration of imported pool 'rpool'
 299 .Bd -literal -offset 2n
 300 .Li # Ic zdb -C rpool
 301
 302 MOS Configuration:
 303         version: 28
 304         name: 'rpool'
 305  ...
 306 .Ed
 307 .It Sy Example 2 Display basic dataset information about 'rpool'
 308 .Bd -literal -offset 2n
 309 .Li # Ic zdb -d rpool
 310 Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
 311 Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
 312  ...
 313 .Ed
 314 .It Xo Sy Example 3 Display basic information about object 0 in
 315 .Sy 'rpool/export/home'
 316 .Xc
 317 .Bd -literal -offset 2n
 318 .Li # Ic zdb -d rpool/export/home 0
 319 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
 320
 321     Object  lvl   iblk   dblk  dsize  lsize   %full  type
 322          0    7    16K    16K  15.0K    16K   25.00  DMU dnode
 323 .Ed
 324 .It Xo Sy Example 4 Display the predicted effect of enabling deduplication on
 325 .Sy 'rpool'
 326 .Xc
 327 .Bd -literal -offset 2n
 328 .Li # Ic zdb -S rpool
 329 Simulated DDT histogram:
 330
 331 bucket             allocated                      referenced
 332 ______  ______________________________  ______________________________
 333 refcnt  blocks   LSIZE   PSIZE   DSIZE  blocks   LSIZE   PSIZE   DSIZE
 334 ------  ------   -----   -----   -----  ------   -----   -----   -----
 335      1    694K   27.1G   15.0G   15.0G    694K   27.1G   15.0G   15.0G
 336      2   35.0K   1.33G    699M    699M   74.7K   2.79G   1.45G   1.45G
 337  ...
 338 dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
 339 .Ed
 340 .El
 341 .Sh SEE ALSO
 342 .Xr zfs 8 ,
 343 .Xr zpool 8
 344 .Sh AUTHORS
 345 This manual page is a
 346 .Xr mdoc 7
 347 reimplementation of the
 348 .Tn illumos
 349 manual page
 350 .Em zdb(1M) ,
 351 modified and customized for
 352 .Fx
 353 and licensed under the
 354 Common Development and Distribution License
 355 .Pq Tn CDDL .
 356 .Pp
 357 The
 358 .Xr mdoc 7
 359 implementation of this manual page was initially written by
 360 .An Martin Matuska Aq mm@FreeBSD.org
 361 and
 362 .An Marcelo Araujo Aq araujo@FreeBSD.org .