1'\" te
2.\" Copyright (c) 2011, Martin Matuska <mm@FreeBSD.org>.
3.\" All Rights Reserved.
4.\"
5.\" The contents of this file are subject to the terms of the
6.\" Common Development and Distribution License (the "License").
7.\" You may not use this file except in compliance with the License.
8.\"
9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10.\" or http://www.opensolaris.org/os/licensing.
11.\" See the License for the specific language governing permissions
12.\" and limitations under the License.
13.\"
14.\" When distributing Covered Code, include this CDDL HEADER in each
15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16.\" If applicable, add the following below this CDDL HEADER, with the
17.\" fields enclosed by brackets "[]" replaced with your own identifying
18.\" information: Portions Copyright [yyyy] [name of copyright owner]
19.\"
20.\" Copyright (c) 2010, Sun Microsystems, Inc. All Rights Reserved.
21.\" Copyright 2011 Nexenta Systems, Inc. All rights reserved.
22.\" Copyright (c) 2011 by Delphix. All rights reserved.
23.\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
24.\"
| 1'\" te
2.\" Copyright (c) 2011, Martin Matuska <mm@FreeBSD.org>.
3.\" All Rights Reserved.
4.\"
5.\" The contents of this file are subject to the terms of the
6.\" Common Development and Distribution License (the "License").
7.\" You may not use this file except in compliance with the License.
8.\"
9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10.\" or http://www.opensolaris.org/os/licensing.
11.\" See the License for the specific language governing permissions
12.\" and limitations under the License.
13.\"
14.\" When distributing Covered Code, include this CDDL HEADER in each
15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16.\" If applicable, add the following below this CDDL HEADER, with the
17.\" fields enclosed by brackets "[]" replaced with your own identifying
18.\" information: Portions Copyright [yyyy] [name of copyright owner]
19.\"
20.\" Copyright (c) 2010, Sun Microsystems, Inc. All Rights Reserved.
21.\" Copyright 2011 Nexenta Systems, Inc. All rights reserved.
22.\" Copyright (c) 2011 by Delphix. All rights reserved.
23.\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
24.\"
|
25.\" $FreeBSD: head/cddl/contrib/opensolaris/cmd/zfs/zfs.8 228055 2011-11-28 09:33:13Z mm $
| 25.\" $FreeBSD: head/cddl/contrib/opensolaris/cmd/zfs/zfs.8 228103 2011-11-28 21:40:00Z mm $
|
26.\"
27.Dd November 26, 2011
28.Dt ZFS 8
29.Os
30.Sh NAME
31.Nm zfs
32.Nd configures ZFS file systems
33.Sh SYNOPSIS
34.Nm
35.Op Fl \&?
36.Nm
37.Cm create
38.Op Fl p
39.Op Fl o Ar property Ns = Ns Ar value
40.Ar ... filesystem
41.Nm
42.Cm create
43.Op Fl ps
44.Op Fl b Ar blocksize
45.Op Fl o Ar property Ns = Ns Ar value
46.Ar ...
47.Fl V
48.Ar size volume
49.Nm
50.Cm destroy
| 26.\"
27.Dd November 26, 2011
28.Dt ZFS 8
29.Os
30.Sh NAME
31.Nm zfs
32.Nd configures ZFS file systems
33.Sh SYNOPSIS
34.Nm
35.Op Fl \&?
36.Nm
37.Cm create
38.Op Fl p
39.Op Fl o Ar property Ns = Ns Ar value
40.Ar ... filesystem
41.Nm
42.Cm create
43.Op Fl ps
44.Op Fl b Ar blocksize
45.Op Fl o Ar property Ns = Ns Ar value
46.Ar ...
47.Fl V
48.Ar size volume
49.Nm
50.Cm destroy
|
51.Op Fl rRf
| 51.Op Fl fnpRrv
|
52.Ar filesystem Ns | Ns Ar volume
53.Nm
54.Cm destroy
| 52.Ar filesystem Ns | Ns Ar volume
53.Nm
54.Cm destroy
|
55.Op Fl rRd
| 55.Op Fl dnpRrv
56.Sm off
|
56.Ar snapshot
| 57.Ar snapshot
|
| 58.Ns Op % Ns Ar snapname
59.Ns Op , Ns Ar ...
60.Sm on
|
57.Nm
58.Cm snapshot
59.Op Fl r
60.Op Fl o Ar property Ns = Ns Ar value
61.Ar ... filesystem@snapname Ns | Ns Ar volume@snapname
62.Nm
63.Cm rollback
64.Op Fl rRf
65.Ar snapshot
66.Nm
67.Cm clone
68.Op Fl p
69.Op Fl o Ar property Ns = Ns Ar value
70.Ar ... snapshot filesystem Ns | Ns Ar volume
71.Nm
72.Cm promote
73.Ar clone-filesystem
74.Nm
75.Cm rename
76.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
77.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
78.Nm
79.Cm rename
80.Fl p
81.Ar filesystem Ns | Ns Ar volume
82.Ar filesystem Ns | Ns Ar volume
83.Nm
84.Cm rename
85.Fl r
86.Ar snapshot snapshot
87.Nm
88.Cm rename
89.Fl u
90.Op Fl p
91.Ar filesystem filesystem
92.Nm
93.Cm list
94.Op Fl r Ns | Ns Fl d Ar depth
95.Op Fl H
96.Op Fl o Ar property Ns Op , Ns Ar ...
97.Op Fl t Ar type Ns Op , Ns Ar ...
98.Op Fl s Ar property
99.Ar ...
100.Op Fl S Ar property
101.Ar ...
102.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
103.Nm
104.Cm set
105.Ar property Ns = Ns Ar value
106.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
107.Nm
108.Cm get
109.Op Fl r Ns | Ns Fl d Ar depth
110.Op Fl Hp
111.Op Fl o Ar all | field Ns Op , Ns Ar ...
112.Op Fl s Ar source Ns Op , Ns Ar ...
113.Ar all | property Ns Op , Ns Ar ...
114.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
115.Nm
116.Cm inherit
117.Op Fl rS
118.Ar property
119.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
120.Nm
121.Cm upgrade
122.Op Fl v
123.Nm
124.Cm upgrade
125.Op Fl r
126.Op Fl V Ar version
127.Fl a | Ar filesystem
128.Nm
129.Cm userspace
130.Op Fl niHp
131.Op Fl o Ar field Ns Op , Ns Ar ...
132.Op Fl sS Ar field
133.Ar ...
134.Op Fl t Ar type Ns Op , Ns Ar ...
135.Ar filesystem Ns | Ns Ar snapshot
136.Nm
137.Cm groupspace
138.Op Fl niHp
139.Op Fl o Ar field Ns Op , Ns Ar ...
140.Op Fl sS Ar field
141.Ar ...
142.Op Fl t Ar type Ns Op , Ns Ar ...
143.Ar filesystem Ns | Ns Ar snapshot
144.Nm
145.Cm mount
146.Nm
147.Cm mount
148.Op Fl vO
149.Op Fl o Ar property Ns Op , Ns Ar ...
150.Fl a | Ar filesystem
151.Nm
152.Cm unmount
153.Op Fl f
154.Fl a | Ar filesystem Ns | Ns Ar mountpoint
155.Nm
156.Cm share
157.Fl a | Ar filesystem
158.Nm
159.Cm unshare
160.Fl a | Ar filesystem Ns | Ns Ar mountpoint
161.Nm
162.Cm send
| 61.Nm
62.Cm snapshot
63.Op Fl r
64.Op Fl o Ar property Ns = Ns Ar value
65.Ar ... filesystem@snapname Ns | Ns Ar volume@snapname
66.Nm
67.Cm rollback
68.Op Fl rRf
69.Ar snapshot
70.Nm
71.Cm clone
72.Op Fl p
73.Op Fl o Ar property Ns = Ns Ar value
74.Ar ... snapshot filesystem Ns | Ns Ar volume
75.Nm
76.Cm promote
77.Ar clone-filesystem
78.Nm
79.Cm rename
80.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
81.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
82.Nm
83.Cm rename
84.Fl p
85.Ar filesystem Ns | Ns Ar volume
86.Ar filesystem Ns | Ns Ar volume
87.Nm
88.Cm rename
89.Fl r
90.Ar snapshot snapshot
91.Nm
92.Cm rename
93.Fl u
94.Op Fl p
95.Ar filesystem filesystem
96.Nm
97.Cm list
98.Op Fl r Ns | Ns Fl d Ar depth
99.Op Fl H
100.Op Fl o Ar property Ns Op , Ns Ar ...
101.Op Fl t Ar type Ns Op , Ns Ar ...
102.Op Fl s Ar property
103.Ar ...
104.Op Fl S Ar property
105.Ar ...
106.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
107.Nm
108.Cm set
109.Ar property Ns = Ns Ar value
110.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
111.Nm
112.Cm get
113.Op Fl r Ns | Ns Fl d Ar depth
114.Op Fl Hp
115.Op Fl o Ar all | field Ns Op , Ns Ar ...
116.Op Fl s Ar source Ns Op , Ns Ar ...
117.Ar all | property Ns Op , Ns Ar ...
118.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
119.Nm
120.Cm inherit
121.Op Fl rS
122.Ar property
123.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
124.Nm
125.Cm upgrade
126.Op Fl v
127.Nm
128.Cm upgrade
129.Op Fl r
130.Op Fl V Ar version
131.Fl a | Ar filesystem
132.Nm
133.Cm userspace
134.Op Fl niHp
135.Op Fl o Ar field Ns Op , Ns Ar ...
136.Op Fl sS Ar field
137.Ar ...
138.Op Fl t Ar type Ns Op , Ns Ar ...
139.Ar filesystem Ns | Ns Ar snapshot
140.Nm
141.Cm groupspace
142.Op Fl niHp
143.Op Fl o Ar field Ns Op , Ns Ar ...
144.Op Fl sS Ar field
145.Ar ...
146.Op Fl t Ar type Ns Op , Ns Ar ...
147.Ar filesystem Ns | Ns Ar snapshot
148.Nm
149.Cm mount
150.Nm
151.Cm mount
152.Op Fl vO
153.Op Fl o Ar property Ns Op , Ns Ar ...
154.Fl a | Ar filesystem
155.Nm
156.Cm unmount
157.Op Fl f
158.Fl a | Ar filesystem Ns | Ns Ar mountpoint
159.Nm
160.Cm share
161.Fl a | Ar filesystem
162.Nm
163.Cm unshare
164.Fl a | Ar filesystem Ns | Ns Ar mountpoint
165.Nm
166.Cm send
|
163.Op Fl DvRp
| 167.Op Fl DnPpRrv
|
164.Op Fl i Ar snapshot | Fl I Ar snapshot
165.Ar snapshot
166.Nm
167.Cm receive
168.Op Fl vnFu
169.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
170.Nm
171.Cm receive
172.Op Fl vnFu
173.Op Fl d | e
174.Ar filesystem
175.Nm
176.Cm allow
177.Ar filesystem Ns | Ns Ar volume
178.Nm
179.Cm allow
180.Op Fl ldug
181.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
182.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
183.Ar filesystem Ns | Ns Ar volume
184.Nm
185.Cm allow
186.Op Fl ld
187.Fl e
188.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
189.Ar filesystem Ns | Ns Ar volume
190.Nm
191.Cm allow
192.Fl c
193.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
194.Ar filesystem Ns | Ns Ar volume
195.Nm
196.Cm allow
197.Fl s
198.Ar @setname
199.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
200.Ar filesystem Ns | Ns Ar volume
201.Nm
202.Cm unallow
203.Op Fl rldug
204.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
205.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
206.Ar filesystem Ns | Ns Ar volume
207.Nm
208.Cm unallow
209.Op Fl rld
210.Fl e
211.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
212.Ar filesystem Ns | Ns Ar volume
213.Nm
214.Cm unallow
215.Op Fl r
216.Fl c
217.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
218.Ar filesystem Ns | Ns Ar volume
219.Nm
220.Cm unallow
221.Op Fl r
222.Fl s
223.Ar @setname
224.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
225.Ar filesystem Ns | Ns Ar volume
226.Nm
227.Cm hold
228.Op Fl r
229.Ar tag snapshot ...
230.Nm
231.Cm holds
232.Op Fl r
233.Ar snapshot ...
234.Nm
235.Cm release
236.Op Fl r
237.Ar tag snapshot ...
238.Nm
239.Cm diff
240.Op Fl FHt
241.Ar snapshot
242.Op Ar snapshot Ns | Ns Ar filesystem
243.Nm
244.Cm jail
245.Ar jailid filesystem
246.Nm
247.Cm unjail
248.Ar jailid filesystem
249.Sh DESCRIPTION
250The
251.Nm
252command configures
253.Tn ZFS
254datasets within a
255.Tn ZFS
256storage pool, as described in
257.Xr zpool 8 .
258A dataset is identified by a unique path within the
259.Tn ZFS
260namespace. For example:
261.Bd -ragged -offset 4n
262.No pool/ Ns Brq filesystem,volume,snapshot
263.Ed
264.Pp
265where the maximum length of a dataset name is
266.Dv MAXNAMELEN
267(256 bytes).
268.Pp
269A dataset can be one of the following:
270.Bl -hang -width 12n
271.It Sy file system
272A
273.Tn ZFS
274dataset of type
275.Em filesystem
276can be mounted within the standard system namespace and behaves like other file
277systems. While
278.Tn ZFS
279file systems are designed to be
280.Tn POSIX
281compliant, known issues exist that prevent compliance in some cases.
282Applications that depend on standards conformance might fail due to nonstandard
283behavior when checking file system free space.
284.It Sy volume
285A logical volume exported as a raw or block device. This type of dataset should
286only be used under special circumstances. File systems are typically used in
287most environments.
288.It Sy snapshot
289A read-only version of a file system or volume at a given point in time. It is
290specified as
291.Em filesystem@name
292or
293.Em volume@name .
294.El
295.Ss ZFS File System Hierarchy
296A
297.Tn ZFS
298storage pool is a logical collection of devices that provide space for
299datasets. A storage pool is also the root of the
300.Tn ZFS
301file system hierarchy.
302.Pp
303The root of the pool can be accessed as a file system, such as mounting and
304unmounting, taking snapshots, and setting properties. The physical storage
305characteristics, however, are managed by the
306.Xr zpool 8
307command.
308.Pp
309See
310.Xr zpool 8
311for more information on creating and administering pools.
312.Ss Snapshots
313A snapshot is a read-only copy of a file system or volume. Snapshots can be
314created extremely quickly, and initially consume no additional space within the
315pool. As data within the active dataset changes, the snapshot consumes more
316data than would otherwise be shared with the active dataset.
317.Pp
318Snapshots can have arbitrary names. Snapshots of volumes can be cloned or
319rolled back, but cannot be accessed independently.
320.Pp
321File system snapshots can be accessed under the
322.Pa \&.zfs/snapshot
323directory in the root of the file system. Snapshots are automatically mounted
324on demand and may be unmounted at regular intervals. The visibility of the
325.Pa \&.zfs
326directory can be controlled by the
327.Sy snapdir
328property.
329.Ss Clones
330A clone is a writable volume or file system whose initial contents are the same
331as another dataset. As with snapshots, creating a clone is nearly
332instantaneous, and initially consumes no additional space.
333.Pp
334Clones can only be created from a snapshot. When a snapshot is cloned, it
335creates an implicit dependency between the parent and child. Even though the
336clone is created somewhere else in the dataset hierarchy, the original snapshot
337cannot be destroyed as long as a clone exists. The
338.Sy origin
339property exposes this dependency, and the
340.Cm destroy
341command lists any such dependencies, if they exist.
342.Pp
343The clone parent-child dependency relationship can be reversed by using the
344.Cm promote
345subcommand. This causes the "origin" file system to become a clone of the
346specified file system, which makes it possible to destroy the file system that
347the clone was created from.
348.Ss Mount Points
349Creating a
350.Tn ZFS
351file system is a simple operation, so the number of file systems per system is
352likely to be numerous. To cope with this,
353.Tn ZFS
354automatically manages mounting and unmounting file systems without the need to
355edit the
356.Pa /etc/fstab
357file. All automatically managed file systems are mounted by
358.Tn ZFS
359at boot time.
360.Pp
361By default, file systems are mounted under
362.Pa /path ,
363where
364.Ar path
365is the name of the file system in the
366.Tn ZFS
367namespace. Directories are created and destroyed as needed.
368.Pp
369A file system can also have a mount point set in the
370.Sy mountpoint
371property. This directory is created as needed, and
372.Tn ZFS
373automatically mounts the file system when the
374.Qq Nm Cm mount Fl a
375command is invoked (without editing
376.Pa /etc/fstab Ns ).
377The
378.Sy mountpoint
379property can be inherited, so if
380.Em pool/home
381has a mount point of
382.Pa /home ,
383then
384.Em pool/home/user
385automatically inherits a mount point of
386.Pa /home/user .
387.Pp
388A file system
389.Sy mountpoint
390property of
391.Cm none
392prevents the file system from being mounted.
393.Pp
394If needed,
395.Tn ZFS
396file systems can also be managed with traditional tools
397.Pq Xr mount 8 , Xr umount 8 , Xr fstab 5 .
398If a file system's mount point is set to
399.Cm legacy ,
400.Tn ZFS
401makes no attempt to manage the file system, and the administrator is
402responsible for mounting and unmounting the file system.
403.Ss Jails
404.No A Tn ZFS
405dataset can be attached to a jail by using the
406.Qq Nm Cm jail
407subcommand. You cannot attach a dataset to one jail and the children of the
408same dataset to another jails. To allow managment of the dataset from within
409a jail, the
410.Sy jailed
411property has to be set. The
412.Sy quota
413property cannot be changed from within a jail.
414.Pp
415.No A Tn ZFS
416dataset can be detached from a jail using the
417.Qq Nm Cm unjail
418subcommand.
419.Pp
420After a dataset is attached to a jail and the jailed property is set, a jailed
421file system cannot be mounted outside the jail, since the jail administrator
422might have set the mount point to an unacceptable value.
423.Ss Deduplication
424Deduplication is the process for removing redundant data at the block-level,
425reducing the total amount of data stored. If a file system has the
426.Cm dedup
427property enabled, duplicate data blocks are removed synchronously. The result
428is that only unique data is stored and common components are shared among
429files.
430.Ss Native Properties
431Properties are divided into two types, native properties and user-defined (or
432"user") properties. Native properties either export internal statistics or
433control
434.Tn ZFS
435behavior. In addition, native properties are either editable or read-only. User
436properties have no effect on
437.Tn ZFS
438behavior, but you can use them to annotate datasets in a way that is meaningful
439in your environment. For more information about user properties, see the
440.Qq Sx User Properties
441section, below.
442.Pp
443Every dataset has a set of properties that export statistics about the dataset
444as well as control various behaviors. Properties are inherited from the parent
445unless overridden by the child. Some properties apply only to certain types of
446datasets (file systems, volumes, or snapshots).
447.Pp
448The values of numeric properties can be specified using human-readable suffixes
449(for example,
450.Sy k , KB , M , Gb ,
451and so forth, up to
452.Sy Z
453for zettabyte). The following are all valid (and equal) specifications:
454.Bd -ragged -offset 4n
4551536M, 1.5g, 1.50GB
456.Ed
457.Pp
458The values of non-numeric properties are case sensitive and must be lowercase,
459except for
460.Sy mountpoint , sharenfs , No and Sy sharesmb .
461.Pp
462The following native properties consist of read-only statistics about the
463dataset. These properties can be neither set, nor inherited. Native properties
464apply to all dataset types unless otherwise noted.
465.Bl -tag -width 2n
466.It Sy available
467The amount of space available to the dataset and all its children, assuming
468that there is no other activity in the pool. Because space is shared within a
469pool, availability can be limited by any number of factors, including physical
470pool size, quotas, reservations, or other datasets within the pool.
471.Pp
472This property can also be referred to by its shortened column name,
473.Sy avail .
474.It Sy compressratio
475For non-snapshots, the compression ratio achieved for the
476.Sy used
477space of this dataset, expressed as a multiplier. The
478.Sy used
479property includes descendant datasets, and, for clones, does not include
480the space shared with the origin snapshot. For snapshots, the
481.Sy compressratio
482is the same as the
483.Sy refcompressratio
484property. Compression can be turned on by running:
485.Qq Nm Cm set compression=on Ar dataset
486The default value is
487.Cm off .
488.It Sy creation
489The time this dataset was created.
| 168.Op Fl i Ar snapshot | Fl I Ar snapshot
169.Ar snapshot
170.Nm
171.Cm receive
172.Op Fl vnFu
173.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
174.Nm
175.Cm receive
176.Op Fl vnFu
177.Op Fl d | e
178.Ar filesystem
179.Nm
180.Cm allow
181.Ar filesystem Ns | Ns Ar volume
182.Nm
183.Cm allow
184.Op Fl ldug
185.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
186.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
187.Ar filesystem Ns | Ns Ar volume
188.Nm
189.Cm allow
190.Op Fl ld
191.Fl e
192.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
193.Ar filesystem Ns | Ns Ar volume
194.Nm
195.Cm allow
196.Fl c
197.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
198.Ar filesystem Ns | Ns Ar volume
199.Nm
200.Cm allow
201.Fl s
202.Ar @setname
203.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
204.Ar filesystem Ns | Ns Ar volume
205.Nm
206.Cm unallow
207.Op Fl rldug
208.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
209.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
210.Ar filesystem Ns | Ns Ar volume
211.Nm
212.Cm unallow
213.Op Fl rld
214.Fl e
215.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
216.Ar filesystem Ns | Ns Ar volume
217.Nm
218.Cm unallow
219.Op Fl r
220.Fl c
221.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
222.Ar filesystem Ns | Ns Ar volume
223.Nm
224.Cm unallow
225.Op Fl r
226.Fl s
227.Ar @setname
228.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
229.Ar filesystem Ns | Ns Ar volume
230.Nm
231.Cm hold
232.Op Fl r
233.Ar tag snapshot ...
234.Nm
235.Cm holds
236.Op Fl r
237.Ar snapshot ...
238.Nm
239.Cm release
240.Op Fl r
241.Ar tag snapshot ...
242.Nm
243.Cm diff
244.Op Fl FHt
245.Ar snapshot
246.Op Ar snapshot Ns | Ns Ar filesystem
247.Nm
248.Cm jail
249.Ar jailid filesystem
250.Nm
251.Cm unjail
252.Ar jailid filesystem
253.Sh DESCRIPTION
254The
255.Nm
256command configures
257.Tn ZFS
258datasets within a
259.Tn ZFS
260storage pool, as described in
261.Xr zpool 8 .
262A dataset is identified by a unique path within the
263.Tn ZFS
264namespace. For example:
265.Bd -ragged -offset 4n
266.No pool/ Ns Brq filesystem,volume,snapshot
267.Ed
268.Pp
269where the maximum length of a dataset name is
270.Dv MAXNAMELEN
271(256 bytes).
272.Pp
273A dataset can be one of the following:
274.Bl -hang -width 12n
275.It Sy file system
276A
277.Tn ZFS
278dataset of type
279.Em filesystem
280can be mounted within the standard system namespace and behaves like other file
281systems. While
282.Tn ZFS
283file systems are designed to be
284.Tn POSIX
285compliant, known issues exist that prevent compliance in some cases.
286Applications that depend on standards conformance might fail due to nonstandard
287behavior when checking file system free space.
288.It Sy volume
289A logical volume exported as a raw or block device. This type of dataset should
290only be used under special circumstances. File systems are typically used in
291most environments.
292.It Sy snapshot
293A read-only version of a file system or volume at a given point in time. It is
294specified as
295.Em filesystem@name
296or
297.Em volume@name .
298.El
299.Ss ZFS File System Hierarchy
300A
301.Tn ZFS
302storage pool is a logical collection of devices that provide space for
303datasets. A storage pool is also the root of the
304.Tn ZFS
305file system hierarchy.
306.Pp
307The root of the pool can be accessed as a file system, such as mounting and
308unmounting, taking snapshots, and setting properties. The physical storage
309characteristics, however, are managed by the
310.Xr zpool 8
311command.
312.Pp
313See
314.Xr zpool 8
315for more information on creating and administering pools.
316.Ss Snapshots
317A snapshot is a read-only copy of a file system or volume. Snapshots can be
318created extremely quickly, and initially consume no additional space within the
319pool. As data within the active dataset changes, the snapshot consumes more
320data than would otherwise be shared with the active dataset.
321.Pp
322Snapshots can have arbitrary names. Snapshots of volumes can be cloned or
323rolled back, but cannot be accessed independently.
324.Pp
325File system snapshots can be accessed under the
326.Pa \&.zfs/snapshot
327directory in the root of the file system. Snapshots are automatically mounted
328on demand and may be unmounted at regular intervals. The visibility of the
329.Pa \&.zfs
330directory can be controlled by the
331.Sy snapdir
332property.
333.Ss Clones
334A clone is a writable volume or file system whose initial contents are the same
335as another dataset. As with snapshots, creating a clone is nearly
336instantaneous, and initially consumes no additional space.
337.Pp
338Clones can only be created from a snapshot. When a snapshot is cloned, it
339creates an implicit dependency between the parent and child. Even though the
340clone is created somewhere else in the dataset hierarchy, the original snapshot
341cannot be destroyed as long as a clone exists. The
342.Sy origin
343property exposes this dependency, and the
344.Cm destroy
345command lists any such dependencies, if they exist.
346.Pp
347The clone parent-child dependency relationship can be reversed by using the
348.Cm promote
349subcommand. This causes the "origin" file system to become a clone of the
350specified file system, which makes it possible to destroy the file system that
351the clone was created from.
352.Ss Mount Points
353Creating a
354.Tn ZFS
355file system is a simple operation, so the number of file systems per system is
356likely to be numerous. To cope with this,
357.Tn ZFS
358automatically manages mounting and unmounting file systems without the need to
359edit the
360.Pa /etc/fstab
361file. All automatically managed file systems are mounted by
362.Tn ZFS
363at boot time.
364.Pp
365By default, file systems are mounted under
366.Pa /path ,
367where
368.Ar path
369is the name of the file system in the
370.Tn ZFS
371namespace. Directories are created and destroyed as needed.
372.Pp
373A file system can also have a mount point set in the
374.Sy mountpoint
375property. This directory is created as needed, and
376.Tn ZFS
377automatically mounts the file system when the
378.Qq Nm Cm mount Fl a
379command is invoked (without editing
380.Pa /etc/fstab Ns ).
381The
382.Sy mountpoint
383property can be inherited, so if
384.Em pool/home
385has a mount point of
386.Pa /home ,
387then
388.Em pool/home/user
389automatically inherits a mount point of
390.Pa /home/user .
391.Pp
392A file system
393.Sy mountpoint
394property of
395.Cm none
396prevents the file system from being mounted.
397.Pp
398If needed,
399.Tn ZFS
400file systems can also be managed with traditional tools
401.Pq Xr mount 8 , Xr umount 8 , Xr fstab 5 .
402If a file system's mount point is set to
403.Cm legacy ,
404.Tn ZFS
405makes no attempt to manage the file system, and the administrator is
406responsible for mounting and unmounting the file system.
407.Ss Jails
408.No A Tn ZFS
409dataset can be attached to a jail by using the
410.Qq Nm Cm jail
411subcommand. You cannot attach a dataset to one jail and the children of the
412same dataset to another jails. To allow managment of the dataset from within
413a jail, the
414.Sy jailed
415property has to be set. The
416.Sy quota
417property cannot be changed from within a jail.
418.Pp
419.No A Tn ZFS
420dataset can be detached from a jail using the
421.Qq Nm Cm unjail
422subcommand.
423.Pp
424After a dataset is attached to a jail and the jailed property is set, a jailed
425file system cannot be mounted outside the jail, since the jail administrator
426might have set the mount point to an unacceptable value.
427.Ss Deduplication
428Deduplication is the process for removing redundant data at the block-level,
429reducing the total amount of data stored. If a file system has the
430.Cm dedup
431property enabled, duplicate data blocks are removed synchronously. The result
432is that only unique data is stored and common components are shared among
433files.
434.Ss Native Properties
435Properties are divided into two types, native properties and user-defined (or
436"user") properties. Native properties either export internal statistics or
437control
438.Tn ZFS
439behavior. In addition, native properties are either editable or read-only. User
440properties have no effect on
441.Tn ZFS
442behavior, but you can use them to annotate datasets in a way that is meaningful
443in your environment. For more information about user properties, see the
444.Qq Sx User Properties
445section, below.
446.Pp
447Every dataset has a set of properties that export statistics about the dataset
448as well as control various behaviors. Properties are inherited from the parent
449unless overridden by the child. Some properties apply only to certain types of
450datasets (file systems, volumes, or snapshots).
451.Pp
452The values of numeric properties can be specified using human-readable suffixes
453(for example,
454.Sy k , KB , M , Gb ,
455and so forth, up to
456.Sy Z
457for zettabyte). The following are all valid (and equal) specifications:
458.Bd -ragged -offset 4n
4591536M, 1.5g, 1.50GB
460.Ed
461.Pp
462The values of non-numeric properties are case sensitive and must be lowercase,
463except for
464.Sy mountpoint , sharenfs , No and Sy sharesmb .
465.Pp
466The following native properties consist of read-only statistics about the
467dataset. These properties can be neither set, nor inherited. Native properties
468apply to all dataset types unless otherwise noted.
469.Bl -tag -width 2n
470.It Sy available
471The amount of space available to the dataset and all its children, assuming
472that there is no other activity in the pool. Because space is shared within a
473pool, availability can be limited by any number of factors, including physical
474pool size, quotas, reservations, or other datasets within the pool.
475.Pp
476This property can also be referred to by its shortened column name,
477.Sy avail .
478.It Sy compressratio
479For non-snapshots, the compression ratio achieved for the
480.Sy used
481space of this dataset, expressed as a multiplier. The
482.Sy used
483property includes descendant datasets, and, for clones, does not include
484the space shared with the origin snapshot. For snapshots, the
485.Sy compressratio
486is the same as the
487.Sy refcompressratio
488property. Compression can be turned on by running:
489.Qq Nm Cm set compression=on Ar dataset
490The default value is
491.Cm off .
492.It Sy creation
493The time this dataset was created.
|
| 494.It Sy clones
495For snapshots, this property is a comma-separated list of filesystems or
496volumes which are clones of this snapshot. The clones'
497.Sy origin
498property is this snapshot. If the
499.Sy clones
500property is not empty, then this snapshot can not be destroyed (even with the
501.Fl r
502or
503.Fl f
504options).
|
490.It Sy defer_destroy
491This property is
492.Cm on
493if the snapshot has been marked for deferred destroy by using the
494.Qq Nm Cm destroy -d
495command. Otherwise, the property is
496.Cm off .
497.It Sy mounted
498For file systems, indicates whether the file system is currently mounted. This
499property can be either
500.Cm yes
501or
502.Cm no .
503.It Sy origin
504For cloned file systems or volumes, the snapshot from which the clone was
505created. See also the
506.Sy clones
507property.
508.It Sy referenced
509The amount of data that is accessible by this dataset, which may or may not be
510shared with other datasets in the pool. When a snapshot or clone is created, it
511initially references the same amount of space as the file system or snapshot it
512was created from, since its contents are identical.
513.Pp
514This property can also be referred to by its shortened column name,
515.Sy refer .
516.It Sy refcompressratio
517The compression ratio achieved for the
518.Sy referenced
519space of this dataset, expressed as a multiplier. See also the
520.Sy compressratio
521property.
522.It Sy type
523The type of dataset:
524.Sy filesystem , volume , No or Sy snapshot .
525.It Sy used
526The amount of space consumed by this dataset and all its descendents. This is
527the value that is checked against this dataset's quota and reservation. The
528space used does not include this dataset's reservation, but does take into
529account the reservations of any descendent datasets. The amount of space that a
530dataset consumes from its parent, as well as the amount of space that are freed
531if this dataset is recursively destroyed, is the greater of its space used and
532its reservation.
533.Pp
534When snapshots (see the
535.Qq Sx Snapshots
536section) are created, their space is
537initially shared between the snapshot and the file system, and possibly with
538previous snapshots. As the file system changes, space that was previously
539shared becomes unique to the snapshot, and counted in the snapshot's space
540used. Additionally, deleting snapshots can increase the amount of space unique
541to (and used by) other snapshots.
542.Pp
543The amount of space used, available, or referenced does not take into account
544pending changes. Pending changes are generally accounted for within a few
545seconds. Committing a change to a disk using
546.Xr fsync 2
547or
548.Sy O_SYNC
549does not necessarily guarantee that the space usage information is updated
550immediately.
551.It Sy usedby*
552The
553.Sy usedby*
554properties decompose the
555.Sy used
556properties into the various reasons that space is used. Specifically,
557.Sy used No =
558.Sy usedbysnapshots + usedbydataset + usedbychildren + usedbyrefreservation .
559These properties are only available for datasets created
560with
561.Tn ZFS
562pool version 13 pools and higher.
563.It Sy usedbysnapshots
564The amount of space consumed by snapshots of this dataset. In particular, it is
565the amount of space that would be freed if all of this dataset's snapshots were
566destroyed. Note that this is not simply the sum of the snapshots'
567.Sy used
568properties because space can be shared by multiple snapshots.
569.It Sy usedbydataset
570The amount of space used by this dataset itself, which would be freed if the
571dataset were destroyed (after first removing any
572.Sy refreservation
573and destroying any necessary snapshots or descendents).
574.It Sy usedbychildren
575The amount of space used by children of this dataset, which would be freed if
576all the dataset's children were destroyed.
577.It Sy usedbyrefreservation
578The amount of space used by a
579.Sy refreservation
580set on this dataset, which would be freed if the
581.Sy refreservation
582was removed.
583.It Sy userused@ Ns Ar user
584The amount of space consumed by the specified user in this dataset. Space is
585charged to the owner of each file, as displayed by
586.Qq Nm ls Fl l .
587The amount of space charged is displayed by
588.Qq Nm du
589and
590.Qq Nm ls Fl s .
591See the
592.Qq Nm Cm userspace
593subcommand for more information.
594.Pp
595Unprivileged users can access only their own space usage. The root user, or a
596user who has been granted the
597.Sy userused
598privilege with
599.Qq Nm Cm allow ,
600can access everyone's usage.
601.Pp
602The
603.Sy userused@ Ns ...
604properties are not displayed by
605.Qq Nm Cm get all .
606The user's name must be appended after the
607.Sy @
608symbol, using one of the following forms:
609.Bl -bullet -offset 2n
610.It
611POSIX name (for example,
612.Em joe Ns )
613.It
614POSIX numeric ID (for example,
615.Em 1001 Ns )
616.El
617.It Sy userrefs
618This property is set to the number of user holds on this snapshot. User holds
619are set by using the
620.Qq Nm Cm hold
621command.
622.It Sy groupused@ Ns Ar group
623The amount of space consumed by the specified group in this dataset. Space is
624charged to the group of each file, as displayed by
625.Nm ls Fl l .
626See the
627.Sy userused@ Ns Ar user
628property for more information.
629.Pp
630Unprivileged users can only access their own groups' space usage. The root
631user, or a user who has been granted the
632.Sy groupused
633privilege with
634.Qq Nm Cm allow ,
635can access all groups' usage.
636.It Sy volblocksize Ns = Ns Ar blocksize
637For volumes, specifies the block size of the volume. The
638.Ar blocksize
639cannot be changed once the volume has been written, so it should be set at
640volume creation time. The default
641.Ar blocksize
642for volumes is 8 Kbytes. Any
643power of 2 from 512 bytes to 128 Kbytes is valid.
644.Pp
645This property can also be referred to by its shortened column name,
646.Sy volblock .
| 505.It Sy defer_destroy
506This property is
507.Cm on
508if the snapshot has been marked for deferred destroy by using the
509.Qq Nm Cm destroy -d
510command. Otherwise, the property is
511.Cm off .
512.It Sy mounted
513For file systems, indicates whether the file system is currently mounted. This
514property can be either
515.Cm yes
516or
517.Cm no .
518.It Sy origin
519For cloned file systems or volumes, the snapshot from which the clone was
520created. See also the
521.Sy clones
522property.
523.It Sy referenced
524The amount of data that is accessible by this dataset, which may or may not be
525shared with other datasets in the pool. When a snapshot or clone is created, it
526initially references the same amount of space as the file system or snapshot it
527was created from, since its contents are identical.
528.Pp
529This property can also be referred to by its shortened column name,
530.Sy refer .
531.It Sy refcompressratio
532The compression ratio achieved for the
533.Sy referenced
534space of this dataset, expressed as a multiplier. See also the
535.Sy compressratio
536property.
537.It Sy type
538The type of dataset:
539.Sy filesystem , volume , No or Sy snapshot .
540.It Sy used
541The amount of space consumed by this dataset and all its descendents. This is
542the value that is checked against this dataset's quota and reservation. The
543space used does not include this dataset's reservation, but does take into
544account the reservations of any descendent datasets. The amount of space that a
545dataset consumes from its parent, as well as the amount of space that are freed
546if this dataset is recursively destroyed, is the greater of its space used and
547its reservation.
548.Pp
549When snapshots (see the
550.Qq Sx Snapshots
551section) are created, their space is
552initially shared between the snapshot and the file system, and possibly with
553previous snapshots. As the file system changes, space that was previously
554shared becomes unique to the snapshot, and counted in the snapshot's space
555used. Additionally, deleting snapshots can increase the amount of space unique
556to (and used by) other snapshots.
557.Pp
558The amount of space used, available, or referenced does not take into account
559pending changes. Pending changes are generally accounted for within a few
560seconds. Committing a change to a disk using
561.Xr fsync 2
562or
563.Sy O_SYNC
564does not necessarily guarantee that the space usage information is updated
565immediately.
566.It Sy usedby*
567The
568.Sy usedby*
569properties decompose the
570.Sy used
571properties into the various reasons that space is used. Specifically,
572.Sy used No =
573.Sy usedbysnapshots + usedbydataset + usedbychildren + usedbyrefreservation .
574These properties are only available for datasets created
575with
576.Tn ZFS
577pool version 13 pools and higher.
578.It Sy usedbysnapshots
579The amount of space consumed by snapshots of this dataset. In particular, it is
580the amount of space that would be freed if all of this dataset's snapshots were
581destroyed. Note that this is not simply the sum of the snapshots'
582.Sy used
583properties because space can be shared by multiple snapshots.
584.It Sy usedbydataset
585The amount of space used by this dataset itself, which would be freed if the
586dataset were destroyed (after first removing any
587.Sy refreservation
588and destroying any necessary snapshots or descendents).
589.It Sy usedbychildren
590The amount of space used by children of this dataset, which would be freed if
591all the dataset's children were destroyed.
592.It Sy usedbyrefreservation
593The amount of space used by a
594.Sy refreservation
595set on this dataset, which would be freed if the
596.Sy refreservation
597was removed.
598.It Sy userused@ Ns Ar user
599The amount of space consumed by the specified user in this dataset. Space is
600charged to the owner of each file, as displayed by
601.Qq Nm ls Fl l .
602The amount of space charged is displayed by
603.Qq Nm du
604and
605.Qq Nm ls Fl s .
606See the
607.Qq Nm Cm userspace
608subcommand for more information.
609.Pp
610Unprivileged users can access only their own space usage. The root user, or a
611user who has been granted the
612.Sy userused
613privilege with
614.Qq Nm Cm allow ,
615can access everyone's usage.
616.Pp
617The
618.Sy userused@ Ns ...
619properties are not displayed by
620.Qq Nm Cm get all .
621The user's name must be appended after the
622.Sy @
623symbol, using one of the following forms:
624.Bl -bullet -offset 2n
625.It
626POSIX name (for example,
627.Em joe Ns )
628.It
629POSIX numeric ID (for example,
630.Em 1001 Ns )
631.El
632.It Sy userrefs
633This property is set to the number of user holds on this snapshot. User holds
634are set by using the
635.Qq Nm Cm hold
636command.
637.It Sy groupused@ Ns Ar group
638The amount of space consumed by the specified group in this dataset. Space is
639charged to the group of each file, as displayed by
640.Nm ls Fl l .
641See the
642.Sy userused@ Ns Ar user
643property for more information.
644.Pp
645Unprivileged users can only access their own groups' space usage. The root
646user, or a user who has been granted the
647.Sy groupused
648privilege with
649.Qq Nm Cm allow ,
650can access all groups' usage.
651.It Sy volblocksize Ns = Ns Ar blocksize
652For volumes, specifies the block size of the volume. The
653.Ar blocksize
654cannot be changed once the volume has been written, so it should be set at
655volume creation time. The default
656.Ar blocksize
657for volumes is 8 Kbytes. Any
658power of 2 from 512 bytes to 128 Kbytes is valid.
659.Pp
660This property can also be referred to by its shortened column name,
661.Sy volblock .
|
| 662.It Sy written
663The amount of
664.Sy referenced
665space written to this dataset since the previous snapshot.
666.It Sy written@ Ns Ar snapshot
667The amount of
668.Sy referenced
669space written to this dataset since the specified snapshot. This is the space
670that is referenced by this dataset but was not referenced by the specified
671snapshot.
672.Pp
673The
674.Ar snapshot
675may be specified as a short snapshot name (just the part after the
676.Sy @ Ns ),
677in which case it will be interpreted as a snapshot in the same filesystem as
678this dataset. The
679.Ar snapshot
680may be a full snapshot name
681.Pq Em filesystem@snapshot ,
682which for clones may be a snapshot in the origin's filesystem (or the origin of
683the origin's filesystem, etc).
|
647.El
648.Pp
649The following native properties can be used to change the behavior of a
650.Tn ZFS
651dataset.
652.Bl -tag -width 2n
653.It Xo
654.Sy aclinherit Ns = Ns Cm discard |
655.Cm noallow |
656.Cm restricted |
657.Cm passthrough |
658.Cm passthrough-x
659.Xc
660Controls how
661.Tn ACL
662entries are inherited when files and directories are created. A file system
663with an
664.Sy aclinherit
665property of
666.Cm discard
667does not inherit any
668.Tn ACL
669entries. A file system with an
670.Sy aclinherit
671property value of
672.Cm noallow
673only inherits inheritable
674.Tn ACL
675entries that specify "deny" permissions. The property value
676.Cm restricted
677(the default) removes the
678.Em write_acl
679and
680.Em write_owner
681permissions when the
682.Tn ACL
683entry is inherited. A file system with an
684.Sy aclinherit
685property value of
686.Cm passthrough
687inherits all inheritable
688.Tn ACL
689entries without any modifications made to the
690.Tn ACL
691entries when they are inherited. A file system with an
692.Sy aclinherit
693property value of
694.Cm passthrough-x
695has the same meaning as
696.Cm passthrough ,
697except that the
698.Em owner@ , group@ , No and Em everyone@ Tn ACE Ns s
699inherit the execute permission only if the file creation mode also requests the
700execute bit.
701.Pp
702When the property value is set to
703.Cm passthrough ,
704files are created with a mode determined by the inheritable
705.Tn ACE Ns s.
706If no inheritable
707.Tn ACE Ns s
708exist that affect the mode, then the mode is set in accordance to the requested
709mode from the application.
710.It Sy aclmode Ns = Ns Cm discard | groupmask | passthrough
711Controls how an
712.Tn ACL
713is modified during
714.Xr chmod 2 .
715A file system with an
716.Sy aclmode
717property of
718.Cm discard
719(the default) deletes all
720.Tn ACL
721entries that do not represent the mode of the file. An
722.Sy aclmode
723property of
724.Cm groupmask
725reduces permissions granted in all
726.Em ALLOW
727entries found in the
728.Tn ACL
729such that they are no greater than the group permissions specified by
730.Xr chmod 2 .
731A file system with an
732.Sy aclmode
733property of
734.Cm passthrough
735indicates that no changes are made to the
736.Tn ACL
737other than creating or updating the necessary
738.Tn ACL
739entries to represent the new mode of the file or directory.
740.It Sy atime Ns = Ns Cm on | off
741Controls whether the access time for files is updated when they are read.
742Turning this property off avoids producing write traffic when reading files and
743can result in significant performance gains, though it might confuse mailers
744and other similar utilities. The default value is
745.Cm on .
746.It Sy canmount Ns = Ns Cm on | off | noauto
747If this property is set to
748.Cm off ,
749the file system cannot be mounted, and is ignored by
750.Qq Nm Cm mount Fl a .
751Setting this property to
752.Cm off
753is similar to setting the
754.Sy mountpoint
755property to
756.Cm none ,
757except that the dataset still has a normal
758.Sy mountpoint
759property, which can be inherited. Setting this property to
760.Cm off
761allows datasets to be used solely as a mechanism to inherit properties. One
762example of setting
763.Sy canmount Ns = Ns Cm off
764is to have two datasets with the same
765.Sy mountpoint ,
766so that the children of both datasets appear in the same directory, but might
767have different inherited characteristics.
768.Pp
769When the
770.Cm noauto
771value is set, a dataset can only be mounted and unmounted explicitly. The
772dataset is not mounted automatically when the dataset is created or imported,
773nor is it mounted by the
774.Qq Nm Cm mount Fl a
775command or unmounted by the
776.Qq Nm Cm umount Fl a
777command.
778.Pp
779This property is not inherited.
780.It Sy checksum Ns = Ns Cm on | off | fletcher2 | fletcher4
781Controls the checksum used to verify data integrity. The default value is
782.Cm on ,
783which automatically selects an appropriate algorithm (currently,
784.Cm fletcher4 ,
785but this may change in future releases). The value
786.Cm off
787disables integrity checking on user data. Disabling checksums is
788.Em NOT
789a recommended practice.
790.It Sy compression Ns = Ns Cm on | off | lzjb | gzip | gzip- Ns Ar N | Cm zle
791Controls the compression algorithm used for this dataset. The
792.CM lzjb
793compression algorithm is optimized for performance while providing decent data
794compression. Setting compression to
795.Cm on
796uses the
797.Cm lzjb
798compression algorithm. The
799.Cm gzip
800compression algorithm uses the same compression as the
801.Xr gzip 1
802command. You can specify the
803.Cm gzip
804level by using the value
805.Cm gzip- Ns Ar N
806where
807.Ar N
808is an integer from 1 (fastest) to 9 (best compression ratio). Currently,
809.Cm gzip
810is equivalent to
811.Cm gzip-6
812(which is also the default for
813.Xr gzip 1 Ns ).
814The
815.Cm zle
816compression algorithm compresses runs of zeros.
817.Pp
818This property can also be referred to by its shortened column name
819.Cm compress .
820Changing this property affects only newly-written data.
821.It Sy copies Ns = Ns Cm 1 | 2 | 3
822Controls the number of copies of data stored for this dataset. These copies are
823in addition to any redundancy provided by the pool, for example, mirroring or
824RAID-Z. The copies are stored on different disks, if possible. The space used
825by multiple copies is charged to the associated file and dataset, changing the
826.Sy used
827property and counting against quotas and reservations.
828.Pp
829Changing this property only affects newly-written data. Therefore, set this
830property at file system creation time by using the
831.Fl o Cm copies= Ns Ar N
832option.
833.It Sy dedup Ns = Ns Cm on | off | verify | sha256 Ns Op Cm ,verify
834Configures deduplication for a dataset. The default value is
835.Cm off .
836The default deduplication checksum is
837.Cm sha256
838(this may change in the future).
839When
840.Sy dedup
841is enabled, the checksum defined here overrides the
842.Sy checksum
843property. Setting the value to
844.Cm verify
845has the same effect as the setting
846.Cm sha256,verify .
847.Pp
848If set to
849.Cm verify ,
850.Tn ZFS
851will do a byte-to-byte comparsion in case of two blocks having the same
852signature to make sure the block contents are identical.
853.It Sy devices Ns = Ns Cm on | off
854The
855.Sy devices
856property is currently not supported on
857.Fx .
858.It Sy exec Ns = Ns Cm on | off
859Controls whether processes can be executed from within this file system. The
860default value is
861.Cm on .
862.It Sy mlslabel Ns = Ns Ar label | Cm none
863The
864.Sy mlslabel
865property is currently not supported on
866.Fx .
867.It Sy mountpoint Ns = Ns Ar path | Cm none | legacy
868Controls the mount point used for this file system. See the
869.Qq Sx Mount Points
870section for more information on how this property is used.
871.Pp
872When the
873.Sy mountpoint
874property is changed for a file system, the file system and any children that
875inherit the mount point are unmounted. If the new value is
876.Cm legacy ,
877then they remain unmounted. Otherwise, they are automatically remounted in the
878new location if the property was previously
879.Cm legacy
880or
881.Cm none ,
882or if they were mounted before the property was changed. In addition, any
883shared file systems are unshared and shared in the new location.
884.It Sy nbmand Ns = Ns Cm on | off
885The
886.Sy nbmand
887property is currently not supported on
888.Fx .
889.It Sy primarycache Ns = Ns Cm all | none | metadata
890Controls what is cached in the primary cache (ARC). If this property is set to
891.Cm all ,
892then both user data and metadata is cached. If this property is set to
893.Cm none ,
894then neither user data nor metadata is cached. If this property is set to
895.Cm metadata ,
896then only metadata is cached. The default value is
897.Cm all .
898.It Sy quota Ns = Ns Ar size | Cm none
899Limits the amount of space a dataset and its descendents can consume. This
900property enforces a hard limit on the amount of space used. This includes all
901space consumed by descendents, including file systems and snapshots. Setting a
902quota on a descendent of a dataset that already has a quota does not override
903the ancestor's quota, but rather imposes an additional limit.
904.Pp
905Quotas cannot be set on volumes, as the
906.Sy volsize
907property acts as an implicit quota.
908.It Sy userquota@ Ns Ar user Ns = Ns Ar size | Cm none
909Limits the amount of space consumed by the specified user.
910Similar to the
911.Sy refquota
912property, the
913.Sy userquota
914space calculation does not include space that is used by descendent datasets,
915such as snapshots and clones. User space consumption is identified by the
916.Sy userspace@ Ns Ar user
917property.
918.sp
919Enforcement of user quotas may be delayed by several seconds. This delay means
920that a user might exceed their quota before the system notices that they are
921over quota and begins to refuse additional writes with the
922.Em EDQUOT
923error message. See the
924.Cm userspace
925subcommand for more information.
926.sp
927Unprivileged users can only access their own groups' space usage. The root
928user, or a user who has been granted the
929.Sy userquota
930privilege with
931.Qq Nm Cm allow ,
932can get and set everyone's quota.
933.sp
934This property is not available on volumes, on file systems before version 4, or
935on pools before version 15. The
936.Sy userquota@ Ns ...
937properties are not displayed by
938.Qq Nm Cm get all .
939The user's name must be appended after the
940.Sy @
941symbol, using one of the following forms:
942.Bl -bullet -offset 2n
943.It
944POSIX name (for example,
945.Em joe Ns )
946.It
947POSIX numeric ID (for example,
948.Em 1001 Ns )
949.El
950.It Sy groupquota@ Ns Ar group Ns = Ns Ar size | Cm none
951Limits the amount of space consumed by the specified group. Group space
952consumption is identified by the
953.Sy userquota@ Ns Ar user
954property.
955.sp
956Unprivileged users can access only their own groups' space usage. The root
957user, or a user who has been granted the
958.Sy groupquota
959privilege with
960.Qq Nm Cm allow ,
961can get and set all groups' quotas.
962.It Sy readonly Ns = Ns Cm on | off
963Controls whether this dataset can be modified. The default value is
964.Cm off .
965.It Sy recordsize Ns = Ns Ar size
966Specifies a suggested block size for files in the file system. This property is
967designed solely for use with database workloads that access files in fixed-size
968records.
969.Tn ZFS
970automatically tunes block sizes according to internal algorithms optimized for
971typical access patterns.
972.Pp
973For databases that create very large files but access them in small random
974chunks, these algorithms may be suboptimal. Specifying a
975.Sy recordsize
976greater than or equal to the record size of the database can result in
977significant performance gains. Use of this property for general purpose file
978systems is strongly discouraged, and may adversely affect performance.
979.Pp
980The size specified must be a power of two greater than or equal to 512 and less
981than or equal to 128 Kbytes.
982.Pp
983Changing the file system's
984.Sy recordsize
985affects only files created afterward; existing files are unaffected.
986.sp
987This property can also be referred to by its shortened column name,
988.Sy recsize .
989.It Sy refquota Ns = Ns Ar size | Cm none
990Limits the amount of space a dataset can consume. This property enforces a hard
991limit on the amount of space used. This hard limit does not include space used
992by descendents, including file systems and snapshots.
993.It Sy refreservation Ns = Ns Ar size | Cm none
994The minimum amount of space guaranteed to a dataset, not including its
995descendents. When the amount of space used is below this value, the dataset is
996treated as if it were taking up the amount of space specified by
997.Sy refreservation .
998The
999.Sy refreservation
1000reservation is accounted for in the parent datasets' space used, and counts
1001against the parent datasets' quotas and reservations.
1002.sp
1003If
1004.Sy refreservation
1005is set, a snapshot is only allowed if there is enough free pool space outside
1006of this reservation to accommodate the current number of "referenced" bytes in
1007the dataset.
1008.sp
1009This property can also be referred to by its shortened column name,
1010.Sy refreserv .
1011.It Sy reservation Ns = Ns Ar size | Cm none
1012The minimum amount of space guaranteed to a dataset and its descendents. When
1013the amount of space used is below this value, the dataset is treated as if it
1014were taking up the amount of space specified by its reservation. Reservations
1015are accounted for in the parent datasets' space used, and count against the
1016parent datasets' quotas and reservations.
1017.Pp
1018This property can also be referred to by its shortened column name,
1019.Sy reserv .
1020.It Sy secondarycache Ns = Ns Cm all | none | metadata
1021Controls what is cached in the secondary cache (L2ARC). If this property is set
1022to
1023.Cm all ,
1024then both user data and metadata is cached. If this property is set to
1025.Cm none ,
1026then neither user data nor metadata is cached. If this property is set to
1027.Cm metadata ,
1028then only metadata is cached. The default value is
1029.Cm all .
1030.It Sy setuid Ns = Ns Cm on | off
1031Controls whether the
1032.No set- Ns Tn UID
1033bit is respected for the file system. The default value is
1034.Cm on .
1035.It Sy sharesmb Ns = Ns Cm on | off | Ar opts
1036The
1037.Sy sharesmb
1038property has currently no effect o
1039.Fx .
1040.It Sy sharenfs Ns = Ns Cm on | off | Ar opts
1041Controls whether the file system is shared via
1042.Tn NFS ,
1043and what options are used. A file system with a
1044.Sy sharenfs
1045property of
1046.Cm off
1047is managed the traditional way via
1048.Xr exports 5 .
1049Otherwise, the file system is automatically shared and unshared with the
1050.Qq Nm Cm share
1051and
1052.Qq Nm Cm unshare
1053commands. If the property is set to
1054.Cm on
1055no
1056.Tn NFS
1057export options are used. Otherwise,
1058.Tn NFS
1059export options are equivalent to the contents of this property. The export
1060options may be comma-separated. See
1061.Xr exports 5
1062for a list of valid options.
1063.Pp
1064When the
1065.Sy sharenfs
1066property is changed for a dataset, the
1067.Xr mountd 8
1068dameon is reloaded.
1069.It Sy logbias Ns = Ns Cm latency | throughput
1070Provide a hint to
1071.Tn ZFS
1072about handling of synchronous requests in this dataset.
1073If
1074.Sy logbias
1075is set to
1076.Cm latency
1077(the default),
1078.Tn ZFS
1079will use pool log devices (if configured) to handle the requests at low
1080latency. If
1081.Sy logbias
1082is set to
1083.Cm throughput ,
1084.Tn ZFS
1085will not use configured pool log devices.
1086.Tn ZFS
1087will instead optimize synchronous operations for global pool throughput and
1088efficient use of resources.
1089.It Sy snapdir Ns = Ns Cm hidden | visible
1090Controls whether the
1091.Pa \&.zfs
1092directory is hidden or visible in the root of the file system as discussed in
1093the
1094.Qq Sx Snapshots
1095section. The default value is
1096.Cm hidden .
1097.It Sy sync Ns = Ns Cm standard | always | disabled
1098Controls the behavior of synchronous requests (e.g.
1099.Xr fsync 2 ,
1100O_DSYNC). This property accepts the following values:
1101.Bl -tag -offset 4n -width 8n
1102.It Sy standard
1103This is the POSIX specified behavior of ensuring all synchronous requests are
1104written to stable storage and all devices are flushed to ensure data is not
1105cached by device controllers (this is the default).
1106.It Sy always
1107All file system transactions are written and flushed before their system calls
1108return. This has a large performance penalty.
1109.It Sy disabled
1110Disables synchronous requests. File system transactions are only committed to
1111stable storage periodically. This option will give the highest performance.
1112However, it is very dangerous as
1113.Tn ZFS
1114would be ignoring the synchronous transaction demands of applications such as
1115databases or
1116.Tn NFS .
1117Administrators should only use this option when the risks are understood.
1118.El
1119.It Sy volsize Ns = Ns Ar size
1120For volumes, specifies the logical size of the volume. By default, creating a
1121volume establishes a reservation of equal size. For storage pools with a
1122version number of 9 or higher, a
1123.Sy refreservation
1124is set instead. Any changes to
1125.Sy volsize
1126are reflected in an equivalent change to the reservation (or
1127.Sy refreservation Ns ).
1128The
1129.Sy volsize
1130can only be set to a multiple of
1131.Cm volblocksize ,
1132and cannot be zero.
1133.Pp
1134The reservation is kept equal to the volume's logical size to prevent
1135unexpected behavior for consumers. Without the reservation, the volume could
1136run out of space, resulting in undefined behavior or data corruption, depending
1137on how the volume is used. These effects can also occur when the volume size is
1138changed while it is in use (particularly when shrinking the size). Extreme care
1139should be used when adjusting the volume size.
1140.sp
1141Though not recommended, a "sparse volume" (also known as "thin provisioning")
1142can be created by specifying the
1143.Fl s
1144option to the
1145.Qq Nm Cm create Fl V
1146command, or by changing the reservation after the volume has been created. A
1147"sparse volume" is a volume where the reservation is less then the volume size.
1148Consequently, writes to a sparse volume can fail with
1149.Sy ENOSPC
1150when the pool is low on space. For a sparse volume, changes to
1151.Sy volsize
1152are not reflected in the reservation.
1153.It Sy vscan Ns = Ns Cm off | on
1154The
1155.Sy vscan
1156property is currently not supported on
1157.Fx .
1158.It Sy xattr Ns = Ns Cm off | on
1159The
1160.Sy xattr
1161property is currently not supported on
1162.Fx .
1163.It Sy jailed Ns = Ns Cm off | on
1164Controls whether the dataset is managed from a jail. See the
1165.Qq Sx Jails
1166section for more information. The default value is
1167.Cm off .
1168.El
1169.Pp
1170The following three properties cannot be changed after the file system is
1171created, and therefore, should be set when the file system is created. If the
1172properties are not set with the
1173.Qq Nm Cm create
1174or
1175.Nm zpool Cm create
1176commands, these properties are inherited from the parent dataset. If the parent
1177dataset lacks these properties due to having been created prior to these
1178features being supported, the new file system will have the default values for
1179these properties.
1180.Bl -tag -width 4n
1181.It Sy casesensitivity Ns = Ns Cm sensitive | insensitive | mixed
1182The
1183.Sy casesensitivity
1184property is currently not supported on
1185.Fx .
1186.It Sy normalization Ns = Ns Cm none | formC | formD | formKC | formKD
1187Indicates whether the file system should perform a
1188.Sy unicode
1189normalization of file names whenever two file names are compared, and which
1190normalization algorithm should be used. File names are always stored
1191unmodified, names are normalized as part of any comparison process. If this
1192property is set to a legal value other than
1193.Cm none ,
1194and the
1195.Sy utf8only
1196property was left unspecified, the
1197.Sy utf8only
1198property is automatically set to
1199.Cm on .
1200The default value of the
1201.Sy normalization
1202property is
1203.Cm none .
1204This property cannot be changed after the file system is created.
1205.It Sy utf8only Ns = Ns Cm on | off
1206Indicates whether the file system should reject file names that include
1207characters that are not present in the
1208.Sy UTF-8
1209character code set. If this property is explicitly set to
1210.Cm off ,
1211the normalization property must either not be explicitly set or be set to
1212.Cm none .
1213The default value for the
1214.Sy utf8only
1215property is
1216.Cm off .
1217This property cannot be changed after the file system is created.
1218.El
1219.Pp
1220The
1221.Sy casesensitivity , normalization , No and Sy utf8only
1222properties are also new permissions that can be assigned to non-privileged
1223users by using the
1224.Tn ZFS
1225delegated administration feature.
1226.Ss Temporary Mount Point Properties
1227When a file system is mounted, either through
1228.Xr mount 8
1229for legacy mounts or the
1230.Qq Nm Cm mount
1231command for normal file systems, its mount options are set according to its
1232properties. The correlation between properties and mount options is as follows:
1233.Bl -column -offset 4n "PROPERTY" "MOUNT OPTION"
1234.It PROPERTY MOUNT OPTION
1235.It atime atime/noatime
1236.It exec exec/noexec
1237.It readonly ro/rw
1238.It setuid suid/nosuid
1239.El
1240.Pp
1241In addition, these options can be set on a per-mount basis using the
1242.Fl o
1243option, without affecting the property that is stored on disk. The values
1244specified on the command line override the values stored in the dataset. These
1245properties are reported as "temporary" by the
1246.Qq Nm Cm get
1247command. If the properties are changed while the dataset is mounted, the new
1248setting overrides any temporary settings.
1249.Ss User Properties
1250In addition to the standard native properties,
1251.Tn ZFS
1252supports arbitrary user properties. User properties have no effect on
1253.Tn ZFS
1254behavior, but applications or administrators can use them to annotate datasets
1255(file systems, volumes, and snapshots).
1256.Pp
1257User property names must contain a colon
1258.Pq Sy \&:
1259character to distinguish them from native properties. They may contain
1260lowercase letters, numbers, and the following punctuation characters: colon
1261.Pq Sy \&: ,
1262dash
1263.Pq Sy \&- ,
1264period
1265.Pq Sy \&.
1266and underscore
1267.Pq Sy \&_ .
1268The expected convention is that the property name is divided into two portions
1269such as
1270.Em module Ns Sy \&: Ns Em property ,
1271but this namespace is not enforced by
1272.Tn ZFS .
1273User property names can be at most 256 characters, and cannot begin with a dash
1274.Pq Sy \&- .
1275.Pp
1276When making programmatic use of user properties, it is strongly suggested to
1277use a reversed
1278.Tn DNS
1279domain name for the
1280.Ar module
1281component of property names to reduce the chance that two
1282independently-developed packages use the same property name for different
1283purposes. Property names beginning with
1284.Em com.sun
1285are reserved for use by Sun Microsystems.
1286.Pp
1287The values of user properties are arbitrary strings, are always inherited, and
1288are never validated. All of the commands that operate on properties
1289.Po
1290.Qq Nm Cm list ,
1291.Qq Nm Cm get ,
1292.Qq Nm Cm set
1293and so forth
1294.Pc
1295can be used to manipulate both native properties and user properties. Use the
1296.Qq Nm Cm inherit
1297command to clear a user property. If the property is not defined in any parent
1298dataset, it is removed entirely. Property values are limited to 1024
1299characters.
1300.Sh SUBCOMMANDS
1301All subcommands that modify state are logged persistently to the pool in their
1302original form.
1303.Bl -tag -width 2n
1304.It Xo
1305.Nm
1306.Op Fl \&?
1307.Xc
1308.Pp
1309Displays a help message.
1310.It Xo
1311.Nm
1312.Cm create
1313.Op Fl p
1314.Op Fl o Ar property Ns = Ns Ar value
1315.Ar ... filesystem
1316.Xc
1317.Pp
1318Creates a new
1319.Tn ZFS
1320file system. The file system is automatically mounted according to the
1321.Sy mountpoint
1322property inherited from the parent.
1323.Bl -tag -width indent
1324.It Fl p
1325Creates all the non-existing parent datasets. Datasets created in this manner
1326are automatically mounted according to the
1327.Sy mountpoint
1328property inherited from their parent. Any property specified on the command
1329line using the
1330.Fl o
1331option is ignored. If the target filesystem already exists, the operation
1332completes successfully.
1333.It Fl o Ar property Ns = Ns Ar value
1334Sets the specified property as if the command
1335.Qq Nm Cm set Ar property Ns = Ns Ar value
1336was invoked at the same time the dataset was created. Any editable
1337.Tn ZFS
1338property can also be set at creation time. Multiple
1339.Fl o
1340options can be specified. An error results if the same property is specified in
1341multiple
1342.Fl o
1343options.
1344.El
1345.It Xo
1346.Nm
1347.Cm create
1348.Op Fl ps
1349.Op Fl b Ar blocksize
1350.Op Fl o Ar property Ns = Ns Ar value
1351.Ar ...
1352.Fl V
1353.Ar size volume
1354.Xc
1355.Pp
1356Creates a volume of the given size. The volume is exported as a block device in
1357.Pa /dev/zvol/path ,
1358where
1359.Ar path
1360is the name of the volume in the
1361.Tn ZFS
1362namespace. The size represents the logical size as exported by the device. By
1363default, a reservation of equal size is created.
1364.Pp
1365.Ar size
1366is automatically rounded up to the nearest 128 Kbytes to ensure that
1367the volume has an integral number of blocks regardless of
1368.Ar blocksize .
1369.Bl -tag -width indent
1370.It Fl p
1371Creates all the non-existing parent datasets. Datasets created in this manner
1372are automatically mounted according to the
1373.Sy mountpoint
1374property inherited from their parent. Any property specified on the command
1375line using the
1376.Fl o
1377option is ignored. If the target filesystem already exists, the operation
1378completes successfully.
1379.It Fl s
1380Creates a sparse volume with no reservation. See
1381.Sy volsize
1382in the
1383.Qq Sx Native Properties
1384section for more information about sparse volumes.
1385.It Fl b Ar blocksize
1386Equivalent to
1387.Fl o Cm volblocksize Ns = Ns Ar blocksize .
1388If this option is specified in conjunction with
1389.Fl o Cm volblocksize ,
1390the resulting behavior is undefined.
1391.It Fl o Ar property Ns = Ns Ar value
1392Sets the specified property as if the
1393.Qq Nm Cm set Ar property Ns = Ns Ar value
1394command was invoked at the same time the dataset was created. Any editable
1395.Tn ZFS
1396property can also be set at creation time. Multiple
1397.Fl o
1398options can be specified. An error results if the same property is specified in
1399multiple
1400.Fl o
1401options.
1402.El
1403.It Xo
1404.Nm
1405.Cm destroy
| 684.El
685.Pp
686The following native properties can be used to change the behavior of a
687.Tn ZFS
688dataset.
689.Bl -tag -width 2n
690.It Xo
691.Sy aclinherit Ns = Ns Cm discard |
692.Cm noallow |
693.Cm restricted |
694.Cm passthrough |
695.Cm passthrough-x
696.Xc
697Controls how
698.Tn ACL
699entries are inherited when files and directories are created. A file system
700with an
701.Sy aclinherit
702property of
703.Cm discard
704does not inherit any
705.Tn ACL
706entries. A file system with an
707.Sy aclinherit
708property value of
709.Cm noallow
710only inherits inheritable
711.Tn ACL
712entries that specify "deny" permissions. The property value
713.Cm restricted
714(the default) removes the
715.Em write_acl
716and
717.Em write_owner
718permissions when the
719.Tn ACL
720entry is inherited. A file system with an
721.Sy aclinherit
722property value of
723.Cm passthrough
724inherits all inheritable
725.Tn ACL
726entries without any modifications made to the
727.Tn ACL
728entries when they are inherited. A file system with an
729.Sy aclinherit
730property value of
731.Cm passthrough-x
732has the same meaning as
733.Cm passthrough ,
734except that the
735.Em owner@ , group@ , No and Em everyone@ Tn ACE Ns s
736inherit the execute permission only if the file creation mode also requests the
737execute bit.
738.Pp
739When the property value is set to
740.Cm passthrough ,
741files are created with a mode determined by the inheritable
742.Tn ACE Ns s.
743If no inheritable
744.Tn ACE Ns s
745exist that affect the mode, then the mode is set in accordance to the requested
746mode from the application.
747.It Sy aclmode Ns = Ns Cm discard | groupmask | passthrough
748Controls how an
749.Tn ACL
750is modified during
751.Xr chmod 2 .
752A file system with an
753.Sy aclmode
754property of
755.Cm discard
756(the default) deletes all
757.Tn ACL
758entries that do not represent the mode of the file. An
759.Sy aclmode
760property of
761.Cm groupmask
762reduces permissions granted in all
763.Em ALLOW
764entries found in the
765.Tn ACL
766such that they are no greater than the group permissions specified by
767.Xr chmod 2 .
768A file system with an
769.Sy aclmode
770property of
771.Cm passthrough
772indicates that no changes are made to the
773.Tn ACL
774other than creating or updating the necessary
775.Tn ACL
776entries to represent the new mode of the file or directory.
777.It Sy atime Ns = Ns Cm on | off
778Controls whether the access time for files is updated when they are read.
779Turning this property off avoids producing write traffic when reading files and
780can result in significant performance gains, though it might confuse mailers
781and other similar utilities. The default value is
782.Cm on .
783.It Sy canmount Ns = Ns Cm on | off | noauto
784If this property is set to
785.Cm off ,
786the file system cannot be mounted, and is ignored by
787.Qq Nm Cm mount Fl a .
788Setting this property to
789.Cm off
790is similar to setting the
791.Sy mountpoint
792property to
793.Cm none ,
794except that the dataset still has a normal
795.Sy mountpoint
796property, which can be inherited. Setting this property to
797.Cm off
798allows datasets to be used solely as a mechanism to inherit properties. One
799example of setting
800.Sy canmount Ns = Ns Cm off
801is to have two datasets with the same
802.Sy mountpoint ,
803so that the children of both datasets appear in the same directory, but might
804have different inherited characteristics.
805.Pp
806When the
807.Cm noauto
808value is set, a dataset can only be mounted and unmounted explicitly. The
809dataset is not mounted automatically when the dataset is created or imported,
810nor is it mounted by the
811.Qq Nm Cm mount Fl a
812command or unmounted by the
813.Qq Nm Cm umount Fl a
814command.
815.Pp
816This property is not inherited.
817.It Sy checksum Ns = Ns Cm on | off | fletcher2 | fletcher4
818Controls the checksum used to verify data integrity. The default value is
819.Cm on ,
820which automatically selects an appropriate algorithm (currently,
821.Cm fletcher4 ,
822but this may change in future releases). The value
823.Cm off
824disables integrity checking on user data. Disabling checksums is
825.Em NOT
826a recommended practice.
827.It Sy compression Ns = Ns Cm on | off | lzjb | gzip | gzip- Ns Ar N | Cm zle
828Controls the compression algorithm used for this dataset. The
829.CM lzjb
830compression algorithm is optimized for performance while providing decent data
831compression. Setting compression to
832.Cm on
833uses the
834.Cm lzjb
835compression algorithm. The
836.Cm gzip
837compression algorithm uses the same compression as the
838.Xr gzip 1
839command. You can specify the
840.Cm gzip
841level by using the value
842.Cm gzip- Ns Ar N
843where
844.Ar N
845is an integer from 1 (fastest) to 9 (best compression ratio). Currently,
846.Cm gzip
847is equivalent to
848.Cm gzip-6
849(which is also the default for
850.Xr gzip 1 Ns ).
851The
852.Cm zle
853compression algorithm compresses runs of zeros.
854.Pp
855This property can also be referred to by its shortened column name
856.Cm compress .
857Changing this property affects only newly-written data.
858.It Sy copies Ns = Ns Cm 1 | 2 | 3
859Controls the number of copies of data stored for this dataset. These copies are
860in addition to any redundancy provided by the pool, for example, mirroring or
861RAID-Z. The copies are stored on different disks, if possible. The space used
862by multiple copies is charged to the associated file and dataset, changing the
863.Sy used
864property and counting against quotas and reservations.
865.Pp
866Changing this property only affects newly-written data. Therefore, set this
867property at file system creation time by using the
868.Fl o Cm copies= Ns Ar N
869option.
870.It Sy dedup Ns = Ns Cm on | off | verify | sha256 Ns Op Cm ,verify
871Configures deduplication for a dataset. The default value is
872.Cm off .
873The default deduplication checksum is
874.Cm sha256
875(this may change in the future).
876When
877.Sy dedup
878is enabled, the checksum defined here overrides the
879.Sy checksum
880property. Setting the value to
881.Cm verify
882has the same effect as the setting
883.Cm sha256,verify .
884.Pp
885If set to
886.Cm verify ,
887.Tn ZFS
888will do a byte-to-byte comparsion in case of two blocks having the same
889signature to make sure the block contents are identical.
890.It Sy devices Ns = Ns Cm on | off
891The
892.Sy devices
893property is currently not supported on
894.Fx .
895.It Sy exec Ns = Ns Cm on | off
896Controls whether processes can be executed from within this file system. The
897default value is
898.Cm on .
899.It Sy mlslabel Ns = Ns Ar label | Cm none
900The
901.Sy mlslabel
902property is currently not supported on
903.Fx .
904.It Sy mountpoint Ns = Ns Ar path | Cm none | legacy
905Controls the mount point used for this file system. See the
906.Qq Sx Mount Points
907section for more information on how this property is used.
908.Pp
909When the
910.Sy mountpoint
911property is changed for a file system, the file system and any children that
912inherit the mount point are unmounted. If the new value is
913.Cm legacy ,
914then they remain unmounted. Otherwise, they are automatically remounted in the
915new location if the property was previously
916.Cm legacy
917or
918.Cm none ,
919or if they were mounted before the property was changed. In addition, any
920shared file systems are unshared and shared in the new location.
921.It Sy nbmand Ns = Ns Cm on | off
922The
923.Sy nbmand
924property is currently not supported on
925.Fx .
926.It Sy primarycache Ns = Ns Cm all | none | metadata
927Controls what is cached in the primary cache (ARC). If this property is set to
928.Cm all ,
929then both user data and metadata is cached. If this property is set to
930.Cm none ,
931then neither user data nor metadata is cached. If this property is set to
932.Cm metadata ,
933then only metadata is cached. The default value is
934.Cm all .
935.It Sy quota Ns = Ns Ar size | Cm none
936Limits the amount of space a dataset and its descendents can consume. This
937property enforces a hard limit on the amount of space used. This includes all
938space consumed by descendents, including file systems and snapshots. Setting a
939quota on a descendent of a dataset that already has a quota does not override
940the ancestor's quota, but rather imposes an additional limit.
941.Pp
942Quotas cannot be set on volumes, as the
943.Sy volsize
944property acts as an implicit quota.
945.It Sy userquota@ Ns Ar user Ns = Ns Ar size | Cm none
946Limits the amount of space consumed by the specified user.
947Similar to the
948.Sy refquota
949property, the
950.Sy userquota
951space calculation does not include space that is used by descendent datasets,
952such as snapshots and clones. User space consumption is identified by the
953.Sy userspace@ Ns Ar user
954property.
955.sp
956Enforcement of user quotas may be delayed by several seconds. This delay means
957that a user might exceed their quota before the system notices that they are
958over quota and begins to refuse additional writes with the
959.Em EDQUOT
960error message. See the
961.Cm userspace
962subcommand for more information.
963.sp
964Unprivileged users can only access their own groups' space usage. The root
965user, or a user who has been granted the
966.Sy userquota
967privilege with
968.Qq Nm Cm allow ,
969can get and set everyone's quota.
970.sp
971This property is not available on volumes, on file systems before version 4, or
972on pools before version 15. The
973.Sy userquota@ Ns ...
974properties are not displayed by
975.Qq Nm Cm get all .
976The user's name must be appended after the
977.Sy @
978symbol, using one of the following forms:
979.Bl -bullet -offset 2n
980.It
981POSIX name (for example,
982.Em joe Ns )
983.It
984POSIX numeric ID (for example,
985.Em 1001 Ns )
986.El
987.It Sy groupquota@ Ns Ar group Ns = Ns Ar size | Cm none
988Limits the amount of space consumed by the specified group. Group space
989consumption is identified by the
990.Sy userquota@ Ns Ar user
991property.
992.sp
993Unprivileged users can access only their own groups' space usage. The root
994user, or a user who has been granted the
995.Sy groupquota
996privilege with
997.Qq Nm Cm allow ,
998can get and set all groups' quotas.
999.It Sy readonly Ns = Ns Cm on | off
1000Controls whether this dataset can be modified. The default value is
1001.Cm off .
1002.It Sy recordsize Ns = Ns Ar size
1003Specifies a suggested block size for files in the file system. This property is
1004designed solely for use with database workloads that access files in fixed-size
1005records.
1006.Tn ZFS
1007automatically tunes block sizes according to internal algorithms optimized for
1008typical access patterns.
1009.Pp
1010For databases that create very large files but access them in small random
1011chunks, these algorithms may be suboptimal. Specifying a
1012.Sy recordsize
1013greater than or equal to the record size of the database can result in
1014significant performance gains. Use of this property for general purpose file
1015systems is strongly discouraged, and may adversely affect performance.
1016.Pp
1017The size specified must be a power of two greater than or equal to 512 and less
1018than or equal to 128 Kbytes.
1019.Pp
1020Changing the file system's
1021.Sy recordsize
1022affects only files created afterward; existing files are unaffected.
1023.sp
1024This property can also be referred to by its shortened column name,
1025.Sy recsize .
1026.It Sy refquota Ns = Ns Ar size | Cm none
1027Limits the amount of space a dataset can consume. This property enforces a hard
1028limit on the amount of space used. This hard limit does not include space used
1029by descendents, including file systems and snapshots.
1030.It Sy refreservation Ns = Ns Ar size | Cm none
1031The minimum amount of space guaranteed to a dataset, not including its
1032descendents. When the amount of space used is below this value, the dataset is
1033treated as if it were taking up the amount of space specified by
1034.Sy refreservation .
1035The
1036.Sy refreservation
1037reservation is accounted for in the parent datasets' space used, and counts
1038against the parent datasets' quotas and reservations.
1039.sp
1040If
1041.Sy refreservation
1042is set, a snapshot is only allowed if there is enough free pool space outside
1043of this reservation to accommodate the current number of "referenced" bytes in
1044the dataset.
1045.sp
1046This property can also be referred to by its shortened column name,
1047.Sy refreserv .
1048.It Sy reservation Ns = Ns Ar size | Cm none
1049The minimum amount of space guaranteed to a dataset and its descendents. When
1050the amount of space used is below this value, the dataset is treated as if it
1051were taking up the amount of space specified by its reservation. Reservations
1052are accounted for in the parent datasets' space used, and count against the
1053parent datasets' quotas and reservations.
1054.Pp
1055This property can also be referred to by its shortened column name,
1056.Sy reserv .
1057.It Sy secondarycache Ns = Ns Cm all | none | metadata
1058Controls what is cached in the secondary cache (L2ARC). If this property is set
1059to
1060.Cm all ,
1061then both user data and metadata is cached. If this property is set to
1062.Cm none ,
1063then neither user data nor metadata is cached. If this property is set to
1064.Cm metadata ,
1065then only metadata is cached. The default value is
1066.Cm all .
1067.It Sy setuid Ns = Ns Cm on | off
1068Controls whether the
1069.No set- Ns Tn UID
1070bit is respected for the file system. The default value is
1071.Cm on .
1072.It Sy sharesmb Ns = Ns Cm on | off | Ar opts
1073The
1074.Sy sharesmb
1075property has currently no effect o
1076.Fx .
1077.It Sy sharenfs Ns = Ns Cm on | off | Ar opts
1078Controls whether the file system is shared via
1079.Tn NFS ,
1080and what options are used. A file system with a
1081.Sy sharenfs
1082property of
1083.Cm off
1084is managed the traditional way via
1085.Xr exports 5 .
1086Otherwise, the file system is automatically shared and unshared with the
1087.Qq Nm Cm share
1088and
1089.Qq Nm Cm unshare
1090commands. If the property is set to
1091.Cm on
1092no
1093.Tn NFS
1094export options are used. Otherwise,
1095.Tn NFS
1096export options are equivalent to the contents of this property. The export
1097options may be comma-separated. See
1098.Xr exports 5
1099for a list of valid options.
1100.Pp
1101When the
1102.Sy sharenfs
1103property is changed for a dataset, the
1104.Xr mountd 8
1105dameon is reloaded.
1106.It Sy logbias Ns = Ns Cm latency | throughput
1107Provide a hint to
1108.Tn ZFS
1109about handling of synchronous requests in this dataset.
1110If
1111.Sy logbias
1112is set to
1113.Cm latency
1114(the default),
1115.Tn ZFS
1116will use pool log devices (if configured) to handle the requests at low
1117latency. If
1118.Sy logbias
1119is set to
1120.Cm throughput ,
1121.Tn ZFS
1122will not use configured pool log devices.
1123.Tn ZFS
1124will instead optimize synchronous operations for global pool throughput and
1125efficient use of resources.
1126.It Sy snapdir Ns = Ns Cm hidden | visible
1127Controls whether the
1128.Pa \&.zfs
1129directory is hidden or visible in the root of the file system as discussed in
1130the
1131.Qq Sx Snapshots
1132section. The default value is
1133.Cm hidden .
1134.It Sy sync Ns = Ns Cm standard | always | disabled
1135Controls the behavior of synchronous requests (e.g.
1136.Xr fsync 2 ,
1137O_DSYNC). This property accepts the following values:
1138.Bl -tag -offset 4n -width 8n
1139.It Sy standard
1140This is the POSIX specified behavior of ensuring all synchronous requests are
1141written to stable storage and all devices are flushed to ensure data is not
1142cached by device controllers (this is the default).
1143.It Sy always
1144All file system transactions are written and flushed before their system calls
1145return. This has a large performance penalty.
1146.It Sy disabled
1147Disables synchronous requests. File system transactions are only committed to
1148stable storage periodically. This option will give the highest performance.
1149However, it is very dangerous as
1150.Tn ZFS
1151would be ignoring the synchronous transaction demands of applications such as
1152databases or
1153.Tn NFS .
1154Administrators should only use this option when the risks are understood.
1155.El
1156.It Sy volsize Ns = Ns Ar size
1157For volumes, specifies the logical size of the volume. By default, creating a
1158volume establishes a reservation of equal size. For storage pools with a
1159version number of 9 or higher, a
1160.Sy refreservation
1161is set instead. Any changes to
1162.Sy volsize
1163are reflected in an equivalent change to the reservation (or
1164.Sy refreservation Ns ).
1165The
1166.Sy volsize
1167can only be set to a multiple of
1168.Cm volblocksize ,
1169and cannot be zero.
1170.Pp
1171The reservation is kept equal to the volume's logical size to prevent
1172unexpected behavior for consumers. Without the reservation, the volume could
1173run out of space, resulting in undefined behavior or data corruption, depending
1174on how the volume is used. These effects can also occur when the volume size is
1175changed while it is in use (particularly when shrinking the size). Extreme care
1176should be used when adjusting the volume size.
1177.sp
1178Though not recommended, a "sparse volume" (also known as "thin provisioning")
1179can be created by specifying the
1180.Fl s
1181option to the
1182.Qq Nm Cm create Fl V
1183command, or by changing the reservation after the volume has been created. A
1184"sparse volume" is a volume where the reservation is less then the volume size.
1185Consequently, writes to a sparse volume can fail with
1186.Sy ENOSPC
1187when the pool is low on space. For a sparse volume, changes to
1188.Sy volsize
1189are not reflected in the reservation.
1190.It Sy vscan Ns = Ns Cm off | on
1191The
1192.Sy vscan
1193property is currently not supported on
1194.Fx .
1195.It Sy xattr Ns = Ns Cm off | on
1196The
1197.Sy xattr
1198property is currently not supported on
1199.Fx .
1200.It Sy jailed Ns = Ns Cm off | on
1201Controls whether the dataset is managed from a jail. See the
1202.Qq Sx Jails
1203section for more information. The default value is
1204.Cm off .
1205.El
1206.Pp
1207The following three properties cannot be changed after the file system is
1208created, and therefore, should be set when the file system is created. If the
1209properties are not set with the
1210.Qq Nm Cm create
1211or
1212.Nm zpool Cm create
1213commands, these properties are inherited from the parent dataset. If the parent
1214dataset lacks these properties due to having been created prior to these
1215features being supported, the new file system will have the default values for
1216these properties.
1217.Bl -tag -width 4n
1218.It Sy casesensitivity Ns = Ns Cm sensitive | insensitive | mixed
1219The
1220.Sy casesensitivity
1221property is currently not supported on
1222.Fx .
1223.It Sy normalization Ns = Ns Cm none | formC | formD | formKC | formKD
1224Indicates whether the file system should perform a
1225.Sy unicode
1226normalization of file names whenever two file names are compared, and which
1227normalization algorithm should be used. File names are always stored
1228unmodified, names are normalized as part of any comparison process. If this
1229property is set to a legal value other than
1230.Cm none ,
1231and the
1232.Sy utf8only
1233property was left unspecified, the
1234.Sy utf8only
1235property is automatically set to
1236.Cm on .
1237The default value of the
1238.Sy normalization
1239property is
1240.Cm none .
1241This property cannot be changed after the file system is created.
1242.It Sy utf8only Ns = Ns Cm on | off
1243Indicates whether the file system should reject file names that include
1244characters that are not present in the
1245.Sy UTF-8
1246character code set. If this property is explicitly set to
1247.Cm off ,
1248the normalization property must either not be explicitly set or be set to
1249.Cm none .
1250The default value for the
1251.Sy utf8only
1252property is
1253.Cm off .
1254This property cannot be changed after the file system is created.
1255.El
1256.Pp
1257The
1258.Sy casesensitivity , normalization , No and Sy utf8only
1259properties are also new permissions that can be assigned to non-privileged
1260users by using the
1261.Tn ZFS
1262delegated administration feature.
1263.Ss Temporary Mount Point Properties
1264When a file system is mounted, either through
1265.Xr mount 8
1266for legacy mounts or the
1267.Qq Nm Cm mount
1268command for normal file systems, its mount options are set according to its
1269properties. The correlation between properties and mount options is as follows:
1270.Bl -column -offset 4n "PROPERTY" "MOUNT OPTION"
1271.It PROPERTY MOUNT OPTION
1272.It atime atime/noatime
1273.It exec exec/noexec
1274.It readonly ro/rw
1275.It setuid suid/nosuid
1276.El
1277.Pp
1278In addition, these options can be set on a per-mount basis using the
1279.Fl o
1280option, without affecting the property that is stored on disk. The values
1281specified on the command line override the values stored in the dataset. These
1282properties are reported as "temporary" by the
1283.Qq Nm Cm get
1284command. If the properties are changed while the dataset is mounted, the new
1285setting overrides any temporary settings.
1286.Ss User Properties
1287In addition to the standard native properties,
1288.Tn ZFS
1289supports arbitrary user properties. User properties have no effect on
1290.Tn ZFS
1291behavior, but applications or administrators can use them to annotate datasets
1292(file systems, volumes, and snapshots).
1293.Pp
1294User property names must contain a colon
1295.Pq Sy \&:
1296character to distinguish them from native properties. They may contain
1297lowercase letters, numbers, and the following punctuation characters: colon
1298.Pq Sy \&: ,
1299dash
1300.Pq Sy \&- ,
1301period
1302.Pq Sy \&.
1303and underscore
1304.Pq Sy \&_ .
1305The expected convention is that the property name is divided into two portions
1306such as
1307.Em module Ns Sy \&: Ns Em property ,
1308but this namespace is not enforced by
1309.Tn ZFS .
1310User property names can be at most 256 characters, and cannot begin with a dash
1311.Pq Sy \&- .
1312.Pp
1313When making programmatic use of user properties, it is strongly suggested to
1314use a reversed
1315.Tn DNS
1316domain name for the
1317.Ar module
1318component of property names to reduce the chance that two
1319independently-developed packages use the same property name for different
1320purposes. Property names beginning with
1321.Em com.sun
1322are reserved for use by Sun Microsystems.
1323.Pp
1324The values of user properties are arbitrary strings, are always inherited, and
1325are never validated. All of the commands that operate on properties
1326.Po
1327.Qq Nm Cm list ,
1328.Qq Nm Cm get ,
1329.Qq Nm Cm set
1330and so forth
1331.Pc
1332can be used to manipulate both native properties and user properties. Use the
1333.Qq Nm Cm inherit
1334command to clear a user property. If the property is not defined in any parent
1335dataset, it is removed entirely. Property values are limited to 1024
1336characters.
1337.Sh SUBCOMMANDS
1338All subcommands that modify state are logged persistently to the pool in their
1339original form.
1340.Bl -tag -width 2n
1341.It Xo
1342.Nm
1343.Op Fl \&?
1344.Xc
1345.Pp
1346Displays a help message.
1347.It Xo
1348.Nm
1349.Cm create
1350.Op Fl p
1351.Op Fl o Ar property Ns = Ns Ar value
1352.Ar ... filesystem
1353.Xc
1354.Pp
1355Creates a new
1356.Tn ZFS
1357file system. The file system is automatically mounted according to the
1358.Sy mountpoint
1359property inherited from the parent.
1360.Bl -tag -width indent
1361.It Fl p
1362Creates all the non-existing parent datasets. Datasets created in this manner
1363are automatically mounted according to the
1364.Sy mountpoint
1365property inherited from their parent. Any property specified on the command
1366line using the
1367.Fl o
1368option is ignored. If the target filesystem already exists, the operation
1369completes successfully.
1370.It Fl o Ar property Ns = Ns Ar value
1371Sets the specified property as if the command
1372.Qq Nm Cm set Ar property Ns = Ns Ar value
1373was invoked at the same time the dataset was created. Any editable
1374.Tn ZFS
1375property can also be set at creation time. Multiple
1376.Fl o
1377options can be specified. An error results if the same property is specified in
1378multiple
1379.Fl o
1380options.
1381.El
1382.It Xo
1383.Nm
1384.Cm create
1385.Op Fl ps
1386.Op Fl b Ar blocksize
1387.Op Fl o Ar property Ns = Ns Ar value
1388.Ar ...
1389.Fl V
1390.Ar size volume
1391.Xc
1392.Pp
1393Creates a volume of the given size. The volume is exported as a block device in
1394.Pa /dev/zvol/path ,
1395where
1396.Ar path
1397is the name of the volume in the
1398.Tn ZFS
1399namespace. The size represents the logical size as exported by the device. By
1400default, a reservation of equal size is created.
1401.Pp
1402.Ar size
1403is automatically rounded up to the nearest 128 Kbytes to ensure that
1404the volume has an integral number of blocks regardless of
1405.Ar blocksize .
1406.Bl -tag -width indent
1407.It Fl p
1408Creates all the non-existing parent datasets. Datasets created in this manner
1409are automatically mounted according to the
1410.Sy mountpoint
1411property inherited from their parent. Any property specified on the command
1412line using the
1413.Fl o
1414option is ignored. If the target filesystem already exists, the operation
1415completes successfully.
1416.It Fl s
1417Creates a sparse volume with no reservation. See
1418.Sy volsize
1419in the
1420.Qq Sx Native Properties
1421section for more information about sparse volumes.
1422.It Fl b Ar blocksize
1423Equivalent to
1424.Fl o Cm volblocksize Ns = Ns Ar blocksize .
1425If this option is specified in conjunction with
1426.Fl o Cm volblocksize ,
1427the resulting behavior is undefined.
1428.It Fl o Ar property Ns = Ns Ar value
1429Sets the specified property as if the
1430.Qq Nm Cm set Ar property Ns = Ns Ar value
1431command was invoked at the same time the dataset was created. Any editable
1432.Tn ZFS
1433property can also be set at creation time. Multiple
1434.Fl o
1435options can be specified. An error results if the same property is specified in
1436multiple
1437.Fl o
1438options.
1439.El
1440.It Xo
1441.Nm
1442.Cm destroy
|
1406.Op Fl rRf
| 1443.Op Fl fnpRrv
|
1407.Ar filesystem Ns | Ns Ar volume
1408.Xc
1409.Pp
1410Destroys the given dataset. By default, the command unshares any file systems
1411that are currently shared, unmounts any file systems that are currently
1412mounted, and refuses to destroy a dataset that has active dependents (children
1413or clones).
1414.Bl -tag -width indent
1415.It Fl r
1416Recursively destroy all children.
1417.It Fl R
1418Recursively destroy all dependents, including cloned file systems outside the
1419target hierarchy.
1420.It Fl f
1421Force an unmount of any file systems using the
1422.Qq Nm Cm unmount Fl f
1423command. This option has no effect on non-file systems or unmounted file
1424systems.
| 1444.Ar filesystem Ns | Ns Ar volume
1445.Xc
1446.Pp
1447Destroys the given dataset. By default, the command unshares any file systems
1448that are currently shared, unmounts any file systems that are currently
1449mounted, and refuses to destroy a dataset that has active dependents (children
1450or clones).
1451.Bl -tag -width indent
1452.It Fl r
1453Recursively destroy all children.
1454.It Fl R
1455Recursively destroy all dependents, including cloned file systems outside the
1456target hierarchy.
1457.It Fl f
1458Force an unmount of any file systems using the
1459.Qq Nm Cm unmount Fl f
1460command. This option has no effect on non-file systems or unmounted file
1461systems.
|
| 1462.It Fl n
1463Do a dry-run ("No-op") deletion. No data will be deleted. This is useful in
1464conjunction with the
1465.Fl v
1466or
1467.Fl p
1468flags to determine what data would be deleted.
1469.It Fl p
1470Print machine-parsable verbose information about the deleted data.
1471.It Fl v
1472Print verbose information about the deleted data.
|
1425.El
1426.Pp
1427Extreme care should be taken when applying either the
1428.Fl r
1429or the
1430.Fl R
1431options, as they can destroy large portions of a pool and cause unexpected
1432behavior for mounted file systems in use.
1433.It Xo
1434.Nm
1435.Cm destroy
| 1473.El
1474.Pp
1475Extreme care should be taken when applying either the
1476.Fl r
1477or the
1478.Fl R
1479options, as they can destroy large portions of a pool and cause unexpected
1480behavior for mounted file systems in use.
1481.It Xo
1482.Nm
1483.Cm destroy
|
1436.Op Fl rRd
| 1484.Op Fl dnpRrv
1485.Sm off
|
1437.Ar snapshot
| 1486.Ar snapshot
|
| 1487.Ns Op % Ns Ar snapname
1488.Ns Op , Ns Ar ...
1489.Sm on
|
1438.Xc
1439.Pp
| 1490.Xc
1491.Pp
|
1440The given snapshot is destroyed immediately if and only if the
| 1492The given snapshots are destroyed immediately if and only if the
|
1441.Qq Nm Cm destroy
1442command without the
1443.Fl d
1444option would have destroyed it. Such immediate destruction would occur, for
1445example, if the snapshot had no clones and the user-initiated reference count
1446were zero.
1447.Pp
| 1493.Qq Nm Cm destroy
1494command without the
1495.Fl d
1496option would have destroyed it. Such immediate destruction would occur, for
1497example, if the snapshot had no clones and the user-initiated reference count
1498were zero.
1499.Pp
|
1448If the snapshot does not qualify for immediate destruction, it is marked for
| 1500If a snapshot does not qualify for immediate destruction, it is marked for
|
1449deferred deletion. In this state, it exists as a usable, visible snapshot until
1450both of the preconditions listed above are met, at which point it is destroyed.
| 1501deferred deletion. In this state, it exists as a usable, visible snapshot until
1502both of the preconditions listed above are met, at which point it is destroyed.
|
| 1503.Pp
1504An inclusive range of snapshots may be specified by separating the
1505first and last snapshots with a percent sign
1506.Pq Sy % .
1507The first and/or last snapshots may be left blank, in which case the
1508filesystem's oldest or newest snapshot will be implied.
1509.Pp
1510Multiple snapshots
1511(or ranges of snapshots) of the same filesystem or volume may be specified
1512in a comma-separated list of snapshots.
1513Only the snapshot's short name (the
1514part after the
1515.Sy @ )
1516should be specified when using a range or comma-separated list to identify
1517multiple snapshots.
|
1451.Bl -tag -width indent
1452.It Fl r
1453Destroy (or mark for deferred deletion) all snapshots with this name in
1454descendent file systems.
1455.It Fl R
1456Recursively destroy all dependents.
| 1518.Bl -tag -width indent
1519.It Fl r
1520Destroy (or mark for deferred deletion) all snapshots with this name in
1521descendent file systems.
1522.It Fl R
1523Recursively destroy all dependents.
|
| 1524.It Fl n
1525Do a dry-run ("No-op") deletion. No data will be deleted. This is useful in
1526conjunction with the
1527.Fl v
1528or
1529.Fl p
1530flags to determine what data would be deleted.
1531.It Fl p
1532Print machine-parsable verbose information about the deleted data.
1533.It Fl v
1534Print verbose information about the deleted data.
|
1457.It Fl d
1458Defer snapshot deletion.
1459.El
1460.Pp
1461Extreme care should be taken when applying either the
1462.Fl r
1463or the
1464.Fl R
1465options, as they can destroy large portions of a pool and cause unexpected
1466behavior for mounted file systems in use.
1467.It Xo
1468.Nm
1469.Cm snapshot
1470.Op Fl r
1471.Op Fl o Ar property Ns = Ns Ar value
1472.Ar ...
1473.Ar filesystem@snapname Ns | Ns volume@snapname
1474.Xc
1475.Pp
1476Creates a snapshot with the given name. All previous modifications by
1477successful system calls to the file system are part of the snapshot. See the
1478.Qq Sx Snapshots
1479section for details.
1480.Bl -tag -width indent
1481.It Fl r
1482Recursively create snapshots of all descendent datasets. Snapshots are taken
1483atomically, so that all recursive snapshots correspond to the same moment in
1484time.
1485.It Fl o Ar property Ns = Ns Ar value
1486Sets the specified property; see
1487.Qq Nm Cm create
1488for details.
1489.El
1490.It Xo
1491.Nm
1492.Cm rollback
1493.Op Fl rRf
1494.Ar snapshot
1495.Xc
1496.Pp
1497Roll back the given dataset to a previous snapshot. When a dataset is rolled
1498back, all data that has changed since the snapshot is discarded, and the
1499dataset reverts to the state at the time of the snapshot. By default, the
1500command refuses to roll back to a snapshot other than the most recent one. In
1501order to do so, all intermediate snapshots must be destroyed by specifying the
1502.Fl r
1503option.
1504.Bl -tag -width indent
1505.It Fl r
1506Recursively destroy any snapshots more recent than the one specified.
1507.It Fl R
1508Recursively destroy any more recent snapshots, as well as any clones of those
1509snapshots.
1510.It Fl f
1511Used with the
1512.Fl R
1513option to force an unmount of any clone file systems that are to be destroyed.
1514.El
1515.It Xo
1516.Nm
1517.Cm clone
1518.Op Fl p
1519.Op Fl o Ar property Ns = Ns Ar value
1520.Ar ... snapshot filesystem Ns | Ns Ar volume
1521.Xc
1522.Pp
1523Creates a clone of the given snapshot. See the
1524.Qq Sx Clones
1525section for details. The target dataset can be located anywhere in the
1526.Tn ZFS
1527hierarchy, and is created as the same type as the original.
1528.Bl -tag -width indent
1529.It Fl p
1530Creates all the non-existing parent datasets. Datasets created in this manner
1531are automatically mounted according to the
1532.Sy mountpoint
1533property inherited from their parent. If the target filesystem or volume
1534already exists, the operation completes successfully.
1535.It Fl o Ar property Ns = Ns Ar value
1536Sets the specified property; see
1537.Qq Nm Cm create
1538for details.
1539.El
1540.It Xo
1541.Nm
1542.Cm promote
1543.Ar clone-filesystem
1544.Xc
1545.Pp
1546Promotes a clone file system to no longer be dependent on its "origin"
1547snapshot. This makes it possible to destroy the file system that the clone was
1548created from. The clone parent-child dependency relationship is reversed, so
1549that the origin file system becomes a clone of the specified file system.
1550.Pp
1551The snapshot that was cloned, and any snapshots previous to this snapshot, are
1552now owned by the promoted clone. The space they use moves from the origin file
1553system to the promoted clone, so enough space must be available to accommodate
1554these snapshots. No new space is consumed by this operation, but the space
1555accounting is adjusted. The promoted clone must not have any conflicting
1556snapshot names of its own. The
1557.Cm rename
1558subcommand can be used to rename any conflicting snapshots.
1559.It Xo
1560.Nm
1561.Cm rename
1562.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1563.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1564.Xc
1565.It Xo
1566.Nm
1567.Cm rename
1568.Fl p
1569.Ar filesystem Ns | Ns Ar volume
1570.Ar filesystem Ns | Ns Ar volume
1571.Xc
1572.It Xo
1573.Nm
1574.Cm rename
1575.Fl u
1576.Op Fl p
1577.Ar filesystem filesystem
1578.Xc
1579.Pp
1580Renames the given dataset. The new target can be located anywhere in the
1581.Tn ZFS
1582hierarchy, with the exception of snapshots. Snapshots can only be renamed
1583within the parent file system or volume. When renaming a snapshot, the parent
1584file system of the snapshot does not need to be specified as part of the second
1585argument. Renamed file systems can inherit new mount points, in which case they
1586are unmounted and remounted at the new mount point.
1587.Bl -tag -width indent
1588.It Fl p
1589Creates all the nonexistent parent datasets. Datasets created in this manner
1590are automatically mounted according to the
1591.Sy mountpoint
1592property inherited from their parent.
1593.It Fl u
1594Do not remount file systems during rename. If a file system's
1595.Sy mountpoint
1596property is set to
1597.Cm legacy
1598or
1599.Cm none ,
1600file system is not unmounted even if this option is not given.
1601.El
1602.It Xo
1603.Nm
1604.Cm rename
1605.Fl r
1606.Ar snapshot snapshot
1607.Xc
1608.Pp
1609Recursively rename the snapshots of all descendent datasets. Snapshots are the
1610only dataset that can be renamed recursively.
1611.It Xo
1612.Nm
1613.Cm list
1614.Op Fl r Ns | Ns Fl d Ar depth
1615.Op Fl H
1616.Op Fl o Ar property Ns Op , Ns Ar ...
1617.Op Fl t Ar type Ns Op , Ns Ar ...
1618.Op Fl s Ar property
1619.Ar ...
1620.Op Fl S Ar property
1621.Ar ...
1622.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1623.Xc
1624.Pp
1625Lists the property information for the given datasets in tabular form. If
1626specified, you can list property information by the absolute pathname or the
1627relative pathname. By default, all file systems and volumes are displayed.
1628Snapshots are displayed if the
1629.Sy listsnaps
1630property is
1631.Cm on
1632(the default is
1633.Cm off Ns ).
1634The following fields are displayed,
1635.Sy name , used , available , referenced , mountpoint .
1636.Bl -tag -width indent
1637.It Fl r
1638Recursively display any children of the dataset on the command line.
1639.It Fl d Ar depth
1640Recursively display any children of the dataset, limiting the recursion to
1641.Ar depth .
1642A depth of
1643.Sy 1
1644will display only the dataset and its direct children.
1645.It Fl H
1646Used for scripting mode. Do not print headers and separate fields by a single
1647tab instead of arbitrary white space.
1648.It Fl o Ar property Ns Op , Ns Ar ...
1649A comma-separated list of properties to display. The property must be:
1650.Bl -bullet -offset 2n
1651.It
1652One of the properties described in the
1653.Qq Sx Native Properties
1654section
1655.It
1656A user property
1657.It
1658The value
1659.Cm name
1660to display the dataset name
1661.It
1662The value
1663.Cm space
1664to display space usage properties on file systems and volumes. This is a
1665shortcut for specifying
1666.Fl o
1667.Sy name,avail,used,usedsnap,usedds,usedrefreserv,usedchild
1668.Fl t
1669.Sy filesystem,volume
1670syntax.
1671.El
1672.It Fl t Ar type Ns Op , Ns Ar ...
1673A comma-separated list of types to display, where
1674.Ar type
1675is one of
1676.Sy filesystem , snapshot , volume , No or Sy all .
1677For example, specifying
1678.Fl o Cm snapshot
1679displays only snapshots.
1680.It Fl s Ar property
1681A property for sorting the output by column in ascending order based on the
1682value of the property. The property must be one of the properties described in
1683the
1684.Qq Sx Properties
1685section, or the special value
1686.Cm name
1687to sort by the dataset name. Multiple properties can be specified at one time
1688using multiple
1689.Fl s
1690property options. Multiple
1691.Fl s
1692options are evaluated from left to right in decreasing order of importance.
1693.Pp
1694The following is a list of sorting criteria:
1695.Bl -bullet -offset 2n
1696.It
1697Numeric types sort in numeric order.
1698.It
1699String types sort in alphabetical order.
1700.It
1701Types inappropriate for a row sort that row to the literal bottom, regardless
1702of the specified ordering.
1703.It
1704If no sorting options are specified the existing behavior of
1705.Qq Nm Cm list
1706is preserved.
1707.El
1708.It Fl S Ar property
1709Same as the
1710.Fl s
1711option, but sorts by property in descending order.
1712.El
1713.It Xo
1714.Nm
1715.Cm set
1716.Ar property Ns = Ns Ar value
1717.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1718.Xc
1719.Pp
1720Sets the property to the given value for each dataset. Only some properties can
1721be edited. See the "Properties" section for more information on what properties
1722can be set and acceptable values. Numeric values can be specified as exact
1723values, or in a human-readable form with a suffix of
1724.Sy B , K , M , G , T , P , E , Z
1725(for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or
1726zettabytes, respectively). User properties can be set on snapshots. For more
1727information, see the
1728.Qq Sx User Properties
1729section.
1730.It Xo
1731.Nm
1732.Cm get
1733.Op Fl r Ns | Ns Fl d Ar depth
1734.Op Fl Hp
1735.Op Fl o Ar all | field Ns Op , Ns Ar ...
1736.Op Fl s Ar source Ns Op , Ns Ar ...
1737.Ar all | property Ns Op , Ns Ar ...
1738.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1739.Xc
1740.Pp
1741Displays properties for the given datasets. If no datasets are specified, then
1742the command displays properties for all datasets on the system. For each
1743property, the following columns are displayed:
1744.Pp
1745.Bl -hang -width "property" -offset indent -compact
1746.It name
1747Dataset name
1748.It property
1749Property name
1750.It value
1751Property value
1752.It source
1753Property source. Can either be local, default, temporary, inherited, or none
1754(\&-).
1755.El
1756.Pp
1757All columns except the
1758.Sy RECEIVED
1759column are displayed by default. The columns to display can be specified
1760by using the
1761.Fl o
1762option. This command takes a comma-separated list of properties as described in
1763the
1764.Qq Sx Native Properties
1765and
1766.Qq Sx User Properties
1767sections.
1768.Pp
1769The special value
1770.Cm all
1771can be used to display all properties that apply to the given dataset's type
1772(filesystem, volume, or snapshot).
1773.Bl -tag -width indent
1774.It Fl r
1775Recursively display properties for any children.
1776.It Fl d Ar depth
1777Recursively display any children of the dataset, limiting the recursion to
1778.Ar depth .
1779A depth of
1780.Sy 1
1781will display only the dataset and its direct children.
1782.It Fl H
1783Display output in a form more easily parsed by scripts. Any headers are
1784omitted, and fields are explicitly separated by a single tab instead of an
1785arbitrary amount of space.
1786.It Fl p
1787Display numbers in parseable (exact) values.
1788.It Fl o Cm all | Ar field Ns Op , Ns Ar ...
1789A comma-separated list of columns to display. Supported values are
1790.Sy name,property,value,received,source .
1791Default values are
1792.Sy name,property,value,source .
1793The keyword
1794.Cm all
1795specifies all columns.
1796.It Fl s Ar source Ns Op , Ns Ar ...
1797A comma-separated list of sources to display. Those properties coming from a
1798source other than those in this list are ignored. Each source must be one of
1799the following:
1800.Sy local,default,inherited,temporary,received,none .
1801The default value is all sources.
1802.El
1803.It Xo
1804.Nm
1805.Cm inherit
1806.Op Fl rS
1807.Ar property
1808.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1809.Xc
1810.Pp
1811Clears the specified property, causing it to be inherited from an ancestor. If
1812no ancestor has the property set, then the default value is used. See the
1813.Qq Sx Properties
1814section for a listing of default values, and details on which properties can be
1815inherited.
1816.Bl -tag -width indent
1817.It Fl r
1818Recursively inherit the given property for all children.
1819.It Fl S
1820For properties with a received value, revert to this value. This flag has no
1821effect on properties that do not have a received value.
1822.El
1823.It Xo
1824.Nm
1825.Cm upgrade
1826.Op Fl v
1827.Xc
1828.Pp
1829Displays a list of file systems that are not the most recent version.
1830.Bl -tag -width indent
1831.It Fl v
1832Displays
1833.Tn ZFS
1834filesystem versions supported by the current software. The current
1835.Tn ZFS
1836filesystem version and all previous supported versions are displayed, along
1837with an explanation of the features provided with each version.
1838.El
1839.It Xo
1840.Nm
1841.Cm upgrade
1842.Op Fl r
1843.Op Fl V Ar version
1844.Fl a | Ar filesystem
1845.Xc
1846.Pp
1847Upgrades file systems to a new on-disk version. Once this is done, the file
1848systems will no longer be accessible on systems running older versions of the
1849software.
1850.Qq Nm Cm send
1851streams generated from new snapshots of these file systems cannot be accessed
1852on systems running older versions of the software.
1853.Pp
1854In general, the file system version is independent of the pool version. See
1855.Xr zpool 8
1856for information on the
1857.Nm zpool Cm upgrade
1858command.
1859.Pp
1860In some cases, the file system version and the pool version are interrelated
1861and the pool version must be upgraded before the file system version can be
1862upgraded.
1863.Bl -tag -width indent
1864.It Fl r
1865Upgrade the specified file system and all descendent file systems.
1866.It Fl V Ar version
1867Upgrade to the specified
1868.Ar version .
1869If the
1870.Fl V
1871flag is not specified, this command upgrades to the most recent version. This
1872option can only be used to increase the version number, and only up to the most
1873recent version supported by this software.
1874.It Fl a
1875Upgrade all file systems on all imported pools.
1876.It Ar filesystem
1877Upgrade the specified file system.
1878.El
1879.It Xo
1880.Nm
1881.Cm userspace
1882.Op Fl niHp
1883.Op Fl o Ar field Ns Op , Ns Ar ...
1884.Op Fl sS Ar field
1885.Ar ...
1886.Op Fl t Ar type Ns Op , Ns Ar ...
1887.Ar filesystem Ns | Ns Ar snapshot
1888.Xc
1889.Pp
1890Displays space consumed by, and quotas on, each user in the specified
1891filesystem or snapshot. This corresponds to the
1892.Sy userused@ Ns Ar user
1893and
1894.Sy userquota@ Ns Ar user
1895properties.
1896.Bl -tag -width indent
1897.It Fl n
1898Print numeric ID instead of user/group name.
1899.It Fl H
1900Do not print headers, use tab-delimited output.
1901.It Fl p
1902Use exact (parseable) numeric output.
1903.It Fl o Ar field Ns Op , Ns Ar ...
1904Display only the specified fields from the following set,
1905.Sy type,name,used,quota .
1906The default is to display all fields.
1907.It Fl s Ar field
1908Sort output by this field. The
1909.Fl s
1910and
1911.Fl S
1912flags may be specified multiple times to sort first by one field, then by
1913another. The default is
1914.Fl s Cm type Fl s Cm name .
1915.It Fl S Ar field
1916Sort by this field in reverse order. See
1917.Fl s .
1918.It Fl t Ar type Ns Op , Ns Ar ...
1919Print only the specified types from the following set,
1920.Sy all,posixuser,smbuser,posixgroup,smbgroup .
1921.Pp
1922The default is
1923.Fl t Cm posixuser,smbuser .
1924.Pp
1925The default can be changed to include group types.
1926.It Fl i
1927Translate SID to POSIX ID. This flag has currently no effect on
1928.Fx .
1929.El
1930.It Xo
1931.Nm
1932.Cm groupspace
1933.Op Fl niHp
1934.Op Fl o Ar field Ns Op , Ns Ar ...
1935.Op Fl sS Ar field
1936.Ar ...
1937.Op Fl t Ar type Ns Op , Ns Ar ...
1938.Ar filesystem Ns | Ns Ar snapshot
1939.Xc
1940.Pp
1941Displays space consumed by, and quotas on, each group in the specified
1942filesystem or snapshot. This subcommand is identical to
1943.Qq Nm Cm userspace ,
1944except that the default types to display are
1945.Fl t Sy posixgroup,smbgroup .
1946.It Xo
1947.Nm
1948.Cm mount
1949.Xc
1950.Pp
1951Displays all
1952.Tn ZFS
1953file systems currently mounted.
1954.Bl -tag -width indent
1955.It Fl f
1956.El
1957.It Xo
1958.Nm
1959.Cm mount
1960.Op Fl vO
1961.Op Fl o Ar property Ns Op , Ns Ar ...
1962.Fl a | Ar filesystem
1963.Xc
1964.Pp
1965Mounts
1966.Tn ZFS
1967file systems.
1968.Bl -tag -width indent
1969.It Fl v
1970Report mount progress.
1971.It Fl O
1972Perform an overlay mount. Overlay mounts are not supported on
1973.Fx .
1974.It Fl o Ar property Ns Op , Ns Ar ...
1975An optional, comma-separated list of mount options to use temporarily for the
1976duration of the mount. See the
1977.Qq Sx Temporary Mount Point Properties
1978section for details.
1979.It Fl a
1980Mount all available
1981.Tn ZFS
1982file systems.
1983This command may be executed on
1984.Fx
1985system startup by
1986.Pa /etc/rc.d/zfs .
1987For more information, see variable
1988.Va zfs_enable
1989in
1990.Xr rc.conf 5 .
1991.It Ar filesystem
1992Mount the specified filesystem.
1993.El
1994.It Xo
1995.Nm
1996.Cm unmount
1997.Op Fl f
1998.Fl a | Ar filesystem Ns | Ns Ar mountpoint
1999.Xc
2000.Pp
2001Unmounts currently mounted
2002.Tn ZFS
2003file systems.
2004.Bl -tag -width indent
2005.It Fl f
2006Forcefully unmount the file system, even if it is currently in use.
2007.It Fl a
2008Unmount all available
2009.Tn ZFS
2010file systems.
2011.It Ar filesystem | mountpoint
2012Unmount the specified filesystem. The command can also be given a path to a
2013.Tn ZFS
2014file system mount point on the system.
2015.El
2016.It Xo
2017.Nm
2018.Cm share
2019.Fl a | Ar filesystem
2020.Xc
2021.Pp
2022Shares
2023.Tn ZFS
2024file systems that have the
2025.Sy sharenfs
2026property set.
2027.Bl -tag -width indent
2028.It Fl a
2029Share all
2030.Tn ZFS
2031file systems that have the
2032.Sy sharenfs
2033property set.
2034This command may be executed on
2035.Fx
2036system startup by
2037.Pa /etc/rc.d/zfs .
2038For more information, see variable
2039.Va zfs_enable
2040in
2041.Xr rc.conf 5 .
2042.It Ar filesystem
2043Share the specified filesystem according to the
2044.Tn sharenfs
2045property. File systems are shared when the
2046.Tn sharenfs
2047property is set.
2048.El
2049.It Xo
2050.Nm
2051.Cm unshare
2052.Fl a | Ar filesystem Ns | Ns Ar mountpoint
2053.Xc
2054.Pp
2055Unshares
2056.Tn ZFS
2057file systems that have the
2058.Tn sharenfs
2059property set.
2060.Bl -tag -width indent
2061.It Fl a
2062Unshares
2063.Tn ZFS
2064file systems that have the
2065.Sy sharenfs
2066property set.
2067This command may be executed on
2068.Fx
2069system shutdown by
2070.Pa /etc/rc.d/zfs .
2071For more information, see variable
2072.Va zfs_enable
2073in
2074.Xr rc.conf 5 .
2075.It Ar filesystem | mountpoint
2076Unshare the specified filesystem. The command can also be given a path to a
2077.Tn ZFS
2078file system shared on the system.
2079.El
2080.It Xo
2081.Nm
2082.Cm send
| 1535.It Fl d
1536Defer snapshot deletion.
1537.El
1538.Pp
1539Extreme care should be taken when applying either the
1540.Fl r
1541or the
1542.Fl R
1543options, as they can destroy large portions of a pool and cause unexpected
1544behavior for mounted file systems in use.
1545.It Xo
1546.Nm
1547.Cm snapshot
1548.Op Fl r
1549.Op Fl o Ar property Ns = Ns Ar value
1550.Ar ...
1551.Ar filesystem@snapname Ns | Ns volume@snapname
1552.Xc
1553.Pp
1554Creates a snapshot with the given name. All previous modifications by
1555successful system calls to the file system are part of the snapshot. See the
1556.Qq Sx Snapshots
1557section for details.
1558.Bl -tag -width indent
1559.It Fl r
1560Recursively create snapshots of all descendent datasets. Snapshots are taken
1561atomically, so that all recursive snapshots correspond to the same moment in
1562time.
1563.It Fl o Ar property Ns = Ns Ar value
1564Sets the specified property; see
1565.Qq Nm Cm create
1566for details.
1567.El
1568.It Xo
1569.Nm
1570.Cm rollback
1571.Op Fl rRf
1572.Ar snapshot
1573.Xc
1574.Pp
1575Roll back the given dataset to a previous snapshot. When a dataset is rolled
1576back, all data that has changed since the snapshot is discarded, and the
1577dataset reverts to the state at the time of the snapshot. By default, the
1578command refuses to roll back to a snapshot other than the most recent one. In
1579order to do so, all intermediate snapshots must be destroyed by specifying the
1580.Fl r
1581option.
1582.Bl -tag -width indent
1583.It Fl r
1584Recursively destroy any snapshots more recent than the one specified.
1585.It Fl R
1586Recursively destroy any more recent snapshots, as well as any clones of those
1587snapshots.
1588.It Fl f
1589Used with the
1590.Fl R
1591option to force an unmount of any clone file systems that are to be destroyed.
1592.El
1593.It Xo
1594.Nm
1595.Cm clone
1596.Op Fl p
1597.Op Fl o Ar property Ns = Ns Ar value
1598.Ar ... snapshot filesystem Ns | Ns Ar volume
1599.Xc
1600.Pp
1601Creates a clone of the given snapshot. See the
1602.Qq Sx Clones
1603section for details. The target dataset can be located anywhere in the
1604.Tn ZFS
1605hierarchy, and is created as the same type as the original.
1606.Bl -tag -width indent
1607.It Fl p
1608Creates all the non-existing parent datasets. Datasets created in this manner
1609are automatically mounted according to the
1610.Sy mountpoint
1611property inherited from their parent. If the target filesystem or volume
1612already exists, the operation completes successfully.
1613.It Fl o Ar property Ns = Ns Ar value
1614Sets the specified property; see
1615.Qq Nm Cm create
1616for details.
1617.El
1618.It Xo
1619.Nm
1620.Cm promote
1621.Ar clone-filesystem
1622.Xc
1623.Pp
1624Promotes a clone file system to no longer be dependent on its "origin"
1625snapshot. This makes it possible to destroy the file system that the clone was
1626created from. The clone parent-child dependency relationship is reversed, so
1627that the origin file system becomes a clone of the specified file system.
1628.Pp
1629The snapshot that was cloned, and any snapshots previous to this snapshot, are
1630now owned by the promoted clone. The space they use moves from the origin file
1631system to the promoted clone, so enough space must be available to accommodate
1632these snapshots. No new space is consumed by this operation, but the space
1633accounting is adjusted. The promoted clone must not have any conflicting
1634snapshot names of its own. The
1635.Cm rename
1636subcommand can be used to rename any conflicting snapshots.
1637.It Xo
1638.Nm
1639.Cm rename
1640.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1641.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1642.Xc
1643.It Xo
1644.Nm
1645.Cm rename
1646.Fl p
1647.Ar filesystem Ns | Ns Ar volume
1648.Ar filesystem Ns | Ns Ar volume
1649.Xc
1650.It Xo
1651.Nm
1652.Cm rename
1653.Fl u
1654.Op Fl p
1655.Ar filesystem filesystem
1656.Xc
1657.Pp
1658Renames the given dataset. The new target can be located anywhere in the
1659.Tn ZFS
1660hierarchy, with the exception of snapshots. Snapshots can only be renamed
1661within the parent file system or volume. When renaming a snapshot, the parent
1662file system of the snapshot does not need to be specified as part of the second
1663argument. Renamed file systems can inherit new mount points, in which case they
1664are unmounted and remounted at the new mount point.
1665.Bl -tag -width indent
1666.It Fl p
1667Creates all the nonexistent parent datasets. Datasets created in this manner
1668are automatically mounted according to the
1669.Sy mountpoint
1670property inherited from their parent.
1671.It Fl u
1672Do not remount file systems during rename. If a file system's
1673.Sy mountpoint
1674property is set to
1675.Cm legacy
1676or
1677.Cm none ,
1678file system is not unmounted even if this option is not given.
1679.El
1680.It Xo
1681.Nm
1682.Cm rename
1683.Fl r
1684.Ar snapshot snapshot
1685.Xc
1686.Pp
1687Recursively rename the snapshots of all descendent datasets. Snapshots are the
1688only dataset that can be renamed recursively.
1689.It Xo
1690.Nm
1691.Cm list
1692.Op Fl r Ns | Ns Fl d Ar depth
1693.Op Fl H
1694.Op Fl o Ar property Ns Op , Ns Ar ...
1695.Op Fl t Ar type Ns Op , Ns Ar ...
1696.Op Fl s Ar property
1697.Ar ...
1698.Op Fl S Ar property
1699.Ar ...
1700.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1701.Xc
1702.Pp
1703Lists the property information for the given datasets in tabular form. If
1704specified, you can list property information by the absolute pathname or the
1705relative pathname. By default, all file systems and volumes are displayed.
1706Snapshots are displayed if the
1707.Sy listsnaps
1708property is
1709.Cm on
1710(the default is
1711.Cm off Ns ).
1712The following fields are displayed,
1713.Sy name , used , available , referenced , mountpoint .
1714.Bl -tag -width indent
1715.It Fl r
1716Recursively display any children of the dataset on the command line.
1717.It Fl d Ar depth
1718Recursively display any children of the dataset, limiting the recursion to
1719.Ar depth .
1720A depth of
1721.Sy 1
1722will display only the dataset and its direct children.
1723.It Fl H
1724Used for scripting mode. Do not print headers and separate fields by a single
1725tab instead of arbitrary white space.
1726.It Fl o Ar property Ns Op , Ns Ar ...
1727A comma-separated list of properties to display. The property must be:
1728.Bl -bullet -offset 2n
1729.It
1730One of the properties described in the
1731.Qq Sx Native Properties
1732section
1733.It
1734A user property
1735.It
1736The value
1737.Cm name
1738to display the dataset name
1739.It
1740The value
1741.Cm space
1742to display space usage properties on file systems and volumes. This is a
1743shortcut for specifying
1744.Fl o
1745.Sy name,avail,used,usedsnap,usedds,usedrefreserv,usedchild
1746.Fl t
1747.Sy filesystem,volume
1748syntax.
1749.El
1750.It Fl t Ar type Ns Op , Ns Ar ...
1751A comma-separated list of types to display, where
1752.Ar type
1753is one of
1754.Sy filesystem , snapshot , volume , No or Sy all .
1755For example, specifying
1756.Fl o Cm snapshot
1757displays only snapshots.
1758.It Fl s Ar property
1759A property for sorting the output by column in ascending order based on the
1760value of the property. The property must be one of the properties described in
1761the
1762.Qq Sx Properties
1763section, or the special value
1764.Cm name
1765to sort by the dataset name. Multiple properties can be specified at one time
1766using multiple
1767.Fl s
1768property options. Multiple
1769.Fl s
1770options are evaluated from left to right in decreasing order of importance.
1771.Pp
1772The following is a list of sorting criteria:
1773.Bl -bullet -offset 2n
1774.It
1775Numeric types sort in numeric order.
1776.It
1777String types sort in alphabetical order.
1778.It
1779Types inappropriate for a row sort that row to the literal bottom, regardless
1780of the specified ordering.
1781.It
1782If no sorting options are specified the existing behavior of
1783.Qq Nm Cm list
1784is preserved.
1785.El
1786.It Fl S Ar property
1787Same as the
1788.Fl s
1789option, but sorts by property in descending order.
1790.El
1791.It Xo
1792.Nm
1793.Cm set
1794.Ar property Ns = Ns Ar value
1795.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1796.Xc
1797.Pp
1798Sets the property to the given value for each dataset. Only some properties can
1799be edited. See the "Properties" section for more information on what properties
1800can be set and acceptable values. Numeric values can be specified as exact
1801values, or in a human-readable form with a suffix of
1802.Sy B , K , M , G , T , P , E , Z
1803(for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or
1804zettabytes, respectively). User properties can be set on snapshots. For more
1805information, see the
1806.Qq Sx User Properties
1807section.
1808.It Xo
1809.Nm
1810.Cm get
1811.Op Fl r Ns | Ns Fl d Ar depth
1812.Op Fl Hp
1813.Op Fl o Ar all | field Ns Op , Ns Ar ...
1814.Op Fl s Ar source Ns Op , Ns Ar ...
1815.Ar all | property Ns Op , Ns Ar ...
1816.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1817.Xc
1818.Pp
1819Displays properties for the given datasets. If no datasets are specified, then
1820the command displays properties for all datasets on the system. For each
1821property, the following columns are displayed:
1822.Pp
1823.Bl -hang -width "property" -offset indent -compact
1824.It name
1825Dataset name
1826.It property
1827Property name
1828.It value
1829Property value
1830.It source
1831Property source. Can either be local, default, temporary, inherited, or none
1832(\&-).
1833.El
1834.Pp
1835All columns except the
1836.Sy RECEIVED
1837column are displayed by default. The columns to display can be specified
1838by using the
1839.Fl o
1840option. This command takes a comma-separated list of properties as described in
1841the
1842.Qq Sx Native Properties
1843and
1844.Qq Sx User Properties
1845sections.
1846.Pp
1847The special value
1848.Cm all
1849can be used to display all properties that apply to the given dataset's type
1850(filesystem, volume, or snapshot).
1851.Bl -tag -width indent
1852.It Fl r
1853Recursively display properties for any children.
1854.It Fl d Ar depth
1855Recursively display any children of the dataset, limiting the recursion to
1856.Ar depth .
1857A depth of
1858.Sy 1
1859will display only the dataset and its direct children.
1860.It Fl H
1861Display output in a form more easily parsed by scripts. Any headers are
1862omitted, and fields are explicitly separated by a single tab instead of an
1863arbitrary amount of space.
1864.It Fl p
1865Display numbers in parseable (exact) values.
1866.It Fl o Cm all | Ar field Ns Op , Ns Ar ...
1867A comma-separated list of columns to display. Supported values are
1868.Sy name,property,value,received,source .
1869Default values are
1870.Sy name,property,value,source .
1871The keyword
1872.Cm all
1873specifies all columns.
1874.It Fl s Ar source Ns Op , Ns Ar ...
1875A comma-separated list of sources to display. Those properties coming from a
1876source other than those in this list are ignored. Each source must be one of
1877the following:
1878.Sy local,default,inherited,temporary,received,none .
1879The default value is all sources.
1880.El
1881.It Xo
1882.Nm
1883.Cm inherit
1884.Op Fl rS
1885.Ar property
1886.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1887.Xc
1888.Pp
1889Clears the specified property, causing it to be inherited from an ancestor. If
1890no ancestor has the property set, then the default value is used. See the
1891.Qq Sx Properties
1892section for a listing of default values, and details on which properties can be
1893inherited.
1894.Bl -tag -width indent
1895.It Fl r
1896Recursively inherit the given property for all children.
1897.It Fl S
1898For properties with a received value, revert to this value. This flag has no
1899effect on properties that do not have a received value.
1900.El
1901.It Xo
1902.Nm
1903.Cm upgrade
1904.Op Fl v
1905.Xc
1906.Pp
1907Displays a list of file systems that are not the most recent version.
1908.Bl -tag -width indent
1909.It Fl v
1910Displays
1911.Tn ZFS
1912filesystem versions supported by the current software. The current
1913.Tn ZFS
1914filesystem version and all previous supported versions are displayed, along
1915with an explanation of the features provided with each version.
1916.El
1917.It Xo
1918.Nm
1919.Cm upgrade
1920.Op Fl r
1921.Op Fl V Ar version
1922.Fl a | Ar filesystem
1923.Xc
1924.Pp
1925Upgrades file systems to a new on-disk version. Once this is done, the file
1926systems will no longer be accessible on systems running older versions of the
1927software.
1928.Qq Nm Cm send
1929streams generated from new snapshots of these file systems cannot be accessed
1930on systems running older versions of the software.
1931.Pp
1932In general, the file system version is independent of the pool version. See
1933.Xr zpool 8
1934for information on the
1935.Nm zpool Cm upgrade
1936command.
1937.Pp
1938In some cases, the file system version and the pool version are interrelated
1939and the pool version must be upgraded before the file system version can be
1940upgraded.
1941.Bl -tag -width indent
1942.It Fl r
1943Upgrade the specified file system and all descendent file systems.
1944.It Fl V Ar version
1945Upgrade to the specified
1946.Ar version .
1947If the
1948.Fl V
1949flag is not specified, this command upgrades to the most recent version. This
1950option can only be used to increase the version number, and only up to the most
1951recent version supported by this software.
1952.It Fl a
1953Upgrade all file systems on all imported pools.
1954.It Ar filesystem
1955Upgrade the specified file system.
1956.El
1957.It Xo
1958.Nm
1959.Cm userspace
1960.Op Fl niHp
1961.Op Fl o Ar field Ns Op , Ns Ar ...
1962.Op Fl sS Ar field
1963.Ar ...
1964.Op Fl t Ar type Ns Op , Ns Ar ...
1965.Ar filesystem Ns | Ns Ar snapshot
1966.Xc
1967.Pp
1968Displays space consumed by, and quotas on, each user in the specified
1969filesystem or snapshot. This corresponds to the
1970.Sy userused@ Ns Ar user
1971and
1972.Sy userquota@ Ns Ar user
1973properties.
1974.Bl -tag -width indent
1975.It Fl n
1976Print numeric ID instead of user/group name.
1977.It Fl H
1978Do not print headers, use tab-delimited output.
1979.It Fl p
1980Use exact (parseable) numeric output.
1981.It Fl o Ar field Ns Op , Ns Ar ...
1982Display only the specified fields from the following set,
1983.Sy type,name,used,quota .
1984The default is to display all fields.
1985.It Fl s Ar field
1986Sort output by this field. The
1987.Fl s
1988and
1989.Fl S
1990flags may be specified multiple times to sort first by one field, then by
1991another. The default is
1992.Fl s Cm type Fl s Cm name .
1993.It Fl S Ar field
1994Sort by this field in reverse order. See
1995.Fl s .
1996.It Fl t Ar type Ns Op , Ns Ar ...
1997Print only the specified types from the following set,
1998.Sy all,posixuser,smbuser,posixgroup,smbgroup .
1999.Pp
2000The default is
2001.Fl t Cm posixuser,smbuser .
2002.Pp
2003The default can be changed to include group types.
2004.It Fl i
2005Translate SID to POSIX ID. This flag has currently no effect on
2006.Fx .
2007.El
2008.It Xo
2009.Nm
2010.Cm groupspace
2011.Op Fl niHp
2012.Op Fl o Ar field Ns Op , Ns Ar ...
2013.Op Fl sS Ar field
2014.Ar ...
2015.Op Fl t Ar type Ns Op , Ns Ar ...
2016.Ar filesystem Ns | Ns Ar snapshot
2017.Xc
2018.Pp
2019Displays space consumed by, and quotas on, each group in the specified
2020filesystem or snapshot. This subcommand is identical to
2021.Qq Nm Cm userspace ,
2022except that the default types to display are
2023.Fl t Sy posixgroup,smbgroup .
2024.It Xo
2025.Nm
2026.Cm mount
2027.Xc
2028.Pp
2029Displays all
2030.Tn ZFS
2031file systems currently mounted.
2032.Bl -tag -width indent
2033.It Fl f
2034.El
2035.It Xo
2036.Nm
2037.Cm mount
2038.Op Fl vO
2039.Op Fl o Ar property Ns Op , Ns Ar ...
2040.Fl a | Ar filesystem
2041.Xc
2042.Pp
2043Mounts
2044.Tn ZFS
2045file systems.
2046.Bl -tag -width indent
2047.It Fl v
2048Report mount progress.
2049.It Fl O
2050Perform an overlay mount. Overlay mounts are not supported on
2051.Fx .
2052.It Fl o Ar property Ns Op , Ns Ar ...
2053An optional, comma-separated list of mount options to use temporarily for the
2054duration of the mount. See the
2055.Qq Sx Temporary Mount Point Properties
2056section for details.
2057.It Fl a
2058Mount all available
2059.Tn ZFS
2060file systems.
2061This command may be executed on
2062.Fx
2063system startup by
2064.Pa /etc/rc.d/zfs .
2065For more information, see variable
2066.Va zfs_enable
2067in
2068.Xr rc.conf 5 .
2069.It Ar filesystem
2070Mount the specified filesystem.
2071.El
2072.It Xo
2073.Nm
2074.Cm unmount
2075.Op Fl f
2076.Fl a | Ar filesystem Ns | Ns Ar mountpoint
2077.Xc
2078.Pp
2079Unmounts currently mounted
2080.Tn ZFS
2081file systems.
2082.Bl -tag -width indent
2083.It Fl f
2084Forcefully unmount the file system, even if it is currently in use.
2085.It Fl a
2086Unmount all available
2087.Tn ZFS
2088file systems.
2089.It Ar filesystem | mountpoint
2090Unmount the specified filesystem. The command can also be given a path to a
2091.Tn ZFS
2092file system mount point on the system.
2093.El
2094.It Xo
2095.Nm
2096.Cm share
2097.Fl a | Ar filesystem
2098.Xc
2099.Pp
2100Shares
2101.Tn ZFS
2102file systems that have the
2103.Sy sharenfs
2104property set.
2105.Bl -tag -width indent
2106.It Fl a
2107Share all
2108.Tn ZFS
2109file systems that have the
2110.Sy sharenfs
2111property set.
2112This command may be executed on
2113.Fx
2114system startup by
2115.Pa /etc/rc.d/zfs .
2116For more information, see variable
2117.Va zfs_enable
2118in
2119.Xr rc.conf 5 .
2120.It Ar filesystem
2121Share the specified filesystem according to the
2122.Tn sharenfs
2123property. File systems are shared when the
2124.Tn sharenfs
2125property is set.
2126.El
2127.It Xo
2128.Nm
2129.Cm unshare
2130.Fl a | Ar filesystem Ns | Ns Ar mountpoint
2131.Xc
2132.Pp
2133Unshares
2134.Tn ZFS
2135file systems that have the
2136.Tn sharenfs
2137property set.
2138.Bl -tag -width indent
2139.It Fl a
2140Unshares
2141.Tn ZFS
2142file systems that have the
2143.Sy sharenfs
2144property set.
2145This command may be executed on
2146.Fx
2147system shutdown by
2148.Pa /etc/rc.d/zfs .
2149For more information, see variable
2150.Va zfs_enable
2151in
2152.Xr rc.conf 5 .
2153.It Ar filesystem | mountpoint
2154Unshare the specified filesystem. The command can also be given a path to a
2155.Tn ZFS
2156file system shared on the system.
2157.El
2158.It Xo
2159.Nm
2160.Cm send
|
2083.Op Fl DvRp
| 2161.Op Fl DnPpRrv
|
2084.Op Fl i Ar snapshot | Fl I Ar snapshot
2085.Ar snapshot
2086.Xc
2087.Pp
2088Creates a stream representation of the last
2089.Ar snapshot
2090argument (not part of
2091.Fl i
2092or
2093.Fl I Ns )
2094which is written to standard output. The output can be redirected to
2095a file or to a different system (for example, using
2096.Xr ssh 1 Ns ).
2097By default, a full stream is generated.
2098.Bl -tag -width indent
2099.It Fl i Ar snapshot
2100Generate an incremental stream from the
2101.Fl i Ar snapshot
2102to the last
2103.Ar snapshot .
2104The incremental source (the
2105.Fl i Ar snapshot Ns )
2106can be specified as the last component of the snapshot name (for example, the
2107part after the
2108.Sy @ Ns ),
2109and it is assumed to be from the same file system as the last
2110.Ar snapshot .
2111.Pp
2112If the destination is a clone, the source may be the origin snapshot, which
2113must be fully specified (for example,
2114.Cm pool/fs@origin ,
2115not just
2116.Cm @origin Ns ).
2117.It Fl I Ar snapshot
2118Generate a stream package that sends all intermediary snapshots from the
2119.Fl I Ar snapshot to the last
2120.Ar snapshot . For example,
2121.Ic -I @a fs@d
2122is similar to
2123.Ic -i @a fs@b; -i @b fs@c; -i @c fs@d Ns .
2124The incremental source snapshot may be specified as with the
2125.Fl i
2126option.
2127.It Fl R
2128Generate a replication stream package, which will replicate the specified
2129filesystem, and all descendent file systems, up to the named snapshot. When
2130received, all properties, snapshots, descendent file systems, and clones are
2131preserved.
2132.Pp
2133If the
2134.Fl i
2135or
2136.Fl I
2137flags are used in conjunction with the
2138.Fl R
2139flag, an incremental replication stream is generated. The current values of
2140properties, and current snapshot and file system names are set when the stream
2141is received. If the
2142.Fl F
2143flag is specified when this stream is received, snapshots and file systems that
2144 do not exist on the sending side are destroyed.
2145.It Fl D
2146Generate a deduplicated stream. Blocks which would have been sent multiple
2147times in the send stream will only be sent once. The receiving system must
2148also support this feature to recieve a deduplicated stream. This flag can
2149be used regardless of the dataset's
2150.Sy dedup
2151property, but performance will be much better if the filesystem uses a
2152dedup-capable checksum (eg.
2153.Sy sha256 Ns ).
| 2162.Op Fl i Ar snapshot | Fl I Ar snapshot
2163.Ar snapshot
2164.Xc
2165.Pp
2166Creates a stream representation of the last
2167.Ar snapshot
2168argument (not part of
2169.Fl i
2170or
2171.Fl I Ns )
2172which is written to standard output. The output can be redirected to
2173a file or to a different system (for example, using
2174.Xr ssh 1 Ns ).
2175By default, a full stream is generated.
2176.Bl -tag -width indent
2177.It Fl i Ar snapshot
2178Generate an incremental stream from the
2179.Fl i Ar snapshot
2180to the last
2181.Ar snapshot .
2182The incremental source (the
2183.Fl i Ar snapshot Ns )
2184can be specified as the last component of the snapshot name (for example, the
2185part after the
2186.Sy @ Ns ),
2187and it is assumed to be from the same file system as the last
2188.Ar snapshot .
2189.Pp
2190If the destination is a clone, the source may be the origin snapshot, which
2191must be fully specified (for example,
2192.Cm pool/fs@origin ,
2193not just
2194.Cm @origin Ns ).
2195.It Fl I Ar snapshot
2196Generate a stream package that sends all intermediary snapshots from the
2197.Fl I Ar snapshot to the last
2198.Ar snapshot . For example,
2199.Ic -I @a fs@d
2200is similar to
2201.Ic -i @a fs@b; -i @b fs@c; -i @c fs@d Ns .
2202The incremental source snapshot may be specified as with the
2203.Fl i
2204option.
2205.It Fl R
2206Generate a replication stream package, which will replicate the specified
2207filesystem, and all descendent file systems, up to the named snapshot. When
2208received, all properties, snapshots, descendent file systems, and clones are
2209preserved.
2210.Pp
2211If the
2212.Fl i
2213or
2214.Fl I
2215flags are used in conjunction with the
2216.Fl R
2217flag, an incremental replication stream is generated. The current values of
2218properties, and current snapshot and file system names are set when the stream
2219is received. If the
2220.Fl F
2221flag is specified when this stream is received, snapshots and file systems that
2222 do not exist on the sending side are destroyed.
2223.It Fl D
2224Generate a deduplicated stream. Blocks which would have been sent multiple
2225times in the send stream will only be sent once. The receiving system must
2226also support this feature to recieve a deduplicated stream. This flag can
2227be used regardless of the dataset's
2228.Sy dedup
2229property, but performance will be much better if the filesystem uses a
2230dedup-capable checksum (eg.
2231.Sy sha256 Ns ).
|
| 2232.It Fl r
2233Recursively send all descendant snapshots. This is similar to the
2234.Fl R
2235flag, but information about deleted and renamed datasets is not included, and
2236property information is only included if the
2237.Fl p
2238flag is specified.
|
2154.It Fl p
2155Include the dataset's properties in the stream. This flag is implicit when
2156.Fl R
2157is specified. The receiving system must also support this feature.
| 2239.It Fl p
2240Include the dataset's properties in the stream. This flag is implicit when
2241.Fl R
2242is specified. The receiving system must also support this feature.
|
| 2243.It Fl n
2244Do a dry-run ("No-op") send. Do not generate any actual send data. This is
2245useful in conjunction with the
2246.Fl v
2247or
2248.Fl P
2249flags to determine what data will be sent.
2250.It Fl P
2251Print machine-parsable verbose information about the stream package generated.
|
2158.It Fl v
2159Print verbose information about the stream package generated.
2160.El
2161.Pp
2162The format of the stream is committed. You will be able to receive your streams
2163on future versions of
2164.Tn ZFS .
2165.It Xo
2166.Nm
2167.Cm receive
2168.Op Fl vnFu
2169.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2170.Xc
2171.It Xo
2172.Nm
2173.Cm receive
2174.Op Fl vnFu
2175.Op Fl d | e
2176.Ar filesystem
2177.Xc
2178.Pp
2179Creates a snapshot whose contents are as specified in the stream provided on
2180standard input. If a full stream is received, then a new file system is created
2181as well. Streams are created using the
2182.Qq Nm Cm send
2183subcommand, which by default creates a full stream.
2184.Qq Nm Cm recv
2185can be used as an alias for
2186.Qq Nm Cm receive .
2187.Pp
2188If an incremental stream is received, then the destination file system must
2189already exist, and its most recent snapshot must match the incremental stream's
2190source. For
2191.Sy zvol Ns s,
2192the destination device link is destroyed and recreated, which means the
2193.Sy zvol
2194cannot be accessed during the
2195.Sy receive
2196operation.
2197.Pp
2198When a snapshot replication package stream that is generated by using the
2199.Qq Nm Cm send Fl R
2200command is received, any snapshots that do not exist on the sending location
2201are destroyed by using the
2202.Qq Nm Cm destroy Fl d
2203command.
2204.Pp
2205The name of the snapshot (and file system, if a full stream is received) that
2206this subcommand creates depends on the argument type and the
2207.Fl d
2208or
2209.Fl e
2210option.
2211.Pp
2212If the argument is a snapshot name, the specified
2213.Ar snapshot
2214is created. If the argument is a file system or volume name, a snapshot with
2215the same name as the sent snapshot is created within the specified
2216.Ar filesystem
2217or
2218.Ar volume .
2219If the
2220.Fl d
2221or
2222.Fl e
2223option is specified, the snapshot name is determined by appending the sent
2224snapshot's name to the specified
2225.Ar filesystem .
2226If the
2227.Fl d
2228option is specified, all but the pool name of the sent snapshot path is
2229appended (for example,
2230.Sy b/c@1
2231appended from sent snapshot
2232.Sy a/b/c@1 Ns ),
2233and if the
2234.Fl e
2235option is specified, only the tail of the sent snapshot path is appended (for
2236example,
2237.Sy c@1
2238appended from sent snapshot
2239.Sy a/b/c@1 Ns ).
2240In the case of
2241.Fl d ,
2242any file systems needed to replicate the path of the sent snapshot are created
2243within the specified file system.
2244.Bl -tag -width indent
2245.It Fl d
2246Use the full sent snapshot path without the first element (without pool name)
2247to determine the name of the new snapshot as described in the paragraph above.
2248.It Fl e
2249Use only the last element of the sent snapshot path to determine the name of
2250the new snapshot as described in the paragraph above.
2251.It Fl u
2252File system that is associated with the received stream is not mounted.
2253.It Fl v
2254Print verbose information about the stream and the time required to perform the
2255receive operation.
2256.It Fl n
2257Do not actually receive the stream. This can be useful in conjunction with the
2258.It Fl v
2259option to verify the name the receive operation would use.
2260.It Fl F
2261Force a rollback of the file system to the most recent snapshot before
2262performing the receive operation. If receiving an incremental replication
2263stream (for example, one generated by
2264.Qq Nm Cm send Fl R Fi iI Ns ) ,
2265destroy snapshots and file systems that do not exist on the sending side.
2266.El
2267.It Xo
2268.Nm
2269.Cm allow
2270.Ar filesystem Ns | Ns Ar volume
2271.Xc
2272.Pp
2273Displays permissions that have been delegated on the specified filesystem or
2274volume. See the other forms of
2275.Qq Nm Cm allow
2276for more information.
2277.It Xo
2278.Nm
2279.Cm allow
2280.Op Fl ldug
2281.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2282.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2283.Ar filesystem Ns | Ns Ar volume
2284.Xc
2285.It Xo
2286.Nm
2287.Cm allow
2288.Op Fl ld
2289.Fl e
2290.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2291.Ar filesystem Ns | Ns Ar volume
2292.Xc
2293.Pp
2294Delegates
2295.Tn ZFS
2296administration permission for the file systems to non-privileged users.
2297.Bl -tag -width indent
2298.It Xo
2299.Op Fl ug
2300.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2301.Xc
2302Specifies to whom the permissions are delegated. Multiple entities can be
2303specified as a comma-separated list. If neither of the
2304.Fl ug
2305options are specified, then the argument is interpreted preferentially as the
2306keyword "everyone", then as a user name, and lastly as a group name. To specify
2307a user or group named "everyone", use the
2308.Fl u
2309or
2310.Fl g
2311options. To specify a group with the same name as a user, use the
2312.Fl g
2313option.
2314.It Xo
2315.Op Fl e
2316.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2317.Xc
2318Specifies that the permissions be delegated to "everyone." Multiple permissions
2319may be specified as a comma-separated list. Permission names are the same as
2320.Tn ZFS
2321subcommand and property names. See the property list below. Property set names,
2322which begin with an at sign
2323.Pq Sy @ Ns ,
2324may be specified. See the
2325.Fl s
2326form below for details.
2327.It Xo
2328.Op Fl ld
2329.Ar filesystem Ns | Ns Ar volume
2330.Xc
2331Specifies where the permissions are delegated. If neither of the
2332.Fl ld
2333options are specified, or both are, then the permissions are allowed for the
2334file system or volume, and all of its descendents. If only the
2335.Fl l
2336option is used, then is allowed "locally" only for the specified file system.
2337If only the
2338.Fl d
2339option is used, then is allowed only for the descendent file systems.
2340.El
2341.Pp
2342Permissions are generally the ability to use a
2343.Tn ZFS
2344subcommand or change a
2345.Tn ZFS
2346property. The following permissions are available:
2347.Bl -column -offset 4n "secondarycache" "subcommand"
2348.It NAME Ta TYPE Ta NOTES
2349.It Xo allow Ta subcommand Ta Must
2350also have the permission that is being allowed
2351.Xc
2352.It Xo clone Ta subcommand Ta Must
2353also have the 'create' ability and 'mount' ability in the origin file system
2354.Xc
2355.It create Ta subcommand Ta Must also have the 'mount' ability
2356.It destroy Ta subcommand Ta Must also have the 'mount' ability
2357.It hold Ta subcommand Ta Allows adding a user hold to a snapshot
2358.It mount Ta subcommand Ta Allows mount/umount of Tn ZFS No datasets
2359.It Xo promote Ta subcommand Ta Must
2360also have the 'mount' and 'promote' ability in the origin file system
2361.Xc
2362.It receive Ta subcommand Ta Must also have the 'mount' and 'create' ability
2363.It Xo release Ta subcommand Ta Allows
2364releasing a user hold which might destroy the snapshot
2365.Xc
2366.It Xo rename Ta subcommand Ta Must
2367also have the 'mount' and 'create' ability in the new parent
2368.Xc
2369.It rollback Ta subcommand Ta Must also have the 'mount' ability
2370.It send Ta subcommand
2371.It share Ta subcommand Ta Allows Xo
2372sharing file systems over the
2373.Tn NFS
2374protocol
2375.Xc
2376.It snapshot Ta subcommand Ta Must also have the 'mount' ability
2377.It groupquota Ta other Ta Allows accessing any groupquota@... property
2378.It groupused Ta other Ta Allows reading any groupused@... property
2379.It userprop Ta other Ta Allows changing any user property
2380.It userquota Ta other Ta Allows accessing any userquota@... property
2381.It userused Ta other Ta Allows reading any userused@... property
2382.It Ta
2383.It aclinherit Ta property
2384.It aclmode Ta property
2385.It atime Ta property
2386.It canmount Ta property
2387.It casesensitivity Ta property
2388.It checksum Ta property
2389.It compression Ta property
2390.It copies Ta property
2391.It dedup Ta property
2392.It devices Ta property
2393.It exec Ta property
2394.It logbias Ta property
2395.It jailed Ta property
2396.It mlslabel Ta property
2397.It mountpoint Ta property
2398.It nbmand Ta property
2399.It normalization Ta property
2400.It primarycache Ta property
2401.It quota Ta property
2402.It readonly Ta property
2403.It recordsize Ta property
2404.It refquota Ta property
2405.It refreservation Ta property
2406.It reservation Ta property
2407.It secondarycache Ta property
2408.It setuid Ta property
2409.It sharenfs Ta property
2410.It sharesmb Ta property
2411.It snapdir Ta property
2412.It sync Ta property
2413.It utf8only Ta property
2414.It version Ta property
2415.It volblocksize Ta property
2416.It volsize Ta property
2417.It vscan Ta property
2418.It xattr Ta property
2419.El
2420.It Xo
2421.Nm
2422.Cm allow
2423.Fl c
2424.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2425.Ar filesystem Ns | Ns Ar volume
2426.Xc
2427.Pp
2428Sets "create time" permissions. These permissions are granted (locally) to the
2429creator of any newly-created descendent file system.
2430.It Xo
2431.Nm
2432.Cm allow
2433.Fl s
2434.Ar @setname
2435.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2436.Ar filesystem Ns | Ns Ar volume
2437.Xc
2438.Pp
2439Defines or adds permissions to a permission set. The set can be used by other
2440.Qq Nm Cm allow
2441commands for the specified file system and its descendents. Sets are evaluated
2442dynamically, so changes to a set are immediately reflected. Permission sets
2443follow the same naming restrictions as ZFS file systems, but the name must
2444begin with an "at sign"
2445.Pq Sy @ Ns ,
2446and can be no more than 64 characters long.
2447.It Xo
2448.Nm
2449.Cm unallow
2450.Op Fl rldug
2451.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2452.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2453.Ar filesystem Ns | Ns Ar volume
2454.Xc
2455.It Xo
2456.Nm
2457.Cm unallow
2458.Op Fl rld
2459.Fl e
2460.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2461.Ar filesystem Ns | Ns Ar volume
2462.Xc
2463.It Xo
2464.Nm
2465.Cm unallow
2466.Op Fl r
2467.Fl c
2468.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2469.Ar filesystem Ns | Ns Ar volume
2470.Xc
2471.Pp
2472Removes permissions that were granted with the
2473.Qq Nm Cm allow
2474command. No permissions are explicitly denied, so other permissions granted are
2475still in effect. For example, if the permission is granted by an ancestor. If
2476no permissions are specified, then all permissions for the specified
2477.Ar user , group , No or Ar everyone
2478are removed. Specifying "everyone" (or using the
2479.Fl e
2480option) only removes the permissions that were granted to "everyone",
2481not all permissions for every user and group. See the
2482.Qq Nm Cm allow
2483command for a description of the
2484.Fl ldugec
2485options.
2486.Bl -tag -width indent
2487.It Fl r
2488Recursively remove the permissions from this file system and all descendents.
2489.El
2490.It Xo
2491.Nm
2492.Cm unallow
2493.Op Fl r
2494.Fl s
2495.Ar @setname
2496.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2497.Ar filesystem Ns | Ns Ar volume
2498.Xc
2499.Pp
2500Removes permissions from a permission set. If no permissions are specified,
2501then all permissions are removed, thus removing the set entirely.
2502.It Xo
2503.Nm
2504.Cm hold
2505.Op Fl r
2506.Ar tag snapshot ...
2507.Xc
2508.Pp
2509Adds a single reference, named with the
2510.Ar tag
2511argument, to the specified snapshot or snapshots. Each snapshot has its own tag
2512namespace, and tags must be unique within that space.
2513.Pp
2514If a hold exists on a snapshot, attempts to destroy that snapshot by using the
2515.Qq Nm Cm destroy
2516command returns
2517.Em EBUSY .
2518.Bl -tag -width indent
2519.It Fl r
2520Specifies that a hold with the given tag is applied recursively to the
2521snapshots of all descendent file systems.
2522.El
2523.It Xo
2524.Nm
2525.Cm holds
2526.Op Fl r
2527.Ar snapshot ...
2528.Xc
2529.Pp
2530Lists all existing user references for the given snapshot or snapshots.
2531.Bl -tag -width indent
2532.It Fl r
2533Lists the holds that are set on the named descendent snapshots, in addition to
2534listing the holds on the named snapshot.
2535.El
2536.It Xo
2537.Nm
2538.Cm release
2539.Op Fl r
2540.Ar tag snapshot ...
2541.Xc
2542.Pp
2543Removes a single reference, named with the
2544.Ar tag
2545argument, from the specified snapshot or snapshots. The tag must already exist
2546for each snapshot.
2547.Bl -tag -width indent
2548.It Fl r
2549Recursively releases a hold with the given tag on the snapshots of all
2550descendent file systems.
2551.El
2552.It Xo
2553.Nm
2554.Cm diff
2555.Op Fl FHt
2556.Ar snapshot
2557.Op Ar snapshot Ns | Ns Ar filesystem
2558.Xc
2559.Pp
2560Describes differences between a snapshot and a successor dataset. The
2561successor dataset can be a later snapshot or the current filesystem.
2562.Pp
2563The changed files are displayed including the change type. The change type
2564is displayed ussing a single character. If a file or directory was renamed,
2565the old and the new names are displayed.
2566.Pp
2567The following change types can be displayed:
2568.Pp
2569.Bl -column -offset indent "CHARACTER" "CHANGE TYPE"
2570.It CHARACTER Ta CHANGE TYPE
2571.It \&+ Ta file was added
2572.It \&- Ta file was removed
2573.It \&M Ta file was modified
2574.It \&R Ta file was renamed
2575.El
2576.Bl -tag -width indent
2577.It Fl F
2578Display a single letter for the file type in second to last column.
2579.Pp
2580The following file types can be displayed:
2581.Pp
2582.Bl -column -offset indent "CHARACTER" "FILE TYPE"
2583.It CHARACTER Ta FILE TYPE
2584.It \&F Ta file
2585.It \&/ Ta directory
2586.It \&B Ta block device
2587.It \&@ Ta symbolic link
2588.It \&= Ta socket
2589.It \&> Ta door (not supported on Fx Ns )
2590.It \&| Ta FIFO (not supported on Fx Ns )
2591.It \&P Ta event portal (not supported on Fx Ns )
2592.El
2593.It Fl H
2594Machine-parseable output, fields separated a tab character.
2595.It Fl t
2596Display a change timestamp in the first column.
2597.El
2598.It Xo
2599.Nm
2600.Cm jail
2601.Ar jailid filesystem
2602.Xc
2603.Pp
2604Attaches the specified
2605.Ar filesystem
2606to the jail identified by JID
2607.Ar jailid .
2608From now on this file system tree can be managed from within a jail if the
2609.Sy jailed
2610property has been set. To use this functionality, the jail needs the
2611.Va enforce_statfs
2612parameter set to
2613.Sy 0
2614and the
2615.Va allow.mount
2616parameter set to
2617.Sy 1 .
2618.Pp
2619See
2620.Xr jail 8
2621for more information on managing jails and configuring the parameters above.
2622.It Xo
2623.Nm
2624.Cm unjail
2625.Ar jailid filesystem
2626.Xc
2627.Pp
2628Detaches the specified
2629.Ar filesystem
2630from the jail identified by JID
2631.Ar jailid .
2632.El
2633.Sh EXAMPLES
2634.Bl -tag -width 0n
2635.It Sy Example 1 No Creating a Tn ZFS No File System Hierarchy
2636.Pp
2637The following commands create a file system named
2638.Em pool/home
2639and a file system named
2640.Em pool/home/bob .
2641The mount point
2642.Pa /home
2643is set for the parent file system, and is automatically inherited by the child
2644file system.
2645.Bd -literal -offset 2n
2646.Li # Ic zfs create pool/home
2647.Li # Ic zfs set mountpoint=/home pool/home
2648.Li # Ic zfs create pool/home/bob
2649.Ed
2650.It Sy Example 2 No Creating a Tn ZFS No Snapshot
2651.Pp
2652The following command creates a snapshot named
2653.Sy yesterday .
2654This snapshot is mounted on demand in the
2655.Pa \&.zfs/snapshot
2656directory at the root of the
2657.Em pool/home/bob
2658file system.
2659.Bd -literal -offset 2n
2660.Li # Ic zfs snapshot pool/home/bob@yesterday
2661.Ed
2662.It Sy Example 3 No Creating and Destroying Multiple Snapshots
2663.Pp
2664The following command creates snapshots named
2665.Em yesterday
2666of
2667.Em pool/home
2668and all of its descendent file systems. Each snapshot is mounted on demand in
2669the
2670.Pa \&.zfs/snapshot
2671directory at the root of its file system. The second command destroys the newly
2672created snapshots.
2673.Bd -literal -offset 2n
2674.Li # Ic zfs snapshot -r pool/home@yesterday
2675.Li # Ic zfs destroy -r pool/home@yesterday
2676.Ed
2677.It Sy Example 4 No Disabling and Enabling File System Compression
2678.Pp
2679The following command disables the
2680.Sy compression
2681property for all file systems under
2682.Em pool/home .
2683The next command explicitly enables
2684.Sy compression
2685for
2686.Em pool/home/anne .
2687.Bd -literal -offset 2n
2688.Li # Ic zfs set compression=off pool/home
2689.Li # Ic zfs set compression=on pool/home/anne
2690.Ed
2691.It Sy Example 5 No Listing Tn ZFS No Datasets
2692.Pp
2693The following command lists all active file systems and volumes in the system.
2694Snapshots are displayed if the
2695.Sy listsnaps
2696property is
2697.Cm on .
2698The default is
2699.Cm off .
2700See
2701.Xr zpool 8
2702for more information on pool properties.
2703.Bd -literal -offset 2n
2704.Li # Ic zfs list
2705 NAME USED AVAIL REFER MOUNTPOINT
2706 pool 450K 457G 18K /pool
2707 pool/home 315K 457G 21K /home
2708 pool/home/anne 18K 457G 18K /home/anne
2709 pool/home/bob 276K 457G 276K /home/bob
2710.Ed
2711.It Sy Example 6 No Setting a Quota on a Tn ZFS No File System
2712.Pp
2713The following command sets a quota of 50 Gbytes for
2714.Em pool/home/bob .
2715.Bd -literal -offset 2n
2716.Li # Ic zfs set quota=50G pool/home/bob
2717.Ed
2718.It Sy Example 7 No Listing Tn ZFS No Properties
2719.Pp
2720The following command lists all properties for
2721.Em pool/home/bob .
2722.Bd -literal -offset 2n
2723.Li # Ic zfs get all pool/home/bob
2724NAME PROPERTY VALUE SOURCE
2725pool/home/bob type filesystem -
2726pool/home/bob creation Tue Jul 21 15:53 2009 -
2727pool/home/bob used 21K -
2728pool/home/bob available 20.0G -
2729pool/home/bob referenced 21K -
2730pool/home/bob compressratio 1.00x -
2731pool/home/bob mounted yes -
2732pool/home/bob quota 20G local
2733pool/home/bob reservation none default
2734pool/home/bob recordsize 128K default
2735pool/home/bob mountpoint /home/bob default
2736pool/home/bob sharenfs off default
2737pool/home/bob checksum on default
2738pool/home/bob compression on local
2739pool/home/bob atime on default
2740pool/home/bob devices on default
2741pool/home/bob exec on default
2742pool/home/bob setuid on default
2743pool/home/bob readonly off default
2744pool/home/bob jailed off default
2745pool/home/bob snapdir hidden default
2746pool/home/bob aclmode discard default
2747pool/home/bob aclinherit restricted default
2748pool/home/bob canmount on default
2749pool/home/bob xattr on default
2750pool/home/bob copies 1 default
2751pool/home/bob version 5 -
2752pool/home/bob utf8only off -
2753pool/home/bob normalization none -
2754pool/home/bob casesensitivity sensitive -
2755pool/home/bob vscan off default
2756pool/home/bob nbmand off default
2757pool/home/bob sharesmb off default
2758pool/home/bob refquota none default
2759pool/home/bob refreservation none default
2760pool/home/bob primarycache all default
2761pool/home/bob secondarycache all default
2762pool/home/bob usedbysnapshots 0 -
2763pool/home/bob usedbydataset 21K -
2764pool/home/bob usedbychildren 0 -
2765pool/home/bob usedbyrefreservation 0 -
2766pool/home/bob logbias latency default
2767pool/home/bob dedup off default
2768pool/home/bob mlslabel -
2769pool/home/bob sync standard default
2770pool/home/bob refcompressratio 1.00x -
2771.Ed
2772.Pp
2773The following command gets a single property value.
2774.Bd -literal -offset 2n
2775.Li # Ic zfs get -H -o value compression pool/home/bob
2776on
2777.Ed
2778.Pp
2779The following command lists all properties with local settings for
2780.Em pool/home/bob .
2781.Bd -literal -offset 2n
2782.Li # Ic zfs get -s local -o name,property,value all pool/home/bob
2783NAME PROPERTY VALUE
2784pool/home/bob quota 20G
2785pool/home/bob compression on
2786.Ed
2787.It Sy Example 8 No Rolling Back a Tn ZFS No File System
2788.Pp
2789The following command reverts the contents of
2790.Em pool/home/anne
2791to the snapshot named
2792.Em yesterday ,
2793deleting all intermediate snapshots.
2794.Bd -literal -offset 2n
2795.Li # Ic zfs rollback -r pool/home/anne@yesterday
2796.Ed
2797.It Sy Example 9 No Creating a Tn ZFS No Clone
2798.Pp
2799The following command creates a writable file system whose initial contents are
2800the same as
2801.Em pool/home/bob@yesterday .
2802.Bd -literal -offset 2n
2803.Li # Ic zfs clone pool/home/bob@yesterday pool/clone
2804.Ed
2805.It Sy Example 10 No Promoting a Tn ZFS No Clone
2806.Pp
2807The following commands illustrate how to test out changes to a file system, and
2808then replace the original file system with the changed one, using clones, clone
2809promotion, and renaming:
2810.Bd -literal -offset 2n
2811.Li # Ic zfs create pool/project/production
2812.Ed
2813.Pp
2814Populate
2815.Pa /pool/project/production
2816with data and continue with the following commands:
2817.Bd -literal -offset 2n
2818.Li # Ic zfs snapshot pool/project/production@today
2819.Li # Ic zfs clone pool/project/production@today pool/project/beta
2820.Ed
2821.Pp
2822Now make changes to
2823.Pa /pool/project/beta
2824and continue with the following commands:
2825.Bd -literal -offset 2n
2826.Li # Ic zfs promote pool/project/beta
2827.Li # Ic zfs rename pool/project/production pool/project/legacy
2828.Li # Ic zfs rename pool/project/beta pool/project/production
2829.Ed
2830.Pp
2831Once the legacy version is no longer needed, it can be destroyed.
2832.Bd -literal -offset 2n
2833.Li # Ic zfs destroy pool/project/legacy
2834.Ed
2835.It Sy Example 11 No Inheriting Tn ZFS No Properties
2836.Pp
2837The following command causes
2838.Em pool/home/bob
2839and
2840.Em pool/home/anne
2841to inherit the
2842.Sy checksum
2843property from their parent.
2844.Bd -literal -offset 2n
2845.Li # Ic zfs inherit checksum pool/home/bob pool/home/anne
2846.Ed
2847.It Sy Example 12 No Remotely Replicating Tn ZFS No Data
2848.Pp
2849The following commands send a full stream and then an incremental stream to a
2850remote machine, restoring them into
2851.Sy poolB/received/fs@a
2852and
2853.Sy poolB/received/fs@b ,
2854respectively.
2855.Sy poolB
2856must contain the file system
2857.Sy poolB/received ,
2858and must not initially contain
2859.Sy poolB/received/fs .
2860.Bd -literal -offset 2n
2861.Li # Ic zfs send pool/fs@a | ssh host zfs receive poolB/received/fs@a
2862.Li # Ic zfs send -i a pool/fs@b | ssh host zfs receive poolB/received/fs
2863.Ed
2864.It Xo
2865.Sy Example 13
2866Using the
2867.Qq zfs receive -d
2868Option
2869.Xc
2870.Pp
2871The following command sends a full stream of
2872.Sy poolA/fsA/fsB@snap
2873to a remote machine, receiving it into
2874.Sy poolB/received/fsA/fsB@snap .
2875The
2876.Sy fsA/fsB@snap
2877portion of the received snapshot's name is determined from the name of the sent
2878snapshot.
2879.Sy poolB
2880must contain the file system
2881.Sy poolB/received .
2882If
2883.Sy poolB/received/fsA
2884does not exist, it is created as an empty file system.
2885.Bd -literal -offset 2n
2886.Li # Ic zfs send poolA/fsA/fsB@snap | ssh host zfs receive -d poolB/received
2887.Ed
2888.It Sy Example 14 No Setting User Properties
2889.Pp
2890The following example sets the user-defined
2891.Sy com.example:department
2892property for a dataset.
2893.Bd -literal -offset 2n
2894.Li # Ic zfs set com.example:department=12345 tank/accounting
2895.Ed
2896.It Sy Example 15 No Performing a Rolling Snapshot
2897.Pp
2898The following example shows how to maintain a history of snapshots with a
2899consistent naming scheme. To keep a week's worth of snapshots, the user
2900destroys the oldest snapshot, renames the remaining snapshots, and then creates
2901a new snapshot, as follows:
2902.Bd -literal -offset 2n
2903.Li # Ic zfs destroy -r pool/users@7daysago
2904.Li # Ic zfs rename -r pool/users@6daysago @7daysago
2905.Li # Ic zfs rename -r pool/users@5daysago @6daysago
2906.Li # Ic zfs rename -r pool/users@yesterday @5daysago
2907.Li # Ic zfs rename -r pool/users@yesterday @4daysago
2908.Li # Ic zfs rename -r pool/users@yesterday @3daysago
2909.Li # Ic zfs rename -r pool/users@yesterday @2daysago
2910.Li # Ic zfs rename -r pool/users@today @yesterday
2911.Li # Ic zfs snapshot -r pool/users@today
2912.Ed
2913.It Xo
2914.Sy Example 16
2915Setting
2916.Qq sharenfs
2917Property Options on a ZFS File System
2918.Xc
2919.Pp
2920The following command shows how to set
2921.Sy sharenfs
2922property options to enable root access for a specific network on the
2923.Em tank/home
2924file system. The contents of the
2925.Sy sharenfs
2926property are valid
2927.Xr exports 5
2928options.
2929.Bd -literal -offset 2n
2930.Li # Ic zfs set sharenfs="maproot=root,network 192.168.0.0/24" tank/home
2931.Ed
2932.Pp
2933Another way to write this command with the same result is:
2934.Bd -literal -offset 2n
2935.Li # Ic set zfs sharenfs="-maproot=root -network 192.168.0.0/24" tank/home
2936.Ed
2937.It Xo
2938.Sy Example 17
2939Delegating
2940.Tn ZFS
2941Administration Permissions on a
2942.Tn ZFS
2943Dataset
2944.Xc
2945.Pp
2946The following example shows how to set permissions so that user
2947.Em cindys
2948can create, destroy, mount, and take snapshots on
2949.Em tank/cindys .
2950The permissions on
2951.Em tank/cindys
2952are also displayed.
2953.Bd -literal -offset 2n
2954.Li # Ic zfs allow cindys create,destroy,mount,snapshot tank/cindys
2955.Li # Ic zfs allow tank/cindys
2956-------------------------------------------------------------
2957Local+Descendent permissions on (tank/cindys)
2958 user cindys create,destroy,mount,snapshot
2959-------------------------------------------------------------
2960.Ed
2961.It Sy Example 18 No Delegating Create Time Permissions on a Tn ZFS No Dataset
2962.Pp
2963The following example shows how to grant anyone in the group
2964.Em staff
2965to create file systems in
2966.Em tank/users .
2967This syntax also allows staff members to destroy their own file systems, but
2968not destroy anyone else's file system. The permissions on
2969.Em tank/users
2970are also displayed.
2971.Bd -literal -offset 2n
2972.Li # Ic zfs allow staff create,mount tank/users
2973.Li # Ic zfs allow -c destroy tank/users
2974.Li # Ic zfs allow tank/users
2975-------------------------------------------------------------
2976Create time permissions on (tank/users)
2977 create,destroy
2978Local+Descendent permissions on (tank/users)
2979 group staff create,mount
2980-------------------------------------------------------------
2981.Ed
2982.It Xo
2983.Sy Example 19
2984Defining and Granting a Permission Set on a
2985.Tn ZFS
2986Dataset
2987.Xc
2988.Pp
2989The following example shows how to define and grant a permission set on the
2990.Em tank/users
2991file system. The permissions on
2992.Em tank/users
2993are also displayed.
2994.Bd -literal -offset 2n
2995.Li # Ic zfs allow -s @pset create,destroy,snapshot,mount tank/users
2996.Li # Ic zfs allow staff @pset tank/users
2997.Li # Ic zfs allow tank/users
2998-------------------------------------------------------------
2999Permission sets on (tank/users)
3000 @pset create,destroy,mount,snapshot
3001Create time permissions on (tank/users)
3002 create,destroy
3003Local+Descendent permissions on (tank/users)
3004 group staff @pset,create,mount
3005-------------------------------------------------------------
3006.Ed
3007.It Sy Example 20 No Delegating Property Permissions on a Tn ZFS No Dataset
3008.Pp
3009The following example shows to grant the ability to set quotas and reservations
3010on the
3011.Sy users/home
3012file system. The permissions on
3013.Sy users/home
3014are also displayed.
3015.Bd -literal -offset 2n
3016.Li # Ic zfs allow cindys quota,reservation users/home
3017.Li # Ic zfs allow cindys
3018-------------------------------------------------------------
3019Local+Descendent permissions on (users/home)
3020 user cindys quota,reservation
3021-------------------------------------------------------------
3022.Li # Ic su - cindys
3023.Li cindys% Ic zfs set quota=10G users/home/marks
3024.Li cindys% Ic zfs get quota users/home/marks
3025NAME PROPERTY VALUE SOURCE
3026users/home/marks quota 10G local
3027.Ed
3028.It Sy Example 21 No Removing ZFS Delegated Permissions on a Tn ZFS No Dataset
3029.Pp
3030The following example shows how to remove the snapshot permission from the
3031.Em staff
3032group on the
3033.Em tank/users
3034file system. The permissions on
3035.Em tank/users
3036are also displayed.
3037.Bd -literal -offset 2n
3038.Li # Ic zfs unallow staff snapshot tank/users
3039.Li # Ic zfs allow tank/users
3040-------------------------------------------------------------
3041Permission sets on (tank/users)
3042 @pset create,destroy,mount,snapshot
3043Create time permissions on (tank/users)
3044 create,destroy
3045Local+Descendent permissions on (tank/users)
3046 group staff @pset,create,mount
3047-------------------------------------------------------------
3048.Ed
3049.El
3050.Sh EXIT STATUS
3051The following exit values are returned:
3052.Bl -tag -offset 2n -width 2n
3053.It 0
3054Successful completion.
3055.It 1
3056An error occurred.
3057.It 2
3058Invalid command line options were specified.
3059.El
3060.Sh SEE ALSO
3061.Xr chmod 2 ,
3062.Xr fsync 2 ,
3063.Xr exports 5 ,
3064.Xr fstab 5 ,
3065.Xr rc.conf 5 ,
3066.Xr jail 8 ,
3067.Xr mount 8 ,
3068.Xr umount 8 ,
3069.Xr zpool 8
3070.Sh AUTHORS
3071This manual page is a
3072.Xr mdoc 7
3073reimplementation of the
3074.Tn OpenSolaris
3075manual page
3076.Em zfs(1M) ,
3077modified and customized for
3078.Fx
3079and licensed under the
3080Common Development and Distribution License
3081.Pq Tn CDDL .
3082.Pp
3083The
3084.Xr mdoc 7
3085implementation of this manual page was initially written by
3086.An Martin Matuska Aq mm@FreeBSD.org .
| 2252.It Fl v
2253Print verbose information about the stream package generated.
2254.El
2255.Pp
2256The format of the stream is committed. You will be able to receive your streams
2257on future versions of
2258.Tn ZFS .
2259.It Xo
2260.Nm
2261.Cm receive
2262.Op Fl vnFu
2263.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2264.Xc
2265.It Xo
2266.Nm
2267.Cm receive
2268.Op Fl vnFu
2269.Op Fl d | e
2270.Ar filesystem
2271.Xc
2272.Pp
2273Creates a snapshot whose contents are as specified in the stream provided on
2274standard input. If a full stream is received, then a new file system is created
2275as well. Streams are created using the
2276.Qq Nm Cm send
2277subcommand, which by default creates a full stream.
2278.Qq Nm Cm recv
2279can be used as an alias for
2280.Qq Nm Cm receive .
2281.Pp
2282If an incremental stream is received, then the destination file system must
2283already exist, and its most recent snapshot must match the incremental stream's
2284source. For
2285.Sy zvol Ns s,
2286the destination device link is destroyed and recreated, which means the
2287.Sy zvol
2288cannot be accessed during the
2289.Sy receive
2290operation.
2291.Pp
2292When a snapshot replication package stream that is generated by using the
2293.Qq Nm Cm send Fl R
2294command is received, any snapshots that do not exist on the sending location
2295are destroyed by using the
2296.Qq Nm Cm destroy Fl d
2297command.
2298.Pp
2299The name of the snapshot (and file system, if a full stream is received) that
2300this subcommand creates depends on the argument type and the
2301.Fl d
2302or
2303.Fl e
2304option.
2305.Pp
2306If the argument is a snapshot name, the specified
2307.Ar snapshot
2308is created. If the argument is a file system or volume name, a snapshot with
2309the same name as the sent snapshot is created within the specified
2310.Ar filesystem
2311or
2312.Ar volume .
2313If the
2314.Fl d
2315or
2316.Fl e
2317option is specified, the snapshot name is determined by appending the sent
2318snapshot's name to the specified
2319.Ar filesystem .
2320If the
2321.Fl d
2322option is specified, all but the pool name of the sent snapshot path is
2323appended (for example,
2324.Sy b/c@1
2325appended from sent snapshot
2326.Sy a/b/c@1 Ns ),
2327and if the
2328.Fl e
2329option is specified, only the tail of the sent snapshot path is appended (for
2330example,
2331.Sy c@1
2332appended from sent snapshot
2333.Sy a/b/c@1 Ns ).
2334In the case of
2335.Fl d ,
2336any file systems needed to replicate the path of the sent snapshot are created
2337within the specified file system.
2338.Bl -tag -width indent
2339.It Fl d
2340Use the full sent snapshot path without the first element (without pool name)
2341to determine the name of the new snapshot as described in the paragraph above.
2342.It Fl e
2343Use only the last element of the sent snapshot path to determine the name of
2344the new snapshot as described in the paragraph above.
2345.It Fl u
2346File system that is associated with the received stream is not mounted.
2347.It Fl v
2348Print verbose information about the stream and the time required to perform the
2349receive operation.
2350.It Fl n
2351Do not actually receive the stream. This can be useful in conjunction with the
2352.It Fl v
2353option to verify the name the receive operation would use.
2354.It Fl F
2355Force a rollback of the file system to the most recent snapshot before
2356performing the receive operation. If receiving an incremental replication
2357stream (for example, one generated by
2358.Qq Nm Cm send Fl R Fi iI Ns ) ,
2359destroy snapshots and file systems that do not exist on the sending side.
2360.El
2361.It Xo
2362.Nm
2363.Cm allow
2364.Ar filesystem Ns | Ns Ar volume
2365.Xc
2366.Pp
2367Displays permissions that have been delegated on the specified filesystem or
2368volume. See the other forms of
2369.Qq Nm Cm allow
2370for more information.
2371.It Xo
2372.Nm
2373.Cm allow
2374.Op Fl ldug
2375.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2376.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2377.Ar filesystem Ns | Ns Ar volume
2378.Xc
2379.It Xo
2380.Nm
2381.Cm allow
2382.Op Fl ld
2383.Fl e
2384.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2385.Ar filesystem Ns | Ns Ar volume
2386.Xc
2387.Pp
2388Delegates
2389.Tn ZFS
2390administration permission for the file systems to non-privileged users.
2391.Bl -tag -width indent
2392.It Xo
2393.Op Fl ug
2394.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2395.Xc
2396Specifies to whom the permissions are delegated. Multiple entities can be
2397specified as a comma-separated list. If neither of the
2398.Fl ug
2399options are specified, then the argument is interpreted preferentially as the
2400keyword "everyone", then as a user name, and lastly as a group name. To specify
2401a user or group named "everyone", use the
2402.Fl u
2403or
2404.Fl g
2405options. To specify a group with the same name as a user, use the
2406.Fl g
2407option.
2408.It Xo
2409.Op Fl e
2410.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2411.Xc
2412Specifies that the permissions be delegated to "everyone." Multiple permissions
2413may be specified as a comma-separated list. Permission names are the same as
2414.Tn ZFS
2415subcommand and property names. See the property list below. Property set names,
2416which begin with an at sign
2417.Pq Sy @ Ns ,
2418may be specified. See the
2419.Fl s
2420form below for details.
2421.It Xo
2422.Op Fl ld
2423.Ar filesystem Ns | Ns Ar volume
2424.Xc
2425Specifies where the permissions are delegated. If neither of the
2426.Fl ld
2427options are specified, or both are, then the permissions are allowed for the
2428file system or volume, and all of its descendents. If only the
2429.Fl l
2430option is used, then is allowed "locally" only for the specified file system.
2431If only the
2432.Fl d
2433option is used, then is allowed only for the descendent file systems.
2434.El
2435.Pp
2436Permissions are generally the ability to use a
2437.Tn ZFS
2438subcommand or change a
2439.Tn ZFS
2440property. The following permissions are available:
2441.Bl -column -offset 4n "secondarycache" "subcommand"
2442.It NAME Ta TYPE Ta NOTES
2443.It Xo allow Ta subcommand Ta Must
2444also have the permission that is being allowed
2445.Xc
2446.It Xo clone Ta subcommand Ta Must
2447also have the 'create' ability and 'mount' ability in the origin file system
2448.Xc
2449.It create Ta subcommand Ta Must also have the 'mount' ability
2450.It destroy Ta subcommand Ta Must also have the 'mount' ability
2451.It hold Ta subcommand Ta Allows adding a user hold to a snapshot
2452.It mount Ta subcommand Ta Allows mount/umount of Tn ZFS No datasets
2453.It Xo promote Ta subcommand Ta Must
2454also have the 'mount' and 'promote' ability in the origin file system
2455.Xc
2456.It receive Ta subcommand Ta Must also have the 'mount' and 'create' ability
2457.It Xo release Ta subcommand Ta Allows
2458releasing a user hold which might destroy the snapshot
2459.Xc
2460.It Xo rename Ta subcommand Ta Must
2461also have the 'mount' and 'create' ability in the new parent
2462.Xc
2463.It rollback Ta subcommand Ta Must also have the 'mount' ability
2464.It send Ta subcommand
2465.It share Ta subcommand Ta Allows Xo
2466sharing file systems over the
2467.Tn NFS
2468protocol
2469.Xc
2470.It snapshot Ta subcommand Ta Must also have the 'mount' ability
2471.It groupquota Ta other Ta Allows accessing any groupquota@... property
2472.It groupused Ta other Ta Allows reading any groupused@... property
2473.It userprop Ta other Ta Allows changing any user property
2474.It userquota Ta other Ta Allows accessing any userquota@... property
2475.It userused Ta other Ta Allows reading any userused@... property
2476.It Ta
2477.It aclinherit Ta property
2478.It aclmode Ta property
2479.It atime Ta property
2480.It canmount Ta property
2481.It casesensitivity Ta property
2482.It checksum Ta property
2483.It compression Ta property
2484.It copies Ta property
2485.It dedup Ta property
2486.It devices Ta property
2487.It exec Ta property
2488.It logbias Ta property
2489.It jailed Ta property
2490.It mlslabel Ta property
2491.It mountpoint Ta property
2492.It nbmand Ta property
2493.It normalization Ta property
2494.It primarycache Ta property
2495.It quota Ta property
2496.It readonly Ta property
2497.It recordsize Ta property
2498.It refquota Ta property
2499.It refreservation Ta property
2500.It reservation Ta property
2501.It secondarycache Ta property
2502.It setuid Ta property
2503.It sharenfs Ta property
2504.It sharesmb Ta property
2505.It snapdir Ta property
2506.It sync Ta property
2507.It utf8only Ta property
2508.It version Ta property
2509.It volblocksize Ta property
2510.It volsize Ta property
2511.It vscan Ta property
2512.It xattr Ta property
2513.El
2514.It Xo
2515.Nm
2516.Cm allow
2517.Fl c
2518.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2519.Ar filesystem Ns | Ns Ar volume
2520.Xc
2521.Pp
2522Sets "create time" permissions. These permissions are granted (locally) to the
2523creator of any newly-created descendent file system.
2524.It Xo
2525.Nm
2526.Cm allow
2527.Fl s
2528.Ar @setname
2529.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2530.Ar filesystem Ns | Ns Ar volume
2531.Xc
2532.Pp
2533Defines or adds permissions to a permission set. The set can be used by other
2534.Qq Nm Cm allow
2535commands for the specified file system and its descendents. Sets are evaluated
2536dynamically, so changes to a set are immediately reflected. Permission sets
2537follow the same naming restrictions as ZFS file systems, but the name must
2538begin with an "at sign"
2539.Pq Sy @ Ns ,
2540and can be no more than 64 characters long.
2541.It Xo
2542.Nm
2543.Cm unallow
2544.Op Fl rldug
2545.Cm everyone Ns | Ns Ar user Ns | Ns Ar group Ns Op , Ns Ar ...
2546.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2547.Ar filesystem Ns | Ns Ar volume
2548.Xc
2549.It Xo
2550.Nm
2551.Cm unallow
2552.Op Fl rld
2553.Fl e
2554.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2555.Ar filesystem Ns | Ns Ar volume
2556.Xc
2557.It Xo
2558.Nm
2559.Cm unallow
2560.Op Fl r
2561.Fl c
2562.Op Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2563.Ar filesystem Ns | Ns Ar volume
2564.Xc
2565.Pp
2566Removes permissions that were granted with the
2567.Qq Nm Cm allow
2568command. No permissions are explicitly denied, so other permissions granted are
2569still in effect. For example, if the permission is granted by an ancestor. If
2570no permissions are specified, then all permissions for the specified
2571.Ar user , group , No or Ar everyone
2572are removed. Specifying "everyone" (or using the
2573.Fl e
2574option) only removes the permissions that were granted to "everyone",
2575not all permissions for every user and group. See the
2576.Qq Nm Cm allow
2577command for a description of the
2578.Fl ldugec
2579options.
2580.Bl -tag -width indent
2581.It Fl r
2582Recursively remove the permissions from this file system and all descendents.
2583.El
2584.It Xo
2585.Nm
2586.Cm unallow
2587.Op Fl r
2588.Fl s
2589.Ar @setname
2590.Ar perm Ns | Ns Ar @setname Ns Op , Ns Ar ...
2591.Ar filesystem Ns | Ns Ar volume
2592.Xc
2593.Pp
2594Removes permissions from a permission set. If no permissions are specified,
2595then all permissions are removed, thus removing the set entirely.
2596.It Xo
2597.Nm
2598.Cm hold
2599.Op Fl r
2600.Ar tag snapshot ...
2601.Xc
2602.Pp
2603Adds a single reference, named with the
2604.Ar tag
2605argument, to the specified snapshot or snapshots. Each snapshot has its own tag
2606namespace, and tags must be unique within that space.
2607.Pp
2608If a hold exists on a snapshot, attempts to destroy that snapshot by using the
2609.Qq Nm Cm destroy
2610command returns
2611.Em EBUSY .
2612.Bl -tag -width indent
2613.It Fl r
2614Specifies that a hold with the given tag is applied recursively to the
2615snapshots of all descendent file systems.
2616.El
2617.It Xo
2618.Nm
2619.Cm holds
2620.Op Fl r
2621.Ar snapshot ...
2622.Xc
2623.Pp
2624Lists all existing user references for the given snapshot or snapshots.
2625.Bl -tag -width indent
2626.It Fl r
2627Lists the holds that are set on the named descendent snapshots, in addition to
2628listing the holds on the named snapshot.
2629.El
2630.It Xo
2631.Nm
2632.Cm release
2633.Op Fl r
2634.Ar tag snapshot ...
2635.Xc
2636.Pp
2637Removes a single reference, named with the
2638.Ar tag
2639argument, from the specified snapshot or snapshots. The tag must already exist
2640for each snapshot.
2641.Bl -tag -width indent
2642.It Fl r
2643Recursively releases a hold with the given tag on the snapshots of all
2644descendent file systems.
2645.El
2646.It Xo
2647.Nm
2648.Cm diff
2649.Op Fl FHt
2650.Ar snapshot
2651.Op Ar snapshot Ns | Ns Ar filesystem
2652.Xc
2653.Pp
2654Describes differences between a snapshot and a successor dataset. The
2655successor dataset can be a later snapshot or the current filesystem.
2656.Pp
2657The changed files are displayed including the change type. The change type
2658is displayed ussing a single character. If a file or directory was renamed,
2659the old and the new names are displayed.
2660.Pp
2661The following change types can be displayed:
2662.Pp
2663.Bl -column -offset indent "CHARACTER" "CHANGE TYPE"
2664.It CHARACTER Ta CHANGE TYPE
2665.It \&+ Ta file was added
2666.It \&- Ta file was removed
2667.It \&M Ta file was modified
2668.It \&R Ta file was renamed
2669.El
2670.Bl -tag -width indent
2671.It Fl F
2672Display a single letter for the file type in second to last column.
2673.Pp
2674The following file types can be displayed:
2675.Pp
2676.Bl -column -offset indent "CHARACTER" "FILE TYPE"
2677.It CHARACTER Ta FILE TYPE
2678.It \&F Ta file
2679.It \&/ Ta directory
2680.It \&B Ta block device
2681.It \&@ Ta symbolic link
2682.It \&= Ta socket
2683.It \&> Ta door (not supported on Fx Ns )
2684.It \&| Ta FIFO (not supported on Fx Ns )
2685.It \&P Ta event portal (not supported on Fx Ns )
2686.El
2687.It Fl H
2688Machine-parseable output, fields separated a tab character.
2689.It Fl t
2690Display a change timestamp in the first column.
2691.El
2692.It Xo
2693.Nm
2694.Cm jail
2695.Ar jailid filesystem
2696.Xc
2697.Pp
2698Attaches the specified
2699.Ar filesystem
2700to the jail identified by JID
2701.Ar jailid .
2702From now on this file system tree can be managed from within a jail if the
2703.Sy jailed
2704property has been set. To use this functionality, the jail needs the
2705.Va enforce_statfs
2706parameter set to
2707.Sy 0
2708and the
2709.Va allow.mount
2710parameter set to
2711.Sy 1 .
2712.Pp
2713See
2714.Xr jail 8
2715for more information on managing jails and configuring the parameters above.
2716.It Xo
2717.Nm
2718.Cm unjail
2719.Ar jailid filesystem
2720.Xc
2721.Pp
2722Detaches the specified
2723.Ar filesystem
2724from the jail identified by JID
2725.Ar jailid .
2726.El
2727.Sh EXAMPLES
2728.Bl -tag -width 0n
2729.It Sy Example 1 No Creating a Tn ZFS No File System Hierarchy
2730.Pp
2731The following commands create a file system named
2732.Em pool/home
2733and a file system named
2734.Em pool/home/bob .
2735The mount point
2736.Pa /home
2737is set for the parent file system, and is automatically inherited by the child
2738file system.
2739.Bd -literal -offset 2n
2740.Li # Ic zfs create pool/home
2741.Li # Ic zfs set mountpoint=/home pool/home
2742.Li # Ic zfs create pool/home/bob
2743.Ed
2744.It Sy Example 2 No Creating a Tn ZFS No Snapshot
2745.Pp
2746The following command creates a snapshot named
2747.Sy yesterday .
2748This snapshot is mounted on demand in the
2749.Pa \&.zfs/snapshot
2750directory at the root of the
2751.Em pool/home/bob
2752file system.
2753.Bd -literal -offset 2n
2754.Li # Ic zfs snapshot pool/home/bob@yesterday
2755.Ed
2756.It Sy Example 3 No Creating and Destroying Multiple Snapshots
2757.Pp
2758The following command creates snapshots named
2759.Em yesterday
2760of
2761.Em pool/home
2762and all of its descendent file systems. Each snapshot is mounted on demand in
2763the
2764.Pa \&.zfs/snapshot
2765directory at the root of its file system. The second command destroys the newly
2766created snapshots.
2767.Bd -literal -offset 2n
2768.Li # Ic zfs snapshot -r pool/home@yesterday
2769.Li # Ic zfs destroy -r pool/home@yesterday
2770.Ed
2771.It Sy Example 4 No Disabling and Enabling File System Compression
2772.Pp
2773The following command disables the
2774.Sy compression
2775property for all file systems under
2776.Em pool/home .
2777The next command explicitly enables
2778.Sy compression
2779for
2780.Em pool/home/anne .
2781.Bd -literal -offset 2n
2782.Li # Ic zfs set compression=off pool/home
2783.Li # Ic zfs set compression=on pool/home/anne
2784.Ed
2785.It Sy Example 5 No Listing Tn ZFS No Datasets
2786.Pp
2787The following command lists all active file systems and volumes in the system.
2788Snapshots are displayed if the
2789.Sy listsnaps
2790property is
2791.Cm on .
2792The default is
2793.Cm off .
2794See
2795.Xr zpool 8
2796for more information on pool properties.
2797.Bd -literal -offset 2n
2798.Li # Ic zfs list
2799 NAME USED AVAIL REFER MOUNTPOINT
2800 pool 450K 457G 18K /pool
2801 pool/home 315K 457G 21K /home
2802 pool/home/anne 18K 457G 18K /home/anne
2803 pool/home/bob 276K 457G 276K /home/bob
2804.Ed
2805.It Sy Example 6 No Setting a Quota on a Tn ZFS No File System
2806.Pp
2807The following command sets a quota of 50 Gbytes for
2808.Em pool/home/bob .
2809.Bd -literal -offset 2n
2810.Li # Ic zfs set quota=50G pool/home/bob
2811.Ed
2812.It Sy Example 7 No Listing Tn ZFS No Properties
2813.Pp
2814The following command lists all properties for
2815.Em pool/home/bob .
2816.Bd -literal -offset 2n
2817.Li # Ic zfs get all pool/home/bob
2818NAME PROPERTY VALUE SOURCE
2819pool/home/bob type filesystem -
2820pool/home/bob creation Tue Jul 21 15:53 2009 -
2821pool/home/bob used 21K -
2822pool/home/bob available 20.0G -
2823pool/home/bob referenced 21K -
2824pool/home/bob compressratio 1.00x -
2825pool/home/bob mounted yes -
2826pool/home/bob quota 20G local
2827pool/home/bob reservation none default
2828pool/home/bob recordsize 128K default
2829pool/home/bob mountpoint /home/bob default
2830pool/home/bob sharenfs off default
2831pool/home/bob checksum on default
2832pool/home/bob compression on local
2833pool/home/bob atime on default
2834pool/home/bob devices on default
2835pool/home/bob exec on default
2836pool/home/bob setuid on default
2837pool/home/bob readonly off default
2838pool/home/bob jailed off default
2839pool/home/bob snapdir hidden default
2840pool/home/bob aclmode discard default
2841pool/home/bob aclinherit restricted default
2842pool/home/bob canmount on default
2843pool/home/bob xattr on default
2844pool/home/bob copies 1 default
2845pool/home/bob version 5 -
2846pool/home/bob utf8only off -
2847pool/home/bob normalization none -
2848pool/home/bob casesensitivity sensitive -
2849pool/home/bob vscan off default
2850pool/home/bob nbmand off default
2851pool/home/bob sharesmb off default
2852pool/home/bob refquota none default
2853pool/home/bob refreservation none default
2854pool/home/bob primarycache all default
2855pool/home/bob secondarycache all default
2856pool/home/bob usedbysnapshots 0 -
2857pool/home/bob usedbydataset 21K -
2858pool/home/bob usedbychildren 0 -
2859pool/home/bob usedbyrefreservation 0 -
2860pool/home/bob logbias latency default
2861pool/home/bob dedup off default
2862pool/home/bob mlslabel -
2863pool/home/bob sync standard default
2864pool/home/bob refcompressratio 1.00x -
2865.Ed
2866.Pp
2867The following command gets a single property value.
2868.Bd -literal -offset 2n
2869.Li # Ic zfs get -H -o value compression pool/home/bob
2870on
2871.Ed
2872.Pp
2873The following command lists all properties with local settings for
2874.Em pool/home/bob .
2875.Bd -literal -offset 2n
2876.Li # Ic zfs get -s local -o name,property,value all pool/home/bob
2877NAME PROPERTY VALUE
2878pool/home/bob quota 20G
2879pool/home/bob compression on
2880.Ed
2881.It Sy Example 8 No Rolling Back a Tn ZFS No File System
2882.Pp
2883The following command reverts the contents of
2884.Em pool/home/anne
2885to the snapshot named
2886.Em yesterday ,
2887deleting all intermediate snapshots.
2888.Bd -literal -offset 2n
2889.Li # Ic zfs rollback -r pool/home/anne@yesterday
2890.Ed
2891.It Sy Example 9 No Creating a Tn ZFS No Clone
2892.Pp
2893The following command creates a writable file system whose initial contents are
2894the same as
2895.Em pool/home/bob@yesterday .
2896.Bd -literal -offset 2n
2897.Li # Ic zfs clone pool/home/bob@yesterday pool/clone
2898.Ed
2899.It Sy Example 10 No Promoting a Tn ZFS No Clone
2900.Pp
2901The following commands illustrate how to test out changes to a file system, and
2902then replace the original file system with the changed one, using clones, clone
2903promotion, and renaming:
2904.Bd -literal -offset 2n
2905.Li # Ic zfs create pool/project/production
2906.Ed
2907.Pp
2908Populate
2909.Pa /pool/project/production
2910with data and continue with the following commands:
2911.Bd -literal -offset 2n
2912.Li # Ic zfs snapshot pool/project/production@today
2913.Li # Ic zfs clone pool/project/production@today pool/project/beta
2914.Ed
2915.Pp
2916Now make changes to
2917.Pa /pool/project/beta
2918and continue with the following commands:
2919.Bd -literal -offset 2n
2920.Li # Ic zfs promote pool/project/beta
2921.Li # Ic zfs rename pool/project/production pool/project/legacy
2922.Li # Ic zfs rename pool/project/beta pool/project/production
2923.Ed
2924.Pp
2925Once the legacy version is no longer needed, it can be destroyed.
2926.Bd -literal -offset 2n
2927.Li # Ic zfs destroy pool/project/legacy
2928.Ed
2929.It Sy Example 11 No Inheriting Tn ZFS No Properties
2930.Pp
2931The following command causes
2932.Em pool/home/bob
2933and
2934.Em pool/home/anne
2935to inherit the
2936.Sy checksum
2937property from their parent.
2938.Bd -literal -offset 2n
2939.Li # Ic zfs inherit checksum pool/home/bob pool/home/anne
2940.Ed
2941.It Sy Example 12 No Remotely Replicating Tn ZFS No Data
2942.Pp
2943The following commands send a full stream and then an incremental stream to a
2944remote machine, restoring them into
2945.Sy poolB/received/fs@a
2946and
2947.Sy poolB/received/fs@b ,
2948respectively.
2949.Sy poolB
2950must contain the file system
2951.Sy poolB/received ,
2952and must not initially contain
2953.Sy poolB/received/fs .
2954.Bd -literal -offset 2n
2955.Li # Ic zfs send pool/fs@a | ssh host zfs receive poolB/received/fs@a
2956.Li # Ic zfs send -i a pool/fs@b | ssh host zfs receive poolB/received/fs
2957.Ed
2958.It Xo
2959.Sy Example 13
2960Using the
2961.Qq zfs receive -d
2962Option
2963.Xc
2964.Pp
2965The following command sends a full stream of
2966.Sy poolA/fsA/fsB@snap
2967to a remote machine, receiving it into
2968.Sy poolB/received/fsA/fsB@snap .
2969The
2970.Sy fsA/fsB@snap
2971portion of the received snapshot's name is determined from the name of the sent
2972snapshot.
2973.Sy poolB
2974must contain the file system
2975.Sy poolB/received .
2976If
2977.Sy poolB/received/fsA
2978does not exist, it is created as an empty file system.
2979.Bd -literal -offset 2n
2980.Li # Ic zfs send poolA/fsA/fsB@snap | ssh host zfs receive -d poolB/received
2981.Ed
2982.It Sy Example 14 No Setting User Properties
2983.Pp
2984The following example sets the user-defined
2985.Sy com.example:department
2986property for a dataset.
2987.Bd -literal -offset 2n
2988.Li # Ic zfs set com.example:department=12345 tank/accounting
2989.Ed
2990.It Sy Example 15 No Performing a Rolling Snapshot
2991.Pp
2992The following example shows how to maintain a history of snapshots with a
2993consistent naming scheme. To keep a week's worth of snapshots, the user
2994destroys the oldest snapshot, renames the remaining snapshots, and then creates
2995a new snapshot, as follows:
2996.Bd -literal -offset 2n
2997.Li # Ic zfs destroy -r pool/users@7daysago
2998.Li # Ic zfs rename -r pool/users@6daysago @7daysago
2999.Li # Ic zfs rename -r pool/users@5daysago @6daysago
3000.Li # Ic zfs rename -r pool/users@yesterday @5daysago
3001.Li # Ic zfs rename -r pool/users@yesterday @4daysago
3002.Li # Ic zfs rename -r pool/users@yesterday @3daysago
3003.Li # Ic zfs rename -r pool/users@yesterday @2daysago
3004.Li # Ic zfs rename -r pool/users@today @yesterday
3005.Li # Ic zfs snapshot -r pool/users@today
3006.Ed
3007.It Xo
3008.Sy Example 16
3009Setting
3010.Qq sharenfs
3011Property Options on a ZFS File System
3012.Xc
3013.Pp
3014The following command shows how to set
3015.Sy sharenfs
3016property options to enable root access for a specific network on the
3017.Em tank/home
3018file system. The contents of the
3019.Sy sharenfs
3020property are valid
3021.Xr exports 5
3022options.
3023.Bd -literal -offset 2n
3024.Li # Ic zfs set sharenfs="maproot=root,network 192.168.0.0/24" tank/home
3025.Ed
3026.Pp
3027Another way to write this command with the same result is:
3028.Bd -literal -offset 2n
3029.Li # Ic set zfs sharenfs="-maproot=root -network 192.168.0.0/24" tank/home
3030.Ed
3031.It Xo
3032.Sy Example 17
3033Delegating
3034.Tn ZFS
3035Administration Permissions on a
3036.Tn ZFS
3037Dataset
3038.Xc
3039.Pp
3040The following example shows how to set permissions so that user
3041.Em cindys
3042can create, destroy, mount, and take snapshots on
3043.Em tank/cindys .
3044The permissions on
3045.Em tank/cindys
3046are also displayed.
3047.Bd -literal -offset 2n
3048.Li # Ic zfs allow cindys create,destroy,mount,snapshot tank/cindys
3049.Li # Ic zfs allow tank/cindys
3050-------------------------------------------------------------
3051Local+Descendent permissions on (tank/cindys)
3052 user cindys create,destroy,mount,snapshot
3053-------------------------------------------------------------
3054.Ed
3055.It Sy Example 18 No Delegating Create Time Permissions on a Tn ZFS No Dataset
3056.Pp
3057The following example shows how to grant anyone in the group
3058.Em staff
3059to create file systems in
3060.Em tank/users .
3061This syntax also allows staff members to destroy their own file systems, but
3062not destroy anyone else's file system. The permissions on
3063.Em tank/users
3064are also displayed.
3065.Bd -literal -offset 2n
3066.Li # Ic zfs allow staff create,mount tank/users
3067.Li # Ic zfs allow -c destroy tank/users
3068.Li # Ic zfs allow tank/users
3069-------------------------------------------------------------
3070Create time permissions on (tank/users)
3071 create,destroy
3072Local+Descendent permissions on (tank/users)
3073 group staff create,mount
3074-------------------------------------------------------------
3075.Ed
3076.It Xo
3077.Sy Example 19
3078Defining and Granting a Permission Set on a
3079.Tn ZFS
3080Dataset
3081.Xc
3082.Pp
3083The following example shows how to define and grant a permission set on the
3084.Em tank/users
3085file system. The permissions on
3086.Em tank/users
3087are also displayed.
3088.Bd -literal -offset 2n
3089.Li # Ic zfs allow -s @pset create,destroy,snapshot,mount tank/users
3090.Li # Ic zfs allow staff @pset tank/users
3091.Li # Ic zfs allow tank/users
3092-------------------------------------------------------------
3093Permission sets on (tank/users)
3094 @pset create,destroy,mount,snapshot
3095Create time permissions on (tank/users)
3096 create,destroy
3097Local+Descendent permissions on (tank/users)
3098 group staff @pset,create,mount
3099-------------------------------------------------------------
3100.Ed
3101.It Sy Example 20 No Delegating Property Permissions on a Tn ZFS No Dataset
3102.Pp
3103The following example shows to grant the ability to set quotas and reservations
3104on the
3105.Sy users/home
3106file system. The permissions on
3107.Sy users/home
3108are also displayed.
3109.Bd -literal -offset 2n
3110.Li # Ic zfs allow cindys quota,reservation users/home
3111.Li # Ic zfs allow cindys
3112-------------------------------------------------------------
3113Local+Descendent permissions on (users/home)
3114 user cindys quota,reservation
3115-------------------------------------------------------------
3116.Li # Ic su - cindys
3117.Li cindys% Ic zfs set quota=10G users/home/marks
3118.Li cindys% Ic zfs get quota users/home/marks
3119NAME PROPERTY VALUE SOURCE
3120users/home/marks quota 10G local
3121.Ed
3122.It Sy Example 21 No Removing ZFS Delegated Permissions on a Tn ZFS No Dataset
3123.Pp
3124The following example shows how to remove the snapshot permission from the
3125.Em staff
3126group on the
3127.Em tank/users
3128file system. The permissions on
3129.Em tank/users
3130are also displayed.
3131.Bd -literal -offset 2n
3132.Li # Ic zfs unallow staff snapshot tank/users
3133.Li # Ic zfs allow tank/users
3134-------------------------------------------------------------
3135Permission sets on (tank/users)
3136 @pset create,destroy,mount,snapshot
3137Create time permissions on (tank/users)
3138 create,destroy
3139Local+Descendent permissions on (tank/users)
3140 group staff @pset,create,mount
3141-------------------------------------------------------------
3142.Ed
3143.El
3144.Sh EXIT STATUS
3145The following exit values are returned:
3146.Bl -tag -offset 2n -width 2n
3147.It 0
3148Successful completion.
3149.It 1
3150An error occurred.
3151.It 2
3152Invalid command line options were specified.
3153.El
3154.Sh SEE ALSO
3155.Xr chmod 2 ,
3156.Xr fsync 2 ,
3157.Xr exports 5 ,
3158.Xr fstab 5 ,
3159.Xr rc.conf 5 ,
3160.Xr jail 8 ,
3161.Xr mount 8 ,
3162.Xr umount 8 ,
3163.Xr zpool 8
3164.Sh AUTHORS
3165This manual page is a
3166.Xr mdoc 7
3167reimplementation of the
3168.Tn OpenSolaris
3169manual page
3170.Em zfs(1M) ,
3171modified and customized for
3172.Fx
3173and licensed under the
3174Common Development and Distribution License
3175.Pq Tn CDDL .
3176.Pp
3177The
3178.Xr mdoc 7
3179implementation of this manual page was initially written by
3180.An Martin Matuska Aq mm@FreeBSD.org .
|