summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBrian Behlendorf <[email protected]>2013-10-28 11:57:15 -0700
committerBrian Behlendorf <[email protected]>2013-10-29 13:24:44 -0700
commit7c2448a33ee71be1671c158a167559d1320ff839 (patch)
tree69ab37b5ec722957877eb5a1ad75dfe3af7bea68
parentfc9e0530c9b1be00c122f88d9e4c8c329f2d5d26 (diff)
Improve xattr property documentation
Extend the xattr property section of zfs(8) such that it covers both styles of supported xattr. A short discussion of the benefits and drawbacks of each type is presented to allow users to make an informed choice. Signed-off-by: Massimo Maggi <[email protected]> Signed-off-by: Richard Yao <[email protected]> Signed-off-by: Brian Behlendorf <[email protected]> Issue #170
-rw-r--r--man/man8/zfs.826
1 files changed, 24 insertions, 2 deletions
diff --git a/man/man8/zfs.8 b/man/man8/zfs.8
index 57f0b1ba1..fd612afd3 100644
--- a/man/man8/zfs.8
+++ b/man/man8/zfs.8
@@ -1176,11 +1176,33 @@ Controls whether regular files should be scanned for viruses when a file is open
.ne 2
.mk
.na
-\fB\fBxattr\fR=\fBon\fR | \fBoff\fR\fR
+\fB\fBxattr\fR=\fBon\fR | \fBoff\fR | \fBsa\fR\fR
.ad
.sp .6
.RS 4n
-Controls whether extended attributes are enabled for this file system. The default value is \fBon\fR.
+Controls whether extended attributes are enabled for this file system. Two
+styles of extended attributes are supported either directory based or system
+attribute based.
+.sp
+The default value of \fBon\fR enables directory based extended attributes.
+This style of xattr imposes no practical limit on either the size or number of
+xattrs which may be set on a file. Although under Linux the \fBgetxattr\fR(2)
+and \fBsetxattr\fR(2) system calls limit the maximum xattr size to 64K. This
+is the most compatible style of xattr and it is supported by the majority of
+ZFS implementations.
+.sp
+System attribute based xattrs may be enabled by setting the value to \fBsa\fR.
+The key advantage of this type of xattr is improved performance. Storing
+xattrs as system attributes significantly decreases the amount of disk IO
+required. Up to 64K of xattr data may be stored per file in the space reserved
+for system attributes. If there is not enough space available for an xattr then
+it will be automatically written as a directory based xattr. System attribute
+based xattrs are not accessable on platforms which do not support the
+\fBxattr=sa\fR feature.
+.sp
+The use of system attribute based xattrs is strongly encouraged for users of
+SELinux or Posix ACLs. Both of these features heavily rely of xattrs and
+benefit significantly from the reduced xattr access time.
.RE
.sp