| .\" |
| .\" This file and its contents are supplied under the terms of the |
| .\" Common Development and Distribution License ("CDDL"), version 1.0. |
| .\" You may only use this file in accordance with the terms of version |
| .\" 1.0 of the CDDL. |
| .\" |
| .\" A full copy of the text of the CDDL should have accompanied this |
| .\" source. A copy of the CDDL is also available via the Internet at |
| .\" http://www.illumos.org/license/CDDL. |
| .\" |
| .\" Copyright 2012, Richard Lowe. |
| .\" Copyright (c) 2012, 2019 by Delphix. All rights reserved. |
| .\" Copyright 2017 Nexenta Systems, Inc. |
| .\" Copyright (c) 2017 Lawrence Livermore National Security, LLC. |
| .\" Copyright (c) 2017 Intel Corporation. |
| .\" |
| .Dd October 7, 2020 |
| .Dt ZDB 8 |
| .Os |
| . |
| .Sh NAME |
| .Nm zdb |
| .Nd display ZFS storage pool debugging and consistency information |
| .Sh SYNOPSIS |
| .Nm |
| .Op Fl AbcdDFGhikLMNPsvXYy |
| .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … |
| .Op Fl I Ar inflight I/Os |
| .Oo Fl o Ar var Ns = Ns Ar value Oc Ns … |
| .Op Fl t Ar txg |
| .Op Fl U Ar cache |
| .Op Fl x Ar dumpdir |
| .Op Ar poolname Ns Op / Ns Ar dataset | objset ID |
| .Op Ar object Ns | Ns Ar range Ns … |
| .Nm |
| .Op Fl AdiPv |
| .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … |
| .Op Fl U Ar cache |
| .Ar poolname Ns Op Ar / Ns Ar dataset | objset ID |
| .Op Ar object Ns | Ns Ar range Ns … |
| .Nm |
| .Fl C |
| .Op Fl A |
| .Op Fl U Ar cache |
| .Nm |
| .Fl E |
| .Op Fl A |
| .Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15 |
| .Nm |
| .Fl l |
| .Op Fl Aqu |
| .Ar device |
| .Nm |
| .Fl m |
| .Op Fl AFLPXY |
| .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … |
| .Op Fl t Ar txg |
| .Op Fl U Ar cache |
| .Ar poolname Op Ar vdev Oo Ar metaslab Oc Ns … |
| .Nm |
| .Fl O |
| .Ar dataset path |
| .Nm |
| .Fl r |
| .Ar dataset path destination |
| .Nm |
| .Fl R |
| .Op Fl A |
| .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … |
| .Op Fl U Ar cache |
| .Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags |
| .Nm |
| .Fl S |
| .Op Fl AP |
| .Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … |
| .Op Fl U Ar cache |
| .Ar poolname |
| . |
| .Sh DESCRIPTION |
| The |
| .Nm |
| utility displays information about a ZFS pool useful for debugging and performs |
| some amount of consistency checking. |
| It is a not a general purpose tool and options |
| .Pq and facilities |
| may change. |
| This is not a |
| .Xr fsck 8 |
| utility. |
| .Pp |
| The output of this command in general reflects the on-disk structure of a ZFS |
| pool, and is inherently unstable. |
| The precise output of most invocations is not documented, a knowledge of ZFS |
| internals is assumed. |
| .Pp |
| If the |
| .Ar dataset |
| argument does not contain any |
| .Qq Sy / |
| or |
| .Qq Sy @ |
| characters, it is interpreted as a pool name. |
| The root dataset can be specified as |
| .Qq Ar pool Ns / . |
| .Pp |
| When operating on an imported and active pool it is possible, though unlikely, |
| that zdb may interpret inconsistent pool data and behave erratically. |
| . |
| .Sh OPTIONS |
| Display options: |
| .Bl -tag -width Ds |
| .It Fl b |
| Display statistics regarding the number, size |
| .Pq logical, physical and allocated |
| and deduplication of blocks. |
| .It Fl c |
| Verify the checksum of all metadata blocks while printing block statistics |
| .Po see |
| .Fl b |
| .Pc . |
| .Pp |
| If specified multiple times, verify the checksums of all blocks. |
| .It Fl C |
| Display information about the configuration. |
| If specified with no other options, instead display information about the cache |
| file |
| .Pq Pa /etc/zfs/zpool.cache . |
| To specify the cache file to display, see |
| .Fl U . |
| .Pp |
| If specified multiple times, and a pool name is also specified display both the |
| cached configuration and the on-disk configuration. |
| If specified multiple times with |
| .Fl e |
| also display the configuration that would be used were the pool to be imported. |
| .It Fl d |
| Display information about datasets. |
| Specified once, displays basic dataset information: ID, create transaction, |
| size, and object count. |
| See |
| .Fl N |
| for determining if |
| .Op Ar poolname Ns Op / Ns Ar dataset | objset ID |
| is to use the specified |
| .Op Ar dataset | objset ID |
| as a string (dataset name) or a number (objset ID) when |
| datasets have numeric names. |
| .Pp |
| If specified multiple times provides greater and greater verbosity. |
| .Pp |
| If object IDs or object ID ranges are specified, display information about |
| those specific objects or ranges only. |
| .Pp |
| An object ID range is specified in terms of a colon-separated tuple of |
| the form |
| .Ao start Ac : Ns Ao end Ac Ns Op : Ns Ao flags Ac . |
| The fields |
| .Ar start |
| and |
| .Ar end |
| are integer object identifiers that denote the upper and lower bounds |
| of the range. |
| An |
| .Ar end |
| value of -1 specifies a range with no upper bound. |
| The |
| .Ar flags |
| field optionally specifies a set of flags, described below, that control |
| which object types are dumped. |
| By default, all object types are dumped. |
| A minus sign |
| .Pq - |
| negates the effect of the flag that follows it and has no effect unless |
| preceded by the |
| .Ar A |
| flag. |
| For example, the range 0:-1:A-d will dump all object types except for directories. |
| .Pp |
| .Bl -tag -compact -width Ds |
| .It Sy A |
| Dump all objects (this is the default) |
| .It Sy d |
| Dump ZFS directory objects |
| .It Sy f |
| Dump ZFS plain file objects |
| .It Sy m |
| Dump SPA space map objects |
| .It Sy z |
| Dump ZAP objects |
| .It Sy - |
| Negate the effect of next flag |
| .El |
| .It Fl D |
| Display deduplication statistics, including the deduplication ratio |
| .Pq Sy dedup , |
| compression ratio |
| .Pq Sy compress , |
| inflation due to the zfs copies property |
| .Pq Sy copies , |
| and an overall effective ratio |
| .Pq Sy dedup No * Sy compress No / Sy copies . |
| .It Fl DD |
| Display a histogram of deduplication statistics, showing the allocated |
| .Pq physically present on disk |
| and referenced |
| .Pq logically referenced in the pool |
| block counts and sizes by reference count. |
| .It Fl DDD |
| Display the statistics independently for each deduplication table. |
| .It Fl DDDD |
| Dump the contents of the deduplication tables describing duplicate blocks. |
| .It Fl DDDDD |
| Also dump the contents of the deduplication tables describing unique blocks. |
| .It Fl E Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15 |
| Decode and display block from an embedded block pointer specified by the |
| .Ar word |
| arguments. |
| .It Fl h |
| Display pool history similar to |
| .Nm zpool Cm history , |
| but include internal changes, transaction, and dataset information. |
| .It Fl i |
| Display information about intent log |
| .Pq ZIL |
| entries relating to each dataset. |
| If specified multiple times, display counts of each intent log transaction type. |
| .It Fl k |
| Examine the checkpointed state of the pool. |
| Note, the on disk format of the pool is not reverted to the checkpointed state. |
| .It Fl l Ar device |
| Read the vdev labels and L2ARC header from the specified device. |
| .Nm Fl l |
| will return 0 if valid label was found, 1 if error occurred, and 2 if no valid |
| labels were found. |
| The presence of L2ARC header is indicated by a specific |
| sequence (L2ARC_DEV_HDR_MAGIC). |
| If there is an accounting error in the size or the number of L2ARC log blocks |
| .Nm Fl l |
| will return 1. |
| Each unique configuration is displayed only once. |
| .It Fl ll Ar device |
| In addition display label space usage stats. |
| If a valid L2ARC header was found |
| also display the properties of log blocks used for restoring L2ARC contents |
| (persistent L2ARC). |
| .It Fl lll Ar device |
| Display every configuration, unique or not. |
| If a valid L2ARC header was found |
| also display the properties of log entries in log blocks used for restoring |
| L2ARC contents (persistent L2ARC). |
| .Pp |
| If the |
| .Fl q |
| option is also specified, don't print the labels or the L2ARC header. |
| .Pp |
| If the |
| .Fl u |
| option is also specified, also display the uberblocks on this device. |
| Specify multiple times to increase verbosity. |
| .It Fl L |
| Disable leak detection and the loading of space maps. |
| By default, |
| .Nm |
| verifies that all non-free blocks are referenced, which can be very expensive. |
| .It Fl m |
| Display the offset, spacemap, free space of each metaslab, all the log |
| spacemaps and their obsolete entry statistics. |
| .It Fl mm |
| Also display information about the on-disk free space histogram associated with |
| each metaslab. |
| .It Fl mmm |
| Display the maximum contiguous free space, the in-core free space histogram, and |
| the percentage of free space in each space map. |
| .It Fl mmmm |
| Display every spacemap record. |
| .It Fl M |
| Display the offset, spacemap, and free space of each metaslab. |
| .It Fl MM |
| Also display information about the maximum contiguous free space and the |
| percentage of free space in each space map. |
| .It Fl MMM |
| Display every spacemap record. |
| .It Fl N |
| Same as |
| .Fl d |
| but force zdb to interpret the |
| .Op Ar dataset | objset ID |
| in |
| .Op Ar poolname Ns Op / Ns Ar dataset | objset ID |
| as a numeric objset ID. |
| .It Fl O Ar dataset path |
| Look up the specified |
| .Ar path |
| inside of the |
| .Ar dataset |
| and display its metadata and indirect blocks. |
| Specified |
| .Ar path |
| must be relative to the root of |
| .Ar dataset . |
| This option can be combined with |
| .Fl v |
| for increasing verbosity. |
| .It Fl r Ar dataset path destination |
| Copy the specified |
| .Ar path |
| inside of the |
| .Ar dataset |
| to the specified destination. |
| Specified |
| .Ar path |
| must be relative to the root of |
| .Ar dataset . |
| This option can be combined with |
| .Fl v |
| for increasing verbosity. |
| .It Xo |
| .Fl R Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags |
| .Xc |
| Read and display a block from the specified device. |
| By default the block is displayed as a hex dump, but see the description of the |
| .Sy r |
| flag, below. |
| .Pp |
| The block is specified in terms of a colon-separated tuple |
| .Ar vdev |
| .Pq an integer vdev identifier |
| .Ar offset |
| .Pq the offset within the vdev |
| .Ar size |
| .Pq the physical size, or logical size / physical size |
| of the block to read and, optionally, |
| .Ar flags |
| .Pq a set of flags, described below . |
| .Pp |
| .Bl -tag -compact -width "b offset" |
| .It Sy b Ar offset |
| Print block pointer at hex offset |
| .It Sy c |
| Calculate and display checksums |
| .It Sy d |
| Decompress the block. |
| Set environment variable |
| .Nm ZDB_NO_ZLE |
| to skip zle when guessing. |
| .It Sy e |
| Byte swap the block |
| .It Sy g |
| Dump gang block header |
| .It Sy i |
| Dump indirect block |
| .It Sy r |
| Dump raw uninterpreted block data |
| .It Sy v |
| Verbose output for guessing compression algorithm |
| .El |
| .It Fl s |
| Report statistics on |
| .Nm zdb |
| I/O. |
| Display operation counts, bandwidth, and error counts of I/O to the pool from |
| .Nm . |
| .It Fl S |
| Simulate the effects of deduplication, constructing a DDT and then display |
| that DDT as with |
| .Fl DD . |
| .It Fl u |
| Display the current uberblock. |
| .El |
| .Pp |
| Other options: |
| .Bl -tag -width Ds |
| .It Fl A |
| Do not abort should any assertion fail. |
| .It Fl AA |
| Enable panic recovery, certain errors which would otherwise be fatal are |
| demoted to warnings. |
| .It Fl AAA |
| Do not abort if asserts fail and also enable panic recovery. |
| .It Fl e Oo Fl p Ar path Oc Ns … |
| Operate on an exported pool, not present in |
| .Pa /etc/zfs/zpool.cache . |
| The |
| .Fl p |
| flag specifies the path under which devices are to be searched. |
| .It Fl x Ar dumpdir |
| All blocks accessed will be copied to files in the specified directory. |
| The blocks will be placed in sparse files whose name is the same as |
| that of the file or device read. |
| .Nm |
| can be then run on the generated files. |
| Note that the |
| .Fl bbc |
| flags are sufficient to access |
| .Pq and thus copy |
| all metadata on the pool. |
| .It Fl F |
| Attempt to make an unreadable pool readable by trying progressively older |
| transactions. |
| .It Fl G |
| Dump the contents of the zfs_dbgmsg buffer before exiting |
| .Nm . |
| zfs_dbgmsg is a buffer used by ZFS to dump advanced debug information. |
| .It Fl I Ar inflight I/Os |
| Limit the number of outstanding checksum I/Os to the specified value. |
| The default value is 200. |
| This option affects the performance of the |
| .Fl c |
| option. |
| .It Fl o Ar var Ns = Ns Ar value … |
| Set the given global libzpool variable to the provided value. |
| The value must be an unsigned 32-bit integer. |
| Currently only little-endian systems are supported to avoid accidentally setting |
| the high 32 bits of 64-bit variables. |
| .It Fl P |
| Print numbers in an unscaled form more amenable to parsing, e.g.\& |
| .Sy 1000000 |
| rather than |
| .Sy 1M . |
| .It Fl t Ar transaction |
| Specify the highest transaction to use when searching for uberblocks. |
| See also the |
| .Fl u |
| and |
| .Fl l |
| options for a means to see the available uberblocks and their associated |
| transaction numbers. |
| .It Fl U Ar cachefile |
| Use a cache file other than |
| .Pa /etc/zfs/zpool.cache . |
| .It Fl v |
| Enable verbosity. |
| Specify multiple times for increased verbosity. |
| .It Fl V |
| Attempt verbatim import. |
| This mimics the behavior of the kernel when loading a pool from a cachefile. |
| Only usable with |
| .Fl e . |
| .It Fl X |
| Attempt |
| .Qq extreme |
| transaction rewind, that is attempt the same recovery as |
| .Fl F |
| but read transactions otherwise deemed too old. |
| .It Fl Y |
| Attempt all possible combinations when reconstructing indirect split blocks. |
| This flag disables the individual I/O deadman timer in order to allow as |
| much time as required for the attempted reconstruction. |
| .It Fl y |
| Perform validation for livelists that are being deleted. |
| Scans through the livelist and metaslabs, checking for duplicate entries |
| and compares the two, checking for potential double frees. |
| If it encounters issues, warnings will be printed, but the command will not |
| necessarily fail. |
| .El |
| .Pp |
| Specifying a display option more than once enables verbosity for only that |
| option, with more occurrences enabling more verbosity. |
| .Pp |
| If no options are specified, all information about the named pool will be |
| displayed at default verbosity. |
| . |
| .Sh EXAMPLES |
| .Bl -tag -width Ds |
| .It Xo |
| .Sy Example 1 : |
| Display the configuration of imported pool |
| .Ar rpool |
| .Xc |
| .Bd -literal |
| .No # Nm zdb Fl C Ar rpool |
| MOS Configuration: |
| version: 28 |
| name: 'rpool' |
| … |
| .Ed |
| .It Xo |
| .Sy Example 2 : |
| Display basic dataset information about |
| .Ar rpool |
| .Xc |
| .Bd -literal |
| .No # Nm zdb Fl d Ar rpool |
| Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects |
| Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects |
| … |
| .Ed |
| .It Xo |
| .Sy Example 3 : |
| Display basic information about object 0 in |
| .Ar rpool/export/home |
| .Xc |
| .Bd -literal |
| .No # Nm zdb Fl d Ar rpool/export/home 0 |
| Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects |
| |
| Object lvl iblk dblk dsize lsize %full type |
| 0 7 16K 16K 15.0K 16K 25.00 DMU dnode |
| .Ed |
| .It Xo |
| .Sy Example 4 : |
| Display the predicted effect of enabling deduplication on |
| .Ar rpool |
| .Xc |
| .Bd -literal |
| .No # Nm zdb Fl S Ar rpool |
| Simulated DDT histogram: |
| |
| bucket allocated referenced |
| ______ ______________________________ ______________________________ |
| refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE |
| ------ ------ ----- ----- ----- ------ ----- ----- ----- |
| 1 694K 27.1G 15.0G 15.0G 694K 27.1G 15.0G 15.0G |
| 2 35.0K 1.33G 699M 699M 74.7K 2.79G 1.45G 1.45G |
| … |
| dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00 |
| .Ed |
| .El |
| . |
| .Sh SEE ALSO |
| .Xr zfs 8 , |
| .Xr zpool 8 |