forked from openzfs/zfs
-
Notifications
You must be signed in to change notification settings - Fork 3
/
zfs.8
4049 lines (3699 loc) · 139 KB
/
zfs.8
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
'\" t
.\"
.\" 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 <[email protected]>
.\" Copyright (c) 2011, 2015 by Delphix. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright 2012 Nexenta Systems, Inc. All Rights Reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright 2016 Richard Laager. All rights reserved.
.\"
.TH zfs 8 "May 11, 2016" "ZFS pool 28, filesystem 5" "System Administration Commands"
.SH NAME
zfs \- configures ZFS file systems
.SH SYNOPSIS
.LP
.nf
\fBzfs\fR [\fB-?\fR]
.fi
.LP
.nf
\fBzfs\fR \fBcreate\fR [\fB-p\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fIfilesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBcreate\fR [\fB-ps\fR] [\fB-b\fR \fIblocksize\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fB-V\fR \fIsize\fR \fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBdestroy\fR [\fB-fnpRrv\fR] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBdestroy\fR [\fB-dnpRrv\fR] \fIfilesystem\fR|\fIvolume\fR@\fIsnap\fR[%\fIsnap\fR][,...]
.fi
.LP
.nf
\fBzfs\fR \fBdestroy\fR \fIfilesystem\fR|\fIvolume\fR#\fIbookmark\fR
.fi
.LP
.nf
\fBzfs\fR \fBsnapshot | snap\fR [\fB-r\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ...
\fIfilesystem@snapname\fR|\fIvolume@snapname\fR ...
.fi
.LP
.nf
\fBzfs\fR \fBrollback\fR [\fB-rRf\fR] \fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBclone\fR [\fB-p\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fIsnapshot\fR \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBpromote\fR \fIclone-filesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBrename\fR [\fB-f\fR] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR
\fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBrename\fR [\fB-fp\fR] \fIfilesystem\fR|\fIvolume\fR \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBrename\fR \fB-r\fR \fIsnapshot\fR \fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBlist\fR [\fB-r\fR|\fB-d\fR \fIdepth\fR][\fB-Hp\fR][\fB-o\fR \fIproperty\fR[,\fIproperty\fR]...] [\fB-t\fR \fItype\fR[,\fItype\fR]..]
[\fB-s\fR \fIproperty\fR] ... [\fB-S\fR \fIproperty\fR] ... [\fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR|\fImountpoint\fR] ...
.fi
.LP
.nf
\fBzfs\fR \fBset\fR \fIproperty\fR=\fIvalue\fR... \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR...
.fi
.LP
.nf
\fBzfs\fR \fBget\fR [\fB-r\fR|\fB-d\fR \fIdepth\fR][\fB-Hp\fR][\fB-o\fR \fIfield\fR[,...]] [\fB-t\fR \fItype\fR[,...]]
[\fB-s\fR \fIsource\fR[,...]] "\fIall\fR" | \fIproperty\fR[,...] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR|\fImountpoint\fR ...
.fi
.LP
.nf
\fBzfs\fR \fBinherit\fR [\fB-rS\fR] \fIproperty\fR \fIfilesystem\fR|\fIvolume|snapshot\fR ...
.fi
.LP
.nf
\fBzfs\fR \fBupgrade\fR [\fB-v\fR]
.fi
.LP
.nf
\fBzfs\fR \fBupgrade\fR [\fB-r\fR] [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIfilesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBuserspace\fR [\fB-Hinp\fR] [\fB-o\fR \fIfield\fR[,...]] [\fB-s\fR \fIfield\fR] ...
[\fB-S\fR \fIfield\fR] ... [\fB-t\fR \fItype\fR[,...]] \fIfilesystem\fR|\fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBgroupspace\fR [\fB-Hinp\fR] [\fB-o\fR \fIfield\fR[,...]] [\fB-s\fR \fIfield\fR] ...
[\fB-S\fR \fIfield\fR] ... [\fB-t\fR \fItype\fR[,...]] \fIfilesystem\fR|\fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBmount\fR
.fi
.LP
.nf
\fBzfs\fR \fBmount\fR [\fB-vO\fR] [\fB-o \fIoptions\fR\fR] \fB-a\fR | \fIfilesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBunmount | umount\fR [\fB-f\fR] \fB-a\fR | \fIfilesystem\fR|\fImountpoint\fR
.fi
.LP
.nf
\fBzfs\fR \fBshare\fR [\fBnfs\fR|\fBsmb\fR] \fB-a\fR | \fIfilesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBunshare\fR [\fBnfs\fR|\fBsmb\fR] \fB-a\fR | \fIfilesystem\fR|\fImountpoint\fR
.fi
.LP
.nf
\fBzfs\fR \fBbookmark\fR \fIsnapshot\fR \fIbookmark\fR
.fi
.LP
.nf
\fBzfs\fR \fBsend\fR [\fB-DnPpRveLc\fR] [\fB-\fR[\fBiI\fR] \fIsnapshot\fR] \fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBsend\fR [\fB-Le\fR] [\fB-i \fIsnapshot\fR|\fIbookmark\fR]\fR \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBsend\fR [\fB-Penv\fR] \fB-t\fR \fIreceive_resume_token\fR
.fi
.LP
.nf
\fBzfs\fR \fBreceive\fR [\fB-Fnsuv\fR] [\fB-o origin\fR=\fIsnapshot\fR] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR
.fi
.LP
.nf
\fBzfs\fR \fBreceive\fR [\fB-Fnsuv\fR] [\fB-d\fR|\fB-e\fR] [\fB-o origin\fR=\fIsnapshot\fR] \fIfilesystem\fR
.fi
.LP
.nf
\fBzfs\fR \fBreceive\fR \fB-A\fR \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBallow\fR \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBallow\fR [\fB-ldug\fR] "\fIeveryone\fR"|\fIuser\fR|\fIgroup\fR[,...] \fIperm\fR|\fI@setname\fR[,...]
\fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBallow\fR [\fB-ld\fR] \fB-e\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBallow\fR \fB-c\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBallow\fR \fB-s\fR @\fIsetname\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBunallow\fR [\fB-rldug\fR] "\fIeveryone\fR"|\fIuser\fR|\fIgroup\fR[,...] [\fIperm\fR|@\fIsetname\fR[,... ]]
\fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBunallow\fR [\fB-rld\fR] \fB-e\fR [\fIperm\fR|@\fIsetname\fR[,... ]] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBunallow\fR [\fB-r\fR] \fB-c\fR [\fIperm\fR|@\fIsetname\fR[ ... ]] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBunallow\fR [\fB-r\fR] \fB-s\fR @\fIsetname\fR [\fIperm\fR|@\fIsetname\fR[,... ]] \fIfilesystem\fR|\fIvolume\fR
.fi
.LP
.nf
\fBzfs\fR \fBhold\fR [\fB-r\fR] \fItag\fR \fIsnapshot\fR...
.fi
.LP
.nf
\fBzfs\fR \fBholds\fR [\fB-r\fR] \fIsnapshot\fR...
.fi
.LP
.nf
\fBzfs\fR \fBrelease\fR [\fB-r\fR] \fItag\fR \fIsnapshot\fR...
.fi
.LP
.nf
\fBzfs\fR \fBdiff\fR [\fB-FHt\fR] \fIsnapshot\fR \fIsnapshot|filesystem\fR
.fi
.LP
.nf
\fB\fBzfs key -l\fR \fIfilesystem\fR | \fIvolume\fR\fR
.fi
.LP
.nf
\fB\fBzfs key -u\fR \fIfilesystem\fR | \fIvolume\fR\fR
.fi
.LP
.nf
\fB\fBzfs key -c\fR [\fB-o\fR \fIkeysource\fR=\fIkeysource\fR] [\fB-o\fR \fIpbkdf2iters\fR=\fIiterations\fR] \fIfilesystem\fR | \fIvolume\fR\fR
.SH DESCRIPTION
.LP
The \fBzfs\fR command configures \fBZFS\fR datasets within a \fBZFS\fR storage pool, as described in \fBzpool\fR(8). A dataset is identified by a unique path within the \fBZFS\fR namespace. For example:
.sp
.in +2
.nf
pool/{filesystem,volume,snapshot}
.fi
.in -2
.sp
.sp
.LP
where the maximum length of a dataset name is \fBMAXNAMELEN\fR (256 bytes).
.sp
.LP
A dataset can be one of the following:
.sp
.ne 2
.na
\fB\fIfilesystem\fR\fR
.ad
.sp .6
.RS 4n
A \fBZFS\fR dataset of type \fBfilesystem\fR can be mounted within the standard system namespace and behaves like other file systems. While \fBZFS\fR file systems are designed to be \fBPOSIX\fR compliant, known issues exist that prevent compliance in some cases. Applications that depend on standards conformance might fail due to nonstandard behavior when checking file system free space.
.RE
.sp
.ne 2
.na
\fB\fIvolume\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE
.sp
.ne 2
.na
\fB\fIsnapshot\fR\fR
.ad
.sp .6
.RS 4n
A read-only version of a file system or volume at a given point in time. It is specified as \fIfilesystem@name\fR or \fIvolume@name\fR.
.RE
.sp
.ne 2
.na
\fB\fIbookmark\fR\fR
.ad
.sp .6
.RS 4n
Much like a \fIsnapshot\fR, but without the hold on on-disk data. It can be used as the source of a send (but not for a receive).
It is specified as \fIfilesystem#name\fR or \fIvolume#name\fR.
.RE
.SS "ZFS File System Hierarchy"
.LP
A \fBZFS\fR storage pool is a logical collection of devices that provide space for datasets. A storage pool is also the root of the \fBZFS\fR file system hierarchy.
.sp
.LP
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 \fBzpool\fR(8) command.
.sp
.LP
See \fBzpool\fR(8) for more information on creating and administering pools.
.SS "Snapshots"
.LP
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.
.sp
.LP
Snapshots can have arbitrary names. Snapshots of volumes can be cloned or rolled back. Visibility is determined by the \fBsnapdev\fR property of the parent volume.
.sp
.LP
File system snapshots can be accessed under the \fB\&.zfs/snapshot\fR 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 \fB\&.zfs\fR directory can be controlled by the \fBsnapdir\fR property.
.SS "Bookmarks"
.LP
A bookmark is like a snapshot, a read-only copy of a file system or volume. Bookmarks can be created extremely quickly, compared to snapshots, and they consume no additional space within the pool. Bookmarks can also have arbitrary names, much like snapshots.
.sp
.LP
Unlike snapshots, bookmarks can not be accessed through the filesystem in any way. From a storage standpoint a bookmark just provides a way to reference when a snapshot was created as a distinct object. Bookmarks are initially tied to a snapshot, not the filesystem/volume, and they will survive if the snapshot itself is destroyed. Since they are very light weight there's little incentive to destroy them.
.SS "Clones"
.LP
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.
.sp
.LP
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 \fBorigin\fR property exposes this dependency, and the \fBdestroy\fR command lists any such dependencies, if they exist.
.sp
.LP
The clone parent-child dependency relationship can be reversed by using the \fBpromote\fR subcommand. This causes the "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"
.LP
Creating a \fBZFS\fR file system is a simple operation, so the number of file systems per system is likely to be numerous. To cope with this, \fBZFS\fR automatically manages mounting and unmounting file systems without the need to edit the \fB/etc/fstab\fR file. All automatically managed file systems are mounted by \fBZFS\fR at boot time.
.sp
.LP
By default, file systems are mounted under \fB/\fIpath\fR\fR, where \fIpath\fR is the name of the file system in the \fBZFS\fR namespace. Directories are created and destroyed as needed.
.sp
.LP
A file system can also have a mount point set in the \fBmountpoint\fR property. This directory is created as needed, and \fBZFS\fR automatically mounts the file system when the \fBzfs mount -a\fR command is invoked (without editing \fB/etc/fstab\fR). The \fBmountpoint\fR property can be inherited, so if \fBpool/home\fR has a mount point of \fB/export/stuff\fR, then \fBpool/home/user\fR automatically inherits a mount point of \fB/export/stuff/user\fR.
.sp
.LP
A file system \fBmountpoint\fR property of \fBnone\fR prevents the file system from being mounted.
.sp
.LP
If needed, \fBZFS\fR file systems can also be managed with traditional tools (\fBmount\fR, \fBumount\fR, \fB/etc/fstab\fR). If a file system's mount point is set to \fBlegacy\fR, \fBZFS\fR makes no attempt to manage the file system, and the administrator is responsible for mounting and unmounting the file system.
.SS "Deduplication"
.LP
Deduplication is the process for removing redundant data at the block-level, reducing the total amount of data stored. If a file system has the \fBdedup\fR property enabled, duplicate data blocks are removed synchronously. The result is that only unique data is stored and common components are shared among files.
.sp
\fBWARNING: DO NOT ENABLE DEDUPLICATION UNLESS YOU NEED IT AND KNOW EXACTLY WHAT YOU ARE DOING!\fR
.sp
Deduplicating data is a very resource-intensive operation. It is generally recommended that you have \fIat least\fR 1.25 GiB of RAM per 1 TiB of storage when you enable deduplication. But calculating the exact requirements is a somewhat complicated affair.
.sp
Enabling deduplication on an improperly-designed system will result in extreme performance issues (extremely slow filesystem and snapshot deletions etc.) and can potentially lead to data loss (i.e. unimportable pool due to memory exhaustion) if your system is not built for this purpose. Deduplication affects the processing power (CPU), disks (and the controller) as well as primary (real) memory.
.sp
Before creating a pool with deduplication enabled, ensure that you have planned your hardware requirements appropriately and implemented appropriate recovery practices, such as regular backups.
.sp
Unless necessary, deduplication should NOT be enabled on a system. Instead, consider using \fIcompression=lz4\fR, as a less resource-intensive alternative.
.SS "Properties"
.sp
.LP
Properties are divided into two types: native properties and user-defined (or "user") properties. Native properties either export internal statistics or control \fBZFS\fR behavior. User properties have no effect on \fBZFS\fR behavior, but you can use them to annotate datasets and snapshots in a way that is meaningful in your environment.
.sp
.LP
Properties are generally inherited from the parent unless overridden by the child. See the documentation below for exceptions.
.sp
.LP
.SS "Native Properties"
Native properties apply to all dataset types unless otherwise noted. However, native properties cannot be edited on snapshots.
.sp
.LP
The values of numeric native properties can be specified using human-readable abbreviations (\fBK\fR, \fBM\fR, \fBG\fR, \fBT\fR, \fBP\fR, \fBE\fR, and \fBZ\fR). These abbreviations can optionally use the IEC binary prefixes (e.g. GiB) or SI decimal prefixes (e.g. GB), though the SI prefixes are treated as binary prefixes. Abbreviations are case-insensitive. The following are all valid (and equal) specifications:
.sp
.in +2
.nf
1536M, 1.5g, 1.50GB, 1.5GiB
.fi
.in -2
.sp
.sp
.LP
The values of non-numeric native properties are case-sensitive and must be lowercase, except for \fBmountpoint\fR, \fBsharenfs\fR, and \fBsharesmb\fR.
.sp
.LP
The following native properties consist of read-only statistics about the dataset. These properties can be neither set, nor inherited.
.sp
.ne 2
.na
\fB\fBavailable\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
This property can also be referred to by its shortened column name, \fBavail\fR.
.RE
.sp
.ne 2
.na
\fB\fBcompressratio\fR\fR
.ad
.sp .6
.RS 4n
For non-snapshots, the compression ratio achieved for the \fBused\fR space of this dataset, expressed as a multiplier. The \fBused\fR property includes descendant datasets, and, for clones, does not include the space shared with the origin snapshot. For snapshots, the \fBcompressratio\fR is the same as the \fBrefcompressratio\fR property. The \fBcompression\fR property controls whether compression is enabled on a dataset.
.RE
.sp
.ne 2
.na
\fB\fBcreation\fR\fR
.ad
.sp .6
.RS 4n
The time this dataset was created.
.RE
.sp
.ne 2
.na
\fB\fBclones\fR\fR
.ad
.sp .6
.RS 4n
For snapshots, this property is a comma-separated list of filesystems or
volumes which are clones of this snapshot. The clones' \fBorigin\fR property
is this snapshot. If the \fBclones\fR property is not empty, then this
snapshot can not be destroyed (even with the \fB-r\fR or \fB-f\fR options). The
roles of origin and clone can be swapped by promoting the clone with the
\fBzfs promote\fR command.
.RE
.sp
.ne 2
.na
\fB\fBdefer_destroy\fR\fR
.ad
.sp .6
.RS 4n
This property is \fBon\fR if the snapshot has been marked for deferred destruction by using the \fBzfs destroy\fR \fB-d\fR command. Otherwise, the property is \fBoff\fR.
.RE
.sp
.ne 2
.na
\fB\fBfilesystem_count\fR
.ad
.sp .6
.RS 4n
The total number of filesystems and volumes that exist under this location in the
dataset tree. This value is only available when a \fBfilesystem_limit\fR has
been set somewhere in the tree under which the dataset resides.
.RE
.sp
.ne 2
.mk
.na
\fB\fBkeystatus\fR
.ad
.sp .6
.RS 4n
Indicates if an encryption key is currently loaded into ZFS. The possible values are \fBnone\fR, \fBavailable\fR, and \fBunavaliable\fR. See \fBzfs key -l\fR and \fBzfs key -u\fR.
.RE
.sp
.ne 2
.na
\fB\fBlogicalreferenced\fR\fR
.ad
.sp .6
.RS 4n
The amount of space that is "logically" accessible by this dataset. See
the \fBreferenced\fR property. The logical space ignores the effect of
the \fBcompression\fR and \fBcopies\fR properties, giving a quantity
closer to the amount of data that applications see. However, it does
include space consumed by metadata.
.sp
This property can also be referred to by its shortened column name,
\fBlrefer\fR.
.RE
.sp
.ne 2
.na
\fB\fBlogicalused\fR\fR
.ad
.sp .6
.RS 4n
The amount of space that is "logically" consumed by this dataset and all
its descendents. See the \fBused\fR property. The logical space
ignores the effect of the \fBcompression\fR and \fBcopies\fR properties,
giving a quantity closer to the amount of data that applications see.
However, it does include space consumed by metadata.
.sp
This property can also be referred to by its shortened column name,
\fBlused\fR.
.RE
.sp
.ne 2
.na
\fB\fBmounted\fR\fR
.ad
.sp .6
.RS 4n
For file systems, indicates whether the file system is currently mounted. This property can be either \fByes\fR or \fBno\fR.
.RE
.sp
.ne 2
.na
\fB\fBorigin\fR\fR
.ad
.sp .6
.RS 4n
For cloned file systems or volumes, the snapshot from which the clone was created. The origin cannot be destroyed (even with the \fB-r\fR or \fB-f\fR options) so long as a clone exists. See also the \fBclones\fR property.
.RE
.sp
.ne 2
.na
\fB\fBreceive_resume_token\fR\fR
.ad
.sp .6
.RS 4n
For filesystems or volumes which have saved partially-completed state from \fBzfs receive -s\fR , this opaque token can be provided to \fBzfs send -t\fR to resume and complete the \fBzfs receive\fR.
.RE
.sp
.ne 2
.mk
.na
\fB\fBreferenced\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
This property can also be referred to by its shortened column name, \fBrefer\fR.
.RE
.sp
.ne 2
.na
\fB\fBrefcompressratio\fR\fR
.ad
.sp .6
.RS 4n
The compression ratio achieved for the \fBreferenced\fR space of this
dataset, expressed as a multiplier. See also the \fBcompressratio\fR
property.
.RE
.sp
.ne 2
.na
\fB\fBsnapshot_count\fR
.ad
.sp .6
.RS 4n
The total number of snapshots that exist under this location in the dataset tree.
This value is only available when a \fBsnapshot_limit\fR has been set somewhere
in the tree under which the dataset resides.
.RE
.sp
.ne 2
.na
\fB\fBtype\fR\fR
.ad
.sp .6
.RS 4n
The type of dataset: \fBfilesystem\fR, \fBvolume\fR, or \fBsnapshot\fR.
.RE
.sp
.ne 2
.na
\fB\fBused\fR\fR
.ad
.sp .6
.RS 4n
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.
.sp
When snapshots (see the "Snapshots" section) 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 (and used by) other snapshots.
.sp
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 \fBfsync\fR(2) or \fBO_SYNC\fR (see \fBopen\fR(2)) does not necessarily guarantee that the space usage information is updated immediately.
.RE
.sp
.ne 2
.na
\fB\fBusedby*\fR\fR
.ad
.sp .6
.RS 4n
The \fBusedby*\fR properties decompose the \fBused\fR properties into the various reasons that space is used. Specifically, \fBused\fR = \fBusedbychildren\fR + \fBusedbydataset\fR + \fBusedbyrefreservation\fR + \fBusedbysnapshots\fR. These properties are only available for datasets created on \fBzpool\fR version 13 or higher pools.
.RE
.sp
.ne 2
.na
\fB\fBusedbychildren\fR\fR
.ad
.sp .6
.RS 4n
The amount of space used by children of this dataset, which would be freed if all the dataset's children were destroyed.
.RE
.sp
.ne 2
.na
\fB\fBusedbydataset\fR\fR
.ad
.sp .6
.RS 4n
The amount of space used by this dataset itself, which would be freed if the dataset were destroyed (after first removing any \fBrefreservation\fR and destroying any necessary snapshots or descendents).
.RE
.sp
.ne 2
.na
\fB\fBusedbyrefreservation\fR\fR
.ad
.sp .6
.RS 4n
The amount of space used by a \fBrefreservation\fR set on this dataset, which would be freed if the \fBrefreservation\fR was removed.
.RE
.sp
.ne 2
.na
\fB\fBusedbysnapshots\fR\fR
.ad
.sp .6
.RS 4n
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' \fBused\fR properties because space can be shared by multiple snapshots.
.RE
.sp
.ne 2
.na
\fB\fBuserobjused@\fR\fIuser\fR\fR
.br
\fB\fBuserused@\fR\fIuser\fR\fR
.ad
.sp .6
.RS 4n
The amount of space consumed by the specified user in this dataset. Space is charged to the owner of each file, as displayed by \fBls\fR \fB-l\fR. The amount of space charged is displayed by \fBdu\fR and \fBls\fR \fB-s\fR. See the \fBzfs userspace\fR subcommand for more information.
.sp
Unprivileged users can access only their own space usage. The root user, or a user who has been granted the \fBuserused\fR privilege with \fBzfs allow\fR, can access everyone's usage.
.sp
The \fBuserused@\fR... properties are not displayed by \fBzfs get all\fR. The user's name must be appended after the \fB@\fR symbol, using one of the following forms:
.RS +4
.TP
.ie t \(bu
.el o
\fIPOSIX name\fR (for example, \fBjoe\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIPOSIX numeric ID\fR (for example, \fB789\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fISID name\fR (for example, \fBjoe.smith@mydomain\fR)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fISID numeric ID\fR (for example, \fBS-1-123-456-789\fR)
.RE
.RE
Files created on Linux always have POSIX owners.
.RS 4n
The \fBuserobjused\fR is similar to \fBuserused\fR but instead it counts the number of objects consumed by \fIuser\fR. This feature doesn't count the internal objects used by ZFS, therefore it may under count a few objects comparing with the results of third-party tool such as \fBdfs -i\fR.
When the property \fBxattr=on\fR is set on a fileset, ZFS will create additional objects per-file to store extended attributes. These additional objects are reflected in the \fBuserobjused\fR value and are counted against the user's \fBuserobjquota\fR. When a filesystem is configured to use \fBxattr=sa\fR no additional internal objects are required.
.RE
.sp
.ne 2
.na
\fB\fBuserrefs\fR\fR
.ad
.sp .6
.RS 4n
This property is set to the number of user holds on this snapshot. User holds are set by using the \fBzfs hold\fR command.
.RE
.sp
.ne 2
.na
\fB\fBgroupused@\fR\fIgroup\fR\fR
.br
\fB\fBgroupobjused@\fR\fIgroup\fR\fR
.ad
.sp .6
.RS 4n
The amount of space consumed by the specified group in this dataset. Space is charged to the group of each file, as displayed by \fBls\fR \fB-l\fR. See the \fBuserused@\fR\fIuser\fR property for more information.
.sp
Unprivileged users can only access their own groups' space usage. The root user, or a user who has been granted the \fBgroupused\fR privilege with \fBzfs allow\fR, can access all groups' usage.
.RE
.RS 4n
The \fBgroupobjused\fR is similar to \fBgroupused\fR but instead it counts the number of objects consumed by \fIgroup\fR.
When the property \fBxattr=on\fR is set on a fileset, ZFS will create additional objects per-file to store extended attributes. These additional objects are reflected in the \fBgroupobjused\fR value and are counted against the group's \fBgroupobjquota.\fR. When a filesystem is configured to use \fBxattr=sa\fR no additional internal objects are required.
.RE
.sp
.ne 2
.na
\fB\fBvolblocksize\fR=\fIblocksize\fR\fR
.ad
.sp .6
.RS 4n
This property, which is only valid on volumes, specifies the block size of the volume. Any power of two from 512B to 128KiB is valid. The default is 8KiB.
.sp
This property cannot be changed after the volume is created.
.sp
This property can also be referred to by its shortened column name, \fBvolblock\fR.
.RE
.sp
.ne 2
.na
\fB\fBwritten\fR\fR
.ad
.sp .6
.RS 4n
The amount of \fBreferenced\fR space written to this dataset since the
previous snapshot.
.RE
.sp
.ne 2
.na
\fB\fBwritten@\fR\fIsnapshot\fR\fR
.ad
.sp .6
.RS 4n
The amount of \fBreferenced\fR 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.
.sp
The \fIsnapshot\fR may be specified as a short snapshot name (just the part
after the \fB@\fR), in which case it will be interpreted as a snapshot in
the same filesystem as this dataset.
The \fIsnapshot\fR be a full snapshot name (\fIfilesystem\fR@\fIsnapshot\fR),
which for clones may be a snapshot in the origin's filesystem (or the origin
of the origin's filesystem, etc).
.RE
.sp
.LP
The following native properties can be used to change the behavior of a \fBZFS\fR dataset.
.sp
.ne 2
.na
\fB\fBaclinherit\fR=\fBrestricted\fR | \fBdiscard\fR | \fBnoallow\fR | \fBpassthrough\fR | \fBpassthrough-x\fR\fR
.ad
.sp .6
.RS 4n
Controls how \fBACL\fR entries are inherited when files and directories are created. A file system with an \fBaclinherit\fR property of \fBdiscard\fR does not inherit any \fBACL\fR entries. A file system with an \fBaclinherit\fR property value of \fBnoallow\fR only inherits inheritable \fBACL\fR entries that specify "deny" permissions. The property value \fBrestricted\fR (the default) removes the \fBwrite_acl\fR and \fBwrite_owner\fR permissions when the \fBACL\fR entry is inherited. A file system with an \fBaclinherit\fR property value of \fBpassthrough\fR inherits all inheritable \fBACL\fR entries without any modifications made to the \fBACL\fR entries when they are inherited. A file system with an \fBaclinherit\fR property value of \fBpassthrough-x\fR has the same meaning as \fBpassthrough\fR, except that the \fBowner@\fR, \fBgroup@\fR, and \fBeveryone@\fR \fBACE\fRs inherit the execute permission only if the file creation mode also requests the execute bit.
.sp
When the property value is set to \fBpassthrough\fR, files are created with a mode determined by the inheritable \fBACE\fRs. If no inheritable \fBACE\fRs exist that affect the mode, then the mode is set in accordance to the requested mode from the application.
.sp
The \fBaclinherit\fR property does not apply to Posix ACLs.
.RE
.sp
.ne 2
.na
\fB\fBacltype\fR=\fBoff\fR | \fBnoacl\fR | \fBposixacl\fR \fR
.ad
.sp .6
.RS 4n
Controls whether ACLs are enabled and if so what type of ACL to use. When
a file system has the \fBacltype\fR property set to \fBoff\fR (the default)
then ACLs are disabled. Setting the \fBacltype\fR property to \fBposixacl\fR
indicates Posix ACLs should be used. Posix ACLs are specific to Linux and
are not functional on other platforms. Posix ACLs are stored as an xattr and
therefore will not overwrite any existing ZFS/NFSv4 ACLs which may be set.
Currently only \fBposixacls\fR are supported on Linux.
.sp
To obtain the best performance when setting \fBposixacl\fR users are strongly
encouraged to set the \fBxattr=sa\fR property. This will result in the
Posix ACL being stored more efficiently on disk. But as a consequence of this
all new xattrs will only be accessible from ZFS implementations which support
the \fBxattr=sa\fR property. See the \fBxattr\fR property for more details.
.sp
The value \fBnoacl\fR is an alias for \fBoff\fR.
.RE
.sp
.ne 2
.na
\fB\fBatime\fR=\fBon\fR | \fBoff\fR\fR
.ad
.sp .6
.RS 4n
Controls whether the access time for files is updated when they are read. Setting this property to \fBoff\fR 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 \fBon\fR. See also \fBrelatime\fR below.
.sp
The values \fBon\fR and \fBoff\fR are equivalent to the \fBatime\fR and \fBnoatime\fR mount options.
.RE
.sp
.ne 2
.na
\fB\fBcanmount\fR=\fBon\fR | \fBoff\fR | \fBnoauto\fR\fR
.ad
.sp .6
.RS 4n
If this property is set to \fBoff\fR, the file system cannot be mounted, and is ignored by \fBzfs mount -a\fR. Setting this property to \fBoff\fR is similar to setting the \fBmountpoint\fR property to \fBnone\fR, except that the dataset still has a normal \fBmountpoint\fR property, which can be inherited. Setting this property to \fBoff\fR allows datasets to be used solely as a mechanism to inherit properties. One example of setting \fBcanmount=\fR\fBoff\fR is to have two datasets with the same \fBmountpoint\fR, so that the children of both datasets appear in the same directory, but might have different inherited characteristics.
.sp
When the \fBnoauto\fR option is set, 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 \fBzfs mount -a\fR command or unmounted by the \fBzfs unmount -a\fR command.
.sp
This property is not inherited. Every dataset defaults to \fBon\fR independently.
.sp
The values \fBon\fR and \fBnoauto\fR are equivalent to the \fBauto\fR and \fBnoauto\fR mount options.
.RE
.sp
.ne 2
.na
\fB\fBchecksum\fR=\fBon\fR | \fBoff\fR | \fBfletcher2\fR | \fBfletcher4\fR | \fBsha256\fR | \fBnoparity\fR | \fBsha512\fR | \fBskein\fR | \fBedonr\fR\fR
.ad
.sp .6
.RS 4n
Controls the checksum used to verify data integrity. The default value is
\fBon\fR, which automatically selects an appropriate algorithm (currently,
\fBfletcher4\fR, but this may change in future releases). The value \fBoff\fR
disables integrity checking on user data. The value \fBnoparity\fR 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 \fBNOT\fR a
recommended practice.
.sp
The \fBsha512\fR, \fBskein\fR, and \fBedonr\fR checksum algorithms require
enabling the appropriate features on the pool. Please see zpool-features for
more information on these algorithms.
Changing this property affects only newly-written data.
.RE
.sp
.ne 2
.na
\fB\fBcompression\fR=\fBoff\fR | \fBon\fR | \fBlzjb\fR | \fBlz4\fR |
\fBgzip\fR | \fBgzip-\fR\fIN\fR | \fBzle\fR\fR
.ad
.sp .6
.RS 4n
Controls the compression algorithm used for this dataset.
.sp
Setting compression to \fBon\fR 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, \fBon\fR 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
algorithm is either \fBlzjb\fR or, if the \fBlz4_compress\fR feature is
enabled, \fBlz4\fR.
.sp
The \fBlzjb\fR compression algorithm is optimized for performance while
providing decent data compression.
.sp
The \fBlz4\fR compression algorithm is a high-performance replacement
for the \fBlzjb\fR algorithm. It features significantly faster
compression and decompression, as well as a moderately higher
compression ratio than \fBlzjb\fR, but can only be used on pools with
the \fBlz4_compress\fR feature set to \fIenabled\fR. See
\fBzpool-features\fR(5) for details on ZFS feature flags and the
\fBlz4_compress\fR feature.
.sp
The \fBgzip\fR compression algorithm uses the same compression as
the \fBgzip\fR(1) command. You can specify the \fBgzip\fR level by using the
value \fBgzip-\fR\fIN\fR where \fIN\fR is an integer from 1 (fastest) to 9
(best compression ratio). Currently, \fBgzip\fR is equivalent to \fBgzip-6\fR
(which is also the default for \fBgzip\fR(1)). The \fBzle\fR compression
algorithm compresses runs of zeros.
.sp
This property can also be referred to by its shortened column name
\fBcompress\fR. Changing this property affects only newly-written data.
.RE
.sp
.ne 2
.na
\fB\fBcopies\fR=\fB1\fR | \fB2\fR | \fB3\fR\fR
.ad
.sp .6
.RS 4n
Controls the number of copies of data stored for this dataset. These copies are in addition to any redundancy provided by the pool, for example, mirroring or RAID-Z. The copies are stored on different disks, if possible. The space used by multiple copies is charged to the associated file and dataset, changing the \fBused\fR property and counting against quotas and reservations.
.sp
Changing this property only affects newly-written data.
.sp
Remember that \fBZFS\fR will not import a pool with a missing top-level vdev. Do NOT create, for example, a two-disk, striped pool and set \fBcopies=\fR\fI2\fR on some datasets thinking you have setup redundancy for them. When one disk dies, you will not be able to import the pool and will have lost all of your data.
.RE
.sp
.ne 2
.na
\fB\fBdedup\fR=\fBoff\fR | \fBon\fR | \fBverify\fR | \fBsha256\fR[,\fBverify\fR]\fR
.ad
.sp .6
.RS 4n
Controls whether deduplication is in effect for a dataset. The default value is \fBoff\fR. The default checksum used for deduplication is \fBsha256\fR (subject to change). When \fBdedup\fR is enabled, the \fBdedup\fR checksum algorithm overrides the \fBchecksum\fR property. Setting the value to \fBverify\fR is equivalent to specifying \fBsha256,verify\fR.
.sp
If the property is set to \fBverify\fR, then, whenever two blocks have the same signature, ZFS will do a byte-for-byte comparison with the existing block to ensure that the contents are identical.
.sp
Unless necessary, deduplication should NOT be enabled on a system. See \fBDeduplication\fR above.
.RE
.sp
.ne 2
.na
\fB\fBdevices\fR=\fBon\fR | \fBoff\fR\fR
.ad
.sp .6
.RS 4n
Controls whether device nodes can be opened on this file system. The default value is \fBon\fR.
.sp
The values \fBon\fR and \fBoff\fR are equivalent to the \fBdev\fR and \fBnodev\fR mount options.
.RE
.sp
.ne 2
.na
\fB\fBdnodesize\fR=\fBlegacy\fR | \fBauto\fR | \fB1k\fR | \fB2k\fR | \fB4k\fR | \fB8k\fR | \fB16k\fR\fR
.ad
.sp .6
.RS 4n
Specifies a compatibility mode or literal value for the size of dnodes
in the file system. The default value is \fBlegacy\fR. Setting this
property to a value other than \fBlegacy\fR requires the
\fBlarge_dnode\fR pool feature to be enabled.
.sp
Consider setting \fBdnodesize\fR to \fBauto\fR if the dataset uses the
\fBxattr=sa\fR property setting and the workload makes heavy use of
extended attributes. This may be applicable to SELinux-enabled systems,
Lustre servers, and Samba servers, for example. Literal values are
supported for cases where the optimal size is known in advance and for
performance testing.
.sp