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