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 Ns | Ns Sy auto
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 If
1367 .Sy refreservation
1368 is set to
1369 .Sy auto ,
1370 a volume is made dense
1371 .Po or
1372 .Qq not sparse
1373 .Pc .
1374 .Sy refreservation Ns = Ns Sy auto
1375 is only supported on volumes. See
1376 .Sy volsize
1377 in the
1378 .Sx Native Properties
1379 section for more information about sparse volumes.
1380 .Pp
1381 This property can also be referred to by its shortened column name,
1382 .Sy refreserv .
1383 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1384 The minimum amount of space guaranteed to a dataset and its descendants.
1385 When the amount of space used is below this value, the dataset is treated as if
1386 it were taking up the amount of space specified by its reservation.
1387 Reservations are accounted for in the parent datasets' space used, and count
1388 against the parent datasets' quotas and reservations.
1389 .Pp
1390 See
1391 .Sy refreservation Ns = Ns Sy auto
1392 above for a description of the behavior of setting
1393 .Sy reservation
1394 to
1395 .Sy auto .
1396 If the pool is at version 9 or later,
1397 .Sy refreservation Ns = Ns Sy auto
1398 should be used instead.
1399 .Pp
1400 This property can also be referred to by its shortened column name,
1401 .Sy reserv .
1402 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1403 Controls what is cached in the secondary cache
1404 .Pq L2ARC .
1405 If this property is set to
1406 .Sy all ,
1407 then both user data and metadata is cached.
1408 If this property is set to
1409 .Sy none ,
1410 then neither user data nor metadata is cached.
1411 If this property is set to
1412 .Sy metadata ,
1413 then only metadata is cached.
1414 The default value is
1415 .Sy all .
1416 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1417 Controls whether the setuid bit is respected for the file system.
1418 The default value is
1419 .Sy on .
1420 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1421 Controls whether the file system is shared via SMB, and what options are to be
1422 used.
1423 A file system with the
1424 .Sy sharesmb
1425 property set to
1426 .Sy off
1427 is managed through traditional tools such as
1428 .Xr sharemgr 1M .
1429 Otherwise, the file system is automatically shared and unshared with the
1430 .Nm zfs Cm share
1431 and
1432 .Nm zfs Cm unshare
1433 commands.
1434 If the property is set to
1435 .Sy on ,
1436 the
1437 .Xr sharemgr 1M
1438 command is invoked with no options.
1439 Otherwise, the
1440 .Xr sharemgr 1M
1441 command is invoked with options equivalent to the contents of this property.
1442 .Pp
1443 Because SMB shares requires a resource name, a unique resource name is
1444 constructed from the dataset name.
1445 The constructed name is a copy of the dataset name except that the characters in
1446 the dataset name, which would be invalid in the resource name, are replaced with
1447 underscore
1448 .Pq Sy _
1449 characters.
1450 A pseudo property
1451 .Qq name
1452 is also supported that allows you to replace the data set name with a specified
1453 name.
1454 The specified name is then used to replace the prefix dataset in the case of
1455 inheritance.
1456 For example, if the dataset
1457 .Em data/home/john
1458 is set to
1459 .Sy name Ns = Ns Sy john ,
1460 then
1461 .Em data/home/john
1462 has a resource name of
1463 .Sy john .
1464 If a child dataset
1465 .Em data/home/john/backups
1466 is shared, it has a resource name of
1467 .Sy john_backups .
1468 .Pp
1469 When SMB shares are created, the SMB share name appears as an entry in the
1470 .Pa .zfs/shares
1471 directory.
1472 You can use the
1473 .Nm ls
1474 or
1475 .Nm chmod
1476 command to display the share-level ACLs on the entries in this directory.
1477 .Pp
1478 When the
1479 .Sy sharesmb
1480 property is changed for a dataset, the dataset and any children inheriting the
1481 property are re-shared with the new options, only if the property was previously
1482 set to
1483 .Sy off ,
1484 or if they were shared before the property was changed.
1485 If the new property is set to
1486 .Sy off ,
1487 the file systems are unshared.
1488 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1489 Controls whether the file system is shared via NFS, and what options are to be
1490 used.
1491 A file system with a
1492 .Sy sharenfs
1493 property of
1494 .Sy off
1495 is managed through traditional tools such as
1496 .Xr share 1M ,
1497 .Xr unshare 1M ,
1498 and
1499 .Xr dfstab 4 .
1500 Otherwise, the file system is automatically shared and unshared with the
1501 .Nm zfs Cm share
1502 and
1503 .Nm zfs Cm unshare
1504 commands.
1505 If the property is set to
1506 .Sy on ,
1507 .Xr share 1M
1508 command is invoked with no options.
1509 Otherwise, the
1510 .Xr share 1M
1511 command is invoked with options equivalent to the contents of this property.
1512 .Pp
1513 When the
1514 .Sy sharenfs
1515 property is changed for a dataset, the dataset and any children inheriting the
1516 property are re-shared with the new options, only if the property was previously
1517 .Sy off ,
1518 or if they were shared before the property was changed.
1519 If the new property is
1520 .Sy off ,
1521 the file systems are unshared.
1522 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1523 Provide a hint to ZFS about handling of synchronous requests in this dataset.
1524 If
1525 .Sy logbias
1526 is set to
1527 .Sy latency
1528 .Pq the default ,
1529 ZFS will use pool log devices
1530 .Pq if configured
1531 to handle the requests at low latency.
1532 If
1533 .Sy logbias
1534 is set to
1535 .Sy throughput ,
1536 ZFS will not use configured pool log devices.
1537 ZFS will instead optimize synchronous operations for global pool throughput and
1538 efficient use of resources.
1539 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1540 Controls whether the
1541 .Pa .zfs
1542 directory is hidden or visible in the root of the file system as discussed in
1543 the
1544 .Sx Snapshots
1545 section.
1546 The default value is
1547 .Sy hidden .
1548 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1549 Controls the behavior of synchronous requests
1550 .Pq e.g. fsync, O_DSYNC .
1551 .Sy standard
1552 is the
1553 .Tn POSIX
1554 specified behavior of ensuring all synchronous requests are written to stable
1555 storage and all devices are flushed to ensure data is not cached by device
1556 controllers
1557 .Pq this is the default .
1558 .Sy always
1559 causes every file system transaction to be written and flushed before its
1560 system call returns.
1561 This has a large performance penalty.
1562 .Sy disabled
1563 disables synchronous requests.
1564 File system transactions are only committed to stable storage periodically.
1565 This option will give the highest performance.
1566 However, it is very dangerous as ZFS would be ignoring the synchronous
1567 transaction demands of applications such as databases or NFS.
1568 Administrators should only use this option when the risks are understood.
1569 .It Sy version Ns = Ns Em N Ns | Ns Sy current
1570 The on-disk version of this file system, which is independent of the pool
1571 version.
1572 This property can only be set to later supported versions.
1573 See the
1574 .Nm zfs Cm upgrade
1575 command.
1576 .It Sy volsize Ns = Ns Em size
1577 For volumes, specifies the logical size of the volume.
1578 By default, creating a volume establishes a reservation of equal size.
1579 For storage pools with a version number of 9 or higher, a
1580 .Sy refreservation
1581 is set instead.
1582 Any changes to
1583 .Sy volsize
1584 are reflected in an equivalent change to the reservation
1585 .Po or
1586 .Sy refreservation
1587 .Pc .
1588 The
1589 .Sy volsize
1590 can only be set to a multiple of
1591 .Sy volblocksize ,
1592 and cannot be zero.
1593 .Pp
1594 The reservation is kept equal to the volume's logical size to prevent unexpected
1595 behavior for consumers.
1596 Without the reservation, the volume could run out of space, resulting in
1597 undefined behavior or data corruption, depending on how the volume is used.
1598 These effects can also occur when the volume size is changed while it is in use
1599 .Pq particularly when shrinking the size .
1600 Extreme care should be used when adjusting the volume size.
1601 .Pp
1602 Though not recommended, a
1603 .Qq sparse volume
1604 .Po also known as
1605 .Qq thin provisioning
1606 .Pc
1607 can be created by specifying the
1608 .Fl s
1609 option to the
1610 .Nm zfs Cm create Fl V
1611 command, or by changing the reservation after the volume has been created.
1612 A
1613 .Qq sparse volume
1614 is a volume where the reservation is less than the size of the volume plus the
1615 space required to store its metadata.
1616 Consequently, writes to a sparse volume can fail with
1617 .Er ENOSPC
1618 when the pool is low on space.
1619 For a sparse volume, changes to
1620 .Sy volsize
1621 are not reflected in the reservation. A sparse volume can be made dense
1622 .Po or
1623 .Qq not sparse
1624 .Pc
1625 by setting the reservation to
1626 .Sy auto .
1627 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1628 Controls whether regular files should be scanned for viruses when a file is
1629 opened and closed.
1630 In addition to enabling this property, the virus scan service must also be
1631 enabled for virus scanning to occur.
1632 The default value is
1633 .Sy off .
1634 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off
1635 Controls whether extended attributes are enabled for this file system.
1636 The default value is
1637 .Sy on .
1638 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1639 Controls whether the dataset is managed from a non-global zone.
1640 See the
1641 .Sx Zones
1642 section for more information.
1643 The default value is
1644 .Sy off .
1645 .El
1646 .Pp
1647 The following three properties cannot be changed after the file system is
1648 created, and therefore, should be set when the file system is created.
1649 If the properties are not set with the
1650 .Nm zfs Cm create
1651 or
1652 .Nm zpool Cm create
1653 commands, these properties are inherited from the parent dataset.
1654 If the parent dataset lacks these properties due to having been created prior to
1655 these features being supported, the new file system will have the default values
1656 for these properties.
1657 .Bl -tag -width ""
1658 .It Xo
1659 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1660 .Sy insensitive Ns | Ns Sy mixed
1661 .Xc
1662 Indicates whether the file name matching algorithm used by the file system
1663 should be case-sensitive, case-insensitive, or allow a combination of both
1664 styles of matching.
1665 The default value for the
1666 .Sy casesensitivity
1667 property is
1668 .Sy sensitive .
1669 Traditionally,
1670 .Ux
1671 and
1672 .Tn POSIX
1673 file systems have case-sensitive file names.
1674 .Pp
1675 The
1676 .Sy mixed
1677 value for the
1678 .Sy casesensitivity
1679 property indicates that the file system can support requests for both
1680 case-sensitive and case-insensitive matching behavior.
1681 Currently, case-insensitive matching behavior on a file system that supports
1682 mixed behavior is limited to the SMB server product.
1683 For more information about the
1684 .Sy mixed
1685 value behavior, see the "ZFS Administration Guide".
1686 .It Xo
1687 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1688 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1689 .Xc
1690 Indicates whether the file system should perform a
1691 .Sy unicode
1692 normalization of file names whenever two file names are compared, and which
1693 normalization algorithm should be used.
1694 File names are always stored unmodified, names are normalized as part of any
1695 comparison process.
1696 If this property is set to a legal value other than
1697 .Sy none ,
1698 and the
1699 .Sy utf8only
1700 property was left unspecified, the
1701 .Sy utf8only
1702 property is automatically set to
1703 .Sy on .
1704 The default value of the
1705 .Sy normalization
1706 property is
1707 .Sy none .
1708 This property cannot be changed after the file system is created.
1709 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1710 Indicates whether the file system should reject file names that include
1711 characters that are not present in the
1712 .Sy UTF-8
1713 character code set.
1714 If this property is explicitly set to
1715 .Sy off ,
1716 the normalization property must either not be explicitly set or be set to
1717 .Sy none .
1718 The default value for the
1719 .Sy utf8only
1720 property is
1721 .Sy off .
1722 This property cannot be changed after the file system is created.
1723 .El
1724 .Pp
1725 The
1726 .Sy casesensitivity ,
1727 .Sy normalization ,
1728 and
1729 .Sy utf8only
1730 properties are also new permissions that can be assigned to non-privileged users
1731 by using the ZFS delegated administration feature.
1732 .Ss "Temporary Mount Point Properties"
1733 When a file system is mounted, either through
1734 .Xr mount 1M
1735 for legacy mounts or the
1736 .Nm zfs Cm mount
1737 command for normal file systems, its mount options are set according to its
1738 properties.
1739 The correlation between properties and mount options is as follows:
1740 .Bd -literal
1741 PROPERTY MOUNT OPTION
1742 devices devices/nodevices
1743 exec exec/noexec
1744 readonly ro/rw
1745 setuid setuid/nosetuid
1746 xattr xattr/noxattr
1747 .Ed
1748 .Pp
1749 In addition, these options can be set on a per-mount basis using the
1750 .Fl o
1751 option, without affecting the property that is stored on disk.
1752 The values specified on the command line override the values stored in the
1753 dataset.
1754 The
1755 .Sy nosuid
1756 option is an alias for
1757 .Sy nodevices Ns \&, Ns Sy nosetuid .
1758 These properties are reported as
1759 .Qq temporary
1760 by the
1761 .Nm zfs Cm get
1762 command.
1763 If the properties are changed while the dataset is mounted, the new setting
1764 overrides any temporary settings.
1765 .Ss "User Properties"
1766 In addition to the standard native properties, ZFS supports arbitrary user
1767 properties.
1768 User properties have no effect on ZFS behavior, but applications or
1769 administrators can use them to annotate datasets
1770 .Pq file systems, volumes, and snapshots .
1771 .Pp
1772 User property names must contain a colon
1773 .Pq Qq Sy \&:
1774 character to distinguish them from native properties.
1775 They may contain lowercase letters, numbers, and the following punctuation
1776 characters: colon
1777 .Pq Qq Sy \&: ,
1778 dash
1779 .Pq Qq Sy - ,
1780 period
1781 .Pq Qq Sy \&. ,
1782 and underscore
1783 .Pq Qq Sy _ .
1784 The expected convention is that the property name is divided into two portions
1785 such as
1786 .Em module Ns \&: Ns Em property ,
1787 but this namespace is not enforced by ZFS.
1788 User property names can be at most 256 characters, and cannot begin with a dash
1789 .Pq Qq Sy - .
1790 .Pp
1791 When making programmatic use of user properties, it is strongly suggested to use
1792 a reversed
1793 .Sy DNS
1794 domain name for the
1795 .Em module
1796 component of property names to reduce the chance that two
1797 independently-developed packages use the same property name for different
1798 purposes.
1799 .Pp
1800 The values of user properties are arbitrary strings, are always inherited, and
1801 are never validated.
1802 All of the commands that operate on properties
1803 .Po Nm zfs Cm list ,
1804 .Nm zfs Cm get ,
1805 .Nm zfs Cm set ,
1806 and so forth
1807 .Pc
1808 can be used to manipulate both native properties and user properties.
1809 Use the
1810 .Nm zfs Cm inherit
1811 command to clear a user property.
1812 If the property is not defined in any parent dataset, it is removed entirely.
1813 Property values are limited to 8192 bytes.
1814 .Ss ZFS Volumes as Swap or Dump Devices
1815 During an initial installation a swap device and dump device are created on ZFS
1816 volumes in the ZFS root pool.
1817 By default, the swap area size is based on 1/2 the size of physical memory up to
1818 2 Gbytes.
1819 The size of the dump device depends on the kernel's requirements at installation
1820 time.
1821 Separate ZFS volumes must be used for the swap area and dump devices.
1822 Do not swap to a file on a ZFS file system.
1823 A ZFS swap file configuration is not supported.
1824 .Pp
1825 If you need to change your swap area or dump device after the system is
1826 installed or upgraded, use the
1827 .Xr swap 1M
1828 and
1829 .Xr dumpadm 1M
1830 commands.
1831 .Sh SUBCOMMANDS
1832 All subcommands that modify state are logged persistently to the pool in their
1833 original form.
1834 .Bl -tag -width ""
1835 .It Nm Fl \?
1836 Displays a help message.
1837 .It Xo
1838 .Nm
1839 .Cm create
1840 .Op Fl p
1841 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1842 .Ar filesystem
1843 .Xc
1844 Creates a new ZFS file system.
1845 The file system is automatically mounted according to the
1846 .Sy mountpoint
1847 property inherited from the parent.
1848 .Bl -tag -width "-o"
1849 .It Fl o Ar property Ns = Ns Ar value
1850 Sets the specified property as if the command
1851 .Nm zfs Cm set Ar property Ns = Ns Ar value
1852 was invoked at the same time the dataset was created.
1853 Any editable ZFS property can also be set at creation time.
1854 Multiple
1855 .Fl o
1856 options can be specified.
1857 An error results if the same property is specified in multiple
1858 .Fl o
1859 options.
1860 .It Fl p
1861 Creates all the non-existing parent datasets.
1862 Datasets created in this manner are automatically mounted according to the
1863 .Sy mountpoint
1864 property inherited from their parent.
1865 Any property specified on the command line using the
1866 .Fl o
1867 option is ignored.
1868 If the target filesystem already exists, the operation completes successfully.
1869 .El
1870 .It Xo
1871 .Nm
1872 .Cm create
1873 .Op Fl ps
1874 .Op Fl b Ar blocksize
1875 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1876 .Fl V Ar size Ar volume
1877 .Xc
1878 Creates a volume of the given size.
1879 The volume is exported as a block device in
1880 .Pa /dev/zvol/{dsk,rdsk}/path ,
1881 where
1882 .Em path
1883 is the name of the volume in the ZFS namespace.
1884 The size represents the logical size as exported by the device.
1885 By default, a reservation of equal size is created.
1886 .Pp
1887 .Ar size
1888 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
1889 has an integral number of blocks regardless of
1890 .Sy blocksize .
1891 .Bl -tag -width "-b"
1892 .It Fl b Ar blocksize
1893 Equivalent to
1894 .Fl o Sy volblocksize Ns = Ns Ar blocksize .
1895 If this option is specified in conjunction with
1896 .Fl o Sy volblocksize ,
1897 the resulting behavior is undefined.
1898 .It Fl o Ar property Ns = Ns Ar value
1899 Sets the specified property as if the
1900 .Nm zfs Cm set Ar property Ns = Ns Ar value
1901 command was invoked at the same time the dataset was created.
1902 Any editable ZFS property can also be set at creation time.
1903 Multiple
1904 .Fl o
1905 options can be specified.
1906 An error results if the same property is specified in multiple
1907 .Fl o
1908 options.
1909 .It Fl p
1910 Creates all the non-existing parent datasets.
1911 Datasets created in this manner are automatically mounted according to the
1912 .Sy mountpoint
1913 property inherited from their parent.
1914 Any property specified on the command line using the
1915 .Fl o
1916 option is ignored.
1917 If the target filesystem already exists, the operation completes successfully.
1918 .It Fl s
1919 Creates a sparse volume with no reservation.
1920 See
1921 .Sy volsize
1922 in the
1923 .Sx Native Properties
1924 section for more information about sparse volumes.
1925 .El
1926 .It Xo
1927 .Nm
1928 .Cm destroy
1929 .Op Fl Rfnprv
1930 .Ar filesystem Ns | Ns Ar volume
1931 .Xc
1932 Destroys the given dataset.
1933 By default, the command unshares any file systems that are currently shared,
1934 unmounts any file systems that are currently mounted, and refuses to destroy a
1935 dataset that has active dependents
1936 .Pq children or clones .
1937 .Bl -tag -width "-R"
1938 .It Fl R
1939 Recursively destroy all dependents, including cloned file systems outside the
1940 target hierarchy.
1941 .It Fl f
1942 Force an unmount of any file systems using the
1943 .Nm unmount Fl f
1944 command.
1945 This option has no effect on non-file systems or unmounted file systems.
1946 .It Fl n
1947 Do a dry-run
1948 .Pq Qq No-op
1949 deletion.
1950 No data will be deleted.
1951 This is useful in conjunction with the
1952 .Fl v
1953 or
1954 .Fl p
1955 flags to determine what data would be deleted.
1956 .It Fl p
1957 Print machine-parsable verbose information about the deleted data.
1958 .It Fl r
1959 Recursively destroy all children.
1960 .It Fl v
1961 Print verbose information about the deleted data.
1962 .El
1963 .Pp
1964 Extreme care should be taken when applying either the
1965 .Fl r
1966 or the
1967 .Fl R
1968 options, as they can destroy large portions of a pool and cause unexpected
1969 behavior for mounted file systems in use.
1970 .It Xo
1971 .Nm
1972 .Cm destroy
1973 .Op Fl Rdnprv
1974 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
1975 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
1976 .Xc
1977 The given snapshots are destroyed immediately if and only if the
1978 .Nm zfs Cm destroy
1979 command without the
1980 .Fl d
1981 option would have destroyed it.
1982 Such immediate destruction would occur, for example, if the snapshot had no
1983 clones and the user-initiated reference count were zero.
1984 .Pp
1985 If a snapshot does not qualify for immediate destruction, it is marked for
1986 deferred deletion.
1987 In this state, it exists as a usable, visible snapshot until both of the
1988 preconditions listed above are met, at which point it is destroyed.
1989 .Pp
1990 An inclusive range of snapshots may be specified by separating the first and
1991 last snapshots with a percent sign.
1992 The first and/or last snapshots may be left blank, in which case the
1993 filesystem's oldest or newest snapshot will be implied.
1994 .Pp
1995 Multiple snapshots
1996 .Pq or ranges of snapshots
1997 of the same filesystem or volume may be specified in a comma-separated list of
1998 snapshots.
1999 Only the snapshot's short name
2000 .Po the part after the
2001 .Sy @
2002 .Pc
2003 should be specified when using a range or comma-separated list to identify
2004 multiple snapshots.
2005 .Bl -tag -width "-R"
2006 .It Fl R
2007 Recursively destroy all clones of these snapshots, including the clones,
2008 snapshots, and children.
2009 If this flag is specified, the
2010 .Fl d
2011 flag will have no effect.
2012 .It Fl d
2013 Defer snapshot deletion.
2014 .It Fl n
2015 Do a dry-run
2016 .Pq Qq No-op
2017 deletion.
2018 No data will be deleted.
2019 This is useful in conjunction with the
2020 .Fl p
2021 or
2022 .Fl v
2023 flags to determine what data would be deleted.
2024 .It Fl p
2025 Print machine-parsable verbose information about the deleted data.
2026 .It Fl r
2027 Destroy
2028 .Pq or mark for deferred deletion
2029 all snapshots with this name in descendent file systems.
2030 .It Fl v
2031 Print verbose information about the deleted data.
2032 .Pp
2033 Extreme care should be taken when applying either the
2034 .Fl r
2035 or the
2036 .Fl R
2037 options, as they can destroy large portions of a pool and cause unexpected
2038 behavior for mounted file systems in use.
2039 .El
2040 .It Xo
2041 .Nm
2042 .Cm destroy
2043 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2044 .Xc
2045 The given bookmark is destroyed.
2046 .It Xo
2047 .Nm
2048 .Cm snapshot
2049 .Op Fl r
2050 .Oo Fl o Ar property Ns = Ns value Oc Ns ...
2051 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2052 .Xc
2053 Creates snapshots with the given names.
2054 All previous modifications by successful system calls to the file system are
2055 part of the snapshots.
2056 Snapshots are taken atomically, so that all snapshots correspond to the same
2057 moment in time.
2058 See the
2059 .Sx Snapshots
2060 section for details.
2061 .Bl -tag -width "-o"
2062 .It Fl o Ar property Ns = Ns Ar value
2063 Sets the specified property; see
2064 .Nm zfs Cm create
2065 for details.
2066 .It Fl r
2067 Recursively create snapshots of all descendent datasets
2068 .El
2069 .It Xo
2070 .Nm
2071 .Cm rollback
2072 .Op Fl Rfr
2073 .Ar snapshot
2074 .Xc
2075 Roll back the given dataset to a previous snapshot.
2076 When a dataset is rolled back, all data that has changed since the snapshot is
2077 discarded, and the dataset reverts to the state at the time of the snapshot.
2078 By default, the command refuses to roll back to a snapshot other than the most
2079 recent one.
2080 In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2081 specifying the
2082 .Fl r
2083 option.
2084 .Pp
2085 The
2086 .Fl rR
2087 options do not recursively destroy the child snapshots of a recursive snapshot.
2088 Only direct snapshots of the specified filesystem are destroyed by either of
2089 these options.
2090 To completely roll back a recursive snapshot, you must rollback the individual
2091 child snapshots.
2092 .Bl -tag -width "-R"
2093 .It Fl R
2094 Destroy any more recent snapshots and bookmarks, as well as any clones of those
2095 snapshots.
2096 .It Fl f
2097 Used with the
2098 .Fl R
2099 option to force an unmount of any clone file systems that are to be destroyed.
2100 .It Fl r
2101 Destroy any snapshots and bookmarks more recent than the one specified.
2102 .El
2103 .It Xo
2104 .Nm
2105 .Cm clone
2106 .Op Fl p
2107 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2108 .Ar snapshot Ar filesystem Ns | Ns Ar volume
2109 .Xc
2110 Creates a clone of the given snapshot.
2111 See the
2112 .Sx Clones
2113 section for details.
2114 The target dataset can be located anywhere in the ZFS hierarchy, and is created
2115 as the same type as the original.
2116 .Bl -tag -width "-o"
2117 .It Fl o Ar property Ns = Ns Ar value
2118 Sets the specified property; see
2119 .Nm zfs Cm create
2120 for details.
2121 .It Fl p
2122 Creates all the non-existing parent datasets.
2123 Datasets created in this manner are automatically mounted according to the
2124 .Sy mountpoint
2125 property inherited from their parent.
2126 If the target filesystem or volume already exists, the operation completes
2127 successfully.
2128 .El
2129 .It Xo
2130 .Nm
2131 .Cm promote
2132 .Ar clone-filesystem
2133 .Xc
2134 Promotes a clone file system to no longer be dependent on its
2135 .Qq origin
2136 snapshot.
2137 This makes it possible to destroy the file system that the clone was created
2138 from.
2139 The clone parent-child dependency relationship is reversed, so that the origin
2140 file system becomes a clone of the specified file system.
2141 .Pp
2142 The snapshot that was cloned, and any snapshots previous to this snapshot, are
2143 now owned by the promoted clone.
2144 The space they use moves from the origin file system to the promoted clone, so
2145 enough space must be available to accommodate these snapshots.
2146 No new space is consumed by this operation, but the space accounting is
2147 adjusted.
2148 The promoted clone must not have any conflicting snapshot names of its own.
2149 The
2150 .Cm rename
2151 subcommand can be used to rename any conflicting snapshots.
2152 .It Xo
2153 .Nm
2154 .Cm rename
2155 .Op Fl f
2156 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2157 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2158 .Xc
2159 .It Xo
2160 .Nm
2161 .Cm rename
2162 .Op Fl fp
2163 .Ar filesystem Ns | Ns Ar volume
2164 .Ar filesystem Ns | Ns Ar volume
2165 .Xc
2166 Renames the given dataset.
2167 The new target can be located anywhere in the ZFS hierarchy, with the exception
2168 of snapshots.
2169 Snapshots can only be renamed within the parent file system or volume.
2170 When renaming a snapshot, the parent file system of the snapshot does not need
2171 to be specified as part of the second argument.
2172 Renamed file systems can inherit new mount points, in which case they are
2173 unmounted and remounted at the new mount point.
2174 .Bl -tag -width "-a"
2175 .It Fl f
2176 Force unmount any filesystems that need to be unmounted in the process.
2177 .It Fl p
2178 Creates all the nonexistent parent datasets.
2179 Datasets created in this manner are automatically mounted according to the
2180 .Sy mountpoint
2181 property inherited from their parent.
2182 .El
2183 .It Xo
2184 .Nm
2185 .Cm rename
2186 .Fl r
2187 .Ar snapshot Ar snapshot
2188 .Xc
2189 Recursively rename the snapshots of all descendent datasets.
2190 Snapshots are the only dataset that can be renamed recursively.
2191 .It Xo
2192 .Nm
2193 .Cm list
2194 .Op Fl r Ns | Ns Fl d Ar depth
2195 .Op Fl Hp
2196 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2197 .Oo Fl s Ar property Oc Ns ...
2198 .Oo Fl S Ar property Oc Ns ...
2199 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2200 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2201 .Xc
2202 Lists the property information for the given datasets in tabular form.
2203 If specified, you can list property information by the absolute pathname or the
2204 relative pathname.
2205 By default, all file systems and volumes are displayed.
2206 Snapshots are displayed if the
2207 .Sy listsnaps
2208 property is
2209 .Sy on
2210 .Po the default is
2211 .Sy off
2212 .Pc .
2213 The following fields are displayed,
2214 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2215 .Sy mountpoint .
2216 .Bl -tag -width "-H"
2217 .It Fl H
2218 Used for scripting mode.
2219 Do not print headers and separate fields by a single tab instead of arbitrary
2220 white space.
2221 .It Fl S Ar property
2222 Same as the
2223 .Fl s
2224 option, but sorts by property in descending order.
2225 .It Fl d Ar depth
2226 Recursively display any children of the dataset, limiting the recursion to
2227 .Ar depth .
2228 A
2229 .Ar depth
2230 of
2231 .Sy 1
2232 will display only the dataset and its direct children.
2233 .It Fl o Ar property
2234 A comma-separated list of properties to display.
2235 The property must be:
2236 .Bl -bullet
2237 .It
2238 One of the properties described in the
2239 .Sx Native Properties
2240 section
2241 .It
2242 A user property
2243 .It
2244 The value
2245 .Sy name
2246 to display the dataset name
2247 .It
2248 The value
2249 .Sy space
2250 to display space usage properties on file systems and volumes.
2251 This is a shortcut for specifying
2252 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2253 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2254 .Sy filesystem Ns \&, Ns Sy volume
2255 syntax.
2256 .El
2257 .It Fl p
2258 Display numbers in parsable
2259 .Pq exact
2260 values.
2261 .It Fl r
2262 Recursively display any children of the dataset on the command line.
2263 .It Fl s Ar property
2264 A property for sorting the output by column in ascending order based on the
2265 value of the property.
2266 The property must be one of the properties described in the
2267 .Sx Properties
2268 section, or the special value
2269 .Sy name
2270 to sort by the dataset name.
2271 Multiple properties can be specified at one time using multiple
2272 .Fl s
2273 property options.
2274 Multiple
2275 .Fl s
2276 options are evaluated from left to right in decreasing order of importance.
2277 The following is a list of sorting criteria:
2278 .Bl -bullet
2279 .It
2280 Numeric types sort in numeric order.
2281 .It
2282 String types sort in alphabetical order.
2283 .It
2284 Types inappropriate for a row sort that row to the literal bottom, regardless of
2285 the specified ordering.
2286 .El
2287 .Pp
2288 If no sorting options are specified the existing behavior of
2289 .Nm zfs Cm list
2290 is preserved.
2291 .It Fl t Ar type
2292 A comma-separated list of types to display, where
2293 .Ar type
2294 is one of
2295 .Sy filesystem ,
2296 .Sy snapshot ,
2297 .Sy volume ,
2298 .Sy bookmark ,
2299 or
2300 .Sy all .
2301 For example, specifying
2302 .Fl t Sy snapshot
2303 displays only snapshots.
2304 .El
2305 .It Xo
2306 .Nm
2307 .Cm set
2308 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2309 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2310 .Xc
2311 Sets the property or list of properties to the given value(s) for each dataset.
2312 Only some properties can be edited.
2313 See the
2314 .Sx Properties
2315 section for more information on what properties can be set and acceptable
2316 values.
2317 Numeric values can be specified as exact values, or in a human-readable form
2318 with a suffix of
2319 .Sy B , K , M , G , T , P , E , Z
2320 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2321 or zettabytes, respectively
2322 .Pc .
2323 User properties can be set on snapshots.
2324 For more information, see the
2325 .Sx User Properties
2326 section.
2327 .It Xo
2328 .Nm
2329 .Cm get
2330 .Op Fl r Ns | Ns Fl d Ar depth
2331 .Op Fl Hp
2332 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2333 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2334 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2335 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2336 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2337 .Xc
2338 Displays properties for the given datasets.
2339 If no datasets are specified, then the command displays properties for all
2340 datasets on the system.
2341 For each property, the following columns are displayed:
2342 .Bd -literal
2343 name Dataset name
2344 property Property name
2345 value Property value
2346 source Property source. Can either be local, default,
2347 temporary, inherited, or none (-).
2348 .Ed
2349 .Pp
2350 All columns are displayed by default, though this can be controlled by using the
2351 .Fl o
2352 option.
2353 This command takes a comma-separated list of properties as described in the
2354 .Sx Native Properties
2355 and
2356 .Sx User Properties
2357 sections.
2358 .Pp
2359 The special value
2360 .Sy all
2361 can be used to display all properties that apply to the given dataset's type
2362 .Pq filesystem, volume, snapshot, or bookmark .
2363 .Bl -tag -width "-H"
2364 .It Fl H
2365 Display output in a form more easily parsed by scripts.
2366 Any headers are omitted, and fields are explicitly separated by a single tab
2367 instead of an arbitrary amount of space.
2368 .It Fl d Ar depth
2369 Recursively display any children of the dataset, limiting the recursion to
2370 .Ar depth .
2371 A depth of
2372 .Sy 1
2373 will display only the dataset and its direct children.
2374 .It Fl o Ar field
2375 A comma-separated list of columns to display.
2376 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2377 is the default value.
2378 .It Fl p
2379 Display numbers in parsable
2380 .Pq exact
2381 values.
2382 .It Fl r
2383 Recursively display properties for any children.
2384 .It Fl s Ar source
2385 A comma-separated list of sources to display.
2386 Those properties coming from a source other than those in this list are ignored.
2387 Each source must be one of the following:
2388 .Sy local ,
2389 .Sy default ,
2390 .Sy inherited ,
2391 .Sy temporary ,
2392 and
2393 .Sy none .
2394 The default value is all sources.
2395 .It Fl t Ar type
2396 A comma-separated list of types to display, where
2397 .Ar type
2398 is one of
2399 .Sy filesystem ,
2400 .Sy snapshot ,
2401 .Sy volume ,
2402 .Sy bookmark ,
2403 or
2404 .Sy all .
2405 .El
2406 .It Xo
2407 .Nm
2408 .Cm inherit
2409 .Op Fl rS
2410 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2411 .Xc
2412 Clears the specified property, causing it to be inherited from an ancestor,
2413 restored to default if no ancestor has the property set, or with the
2414 .Fl S
2415 option reverted to the received value if one exists.
2416 See the
2417 .Sx Properties
2418 section for a listing of default values, and details on which properties can be
2419 inherited.
2420 .Bl -tag -width "-r"
2421 .It Fl r
2422 Recursively inherit the given property for all children.
2423 .It Fl S
2424 Revert the property to the received value if one exists; otherwise operate as
2425 if the
2426 .Fl S
2427 option was not specified.
2428 .El
2429 .It Xo
2430 .Nm
2431 .Cm remap
2432 .Ar filesystem Ns | Ns Ar volume
2433 .Xc
2434 Remap the indirect blocks in the given fileystem or volume so that they no
2435 longer reference blocks on previously removed vdevs and we can eventually
2436 shrink the size of the indirect mapping objects for the previously removed
2437 vdevs. Note that remapping all blocks might not be possible and that
2438 references from snapshots will still exist and cannot be remapped.
2439 .It Xo
2440 .Nm
2441 .Cm upgrade
2442 .Xc
2443 Displays a list of file systems that are not the most recent version.
2444 .It Xo
2445 .Nm
2446 .Cm upgrade
2447 .Fl v
2448 .Xc
2449 Displays a list of currently supported file system versions.
2450 .It Xo
2451 .Nm
2452 .Cm upgrade
2453 .Op Fl r
2454 .Op Fl V Ar version
2455 .Fl a | Ar filesystem
2456 .Xc
2457 Upgrades file systems to a new on-disk version.
2458 Once this is done, the file systems will no longer be accessible on systems
2459 running older versions of the software.
2460 .Nm zfs Cm send
2461 streams generated from new snapshots of these file systems cannot be accessed on
2462 systems running older versions of the software.
2463 .Pp
2464 In general, the file system version is independent of the pool version.
2465 See
2466 .Xr zpool 1M
2467 for information on the
2468 .Nm zpool Cm upgrade
2469 command.
2470 .Pp
2471 In some cases, the file system version and the pool version are interrelated and
2472 the pool version must be upgraded before the file system version can be
2473 upgraded.
2474 .Bl -tag -width "-V"
2475 .It Fl V Ar version
2476 Upgrade to the specified
2477 .Ar version .
2478 If the
2479 .Fl V
2480 flag is not specified, this command upgrades to the most recent version.
2481 This
2482 option can only be used to increase the version number, and only up to the most
2483 recent version supported by this software.
2484 .It Fl a
2485 Upgrade all file systems on all imported pools.
2486 .It Ar filesystem
2487 Upgrade the specified file system.
2488 .It Fl r
2489 Upgrade the specified file system and all descendent file systems.
2490 .El
2491 .It Xo
2492 .Nm
2493 .Cm userspace
2494 .Op Fl Hinp
2495 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2496 .Oo Fl s Ar field Oc Ns ...
2497 .Oo Fl S Ar field Oc Ns ...
2498 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2499 .Ar filesystem Ns | Ns Ar snapshot
2500 .Xc
2501 Displays space consumed by, and quotas on, each user in the specified filesystem
2502 or snapshot.
2503 This corresponds to the
2504 .Sy userused@ Ns Em user
2505 and
2506 .Sy userquota@ Ns Em user
2507 properties.
2508 .Bl -tag -width "-H"
2509 .It Fl H
2510 Do not print headers, use tab-delimited output.
2511 .It Fl S Ar field
2512 Sort by this field in reverse order.
2513 See
2514 .Fl s .
2515 .It Fl i
2516 Translate SID to POSIX ID.
2517 The POSIX ID may be ephemeral if no mapping exists.
2518 Normal POSIX interfaces
2519 .Po for example,
2520 .Xr stat 2 ,
2521 .Nm ls Fl l
2522 .Pc
2523 perform this translation, so the
2524 .Fl i
2525 option allows the output from
2526 .Nm zfs Cm userspace
2527 to be compared directly with those utilities.
2528 However,
2529 .Fl i
2530 may lead to confusion if some files were created by an SMB user before a
2531 SMB-to-POSIX name mapping was established.
2532 In such a case, some files will be owned by the SMB entity and some by the POSIX
2533 entity.
2534 However, the
2535 .Fl i
2536 option will report that the POSIX entity has the total usage and quota for both.
2537 .It Fl n
2538 Print numeric ID instead of user/group name.
2539 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2540 Display only the specified fields from the following set:
2541 .Sy type ,
2542 .Sy name ,
2543 .Sy used ,
2544 .Sy quota .
2545 The default is to display all fields.
2546 .It Fl p
2547 Use exact
2548 .Pq parsable
2549 numeric output.
2550 .It Fl s Ar field
2551 Sort output by this field.
2552 The
2553 .Fl s
2554 and
2555 .Fl S
2556 flags may be specified multiple times to sort first by one field, then by
2557 another.
2558 The default is
2559 .Fl s Sy type Fl s Sy name .
2560 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2561 Print only the specified types from the following set:
2562 .Sy all ,
2563 .Sy posixuser ,
2564 .Sy smbuser ,
2565 .Sy posixgroup ,
2566 .Sy smbgroup .
2567 The default is
2568 .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
2569 The default can be changed to include group types.
2570 .El
2571 .It Xo
2572 .Nm
2573 .Cm groupspace
2574 .Op Fl Hinp
2575 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2576 .Oo Fl s Ar field Oc Ns ...
2577 .Oo Fl S Ar field Oc Ns ...
2578 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2579 .Ar filesystem Ns | Ns Ar snapshot
2580 .Xc
2581 Displays space consumed by, and quotas on, each group in the specified
2582 filesystem or snapshot.
2583 This subcommand is identical to
2584 .Nm zfs Cm userspace ,
2585 except that the default types to display are
2586 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
2587 .It Xo
2588 .Nm
2589 .Cm mount
2590 .Xc
2591 Displays all ZFS file systems currently mounted.
2592 .It Xo
2593 .Nm
2594 .Cm mount
2595 .Op Fl Ov
2596 .Op Fl o Ar options
2597 .Fl a | Ar filesystem
2598 .Xc
2599 Mounts ZFS file systems.
2600 .Bl -tag -width "-O"
2601 .It Fl O
2602 Perform an overlay mount.
2603 See
2604 .Xr mount 1M
2605 for more information.
2606 .It Fl a
2607 Mount all available ZFS file systems.
2608 Invoked automatically as part of the boot process.
2609 .It Ar filesystem
2610 Mount the specified filesystem.
2611 .It Fl o Ar options
2612 An optional, comma-separated list of mount options to use temporarily for the
2613 duration of the mount.
2614 See the
2615 .Sx Temporary Mount Point Properties
2616 section for details.
2617 .It Fl v
2618 Report mount progress.
2619 .El
2620 .It Xo
2621 .Nm
2622 .Cm unmount
2623 .Op Fl f
2624 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2625 .Xc
2626 Unmounts currently mounted ZFS file systems.
2627 .Bl -tag -width "-a"
2628 .It Fl a
2629 Unmount all available ZFS file systems.
2630 Invoked automatically as part of the shutdown process.
2631 .It Ar filesystem Ns | Ns Ar mountpoint
2632 Unmount the specified filesystem.
2633 The command can also be given a path to a ZFS file system mount point on the
2634 system.
2635 .It Fl f
2636 Forcefully unmount the file system, even if it is currently in use.
2637 .El
2638 .It Xo
2639 .Nm
2640 .Cm share
2641 .Fl a | Ar filesystem
2642 .Xc
2643 Shares available ZFS file systems.
2644 .Bl -tag -width "-a"
2645 .It Fl a
2646 Share all available ZFS file systems.
2647 Invoked automatically as part of the boot process.
2648 .It Ar filesystem
2649 Share the specified filesystem according to the
2650 .Sy sharenfs
2651 and
2652 .Sy sharesmb
2653 properties.
2654 File systems are shared when the
2655 .Sy sharenfs
2656 or
2657 .Sy sharesmb
2658 property is set.
2659 .El
2660 .It Xo
2661 .Nm
2662 .Cm unshare
2663 .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2664 .Xc
2665 Unshares currently shared ZFS file systems.
2666 .Bl -tag -width "-a"
2667 .It Fl a
2668 Unshare all available ZFS file systems.
2669 Invoked automatically as part of the shutdown process.
2670 .It Ar filesystem Ns | Ns Ar mountpoint
2671 Unshare the specified filesystem.
2672 The command can also be given a path to a ZFS file system shared on the system.
2673 .El
2674 .It Xo
2675 .Nm
2676 .Cm bookmark
2677 .Ar snapshot bookmark
2678 .Xc
2679 Creates a bookmark of the given snapshot.
2680 Bookmarks mark the point in time when the snapshot was created, and can be used
2681 as the incremental source for a
2682 .Nm zfs Cm send
2683 command.
2684 .Pp
2685 This feature must be enabled to be used.
2686 See
2687 .Xr zpool-features 5
2688 for details on ZFS feature flags and the
2689 .Sy bookmarks
2690 feature.
2691 .It Xo
2692 .Nm
2693 .Cm send
2694 .Op Fl DLPRcenpv
2695 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2696 .Ar snapshot
2697 .Xc
2698 Creates a stream representation of the second
2699 .Ar snapshot ,
2700 which is written to standard output.
2701 The output can be redirected to a file or to a different system
2702 .Po for example, using
2703 .Xr ssh 1
2704 .Pc .
2705 By default, a full stream is generated.
2706 .Bl -tag -width "-D"
2707 .It Fl D, -dedup
2708 Generate a deduplicated stream.
2709 Blocks which would have been sent multiple times in the send stream will only be
2710 sent once.
2711 The receiving system must also support this feature to receive a deduplicated
2712 stream.
2713 This flag can be used regardless of the dataset's
2714 .Sy dedup
2715 property, but performance will be much better if the filesystem uses a
2716 dedup-capable checksum
2717 .Po for example,
2718 .Sy sha256
2719 .Pc .
2720 .It Fl I Ar snapshot
2721 Generate a stream package that sends all intermediary snapshots from the first
2722 snapshot to the second snapshot.
2723 For example,
2724 .Fl I Em @a Em fs@d
2725 is similar to
2726 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
2727 The incremental source may be specified as with the
2728 .Fl i
2729 option.
2730 .It Fl L, -large-block
2731 Generate a stream which may contain blocks larger than 128KB.
2732 This flag has no effect if the
2733 .Sy large_blocks
2734 pool feature is disabled, or if the
2735 .Sy recordsize
2736 property of this filesystem has never been set above 128KB.
2737 The receiving system must have the
2738 .Sy large_blocks
2739 pool feature enabled as well.
2740 See
2741 .Xr zpool-features 5
2742 for details on ZFS feature flags and the
2743 .Sy large_blocks
2744 feature.
2745 .It Fl P, -parsable
2746 Print machine-parsable verbose information about the stream package generated.
2747 .It Fl R, -replicate
2748 Generate a replication stream package, which will replicate the specified
2749 file system, and all descendent file systems, up to the named snapshot.
2750 When received, all properties, snapshots, descendent file systems, and clones
2751 are preserved.
2752 .Pp
2753 If the
2754 .Fl i
2755 or
2756 .Fl I
2757 flags are used in conjunction with the
2758 .Fl R
2759 flag, an incremental replication stream is generated.
2760 The current values of properties, and current snapshot and file system names are
2761 set when the stream is received.
2762 If the
2763 .Fl F
2764 flag is specified when this stream is received, snapshots and file systems that
2765 do not exist on the sending side are destroyed.
2766 .It Fl e, -embed
2767 Generate a more compact stream by using
2768 .Sy WRITE_EMBEDDED
2769 records for blocks which are stored more compactly on disk by the
2770 .Sy embedded_data
2771 pool feature.
2772 This flag has no effect if the
2773 .Sy embedded_data
2774 feature is disabled.
2775 The receiving system must have the
2776 .Sy embedded_data
2777 feature enabled.
2778 If the
2779 .Sy lz4_compress
2780 feature is active on the sending system, then the receiving system must have
2781 that feature enabled as well.
2782 See
2783 .Xr zpool-features 5
2784 for details on ZFS feature flags and the
2785 .Sy embedded_data
2786 feature.
2787 .It Fl c, -compressed
2788 Generate a more compact stream by using compressed WRITE records for blocks
2789 which are compressed on disk and in memory
2790 .Po see the
2791 .Sy compression
2792 property for details
2793 .Pc .
2794 If the
2795 .Sy lz4_compress
2796 feature is active on the sending system, then the receiving system must have
2797 that feature enabled as well.
2798 If the
2799 .Sy large_blocks
2800 feature is enabled on the sending system but the
2801 .Fl L
2802 option is not supplied in conjunction with
2803 .Fl c ,
2804 then the data will be decompressed before sending so it can be split into
2805 smaller block sizes.
2806 .It Fl i Ar snapshot
2807 Generate an incremental stream from the first
2808 .Ar snapshot
2809 .Pq the incremental source
2810 to the second
2811 .Ar snapshot
2812 .Pq the incremental target .
2813 The incremental source can be specified as the last component of the snapshot
2814 name
2815 .Po the
2816 .Sy @
2817 character and following
2818 .Pc
2819 and it is assumed to be from the same file system as the incremental target.
2820 .Pp
2821 If the destination is a clone, the source may be the origin snapshot, which must
2822 be fully specified
2823 .Po for example,
2824 .Em pool/fs@origin ,
2825 not just
2826 .Em @origin
2827 .Pc .
2828 .It Fl n, -dryrun
2829 Do a dry-run
2830 .Pq Qq No-op
2831 send.
2832 Do not generate any actual send data.
2833 This is useful in conjunction with the
2834 .Fl v
2835 or
2836 .Fl P
2837 flags to determine what data will be sent.
2838 In this case, the verbose output will be written to standard output
2839 .Po contrast with a non-dry-run, where the stream is written to standard output
2840 and the verbose output goes to standard error
2841 .Pc .
2842 .It Fl p, -props
2843 Include the dataset's properties in the stream.
2844 This flag is implicit when
2845 .Fl R
2846 is specified.
2847 The receiving system must also support this feature.
2848 .It Fl v, -verbose
2849 Print verbose information about the stream package generated.
2850 This information includes a per-second report of how much data has been sent.
2851 .Pp
2852 The format of the stream is committed.
2853 You will be able to receive your streams on future versions of ZFS .
2854 .El
2855 .It Xo
2856 .Nm
2857 .Cm send
2858 .Op Fl Lce
2859 .Op Fl i Ar snapshot Ns | Ns Ar bookmark
2860 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2861 .Xc
2862 Generate a send stream, which may be of a filesystem, and may be incremental
2863 from a bookmark.
2864 If the destination is a filesystem or volume, the pool must be read-only, or the
2865 filesystem must not be mounted.
2866 When the stream generated from a filesystem or volume is received, the default
2867 snapshot name will be
2868 .Qq --head-- .
2869 .Bl -tag -width "-L"
2870 .It Fl L, -large-block
2871 Generate a stream which may contain blocks larger than 128KB.
2872 This flag has no effect if the
2873 .Sy large_blocks
2874 pool feature is disabled, or if the
2875 .Sy recordsize
2876 property of this filesystem has never been set above 128KB.
2877 The receiving system must have the
2878 .Sy large_blocks
2879 pool feature enabled as well.
2880 See
2881 .Xr zpool-features 5
2882 for details on ZFS feature flags and the
2883 .Sy large_blocks
2884 feature.
2885 .It Fl c, -compressed
2886 Generate a more compact stream by using compressed WRITE records for blocks
2887 which are compressed on disk and in memory
2888 .Po see the
2889 .Sy compression
2890 property for details
2891 .Pc .
2892 If the
2893 .Sy lz4_compress
2894 feature is active on the sending system, then the receiving system must have
2895 that feature enabled as well.
2896 If the
2897 .Sy large_blocks
2898 feature is enabled on the sending system but the
2899 .Fl L
2900 option is not supplied in conjunction with
2901 .Fl c ,
2902 then the data will be decompressed before sending so it can be split into
2903 smaller block sizes.
2904 .It Fl e, -embed
2905 Generate a more compact stream by using
2906 .Sy WRITE_EMBEDDED
2907 records for blocks which are stored more compactly on disk by the
2908 .Sy embedded_data
2909 pool feature.
2910 This flag has no effect if the
2911 .Sy embedded_data
2912 feature is disabled.
2913 The receiving system must have the
2914 .Sy embedded_data
2915 feature enabled.
2916 If the
2917 .Sy lz4_compress
2918 feature is active on the sending system, then the receiving system must have
2919 that feature enabled as well.
2920 See
2921 .Xr zpool-features 5
2922 for details on ZFS feature flags and the
2923 .Sy embedded_data
2924 feature.
2925 .It Fl i Ar snapshot Ns | Ns Ar bookmark
2926 Generate an incremental send stream.
2927 The incremental source must be an earlier snapshot in the destination's history.
2928 It will commonly be an earlier snapshot in the destination's file system, in
2929 which case it can be specified as the last component of the name
2930 .Po the
2931 .Sy #
2932 or
2933 .Sy @
2934 character and following
2935 .Pc .
2936 .Pp
2937 If the incremental target is a clone, the incremental source can be the origin
2938 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
2939 origin, etc.
2940 .El
2941 .It Xo
2942 .Nm
2943 .Cm send
2944 .Op Fl Penv
2945 .Fl t
2946 .Ar receive_resume_token
2947 .Xc
2948 Creates a send stream which resumes an interrupted receive.
2949 The
2950 .Ar receive_resume_token
2951 is the value of this property on the filesystem or volume that was being
2952 received into.
2953 See the documentation for
2954 .Sy zfs receive -s
2955 for more details.
2956 .It Xo
2957 .Nm
2958 .Cm receive
2959 .Op Fl Fnsuv
2960 .Op Fl o Sy origin Ns = Ns Ar snapshot
2961 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2962 .Xc
2963 .It Xo
2964 .Nm
2965 .Cm receive
2966 .Op Fl Fnsuv
2967 .Op Fl d Ns | Ns Fl e
2968 .Op Fl o Sy origin Ns = Ns Ar snapshot
2969 .Ar filesystem
2970 .Xc
2971 Creates a snapshot whose contents are as specified in the stream provided on
2972 standard input.
2973 If a full stream is received, then a new file system is created as well.
2974 Streams are created using the
2975 .Nm zfs Cm send
2976 subcommand, which by default creates a full stream.
2977 .Nm zfs Cm recv
2978 can be used as an alias for
2979 .Nm zfs Cm receive.
2980 .Pp
2981 If an incremental stream is received, then the destination file system must
2982 already exist, and its most recent snapshot must match the incremental stream's
2983 source.
2984 For
2985 .Sy zvols ,
2986 the destination device link is destroyed and recreated, which means the
2987 .Sy zvol
2988 cannot be accessed during the
2989 .Cm receive
2990 operation.
2991 .Pp
2992 When a snapshot replication package stream that is generated by using the
2993 .Nm zfs Cm send Fl R
2994 command is received, any snapshots that do not exist on the sending location are
2995 destroyed by using the
2996 .Nm zfs Cm destroy Fl d
2997 command.
2998 .Pp
2999 The name of the snapshot
3000 .Pq and file system, if a full stream is received
3001 that this subcommand creates depends on the argument type and the use of the
3002 .Fl d
3003 or
3004 .Fl e
3005 options.
3006 .Pp
3007 If the argument is a snapshot name, the specified
3008 .Ar snapshot
3009 is created.
3010 If the argument is a file system or volume name, a snapshot with the same name
3011 as the sent snapshot is created within the specified
3012 .Ar filesystem
3013 or
3014 .Ar volume .
3015 If neither of the
3016 .Fl d
3017 or
3018 .Fl e
3019 options are specified, the provided target snapshot name is used exactly as
3020 provided.
3021 .Pp
3022 The
3023 .Fl d
3024 and
3025 .Fl e
3026 options cause the file system name of the target snapshot to be determined by
3027 appending a portion of the sent snapshot's name to the specified target
3028 .Ar filesystem .
3029 If the
3030 .Fl d
3031 option is specified, all but the first element of the sent snapshot's file
3032 system path
3033 .Pq usually the pool name
3034 is used and any required intermediate file systems within the specified one are
3035 created.
3036 If the
3037 .Fl e
3038 option is specified, then only the last element of the sent snapshot's file
3039 system name
3040 .Pq i.e. the name of the source file system itself
3041 is used as the target file system name.
3042 .Bl -tag -width "-F"
3043 .It Fl F
3044 Force a rollback of the file system to the most recent snapshot before
3045 performing the receive operation.
3046 If receiving an incremental replication stream
3047 .Po for example, one generated by
3048 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3049 .Pc ,
3050 destroy snapshots and file systems that do not exist on the sending side.
3051 .It Fl d
3052 Discard the first element of the sent snapshot's file system name, using the
3053 remaining elements to determine the name of the target file system for the new
3054 snapshot as described in the paragraph above.
3055 .It Fl e
3056 Discard all but the last element of the sent snapshot's file system name, using
3057 that element to determine the name of the target file system for the new
3058 snapshot as described in the paragraph above.
3059 .It Fl n
3060 Do not actually receive the stream.
3061 This can be useful in conjunction with the
3062 .Fl v
3063 option to verify the name the receive operation would use.
3064 .It Fl o Sy origin Ns = Ns Ar snapshot
3065 Forces the stream to be received as a clone of the given snapshot.
3066 If the stream is a full send stream, this will create the filesystem
3067 described by the stream as a clone of the specified snapshot.
3068 Which snapshot was specified will not affect the success or failure of the
3069 receive, as long as the snapshot does exist.
3070 If the stream is an incremental send stream, all the normal verification will be
3071 performed.
3072 .It Fl u
3073 File system that is associated with the received stream is not mounted.
3074 .It Fl v
3075 Print verbose information about the stream and the time required to perform the
3076 receive operation.
3077 .It Fl s
3078 If the receive is interrupted, save the partially received state, rather
3079 than deleting it.
3080 Interruption may be due to premature termination of the stream
3081 .Po e.g. due to network failure or failure of the remote system
3082 if the stream is being read over a network connection
3083 .Pc ,
3084 a checksum error in the stream, termination of the
3085 .Nm zfs Cm receive
3086 process, or unclean shutdown of the system.
3087 .Pp
3088 The receive can be resumed with a stream generated by
3089 .Nm zfs Cm send Fl t Ar token ,
3090 where the
3091 .Ar token
3092 is the value of the
3093 .Sy receive_resume_token
3094 property of the filesystem or volume which is received into.
3095 .Pp
3096 To use this flag, the storage pool must have the
3097 .Sy extensible_dataset
3098 feature enabled.
3099 See
3100 .Xr zpool-features 5
3101 for details on ZFS feature flags.
3102 .El
3103 .It Xo
3104 .Nm
3105 .Cm receive
3106 .Fl A
3107 .Ar filesystem Ns | Ns Ar volume
3108 .Xc
3109 Abort an interrupted
3110 .Nm zfs Cm receive Fl s ,
3111 deleting its saved partially received state.
3112 .It Xo
3113 .Nm
3114 .Cm allow
3115 .Ar filesystem Ns | Ns Ar volume
3116 .Xc
3117 Displays permissions that have been delegated on the specified filesystem or
3118 volume.
3119 See the other forms of
3120 .Nm zfs Cm allow
3121 for more information.
3122 .It Xo
3123 .Nm
3124 .Cm allow
3125 .Op Fl dglu
3126 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3127 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3128 .Ar setname Oc Ns ...
3129 .Ar filesystem Ns | Ns Ar volume
3130 .br
3131 .Nm
3132 .Cm allow
3133 .Op Fl dl
3134 .Fl e Ns | Ns Sy everyone
3135 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3136 .Ar setname Oc Ns ...
3137 .Ar filesystem Ns | Ns Ar volume
3138 .Xc
3139 Delegates ZFS administration permission for the file systems to non-privileged
3140 users.
3141 .Bl -tag -width "-d"
3142 .It Fl d
3143 Allow only for the descendent file systems.
3144 .It Fl e Ns | Ns Sy everyone
3145 Specifies that the permissions be delegated to everyone.
3146 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3147 Explicitly specify that permissions are delegated to the group.
3148 .It Fl l
3149 Allow
3150 .Qq locally
3151 only for the specified file system.
3152 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3153 Explicitly specify that permissions are delegated to the user.
3154 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3155 Specifies to whom the permissions are delegated.
3156 Multiple entities can be specified as a comma-separated list.
3157 If neither of the
3158 .Fl gu
3159 options are specified, then the argument is interpreted preferentially as the
3160 keyword
3161 .Sy everyone ,
3162 then as a user name, and lastly as a group name.
3163 To specify a user or group named
3164 .Qq everyone ,
3165 use the
3166 .Fl g
3167 or
3168 .Fl u
3169 options.
3170 To specify a group with the same name as a user, use the
3171 .Fl g
3172 options.
3173 .It Xo
3174 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3175 .Ar setname Oc Ns ...
3176 .Xc
3177 The permissions to delegate.
3178 Multiple permissions may be specified as a comma-separated list.
3179 Permission names are the same as ZFS subcommand and property names.
3180 See the property list below.
3181 Property set names, which begin with
3182 .Sy @ ,
3183 may be specified.
3184 See the
3185 .Fl s
3186 form below for details.
3187 .El
3188 .Pp
3189 If neither of the
3190 .Fl dl
3191 options are specified, or both are, then the permissions are allowed for the
3192 file system or volume, and all of its descendents.
3193 .Pp
3194 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3195 property.
3196 The following permissions are available:
3197 .Bd -literal
3198 NAME TYPE NOTES
3199 allow subcommand Must also have the permission that is
3200 being allowed
3201 clone subcommand Must also have the 'create' ability and
3202 'mount' ability in the origin file system
3203 create subcommand Must also have the 'mount' ability
3204 destroy subcommand Must also have the 'mount' ability
3205 diff subcommand Allows lookup of paths within a dataset
3206 given an object number, and the ability
3207 to create snapshots necessary to
3208 'zfs diff'.
3209 mount subcommand Allows mount/umount of ZFS datasets
3210 promote subcommand Must also have the 'mount' and 'promote'
3211 ability in the origin file system
3212 receive subcommand Must also have the 'mount' and 'create'
3213 ability
3214 rename subcommand Must also have the 'mount' and 'create'
3215 ability in the new parent
3216 rollback subcommand Must also have the 'mount' ability
3217 send subcommand
3218 share subcommand Allows sharing file systems over NFS
3219 or SMB protocols
3220 snapshot subcommand Must also have the 'mount' ability
3221
3222 groupquota other Allows accessing any groupquota@...
3223 property
3224 groupused other Allows reading any groupused@... property
3225 userprop other Allows changing any user property
3226 userquota other Allows accessing any userquota@...
3227 property
3228 userused other Allows reading any userused@... property
3229
3230 aclinherit property
3231 aclmode property
3232 atime property
3233 canmount property
3234 casesensitivity property
3235 checksum property
3236 compression property
3237 copies property
3238 devices property
3239 exec property
3240 filesystem_limit property
3241 mountpoint property
3242 nbmand property
3243 normalization property
3244 primarycache property
3245 quota property
3246 readonly property
3247 recordsize property
3248 refquota property
3249 refreservation property
3250 reservation property
3251 secondarycache property
3252 setuid property
3253 sharenfs property
3254 sharesmb property
3255 snapdir property
3256 snapshot_limit property
3257 utf8only property
3258 version property
3259 volblocksize property
3260 volsize property
3261 vscan property
3262 xattr property
3263 zoned property
3264 .Ed
3265 .It Xo
3266 .Nm
3267 .Cm allow
3268 .Fl c
3269 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3270 .Ar setname Oc Ns ...
3271 .Ar filesystem Ns | Ns Ar volume
3272 .Xc
3273 Sets
3274 .Qq create time
3275 permissions.
3276 These permissions are granted
3277 .Pq locally
3278 to the creator of any newly-created descendent file system.
3279 .It Xo
3280 .Nm
3281 .Cm allow
3282 .Fl s No @ Ns Ar setname
3283 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3284 .Ar setname Oc Ns ...
3285 .Ar filesystem Ns | Ns Ar volume
3286 .Xc
3287 Defines or adds permissions to a permission set.
3288 The set can be used by other
3289 .Nm zfs Cm allow
3290 commands for the specified file system and its descendents.
3291 Sets are evaluated dynamically, so changes to a set are immediately reflected.
3292 Permission sets follow the same naming restrictions as ZFS file systems, but the
3293 name must begin with
3294 .Sy @ ,
3295 and can be no more than 64 characters long.
3296 .It Xo
3297 .Nm
3298 .Cm unallow
3299 .Op Fl dglru
3300 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3301 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3302 .Ar setname Oc Ns ... Oc
3303 .Ar filesystem Ns | Ns Ar volume
3304 .br
3305 .Nm
3306 .Cm unallow
3307 .Op Fl dlr
3308 .Fl e Ns | Ns Sy everyone
3309 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3310 .Ar setname Oc Ns ... Oc
3311 .Ar filesystem Ns | Ns Ar volume
3312 .br
3313 .Nm
3314 .Cm unallow
3315 .Op Fl r
3316 .Fl c
3317 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3318 .Ar setname Oc Ns ... Oc
3319 .Ar filesystem Ns | Ns Ar volume
3320 .Xc
3321 Removes permissions that were granted with the
3322 .Nm zfs Cm allow
3323 command.
3324 No permissions are explicitly denied, so other permissions granted are still in
3325 effect.
3326 For example, if the permission is granted by an ancestor.
3327 If no permissions are specified, then all permissions for the specified
3328 .Ar user ,
3329 .Ar group ,
3330 or
3331 .Sy everyone
3332 are removed.
3333 Specifying
3334 .Sy everyone
3335 .Po or using the
3336 .Fl e
3337 option
3338 .Pc
3339 only removes the permissions that were granted to everyone, not all permissions
3340 for every user and group.
3341 See the
3342 .Nm zfs Cm allow
3343 command for a description of the
3344 .Fl ldugec
3345 options.
3346 .Bl -tag -width "-r"
3347 .It Fl r
3348 Recursively remove the permissions from this file system and all descendents.
3349 .El
3350 .It Xo
3351 .Nm
3352 .Cm unallow
3353 .Op Fl r
3354 .Fl s No @ Ns Ar setname
3355 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3356 .Ar setname Oc Ns ... Oc
3357 .Ar filesystem Ns | Ns Ar volume
3358 .Xc
3359 Removes permissions from a permission set.
3360 If no permissions are specified, then all permissions are removed, thus removing
3361 the set entirely.
3362 .It Xo
3363 .Nm
3364 .Cm hold
3365 .Op Fl r
3366 .Ar tag Ar snapshot Ns ...
3367 .Xc
3368 Adds a single reference, named with the
3369 .Ar tag
3370 argument, to the specified snapshot or snapshots.
3371 Each snapshot has its own tag namespace, and tags must be unique within that
3372 space.
3373 .Pp
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 Specifies that a hold with the given tag is applied recursively to the snapshots
3381 of all descendent file systems.
3382 .El
3383 .It Xo
3384 .Nm
3385 .Cm holds
3386 .Op Fl r
3387 .Ar snapshot Ns ...
3388 .Xc
3389 Lists all existing user references for the given snapshot or snapshots.
3390 .Bl -tag -width "-r"
3391 .It Fl r
3392 Lists the holds that are set on the named descendent snapshots, in addition to
3393 listing the holds on the named snapshot.
3394 .El
3395 .It Xo
3396 .Nm
3397 .Cm release
3398 .Op Fl r
3399 .Ar tag Ar snapshot Ns ...
3400 .Xc
3401 Removes a single reference, named with the
3402 .Ar tag
3403 argument, from the specified snapshot or snapshots.
3404 The tag must already exist for each snapshot.
3405 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3406 .Nm zfs Cm destroy
3407 command return
3408 .Er EBUSY .
3409 .Bl -tag -width "-r"
3410 .It Fl r
3411 Recursively releases a hold with the given tag on the snapshots of all
3412 descendent file systems.
3413 .El
3414 .It Xo
3415 .Nm
3416 .Cm diff
3417 .Op Fl FHt
3418 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3419 .Xc
3420 Display the difference between a snapshot of a given filesystem and another
3421 snapshot of that filesystem from a later time or the current contents of the
3422 filesystem.
3423 The first column is a character indicating the type of change, the other columns
3424 indicate pathname, new pathname
3425 .Pq in case of rename ,
3426 change in link count, and optionally file type and/or change time.
3427 The types of change are:
3428 .Bd -literal
3429 - The path has been removed
3430 + The path has been created
3431 M The path has been modified
3432 R The path has been renamed
3433 .Ed
3434 .Bl -tag -width "-F"
3435 .It Fl F
3436 Display an indication of the type of file, in a manner similar to the
3437 .Fl
3438 option of
3439 .Xr ls 1 .
3440 .Bd -literal
3441 B Block device
3442 C Character device
3443 / Directory
3444 > Door
3445 | Named pipe
3446 @ Symbolic link
3447 P Event port
3448 = Socket
3449 F Regular file
3450 .Ed
3451 .It Fl H
3452 Give more parsable tab-separated output, without header lines and without
3453 arrows.
3454 .It Fl t
3455 Display the path's inode change time as the first column of output.
3456 .El
3457 .It Xo
3458 .Nm
3459 .Cm program
3460 .Op Fl n
3461 .Op Fl t Ar timeout
3462 .Op Fl m Ar memory_limit
3463 .Ar pool script
3464 .Op Ar arg1 No ...
3465 .Xc
3466 Executes
3467 .Ar script
3468 as a ZFS channel program on
3469 .Ar pool .
3470 The ZFS channel
3471 program interface allows ZFS administrative operations to be run
3472 programmatically via a Lua script.
3473 The entire script is executed atomically, with no other administrative
3474 operations taking effect concurrently.
3475 A library of ZFS calls is made available to channel program scripts.
3476 Channel programs may only be run with root privileges.
3477 .sp
3478 For full documentation of the ZFS channel program interface, see the manual
3479 page for
3480 .Bl -tag -width ""
3481 .It Fl n
3482 Executes a read-only channel program, which runs faster.
3483 The program cannot change on-disk state by calling functions from
3484 the zfs.sync submodule.
3485 The program can be used to gather information such as properties and
3486 determining if changes would succeed (zfs.check.*).
3487 Without this flag, all pending changes must be synced to disk before
3488 a channel program can complete.
3489 .It Fl t Ar timeout
3490 Execution time limit, in milliseconds.
3491 If a channel program executes for longer than the provided timeout, it will
3492 be stopped and an error will be returned.
3493 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
3494 .It Fl m Ar memory-limit
3495 Memory limit, in bytes.
3496 If a channel program attempts to allocate more memory than the given limit,
3497 it will be stopped and an error returned.
3498 The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
3499 .sp
3500 All remaining argument strings are passed directly to the channel program as
3501 arguments.
3502 See
3503 .Xr zfs-program 1M
3504 for more information.
3505 .El
3506 .El
3507 .Sh EXIT STATUS
3508 The
3509 .Nm
3510 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3511 options were specified.
3512 .Sh EXAMPLES
3513 .Bl -tag -width ""
3514 .It Sy Example 1 No Creating a ZFS File System Hierarchy
3515 The following commands create a file system named
3516 .Em pool/home
3517 and a file system named
3518 .Em pool/home/bob .
3519 The mount point
3520 .Pa /export/home
3521 is set for the parent file system, and is automatically inherited by the child
3522 file system.
3523 .Bd -literal
3524 # zfs create pool/home
3525 # zfs set mountpoint=/export/home pool/home
3526 # zfs create pool/home/bob
3527 .Ed
3528 .It Sy Example 2 No Creating a ZFS Snapshot
3529 The following command creates a snapshot named
3530 .Sy yesterday .
3531 This snapshot is mounted on demand in the
3532 .Pa .zfs/snapshot
3533 directory at the root of the
3534 .Em pool/home/bob
3535 file system.
3536 .Bd -literal
3537 # zfs snapshot pool/home/bob@yesterday
3538 .Ed
3539 .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3540 The following command creates snapshots named
3541 .Sy yesterday
3542 of
3543 .Em pool/home
3544 and all of its descendent file systems.
3545 Each snapshot is mounted on demand in the
3546 .Pa .zfs/snapshot
3547 directory at the root of its file system.
3548 The second command destroys the newly created snapshots.
3549 .Bd -literal
3550 # zfs snapshot -r pool/home@yesterday
3551 # zfs destroy -r pool/home@yesterday
3552 .Ed
3553 .It Sy Example 4 No Disabling and Enabling File System Compression
3554 The following command disables the
3555 .Sy compression
3556 property for all file systems under
3557 .Em pool/home .
3558 The next command explicitly enables
3559 .Sy compression
3560 for
3561 .Em pool/home/anne .
3562 .Bd -literal
3563 # zfs set compression=off pool/home
3564 # zfs set compression=on pool/home/anne
3565 .Ed
3566 .It Sy Example 5 No Listing ZFS Datasets
3567 The following command lists all active file systems and volumes in the system.
3568 Snapshots are displayed if the
3569 .Sy listsnaps
3570 property is
3571 .Sy on .
3572 The default is
3573 .Sy off .
3574 See
3575 .Xr zpool 1M
3576 for more information on pool properties.
3577 .Bd -literal
3578 # zfs list
3579 NAME USED AVAIL REFER MOUNTPOINT
3580 pool 450K 457G 18K /pool
3581 pool/home 315K 457G 21K /export/home
3582 pool/home/anne 18K 457G 18K /export/home/anne
3583 pool/home/bob 276K 457G 276K /export/home/bob
3584 .Ed
3585 .It Sy Example 6 No Setting a Quota on a ZFS File System
3586 The following command sets a quota of 50 Gbytes for
3587 .Em pool/home/bob .
3588 .Bd -literal
3589 # zfs set quota=50G pool/home/bob
3590 .Ed
3591 .It Sy Example 7 No Listing ZFS Properties
3592 The following command lists all properties for
3593 .Em pool/home/bob .
3594 .Bd -literal
3595 # zfs get all pool/home/bob
3596 NAME PROPERTY VALUE SOURCE
3597 pool/home/bob type filesystem -
3598 pool/home/bob creation Tue Jul 21 15:53 2009 -
3599 pool/home/bob used 21K -
3600 pool/home/bob available 20.0G -
3601 pool/home/bob referenced 21K -
3602 pool/home/bob compressratio 1.00x -
3603 pool/home/bob mounted yes -
3604 pool/home/bob quota 20G local
3605 pool/home/bob reservation none default
3606 pool/home/bob recordsize 128K default
3607 pool/home/bob mountpoint /pool/home/bob default
3608 pool/home/bob sharenfs off default
3609 pool/home/bob checksum on default
3610 pool/home/bob compression on local
3611 pool/home/bob atime on default
3612 pool/home/bob devices on default
3613 pool/home/bob exec on default
3614 pool/home/bob setuid on default
3615 pool/home/bob readonly off default
3616 pool/home/bob zoned off default
3617 pool/home/bob snapdir hidden default
3618 pool/home/bob aclmode discard default
3619 pool/home/bob aclinherit restricted default
3620 pool/home/bob canmount on default
3621 pool/home/bob xattr on default
3622 pool/home/bob copies 1 default
3623 pool/home/bob version 4 -
3624 pool/home/bob utf8only off -
3625 pool/home/bob normalization none -
3626 pool/home/bob casesensitivity sensitive -
3627 pool/home/bob vscan off default
3628 pool/home/bob nbmand off default
3629 pool/home/bob sharesmb off default
3630 pool/home/bob refquota none default
3631 pool/home/bob refreservation none default
3632 pool/home/bob primarycache all default
3633 pool/home/bob secondarycache all default
3634 pool/home/bob usedbysnapshots 0 -
3635 pool/home/bob usedbydataset 21K -
3636 pool/home/bob usedbychildren 0 -
3637 pool/home/bob usedbyrefreservation 0 -
3638 .Ed
3639 .Pp
3640 The following command gets a single property value.
3641 .Bd -literal
3642 # zfs get -H -o value compression pool/home/bob
3643 on
3644 .Ed
3645 The following command lists all properties with local settings for
3646 .Em pool/home/bob .
3647 .Bd -literal
3648 # zfs get -r -s local -o name,property,value all pool/home/bob
3649 NAME PROPERTY VALUE
3650 pool/home/bob quota 20G
3651 pool/home/bob compression on
3652 .Ed
3653 .It Sy Example 8 No Rolling Back a ZFS File System
3654 The following command reverts the contents of
3655 .Em pool/home/anne
3656 to the snapshot named
3657 .Sy yesterday ,
3658 deleting all intermediate snapshots.
3659 .Bd -literal
3660 # zfs rollback -r pool/home/anne@yesterday
3661 .Ed
3662 .It Sy Example 9 No Creating a ZFS Clone
3663 The following command creates a writable file system whose initial contents are
3664 the same as
3665 .Em pool/home/bob@yesterday .
3666 .Bd -literal
3667 # zfs clone pool/home/bob@yesterday pool/clone
3668 .Ed
3669 .It Sy Example 10 No Promoting a ZFS Clone
3670 The following commands illustrate how to test out changes to a file system, and
3671 then replace the original file system with the changed one, using clones, clone
3672 promotion, and renaming:
3673 .Bd -literal
3674 # zfs create pool/project/production
3675 populate /pool/project/production with data
3676 # zfs snapshot pool/project/production@today
3677 # zfs clone pool/project/production@today pool/project/beta
3678 make changes to /pool/project/beta and test them
3679 # zfs promote pool/project/beta
3680 # zfs rename pool/project/production pool/project/legacy
3681 # zfs rename pool/project/beta pool/project/production
3682 once the legacy version is no longer needed, it can be destroyed
3683 # zfs destroy pool/project/legacy
3684 .Ed
3685 .It Sy Example 11 No Inheriting ZFS Properties
3686 The following command causes
3687 .Em pool/home/bob
3688 and
3689 .Em pool/home/anne
3690 to inherit the
3691 .Sy checksum
3692 property from their parent.
3693 .Bd -literal
3694 # zfs inherit checksum pool/home/bob pool/home/anne
3695 .Ed
3696 .It Sy Example 12 No Remotely Replicating ZFS Data
3697 The following commands send a full stream and then an incremental stream to a
3698 remote machine, restoring them into
3699 .Em poolB/received/fs@a
3700 and
3701 .Em poolB/received/fs@b ,
3702 respectively.
3703 .Em poolB
3704 must contain the file system
3705 .Em poolB/received ,
3706 and must not initially contain
3707 .Em poolB/received/fs .
3708 .Bd -literal
3709 # zfs send pool/fs@a | \e
3710 ssh host zfs receive poolB/received/fs@a
3711 # zfs send -i a pool/fs@b | \e
3712 ssh host zfs receive poolB/received/fs
3713 .Ed
3714 .It Sy Example 13 No Using the zfs receive -d Option
3715 The following command sends a full stream of
3716 .Em poolA/fsA/fsB@snap
3717 to a remote machine, receiving it into
3718 .Em poolB/received/fsA/fsB@snap .
3719 The
3720 .Em fsA/fsB@snap
3721 portion of the received snapshot's name is determined from the name of the sent
3722 snapshot.
3723 .Em poolB
3724 must contain the file system
3725 .Em poolB/received .
3726 If
3727 .Em poolB/received/fsA
3728 does not exist, it is created as an empty file system.
3729 .Bd -literal
3730 # zfs send poolA/fsA/fsB@snap | \e
3731 ssh host zfs receive -d poolB/received
3732 .Ed
3733 .It Sy Example 14 No Setting User Properties
3734 The following example sets the user-defined
3735 .Sy com.example:department
3736 property for a dataset.
3737 .Bd -literal
3738 # zfs set com.example:department=12345 tank/accounting
3739 .Ed
3740 .It Sy Example 15 No Performing a Rolling Snapshot
3741 The following example shows how to maintain a history of snapshots with a
3742 consistent naming scheme.
3743 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
3744 renames the remaining snapshots, and then creates a new snapshot, as follows:
3745 .Bd -literal
3746 # zfs destroy -r pool/users@7daysago
3747 # zfs rename -r pool/users@6daysago @7daysago
3748 # zfs rename -r pool/users@5daysago @6daysago
3749 # zfs rename -r pool/users@yesterday @5daysago
3750 # zfs rename -r pool/users@yesterday @4daysago
3751 # zfs rename -r pool/users@yesterday @3daysago
3752 # zfs rename -r pool/users@yesterday @2daysago
3753 # zfs rename -r pool/users@today @yesterday
3754 # zfs snapshot -r pool/users@today
3755 .Ed
3756 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3757 The following commands show how to set
3758 .Sy sharenfs
3759 property options to enable
3760 .Sy rw
3761 access for a set of
3762 .Sy IP
3763 addresses and to enable root access for system
3764 .Sy neo
3765 on the
3766 .Em tank/home
3767 file system.
3768 .Bd -literal
3769 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
3770 .Ed
3771 .Pp
3772 If you are using
3773 .Sy DNS
3774 for host name resolution, specify the fully qualified hostname.
3775 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
3776 The following example shows how to set permissions so that user
3777 .Sy cindys
3778 can create, destroy, mount, and take snapshots on
3779 .Em tank/cindys .
3780 The permissions on
3781 .Em tank/cindys
3782 are also displayed.
3783 .Bd -literal
3784 # zfs allow cindys create,destroy,mount,snapshot tank/cindys
3785 # zfs allow tank/cindys
3786 ---- Permissions on tank/cindys --------------------------------------
3787 Local+Descendent permissions:
3788 user cindys create,destroy,mount,snapshot
3789 .Ed
3790 .Pp
3791 Because the
3792 .Em tank/cindys
3793 mount point permission is set to 755 by default, user
3794 .Sy cindys
3795 will be unable to mount file systems under
3796 .Em tank/cindys .
3797 Add an ACE similar to the following syntax to provide mount point access:
3798 .Bd -literal
3799 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
3800 .Ed
3801 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
3802 The following example shows how to grant anyone in the group
3803 .Sy staff
3804 to create file systems in
3805 .Em tank/users .
3806 This syntax also allows staff members to destroy their own file systems, but not
3807 destroy anyone else's file system.
3808 The permissions on
3809 .Em tank/users
3810 are also displayed.
3811 .Bd -literal
3812 # zfs allow staff create,mount tank/users
3813 # zfs allow -c destroy tank/users
3814 # zfs allow tank/users
3815 ---- Permissions on tank/users ---------------------------------------
3816 Permission sets:
3817 destroy
3818 Local+Descendent permissions:
3819 group staff create,mount
3820 .Ed
3821 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
3822 The following example shows how to define and grant a permission set on the
3823 .Em tank/users
3824 file system.
3825 The permissions on
3826 .Em tank/users
3827 are also displayed.
3828 .Bd -literal
3829 # zfs allow -s @pset create,destroy,snapshot,mount tank/users
3830 # zfs allow staff @pset tank/users
3831 # zfs allow tank/users
3832 ---- Permissions on tank/users ---------------------------------------
3833 Permission sets:
3834 @pset create,destroy,mount,snapshot
3835 Local+Descendent permissions:
3836 group staff @pset
3837 .Ed
3838 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
3839 The following example shows to grant the ability to set quotas and reservations
3840 on the
3841 .Em users/home
3842 file system.
3843 The permissions on
3844 .Em users/home
3845 are also displayed.
3846 .Bd -literal
3847 # zfs allow cindys quota,reservation users/home
3848 # zfs allow users/home
3849 ---- Permissions on users/home ---------------------------------------
3850 Local+Descendent permissions:
3851 user cindys quota,reservation
3852 cindys% zfs set quota=10G users/home/marks
3853 cindys% zfs get quota users/home/marks
3854 NAME PROPERTY VALUE SOURCE
3855 users/home/marks quota 10G local
3856 .Ed
3857 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
3858 The following example shows how to remove the snapshot permission from the
3859 .Sy staff
3860 group on the
3861 .Em tank/users
3862 file system.
3863 The permissions on
3864 .Em tank/users
3865 are also displayed.
3866 .Bd -literal
3867 # zfs unallow staff snapshot tank/users
3868 # zfs allow tank/users
3869 ---- Permissions on tank/users ---------------------------------------
3870 Permission sets:
3871 @pset create,destroy,mount,snapshot
3872 Local+Descendent permissions:
3873 group staff @pset
3874 .Ed
3875 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
3876 The following example shows how to see what has changed between a prior
3877 snapshot of a ZFS dataset and its current state.
3878 The
3879 .Fl F
3880 option is used to indicate type information for the files affected.
3881 .Bd -literal
3882 # zfs diff -F tank/test@before tank/test
3883 M / /tank/test/
3884 M F /tank/test/linked (+1)
3885 R F /tank/test/oldname -> /tank/test/newname
3886 - F /tank/test/deleted
3887 + F /tank/test/created
3888 M F /tank/test/modified
3889 .Ed
3890 .El
3891 .Sh INTERFACE STABILITY
3892 .Sy Committed .
3893 .Sh SEE ALSO
3894 .Xr gzip 1 ,
3895 .Xr ssh 1 ,
3896 .Xr mount 1M ,
3897 .Xr share 1M ,
3898 .Xr sharemgr 1M ,
3899 .Xr unshare 1M ,
3900 .Xr zonecfg 1M ,
3901 .Xr zpool 1M ,
3902 .Xr chmod 2 ,
3903 .Xr stat 2 ,
3904 .Xr write 2 ,
3905 .Xr fsync 3C ,
3906 .Xr dfstab 4 ,
3907 .Xr acl 5 ,
3908 .Xr attributes 5