diff options
Diffstat (limited to 'man/man8/zdb.8')
| -rw-r--r-- | man/man8/zdb.8 | 837 |
1 files changed, 326 insertions, 511 deletions
diff --git a/man/man8/zdb.8 b/man/man8/zdb.8 index 667f6b171..83e7fba14 100644 --- a/man/man8/zdb.8 +++ b/man/man8/zdb.8 @@ -1,4 +1,3 @@ -'\" t .\" .\" This file and its contents are supplied under the terms of the .\" Common Development and Distribution License ("CDDL"), version 1.0. @@ -12,556 +11,378 @@ .\" .\" Copyright 2012, Richard Lowe. .\" Copyright (c) 2012, 2016 by Delphix. All rights reserved. -.\" Copyright 2016 Nexenta Systems, Inc. +.\" Copyright 2017 Nexenta Systems, Inc. +.\" Copyright (c) 2017 Lawrence Livermore National Security, LLC. +.\" Copyright (c) 2017 Intel Corporation. .\" -.TH "ZDB" "8" "April 9, 2016" "" "" - -.SH "NAME" -\fBzdb\fR - Display zpool debugging and consistency information - -.SH "SYNOPSIS" -\fBzdb\fR [-CumdibcsDvhLMXFPAG] [-e [-p \fIpath\fR...]] [-t \fItxg\fR] - [-U \fIcache\fR] [-I \fIinflight I/Os\fR] [-x \fIdumpdir\fR] - [-o \fIvar\fR=\fIvalue\fR] ... [\fIpoolname\fR [\fIobject\fR ...]] - -.P -\fBzdb\fR [-divPA] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] - \fIdataset\fR [\fIobject\fR ...] - -.P -\fBzdb\fR -m [-MLXFPA] [-t \fItxg\fR] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] - \fIpoolname\fR [\fIvdev\fR [\fImetaslab\fR ...]] - -.P -\fBzdb\fR -R [-A] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] \fIpoolname\fR - \fIvdev\fR:\fIoffset\fR:\fIsize\fR[:\fIflags\fR] - -.P -\fBzdb\fR -S [-AP] [-e [-p \fIpath\fR...]] [-U \fIcache\fR] \fIpoolname\fR - -.P -\fBzdb\fR -l [-Aqu] \fIdevice\fR - -.P -\fBzdb\fR -C [-A] [-U \fIcache\fR] - -.SH "DESCRIPTION" -The \fBzdb\fR 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 (and facilities) may change. This is neither -a fsck(8) nor an fsdb(8) utility. - -.P +.Dd April 11, 2017 +.Dt ZDB 8 SMM +.Os Linux +.Sh NAME +.Nm zdb +.Nd display zpool debugging and consistency information +.Sh SYNOPSIS +.Nm +.Op Fl AbcdDFGhiLMPsvVX +.Op Fl e Op Fl p Ar path ... +.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 Op Ar object ... +.Nm +.Op Fl AdiPv +.Op Fl e Op Fl p Ar path ... +.Op Fl U Ar cache +.Ar dataset Op Ar object ... +.Nm +.Fl C +.Op Fl A +.Op Fl U Ar cache +.Nm +.Fl l +.Op Fl Aqu +.Ar device +.Nm +.Fl m +.Op Fl AFLPVX +.Op Fl t Ar txg +.Op Fl e Op Fl p Ar path ... +.Op Fl U Ar cache +.Ar poolname Op Ar vdev Op Ar metaslab ... +.Nm +.Fl O +.Ar dataset path +.Nm +.Fl R +.Op Fl A +.Op Fl e Op Fl p Ar path ... +.Op Fl U Ar cache +.Ar poolname vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op : Ns Ar flags +.Nm +.Fl S +.Op Fl AP +.Op Fl e Op Fl p Ar path ... +.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 neither a +.Xr fsck 1M +nor an +.Xr fsdb 1M +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. - -.P -If the \fIdataset\fR argument does not contain any \fB/\fR or \fB@\fR -characters, it is interpreted as a pool name. The root dataset can be -specified as \fIpool\fB/\fR (pool name followed by a slash). - -.P +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 +.Ar pool Ns / +.Pq pool name followed by a slash . +.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" +.Sh OPTIONS Display options: - -.sp -.ne 2 -.na -\fB-b\fR -.ad -.sp .6 -.RS 4n -Display statistics regarding the number, size (logical, physical and -allocated) and deduplication of blocks. -.RE - -.sp -.ne 2 -.na -\fB-c\fR -.ad -.sp .6 -.RS 4n +.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 -(see \fB-b\fR). -.sp +.Po see +.Fl b +.Pc . +.Pp If specified multiple times, verify the checksums of all blocks. -.RE - -.sp -.ne 2 -.na -\fB-C\fR -.ad -.sp .6 -.RS 4n -Display information about the configuration. If specified with no other -options, instead display information about the cache file -(\fB/etc/zfs/zpool.cache\fR). To specify the cache file to display, see -\fB-U\fR. -.P -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 \fB-e\fR also display the configuration that would be used were the -pool to be imported. -.RE - -.sp -.ne 2 -.na -\fB-d\fR -.ad -.sp .6 -.RS 4n -Display information about datasets. Specified once, displays basic dataset -information: ID, create transaction, size, and object count. -.sp +.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. +.Pp If specified multiple times provides greater and greater verbosity. -.sp -If object IDs are specified, display information about those specific objects only. -.RE - -.sp -.ne 2 -.na -\fB-D\fR -.ad -.sp .6 -.RS 4n -Display deduplication statistics, including the deduplication ratio (dedup), -compression ratio (compress), inflation due to the zfs copies property -(copies), and an overall effective ratio (dedup * compress / copies). -.sp -If specified twice, display a histogram of deduplication statistics, showing -the allocated (physically present on disk) and referenced (logically -referenced in the pool) block counts and sizes by reference count. -.sp -If specified a third time, display the statistics independently for each deduplication table. -.sp -If specified a fourth time, dump the contents of the deduplication tables describing duplicate blocks. -.sp -If specified a fifth time, also dump the contents of the deduplication tables describing unique blocks. -.RE - -.sp -.ne 2 -.na -\fB-h\fR -.ad -.sp .6 -.RS 4n -Display pool history similar to \fBzpool history\fR, but include internal -changes, transaction, and dataset information. -.RE - -.sp -.ne 2 -.na -\fB-i\fR -.ad -.sp .6 -.RS 4n -Display information about intent log (ZIL) entries relating to each -dataset. If specified multiple times, display counts of each intent log -transaction type. -.RE - -.sp -.ne 2 -.na -\fB-l\fR \fIdevice\fR -.ad -.sp .6 -.RS 4n -Read the vdev labels from the specified device and dump the unique -configuration nvlist(s). \fBzdb -l\fR will return 1 if an error occured, 2 if -no configuration nvlist could be unpacked (errors or not), and 0 otherwise. -Specify multiple times to increase verbosity. -.P -If the \fB-u\fR option is also specified, also display the uberblocks on this -device. Specify multiple times to increase verbosity. -.P -If the \fB-q\fR option is also specified, don't dump the configurations or the -uberblocks. -.RE - -.sp -.ne 2 -.na -\fB-L\fR -.ad -.sp .6 -.RS 4n -Disable leak tracing and the loading of space maps. By default, \fBzdb\fR +.Pp +If object IDs are specified, display information about those specific objects +only. +.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 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 l Ar device +Read the vdev labels 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. Each unique configuration is displayed only once. +.It Fl ll Ar device +In addition display label space usage stats. +.It Fl lll Ar device +Display every configuration, unique or not. +.Pp +If the +.Fl q +option is also specified, don't print the labels. +.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 tracing and the loading of space maps. +By default, +.Nm verifies that all non-free blocks are referenced, which can be very expensive. -.RE - -.sp -.ne 2 -.na -\fB-m\fR -.ad -.sp .6 -.RS 4n +.It Fl m Display the offset, spacemap, and free space of each metaslab. -When specified twice, also display information about the on-disk free -space histogram associated with each metaslab. When specified three time, -display the maximum contiguous free space, the in-core free space histogram, -and the percentage of free space in each space map. When specified -four times display every spacemap record. -.RE - -.sp -.ne 2 -.na -\fB-M\fR -.ad -.sp .6 -.RS 4n +.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. -When specified twice, also display information about the maximum contiguous -free space and the percentage of free space in each space map. When specified -three times display every spacemap record. -.RE - -.sp -.ne 2 -.na -\fB-R\fR \fIpoolname\fR \fIvdev\fR:\fIoffset\fR:\fIsize\fR[:\fIflags\fR] -.ad -.sp .6 -.RS 4n -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 \'r\' flag, below. -.sp -The block is specified in terms of a colon-separated tuple \fIvdev\fR (an -integer vdev identifier) \fIoffset\fR (the offset within the vdev) \fIsize\fR -(the size of the block to read) and, optionally, \fIflags\fR (a set of flags, -described below). - -.sp -.ne 2 -.na -\fBb\fR \fIoffset\fR -.ad -.sp .6 -.RS 4n +.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 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 poolname vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op : Ns Ar flags +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 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 -.RE - -.sp -.ne 2 -.na -\fBd\fR -.ad -.sp .6 -.RS 4n +.It Sy d Decompress the block -.RE - -.sp -.ne 2 -.na -\fBe\fR -.ad -.sp .6 -.RS 4n +.It Sy e Byte swap the block -.RE - -.sp -.ne 2 -.na -\fBg\fR -.ad -.sp .6 -.RS 4n +.It Sy g Dump gang block header -.RE - -.sp -.ne 2 -.na -\fBi\fR -.ad -.sp .6 -.RS 4n +.It Sy i Dump indirect block -.RE - -.sp -.ne 2 -.na -\fBr\fR -.ad -.sp .6 -.RS 4n +.It Sy r Dump raw uninterpreted block data -.RE -.RE - -.sp -.ne 2 -.na -\fB-s\fR -.ad -.sp .6 -.RS 4n -Report statistics on \fBzdb\fR\'s I/O. Display operation counts, bandwidth, -and error counts of I/O to the pool from \fBzdb\fR. -.RE - -.sp -.ne 2 -.na -\fB-S\fR -.ad -.sp .6 -.RS 4n +.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 \fB-DD\fR. -.RE - -.sp -.ne 2 -.na -\fB-u\fR -.ad -.sp .6 -.RS 4n +that DDT as with +.Fl DD . +.It Fl u Display the current uberblock. -.RE - -.P +.El +.Pp Other options: - -.sp -.ne 2 -.na -\fB-A\fR -.ad -.sp .6 -.RS 4n +.Bl -tag -width Ds +.It Fl A Do not abort should any assertion fail. -.RE - -.sp -.ne 2 -.na -\fB-AA\fR -.ad -.sp .6 -.RS 4n +.It Fl AA Enable panic recovery, certain errors which would otherwise be fatal are demoted to warnings. -.RE - -.sp -.ne 2 -.na -\fB-AAA\fR -.ad -.sp .6 -.RS 4n +.It Fl AAA Do not abort if asserts fail and also enable panic recovery. -.RE - -.sp -.ne 2 -.na -\fB-e\fR [-p \fIpath\fR]... -.ad -.sp .6 -.RS 4n -Operate on an exported pool, not present in \fB/etc/zfs/zpool.cache\fR. The -\fB-p\fR flag specifies the path under which devices are to be searched. -.RE - -.sp -.ne 2 -.na -\fB-x\fR \fIdumpdir\fR -.ad -.sp .6 -.RS 4n +.It Fl e Op Fl p Ar path ... +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. zdb can be then run on the generated files. -Note that the \fB-bbc\fR flags are sufficient to access (and thus copy) +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. -.RE - -.sp -.ne 2 -.na -\fB-F\fR -.ad -.sp .6 -.RS 4n +.It Fl F Attempt to make an unreadable pool readable by trying progressively older transactions. -.RE - -.sp -.ne 2 -.na -\fB-G\fR -.ad -.sp .6 -.RS 4n -Dump the contents of the zfs_dbgmsg buffer before exiting zdb. zfs_dbgmsg is -a buffer used by ZFS to dump advanced debug information. -.RE - -.sp -.ne 2 -.na -\fB-I \fIinflight I/Os\fR \fR -.ad -.sp .6 -.RS 4n -Limit the number of outstanding checksum I/Os to the specified value. The -default value is 200. This option affects the performance of the \fB-c\fR +.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. -.RE - -.sp -.ne 2 -.na -\fB-o \fIvar\fR=\fIvalue\fR ... \fR -.ad -.sp .6 -.RS 4n -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. -.RE - -.sp -.ne 2 -.na -\fB-P\fR -.ad -.sp .6 -.RS 4n +.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, eg. 1000000 rather than 1M. -.RE - -.sp -.ne 2 -.na -\fB-t\fR \fItransaction\fR -.ad -.sp .6 -.RS 4n -Specify the highest transaction to use when searching for uberblocks. See also -the \fB-u\fR and \fB-l\fR options for a means to see the available uberblocks -and their associated transaction numbers. -.RE - -.sp -.ne 2 -.na -\fB-U\fR \fIcachefile\fR -.ad -.sp .6 -.RS 4n -Use a cache file other than \fB/etc/zfs/zpool.cache\fR. -.RE - -.sp -.ne 2 -.na -\fB-v\fR -.ad -.sp .6 -.RS 4n -Enable verbosity. Specify multiple times for increased verbosity. -.RE - -.sp -.ne 2 -.na -\fB-X\fR -.ad -.sp .6 -.RS 4n -Attempt \'extreme\' transaction rewind, that is attempt the same recovery as -\fB-F\fR but read transactions otherwise deemed too old. -.RE - -.sp -.ne 2 -.na -\fB-V\fR -.ad -.sp .6 -.RS 4n -Attempt a verbatim import. This mimics the behavior of the kernel when loading -a pool from a cachefile. -.RE - -.P +.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 a verbatim import. This mimics the behavior of the kernel when +loading a pool from a cachefile. +.It Fl X +Attempt +.Qq extreme +transaction rewind, that is attempt the same recovery as +.Fl F +but read transactions otherwise deemed too old. +.El +.Pp Specifying a display option more than once enables verbosity for only that option, with more occurrences enabling more verbosity. -.P +.Pp If no options are specified, all information about the named pool will be displayed at default verbosity. - -.SH "EXAMPLES" -.LP -\fBExample 1 \fRDisplay the configuration of imported pool 'rpool' -.sp -.in +2 -.nf +.Sh EXAMPLES +.Bl -tag -width Ds +.It Xo +.Sy Example 1 +Display the configuration of imported pool +.Pa rpool +.Xc +.Bd -literal # zdb -C rpool MOS Configuration: version: 28 name: 'rpool' ... -.fi -.in -2 -.sp - -.LP -\fBExample 2 \fRDisplay basic dataset information about 'rpool' -.sp -.in +2 -.nf +.Ed +.It Xo +.Sy Example 2 +Display basic dataset information about +.Pa rpool +.Xc +.Bd -literal # zdb -d 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 ... -.fi -.in -2 -.sp - -.LP -\fBExample 3 \fRDisplay basic information about object 0 -in 'rpool/export/home' -.sp -.in +2 -.nf +.Ed +.It Xo +.Sy Example 3 +Display basic information about object 0 in +.Pa rpool/export/home +.Xc +.Bd -literal # zdb -d 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 -.fi -.in -2 -.sp - -.LP -\fBExample 4 \fRDisplay the predicted effect of enabling deduplication on 'rpool' -.sp -.in +2 -.nf +.Ed +.It Xo +.Sy Example 4 +Display the predicted effect of enabling deduplication on +.Pa rpool +.Xc +.Bd -literal # zdb -S rpool Simulated DDT histogram: @@ -573,14 +394,8 @@ refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE 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 -.fi -.in -2 -.sp - -.SH "ENVIRONMENT VARIABLES" -.TP -.B "SPA_CONFIG_PATH" -Override the default \fBspa_config_path\fR (\fI/etc/zfs/zpool.cache\fR) setting. If \fB-U\fR flag is specified it will override this environment variable settings once again. - -.SH "SEE ALSO" -zfs(8), zpool(8) +.Ed +.El +.Sh SEE ALSO +.Xr zfs 8 , +.Xr zpool 8 |