| blob | b0ee659701d41be5699bda7765b8c16b9dfa209b |
1 .\"
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or https://opensource.org/licenses/CDDL-1.0.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
22 .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
23 .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
24 .\" Copyright (c) 2017 Datto Inc.
25 .\" Copyright (c) 2018 George Melikov. All Rights Reserved.
26 .\" Copyright 2017 Nexenta Systems, Inc.
27 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
28 .\"
29 .Dd March 16, 2022
30 .Dt ZPOOL-LIST 8
31 .Os
32 .
33 .Sh NAME
34 .Nm zpool-list
35 .Nd list information about ZFS storage pools
36 .Sh SYNOPSIS
37 .Nm zpool
38 .Cm list
39 .Op Fl HgLpPv
40 .Op Fl j Op Ar --json-int, --json-pool-key-guid
41 .Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns …
42 .Op Fl T Sy u Ns | Ns Sy d
43 .Oo Ar pool Oc Ns …
44 .Op Ar interval Op Ar count
45 .
46 .Sh DESCRIPTION
47 Lists the given pools along with a health status and space usage.
48 If no
49 .Ar pool Ns s
50 are specified, all pools in the system are listed.
51 When given an
52 .Ar interval ,
53 the information is printed every
54 .Ar interval
55 seconds until killed.
56 If
57 .Ar count
58 is specified, the command exits after
59 .Ar count
60 reports are printed.
61 .Bl -tag -width Ds
62 .It Fl j Op Ar --json-int, --json-pool-key-guid
63 Display the list of pools in JSON format.
64 Specify
65 .Sy --json-int
66 to display the numbers in integer format instead of strings.
67 Specify
68 .Sy --json-pool-key-guid
69 to set pool GUID as key for pool objects instead of pool names.
70 .It Fl g
71 Display vdev GUIDs instead of the normal device names.
72 These GUIDs can be used in place of device names for the zpool
73 detach/offline/remove/replace commands.
74 .It Fl H
75 Scripted mode.
76 Do not display headers, and separate fields by a single tab instead of arbitrary
77 space.
78 .It Fl o Ar property
79 Comma-separated list of properties to display.
80 See the
81 .Xr zpoolprops 7
82 manual page for a list of valid properties.
83 The default list is
84 .Sy name , size , allocated , free , checkpoint, expandsize , fragmentation ,
85 .Sy capacity , dedupratio , health , altroot .
86 .It Fl L
87 Display real paths for vdevs resolving all symbolic links.
88 This can be used to look up the current block device name regardless of the
89 .Pa /dev/disk
90 path used to open it.
91 .It Fl p
92 Display numbers in parsable
93 .Pq exact
94 values.
95 .It Fl P
96 Display full paths for vdevs instead of only the last component of
97 the path.
98 This can be used in conjunction with the
99 .Fl L
100 flag.
101 .It Fl T Sy u Ns | Ns Sy d
102 Display a time stamp.
103 Specify
104 .Sy u
105 for a printed representation of the internal representation of time.
106 See
107 .Xr time 1 .
108 Specify
109 .Sy d
110 for standard date format.
111 See
112 .Xr date 1 .
113 .It Fl v
114 Verbose statistics.
115 Reports usage statistics for individual vdevs within the pool, in addition to
116 the pool-wide statistics.
117 .El
118 .
119 .Sh EXAMPLES
120 .\" These are, respectively, examples 6, 15 from zpool.8
121 .\" Make sure to update them bidirectionally
122 .Ss Example 1 : No Listing Available ZFS Storage Pools
123 The following command lists all available pools on the system.
124 In this case, the pool
125 .Ar zion
126 is faulted due to a missing device.
127 The results from this command are similar to the following:
128 .Bd -literal -compact -offset Ds
129 .No # Nm zpool Cm list
130 NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
131 rpool 19.9G 8.43G 11.4G - 33% 42% 1.00x ONLINE -
132 tank 61.5G 20.0G 41.5G - 48% 32% 1.00x ONLINE -
133 zion - - - - - - - FAULTED -
134 .Ed
135 .
136 .Ss Example 2 : No Displaying expanded space on a device
137 The following command displays the detailed information for the pool
138 .Ar data .
139 This pool is comprised of a single raidz vdev where one of its devices
140 increased its capacity by 10 GiB.
141 In this example, the pool will not be able to utilize this extra capacity until
142 all the devices under the raidz vdev have been expanded.
143 .Bd -literal -compact -offset Ds
144 .No # Nm zpool Cm list Fl v Ar data
145 NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
146 data 23.9G 14.6G 9.30G - 48% 61% 1.00x ONLINE -
147 raidz1 23.9G 14.6G 9.30G - 48%
148 sda - - - - -
149 sdb - - - 10G -
150 sdc - - - - -
151 .Ed
152 .
153 .Ss Example 3 : No Displaying expanded space on a device
154 The following command lists all available pools on the system in JSON
155 format.
156 .Bd -literal -compact -offset Ds
157 .No # Nm zpool Cm list Fl j | Nm jq
158 {
159 "output_version": {
160 "command": "zpool list",
161 "vers_major": 0,
162 "vers_minor": 1
163 },
164 "pools": {
165 "tank": {
166 "name": "tank",
167 "type": "POOL",
168 "state": "ONLINE",
169 "guid": "15220353080205405147",
170 "txg": "2671",
171 "spa_version": "5000",
172 "zpl_version": "5",
173 "properties": {
174 "size": {
175 "value": "111G",
176 "source": {
177 "type": "NONE",
178 "data": "-"
179 }
180 },
181 "allocated": {
182 "value": "30.8G",
183 "source": {
184 "type": "NONE",
185 "data": "-"
186 }
187 },
188 "free": {
189 "value": "80.2G",
190 "source": {
191 "type": "NONE",
192 "data": "-"
193 }
194 },
195 "checkpoint": {
196 "value": "-",
197 "source": {
198 "type": "NONE",
199 "data": "-"
200 }
201 },
202 "expandsize": {
203 "value": "-",
204 "source": {
205 "type": "NONE",
206 "data": "-"
207 }
208 },
209 "fragmentation": {
210 "value": "0%",
211 "source": {
212 "type": "NONE",
213 "data": "-"
214 }
215 },
216 "capacity": {
217 "value": "27%",
218 "source": {
219 "type": "NONE",
220 "data": "-"
221 }
222 },
223 "dedupratio": {
224 "value": "1.00x",
225 "source": {
226 "type": "NONE",
227 "data": "-"
228 }
229 },
230 "health": {
231 "value": "ONLINE",
232 "source": {
233 "type": "NONE",
234 "data": "-"
235 }
236 },
237 "altroot": {
238 "value": "-",
239 "source": {
240 "type": "DEFAULT",
241 "data": "-"
242 }
243 }
244 }
245 }
246 }
247 }
249 .Ed
250 .
251 .Sh SEE ALSO
252 .Xr zpool-import 8 ,
253 .Xr zpool-status 8