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