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
This commit is contained in:
Martin Matuska
parent
2fccbf04cc
commit
9846ab4ed2
@ -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.
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" 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.
|
||||
.\" 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.
|
||||
.\"
|
||||
.\" 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]
|
||||
.\"
|
||||
.\" 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 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.
|
||||
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
|
||||
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.
|
||||
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 specified.
|
||||
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 .
|
||||
|
||||
@ -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) "
|
||||
|
||||
Loading…
Reference in New Issue
Block a user