xref: /freebsd-src/sys/contrib/openzfs/man/man8/zfs-list.8 (revision ce4dcb97ca433b2a2f03fbae957dae0ff16f6f51)
1eda14cbcSMatt Macy.\"
2eda14cbcSMatt Macy.\" CDDL HEADER START
3eda14cbcSMatt Macy.\"
4eda14cbcSMatt Macy.\" The contents of this file are subject to the terms of the
5eda14cbcSMatt Macy.\" Common Development and Distribution License (the "License").
6eda14cbcSMatt Macy.\" You may not use this file except in compliance with the License.
7eda14cbcSMatt Macy.\"
8eda14cbcSMatt Macy.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9271171e0SMartin Matuska.\" or https://opensource.org/licenses/CDDL-1.0.
10eda14cbcSMatt Macy.\" See the License for the specific language governing permissions
11eda14cbcSMatt Macy.\" and limitations under the License.
12eda14cbcSMatt Macy.\"
13eda14cbcSMatt Macy.\" When distributing Covered Code, include this CDDL HEADER in each
14eda14cbcSMatt Macy.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15eda14cbcSMatt Macy.\" If applicable, add the following below this CDDL HEADER, with the
16eda14cbcSMatt Macy.\" fields enclosed by brackets "[]" replaced with your own identifying
17eda14cbcSMatt Macy.\" information: Portions Copyright [yyyy] [name of copyright owner]
18eda14cbcSMatt Macy.\"
19eda14cbcSMatt Macy.\" CDDL HEADER END
20eda14cbcSMatt Macy.\"
21eda14cbcSMatt Macy.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
22eda14cbcSMatt Macy.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
23eda14cbcSMatt Macy.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
24eda14cbcSMatt Macy.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
25eda14cbcSMatt Macy.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
26eda14cbcSMatt Macy.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
27eda14cbcSMatt Macy.\" Copyright (c) 2014 Integros [integros.com]
28eda14cbcSMatt Macy.\" Copyright 2019 Richard Laager. All rights reserved.
29eda14cbcSMatt Macy.\" Copyright 2018 Nexenta Systems, Inc.
30eda14cbcSMatt Macy.\" Copyright 2019 Joyent, Inc.
31eda14cbcSMatt Macy.\"
32e2257b31SMartin Matuska.Dd February 8, 2024
33eda14cbcSMatt Macy.Dt ZFS-LIST 8
34eda14cbcSMatt Macy.Os
3516038816SMartin Matuska.
36eda14cbcSMatt Macy.Sh NAME
377877fdebSMatt Macy.Nm zfs-list
3816038816SMartin Matuska.Nd list properties of ZFS datasets
39eda14cbcSMatt Macy.Sh SYNOPSIS
407877fdebSMatt Macy.Nm zfs
41eda14cbcSMatt Macy.Cm list
42eda14cbcSMatt Macy.Op Fl r Ns | Ns Fl d Ar depth
43eda14cbcSMatt Macy.Op Fl Hp
44*ce4dcb97SMartin Matuska.Op Fl j Op Ar --json-int
4516038816SMartin Matuska.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns … Oc
4616038816SMartin Matuska.Oo Fl s Ar property Oc Ns …
4716038816SMartin Matuska.Oo Fl S Ar property Oc Ns …
4816038816SMartin Matuska.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc
4916038816SMartin Matuska.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns …
5016038816SMartin Matuska.
51eda14cbcSMatt Macy.Sh DESCRIPTION
52eda14cbcSMatt MacyIf specified, you can list property information by the absolute pathname or the
53eda14cbcSMatt Macyrelative pathname.
54eda14cbcSMatt MacyBy default, all file systems and volumes are displayed.
55eda14cbcSMatt MacySnapshots are displayed if the
56184c1b94SMartin Matuska.Sy listsnapshots
57184c1b94SMartin Matuskapool property is
58eda14cbcSMatt Macy.Sy on
59eda14cbcSMatt Macy.Po the default is
60eda14cbcSMatt Macy.Sy off
61184c1b94SMartin Matuska.Pc ,
62184c1b94SMartin Matuskaor if the
63184c1b94SMartin Matuska.Fl t Sy snapshot
64184c1b94SMartin Matuskaor
65184c1b94SMartin Matuska.Fl t Sy all
66184c1b94SMartin Matuskaoptions are specified.
67eda14cbcSMatt MacyThe following fields are displayed:
6816038816SMartin Matuska.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint .
69eda14cbcSMatt Macy.Bl -tag -width "-H"
70eda14cbcSMatt Macy.It Fl H
71eda14cbcSMatt MacyUsed for scripting mode.
72eda14cbcSMatt MacyDo not print headers and separate fields by a single tab instead of arbitrary
73eda14cbcSMatt Macywhite space.
74*ce4dcb97SMartin Matuska.It Fl j Op Ar --json-int
75*ce4dcb97SMartin MatuskaPrint the output in JSON format.
76*ce4dcb97SMartin MatuskaSpecify
77*ce4dcb97SMartin Matuska.Sy --json-int
78*ce4dcb97SMartin Matuskato print the numbers in integer format instead of strings in JSON output.
79eda14cbcSMatt Macy.It Fl d Ar depth
80eda14cbcSMatt MacyRecursively display any children of the dataset, limiting the recursion to
81eda14cbcSMatt Macy.Ar depth .
82eda14cbcSMatt MacyA
83eda14cbcSMatt Macy.Ar depth
84eda14cbcSMatt Macyof
85eda14cbcSMatt Macy.Sy 1
86eda14cbcSMatt Macywill display only the dataset and its direct children.
87eda14cbcSMatt Macy.It Fl o Ar property
88eda14cbcSMatt MacyA comma-separated list of properties to display.
89eda14cbcSMatt MacyThe property must be:
9016038816SMartin Matuska.Bl -bullet -compact
91eda14cbcSMatt Macy.It
92eda14cbcSMatt MacyOne of the properties described in the
9316038816SMartin Matuska.Sx Native Properties
94eda14cbcSMatt Macysection of
953ff01b23SMartin Matuska.Xr zfsprops 7
96eda14cbcSMatt Macy.It
97eda14cbcSMatt MacyA user property
98eda14cbcSMatt Macy.It
99eda14cbcSMatt MacyThe value
100eda14cbcSMatt Macy.Sy name
101eda14cbcSMatt Macyto display the dataset name
102eda14cbcSMatt Macy.It
103eda14cbcSMatt MacyThe value
104eda14cbcSMatt Macy.Sy space
105eda14cbcSMatt Macyto display space usage properties on file systems and volumes.
106eda14cbcSMatt MacyThis is a shortcut for specifying
10716038816SMartin Matuska.Fl o Ns \ \& Ns Sy name , Ns Sy avail , Ns Sy used , Ns Sy usedsnap , Ns
10816038816SMartin Matuska.Sy usedds , Ns Sy usedrefreserv , Ns Sy usedchild
10916038816SMartin Matuska.Fl t Sy filesystem , Ns Sy volume .
110eda14cbcSMatt Macy.El
111eda14cbcSMatt Macy.It Fl p
112eda14cbcSMatt MacyDisplay numbers in parsable
113eda14cbcSMatt Macy.Pq exact
114eda14cbcSMatt Macyvalues.
115eda14cbcSMatt Macy.It Fl r
116eda14cbcSMatt MacyRecursively display any children of the dataset on the command line.
117eda14cbcSMatt Macy.It Fl s Ar property
118eda14cbcSMatt MacyA property for sorting the output by column in ascending order based on the
119eda14cbcSMatt Macyvalue of the property.
120eda14cbcSMatt MacyThe property must be one of the properties described in the
12116038816SMartin Matuska.Sx Properties
122eda14cbcSMatt Macysection of
1233ff01b23SMartin Matuska.Xr zfsprops 7
124eda14cbcSMatt Macyor the value
125eda14cbcSMatt Macy.Sy name
126eda14cbcSMatt Macyto sort by the dataset name.
127eda14cbcSMatt MacyMultiple properties can be specified at one time using multiple
128eda14cbcSMatt Macy.Fl s
129eda14cbcSMatt Macyproperty options.
130eda14cbcSMatt MacyMultiple
131eda14cbcSMatt Macy.Fl s
132eda14cbcSMatt Macyoptions are evaluated from left to right in decreasing order of importance.
133eda14cbcSMatt MacyThe following is a list of sorting criteria:
13416038816SMartin Matuska.Bl -bullet -compact
135eda14cbcSMatt Macy.It
136eda14cbcSMatt MacyNumeric types sort in numeric order.
137eda14cbcSMatt Macy.It
138eda14cbcSMatt MacyString types sort in alphabetical order.
139eda14cbcSMatt Macy.It
140eda14cbcSMatt MacyTypes inappropriate for a row sort that row to the literal bottom, regardless of
141eda14cbcSMatt Macythe specified ordering.
142eda14cbcSMatt Macy.El
143eda14cbcSMatt Macy.Pp
144eda14cbcSMatt MacyIf no sorting options are specified the existing behavior of
145eda14cbcSMatt Macy.Nm zfs Cm list
146eda14cbcSMatt Macyis preserved.
147da5137abSMartin Matuska.It Fl S Ar property
148da5137abSMartin MatuskaSame as
149da5137abSMartin Matuska.Fl s ,
150da5137abSMartin Matuskabut sorts by property in descending order.
151eda14cbcSMatt Macy.It Fl t Ar type
152eda14cbcSMatt MacyA comma-separated list of types to display, where
153eda14cbcSMatt Macy.Ar type
154eda14cbcSMatt Macyis one of
155eda14cbcSMatt Macy.Sy filesystem ,
156eda14cbcSMatt Macy.Sy snapshot ,
157eda14cbcSMatt Macy.Sy volume ,
158eda14cbcSMatt Macy.Sy bookmark ,
159eda14cbcSMatt Macyor
160eda14cbcSMatt Macy.Sy all .
161eda14cbcSMatt MacyFor example, specifying
162eda14cbcSMatt Macy.Fl t Sy snapshot
163eda14cbcSMatt Macydisplays only snapshots.
164e2257b31SMartin Matuska.Sy fs ,
165e2257b31SMartin Matuska.Sy snap ,
166e2257b31SMartin Matuskaor
167e2257b31SMartin Matuska.Sy vol
168e2257b31SMartin Matuskacan be used as aliases for
169e2257b31SMartin Matuska.Sy filesystem ,
170e2257b31SMartin Matuska.Sy snapshot ,
171e2257b31SMartin Matuskaor
172e2257b31SMartin Matuska.Sy volume .
173eda14cbcSMatt Macy.El
17416038816SMartin Matuska.
175da5137abSMartin Matuska.Sh EXAMPLES
176da5137abSMartin Matuska.\" These are, respectively, examples 5 from zfs.8
177da5137abSMartin Matuska.\" Make sure to update them bidirectionally
178da5137abSMartin Matuska.Ss Example 1 : No Listing ZFS Datasets
179da5137abSMartin MatuskaThe following command lists all active file systems and volumes in the system.
180da5137abSMartin MatuskaSnapshots are displayed if
181da5137abSMartin Matuska.Sy listsnaps Ns = Ns Sy on .
182da5137abSMartin MatuskaThe default is
183da5137abSMartin Matuska.Sy off .
184da5137abSMartin MatuskaSee
185da5137abSMartin Matuska.Xr zpoolprops 7
186da5137abSMartin Matuskafor more information on pool properties.
187da5137abSMartin Matuska.Bd -literal -compact -offset Ds
188da5137abSMartin Matuska.No # Nm zfs Cm list
189da5137abSMartin MatuskaNAME                      USED  AVAIL  REFER  MOUNTPOINT
190da5137abSMartin Matuskapool                      450K   457G    18K  /pool
191da5137abSMartin Matuskapool/home                 315K   457G    21K  /export/home
192da5137abSMartin Matuskapool/home/anne             18K   457G    18K  /export/home/anne
193da5137abSMartin Matuskapool/home/bob             276K   457G   276K  /export/home/bob
194da5137abSMartin Matuska.Ed
195*ce4dcb97SMartin Matuska.Ss Example 2 : No Listing ZFS filesystems and snapshots in JSON format
196*ce4dcb97SMartin Matuska.Bd -literal -compact -offset Ds
197*ce4dcb97SMartin Matuska.No # Nm zfs Cm list Fl j Fl t Ar filesystem,snapshot | Cm jq
198*ce4dcb97SMartin Matuska{
199*ce4dcb97SMartin Matuska  "output_version": {
200*ce4dcb97SMartin Matuska    "command": "zfs list",
201*ce4dcb97SMartin Matuska    "vers_major": 0,
202*ce4dcb97SMartin Matuska    "vers_minor": 1
203*ce4dcb97SMartin Matuska  },
204*ce4dcb97SMartin Matuska  "datasets": {
205*ce4dcb97SMartin Matuska    "pool": {
206*ce4dcb97SMartin Matuska      "name": "pool",
207*ce4dcb97SMartin Matuska      "type": "FILESYSTEM",
208*ce4dcb97SMartin Matuska      "pool": "pool",
209*ce4dcb97SMartin Matuska      "properties": {
210*ce4dcb97SMartin Matuska        "used": {
211*ce4dcb97SMartin Matuska          "value": "290K",
212*ce4dcb97SMartin Matuska          "source": {
213*ce4dcb97SMartin Matuska            "type": "NONE",
214*ce4dcb97SMartin Matuska            "data": "-"
215*ce4dcb97SMartin Matuska          }
216*ce4dcb97SMartin Matuska        },
217*ce4dcb97SMartin Matuska        "available": {
218*ce4dcb97SMartin Matuska          "value": "30.5G",
219*ce4dcb97SMartin Matuska          "source": {
220*ce4dcb97SMartin Matuska            "type": "NONE",
221*ce4dcb97SMartin Matuska            "data": "-"
222*ce4dcb97SMartin Matuska          }
223*ce4dcb97SMartin Matuska        },
224*ce4dcb97SMartin Matuska        "referenced": {
225*ce4dcb97SMartin Matuska          "value": "24K",
226*ce4dcb97SMartin Matuska          "source": {
227*ce4dcb97SMartin Matuska            "type": "NONE",
228*ce4dcb97SMartin Matuska            "data": "-"
229*ce4dcb97SMartin Matuska          }
230*ce4dcb97SMartin Matuska        },
231*ce4dcb97SMartin Matuska        "mountpoint": {
232*ce4dcb97SMartin Matuska          "value": "/pool",
233*ce4dcb97SMartin Matuska          "source": {
234*ce4dcb97SMartin Matuska            "type": "DEFAULT",
235*ce4dcb97SMartin Matuska            "data": "-"
236*ce4dcb97SMartin Matuska          }
237*ce4dcb97SMartin Matuska        }
238*ce4dcb97SMartin Matuska      }
239*ce4dcb97SMartin Matuska    },
240*ce4dcb97SMartin Matuska    "pool/home": {
241*ce4dcb97SMartin Matuska      "name": "pool/home",
242*ce4dcb97SMartin Matuska      "type": "FILESYSTEM",
243*ce4dcb97SMartin Matuska      "pool": "pool",
244*ce4dcb97SMartin Matuska      "properties": {
245*ce4dcb97SMartin Matuska        "used": {
246*ce4dcb97SMartin Matuska          "value": "48K",
247*ce4dcb97SMartin Matuska          "source": {
248*ce4dcb97SMartin Matuska            "type": "NONE",
249*ce4dcb97SMartin Matuska            "data": "-"
250*ce4dcb97SMartin Matuska          }
251*ce4dcb97SMartin Matuska        },
252*ce4dcb97SMartin Matuska        "available": {
253*ce4dcb97SMartin Matuska          "value": "30.5G",
254*ce4dcb97SMartin Matuska          "source": {
255*ce4dcb97SMartin Matuska            "type": "NONE",
256*ce4dcb97SMartin Matuska            "data": "-"
257*ce4dcb97SMartin Matuska          }
258*ce4dcb97SMartin Matuska        },
259*ce4dcb97SMartin Matuska        "referenced": {
260*ce4dcb97SMartin Matuska          "value": "24K",
261*ce4dcb97SMartin Matuska          "source": {
262*ce4dcb97SMartin Matuska            "type": "NONE",
263*ce4dcb97SMartin Matuska            "data": "-"
264*ce4dcb97SMartin Matuska          }
265*ce4dcb97SMartin Matuska        },
266*ce4dcb97SMartin Matuska        "mountpoint": {
267*ce4dcb97SMartin Matuska          "value": "/mnt/home",
268*ce4dcb97SMartin Matuska          "source": {
269*ce4dcb97SMartin Matuska            "type": "LOCAL",
270*ce4dcb97SMartin Matuska            "data": "-"
271*ce4dcb97SMartin Matuska          }
272*ce4dcb97SMartin Matuska        }
273*ce4dcb97SMartin Matuska      }
274*ce4dcb97SMartin Matuska    },
275*ce4dcb97SMartin Matuska    "pool/home/bob": {
276*ce4dcb97SMartin Matuska      "name": "pool/home/bob",
277*ce4dcb97SMartin Matuska      "type": "FILESYSTEM",
278*ce4dcb97SMartin Matuska      "pool": "pool",
279*ce4dcb97SMartin Matuska      "properties": {
280*ce4dcb97SMartin Matuska        "used": {
281*ce4dcb97SMartin Matuska          "value": "24K",
282*ce4dcb97SMartin Matuska          "source": {
283*ce4dcb97SMartin Matuska            "type": "NONE",
284*ce4dcb97SMartin Matuska            "data": "-"
285*ce4dcb97SMartin Matuska          }
286*ce4dcb97SMartin Matuska        },
287*ce4dcb97SMartin Matuska        "available": {
288*ce4dcb97SMartin Matuska          "value": "30.5G",
289*ce4dcb97SMartin Matuska          "source": {
290*ce4dcb97SMartin Matuska            "type": "NONE",
291*ce4dcb97SMartin Matuska            "data": "-"
292*ce4dcb97SMartin Matuska          }
293*ce4dcb97SMartin Matuska        },
294*ce4dcb97SMartin Matuska        "referenced": {
295*ce4dcb97SMartin Matuska          "value": "24K",
296*ce4dcb97SMartin Matuska          "source": {
297*ce4dcb97SMartin Matuska            "type": "NONE",
298*ce4dcb97SMartin Matuska            "data": "-"
299*ce4dcb97SMartin Matuska          }
300*ce4dcb97SMartin Matuska        },
301*ce4dcb97SMartin Matuska        "mountpoint": {
302*ce4dcb97SMartin Matuska          "value": "/mnt/home/bob",
303*ce4dcb97SMartin Matuska          "source": {
304*ce4dcb97SMartin Matuska            "type": "INHERITED",
305*ce4dcb97SMartin Matuska            "data": "pool/home"
306*ce4dcb97SMartin Matuska          }
307*ce4dcb97SMartin Matuska        }
308*ce4dcb97SMartin Matuska      }
309*ce4dcb97SMartin Matuska    },
310*ce4dcb97SMartin Matuska    "pool/home/bob@v1": {
311*ce4dcb97SMartin Matuska      "name": "pool/home/bob@v1",
312*ce4dcb97SMartin Matuska      "type": "SNAPSHOT",
313*ce4dcb97SMartin Matuska      "pool": "pool",
314*ce4dcb97SMartin Matuska      "dataset": "pool/home/bob",
315*ce4dcb97SMartin Matuska      "snapshot_name": "v1",
316*ce4dcb97SMartin Matuska      "properties": {
317*ce4dcb97SMartin Matuska        "used": {
318*ce4dcb97SMartin Matuska          "value": "0B",
319*ce4dcb97SMartin Matuska          "source": {
320*ce4dcb97SMartin Matuska            "type": "NONE",
321*ce4dcb97SMartin Matuska            "data": "-"
322*ce4dcb97SMartin Matuska          }
323*ce4dcb97SMartin Matuska        },
324*ce4dcb97SMartin Matuska        "available": {
325*ce4dcb97SMartin Matuska          "value": "-",
326*ce4dcb97SMartin Matuska          "source": {
327*ce4dcb97SMartin Matuska            "type": "NONE",
328*ce4dcb97SMartin Matuska            "data": "-"
329*ce4dcb97SMartin Matuska          }
330*ce4dcb97SMartin Matuska        },
331*ce4dcb97SMartin Matuska        "referenced": {
332*ce4dcb97SMartin Matuska          "value": "24K",
333*ce4dcb97SMartin Matuska          "source": {
334*ce4dcb97SMartin Matuska            "type": "NONE",
335*ce4dcb97SMartin Matuska            "data": "-"
336*ce4dcb97SMartin Matuska          }
337*ce4dcb97SMartin Matuska        },
338*ce4dcb97SMartin Matuska        "mountpoint": {
339*ce4dcb97SMartin Matuska          "value": "-",
340*ce4dcb97SMartin Matuska          "source": {
341*ce4dcb97SMartin Matuska            "type": "NONE",
342*ce4dcb97SMartin Matuska            "data": "-"
343*ce4dcb97SMartin Matuska          }
344*ce4dcb97SMartin Matuska        }
345*ce4dcb97SMartin Matuska      }
346*ce4dcb97SMartin Matuska    }
347*ce4dcb97SMartin Matuska  }
348*ce4dcb97SMartin Matuska}
349*ce4dcb97SMartin Matuska.Ed
350da5137abSMartin Matuska.
351eda14cbcSMatt Macy.Sh SEE ALSO
3523ff01b23SMartin Matuska.Xr zfsprops 7 ,
3533ff01b23SMartin Matuska.Xr zfs-get 8
354