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