1'\" te
2.\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>.
3.\" All Rights Reserved.
4.\"
5.\" This file and its contents are supplied under the terms of the
6.\" Common Development and Distribution License ("CDDL"), version 1.0.
7.\" You may only use this file in accordance with the terms of version
8.\" 1.0 of the CDDL.
9.\"
10.\" A full copy of the text of the CDDL should have accompanied this
11.\" source. A copy of the CDDL is also available via the Internet at
12.\" http://www.illumos.org/license/CDDL.
13.\"
14.\"
15.\" Copyright 2012, Richard Lowe.
16.\" Copyright (c) 2012, Marcelo Araujo <araujo@FreeBSD.org>.
17.\" All Rights Reserved.
18.\"
| 1'\" te
2.\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>.
3.\" All Rights Reserved.
4.\"
5.\" This file and its contents are supplied under the terms of the
6.\" Common Development and Distribution License ("CDDL"), version 1.0.
7.\" You may only use this file in accordance with the terms of version
8.\" 1.0 of the CDDL.
9.\"
10.\" A full copy of the text of the CDDL should have accompanied this
11.\" source. A copy of the CDDL is also available via the Internet at
12.\" http://www.illumos.org/license/CDDL.
13.\"
14.\"
15.\" Copyright 2012, Richard Lowe.
16.\" Copyright (c) 2012, Marcelo Araujo <araujo@FreeBSD.org>.
17.\" All Rights Reserved.
18.\"
|
19.\" $FreeBSD: stable/9/cddl/contrib/opensolaris/cmd/zdb/zdb.8 235701 2012-05-20 22:21:59Z mm $
| 19.\" $FreeBSD: stable/9/cddl/contrib/opensolaris/cmd/zdb/zdb.8 243674 2012-11-29 14:05:04Z mm $
|
20.\"
21.Dd May 10, 2012
22.Dt ZDB 8
23.Os
24.Sh NAME
25.Nm zdb
26.Nd Display zpool debugging and consistency information
27.Sh SYNOPSIS
28.Nm
29.Op Fl CumdibcsDvhLXFPA
30.Op Fl e Op Fl p Ar path...
31.Op Fl t Ar txg
32.Ar poolname
33.Op Ar object ...
34.Nm
35.Op Fl divPA
36.Op Fl e Op Fl p Ar path...
37.Ar dataset
38.Op Ar object ...
39.Nm
40.Fl m Op Fl LXFPA
41.Op Fl t Ar txg
42.Op Fl e Op Fl p Ar path...
43.Ar poolname
44.Nm
45.Fl R Op Fl A
46.Op Fl e Op Fl p Ar path...
47.Ar poolname
48.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
49.Nm
50.Fl S
51.Op Fl AP
52.Op Fl e Op Fl p Ar path...
53.Ar poolname
54.Nm
55.Fl l
56.Op Fl uA
57.Ar device
58.Nm
59.Fl C
60.Op Fl A
61.Op Fl U Ar cache
62.Sh DESCRIPTION
63The
64.Nm
65utility displays information about a ZFS pool useful for debugging and
66performs some amount of consistency checking.
67It is a not a general purpose tool and options (and facilities) may change.
68This is neither a
69.Xr fsck 8
70nor a
71.Xr fsdb 8
72utility.
73.Pp
74The output of this command in general reflects the on-disk structure of a ZFS
75pool, and is inherently unstable.
76The precise output of most invocations is not documented, a knowledge of ZFS
77internals is assumed.
78.Pp
79When operating on an imported and active pool it is possible, though unlikely,
80that zdb may interpret inconsistent pool data and behave erratically.
81.Sh OPTIONS
82Display options:
83.Bl -tag -width indent
84.It Fl b
85Display statistics regarding the number, size (logical, physical and
86allocated) and deduplication of blocks.
87.It Fl c
88Verify the checksum of all metadata blocks while printing block statistics
89(see
90.Fl b Ns ).
91.Pp
92If specified multiple times, verify the checksums of all blocks.
93.It Fl C
94Display information about the configuration. If specified with no other
95options, instead display information about the cache file
| 20.\"
21.Dd May 10, 2012
22.Dt ZDB 8
23.Os
24.Sh NAME
25.Nm zdb
26.Nd Display zpool debugging and consistency information
27.Sh SYNOPSIS
28.Nm
29.Op Fl CumdibcsDvhLXFPA
30.Op Fl e Op Fl p Ar path...
31.Op Fl t Ar txg
32.Ar poolname
33.Op Ar object ...
34.Nm
35.Op Fl divPA
36.Op Fl e Op Fl p Ar path...
37.Ar dataset
38.Op Ar object ...
39.Nm
40.Fl m Op Fl LXFPA
41.Op Fl t Ar txg
42.Op Fl e Op Fl p Ar path...
43.Ar poolname
44.Nm
45.Fl R Op Fl A
46.Op Fl e Op Fl p Ar path...
47.Ar poolname
48.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
49.Nm
50.Fl S
51.Op Fl AP
52.Op Fl e Op Fl p Ar path...
53.Ar poolname
54.Nm
55.Fl l
56.Op Fl uA
57.Ar device
58.Nm
59.Fl C
60.Op Fl A
61.Op Fl U Ar cache
62.Sh DESCRIPTION
63The
64.Nm
65utility displays information about a ZFS pool useful for debugging and
66performs some amount of consistency checking.
67It is a not a general purpose tool and options (and facilities) may change.
68This is neither a
69.Xr fsck 8
70nor a
71.Xr fsdb 8
72utility.
73.Pp
74The output of this command in general reflects the on-disk structure of a ZFS
75pool, and is inherently unstable.
76The precise output of most invocations is not documented, a knowledge of ZFS
77internals is assumed.
78.Pp
79When operating on an imported and active pool it is possible, though unlikely,
80that zdb may interpret inconsistent pool data and behave erratically.
81.Sh OPTIONS
82Display options:
83.Bl -tag -width indent
84.It Fl b
85Display statistics regarding the number, size (logical, physical and
86allocated) and deduplication of blocks.
87.It Fl c
88Verify the checksum of all metadata blocks while printing block statistics
89(see
90.Fl b Ns ).
91.Pp
92If specified multiple times, verify the checksums of all blocks.
93.It Fl C
94Display information about the configuration. If specified with no other
95options, instead display information about the cache file
|
96.Ns ( Pa /etc/zfs/zpool.cache Ns ).
| 96.Po Pa /etc/zfs/zpool.cache Pc .
|
97To specify the cache file to display, see
98.Fl U
99.Pp
100If specified multiple times, and a pool name is also specified display both
101the cached configuration and the on-disk configuration.
102If specified multiple times with
| 97To specify the cache file to display, see
98.Fl U
99.Pp
100If specified multiple times, and a pool name is also specified display both
101the cached configuration and the on-disk configuration.
102If specified multiple times with
|
103.FL e
| 103.Fl e
|
104also display the configuration that would be used were the pool to be
105imported.
106.It Fl d
107Display information about datasets. Specified once, displays basic dataset
108information: ID, create transaction, size, and object count.
109.Pp
110If specified multiple times provides greater and greater verbosity.
111.Pp
112If object IDs are specified, display information about those specific objects only.
113.It Fl D
114Display deduplication statistics, including the deduplication ratio (dedup),
115compression ratio (compress), inflation due to the zfs copies property
116(copies), and an overall effective ratio (dedup * compress / copies).
117.Pp
118If specified twice, display a histogram of deduplication statistics, showing
119the allocated (physically present on disk) and referenced (logically
120referenced in the pool) block counts and sizes by reference count.
121.It Fl h
122Display pool history similar to
123.Cm zpool history ,
124but include internal changes, transaction, and dataset information.
125.It Fl i
126Display information about intent log (ZIL) entries relating to each
127dataset.
128If specified multiple times, display counts of each intent log transaction
129type.
130.It Fl l Ar device
131Display the vdev labels from the specified device.
132If the
133.Fl u
134option is also specified, also display the uberblocks on this device.
135.It Fl L
136Disable leak tracing and the loading of space maps.
137By default,
| 104also display the configuration that would be used were the pool to be
105imported.
106.It Fl d
107Display information about datasets. Specified once, displays basic dataset
108information: ID, create transaction, size, and object count.
109.Pp
110If specified multiple times provides greater and greater verbosity.
111.Pp
112If object IDs are specified, display information about those specific objects only.
113.It Fl D
114Display deduplication statistics, including the deduplication ratio (dedup),
115compression ratio (compress), inflation due to the zfs copies property
116(copies), and an overall effective ratio (dedup * compress / copies).
117.Pp
118If specified twice, display a histogram of deduplication statistics, showing
119the allocated (physically present on disk) and referenced (logically
120referenced in the pool) block counts and sizes by reference count.
121.It Fl h
122Display pool history similar to
123.Cm zpool history ,
124but include internal changes, transaction, and dataset information.
125.It Fl i
126Display information about intent log (ZIL) entries relating to each
127dataset.
128If specified multiple times, display counts of each intent log transaction
129type.
130.It Fl l Ar device
131Display the vdev labels from the specified device.
132If the
133.Fl u
134option is also specified, also display the uberblocks on this device.
135.It Fl L
136Disable leak tracing and the loading of space maps.
137By default,
|
138.Nm
| 138.Nm
|
139verifies that all non-free blocks are referenced, which can be very expensive.
140.It Fl m
141Display the offset, spacemap, and free space of each metaslab.
142When specified twice, also display information about the maximum contiguous
143free space and the percentage of free space in each space map.
144When specified three times display every spacemap record.
145.It Xo
146.Fl R Ar poolname
147.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
148.Xc
149Read and display a block from the specified device. By default the block is
150displayed as a hex dump, but see the description of the
151.Fl r
152flag, below.
153.Pp
154The block is specified in terms of a colon-separated tuple
155.Ar vdev
156(an integer vdev identifier)
157.Ar offset
158(the offset within the vdev)
159.Ar size
160(the size of the block to read) and, optionally,
161.Ar flags
162(a set of flags, described below).
163.Bl -tag -width indent
164.It Sy b offset
165Print block pointer
166.It Sy d
167Decompress the block
168.It Sy e
169Byte swap the block
170.It Sy g
171Dump gang block header
172.It Sy i
173Dump indirect block
174.It Sy r
175Dump raw uninterpreted block data
176.El
177.It Fl s
178Report statistics on
179.Nm Ns 's
180I/O.
181Display operation counts, bandwidth, and error counts of I/O to the pool from
182.Nm .
183.It Fl S
184Simulate the effects of deduplication, constructing a DDT and then display
185that DDT as with \fB-DD\fR.
186.It Fl u
187Display the current uberblock.
188.El
189.Pp
190Other options:
191.Bl -tag -width indent
192.It Fl A
193Do not abort should any assertion fail.
194.It Fl AA
195Enable panic recovery, certain errors which would otherwise be fatal are
196demoted to warnings.
197.It Fl AAA
198Do not abort if asserts fail and also enable panic recovery.
199.It Fl e Op Fl p Ar path...
200Operate on an exported pool, not present in
201.Pa /etc/zfs/zpool.cache .
202The
203.Fl p
204flag specifies the path under which devices are to be searched.
205.It Fl F
206Attempt to make an unreadable pool readable by trying progressively older
207transactions.
208.It Fl P
209Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather
210than 1M.
211.It Fl t Ar transaction
212Specify the highest transaction to use when searching for uberblocks.
213See also the
214.Fl u
215and
216.Fl l
217options for a means to see the available uberblocks and their associated
218transaction numbers.
219.It Fl U Ar cachefile
220Use a cache file other than
221.Pa /etc/zfs/zpool.cache .
222This option is only valid with
223.Fl C
224.It Fl v
225Enable verbosity.
226Specify multiple times for increased verbosity.
227.It Fl X
228Attempt
229.Ql extreme
230transaction rewind, that is attempt the same recovery as
231.Fl F
232but read transactions otherwise deemed too old.
233.El
234.Pp
235Specifying a display option more than once enables verbosity for only that
236option, with more occurrences enabling more verbosity.
237.Pp
238If no options are specified, all information about the named pool will be
239displayed at default verbosity.
240.Sh EXAMPLES
241.Bl -tag -width 0n
242.It Sy Example 1 Display the configuration of imported pool 'rpool'
243.Bd -literal -offset 2n
244.Li # Ic zdb -C rpool
245
246MOS Configuration:
247 version: 28
248 name: 'rpool'
249 ...
250.Ed
251.It Sy Example 2 Display basic dataset information about 'rpool'
252.Bd -literal -offset 2n
253.Li # Ic zdb -d rpool
254Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
255Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
| 139verifies that all non-free blocks are referenced, which can be very expensive.
140.It Fl m
141Display the offset, spacemap, and free space of each metaslab.
142When specified twice, also display information about the maximum contiguous
143free space and the percentage of free space in each space map.
144When specified three times display every spacemap record.
145.It Xo
146.Fl R Ar poolname
147.Ar vdev Ns : Ns Ar offset Ns : Ns Ar size Ns Op Ns : Ns Ar flags
148.Xc
149Read and display a block from the specified device. By default the block is
150displayed as a hex dump, but see the description of the
151.Fl r
152flag, below.
153.Pp
154The block is specified in terms of a colon-separated tuple
155.Ar vdev
156(an integer vdev identifier)
157.Ar offset
158(the offset within the vdev)
159.Ar size
160(the size of the block to read) and, optionally,
161.Ar flags
162(a set of flags, described below).
163.Bl -tag -width indent
164.It Sy b offset
165Print block pointer
166.It Sy d
167Decompress the block
168.It Sy e
169Byte swap the block
170.It Sy g
171Dump gang block header
172.It Sy i
173Dump indirect block
174.It Sy r
175Dump raw uninterpreted block data
176.El
177.It Fl s
178Report statistics on
179.Nm Ns 's
180I/O.
181Display operation counts, bandwidth, and error counts of I/O to the pool from
182.Nm .
183.It Fl S
184Simulate the effects of deduplication, constructing a DDT and then display
185that DDT as with \fB-DD\fR.
186.It Fl u
187Display the current uberblock.
188.El
189.Pp
190Other options:
191.Bl -tag -width indent
192.It Fl A
193Do not abort should any assertion fail.
194.It Fl AA
195Enable panic recovery, certain errors which would otherwise be fatal are
196demoted to warnings.
197.It Fl AAA
198Do not abort if asserts fail and also enable panic recovery.
199.It Fl e Op Fl p Ar path...
200Operate on an exported pool, not present in
201.Pa /etc/zfs/zpool.cache .
202The
203.Fl p
204flag specifies the path under which devices are to be searched.
205.It Fl F
206Attempt to make an unreadable pool readable by trying progressively older
207transactions.
208.It Fl P
209Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather
210than 1M.
211.It Fl t Ar transaction
212Specify the highest transaction to use when searching for uberblocks.
213See also the
214.Fl u
215and
216.Fl l
217options for a means to see the available uberblocks and their associated
218transaction numbers.
219.It Fl U Ar cachefile
220Use a cache file other than
221.Pa /etc/zfs/zpool.cache .
222This option is only valid with
223.Fl C
224.It Fl v
225Enable verbosity.
226Specify multiple times for increased verbosity.
227.It Fl X
228Attempt
229.Ql extreme
230transaction rewind, that is attempt the same recovery as
231.Fl F
232but read transactions otherwise deemed too old.
233.El
234.Pp
235Specifying a display option more than once enables verbosity for only that
236option, with more occurrences enabling more verbosity.
237.Pp
238If no options are specified, all information about the named pool will be
239displayed at default verbosity.
240.Sh EXAMPLES
241.Bl -tag -width 0n
242.It Sy Example 1 Display the configuration of imported pool 'rpool'
243.Bd -literal -offset 2n
244.Li # Ic zdb -C rpool
245
246MOS Configuration:
247 version: 28
248 name: 'rpool'
249 ...
250.Ed
251.It Sy Example 2 Display basic dataset information about 'rpool'
252.Bd -literal -offset 2n
253.Li # Ic zdb -d rpool
254Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
255Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
|
256...
| 256 ...
|
257.Ed
258.It Xo Sy Example 3 Display basic information about object 0 in
259.Sy 'rpool/export/home'
260.Xc
261.Bd -literal -offset 2n
262.Li # Ic zdb -d rpool/export/home 0
263Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
264
265 Object lvl iblk dblk dsize lsize %full type
266 0 7 16K 16K 15.0K 16K 25.00 DMU dnode
267.Ed
268.It Xo Sy Example 4 Display the predicted effect of enabling deduplication on
269.Sy 'rpool'
270.Xc
271.Bd -literal -offset 2n
272.Li # Ic zdb -S rpool
273Simulated DDT histogram:
274
| 257.Ed
258.It Xo Sy Example 3 Display basic information about object 0 in
259.Sy 'rpool/export/home'
260.Xc
261.Bd -literal -offset 2n
262.Li # Ic zdb -d rpool/export/home 0
263Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
264
265 Object lvl iblk dblk dsize lsize %full type
266 0 7 16K 16K 15.0K 16K 25.00 DMU dnode
267.Ed
268.It Xo Sy Example 4 Display the predicted effect of enabling deduplication on
269.Sy 'rpool'
270.Xc
271.Bd -literal -offset 2n
272.Li # Ic zdb -S rpool
273Simulated DDT histogram:
274
|
275bucket allocated referenced
| 275bucket allocated referenced
|
276______ ______________________________ ______________________________
277refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE
278------ ------ ----- ----- ----- ------ ----- ----- -----
279 1 694K 27.1G 15.0G 15.0G 694K 27.1G 15.0G 15.0G
280 2 35.0K 1.33G 699M 699M 74.7K 2.79G 1.45G 1.45G
281 ...
282dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
283.Ed
284.El
285.Sh SEE ALSO
286.Xr zfs 8 ,
287.Xr zpool 8
288.Sh AUTHORS
289This manual page is a
290.Xr mdoc 7
291reimplementation of the
292.Tn illumos
293manual page
294.Em zdb(1M) ,
295modified and customized for
296.Fx
297and licensed under the
298Common Development and Distribution License
299.Pq Tn CDDL .
300.Pp
301The
302.Xr mdoc 7
303implementation of this manual page was initially written by
304.An Martin Matuska Aq mm@FreeBSD.org
305and
306.An Marcelo Araujo Aq araujo@FreeBSD.org .
| 276______ ______________________________ ______________________________
277refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE
278------ ------ ----- ----- ----- ------ ----- ----- -----
279 1 694K 27.1G 15.0G 15.0G 694K 27.1G 15.0G 15.0G
280 2 35.0K 1.33G 699M 699M 74.7K 2.79G 1.45G 1.45G
281 ...
282dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
283.Ed
284.El
285.Sh SEE ALSO
286.Xr zfs 8 ,
287.Xr zpool 8
288.Sh AUTHORS
289This manual page is a
290.Xr mdoc 7
291reimplementation of the
292.Tn illumos
293manual page
294.Em zdb(1M) ,
295modified and customized for
296.Fx
297and licensed under the
298Common Development and Distribution License
299.Pq Tn CDDL .
300.Pp
301The
302.Xr mdoc 7
303implementation of this manual page was initially written by
304.An Martin Matuska Aq mm@FreeBSD.org
305and
306.An Marcelo Araujo Aq araujo@FreeBSD.org .
|