Date: Thu, 10 May 2012 04:11:40 +0000 (UTC) From: Martin Matuska <mm@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r235212 - head/cddl/contrib/opensolaris/cmd/zdb Message-ID: <201205100411.q4A4Be19016740@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mm Date: Thu May 10 04:11:39 2012 New Revision: 235212 URL: http://svn.freebsd.org/changeset/base/235212 Log: Import illumos changeset 13618:c6ae14a341e8 [1]: 2088 zdb could use a reasonable manual page Rewrite new zdb manpage to mdoc(7) References: https://www.illumos.org/issues/2088 PR: kern/167467 [1] Submitted by: Marcelo Araujo <araujo@FreeBSD.org> [1] Reviewed by: mm Obtained from: Illumos (issue #2088) MFC after: 1 week Modified: head/cddl/contrib/opensolaris/cmd/zdb/zdb.8 head/cddl/contrib/opensolaris/cmd/zdb/zdb.c Modified: head/cddl/contrib/opensolaris/cmd/zdb/zdb.8 ============================================================================== --- head/cddl/contrib/opensolaris/cmd/zdb/zdb.8 Thu May 10 02:07:00 2012 (r235211) +++ head/cddl/contrib/opensolaris/cmd/zdb/zdb.8 Thu May 10 04:11:39 2012 (r235212) @@ -1,61 +1,286 @@ '\" te -.\" Copyright (c) 2011, Martin Matuska <mm@FreeBSD.org>. +.\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>. .\" All Rights Reserved. .\" -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] +.\" 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. .\" -.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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, Marcelo Araujo <araujo@FreeBSD.org>. +.\" All Rights Reserved. .\" .\" $FreeBSD$ .\" -.Dd November 26, 2011 +.Dd May 10, 2012 .Dt ZDB 8 .Os .Sh NAME .Nm zdb -.Nd ZFS debugger +.Nd Display zpool debugging and consistency information .Sh SYNOPSIS .Nm -.Ar pool +.Op Fl CumdibcsDvhLXFPA +.Op Fl e Op Fl p Ar path... +.Op Fl t Ar txg +.Ar poolname +.Op Ar object ... +.Nm +.Op Fl divPA +.Op Fl e Op Fl p Ar path... +.Ar dataset +.Op Ar object ... +.Nm +.Fl m Op Fl LXFPA +.Op Fl t Ar txg +.Op Fl e Op Fl p Ar path... +.Ar poolname +.Nm +.Fl R Op Fl A +.Op Fl e Op Fl p Ar path... +.Ar poolname +.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags +.Nm +.Fl S +.Op Fl AP +.Op Fl e Op Fl p Ar path... +.Ar poolname +.Nm +.Fl l +.Op Fl uA +.Ar device +.Nm +.Fl C +.Op Fl A +.Op Fl U Ar cache .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. +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 +.Xr fsck 8 +nor a +.Xr fsdb 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 +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 indent +.It Fl b +Display statistics regarding the number, size (logical, physical and +allocated) and deduplication of blocks. +.It Fl c +Verify the checksum of all metadata blocks while printing block statistics +(see +.Fl b Ns ). +.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 +.Ns ( Pa /etc/zfs/zpool.cache Ns ). +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. +.Pp +If object IDs are specified, display information about those specific objects only. +.It Fl D +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). +.Pp +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. +.It Fl h +Display pool history similar to +.Cm zpool history , +but include internal changes, transaction, and dataset information. +.It Fl i +Display information about intent log (ZIL) entries relating to each +dataset. +If specified multiple times, display counts of each intent log transaction +type. +.It Fl l Ar device +Display the vdev labels from the specified device. +If the +.Fl u +option is also specified, also display the uberblocks on this device. +.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. +.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. +.It Xo +.Fl R Ar poolname +.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : 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 +.Fl r +flag, below. +.Pp +The block is specified in terms of a colon-separated tuple +.Ar vdev +(an integer vdev identifier) +.Ar offset +(the offset within the vdev) +.Ar size +(the size of the block to read) and, optionally, +.Ar flags +(a set of flags, described below). +.Bl -tag -width indent +.It Sy b offset +Print block pointer +.It Sy d +Decompress the block +.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 +.El +.It Fl s +Report statistics on +.Nm Ns 's +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. +.It Fl u +Display the current uberblock. +.El +.Pp +Other options: +.Bl -tag -width indent +.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 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 F +Attempt to make an unreadable pool readable by trying progressively older +transactions. +.It Fl P +Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather +than 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 . +This option is only valid with +.Fl C +.It Fl v +Enable verbosity. +Specify multiple times for increased verbosity. +.It Fl X +Attempt +.Ql 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. +.Pp +If no options are specified, all information about the named pool will be +displayed at default verbosity. +.Sh EXAMPLES +.Bl -tag -width 0n +.It Sy Example 1 Display the configuration of imported pool 'rpool' +.Bd -literal -offset 2n +.Li # Ic zdb -C rpool + +MOS Configuration: + version: 28 + name: 'rpool' + ... +.Ed +.It Sy Example 2 Display basic dataset information about 'rpool' +.Bd -literal -offset 2n +.Li # Ic 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 +... +.Ed +.It Xo Sy Example 3 Display basic information about object 0 in +.Sy 'rpool/export/home' +.Xc +.Bd -literal -offset 2n +.Li # Ic 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 +.Ed +.It Xo Sy Example 4 Display the predicted effect of enabling deduplication on +.Sy 'rpool' +.Xc +.Bd -literal -offset 2n +.Li # Ic 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 +.Ed .El .Sh SEE ALSO .Xr zfs 8 , @@ -64,16 +289,18 @@ Invalid command line options were specif This manual page is a .Xr mdoc 7 reimplementation of the -.Tn OpenSolaris +.Tn illumos manual page .Em zdb(1M) , modified and customized for .Fx and licensed under the -.Tn Common Development and Distribution License +Common Development and Distribution License .Pq Tn CDDL . .Pp The .Xr mdoc 7 implementation of this manual page was initially written by -.An Martin Matuska Aq mm@FreeBSD.org . +.An Martin Matuska Aq mm@FreeBSD.org +and +.An Marcelo Araujo Aq araujo@FreeBSD.org . Modified: head/cddl/contrib/opensolaris/cmd/zdb/zdb.c ============================================================================== --- head/cddl/contrib/opensolaris/cmd/zdb/zdb.c Thu May 10 02:07:00 2012 (r235211) +++ head/cddl/contrib/opensolaris/cmd/zdb/zdb.c Thu May 10 04:11:39 2012 (r235212) @@ -102,13 +102,16 @@ static void 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 @@ usage(void) "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) "
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205100411.q4A4Be19016740>