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