-
Notifications
You must be signed in to change notification settings - Fork 752
/
zfs.1m
3519 lines (3517 loc) · 107 KB
/
zfs.1m
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
.\" Copyright (c) 2011, 2015 by Delphix. All rights reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
.\" Copyright (c) 2014 Integros [integros.com]
.\" Copyright 2016 Nexenta Systems, Inc.
.\"
.Dd March 20, 2016
.Dt ZFS 1M
.Os
.Sh NAME
.Nm zfs
.Nd configures ZFS file systems
.Sh SYNOPSIS
.Nm
.Op Fl \?
.Nm
.Cm create
.Op Fl p
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Ar filesystem
.Nm
.Cm create
.Op Fl ps
.Op Fl b Ar blocksize
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Fl V Ar size Ar volume
.Nm
.Cm destroy
.Op Fl Rfnprv
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm destroy
.Op Fl Rdnprv
.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
.Nm
.Cm destroy
.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
.Nm
.Cm snapshot
.Op Fl r
.Oo Fl o Ar property Ns = Ns value Oc Ns ...
.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
.Nm
.Cm rollback
.Op Fl Rfr
.Ar snapshot
.Nm
.Cm clone
.Op Fl p
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Ar snapshot Ar filesystem Ns | Ns Ar volume
.Nm
.Cm promote
.Ar clone-filesystem
.Nm
.Cm rename
.Op Fl f
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
.Nm
.Cm rename
.Op Fl fp
.Ar filesystem Ns | Ns Ar volume
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm rename
.Fl r
.Ar snapshot Ar snapshot
.Nm
.Cm list
.Op Fl r Ns | Ns Fl d Ar depth
.Op Fl Hp
.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
.Oo Fl s Ar property Oc Ns ...
.Oo Fl S Ar property Oc Ns ...
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
.Nm
.Cm set
.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
.Nm
.Cm get
.Op Fl r Ns | Ns Fl d Ar depth
.Op Fl Hp
.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
.Nm
.Cm inherit
.Op Fl rS
.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
.Nm
.Cm upgrade
.Nm
.Cm upgrade
.Fl v
.Nm
.Cm upgrade
.Op Fl r
.Op Fl V Ar version
.Fl a | Ar filesystem
.Nm
.Cm userspace
.Op Fl Hinp
.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
.Oo Fl s Ar field Oc Ns ...
.Oo Fl S Ar field Oc Ns ...
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar snapshot
.Nm
.Cm groupspace
.Op Fl Hinp
.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
.Oo Fl s Ar field Oc Ns ...
.Oo Fl S Ar field Oc Ns ...
.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar snapshot
.Nm
.Cm mount
.Nm
.Cm mount
.Op Fl Ov
.Op Fl o Ar options
.Fl a | Ar filesystem
.Nm
.Cm unmount
.Op Fl f
.Fl a | Ar filesystem Ns | Ns Ar mountpoint
.Nm
.Cm share
.Fl a | Ar filesystem
.Nm
.Cm unshare
.Fl a | Ar filesystem Ns | Ns Ar mountpoint
.Nm
.Cm bookmark
.Ar snapshot bookmark
.Nm
.Cm send
.Op Fl DLPRenpv
.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
.Ar snapshot
.Nm
.Cm send
.Op Fl Le
.Op Fl i Ar snapshot Ns | Ns Ar bookmark
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
.Nm
.Cm send
.Op Fl Penv
.Fl t Ar receive_resume_token
.Nm
.Cm receive
.Op Fl Fnsuv
.Op Fl o Sy origin Ns = Ns Ar snapshot
.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
.Nm
.Cm receive
.Op Fl Fnsuv
.Op Fl d Ns | Ns Fl e
.Op Fl o Sy origin Ns = Ns Ar snapshot
.Ar filesystem
.Nm
.Cm receive
.Fl A
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm allow
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm allow
.Op Fl dglu
.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ...
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm allow
.Op Fl dl
.Fl e Ns | Ns Sy everyone
.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ...
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm allow
.Fl c
.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ...
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm allow
.Fl s No @ Ns Ar setname
.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ...
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm unallow
.Op Fl dglru
.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm unallow
.Op Fl dlr
.Fl e Ns | Ns Sy everyone
.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm unallow
.Op Fl r
.Fl c
.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm unallow
.Op Fl r
.Fl s @ Ns Ar setname
.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
.Ar setname Oc Ns ... Oc
.Ar filesystem Ns | Ns Ar volume
.Nm
.Cm hold
.Op Fl r
.Ar tag Ar snapshot Ns ...
.Nm
.Cm holds
.Op Fl r
.Ar snapshot Ns ...
.Nm
.Cm release
.Op Fl r
.Ar tag Ar snapshot Ns ...
.Nm
.Cm diff
.Op Fl FHt
.Ar snapshot Ar snapshot Ns | Ns Ar filesystem
.Sh DESCRIPTION
The
.Nm
command configures ZFS datasets within a ZFS storage pool, as described in
.Xr zpool 1M .
A dataset is identified by a unique path within the ZFS namespace. For example:
.Bd -literal
pool/{filesystem,volume,snapshot}
.Ed
.Pp
where the maximum length of a dataset name is
.Dv MAXNAMELEN
.Pq 256 bytes .
.Pp
A dataset can be one of the following:
.Bl -tag -width "file system"
.It Sy file system
A ZFS dataset of type
.Sy filesystem
can be mounted within the standard system namespace and behaves like other file
systems. While ZFS file systems are designed to be POSIX compliant, known issues
exist that prevent compliance in some cases. Applications that depend on
standards conformance might fail due to non-standard behavior when checking file
system free space.
.It Sy volume
A logical volume exported as a raw or block device. This type of dataset should
only be used under special circumstances. File systems are typically used in
most environments.
.It Sy snapshot
A read-only version of a file system or volume at a given point in time. It is
specified as
.Ar filesystem Ns @ Ns Ar name
or
.Ar volume Ns @ Ns Ar name .
.El
.Ss ZFS File System Hierarchy
A ZFS storage pool is a logical collection of devices that provide space for
datasets. A storage pool is also the root of the ZFS file system hierarchy.
.Pp
The root of the pool can be accessed as a file system, such as mounting and
unmounting, taking snapshots, and setting properties. The physical storage
characteristics, however, are managed by the
.Xr zpool 1M
command.
.Pp
See
.Xr zpool 1M
for more information on creating and administering pools.
.Ss Snapshots
A snapshot is a read-only copy of a file system or volume. Snapshots can be
created extremely quickly, and initially consume no additional space within the
pool. As data within the active dataset changes, the snapshot consumes more
data than would otherwise be shared with the active dataset.
.Pp
Snapshots can have arbitrary names. Snapshots of volumes can be cloned or
rolled back, but cannot be accessed independently.
.Pp
File system snapshots can be accessed under the
.Pa .zfs/snapshot
directory in the root of the file system. Snapshots are automatically mounted on
demand and may be unmounted at regular intervals. The visibility of the
.Pa .zfs
directory can be controlled by the
snapdir
property.
.Ss Clones
A clone is a writable volume or file system whose initial contents are the same
as another dataset. As with snapshots, creating a clone is nearly instantaneous,
and initially consumes no additional space.
.Pp
Clones can only be created from a snapshot. When a snapshot is cloned, it
creates an implicit dependency between the parent and child. Even though the
clone is created somewhere else in the dataset hierarchy, the original snapshot
cannot be destroyed as long as a clone exists. The
.Sy origin
property exposes this dependency, and the
.Cm destroy
command lists any such dependencies, if they exist.
.Pp
The clone parent-child dependency relationship can be reversed by using the
.Cm promote
subcommand. This causes the
.Qq origin
file system to become a clone of the specified file system, which makes it
possible to destroy the file system that the clone was created from.
.Ss "Mount Points"
Creating a ZFS file system is a simple operation, so the number of file systems
per system is likely to be numerous. To cope with this, ZFS automatically
manages mounting and unmounting file systems without the need to edit the
.Pa /etc/vfstab
file. All automatically managed file systems are mounted by ZFS at boot time.
.Pp
By default, file systems are mounted under
.Pa /path ,
where
.Ar path
is the name of the file system in the ZFS namespace. Directories are created and
destroyed as needed.
.Pp
A file system can also have a mount point set in the
.Sy mountpoint
property. This directory is created as needed, and ZFS automatically mounts the
file system when the
.Nm zfs Cm mount Fl a
command is invoked
.Po without editing
.Pa /etc/vfstab
.Pc .
The
.Sy mountpoint
property can be inherited, so if
.Em pool/home
has a mount point of
.Pa /export/stuff ,
then
.Em pool/home/user
automatically inherits a mount point of
.Pa /export/stuff/user .
.Pp
A file system
.Sy mountpoint
property of
.Sy none
prevents the file system from being mounted.
.Pp
If needed, ZFS file systems can also be managed with traditional tools
.Po
.Nm mount ,
.Nm umount ,
.Pa /etc/vfstab
.Pc .
If a file system's mount point is set to
.Sy legacy ,
ZFS makes no attempt to manage the file system, and the administrator is
responsible for mounting and unmounting the file system.
.Ss "Zones"
A ZFS file system can be added to a non-global zone by using the
.Nm zonecfg Cm add Sy fs
subcommand. A ZFS file system that is added to a non-global zone must have its
.Sy mountpoint
property set to
.Sy legacy .
.Pp
The physical properties of an added file system are controlled by the global
administrator. However, the zone administrator can create, modify, or destroy
files within the added file system, depending on how the file system is mounted.
.Pp
A dataset can also be delegated to a non-global zone by using the
.Nm zonecfg Cm add Sy dataset
subcommand. You cannot delegate a dataset to one zone and the children of the
same dataset to another zone. The zone administrator can change properties of
the dataset or any of its children. However, the
.Sy quota ,
.Sy filesystem_limit
and
.Sy snapshot_limit
properties of the delegated dataset can be modified only by the global
administrator.
.Pp
A ZFS volume can be added as a device to a non-global zone by using the
.Nm zonecfg Cm add Sy device
subcommand. However, its physical properties can be modified only by the global
administrator.
.Pp
For more information about
.Nm zonecfg
syntax, see
.Xr zonecfg 1M .
.Pp
After a dataset is delegated to a non-global zone, the
.Sy zoned
property is automatically set. A zoned file system cannot be mounted in the
global zone, since the zone administrator might have to set the mount point to
an unacceptable value.
.Pp
The global administrator can forcibly clear the
.Sy zoned
property, though this should be done with extreme care. The global administrator
should verify that all the mount points are acceptable before clearing the
property.
.Ss Native Properties
Properties are divided into two types, native properties and user-defined
.Po or
.Qq user
.Pc
properties. Native properties either export internal statistics or control ZFS
behavior. In addition, native properties are either editable or read-only. User
properties have no effect on ZFS behavior, but you can use them to annotate
datasets in a way that is meaningful in your environment. For more information
about user properties, see the
.Sx User Properties
section, below.
.Pp
Every dataset has a set of properties that export statistics about the dataset
as well as control various behaviors. Properties are inherited from the parent
unless overridden by the child. Some properties apply only to certain types of
datasets
.Pq file systems, volumes, or snapshots .
.Pp
The values of numeric properties can be specified using human-readable suffixes
.Po for example,
.Sy k ,
.Sy KB ,
.Sy M ,
.Sy Gb ,
and so forth, up to
.Sy Z
for zettabyte
.Pc .
The following are all valid
.Pq and equal
specifications:
.Li 1536M, 1.5g, 1.50GB .
.Pp
The values of non-numeric properties are case sensitive and must be lowercase,
except for
.Sy mountpoint ,
.Sy sharenfs ,
and
.Sy sharesmb .
.Pp
The following native properties consist of read-only statistics about the
dataset. These properties can be neither set, nor inherited. Native properties
apply to all dataset types unless otherwise noted.
.Bl -tag -width "usedbyrefreservation"
.It Sy available
The amount of space available to the dataset and all its children, assuming that
there is no other activity in the pool. Because space is shared within a pool,
availability can be limited by any number of factors, including physical pool
size, quotas, reservations, or other datasets within the pool.
.Pp
This property can also be referred to by its shortened column name,
.Sy avail .
.It Sy compressratio
For non-snapshots, the compression ratio achieved for the
.Sy used
space of this dataset, expressed as a multiplier. The
.Sy used
property includes descendant datasets, and, for clones, does not include the
space shared with the origin snapshot. For snapshots, the
.Sy compressratio
is the same as the
.Sy refcompressratio
property. Compression can be turned on by running:
.Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
The default value is
.Sy off .
.It Sy creation
The time this dataset was created.
.It Sy clones
For snapshots, this property is a comma-separated list of filesystems or volumes
which are clones of this snapshot. The clones'
.Sy origin
property is this snapshot. If the
.Sy clones
property is not empty, then this snapshot can not be destroyed
.Po even with the
.Fl r
or
.Fl f
options
.Pc .
.It Sy defer_destroy
This property is
.Sy on
if the snapshot has been marked for deferred destroy by using the
.Nm zfs Cm destroy Fl d
command. Otherwise, the property is
.Sy off .
.It Sy filesystem_count
The total number of filesystems and volumes that exist under this location in
the dataset tree. This value is only available when a
.Sy filesystem_limit
has been set somewhere in the tree under which the dataset resides.
.It Sy logicalreferenced
The amount of space that is
.Qq logically
accessible by this dataset. See the
.Sy referenced
property. The logical space ignores the effect of the
.Sy compression
and
.Sy copies
properties, giving a quantity closer to the amount of data that applications
see. However, it does include space consumed by metadata.
.Pp
This property can also be referred to by its shortened column name,
.Sy lrefer .
.It Sy logicalused
The amount of space that is
.Qq logically
consumed by this dataset and all its descendents. See the
.Sy used
property. The logical space ignores the effect of the
.Sy compression
and
.Sy copies
properties, giving a quantity closer to the amount of data that applications
see. However, it does include space consumed by metadata.
.Pp
This property can also be referred to by its shortened column name,
.Sy lused .
.It Sy mounted
For file systems, indicates whether the file system is currently mounted. This
property can be either
.Sy yes
or
.Sy no .
.It Sy origin
For cloned file systems or volumes, the snapshot from which the clone was
created. See also the
.Sy clones
property.
.It Sy receive_resume_token
For filesystems or volumes which have saved partially-completed state from
.Sy zfs receive -s ,
this opaque token can be provided to
.Sy zfs send -t
to resume and complete the
.Sy zfs receive .
.It Sy referenced
The amount of data that is accessible by this dataset, which may or may not be
shared with other datasets in the pool. When a snapshot or clone is created, it
initially references the same amount of space as the file system or snapshot it
was created from, since its contents are identical.
.Pp
This property can also be referred to by its shortened column name,
.Sy refer .
.It Sy refcompressratio
The compression ratio achieved for the
.Sy referenced
space of this dataset, expressed as a multiplier. See also the
.Sy compressratio
property.
.It Sy snapshot_count
The total number of snapshots that exist under this location in the dataset
tree. This value is only available when a
.Sy snapshot_limit
has been set somewhere in the tree under which the dataset resides.
.It Sy type
The type of dataset:
.Sy filesystem ,
.Sy volume ,
or
.Sy snapshot .
.It Sy used
The amount of space consumed by this dataset and all its descendents. This is
the value that is checked against this dataset's quota and reservation. The
space used does not include this dataset's reservation, but does take into
account the reservations of any descendent datasets. The amount of space that a
dataset consumes from its parent, as well as the amount of space that are freed
if this dataset is recursively destroyed, is the greater of its space used and
its reservation.
.Pp
When snapshots
.Po see the
.Sx Snapshots
section
.Pc
are created, their space is initially shared between the snapshot and
the file system, and possibly with previous snapshots. As the file system
changes, space that was previously shared becomes unique to the snapshot, and
counted in the snapshot's space used. Additionally, deleting snapshots can
increase the amount of space unique to
.Pq and used by
other snapshots.
.Pp
The amount of space used, available, or referenced does not take into account
pending changes. Pending changes are generally accounted for within a few
seconds. Committing a change to a disk using
.Xr fsync 3C
or
.Dv O_SYNC
does not necessarily guarantee that the space usage information is updated
immediately.
.It Sy usedby*
The
.Sy usedby*
properties decompose the
.Sy used
properties into the various reasons that space is used. Specifically,
.Sy used No =
.Sy usedbychildren No +
.Sy usedbydataset No +
.Sy usedbyrefreservation No +
.Sy usedbysnapshots .
These properties are only available for datasets created on
.Nm zpool
.Qo version 13 Qc
pools.
.It Sy usedbychildren
The amount of space used by children of this dataset, which would be freed if
all the dataset's children were destroyed.
.It Sy usedbydataset
The amount of space used by this dataset itself, which would be freed if the
dataset were destroyed
.Po after first removing any
.Sy refreservation
and destroying any necessary snapshots or descendents
.Pc .
.It Sy usedbyrefreservation
The amount of space used by a
.Sy refreservation
set on this dataset, which would be freed if the
.Sy refreservation
was removed.
.It Sy usedbysnapshots
The amount of space consumed by snapshots of this dataset. In particular, it is
the amount of space that would be freed if all of this dataset's snapshots were
destroyed. Note that this is not simply the sum of the snapshots'
.Sy used
properties because space can be shared by multiple snapshots.
.It Sy userused Ns @ Ns Em user
The amount of space consumed by the specified user in this dataset. Space is
charged to the owner of each file, as displayed by
.Nm ls Fl l .
The amount of space charged is displayed by
.Nm du
and
.Nm ls Fl s .
See the
.Nm zfs Cm userspace
subcommand for more information.
.Pp
Unprivileged users can access only their own space usage. The root user, or a
user who has been granted the
.Sy userused
privilege with
.Nm zfs Cm allow ,
can access everyone's usage.
.Pp
The
.Sy userused Ns @ Ns Em ...
properties are not displayed by
.Nm zfs Cm get Sy all .
The user's name must be appended after the @ symbol, using one of the following
forms:
.Bl -bullet -width ""
.It
.Em POSIX name
.Po for example,
.Sy joe
.Pc
.It
.Em POSIX numeric ID
.Po for example,
.Sy 789
.Pc
.It
.Em SID name
.Po for example,
.Sy joe.smith@mydomain
.Pc
.It
.Em SID numeric ID
.Po for example,
.Sy S-1-123-456-789
.Pc
.El
.It Sy userrefs
This property is set to the number of user holds on this snapshot. User holds
are set by using the
.Nm zfs Cm hold
command.
.It Sy groupused Ns @ Ns Em group
The amount of space consumed by the specified group in this dataset. Space is
charged to the group of each file, as displayed by
.Nm ls Fl l .
See the
.Sy userused Ns @ Ns Em user
property for more information.
.Pp
Unprivileged users can only access their own groups' space usage. The root user,
or a user who has been granted the
.Sy groupused
privilege with
.Nm zfs Cm allow ,
can access all groups' usage.
.It Sy volblocksize Ns = Ns Em blocksize
For volumes, specifies the block size of the volume. The
.Sy blocksize
cannot be changed once the volume has been written, so it should be set at
volume creation time. The default
.Sy blocksize
for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid.
.Pp
This property can also be referred to by its shortened column name,
.Sy volblock .
.It Sy written
The amount of
.Sy referenced
space written to this dataset since the previous snapshot.
.It Sy written Ns @ Ns Em snapshot
The amount of
.Sy referenced
space written to this dataset since the specified snapshot. This is the space
that is referenced by this dataset but was not referenced by the specified
snapshot.
.Pp
The
.Em snapshot
may be specified as a short snapshot name
.Po just the part after the
.Sy @
.Pc ,
in which case it will be interpreted as a snapshot in the same filesystem as
this dataset. The
.Em snapshot
may be a full snapshot name
.Po Em filesystem Ns @ Ns Em snapshot Pc ,
which for clones may be a snapshot in the origin's filesystem
.Pq or the origin of the origin's filesystem, etc.
.El
.Pp
The following native properties can be used to change the behavior of a ZFS
dataset.
.Bl -tag -width ""
.It Xo
.Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
.Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
.Xc
Controls how ACEs are inherited when files and directories are created.
.Bl -tag -width "passthrough-x"
.It Sy discard
does not inherit any ACEs.
.It Sy noallow
only inherits inheritable ACEs that specify
.Qq deny
permissions.
.It Sy restricted
default, removes the
.Sy write_acl
and
.Sy write_owner
permissions when the ACE is inherited.
.It Sy passthrough
inherits all inheritable ACEs without any modifications.
.It Sy passthrough-x
same meaning as
.Sy passthrough ,
except that the
.Sy owner@ ,
.Sy group@ ,
and
.Sy everyone@
ACEs inherit the execute permission only if the file creation mode also requests
the execute bit.
.El
.Pp
When the property value is set to
.Sy passthrough ,
files are created with a mode determined by the inheritable ACEs.
If no inheritable ACEs exist that affect the mode, then the mode is set in
accordance to the requested mode from the application.
.It Xo
.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
.Sy passthrough Ns | Ns Sy restricted
.Xc
Controls how an ACL is modified during
.Xr chmod 2
and how inherited ACEs are modified by the file creation mode.
.Bl -tag -width "passthrough"
.It Sy discard
default, deletes all ACEs except for those representing the mode of the file or
directory requested by
.Xr chmod 2 .
.It Sy groupmask
reduces permissions granted by all
.Sy ALLOW
entries found in the ACL such that they are no greater than the group
permissions specified by the mode.
.It Sy passthrough
indicates that no changes are made to the ACL other than creating or updating
the necessary ACEs to represent the new mode of the file or directory.
.It Sy restricted
causes the
.Xr chmod 2
operation to return an error when used on any file or directory which has a
non-trivial ACL, with entries in addition to those that represent the mode.
.El
.Pp
.Xr chmod 2
is required to change the set user ID, set group ID, or sticky bit on a file or
directory, as they do not have equivalent ACEs. In order to use
.Xr chmod 2
on a file or directory with a non-trivial ACL when
.Sy aclmode
is set to
.Sy restricted ,
you must first remove all ACEs except for those that represent the current mode.
.It Sy atime Ns = Ns Sy on Ns | Ns Sy off
Controls whether the access time for files is updated when they are read.
Turning this property off avoids producing write traffic when reading files and
can result in significant performance gains, though it might confuse mailers
and other similar utilities. The default value is
.Sy on .
.It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
If this property is set to
.Sy off ,
the file system cannot be mounted, and is ignored by
.Nm zfs Cm mount Fl a .
Setting this property to
.Sy off
is similar to setting the
.Sy mountpoint
property to
.Sy none ,
except that the dataset still has a normal
.Sy mountpoint
property, which can be inherited. Setting this property to
.Sy off
allows datasets to be used solely as a mechanism to inherit properties. One
example of setting
.Sy canmount Ns = Ns Sy off
is to have two datasets with the same
.Sy mountpoint ,
so that the children of both datasets appear in the same directory, but might
have different inherited characteristics.
.Pp
When set to
.Sy noauto ,
a dataset can only be mounted and unmounted explicitly. The dataset is not
mounted automatically when the dataset is created or imported, nor is it mounted
by the
.Nm zfs Cm mount Fl a
command or unmounted by the
.Nm zfs Cm unmount Fl a
command.
.Pp
This property is not inherited.
.It Xo
.Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
.Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
.Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
.Xc
Controls the checksum used to verify data integrity. The default value is
.Sy on ,
which automatically selects an appropriate algorithm
.Po currently,
.Sy fletcher4 ,
but this may change in future releases
.Pc .
The value
.Sy off
disables integrity checking on user data. The value
.Sy noparity
not only disables integrity but also disables maintaining parity for user data.
This setting is used internally by a dump device residing on a RAID-Z pool and
should not be used by any other dataset. Disabling checksums is
.Sy NOT
a recommended practice.
.Pp
The
.Sy sha512 ,
.Sy skein ,
and
.Sy edonr
checksum algorithms require enabling the appropriate features on the
pool. Please see
.Xr zpool-features 5
for more information on these algorithms.
.Pp
Changing this property affects only newly-written data.
.It Xo
.Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
.Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
.Xc
Controls the compression algorithm used for this dataset.
.Pp
Setting compression to
.Sy on
indicates that the current default compression algorithm should be used. The
default balances compression and decompression speed, with compression ratio and
is expected to work well on a wide variety of workloads. Unlike all other
settings for this property,
.Sy on
does not select a fixed compression type. As new compression algorithms are
added to ZFS and enabled on a pool, the default compression algorithm may
change. The current default compression algorthm is either
.Sy lzjb
or, if the
.Sy lz4_compress
feature is enabled,
.Sy lz4 .
.Pp
The
.Sy lz4
compression algorithm is a high-performance replacement for the
.Sy lzjb
algorithm. It features significantly faster compression and decompression, as
well as a moderately higher compression ratio than
.Sy lzjb ,
but can only be used on pools with the
.Sy lz4_compress
feature set to
.Sy enabled .
See
.Xr zpool-features 5
for details on ZFS feature flags and the
.Sy lz4_compress
feature.
.Pp
The
.Sy lzjb
compression algorithm is optimized for performance while providing decent data
compression.
.Pp
The
.Sy gzip
compression algorithm uses the same compression as the
.Xr gzip 1
command. You can specify the
.Sy gzip
level by using the value
.Sy gzip- Ns Em N ,
where
.Em N
is an integer from 1
.Pq fastest
to 9
.Pq best compression ratio .
Currently,
.Sy gzip
is equivalent to
.Sy gzip-6
.Po which is also the default for
.Xr gzip 1
.Pc .
.Pp
The
.Sy zle
compression algorithm compresses runs of zeros.
.Pp