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