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