1zfs(1M)                 System Administration Commands                 zfs(1M)
2
3
4

NAME

6       zfs - configures ZFS file systems
7

SYNOPSIS

9       zfs [-?]
10
11
12       zfs create [-p] [-o property=value] ... filesystem
13
14
15       zfs create [-ps] [-b blocksize] [-o property=value] ... -V size volume
16
17
18       zfs destroy [-rRf] filesystem|volume
19
20
21       zfs destroy [-rRd] snapshot
22
23
24       zfs snapshot [-r] [-o property=value]...
25             filesystem@snapname|volume@snapname
26
27
28       zfs rollback [-rRf] snapshot
29
30
31       zfs clone [-p] [-o property=value] ... snapshot filesystem|volume
32
33
34       zfs promote clone-filesystem
35
36
37       zfs rename filesystem|volume|snapshot
38            filesystem|volume|snapshot
39
40
41       zfs rename [-p] filesystem|volume filesystem|volume
42
43
44       zfs rename -r snapshot snapshot
45
46
47       zfs list [-r|-d depth][-H][-o property[,...]] [-t type[,...]]
48            [-s property] ... [-S property] ... [filesystem|volume|snapshot] ...
49
50
51       zfs set property=value filesystem|volume|snapshot ...
52
53
54       zfs get [-r|-d depth][-Hp][-o all | field[,...]] [-s source[,...]]
55            all | property[,...] filesystem|volume|snapshot ...
56
57
58       zfs inherit [-rS] property filesystem|volume|snapshot ...
59
60
61       zfs upgrade [-v]
62
63
64       zfs upgrade [-r] [-V version] -a | filesystem
65
66
67       zfs userspace [-niHp] [-o field[,...]] [-sS field] ...
68            [-t type [,...]] filesystem|snapshot
69
70
71       zfs groupspace [-niHp] [-o field[,...]] [-sS field] ...
72            [-t type [,...]] filesystem|snapshot
73
74
75       zfs mount
76
77
78       zfs mount [-vO] [-o options] -a | filesystem
79
80
81       zfs unmount [-f] -a | filesystem|mountpoint
82
83
84       zfs share -a | filesystem
85
86
87       zfs unshare -a filesystem|mountpoint
88
89
90       zfs send [-DvRp] [-[iI] snapshot] snapshot
91
92
93       zfs receive [-vnFu] filesystem|volume|snapshot
94
95
96       zfs receive [-vnFu] [-d | -e] filesystem
97
98
99       zfs allow filesystem|volume
100
101
102       zfs allow [-ldug] "everyone"|user|group[,...] perm|@setname[,...]
103            filesystem|volume
104
105
106       zfs allow [-ld] -e perm|@setname[,...] filesystem|volume
107
108
109       zfs allow -c perm|@setname[,...] filesystem|volume
110
111
112       zfs allow -s @setname perm|@setname[,...] filesystem|volume
113
114
115       zfs unallow [-rldug] "everyone"|user|group[,...] [perm|@setname[,... ]]
116            filesystem|volume
117
118
119       zfs unallow [-rld] -e [perm|@setname[,... ]] filesystem|volume
120
121
122       zfs unallow [-r] -c [perm|@setname[ ... ]] filesystem|volume
123
124
125       zfs unallow [-r] -s @setname [perm|@setname[,... ]] filesystem|volume
126
127
128       zfs hold [-r] tag snapshot...
129
130
131       zfs holds [-r] snapshot...
132
133
134       zfs release [-r] tag snapshot...
135
136

DESCRIPTION

138       The  zfs  command configures ZFS datasets within a ZFS storage pool, as
139       described in zpool(1M). A dataset is identified by a unique path within
140       the ZFS namespace. For example:
141
142         pool/{filesystem,volume,snapshot}
143
144
145
146
147       where the maximum length of a dataset name is MAXNAMELEN (256 bytes).
148
149
150       A dataset can be one of the following:
151
152       file system
153
154           A ZFS dataset of type filesystem can be mounted within the standard
155           system namespace and behaves like other  file  systems.  While  ZFS
156           file systems are designed to be POSIX compliant, known issues exist
157           that prevent compliance in some cases. Applications that depend  on
158           standards  conformance  might fail due to nonstandard behavior when
159           checking file system free space.
160
161
162       volume
163
164           A logical volume exported as a raw or block device.  This  type  of
165           dataset  should only be used under special circumstances. File sys‐
166           tems are typically used in most environments.
167
168
169       snapshot
170
171           A read-only version of a file system or volume at a given point  in
172           time. It is specified as filesystem@name or volume@name.
173
174
175   ZFS File System Hierarchy
176       A  ZFS  storage  pool  is  a logical collection of devices that provide
177       space for datasets. A storage pool is also the root  of  the  ZFS  file
178       system hierarchy.
179
180
181       The root of the pool can be accessed as a file system, such as mounting
182       and unmounting, taking snapshots, and setting properties. The  physical
183       storage characteristics, however, are managed by the zpool(1M) command.
184
185
186       See zpool(1M) for more information on creating and administering pools.
187
188   Snapshots
189       A  snapshot  is  a read-only copy of a file system or volume. Snapshots
190       can be created extremely quickly, and initially consume  no  additional
191       space  within  the pool. As data within the active dataset changes, the
192       snapshot consumes more data than would otherwise  be  shared  with  the
193       active dataset.
194
195
196       Snapshots  can have arbitrary names. Snapshots of volumes can be cloned
197       or rolled back, but cannot be accessed independently.
198
199
200       File system snapshots can be accessed under the .zfs/snapshot directory
201       in  the root of the file system. Snapshots are automatically mounted on
202       demand and may be unmounted at regular intervals. The visibility of the
203       .zfs directory can be controlled by the snapdir property.
204
205   Clones
206       A  clone is a writable volume or file system whose initial contents are
207       the same as another dataset. As with snapshots,  creating  a  clone  is
208       nearly instantaneous, and initially consumes no additional space.
209
210
211       Clones  can only be created from a snapshot. When a snapshot is cloned,
212       it creates an implicit dependency between the parent  and  child.  Even
213       though  the  clone  is created somewhere else in the dataset hierarchy,
214       the original snapshot cannot be destroyed as long as  a  clone  exists.
215       The  origin  property  exposes this dependency, and the destroy command
216       lists any such dependencies, if they exist.
217
218
219       The clone parent-child dependency relationship can be reversed by using
220       the  promote subcommand. This causes the "origin" file system to become
221       a clone of the specified  file  system,  which  makes  it  possible  to
222       destroy the file system that the clone was created from.
223
224   Mount Points
225       Creating a ZFS file system is a simple operation, so the number of file
226       systems per system is likely to be numerous. To  cope  with  this,  ZFS
227       automatically  manages mounting and unmounting file systems without the
228       need to edit the /etc/vfstab file. All automatically managed file  sys‐
229       tems are mounted by ZFS at boot time.
230
231
232       By  default,  file  systems  are mounted under /path, where path is the
233       name of the file system in the ZFS namespace. Directories  are  created
234       and destroyed as needed.
235
236
237       A  file  system can also have a mount point set in the mountpoint prop‐
238       erty. This directory is created as needed, and ZFS automatically mounts
239       the file system when the zfs mount -a command is invoked (without edit‐
240       ing /etc/vfstab). The mountpoint  property  can  be  inherited,  so  if
241       pool/home has a mount point of /export/stuff, then pool/home/user auto‐
242       matically inherits a mount point of /export/stuff/user.
243
244
245       A file system mountpoint property of none prevents the file system from
246       being mounted.
247
248
249       If  needed, ZFS file systems can also be managed with traditional tools
250       (mount, umount, /etc/vfstab). If a file system's mount point is set  to
251       legacy,  ZFS makes no attempt to manage the file system, and the admin‐
252       istrator is responsible for mounting and unmounting the file system.
253
254   Zones
255       A ZFS file system can be added  to  a  non-global  zone  by  using  the
256       zonecfg  add  fs  subcommand. A ZFS file system that is added to a non-
257       global zone must have its mountpoint property set to legacy.
258
259
260       The physical properties of an added file system are controlled  by  the
261       global  administrator. However, the zone administrator can create, mod‐
262       ify, or destroy files within the added file system,  depending  on  how
263       the file system is mounted.
264
265
266       A  dataset  can  also  be  delegated  to a non-global zone by using the
267       zonecfg add dataset subcommand. You cannot delegate a  dataset  to  one
268       zone  and  the  children  of the same dataset to another zone. The zone
269       administrator can change properties of the dataset or any of its  chil‐
270       dren.  However, the quota property is controlled by the global adminis‐
271       trator.
272
273
274       A ZFS volume can be added as a device to a non-global zone by using the
275       zonecfg  add device subcommand. However, its physical properties can be
276       modified only by the global administrator.
277
278
279       For more information about zonecfg syntax, see zonecfg(1M).
280
281
282       After a dataset is delegated to a non-global zone, the  zoned  property
283       is  automatically  set.  A  zoned  file system cannot be mounted in the
284       global zone, since the zone administrator might have to set  the  mount
285       point to an unacceptable value.
286
287
288       The  global administrator can forcibly clear the zoned property, though
289       this should be done with extreme care. The global administrator  should
290       verify  that  all  the  mount points are acceptable before clearing the
291       property.
292
293   Deduplication
294       Deduplication is the process for removing redundant data at  the block-
295       level,  reducing  the total amount of data stored. If a file system has
296       the dedup  property enabled, duplicate data  blocks  are  removed  syn‐
297       chronously.   The  result is that only unique data is stored and common
298       components are shared among files.
299
300   Native Properties
301       Properties are divided into two  types,  native  properties  and  user-
302       defined  (or "user") properties. Native properties either export inter‐
303       nal statistics or control ZFS behavior. In addition, native  properties
304       are either editable or read-only. User properties have no effect on ZFS
305       behavior, but you can use them to annotate datasets in a  way  that  is
306       meaningful in your environment. For more information about user proper‐
307       ties, see the "User Properties" section, below.
308
309
310       Every dataset has a set of properties that export statistics about  the
311       dataset  as well as control various behaviors. Properties are inherited
312       from the parent unless overridden by the child. Some  properties  apply
313       only  to  certain  types  of  datasets (file systems, volumes, or snap‐
314       shots).
315
316
317       The values of numeric properties can be specified using  human-readable
318       suffixes  (for  example,  k,  KB,  M,  Gb,  and  so  forth, up to Z for
319       zettabyte). The following are all valid (and equal) specifications:
320
321         1536M, 1.5g, 1.50GB
322
323
324
325
326       The values of non-numeric properties are case  sensitive  and  must  be
327       lowercase, except for mountpoint, sharenfs, and sharesmb.
328
329
330       The  following  native properties consist of read-only statistics about
331       the dataset. These properties can be neither set, nor inherited. Native
332       properties apply to all dataset types unless otherwise noted.
333
334       available
335
336           The  amount of space available to the dataset and all its children,
337           assuming that there is no other activity in the pool. Because space
338           is  shared within a pool, availability can be limited by any number
339           of factors, including physical pool size, quotas, reservations,  or
340           other datasets within the pool.
341
342           This property can also be referred to by its shortened column name,
343           avail.
344
345
346       compressratio
347
348           The compression ratio achieved for this  dataset,  expressed  as  a
349           multiplier.  Compression  can be turned on by running: zfs set com‐
350           pression=on dataset. The default value is off.
351
352
353       creation
354
355           The time this dataset was created.
356
357
358       defer_destroy
359
360           This property is on if the snapshot has been  marked  for  deferred
361           destroy  by  using the zfs destroy -d command. Otherwise, the prop‐
362           erty is off.
363
364
365       mounted
366
367           For file systems, indicates whether the file  system  is  currently
368           mounted. This property can be either yes or no.
369
370
371       origin
372
373           For  cloned  file  systems  or volumes, the snapshot from which the
374           clone was created. The origin cannot be destroyed (even with the -r
375           or -f options) so long as a clone exists.
376
377
378       referenced
379
380           The amount of data that is accessible by this dataset, which may or
381           may not be shared with other datasets in the pool. When a  snapshot
382           or  clone  is  created,  it initially references the same amount of
383           space as the file system or snapshot it was created from, since its
384           contents are identical.
385
386           This property can also be referred to by its shortened column name,
387           refer.
388
389
390       type
391
392           The type of dataset: filesystem, volume, or snapshot.
393
394
395       used
396
397           The amount of space consumed by this dataset and  all  its  descen‐
398           dents.  This  is  the  value that is checked against this dataset's
399           quota and  reservation.  The  space  used  does  not  include  this
400           dataset's  reservation, but does take into account the reservations
401           of any descendent datasets. The amount of space that a dataset con‐
402           sumes  from  its  parent,  as  well as the amount of space that are
403           freed if this dataset is recursively destroyed, is the  greater  of
404           its space used and its reservation.
405
406           When  snapshots  (see  the  "Snapshots" section) are created, their
407           space is initially shared between the snapshot and the file system,
408           and  possibly  with previous snapshots. As the file system changes,
409           space that was previously shared becomes unique  to  the  snapshot,
410           and  counted  in  the snapshot's space used. Additionally, deleting
411           snapshots can increase the amount of space unique to (and used  by)
412           other snapshots.
413
414           The  amount  of  space used, available, or referenced does not take
415           into  account  pending  changes.  Pending  changes  are   generally
416           accounted  for  within a few seconds. Committing a change to a disk
417           using fsync(3c) or O_SYNC does not necessarily guarantee  that  the
418           space usage information is updated immediately.
419
420
421       usedby*
422
423           The usedby* properties decompose the used properties into the vari‐
424           ous reasons that space is used. Specifically, used = usedbychildren
425           +  usedbydataset  +  usedbyrefreservation +, usedbysnapshots. These
426           properties are only available for datasets created on  zpool  "ver‐
427           sion 13" pools.
428
429
430       usedbychildren
431
432           The  amount  of space used by children of this dataset, which would
433           be freed if all the dataset's children were destroyed.
434
435
436       usedbydataset
437
438           The amount of space used by this dataset  itself,  which  would  be
439           freed  if  the  dataset  were  destroyed  (after first removing any
440           refreservation and destroying any necessary  snapshots  or  descen‐
441           dents).
442
443
444       usedbyrefreservation
445
446           The  amount  of space used by a refreservation set on this dataset,
447           which would be freed if the refreservation was removed.
448
449
450       usedbysnapshots
451
452           The amount of space consumed by snapshots of this dataset. In  par‐
453           ticular,  it  is  the amount of space that would be freed if all of
454           this dataset's snapshots were destroyed. Note that this is not sim‐
455           ply  the sum of the snapshots' used properties because space can be
456           shared by multiple snapshots.
457
458
459       userused@user
460
461           The amount of space consumed by the specified user in this dataset.
462           Space  is charged to the owner of each file, as displayed by ls -l.
463           The amount of space charged is displayed by du and ls -s.  See  the
464           zfs userspace subcommand for more information.
465
466           Unprivileged  users can access only their own space usage. The root
467           user, or a user who has been granted the  userused  privilege  with
468           zfs allow, can access everyone's usage.
469
470           The  userused@...  properties are not displayed by zfs get all. The
471           user's name must be appended after the @ symbol, using one  of  the
472           following forms:
473
474               o      POSIX name (for example, joe)
475
476               o      POSIX numeric ID (for example, 789)
477
478               o      SID name (for example, joe.smith@mydomain)
479
480               o      SID numeric ID (for example, S-1-123-456-789)
481
482
483       userrefs
484
485           This  property is set to the number of user holds on this snapshot.
486           User holds are set by using the zfs hold command.
487
488
489       groupused@group
490
491           The amount of  space  consumed  by  the  specified  group  in  this
492           dataset.  Space  is charged to the group of each file, as displayed
493           by ls -l. See the userused@user property for more information.
494
495           Unprivileged users can only access their own groups'  space  usage.
496           The  root user, or a user who has been granted the groupused privi‐
497           lege with zfs allow, can access all groups' usage.
498
499
500       volblocksize=blocksize
501
502           For volumes, specifies the block size of the volume. The  blocksize
503           cannot be changed once the volume has been written, so it should be
504           set at volume creation time. The default blocksize for volumes is 8
505           Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid.
506
507           This property can also be referred to by its shortened column name,
508           volblock.
509
510
511
512       The following native properties can be used to change the behavior of a
513       ZFS dataset.
514
515       aclinherit=discard | noallow | restricted | passthrough | passthrough-x
516
517           Controls  how  ACL entries are inherited when files and directories
518           are created. A file system with an aclinherit property  of  discard
519           does  not inherit any ACL entries. A file system with an aclinherit
520           property value of noallow only  inherits  inheritable  ACL  entries
521           that specify "deny" permissions. The property value restricted (the
522           default) removes the write_acl and write_owner permissions when the
523           ACL  entry  is inherited. A file system with an aclinherit property
524           value of passthrough inherits all inheritable ACL  entries  without
525           any  modifications made to the ACL entries when they are inherited.
526           A file system with an aclinherit property  value  of  passthrough-x
527           has  the  same  meaning  as  passthrough,  except  that the owner@,
528           group@, and everyone@ ACEs inherit the execute permission  only  if
529           the file creation mode also requests the execute bit.
530
531           When  the  property  value is set to passthrough, files are created
532           with a mode determined by the inheritable ACEs. If  no  inheritable
533           ACEs exist that affect the mode, then the mode is set in accordance
534           to the requested mode from the application.
535
536
537       aclmode=discard | groupmask | passthrough
538
539           Controls how an ACL is modified during chmod(2). A file system with
540           an  aclmode property of discard deletes all ACL entries that do not
541           represent the mode of the file. An aclmode  property  of  groupmask
542           (the  default)  reduces  user or group permissions. The permissions
543           are reduced, such that they are no greater than the  group  permis‐
544           sion  bits,  unless it is a user entry that has the same UID as the
545           owner of the file or directory. In this case, the  ACL  permissions
546           are reduced so that they are no greater than owner permission bits.
547           A file system with an aclmode  property  of  passthrough  indicates
548           that  no changes are made to the ACL other than generating the nec‐
549           essary ACL entries to represent the new mode of the file or  direc‐
550           tory.
551
552
553       atime=on | off
554
555           Controls whether the access time for files is updated when they are
556           read. Turning this property off avoids producing write traffic when
557           reading  files  and  can  result  in significant performance gains,
558           though it might confuse mailers and other  similar  utilities.  The
559           default value is on.
560
561
562       canmount=on | off | noauto
563
564           If  this property is set to off, the file system cannot be mounted,
565           and is ignored by zfs mount -a. Setting this  property  to  off  is
566           similar to setting the mountpoint property to none, except that the
567           dataset still has a normal mountpoint property, which can be inher‐
568           ited.  Setting  this  property  to  off  allows datasets to be used
569           solely as a mechanism to inherit properties. One example of setting
570           canmount=off  is  to have two datasets with the same mountpoint, so
571           that the children of both datasets appear in  the  same  directory,
572           but might have different inherited characteristics.
573
574           When  the  noauto  option is set, a dataset can only be mounted and
575           unmounted explicitly. The dataset is not mounted automatically when
576           the  dataset  is  created or imported, nor is it mounted by the zfs
577           mount -a command or unmounted by the zfs unmount -a command.
578
579           This property is not inherited.
580
581
582       checksum=on | off | fletcher2,| fletcher4 | sha256
583
584           Controls the checksum used to verify data  integrity.  The  default
585           value  is  on, which automatically selects an appropriate algorithm
586           (currently, fletcher4, but this may change in future releases). The
587           value  off  disables  integrity  checking  on  user data. Disabling
588           checksums is NOT a recommended practice.
589
590           Changing this property affects only newly-written data.
591
592
593       compression=on | off | lzjb | gzip | gzip-N | zle | lzo | lzo9 | bz2 |
594       lzma-N | lzma
595
596           Controls  the compression algorithm used for this dataset. The lzjb
597           compression algorithm is optimized for performance while  providing
598           decent  data  compression.  Setting compression to on uses the lzjb
599           compression algorithm. The gzip compression algorithm uses the same
600           compression  as the gzip(1) command. You can specify the gzip level
601           by using the value gzip-N where N is an integer from 1 (fastest) to
602           9 (best compression ratio). Currently, gzip is equivalent to gzip-6
603           (which is also the default for gzip(1)).
604
605           This property can also be referred to by its shortened column  name
606           compress. Changing this property affects only newly-written data.
607
608           zfs-fuse  :  you  can  also choose lzo, lzo9, bz2 or lzma with zfs-
609           fuse. Notice that it will create data which will be  readable  only
610           with zfs-fuse (and not with the other zfs implementations). Here is
611           a quick benchmark of what you can expect from  the  different  com‐
612           pression  methods (here when writing bzcat linux-2.6.1.tar.bz2 to a
613           zfs volume)
614
615           type                 size            time
616           uncompressed         186501120          17,479
617           lzjb (on)            88276k             14,768
618           lzo                  64793k             13,541
619           lzo9                 48213k             25,551
620           gzip                 42696k             15,352
621           lzma                 39383k             19,933
622           bzip2                37992k             23,397
623
624           lzma is equivalent to lzma-3, and bz2 is the maximum bzip2 compres‐
625           sion (-9).
626
627
628       copies=1 | 2 | 3
629
630           Controls  the  number  of  copies  of data stored for this dataset.
631           These copies are in addition to  any  redundancy  provided  by  the
632           pool,  for  example,  mirroring or RAID-Z. The copies are stored on
633           different disks, if possible. The space used by multiple copies  is
634           charged to the associated file and dataset, changing the used prop‐
635           erty and counting against quotas and reservations.
636
637           Changing this property only affects newly-written data.  Therefore,
638           set  this  property  at  file  system creation time by using the -o
639           copies=N option.
640
641
642       dedup=on | off | verify | sha256[,verify]
643
644           Controls whether deduplication is in  effect  for  a  dataset.  The
645           default  value  is off. The default checksum used for deduplication
646           is sha256 (subject to change). When dedup  is  enabled,  the  dedup
647           checksum  algorithm  overrides  the  checksum property. Setting the
648           value to verify is equivalent to specifying sha256,verify.
649
650           If the property is set to verify, then, whenever  two  blocks  have
651           the same signature, ZFS will do a byte-for-byte comparison with the
652           existing block to ensure that the contents are identical.
653
654
655       devices=on | off
656
657           Controls whether device nodes can be opened on  this  file  system.
658           The default value is on.
659
660
661       exec=on | off
662
663           Controls  whether  processes  can be executed from within this file
664           system. The default value is on.
665
666
667       mlslabel=label | none
668
669           The mlslabel property is a sensitivity label that determines  if  a
670           dataset   can  be mounted in a zone on a system with Trusted Exten‐
671           sions enabled. If the labeled dataset matches the labeled zone, the
672           dataset can be mounted  and accessed from the labeled zone.
673
674           When  the  mlslabel property is not set, the default value is none.
675           Setting the  mlslabel property to none is  equivalent  to  removing
676           the property.
677
678           The  mlslabel property can be modified only when Trusted Extensions
679           is enabled and only with appropriate privilege. Rights to modify it
680           cannot  be  delegated.  When  changing a label to a higher label or
681           setting the initial dataset label, the {PRIV_FILE_UPGRADE_SL} priv‐
682           ilege  is  required.  When changing a label to a lower label or the
683           default (none), the {PRIV_FILE_DOWNGRADE_SL} privilege is required.
684           Changing  the  dataset to labels other than the default can be done
685           only when the dataset is not  mounted.  When  a  dataset  with  the
686           default  label  is mounted into a labeled-zone, the mount operation
687           automatically sets the mlslabel property to the label of that zone.
688
689           When Trusted Extensions is not  enabled,  only  datasets  with  the
690           default label (none) can be mounted.
691
692
693       mountpoint=path | none | legacy
694
695           Controls  the mount point used for this file system. See the "Mount
696           Points" section for more information on how this property is used.
697
698           When the mountpoint property is changed for a file system, the file
699           system and any children that inherit the mount point are unmounted.
700           If the new value is legacy, then they remain unmounted.  Otherwise,
701           they  are  automatically remounted in the new location if the prop‐
702           erty was previously legacy or none, or if they were mounted  before
703           the  property was changed. In addition, any shared file systems are
704           unshared and shared in the new location.
705
706
707       nbmand=on | off
708
709           Controls whether the file system should be mounted with nbmand (Non
710           Blocking  mandatory  locks). This is used for CIFS clients. Changes
711           to this property only take effect when the file system is  umounted
712           and remounted. See mount(1M) for more information on nbmand mounts.
713
714
715       primarycache=all | none | metadata
716
717           Controls  what  is cached in the primary cache (ARC). If this prop‐
718           erty is set to all, then both user data and metadata is cached.  If
719           this  property  is set to none, then neither user data nor metadata
720           is cached. If this property is set to metadata, then only  metadata
721           is cached. The default value is all.
722
723
724       quota=size | none
725
726           Limits  the  amount of space a dataset and its descendents can con‐
727           sume. This property enforces a hard limit on the  amount  of  space
728           used.  This  includes  all space consumed by descendents, including
729           file systems and snapshots. Setting a quota on a  descendent  of  a
730           dataset  that  already has a quota does not override the ancestor's
731           quota, but rather imposes an additional limit.
732
733           Quotas cannot be set on volumes, as the volsize property acts as an
734           implicit quota.
735
736
737       userquota@user=size | none
738
739           Limits  the amount of space consumed by the specified user. Similar
740           to the refquota property, the userquota space calculation does  not
741           include  space  that  is used by descendent datasets, such as snap‐
742           shots and clones. User  space  consumption  is  identified  by  the
743           userspace@user property.
744
745           Enforcement  of user quotas may be delayed by several seconds. This
746           delay means that a user might exceed her quota  before  the  system
747           notices  that  she  is  over  quota. The system would then begin to
748           refuse additional writes with the EDQUOT error message  .  See  the
749           zfs userspace subcommand for more information.
750
751           Unprivileged  users  can only access their own groups' space usage.
752           The root user, or a user who has been granted the userquota  privi‐
753           lege with zfs allow, can get and set everyone's quota.
754
755           This  property  is not available on volumes, on file systems before
756           version 4, or on pools before version 15. The userquota@... proper‐
757           ties  are  not  displayed  by  zfs get all. The user's name must be
758           appended after the @ symbol, using one of the following forms:
759
760               o      POSIX name (for example, joe)
761
762               o      POSIX numeric ID (for example, 789)
763
764               o      SID name (for example, joe.smith@mydomain)
765
766               o      SID numeric ID (for example, S-1-123-456-789)
767
768
769       groupquota@group=size | none
770
771           Limits the amount of space consumed by the specified  group.  Group
772           space consumption is identified by the userquota@user property.
773
774           Unprivileged  users  can access only their own groups' space usage.
775           The root user, or a user who has been granted the groupquota privi‐
776           lege with zfs allow, can get and set all groups' quotas.
777
778
779       readonly=on | off
780
781           Controls whether this dataset can be modified. The default value is
782           off.
783
784           This property can also be referred to by its shortened column name,
785           rdonly.
786
787
788       recordsize=size
789
790           Specifies a suggested block size for files in the file system. This
791           property is designed solely for use with  database  workloads  that
792           access  files  in fixed-size records. ZFS automatically tunes block
793           sizes according to internal algorithms optimized for typical access
794           patterns.
795
796           For databases that create very large files but access them in small
797           random chunks, these algorithms may  be  suboptimal.  Specifying  a
798           recordsize greater than or equal to the record size of the database
799           can result in significant performance gains. Use of  this  property
800           for  general  purpose file systems is strongly discouraged, and may
801           adversely affect performance.
802
803           The size specified must be a power of two greater than or equal  to
804           512 and less than or equal to 128 Kbytes.
805
806           Changing  the  file  system's recordsize affects only files created
807           afterward; existing files are unaffected.
808
809           This property can also be referred to by its shortened column name,
810           recsize.
811
812
813       refquota=size | none
814
815           Limits  the  amount  of  space a dataset can consume. This property
816           enforces a hard limit on the amount of space used. This hard  limit
817           does  not include space used by descendents, including file systems
818           and snapshots.
819
820
821       refreservation=size | none
822
823           The minimum amount of space guaranteed to a dataset, not  including
824           its descendents. When the amount of space used is below this value,
825           the dataset is treated as if it were taking up the amount of  space
826           specified  by  refreservation.  The  refreservation  reservation is
827           accounted for in  the  parent  datasets'  space  used,  and  counts
828           against the parent datasets' quotas and reservations.
829
830           If  refreservation  is  set, a snapshot is only allowed if there is
831           enough free pool space outside of this reservation  to  accommodate
832           the current number of "referenced" bytes in the dataset.
833
834           This property can also be referred to by its shortened column name,
835           refreserv.
836
837
838       reservation=size | none
839
840           The minimum amount of space guaranteed to a dataset and its descen‐
841           dents.  When  the  amount  of  space  used is below this value, the
842           dataset is treated as if it were taking  up  the  amount  of  space
843           specified by its reservation. Reservations are accounted for in the
844           parent datasets' space used, and count against the parent datasets'
845           quotas and reservations.
846
847           This property can also be referred to by its shortened column name,
848           reserv.
849
850
851       secondarycache=all | none | metadata
852
853           Controls what is cached in the secondary  cache  (L2ARC).  If  this
854           property is set to all, then both user data and metadata is cached.
855           If this property is set to none, then neither user data  nor  meta‐
856           data  is  cached.  If  this  property is set to metadata, then only
857           metadata is cached. The default value is all.
858
859
860       setuid=on | off
861
862           Controls whether the set-UID bit is respected for the file  system.
863           The default value is on.
864
865
866       shareiscsi=on | off
867
868           Like the sharenfs property, shareiscsi indicates whether a ZFS vol‐
869           ume is exported as an iSCSI target. The acceptable values for  this
870           property  are  on, off, and type=disk. The default value is off. In
871           the future, other target types might  be  supported.  For  example,
872           tape.
873
874           You  might  want to set shareiscsi=on for a file system so that all
875           ZFS volumes within the file system are shared by default.  However,
876           setting this property on a file system has no direct effect.
877
878
879       sharesmb=on | off | opts
880
881           Controls  whether  the  file  system is shared by using the Solaris
882           CIFS service, and what options are to be used. A file  system  with
883           the  sharesmb  property  set  to off is managed through traditional
884           tools such as sharemgr(1M). Otherwise, the file system is automati‐
885           cally  shared  and unshared with the zfs share and zfs unshare com‐
886           mands. If the property is set to on, the  sharemgr(1M)  command  is
887           invoked  with  no  options.  Otherwise, the sharemgr(1M) command is
888           invoked with options equivalent to the contents of this property.
889
890           Because SMB shares requires a resource name, a unique resource name
891           is  constructed  from  the  dataset name. The constructed name is a
892           copy of the dataset name except that the characters in the  dataset
893           name,  which  would  be  illegal in the resource name, are replaced
894           with underscore (_) characters. A pseudo property  "name"  is  also
895           supported that allows you to replace the data set name with a spec‐
896           ified name. The specified name is then used to replace  the  prefix
897           dataset  in  the  case  of inheritance. For example, if the dataset
898           data/home/john is set  to  name=john,  then  data/home/john  has  a
899           resource  name  of john. If a child dataset of data/home/john/back‐
900           ups, it has a resource name of john_backups.
901
902           When SMB shares are created, the SMB share name appears as an entry
903           in  the  .zfs/shares directory. You can use the ls or chmod command
904           to display the share-level ACLs on the entries in this directory.
905
906           When the sharesmb property is changed for a  dataset,  the  dataset
907           and any children inheriting the property are re-shared with the new
908           options, only if the property was previously set to off, or if they
909           were shared before the property was changed. If the new property is
910           set to off, the file systems are unshared.
911
912
913       sharenfs=on | off | opts
914
915           Controls whether the file  system  is  shared  via  NFS,  and  what
916           options  are used. A file system with a sharenfs property of off is
917           managed through traditional tools such as  share(1M),  unshare(1M),
918           and  dfstab(4).  Otherwise, the file system is automatically shared
919           and unshared with the zfs share and zfs unshare  commands.  If  the
920           property  is  set  to  on, the share(1M) command is invoked with no
921           options. Otherwise, the share(1M) command is invoked  with  options
922           equivalent to the contents of this property.
923
924           When  the  sharenfs  property is changed for a dataset, the dataset
925           and any children inheriting the property are re-shared with the new
926           options,  only  if the property was previously off, or if they were
927           shared before the property was changed. If the new property is off,
928           the file systems are unshared.
929
930
931       logbias = latency | throughput
932
933           Provides  a  hint  to ZFS about handling of synchronous requests in
934           this dataset. If logbias is set to latency (the default), ZFS  uses
935           the  pool's  log  devices (if configured) to handle the requests at
936           low latency. If logbias is set to throughput, ZFS does not use  the
937           configured  pool  log  devices.  Instead, ZFS optimizes synchronous
938           operations  for  global  pool  throughput  and  efficient  use   of
939           resources.
940
941
942       snapdir=hidden | visible
943
944           Controls  whether  the  .zfs  directory is hidden or visible in the
945           root of the file system as discussed in  the  "Snapshots"  section.
946           The default value is hidden.
947
948
949       version=1 | 2 | current
950
951           The  on-disk  version  of this file system, which is independent of
952           the pool version. This property can only be set to later  supported
953           versions. See the zfs upgrade command.
954
955
956       volsize=size
957
958           For  volumes, specifies the logical size of the volume. By default,
959           creating a volume establishes a  reservation  of  equal  size.  For
960           storage  pools  with a version number of 9 or higher, a refreserva‐
961           tion is set instead. Any changes to volsize  are  reflected  in  an
962           equivalent  change to the reservation (or refreservation). The vol‐
963           size can only be set to a multiple of volblocksize, and  cannot  be
964           zero.
965
966           The  reservation is kept equal to the volume's logical size to pre‐
967           vent unexpected behavior for consumers.  Without  the  reservation,
968           the  volume could run out of space, resulting in undefined behavior
969           or data corruption, depending on how  the  volume  is  used.  These
970           effects  can also occur when the volume size is changed while it is
971           in use (particularly when shrinking the size). Extreme care  should
972           be used when adjusting the volume size.
973
974           Though not recommended, a "sparse volume" (also known as "thin pro‐
975           visioning") can be created by specifying the -s option to  the  zfs
976           create  -V command, or by changing the reservation after the volume
977           has been created. A "sparse volume" is a volume where the  reserva‐
978           tion is less then the volume size. Consequently, writes to a sparse
979           volume can fail with ENOSPC when the pool is low on  space.  For  a
980           sparse volume, changes to volsize are not reflected in the reserva‐
981           tion.
982
983
984       vscan=on | off
985
986           Controls whether regular files should be scanned for viruses when a
987           file  is  opened and closed. In addition to enabling this property,
988           the virus scan service must also be enabled for virus  scanning  to
989           occur. The default value is off.
990
991
992       xattr=on | off
993
994           Controls whether extended attributes are enabled for this file sys‐
995           tem. The default value is on.
996
997
998       zoned=on | off
999
1000           Controls whether the dataset is managed from a non-global zone. See
1001           the "Zones" section for more information. The default value is off.
1002
1003
1004
1005       The  following three properties cannot be changed after the file system
1006       is created, and therefore, should be set when the file system  is  cre‐
1007       ated. If the properties are not set with the zfs create or zpool create
1008       commands, these properties are inherited from the  parent  dataset.  If
1009       the  parent  dataset  lacks these properties due to having been created
1010       prior to these features being supported, the new file system will  have
1011       the default values for these properties.
1012
1013       casesensitivity=sensitive | insensitive | mixed
1014
1015           Indicates whether the file name matching algorithm used by the file
1016           system should be case-sensitive, case-insensitive, or allow a  com‐
1017           bination of both styles of matching. The default value for the cas‐
1018           esensitivity property is sensitive. Traditionally, UNIX  and  POSIX
1019           file systems have case-sensitive file names.
1020
1021           The mixed value for the casesensitivity property indicates that the
1022           file system can support requests for both case-sensitive and  case-
1023           insensitive matching behavior. Currently, case-insensitive matching
1024           behavior on a file system that supports mixed behavior  is  limited
1025           to  the Solaris CIFS server product. For more information about the
1026           mixed value behavior, see the Solaris ZFS Administration Guide.
1027
1028
1029       normalization = none | formC | formD | formKC | formKD
1030
1031           Indicates whether the file system should perform a unicode  normal‐
1032           ization  of  file  names  whenever two file names are compared, and
1033           which normalization algorithm should be used. File names are always
1034           stored  unmodified,  names are normalized as part of any comparison
1035           process. If this property is set to a legal value other than  none,
1036           and  the utf8only property was left unspecified, the utf8only prop‐
1037           erty is automatically set to on. The default value of  the  normal‐
1038           ization property is none. This property cannot be changed after the
1039           file system is created.
1040
1041
1042       utf8only=on | off
1043
1044           Indicates whether the file system should  reject  file  names  that
1045           include characters that are not present in the UTF-8 character code
1046           set. If this property is explicitly set to off,  the  normalization
1047           property  must  either not be explicitly set or be set to none. The
1048           default value for the utf8only property is off. This property  can‐
1049           not be changed after the file system is created.
1050
1051
1052
1053       The  casesensitivity,  normalization,  and utf8only properties are also
1054       new permissions that can be assigned to non-privileged users  by  using
1055       the ZFS delegated administration feature.
1056
1057   Temporary Mount Point Properties
1058       When  a  file  system  is  mounted, either through mount(1M) for legacy
1059       mounts or the zfs mount command for  normal  file  systems,  its  mount
1060       options  are  set  according to its properties. The correlation between
1061       properties and mount options is as follows:
1062
1063             PROPERTY                MOUNT OPTION
1064              devices                 devices/nodevices
1065              exec                    exec/noexec
1066              readonly                ro/rw
1067              setuid                  setuid/nosetuid
1068              xattr                   xattr/noxattr
1069
1070
1071
1072
1073       In addition, these options can be set on a per-mount basis using the -o
1074       option, without affecting the property that is stored on disk. The val‐
1075       ues specified on the command line override the  values  stored  in  the
1076       dataset.  The  -nosuid option is an alias for nodevices,nosetuid. These
1077       properties are reported as "temporary" by the zfs get command.  If  the
1078       properties  are  changed  while the dataset is mounted, the new setting
1079       overrides any temporary settings.
1080
1081   User Properties
1082       In addition to the standard native properties, ZFS  supports  arbitrary
1083       user  properties.  User  properties have no effect on ZFS behavior, but
1084       applications or administrators can use them to annotate datasets  (file
1085       systems, volumes, and snapshots).
1086
1087
1088       User  property  names must contain a colon (:) character to distinguish
1089       them from native properties. They may contain lowercase  letters,  num‐
1090       bers,  and  the  following punctuation characters: colon (:), dash (-),
1091       period (.), and underscore (_). The expected  convention  is  that  the
1092       property name is divided into two portions such as module:property, but
1093       this namespace is not enforced by ZFS. User property names  can  be  at
1094       most 256 characters, and cannot begin with a dash (-).
1095
1096
1097       When  making  programmatic  use of user properties, it is strongly sug‐
1098       gested to use a reversed DNS domain name for the  module  component  of
1099       property  names  to  reduce the chance that two independently-developed
1100       packages use the same property name for  different  purposes.  Property
1101       names beginning with com.sun. are reserved for use by Sun Microsystems.
1102
1103
1104       The  values of user properties are arbitrary strings, are always inher‐
1105       ited, and are never validated. All of  the  commands  that  operate  on
1106       properties  (zfs  list,  zfs get, zfs set, and so forth) can be used to
1107       manipulate both native properties and  user  properties.  Use  the  zfs
1108       inherit  command  to  clear  a  user  property . If the property is not
1109       defined in any parent dataset, it is removed entirely. Property  values
1110       are limited to 1024 characters.
1111
1112   ZFS Volumes as Swap or Dump Devices
1113       During  an  initial installation or a live upgrade from a UFS file sys‐
1114       tem, a swap device and dump device are created on ZFS  volumes  in  the
1115       ZFS  root pool. By default, the swap area size is based on 1/2 the size
1116       of physical memory up to 2 Gbytes. The size of the dump device  depends
1117       on the kernel's requirements at installation time. Separate ZFS volumes
1118       must be used for the swap area and dump devices. Do not swap to a  file
1119       on a ZFS file system. A ZFS swap file configuration is not supported.
1120
1121
1122       If you need to change your swap area or dump device after the system is
1123       installed or upgraded, use the swap(1M) and  dumpadm(1M)  commands.  If
1124       you  need  to change the size of your swap area or dump device, see the
1125       Solaris ZFS Administration Guide.
1126

SUBCOMMANDS

1128       All subcommands that modify state are logged persistently to  the  pool
1129       in their original form.
1130
1131       zfs ?
1132
1133           Displays a help message.
1134
1135
1136       zfs create [-p] [-o property=value] ... filesystem
1137
1138           Creates  a  new  ZFS  file system. The file system is automatically
1139           mounted according to the mountpoint  property  inherited  from  the
1140           parent.
1141
1142           -p
1143
1144               Creates  all the non-existing parent datasets. Datasets created
1145               in this manner  are  automatically  mounted  according  to  the
1146               mountpoint  property  inherited from their parent. Any property
1147               specified on the command line using the -o option  is  ignored.
1148               If  the  target  filesystem  already exists, the operation com‐
1149               pletes successfully.
1150
1151
1152           -o property=value
1153
1154               Sets the specified property as if the  command  zfs  set  prop‐
1155               erty=value  was  invoked  at the same time the dataset was cre‐
1156               ated. Any editable ZFS property can also  be  set  at  creation
1157               time. Multiple -o options can be specified. An error results if
1158               the same property is specified in multiple -o options.
1159
1160
1161
1162       zfs create [-ps] [-b blocksize] [-o property=value] ... -V size volume
1163
1164           Creates a volume of the given size. The volume  is  exported  as  a
1165           block  device  in /dev/zvol/{dsk,rdsk}/path, where path is the name
1166           of the volume in the ZFS namespace. The size represents the logical
1167           size  as exported by the device. By default, a reservation of equal
1168           size is created.
1169
1170           size is automatically rounded up  to  the  nearest  128  Kbytes  to
1171           ensure  that the volume has an integral number of blocks regardless
1172           of blocksize.
1173
1174           -p
1175
1176               Creates all the non-existing parent datasets. Datasets  created
1177               in  this  manner  are  automatically  mounted  according to the
1178               mountpoint property inherited from their parent.  Any  property
1179               specified  on  the command line using the -o option is ignored.
1180               If the target filesystem already  exists,  the  operation  com‐
1181               pletes successfully.
1182
1183
1184           -s
1185
1186               Creates a sparse volume with no reservation. See volsize in the
1187               Native Properties section for  more  information  about  sparse
1188               volumes.
1189
1190
1191           -o property=value
1192
1193               Sets  the  specified  property as if the zfs set property=value
1194               command was invoked at the same time the dataset  was  created.
1195               Any  editable  ZFS  property  can also be set at creation time.
1196               Multiple -o options can be specified. An error results  if  the
1197               same property is specified in multiple -o options.
1198
1199
1200           -b blocksize
1201
1202               Equivalent  to  -o  volblocksize=blocksize.  If  this option is
1203               specified in conjunction with -o  volblocksize,  the  resulting
1204               behavior is undefined.
1205
1206
1207
1208       zfs destroy [-rRf] filesystem|volume
1209
1210           Destroys  the  given  dataset. By default, the command unshares any
1211           file systems that are currently shared, unmounts any  file  systems
1212           that  are  currently mounted, and refuses to destroy a dataset that
1213           has active dependents (children or clones).
1214
1215           -r
1216
1217               Recursively destroy all children.
1218
1219
1220           -R
1221
1222               Recursively destroy all dependents, including cloned file  sys‐
1223               tems outside the target hierarchy.
1224
1225
1226           -f
1227
1228               Force  an unmount of any file systems using the unmount -f com‐
1229               mand.  This  option  has  no  effect  on  non-file  systems  or
1230               unmounted file systems.
1231
1232           Extreme  care should be taken when applying either the -r or the -f
1233           options, as they can destroy large portions of  a  pool  and  cause
1234           unexpected behavior for mounted file systems in use.
1235
1236
1237       zfs destroy [-rRd] snapshot
1238
1239           The  given snapshot is destroyed immediately if and only if the zfs
1240           destroy command without the -d option would have destroyed it. Such
1241           immediate destruction would occur, for example, if the snapshot had
1242           no clones and the user-initiated reference count were zero.
1243
1244           If the snapshot does not qualify for immediate destruction,  it  is
1245           marked for deferred deletion. In this state, it exists as a usable,
1246           visible snapshot until both of the preconditions listed  above  are
1247           met, at which point it is destroyed.
1248
1249           -d
1250
1251               Defer snapshot deletion.
1252
1253
1254           -r
1255
1256               Destroy (or mark for deferred deletion) all snapshots with this
1257               name in descendent file systems.
1258
1259
1260           -R
1261
1262               Recursively destroy all dependents.
1263
1264
1265
1266       zfs snapshot [-r] [-o property=value] ... filesystem@snapname|vol‐
1267       ume@snapname
1268
1269           Creates  a snapshot with the given name. All previous modifications
1270           by successful system calls to the file system are part of the snap‐
1271           shot. See the "Snapshots" section for details.
1272
1273           -r
1274
1275               Recursively  create snapshots of all descendent datasets. Snap‐
1276               shots are taken atomically, so  that  all  recursive  snapshots
1277               correspond to the same moment in time.
1278
1279
1280           -o property=value
1281
1282               Sets the specified property; see zfs create for details.
1283
1284
1285
1286       zfs rollback [-rRf] snapshot
1287
1288           Roll  back the given dataset to a previous snapshot. When a dataset
1289           is rolled back, all data that has changed  since  the  snapshot  is
1290           discarded,  and the dataset reverts to the state at the time of the
1291           snapshot. By default, the command refuses to roll back to  a  snap‐
1292           shot  other than the most recent one. In order to do so, all inter‐
1293           mediate snapshots must be destroyed by specifying the -r option.
1294
1295           The -rR options do not recursively destroy the child snapshots of a
1296           recursive  snapshot.  Only  the  top-level  recursive  snapshot  is
1297           destroyed by either of these options. To  completely  roll  back  a
1298           recursive  snapshot,  you  must rollback the individual child snap‐
1299           shots.
1300
1301           -r
1302
1303               Recursively destroy any snapshots  more  recent  than  the  one
1304               specified.
1305
1306
1307           -R
1308
1309               Recursively  destroy  any more recent snapshots, as well as any
1310               clones of those snapshots.
1311
1312
1313           -f
1314
1315               Used with the -R option to force an unmount of any  clone  file
1316               systems that are to be destroyed.
1317
1318
1319
1320       zfs clone [-p] [-o property=value] ... snapshot filesystem|volume
1321
1322           Creates a clone of the given snapshot. See the "Clones" section for
1323           details. The target dataset can be  located  anywhere  in  the  ZFS
1324           hierarchy, and is created as the same type as the original.
1325
1326           -p
1327
1328               Creates  all the non-existing parent datasets. Datasets created
1329               in this manner  are  automatically  mounted  according  to  the
1330               mountpoint  property inherited from their parent. If the target
1331               filesystem or volume already exists,  the  operation  completes
1332               successfully.
1333
1334
1335           -o property=value
1336
1337               Sets the specified property; see zfs create for details.
1338
1339
1340
1341       zfs promote clone-filesystem
1342
1343           Promotes a clone file system to no longer be dependent on its "ori‐
1344           gin" snapshot. This makes it possible to destroy  the  file  system
1345           that  the clone was created from. The clone parent-child dependency
1346           relationship is reversed, so that the origin file system becomes  a
1347           clone of the specified file system.
1348
1349           The  snapshot  that  was cloned, and any snapshots previous to this
1350           snapshot, are now owned by the promoted clone. The space  they  use
1351           moves  from the origin file system to the promoted clone, so enough
1352           space must be available to  accommodate  these  snapshots.  No  new
1353           space  is  consumed  by this operation, but the space accounting is
1354           adjusted. The promoted clone must not have any conflicting snapshot
1355           names  of  its own. The rename subcommand can be used to rename any
1356           conflicting snapshots.
1357
1358
1359       zfs rename filesystem|volume|snapshot
1360       filesystem|volume|snapshot
1361       zfs rename [-p] filesystem|volume filesystem|volume
1362
1363           Renames the given dataset. The new target can be  located  anywhere
1364           in  the  ZFS  hierarchy, with the exception of snapshots. Snapshots
1365           can only be renamed within the parent file system or  volume.  When
1366           renaming  a  snapshot,  the parent file system of the snapshot does
1367           not need to be specified as part of the  second  argument.  Renamed
1368           file  systems  can inherit new mount points, in which case they are
1369           unmounted and remounted at the new mount point.
1370
1371           -p
1372
1373               Creates all the nonexistent parent datasets.  Datasets  created
1374               in  this  manner  are  automatically  mounted  according to the
1375               mountpoint property inherited from their parent.
1376
1377
1378
1379       zfs rename -r snapshot snapshot
1380
1381           Recursively rename the snapshots of all descendent datasets.  Snap‐
1382           shots are the only dataset that can be renamed recursively.
1383
1384
1385       zfs list [-r|-d depth] [-H] [-o property[,...]] [ -t type[,...]] [ -s
1386       property ] ... [ -S property ] ... [filesystem|volume|snapshot] ...
1387
1388           Lists the property information for the given  datasets  in  tabular
1389           form.  If specified, you can list property information by the abso‐
1390           lute pathname or the relative pathname. By default, all  file  sys‐
1391           tems  and  volumes  are  displayed.  Snapshots are displayed if the
1392           listsnaps property is on (the  default  is  off)  .  The  following
1393           fields are displayed, name,used,available,referenced,mountpoint.
1394
1395           -H
1396
1397               Used  for  scripting  mode.  Do  not print headers and separate
1398               fields by a single tab instead of arbitrary white space.
1399
1400
1401           -r
1402
1403               Recursively display any children of the dataset on the  command
1404               line.
1405
1406
1407           -d depth
1408
1409               Recursively  display  any children of the dataset, limiting the
1410               recursion to depth. A depth of 1 will display only the  dataset
1411               and its direct children.
1412
1413
1414           -o property
1415
1416               A  comma-separated  list of properties to display. The property
1417               must be:
1418
1419                   o      One of the properties described in the "Native Prop‐
1420                          erties" section
1421
1422                   o      A user property
1423
1424                   o      The value name to display the dataset name
1425
1426                   o      The value space to display space usage properties on
1427                          file systems and volumes. This  is  a  shortcut  for
1428                          specifying  -o  name,avail,used,usedsnap,usedds,use‐
1429                          drefreserv,usedchild -t filesystem,volume syntax.
1430
1431
1432           -s property
1433
1434               A property for sorting the output by column in ascending  order
1435               based on the value of the property. The property must be one of
1436               the properties described in the "Properties"  section,  or  the
1437               special  value name to sort by the dataset name. Multiple prop‐
1438               erties can be specified at one time using multiple -s  property
1439               options.  Multiple  -s options are evaluated from left to right
1440               in decreasing order of importance.
1441
1442               The following is a list of sorting criteria:
1443
1444                   o      Numeric types sort in numeric order.
1445
1446                   o      String types sort in alphabetical order.
1447
1448                   o      Types inappropriate for a row sort that row  to  the
1449                          literal  bottom,  regardless of the specified order‐
1450                          ing.
1451
1452                   o      If no sorting options  are  specified  the  existing
1453                          behavior of zfs list is preserved.
1454
1455
1456           -S property
1457
1458               Same  as  the  -s  option,  but sorts by property in descending
1459               order.
1460
1461
1462           -t type
1463
1464               A comma-separated list of types to display, where type  is  one
1465               of filesystem, snapshot , volume, or all. For example, specify‐
1466               ing -t snapshot displays only snapshots.
1467
1468
1469
1470       zfs set property=value filesystem|volume|snapshot ...
1471
1472           Sets the property to the given value for each  dataset.  Only  some
1473           properties  can  be  edited.  See the "Properties" section for more
1474           information on what properties can be set  and  acceptable  values.
1475           Numeric  values  can  be  specified as exact values, or in a human-
1476           readable form with a suffix of B, K, M, G, T, P, E, Z  (for  bytes,
1477           kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or
1478           zettabytes, respectively). User properties can be set on snapshots.
1479           For more information, see the "User Properties" section.
1480
1481
1482       zfs get [-r|-d depth] [-Hp] [-o all | field[,...] [-s source[,...]] all
1483       | property[,...] filesystem|volume|snapshot ...
1484
1485           Displays properties for the given  datasets.  If  no  datasets  are
1486           specified, then the command displays properties for all datasets on
1487           the system. For each property, the following columns are displayed:
1488
1489                 name      Dataset name
1490                  property  Property name
1491                  value     Property value
1492                  source    Property source. Can either be local, default,
1493                            temporary, inherited, or none (-).
1494
1495
1496           All columns except the RECEIVED column are  displayed  by  default;
1497           specify  particular  or all columns, using the -o option. This com‐
1498           mand takes a comma-separated list of properties as described in the
1499           "Native Properties" and "User Properties" sections.
1500
1501           The  special  value  all can be used to display all properties that
1502           apply to the given dataset's type  (filesystem,  volume,  or  snap‐
1503           shot).
1504
1505           -r
1506
1507               Recursively display properties for any children.
1508
1509
1510           -d depth
1511
1512               Recursively  display  any children of the dataset, limiting the
1513               recursion to depth. A depth of 1 will display only the  dataset
1514               and its direct children.
1515
1516
1517           -H
1518
1519               Display  output  in  a  form more easily parsed by scripts. Any
1520               headers are omitted, and fields are explicitly separated  by  a
1521               single tab instead of an arbitrary amount of space.
1522
1523
1524           -o field
1525
1526               Set of fields to display. One or more of:
1527
1528                 name,property,value,received,source
1529
1530
1531               Present  multiple fields as a comma-separated list. The default
1532               value is:
1533
1534                 name,property,value,source
1535
1536
1537               The keyword all specifies all sources.
1538
1539
1540           -s source
1541
1542               A comma-separated list of sources to display. Those  properties
1543               coming from a source other than those in this list are ignored.
1544               Each source must be one of the following:
1545
1546                 local,default,inherited,temporary,received,none
1547
1548
1549               The default value is all sources.
1550
1551
1552           -p
1553
1554               Display numbers in parseable (exact) values.
1555
1556
1557
1558       zfs inherit [-rS] property filesystem|volume|snapshot ...
1559
1560           Clears the specified property, causing it to be inherited  from  an
1561           ancestor.  If  no  ancestor  has the property set, then the default
1562           value is used. See  the  "Properties"  section  for  a  listing  of
1563           default values, and details on which properties can be inherited.
1564
1565           -r
1566
1567               Recursively inherit the given property for all children.
1568
1569
1570           -S
1571
1572               Revert  to the received property value, if any. If the property
1573               does not have a received value, the behavior of zfs inherit  -S
1574               is  the  same  as  zfs inherit without -S. If the property does
1575               have a received value, zfs inherit  masks  the  received  value
1576               with  the  inherited  value until zfs inherit -S reverts to the
1577               received value.
1578
1579
1580
1581       zfs upgrade [-v]
1582
1583           Displays a list of file systems that are not the most  recent  ver‐
1584           sion.
1585
1586
1587       zfs upgrade [-r] [-V version] [-a | filesystem]
1588
1589           Upgrades  file systems to a new on-disk version. Once this is done,
1590           the file systems will no longer be accessible  on  systems  running
1591           older versions of the software. zfs send streams generated from new
1592           snapshots of these file systems cannot be accessed on systems  run‐
1593           ning older versions of the software.
1594
1595           In general, the file system version is independent of the pool ver‐
1596           sion. See zpool(1M) for information on the zpool upgrade command.
1597
1598           In some cases, the file system version and  the  pool  version  are
1599           interrelated  and the pool version must be upgraded before the file
1600           system version can be upgraded.
1601
1602           -a
1603
1604               Upgrade all file systems on all imported pools.
1605
1606
1607           filesystem
1608
1609               Upgrade the specified file system.
1610
1611
1612           -r
1613
1614               Upgrade the specified file system and all descendent file  sys‐
1615               tems
1616
1617
1618           -V version
1619
1620               Upgrade  to the specified version. If the -V flag is not speci‐
1621               fied, this command upgrades to the most  recent  version.  This
1622               option  can  only  be  used to increase the version number, and
1623               only up to the most recent version supported by this software.
1624
1625
1626
1627       zfs userspace [-niHp] [-o field[,...]] [-sS field]... [-t type [,...]]
1628       filesystem | snapshot
1629
1630           Displays  space consumed by, and quotas on, each user in the speci‐
1631           fied filesystem or snapshot. This corresponds to the  userused@user
1632           and userquota@user properties.
1633
1634           -n
1635
1636               Print numeric ID instead of user/group name.
1637
1638
1639           -H
1640
1641               Do not print headers, use tab-delimited output.
1642
1643
1644           -p
1645
1646               Use exact (parseable) numeric output.
1647
1648
1649           -o field[,...]
1650
1651               Display  only  the  specified  fields  from  the following set,
1652               type,name,used,quota.The default is to display all fields.
1653
1654
1655           -s field
1656
1657               Sort output by this field. The s and S flags may  be  specified
1658               multiple times to sort first by one field, then by another. The
1659               default is -s type -s name.
1660
1661
1662           -S field
1663
1664               Sort by this field in reverse order. See -s.
1665
1666
1667           -t type[,...]
1668
1669               Print  only  the  specified  types  from  the  following   set,
1670               all,posixuser,smbuser,posixgroup,smbgroup.
1671
1672               The default is -t posixuser,smbuser
1673
1674               The default can be changed to include group types.
1675
1676
1677           -i
1678
1679               Translate  SID to POSIX ID. The POSIX ID may be ephemeral if no
1680               mapping exists. Normal POSIX interfaces (for example,  stat(2),
1681               ls  -l)  perform  this translation, so the -i option allows the
1682               output from zfs userspace to be compared  directly  with  those
1683               utilities. However, -i may lead to confusion if some files were
1684               created by an SMB user before a SMB-to-POSIX name  mapping  was
1685               established.  In  such  a case, some files are owned by the SMB
1686               entity and some by the POSIX entity.  However,  the  -i  option
1687               will report that the POSIX entity has the total usage and quota
1688               for both.
1689
1690
1691
1692       zfs groupspace [-niHp] [-o field[,...]] [-sS field]... [-t type [,...]]
1693       filesystem | snapshot
1694
1695           Displays space consumed by, and quotas on, each group in the speci‐
1696           fied filesystem or snapshot. This subcommand is  identical  to  zfs
1697           userspace,  except  that the default types to display are -t posix‐
1698           group,smbgroup.
1699
1700             -
1701
1702
1703
1704
1705       zfs mount
1706
1707           Displays all ZFS file systems currently mounted.
1708
1709
1710       zfs mount [-vO] [-o options] -a | filesystem
1711
1712           Mounts ZFS file systems. Invoked automatically as part of the  boot
1713           process.
1714
1715           -o options
1716
1717               An  optional, comma-separated list of mount options to use tem‐
1718               porarily for the duration of  the  mount.  See  the  "Temporary
1719               Mount Point Properties" section for details.
1720
1721
1722           -O
1723
1724               Perform an overlay mount. See mount(1M) for more information.
1725
1726
1727           -v
1728
1729               Report mount progress.
1730
1731
1732           -a
1733
1734               Mount  all available ZFS file systems. Invoked automatically as
1735               part of the boot process.
1736
1737
1738           filesystem
1739
1740               Mount the specified filesystem.
1741
1742
1743
1744       zfs unmount [-f] -a | filesystem|mountpoint
1745
1746           Unmounts currently mounted ZFS file systems. Invoked  automatically
1747           as part of the shutdown process.
1748
1749           -f
1750
1751               Forcefully  unmount the file system, even if it is currently in
1752               use.
1753
1754
1755           -a
1756
1757               Unmount all available ZFS file systems.  Invoked  automatically
1758               as part of the boot process.
1759
1760
1761           filesystem|mountpoint
1762
1763               Unmount the specified filesystem. The command can also be given
1764               a path to a ZFS file system mount point on the system.
1765
1766
1767
1768       zfs share -a | filesystem
1769
1770           Shares available ZFS file systems.
1771
1772           -a
1773
1774               Share all available ZFS file systems. Invoked automatically  as
1775               part of the boot process.
1776
1777
1778           filesystem
1779
1780               Share  the  specified  filesystem according to the sharenfs and
1781               sharesmb properties. File systems are shared when the  sharenfs
1782               or sharesmb property is set.
1783
1784
1785
1786       zfs unshare -a | filesystem|mountpoint
1787
1788           Unshares  currently  shared ZFS file systems. This is invoked auto‐
1789           matically as part of the shutdown process.
1790
1791           -a
1792
1793               Unshare all available ZFS file systems.  Invoked  automatically
1794               as part of the boot process.
1795
1796
1797           filesystem|mountpoint
1798
1799               Unshare the specified filesystem. The command can also be given
1800               a path to a ZFS file system shared on the system.
1801
1802
1803
1804       zfs send [-DvRp] [-[iI] snapshot] snapshot
1805
1806           Creates a stream representation of the second  snapshot,  which  is
1807           written  to standard output. The output can be redirected to a file
1808           or to a different system (for example, using ssh(1). By default,  a
1809           full stream is generated.
1810
1811           -D
1812
1813               Perform  dedup  processing  on the stream. Deduplicated streams
1814               cannot be received on systems that do not  support  the  stream
1815               deduplication feature.
1816
1817
1818           -i snapshot
1819
1820               Generate  an  incremental stream from the first snapshot to the
1821               second snapshot. The incremental source  (the  first  snapshot)
1822               can  be  specified  as  the last component of the snapshot name
1823               (for example, the part after the @), and it is  assumed  to  be
1824               from the same file system as the second snapshot.
1825
1826               If  the  destination  is  a clone, the source may be the origin
1827               snapshot,  which  must  be  fully   specified   (for   example,
1828               pool/fs@origin, not just @origin).
1829
1830
1831           -I snapshot
1832
1833               Generate a stream package that sends all intermediary snapshots
1834               from the first snapshot to the second snapshot. For example, -I
1835               @a  fs@d  is similar to -i @a fs@b; -i @b fs@c; -i @c fs@d. The
1836               incremental source snapshot may be specified  as  with  the  -i
1837               option.
1838
1839
1840           -R
1841
1842               Generate a replication stream package, which will replicate the
1843               specified filesystem, and all descendent file  systems,  up  to
1844               the  named  snapshot. When received, all properties, snapshots,
1845               descendent file systems, and clones are preserved.
1846
1847               If the -i or -I flags are used in conjunction with the -R flag,
1848               an  incremental  replication  stream  is generated. The current
1849               values of properties, and  current  snapshot  and  file  system
1850               names  are  set  when the stream is received. If the -F flag is
1851               specified when this stream is received, snapshots and file sys‐
1852               tems that do not exist on the sending side are destroyed.
1853
1854
1855           -p
1856
1857               Send properties.
1858
1859
1860           -v
1861
1862               Print verbose information about the stream package generated.
1863
1864           The  format of the stream is committed. You will be able to receive
1865           your streams on future versions of ZFS.
1866
1867
1868       zfs receive [-vnFu] filesystem|volume|snapshot
1869       zfs receive [-vnFu] [-d | -e] filesystem
1870
1871           Creates a snapshot whose contents are as specified  in  the  stream
1872           provided  on  standard  input. If a full stream is received, then a
1873           new file system is created as well. Streams are created  using  the
1874           zfs  send  subcommand,  which by default creates a full stream. zfs
1875           recv can be used as an alias for zfs receive.
1876
1877           If an incremental stream is received,  then  the  destination  file
1878           system  must already exist, and its most recent snapshot must match
1879           the incremental stream's source. For zvols, the destination  device
1880           link  is  destroyed  and  recreated, which means the zvol cannot be
1881           accessed during the receive operation.
1882
1883           When a snapshot replication package stream  that  is  generated  by
1884           using  the  zfs send -R command is  received, any snapshots that do
1885           not exist on the sending location are destroyed by  using  the  zfs
1886           destroy -d command.
1887
1888           The  name  of  the  snapshot  (and file system, if a full stream is
1889           received) that this subcommand creates depends on the argument type
1890           and the -d or -e option.
1891
1892           If  the argument is a snapshot name, the specified snapshot is cre‐
1893           ated. If the argument is a file system or volume name,  a  snapshot
1894           with the same name as the sent snapshot is created within the spec‐
1895           ified filesystem or volume. If the -d or -e  option  is  specified,
1896           the  snapshot  name  is determined by appending the sent snapshot's
1897           name to the specified filesystem. If the -d  option  is  specified,
1898           all  but  the  pool name of the sent snapshot path is appended (for
1899           example, b/c@1 appended from sent snapshot a/b/c@1), and if the  -e
1900           option  is  specified,  only  the tail of the sent snapshot path is
1901           appended (for example, c@1 appended from sent snapshot a/b/c@1). In
1902           the  case  of  -d, any file systems needed to replicate the path of
1903           the sent snapshot are created within the specified file system.
1904
1905           -d
1906
1907               Use all but the first element of the sent  snapshot  path  (all
1908               but the pool name) to determine the name of the new snapshot as
1909               described in the paragraph above.
1910
1911
1912           -e
1913
1914               Use the last element of the sent snapshot path to determine the
1915               name of the new snapshot as described in the paragraph above.
1916
1917
1918           -u
1919
1920               File  system that is associated with the received stream is not
1921               mounted.
1922
1923
1924           -v
1925
1926               Print  verbose  information  about  the  stream  and  the  time
1927               required to perform the receive operation.
1928
1929
1930           -n
1931
1932               Do  not actually receive the stream. This can be useful in con‐
1933               junction with the -v option to  verify  the  name  the  receive
1934               operation would use.
1935
1936
1937           -F
1938
1939               Force a rollback of the file system to the most recent snapshot
1940               before performing the receive operation. If receiving an incre‐
1941               mental  replication  stream  (for example, one generated by zfs
1942               send -R -[iI]), destroy snapshots and file systems that do  not
1943               exist on the sending side.
1944
1945
1946
1947       zfs allow filesystem | volume
1948
1949           Displays  permissions  that  have  been  delegated on the specified
1950           filesystem or volume. See the other forms of  zfs  allow  for  more
1951           information.
1952
1953
1954       zfs allow [-ldug] "everyone"|user|group[,...] perm|@setname[,...]
1955       filesystem| volume
1956       zfs allow [-ld] -e perm|@setname[,...] filesystem | volume
1957
1958           Delegates ZFS administration permission for  the  file  systems  to
1959           non-privileged users.
1960
1961           [-ug] "everyone"|user|group[,...]
1962
1963               Specifies to whom the permissions are delegated. Multiple enti‐
1964               ties can be specified as a comma-separated list. If neither  of
1965               the -ug options are specified, then the argument is interpreted
1966               preferentially as the keyword "everyone", then as a user  name,
1967               and  lastly  as  a group name. To specify a user or group named
1968               "everyone", use the -u or -g options. To specify a  group  with
1969               the same name as a user, use the -g options.
1970
1971
1972           [-e] perm|@setname[,...]
1973
1974               Specifies that the permissions be delegated to "everyone." Mul‐
1975               tiple permissions may be specified as a  comma-separated  list.
1976               Permission  names  are  the same as ZFS subcommand and property
1977               names. See the property list below. Property set  names,  which
1978               begin  with  an at sign (@) , may be specified. See the -s form
1979               below for details.
1980
1981
1982           [-ld] filesystem|volume
1983
1984               Specifies where the permissions are delegated.  If  neither  of
1985               the  -ld  options  are specified, or both are, then the permis‐
1986               sions are allowed for the file system or volume, and all of its
1987               descendents.  If  only  the  -l option is used, then is allowed
1988               "locally" only for the specified file system. If  only  the  -d
1989               option  is  used,  then is allowed only for the descendent file
1990               systems.
1991
1992
1993
1994
1995       Permissions are generally the ability to use a ZFS subcommand or change
1996       a ZFS property. The following permissions are available:
1997
1998         NAME             TYPE           NOTES
1999         allow            subcommand     Must also have the permission that is
2000                                         being allowed
2001         clone            subcommand     Must also have the 'create' ability and
2002                                         'mount'
2003                                         ability in the origin file system
2004         create           subcommand     Must also have the 'mount' ability
2005         destroy          subcommand     Must also have the 'mount' ability
2006         hold             subcommand     Allows adding a user hold to a snapshot
2007         mount            subcommand     Allows mount/umount of ZFS datasets
2008         promote          subcommand     Must also have the 'mount' and 'promote'
2009                                         ability in the origin file system
2010         receive          subcommand     Must also have the 'mount' and 'create'
2011                                         ability
2012         release          subcommand     Allows releasing a user hold which
2013                                         might destroy the snapshot
2014         rename           subcommand     Must also have the 'mount' and 'create'
2015                                         ability in the new parent
2016         rollback         subcommand
2017         send             subcommand
2018         share            subcommand     Allows sharing file systems over NFS or
2019                                         SMB protocols
2020         snapshot         subcommand
2021         groupquota       other          Allows accessing any groupquota@...
2022                                         property
2023         groupused        other          Allows reading any groupused@... property
2024         userprop         other          Allows changing any user property
2025         userquota        other          Allows accessing any userquota@...
2026                                         property
2027         userused         other          Allows reading any userused@... property
2028         aclinherit       property
2029         aclmode          property
2030         atime            property
2031         canmount         property
2032         casesensitivity  property
2033         checksum         property
2034         compression      property
2035         copies           property
2036         dedup            property
2037         devices          property
2038         exec             property
2039         logbias          property
2040         mlslabel         property
2041         mountpoint       property
2042         nbmand           property
2043         normalization    property
2044         primarycache     property
2045         quota            property
2046         readonly         property
2047         recordsize       property
2048         refquota         property
2049         refreservation   property
2050         reservation      property
2051         secondarycache   property
2052         setuid           property
2053         shareiscsi       property
2054         sharenfs         property
2055         sharesmb         property
2056         snapdir          property
2057         utf8only         property
2058         version          property
2059         volblocksize     property
2060         volsize          property
2061         vscan            property
2062         xattr            property
2063         zoned            property
2064
2065
2066
2067       zfs allow -c perm|@setname[,...] filesystem|volume
2068
2069           Sets  "create  time"  permissions.  These  permissions  are granted
2070           (locally) to the creator of any newly-created descendent file  sys‐
2071           tem.
2072
2073
2074       zfs allow -s @setname perm|@setname[,...] filesystem|volume
2075
2076           Defines  or  adds  permissions  to a permission set. The set can be
2077           used by other zfs allow commands for the specified file system  and
2078           its  descendents.  Sets  are evaluated dynamically, so changes to a
2079           set are immediately reflected. Permission sets follow the same nam‐
2080           ing  restrictions as ZFS file systems, but the name must begin with
2081           an "at sign" (@), and can be no more than 64 characters long.
2082
2083
2084       zfs unallow [-rldug] "everyone"|user|group[,...] [perm|@setname[, ...]]
2085       filesystem|volume
2086       zfs unallow [-rld] -e [perm|@setname [,...]] filesystem|volume
2087       zfs unallow [-r] -c [perm|@setname[,...]]
2088       filesystem|volume
2089
2090           Removes  permissions  that were granted with the zfs allow command.
2091           No permissions are explicitly denied, so other permissions  granted
2092           are  still  in effect. For example, if the permission is granted by
2093           an ancestor. If no permissions are specified, then all  permissions
2094           for  the specified user, group, or everyone are removed. Specifying
2095           "everyone" (or using the -e option) only  removes  the  permissions
2096           that were granted to "everyone", not all permissions for every user
2097           and group. See the zfs allow  command  for  a  description  of  the
2098           -ldugec options.
2099
2100           -r
2101
2102               Recursively  remove  the  permissions from this file system and
2103               all descendents.
2104
2105
2106
2107       zfs unallow [-r] -s @setname [perm|@setname[,...]]
2108       filesystem|volume
2109
2110           Removes permissions from a permission set. If  no  permissions  are
2111           specified,  then all permissions are removed, thus removing the set
2112           entirely.
2113
2114
2115       zfs hold [-r] tag snapshot...
2116
2117           Adds a single reference, named with the tag argument, to the speci‐
2118           fied  snapshot  or  snapshots. Each snapshot has its own tag names‐
2119           pace, and tags must be unique within that space.
2120
2121           If a hold exists on a snapshot, attempts to destroy  that  snapshot
2122           by using the zfs destroy command return EBUSY.
2123
2124           -r
2125
2126               Specifies that a hold with the given tag is applied recursively
2127               to the snapshots of all descendent file systems.
2128
2129
2130
2131       zfs holds [-r] snapshot...
2132
2133           Lists all existing user references for the given snapshot or  snap‐
2134           shots.
2135
2136           -r
2137
2138               Lists the holds that are set on the named descendent snapshots,
2139               in addition to listing the holds on the named snapshot.
2140
2141
2142
2143       zfs release [-r] tag snapshot...
2144
2145           Removes a single reference, named with the tag argument,  from  the
2146           specified  snapshot  or  snapshots.  The tag must already exist for
2147           each snapshot.
2148
2149           If a hold exists on a snapshot, attempts to destroy  that  snapshot
2150           by using the zfs destroy command return EBUSY.
2151
2152           -r
2153
2154               Recursively releases a hold with the given tag on the snapshots
2155               of all descendent file systems.
2156
2157
2158

EXAMPLES

2160       Example 1 Creating a ZFS File System Hierarchy
2161
2162
2163       The following commands create a file system named pool/home and a  file
2164       system named pool/home/bob. The mount point /export/home is set for the
2165       parent file system, and is automatically inherited by  the  child  file
2166       system.
2167
2168
2169         # zfs create pool/home
2170         # zfs set mountpoint=/export/home pool/home
2171         # zfs create pool/home/bob
2172
2173
2174
2175       Example 2 Creating a ZFS Snapshot
2176
2177
2178       The following command creates a snapshot named yesterday. This snapshot
2179       is mounted on demand in the .zfs/snapshot directory at the root of  the
2180       pool/home/bob file system.
2181
2182
2183         # zfs snapshot pool/home/bob@yesterday
2184
2185
2186
2187       Example 3 Creating and Destroying Multiple Snapshots
2188
2189
2190       The  following  command  creates snapshots named yesterday of pool/home
2191       and all of its descendent file systems. Each  snapshot  is  mounted  on
2192       demand  in  the .zfs/snapshot directory at the root of its file system.
2193       The second command destroys the newly created snapshots.
2194
2195
2196         # zfs snapshot -r pool/home@yesterday
2197         # zfs destroy -r pool/home@yesterday
2198
2199
2200
2201       Example 4 Disabling and Enabling File System Compression
2202
2203
2204       The following command disables the compression property  for  all  file
2205       systems  under  pool/home. The next command explicitly enables compres‐
2206       sion for pool/home/anne.
2207
2208
2209         # zfs set compression=off pool/home
2210         # zfs set compression=on pool/home/anne
2211
2212
2213
2214       Example 5 Listing ZFS Datasets
2215
2216
2217       The following command lists all active file systems and volumes in  the
2218       system.  Snapshots  are  displayed if the listsnaps property is on. The
2219       default is off. See zpool(1M) for more information on pool properties.
2220
2221
2222         # zfs list
2223            NAME                      USED  AVAIL  REFER  MOUNTPOINT
2224            pool                      450K   457G    18K  /pool
2225            pool/home                 315K   457G    21K  /export/home
2226            pool/home/anne             18K   457G    18K  /export/home/anne
2227            pool/home/bob             276K   457G   276K  /export/home/bob
2228
2229
2230
2231       Example 6 Setting a Quota on a ZFS File System
2232
2233
2234       The following command sets a quota of 50 Gbytes for pool/home/bob.
2235
2236
2237         # zfs set quota=50G pool/home/bob
2238
2239
2240
2241       Example 7 Listing ZFS Properties
2242
2243
2244       The following command lists all properties for pool/home/bob.
2245
2246
2247         # zfs get all pool/home/bob
2248         NAME           PROPERTY              VALUE                  SOURCE
2249         pool/home/bob  type                  filesystem             -
2250         pool/home/bob  creation              Mon Nov  9 15:05 2009  -
2251         pool/home/bob  used                  282M                   -
2252         pool/home/bob  available             134G                   -
2253         pool/home/bob  referenced            282M                   -
2254         pool/home/bob  compressratio         1.00x                  -
2255         pool/home/bob  mounted               yes                    -
2256         pool/home/bob  quota                 none                   default
2257         pool/home/bob  reservation           none                   default
2258         pool/home/bob  recordsize            128K                   default
2259         pool/home/bob  mountpoint            /pool/home/bob         default
2260         pool/home/bob  sharenfs              off                    default
2261         pool/home/bob  checksum              on                     default
2262         pool/home/bob  compression           on                     local
2263         pool/home/bob  atime                 on                     default
2264         pool/home/bob  devices               on                     default
2265         pool/home/bob  exec                  on                     default
2266         pool/home/bob  setuid                on                     default
2267         pool/home/bob  readonly              off                    default
2268         pool/home/bob  zoned                 off                    default
2269         pool/home/bob  snapdir               hidden                 default
2270         pool/home/bob  aclmode               groupmask              default
2271         pool/home/bob  aclinherit            restricted             default
2272         pool/home/bob  canmount              on                     default
2273         pool/home/bob  shareiscsi            off                    default
2274         pool/home/bob  xattr                 on                     default
2275         pool/home/bob  copies                1                      default
2276         pool/home/bob  version               4                      -
2277         pool/home/bob  utf8only              off                    -
2278         pool/home/bob  normalization         none                   -
2279         pool/home/bob  casesensitivity       sensitive              -
2280         pool/home/bob  vscan                 off                    default
2281         pool/home/bob  nbmand                off                    default
2282         pool/home/bob  sharesmb              off                    default
2283         pool/home/bob  refquota              none                   default
2284         pool/home/bob  refreservation        none                   default
2285         pool/home/bob  primarycache          all                    default
2286         pool/home/bob  secondarycache        all                    default
2287         pool/home/bob  usedbysnapshots       0                      -
2288         pool/home/bob  usedbydataset         282M                   -
2289         pool/home/bob  usedbychildren        0                      -
2290         pool/home/bob  usedbyrefreservation  0                      -
2291         pool/home/bob  logbias               latency                default
2292         pool/home/bob  dedup                 off                    default
2293         pool/home/bob  mlslabel              none                   default
2294
2295
2296
2297
2298       The following command gets a single property value.
2299
2300
2301         # zfs get -H -o value compression pool/home/bob
2302         on
2303
2304
2305
2306
2307       The following command lists all  properties  with  local  settings  for
2308       pool/home/bob.
2309
2310
2311         # zfs get -r -s local -o name,property,value all pool/home/bob
2312         NAME           PROPERTY              VALUE
2313         pool/home/bob  quota                 20G
2314         pool/home/bob  compression           on
2315
2316
2317
2318       Example 8 Rolling Back a ZFS File System
2319
2320
2321       The  following  command  reverts  the contents of pool/home/anne to the
2322       snapshot named yesterday, deleting all intermediate snapshots.
2323
2324
2325         # zfs rollback -r pool/home/anne@yesterday
2326
2327
2328
2329       Example 9 Creating a ZFS Clone
2330
2331
2332       The following command creates a writable file system whose initial con‐
2333       tents are the same as pool/home/bob@yesterday.
2334
2335
2336         # zfs clone pool/home/bob@yesterday pool/clone
2337
2338
2339
2340       Example 10 Promoting a ZFS Clone
2341
2342
2343       The  following  commands  illustrate  how to test out changes to a file
2344       system, and then replace the original file system with the changed one,
2345       using clones, clone promotion, and renaming:
2346
2347
2348         # zfs create pool/project/production
2349           populate /pool/project/production with data
2350         # zfs snapshot pool/project/production@today
2351         # zfs clone pool/project/production@today pool/project/beta
2352         make changes to /pool/project/beta and test them
2353         # zfs promote pool/project/beta
2354         # zfs rename pool/project/production pool/project/legacy
2355         # zfs rename pool/project/beta pool/project/production
2356         once the legacy version is no longer needed, it can be destroyed
2357         # zfs destroy pool/project/legacy
2358
2359
2360
2361       Example 11 Inheriting ZFS Properties
2362
2363
2364       The  following  command  causes  pool/home/bob  and  pool/home/anne  to
2365       inherit the checksum property from their parent.
2366
2367
2368         # zfs inherit checksum pool/home/bob pool/home/anne
2369
2370
2371
2372       Example 12 Remotely Replicating ZFS Data
2373
2374
2375       The following commands send a  full  stream  and  then  an  incremental
2376       stream  to a remote machine, restoring them into poolB/received/fs@aand
2377       poolB/received/fs@b, respectively. poolB must contain the  file  system
2378       poolB/received, and must not initially contain poolB/received/fs.
2379
2380
2381         # zfs send pool/fs@a | \
2382            ssh host zfs receive poolB/received/fs@a
2383         # zfs send -i a pool/fs@b | ssh host \
2384            zfs receive poolB/received/fs
2385
2386
2387
2388       Example 13 Using the zfs receive -d Option
2389
2390
2391       The  following  command  sends a full stream of poolA/fsA/fsB@snap to a
2392       remote machine,  receiving  it  into  poolB/received/fsA/fsB@snap.  The
2393       fsA/fsB@snap portion of the received snapshot's name is determined from
2394       the name of the sent snapshot.  poolB  must  contain  the  file  system
2395       poolB/received.  If poolB/received/fsA does not exist, it is created as
2396       an empty file system.
2397
2398
2399         # zfs send poolA/fsA/fsB@snap | \
2400            ssh host zfs receive -d poolB/received
2401
2402
2403
2404       Example 14 Setting User Properties
2405
2406
2407       The following  example  sets  the  user-defined  com.example:department
2408       property for a dataset.
2409
2410
2411         # zfs set com.example:department=12345 tank/accounting
2412
2413
2414
2415       Example 15 Creating a ZFS Volume as an iSCSI Target Device
2416
2417
2418       The following example shows how to create a ZFS volume as an iSCSI tar‐
2419       get.
2420
2421
2422         # zfs create -V 2g pool/volumes/vol1
2423         # zfs set shareiscsi=on pool/volumes/vol1
2424         # iscsitadm list target
2425         Target: pool/volumes/vol1
2426          iSCSI Name:
2427          iqn.1986-03.com.sun:02:7b4b02a6-3277-eb1b-e686-a24762c52a8c
2428          Connections: 0
2429
2430
2431
2432
2433       After the iSCSI target is created, set up the iSCSI initiator. For more
2434       information about the Solaris iSCSI initiator, see iscsitadm(1M).
2435
2436       Example 16 Performing a Rolling Snapshot
2437
2438
2439       The following example shows how to maintain a history of snapshots with
2440       a consistent naming scheme. To keep a week's worth  of  snapshots,  the
2441       user destroys the oldest snapshot, renames the remaining snapshots, and
2442       then creates a new snapshot, as follows:
2443
2444
2445         # zfs destroy -r pool/users@7daysago
2446         # zfs rename -r pool/users@6daysago @7daysago
2447         # zfs rename -r pool/users@5daysago @6daysago
2448         # zfs rename -r pool/users@yesterday @5daysago
2449         # zfs rename -r pool/users@yesterday @4daysago
2450         # zfs rename -r pool/users@yesterday @3daysago
2451         # zfs rename -r pool/users@yesterday @2daysago
2452         # zfs rename -r pool/users@today @yesterday
2453         # zfs snapshot -r pool/users@today
2454
2455
2456
2457       Example 17 Setting sharenfs Property Options on a ZFS File System
2458
2459
2460       The following commands show how to set  sharenfs  property  options  to
2461       enable  rw  access  for a set of IP addresses and to enable root access
2462       for system neo on the tank/home file system.
2463
2464
2465         # # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
2466
2467
2468
2469
2470       If you are using DNS for host name resolution, specify the fully quali‐
2471       fied hostname.
2472
2473
2474       Example 18 Delegating ZFS Administration Permissions on a ZFS Dataset
2475
2476
2477       The  following example shows how to set permissions so that user cindys
2478       can create, destroy, mount, and take snapshots on tank/cindys. The per‐
2479       missions on tank/cindys are also displayed.
2480
2481
2482         # zfs allow cindys create,destroy,mount,snapshot tank/cindys
2483         # zfs allow tank/cindys
2484         -------------------------------------------------------------
2485         Local+Descendent permissions on (tank/cindys)
2486                   user cindys create,destroy,mount,snapshot
2487         -------------------------------------------------------------
2488
2489
2490
2491
2492       Because  the  tank/cindys  mount  point  permission  is  set  to 755 by
2493       default, user cindys  will  be  unable  to  mount  file  systems  under
2494       tank/cindys.  Set  an  ACL  similar  to the following syntax to provide
2495       mount point access:
2496
2497         # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
2498
2499
2500
2501       Example 19 Delegating Create Time Permissions on a ZFS Dataset
2502
2503
2504       The following example shows how to grant anyone in the group  staff  to
2505       create  file  systems in tank/users. This syntax also allows staff mem‐
2506       bers to destroy their own file systems, but not destroy  anyone  else's
2507       file system. The permissions on tank/users are also displayed.
2508
2509
2510         # # zfs allow staff create,mount tank/users
2511         # zfs allow -c destroy tank/users
2512         # zfs allow tank/users
2513         -------------------------------------------------------------
2514         Create time permissions on (tank/users)
2515                   create,destroy
2516         Local+Descendent permissions on (tank/users)
2517                   group staff create,mount
2518         -------------------------------------------------------------
2519
2520
2521
2522       Example 20 Defining and Granting a Permission Set on a ZFS Dataset
2523
2524
2525       The following example shows how to define and grant a permission set on
2526       the tank/users file system. The permissions on tank/users are also dis‐
2527       played.
2528
2529
2530         # zfs allow -s @pset create,destroy,snapshot,mount tank/users
2531         # zfs allow staff @pset tank/users
2532         # zfs allow tank/users
2533         -------------------------------------------------------------
2534         Permission sets on (tank/users)
2535                 @pset create,destroy,mount,snapshot
2536         Create time permissions on (tank/users)
2537                 create,destroy
2538         Local+Descendent permissions on (tank/users)
2539                 group staff @pset,create,mount
2540         -------------------------------------------------------------
2541
2542
2543
2544       Example 21 Delegating Property Permissions on a ZFS Dataset
2545
2546
2547       The  following  example  shows  to  grant the ability to set quotas and
2548       reservations  on  the  users/home  file  system.  The  permissions   on
2549       users/home are also displayed.
2550
2551
2552         # zfs allow cindys quota,reservation users/home
2553         # zfs allow users/home
2554         -------------------------------------------------------------
2555         Local+Descendent permissions on (users/home)
2556                 user cindys quota,reservation
2557         -------------------------------------------------------------
2558         cindys% zfs set quota=10G users/home/marks
2559         cindys% zfs get quota users/home/marks
2560         NAME              PROPERTY  VALUE             SOURCE
2561         users/home/marks  quota     10G               local
2562
2563
2564
2565       Example 22 Removing ZFS Delegated Permissions on a ZFS Dataset
2566
2567
2568       The  following example shows how to remove the snapshot permission from
2569       the staff group on the  tank/users  file  system.  The  permissions  on
2570       tank/users are also displayed.
2571
2572
2573         # zfs unallow staff snapshot tank/users
2574         # zfs allow tank/users
2575         -------------------------------------------------------------
2576         Permission sets on (tank/users)
2577                 @pset create,destroy,mount,snapshot
2578         Create time permissions on (tank/users)
2579                 create,destroy
2580         Local+Descendent permissions on (tank/users)
2581                 group staff @pset,create,mount
2582         -------------------------------------------------------------
2583
2584
2585

EXIT STATUS

2587       The following exit values are returned:
2588
2589       0
2590
2591           Successful completion.
2592
2593
2594       1
2595
2596           An error occurred.
2597
2598
2599       2
2600
2601           Invalid command line options were specified.
2602
2603

ATTRIBUTES

2605       See attributes(5) for descriptions of the following attributes:
2606
2607
2608
2609
2610       ┌─────────────────────────────┬─────────────────────────────┐
2611       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
2612       ├─────────────────────────────┼─────────────────────────────┤
2613       │Availability                 │SUNWzfsu                     │
2614       ├─────────────────────────────┼─────────────────────────────┤
2615       │Interface Stability          │Committed                    │
2616       └─────────────────────────────┴─────────────────────────────┘
2617

SEE ALSO

2619       ssh(1), iscsitadm(1M), mount(1M), share(1M), sharemgr(1M), unshare(1M),
2620       zonecfg(1M),  zpool(1M),  chmod(2),   stat(2),   write(2),   fsync(3C),
2621       dfstab(4), attributes(5)
2622
2623
2624       See  the gzip(1) man page, which is not part of the SunOS man page col‐
2625       lection.
2626
2627
2628       For information about using the ZFS web-based management tool and other
2629       ZFS features, see the Solaris ZFS Administration Guide.
2630
2631
2632
2633SunOS 5.11                        21 Dec 2009                          zfs(1M)
Impressum