Date: Tue, 1 May 2012 04:06:33 GMT From: Marcelo Araujo <araujo@FreeBSD.org> To: freebsd-gnats-submit@FreeBSD.org Subject: kern/167467: [ZFS] improve zdb(8) manpage and help. Message-ID: <201205010406.q4146XI7041779@red.freebsd.org> Resent-Message-ID: <201205010410.q414A6xZ014115@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 167467
>Category: kern
>Synopsis: [ZFS] improve zdb(8) manpage and help.
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-bugs
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue May 01 04:10:06 UTC 2012
>Closed-Date:
>Last-Modified:
>Originator: Marcelo Araujo
>Release: 10.0-CURRENT
>Organization:
FreeBSD
>Environment:
FreeBSD hosta 10.0-CURRENT FreeBSD 10.0-CURRENT #2 r233530M: Mon Apr 23 11:51:58 UTC 2012 araujo@hosta:/usr/obj/usr/src/sys/HOSTA i386
>Description:
Improve zdb man page as well as the output help provided by zdb command.
>How-To-Repeat:
>Fix:
Patch attached with submission follows:
diff -r b470a5db430e cddl/contrib/opensolaris/cmd/zdb/zdb.8
--- a/cddl/contrib/opensolaris/cmd/zdb/zdb.8 Mon Apr 30 06:02:00 2012 +0000
+++ b/cddl/contrib/opensolaris/cmd/zdb/zdb.8 Mon Apr 30 11:28:04 2012 +0000
@@ -18,55 +18,451 @@
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 2012, Richard Lowe.
+.\" Copyright (c) 2012, Marcelo Araujo <araujo@FreeBSD.org>.
+.\" All Rights Reserved.
.\"
.\" $FreeBSD$
.\"
-.Dd November 26, 2011
+.Dd May 1, 2012
.Dt ZDB 8
.Os
.Sh NAME
.Nm zdb
-.Nd ZFS debugger
+.Nd Display zpool debugging and consistency information
.Sh SYNOPSIS
-.Nm
-.Ar pool
+\fBzdb\fR [-CumdibcsDvhLXFPA] [-e [-p \fIpath\fR...]] [-t \fItxg\fR]
+ \fIpoolname\fR [\fIobject\fR ...]
+
+.P
+\fBzdb\fR [-divPA] [-e [-p \fIpath\fR...]]
+ \fIdataset\fR [\fIobject\fR ...]
+
+.P
+\fBzdb\fR -m [-LXFPA] [-t \fItxg\fR] [-e [-p \fIpath\fR...]] \fIpoolname\fR
+ [\fIvdev\fR [\fImetaslab\fR ...]]
+
+.P
+\fBzdb\fR -R [-A] [-e [-p \fIpath\fR...]] \fIpoolname\fR
+ \fIvdev\fR:\fIoffset\fR:\fIsize\fR[:\fIflags\fR]
+
+.P
+\fBzdb\fR -S [-AP] [-e [-p \fIpath\fR...]] \fIpoolname\fR
+
+.P
+\fBzdb\fR -l [-uA] \fIdevice\fR
+
+.P
+\fBzdb\fR -C [-A] [-U \fIcache\fR]
+
.Sh DESCRIPTION
The
-.Nm
-command is used by support engineers to diagnose failures and
-gather statistics. Since the
-.Tn ZFS
-file system is always consistent on disk and is self-repairing,
-.Nm
-should only be run under the direction by a support engineer.
-.Pp
-If no arguments are specified,
-.Nm
-performs basic consistency checks on the pool and associated datasets, and
-report any problems detected.
-.Nm
-Any options supported by this command are internal to Sun and subject to change
-at any time.
-.Sh EXIT STATUS
-The following exit values are returned:
-.Bl -tag -offset 2n -width 2n
-.It 0
-The pool is consistent.
-.It 1
-An error was detected.
-.It 2
-Invalid command line options were specified.
-.El
+.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 (and facilities) may change. This is neither
+a fsck(1M) nor an fsdb(1M) utility.
+.p
+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
+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:
+.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
+Verify the checksum of all metadata blocks while printing block statistics
+(see \fB-b\fR).
+.sp
+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
+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.
+.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
+Display the vdev labels from the specified device. If the \fB-u\fR option is
+also specified, also display the uberblocks on this device.
+.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
+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
+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
+Print block pointer
+.RE
+.sp
+.ne 2
+.na
+\fBd\fR
+.ad
+.sp .6
+.RS 4n
+Decompress the block
+.RE
+.sp
+.ne 2
+.na
+\fBe\fR
+.ad
+.sp .6
+.RS 4n
+Byte swap the block
+.RE
+.sp
+.ne 2
+.na
+\fBg\fR
+.ad
+.sp .6
+.RS 4n
+Dump gang block header
+.RE
+.sp
+.ne 2
+.na
+\fBi\fR
+.ad
+.sp .6
+.RS 4n
+Dump indirect block
+.RE
+.sp
+.ne 2
+.na
+\fBr\fR
+.ad
+.sp .6
+.RS 4n
+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
+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
+Display the current uberblock.
+.RE
+.P
+Other options:
+.sp
+.ne 2
+.na
+\fB-A\fR
+.ad
+.sp .6
+.RS 4n
+Do not abort should any assertion fail.
+.RE
+.sp
+.ne 2
+.na
+\fB-AA\fR
+.ad
+.sp .6
+.RS 4n
+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
+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-F\fR
+.ad
+.sp .6
+.RS 4n
+Attempt to make an unreadable pool readable by trying progressively older
+transactions.
+.RE
+.sp
+.ne 2
+.na
+\fB-P\fR
+.ad
+.sp .6
+.RS 4n
+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. This option is only
+valid with \fB-C\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
+.P
+Specifying a display option more than once enables verbosity for only that
+option, with more occurrences enabling more verbosity.
+.P
+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
+# 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
+# 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
+# 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
+# zdb -S 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
+.fi
+.in -2
+.sp
.Sh SEE ALSO
-.Xr zfs 8 ,
+.Xr zfs 8,
.Xr zpool 8
.Sh AUTHORS
This manual page is a
.Xr mdoc 7
-reimplementation of the
+reimplementation of
.Tn OpenSolaris
manual page
-.Em zdb(1M) ,
+.Em zdb(1M),
modified and customized for
.Fx
and licensed under the
diff -r b470a5db430e cddl/contrib/opensolaris/cmd/zdb/zdb.c
--- a/cddl/contrib/opensolaris/cmd/zdb/zdb.c Mon Apr 30 06:02:00 2012 +0000
+++ b/cddl/contrib/opensolaris/cmd/zdb/zdb.c Mon Apr 30 11:28:04 2012 +0000
@@ -102,13 +102,16 @@
usage(void)
{
(void) fprintf(stderr,
- "Usage: %s [-CumdibcsDvhL] poolname [object...]\n"
- " %s [-div] dataset [object...]\n"
- " %s -m [-L] poolname [vdev [metaslab...]]\n"
- " %s -R poolname vdev:offset:size[:flags]\n"
- " %s -S poolname\n"
- " %s -l [-u] device\n"
- " %s -C\n\n",
+ "Usage: %s [-CumdibcsDvhLXFPA] [-t txg] [-e [-p path...]]"
+ "poolname [object...]\n"
+ " %s [-divPA] [-e -p path...] dataset [object...]\n"
+ " %s -m [-LXFPA] [-t txg] [-e [-p path...]]"
+ "poolname [vdev [metaslab...]]\n"
+ " %s -R [-A] [-e [-p path...]] poolname "
+ "vdev:offset:size[:flags]\n"
+ " %s -S [-PA] [-e [-p path...]] poolname\n"
+ " %s -l [-uA] device\n"
+ " %s -C [-A] [-U config]\n\n",
cmdname, cmdname, cmdname, cmdname, cmdname, cmdname, cmdname);
(void) fprintf(stderr, " Dataset name must include at least one "
@@ -150,7 +153,7 @@
"has altroot/not in a cachefile\n");
(void) fprintf(stderr, " -p <path> -- use one or more with "
"-e to specify path to vdev dir\n");
- (void) fprintf(stderr, " -P print numbers parsable\n");
+ (void) fprintf(stderr, " -P print numbers in parseable form\n");
(void) fprintf(stderr, " -t <txg> -- highest txg to use when "
"searching for uberblocks\n");
(void) fprintf(stderr, "Specify an option more than once (e.g. -bb) "
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205010406.q4146XI7041779>