2004 lines
60 KiB
Groff
2004 lines
60 KiB
Groff
.\"
|
|
.\" 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, 2019 by Delphix. All rights reserved.
|
|
.\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
|
|
.\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
|
|
.\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org>
|
|
.\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org>
|
|
.\" 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 (c) 2016 Nexenta Systems, Inc. All Rights Reserved.
|
|
.\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org>
|
|
.\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved.
|
|
.\" Copyright 2019 Richard Laager. All rights reserved.
|
|
.\" Copyright 2018 Nexenta Systems, Inc.
|
|
.\" Copyright 2019 Joyent, Inc.
|
|
.\" Copyright (c) 2019, Kjeld Schouten-Lebbing
|
|
.\"
|
|
.Dd September 1, 2020
|
|
.Dt ZFSPROPS 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm zfsprops
|
|
.Nd Native properties and user-defined of ZFS datasets.
|
|
.Sh DESCRIPTION
|
|
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.
|
|
.Ss Native Properties
|
|
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 createtxg
|
|
The transaction group (txg) in which the dataset was created. Bookmarks have
|
|
the same
|
|
.Sy createtxg
|
|
as the snapshot they are initially tied to. This property is suitable for
|
|
ordering a list of snapshots, e.g. for incremental send and receive.
|
|
.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 .
|
|
The roles of origin and clone can be swapped by promoting the clone with the
|
|
.Nm zfs Cm promote
|
|
command.
|
|
.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 encryptionroot
|
|
For encrypted datasets, indicates where the dataset is currently inheriting its
|
|
encryption key from. Loading or unloading a key for the
|
|
.Sy encryptionroot
|
|
will implicitly load / unload the key for any inheriting datasets (see
|
|
.Nm zfs Cm load-key
|
|
and
|
|
.Nm zfs Cm unload-key
|
|
for details).
|
|
Clones will always share an
|
|
encryption key with their origin. See the
|
|
.Em Encryption
|
|
section of
|
|
.Xr zfs-load-key 8
|
|
for details.
|
|
.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 keystatus
|
|
Indicates if an encryption key is currently loaded into ZFS. The possible
|
|
values are
|
|
.Sy none ,
|
|
.Sy available ,
|
|
and
|
|
.Sy unavailable .
|
|
See
|
|
.Nm zfs Cm load-key
|
|
and
|
|
.Nm zfs Cm unload-key .
|
|
.It Sy guid
|
|
The 64 bit GUID of this dataset or bookmark which does not change over its
|
|
entire lifetime. When a snapshot is sent to another pool, the received
|
|
snapshot has the same GUID. Thus, the
|
|
.Sy guid
|
|
is suitable to identify a snapshot across pools.
|
|
.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 objsetid
|
|
A unique identifier for this dataset within the pool. Unlike the dataset's
|
|
.Sy guid
|
|
, the
|
|
.Sy objsetid
|
|
of a dataset is not transferred to other pools when the snapshot is copied
|
|
with a send/receive operation.
|
|
The
|
|
.Sy objsetid
|
|
can be reused (for a new dataset) after the dataset is deleted.
|
|
.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 redact_snaps
|
|
For bookmarks, this is the list of snapshot guids the bookmark contains a redaction
|
|
list for.
|
|
For snapshots, this is the list of snapshot guids the snapshot is redacted with
|
|
respect to.
|
|
.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 ,
|
|
.Sy snapshot ,
|
|
or
|
|
.Sy bookmark .
|
|
.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 is freed if this dataset is recursively destroyed, is the
|
|
greater of its space used and its reservation.
|
|
.Pp
|
|
The used space of a snapshot
|
|
.Po see the
|
|
.Em Snapshots
|
|
section of
|
|
.Xr zfsconcepts 8
|
|
.Pc
|
|
is space that is referenced exclusively by this snapshot.
|
|
If this snapshot is destroyed, the amount of
|
|
.Sy used
|
|
space will be freed.
|
|
Space that is shared by multiple snapshots isn't accounted for in this metric.
|
|
When a snapshot is destroyed, space that was previously shared with this
|
|
snapshot can become unique to snapshots adjacent to it, thus changing the used
|
|
space of those snapshots.
|
|
The used space of the latest snapshot can also be affected by changes in the
|
|
file system.
|
|
Note that the
|
|
.Sy used
|
|
space of a snapshot is a subset of the
|
|
.Sy written
|
|
space of the snapshot.
|
|
.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 2
|
|
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
|
|
.Pp
|
|
Files created on Linux always have POSIX owners.
|
|
.It Sy userobjused Ns @ Ns Em user
|
|
The
|
|
.Sy userobjused
|
|
property is similar to
|
|
.Sy userused
|
|
but instead it counts the number of objects consumed by a user. This property
|
|
counts all objects allocated on behalf of the user, it may differ from the
|
|
results of system tools such as
|
|
.Nm df Fl i .
|
|
.Pp
|
|
When the property
|
|
.Sy xattr=on
|
|
is set on a file system additional objects will be created per-file to store
|
|
extended attributes. These additional objects are reflected in the
|
|
.Sy userobjused
|
|
value and are counted against the user's
|
|
.Sy userobjquota .
|
|
When a file system is configured to use
|
|
.Sy xattr=sa
|
|
no additional internal objects are normally required.
|
|
.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 groupobjused Ns @ Ns Em group
|
|
The number of objects consumed by the specified group in this dataset.
|
|
Multiple objects may be charged to the group for each file when extended
|
|
attributes are in use. See the
|
|
.Sy userobjused 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 groupobjused
|
|
privilege with
|
|
.Nm zfs Cm allow ,
|
|
can access all groups' usage.
|
|
.It Sy projectused Ns @ Ns Em project
|
|
The amount of space consumed by the specified project in this dataset. Project
|
|
is identified via the project identifier (ID) that is object-based numeral
|
|
attribute. An object can inherit the project ID from its parent object (if the
|
|
parent has the flag of inherit project ID that can be set and changed via
|
|
.Nm chattr Fl /+P
|
|
or
|
|
.Nm zfs project Fl s )
|
|
when being created. The privileged user can set and change object's project
|
|
ID via
|
|
.Nm chattr Fl p
|
|
or
|
|
.Nm zfs project Fl s
|
|
anytime. Space is charged to the project of each file, as displayed by
|
|
.Nm lsattr Fl p
|
|
or
|
|
.Nm zfs project .
|
|
See the
|
|
.Sy userused Ns @ Ns Em user
|
|
property for more information.
|
|
.Pp
|
|
The root user, or a user who has been granted the
|
|
.Sy projectused
|
|
privilege with
|
|
.Nm zfs allow ,
|
|
can access all projects' usage.
|
|
.It Sy projectobjused Ns @ Ns Em project
|
|
The
|
|
.Sy projectobjused
|
|
is similar to
|
|
.Sy projectused
|
|
but instead it counts the number of objects consumed by project. When the
|
|
property
|
|
.Sy xattr=on
|
|
is set on a fileset, ZFS will create additional objects per-file to store
|
|
extended attributes. These additional objects are reflected in the
|
|
.Sy projectobjused
|
|
value and are counted against the project's
|
|
.Sy projectobjquota .
|
|
When a filesystem is configured to use
|
|
.Sy xattr=sa
|
|
no additional internal objects are required. See the
|
|
.Sy userobjused Ns @ Ns Em user
|
|
property for more information.
|
|
.Pp
|
|
The root user, or a user who has been granted the
|
|
.Sy projectobjused
|
|
privilege with
|
|
.Nm zfs allow ,
|
|
can access all projects' objects usage.
|
|
.It Sy volblocksize
|
|
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 space
|
|
.Sy referenced
|
|
by this dataset, that was written since the previous snapshot
|
|
.Pq i.e. that is not referenced by 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.
|
|
.Pp
|
|
The
|
|
.Sy aclinherit
|
|
property does not apply to POSIX ACLs.
|
|
.It Xo
|
|
.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
|
|
.Sy passthrough Ns | Ns Sy restricted Ns
|
|
.Xc
|
|
Controls how an ACL is modified during chmod(2) and how inherited ACEs
|
|
are modified by the file creation mode.
|
|
.Bl -tag -width "passthrough"
|
|
.It Sy discard
|
|
default, deletes all
|
|
.Sy ACEs
|
|
except for those representing
|
|
the mode of the file or directory requested by
|
|
.Xr chmod 2 .
|
|
.It Sy groupmask
|
|
reduces permissions granted in all
|
|
.Sy ALLOW
|
|
entries found in the
|
|
.Sy ACL
|
|
such that they are no greater than the group permissions specified by
|
|
.Xr chmod 2 .
|
|
.It Sy passthrough
|
|
indicates that no changes are made to the
|
|
.Tn ACL
|
|
other than creating or updating the necessary
|
|
.Tn ACL
|
|
entries to represent the new mode of the file or directory.
|
|
.It Sy restricted
|
|
will cause the
|
|
.Xr chmod 2
|
|
operation to return an error when used on any file or directory which has
|
|
a non-trivial
|
|
.Tn ACL
|
|
whose entries can not be represented by a mode.
|
|
.Xr chmod 2
|
|
is required to change the set user ID, set group ID, or sticky bits on a file
|
|
or directory, as they do not have equivalent
|
|
.Tn ACL
|
|
entries.
|
|
In order to use
|
|
.Xr chmod 2
|
|
on a file or directory with a non-trivial
|
|
.Tn ACL
|
|
when
|
|
.Sy aclmode
|
|
is set to
|
|
.Sy restricted ,
|
|
you must first remove all
|
|
.Tn ACL
|
|
entries which do not represent the current mode.
|
|
.El
|
|
.It Sy acltype Ns = Ns Sy off Ns | Ns Sy nfsv4 Ns | Ns Sy posix
|
|
Controls whether ACLs are enabled and if so what type of ACL to use.
|
|
When this property is set to a type of ACL not supported by the current
|
|
platform, the behavior is the same as if it were set to
|
|
.Sy off .
|
|
.Bl -tag -width "posixacl"
|
|
.It Sy off
|
|
default on Linux, when a file system has the
|
|
.Sy acltype
|
|
property set to off then ACLs are disabled.
|
|
.It Sy noacl
|
|
an alias for
|
|
.Sy off
|
|
.It Sy nfsv4
|
|
default on FreeBSD, indicates that NFSv4-style ZFS ACLs should be used.
|
|
These ACLs can be managed with the
|
|
.Xr getfacl 1
|
|
and
|
|
.Xr setfacl 1
|
|
commands on FreeBSD. The
|
|
.Sy nfsv4
|
|
ZFS ACL type is not yet supported on Linux.
|
|
.It Sy posix
|
|
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 extended
|
|
attribute and therefore will not overwrite any existing NFSv4 ACLs which
|
|
may be set.
|
|
.It Sy posixacl
|
|
an alias for
|
|
.Sy posix
|
|
.El
|
|
.Pp
|
|
To obtain the best performance when setting
|
|
.Sy posix
|
|
users are strongly encouraged to set the
|
|
.Sy xattr=sa
|
|
property. This will result in the POSIX ACL being stored more efficiently on
|
|
disk. But as a consequence, all new extended attributes will only be
|
|
accessible from OpenZFS implementations which support the
|
|
.Sy xattr=sa
|
|
property. See the
|
|
.Sy xattr
|
|
property for more details.
|
|
.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 values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy atime
|
|
and
|
|
.Sy noatime
|
|
mount options. The default value is
|
|
.Sy on .
|
|
See also
|
|
.Sy relatime
|
|
below.
|
|
.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.
|
|
FreeBSD does not support the
|
|
.Sy edonr
|
|
algorithm.
|
|
.Pp
|
|
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 Ns | Ns Sy zstd Ns | Ns
|
|
.Sy zstd- Ns Em N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Em N
|
|
.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 algorithm 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 zstd
|
|
compression algorithm provides both high compression ratios and good
|
|
performance. You can specify the
|
|
.Sy zstd
|
|
level by using the value
|
|
.Sy zstd- Ns Em N ,
|
|
where
|
|
.Em N
|
|
is an integer from 1
|
|
.Pq fastest
|
|
to 19
|
|
.Pq best compression ratio .
|
|
.Sy zstd
|
|
is equivalent to
|
|
.Sy zstd-3 .
|
|
.Pp
|
|
Faster speeds at the cost of the compression ratio can be requested by
|
|
setting a negative
|
|
.Sy zstd
|
|
level. This is done using
|
|
.Sy zstd-fast- Ns Em N ,
|
|
where
|
|
.Em N
|
|
is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative
|
|
.Sy zstd
|
|
level. The lower the level the faster the compression - 1000 provides
|
|
the fastest compression and lowest compression ratio.
|
|
.Sy zstd-fast
|
|
is equivalent to
|
|
.Sy zstd-fast-1 .
|
|
.Pp
|
|
The
|
|
.Sy zle
|
|
compression algorithm compresses runs of zeros.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name
|
|
.Sy compress .
|
|
Changing this property affects only newly-written data.
|
|
.Pp
|
|
When any setting except
|
|
.Sy off
|
|
is selected, compression will explicitly check for blocks consisting of only
|
|
zeroes (the NUL byte). When a zero-filled block is detected, it is stored as
|
|
a hole and not compressed using the indicated compression algorithm.
|
|
.Pp
|
|
Any block being compressed must be no larger than 7/8 of its original size
|
|
after compression, otherwise the compression will not be considered worthwhile
|
|
and the block saved uncompressed. Note that when the logical block is less than
|
|
8 times the disk sector size this effectively reduces the necessary compression
|
|
ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
|
|
or less of their original size.
|
|
.It Xo
|
|
.Sy context Ns = Ns Sy none Ns | Ns
|
|
.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
|
|
.Xc
|
|
This flag sets the SELinux context for all files in the file system under
|
|
a mount point for that file system. See
|
|
.Xr selinux 8
|
|
for more information.
|
|
.It Xo
|
|
.Sy fscontext Ns = Ns Sy none Ns | Ns
|
|
.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
|
|
.Xc
|
|
This flag sets the SELinux context for the file system file system being
|
|
mounted. See
|
|
.Xr selinux 8
|
|
for more information.
|
|
.It Xo
|
|
.Sy defcontext Ns = Ns Sy none Ns | Ns
|
|
.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
|
|
.Xc
|
|
This flag sets the SELinux default context for unlabeled files. See
|
|
.Xr selinux 8
|
|
for more information.
|
|
.It Xo
|
|
.Sy rootcontext Ns = Ns Sy none Ns | Ns
|
|
.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level
|
|
.Xc
|
|
This flag sets the SELinux context for the root inode of the file system. See
|
|
.Xr selinux 8
|
|
for more information.
|
|
.It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
|
|
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
|
|
.Sy used
|
|
property and counting against quotas and reservations.
|
|
.Pp
|
|
Changing this property only affects newly-written data.
|
|
Therefore, set this property at file system creation time by using the
|
|
.Fl o Sy copies Ns = Ns Ar N
|
|
option.
|
|
.Pp
|
|
Remember that ZFS will not import a pool with a missing top-level vdev. Do
|
|
.Sy NOT
|
|
create, for example a two-disk striped pool and set
|
|
.Sy copies=2
|
|
on some datasets thinking you have setup redundancy for them. When a disk
|
|
fails you will not be able to import the pool and will have lost all of your
|
|
data.
|
|
.Pp
|
|
Encrypted datasets may not have
|
|
.Sy copies Ns = Ns Em 3
|
|
since the implementation stores some encryption metadata where the third copy
|
|
would normally be.
|
|
.It Sy devices Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether device nodes can be opened on this file system.
|
|
The default value is
|
|
.Sy on .
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy dev
|
|
and
|
|
.Sy nodev
|
|
mount options.
|
|
.It Xo
|
|
.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns
|
|
.Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns
|
|
.Sy edonr,verify
|
|
.Xc
|
|
Configures deduplication for a dataset. The default value is
|
|
.Sy off .
|
|
The default deduplication checksum is
|
|
.Sy sha256
|
|
(this may change in the future). When
|
|
.Sy dedup
|
|
is enabled, the checksum defined here overrides the
|
|
.Sy checksum
|
|
property. Setting the value to
|
|
.Sy verify
|
|
has the same effect as the setting
|
|
.Sy sha256,verify.
|
|
.Pp
|
|
If set to
|
|
.Sy verify ,
|
|
ZFS will do a byte-to-byte comparison in case of two blocks having the same
|
|
signature to make sure the block contents are identical. Specifying
|
|
.Sy verify
|
|
is mandatory for the
|
|
.Sy edonr
|
|
algorithm.
|
|
.Pp
|
|
Unless necessary, deduplication should NOT be enabled on a system. See the
|
|
.Em Deduplication
|
|
section of
|
|
.Xr zfsconcepts 8 .
|
|
.It Xo
|
|
.Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns
|
|
.Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k
|
|
.Xc
|
|
Specifies a compatibility mode or literal value for the size of dnodes in the
|
|
file system. The default value is
|
|
.Sy legacy .
|
|
Setting this property to a value other than
|
|
.Sy legacy
|
|
requires the large_dnode pool feature to be enabled.
|
|
.Pp
|
|
Consider setting
|
|
.Sy dnodesize
|
|
to
|
|
.Sy auto
|
|
if the dataset uses the
|
|
.Sy xattr=sa
|
|
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.
|
|
.Pp
|
|
Leave
|
|
.Sy dnodesize
|
|
set to
|
|
.Sy legacy
|
|
if you need to receive a send stream of this dataset on a pool that doesn't
|
|
enable the large_dnode feature, or if you need to import this pool on a system
|
|
that doesn't support the large_dnode feature.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name,
|
|
.Sy dnsize .
|
|
.It Xo
|
|
.Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns
|
|
.Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns
|
|
.Sy aes-192-gcm Ns | Ns Sy aes-256-gcm
|
|
.Xc
|
|
Controls the encryption cipher suite (block cipher, key length, and mode) used
|
|
for this dataset. Requires the
|
|
.Sy encryption
|
|
feature to be enabled on the pool.
|
|
Requires a
|
|
.Sy keyformat
|
|
to be set at dataset creation time.
|
|
.Pp
|
|
Selecting
|
|
.Sy encryption Ns = Ns Sy on
|
|
when creating a dataset indicates that the default encryption suite will be
|
|
selected, which is currently
|
|
.Sy aes-256-gcm .
|
|
In order to provide consistent data protection, encryption must be specified at
|
|
dataset creation time and it cannot be changed afterwards.
|
|
.Pp
|
|
For more details and caveats about encryption see the
|
|
.Em Encryption
|
|
section of
|
|
.Xr zfs-load-key 8 .
|
|
.It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase
|
|
Controls what format the user's encryption key will be provided as. This
|
|
property is only set when the dataset is encrypted.
|
|
.Pp
|
|
Raw keys and hex keys must be 32 bytes long (regardless of the chosen
|
|
encryption suite) and must be randomly generated. A raw key can be generated
|
|
with the following command:
|
|
.Bd -literal
|
|
# dd if=/dev/urandom of=/path/to/output/key bs=32 count=1
|
|
.Ed
|
|
.Pp
|
|
Passphrases must be between 8 and 512 bytes long and will be processed through
|
|
PBKDF2 before being used (see the
|
|
.Sy pbkdf2iters
|
|
property). Even though the
|
|
encryption suite cannot be changed after dataset creation, the keyformat can be
|
|
with
|
|
.Nm zfs Cm change-key .
|
|
.It Xo
|
|
.Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path>
|
|
.Xc
|
|
Controls where the user's encryption key will be loaded from by default for
|
|
commands such as
|
|
.Nm zfs Cm load-key
|
|
and
|
|
.Nm zfs Cm mount Cm -l .
|
|
This property is only set for encrypted datasets which are encryption roots. If
|
|
unspecified, the default is
|
|
.Sy prompt.
|
|
.Pp
|
|
Even though the encryption suite cannot be changed after dataset creation, the
|
|
keylocation can be with either
|
|
.Nm zfs Cm set
|
|
or
|
|
.Nm zfs Cm change-key .
|
|
If
|
|
.Sy prompt
|
|
is selected ZFS will ask for the key at the command prompt when it is required
|
|
to access the encrypted data (see
|
|
.Nm zfs Cm load-key
|
|
for details). This setting will also allow the key to be passed in via STDIN,
|
|
but users should be careful not to place keys which should be kept secret on
|
|
the command line. If a file URI is selected, the key will be loaded from the
|
|
specified absolute file path.
|
|
.It Sy pbkdf2iters Ns = Ns Ar iterations
|
|
Controls the number of PBKDF2 iterations that a
|
|
.Sy passphrase
|
|
encryption key should be run through when processing it into an encryption key.
|
|
This property is only defined when encryption is enabled and a keyformat of
|
|
.Sy passphrase
|
|
is selected. The goal of PBKDF2 is to significantly increase the
|
|
computational difficulty needed to brute force a user's passphrase. This is
|
|
accomplished by forcing the attacker to run each passphrase through a
|
|
computationally expensive hashing function many times before they arrive at the
|
|
resulting key. A user who actually knows the passphrase will only have to pay
|
|
this cost once. As CPUs become better at processing, this number should be
|
|
raised to ensure that a brute force attack is still not possible. The current
|
|
default is
|
|
.Sy 350000
|
|
and the minimum is
|
|
.Sy 100000 .
|
|
This property may be changed with
|
|
.Nm zfs Cm change-key .
|
|
.It Sy exec Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether processes can be executed from within this file system.
|
|
The default value is
|
|
.Sy on .
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy exec
|
|
and
|
|
.Sy noexec
|
|
mount options.
|
|
.It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
|
|
Limits the number of filesystems and volumes that can exist under this point in
|
|
the dataset tree.
|
|
The limit is not enforced if the user is allowed to change the limit.
|
|
Setting a
|
|
.Sy filesystem_limit
|
|
to
|
|
.Sy on
|
|
a descendent of a filesystem that already has a
|
|
.Sy filesystem_limit
|
|
does not override the ancestor's
|
|
.Sy filesystem_limit ,
|
|
but rather imposes an additional limit.
|
|
This feature must be enabled to be used
|
|
.Po see
|
|
.Xr zpool-features 5
|
|
.Pc .
|
|
.It Sy special_small_blocks Ns = Ns Em size
|
|
This value represents the threshold block size for including small file
|
|
blocks into the special allocation class. Blocks smaller than or equal to this
|
|
value will be assigned to the special allocation class while greater blocks
|
|
will be assigned to the regular class. Valid values are zero or a power of two
|
|
from 512B up to 1M. The default size is 0 which means no small file blocks
|
|
will be allocated in the special class.
|
|
.Pp
|
|
Before setting this property, a special class vdev must be added to the
|
|
pool. See
|
|
.Xr zpool 8
|
|
for more details on the special allocation class.
|
|
.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
|
|
Controls the mount point used for this file system.
|
|
See the
|
|
.Em Mount Points
|
|
section of
|
|
.Xr zfsconcepts 8
|
|
for more information on how this property is used.
|
|
.Pp
|
|
When the
|
|
.Sy mountpoint
|
|
property is changed for a file system, the file system and any children that
|
|
inherit the mount point are unmounted.
|
|
If the new value is
|
|
.Sy legacy ,
|
|
then they remain unmounted.
|
|
Otherwise, they are automatically remounted in the new location if the property
|
|
was previously
|
|
.Sy legacy
|
|
or
|
|
.Sy none ,
|
|
or if they were mounted before the property was changed.
|
|
In addition, any shared file systems are unshared and shared in the new
|
|
location.
|
|
.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether the file system should be mounted with
|
|
.Sy nbmand
|
|
.Pq Non Blocking mandatory locks .
|
|
This is used for SMB clients.
|
|
Changes to this property only take effect when the file system is umounted and
|
|
remounted.
|
|
See
|
|
.Xr mount 8
|
|
for more information on
|
|
.Sy nbmand
|
|
mounts. This property is not used on Linux.
|
|
.It Sy overlay Ns = Ns Sy on Ns | Ns Sy off
|
|
Allow mounting on a busy directory or a directory which already contains
|
|
files or directories.
|
|
This is the default mount behavior for Linux and FreeBSD file systems.
|
|
On these platforms the property is
|
|
.Sy on
|
|
by default.
|
|
Set to
|
|
.Sy off
|
|
to disable overlay mounts for consistency with OpenZFS on other platforms.
|
|
.It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
|
|
Controls what is cached in the primary cache
|
|
.Pq ARC .
|
|
If this property is set to
|
|
.Sy all ,
|
|
then both user data and metadata is cached.
|
|
If this property is set to
|
|
.Sy none ,
|
|
then neither user data nor metadata is cached.
|
|
If this property is set to
|
|
.Sy metadata ,
|
|
then only metadata is cached.
|
|
The default value is
|
|
.Sy all .
|
|
.It Sy quota Ns = Ns Em size Ns | Ns Sy none
|
|
Limits the amount of space a dataset and its descendents can consume.
|
|
This property enforces a hard limit on the amount of space used.
|
|
This includes all space consumed by descendents, including file systems and
|
|
snapshots.
|
|
Setting a quota on a descendent of a dataset that already has a quota does not
|
|
override the ancestor's quota, but rather imposes an additional limit.
|
|
.Pp
|
|
Quotas cannot be set on volumes, as the
|
|
.Sy volsize
|
|
property acts as an implicit quota.
|
|
.It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
|
|
Limits the number of snapshots that can be created on a dataset and its
|
|
descendents.
|
|
Setting a
|
|
.Sy snapshot_limit
|
|
on a descendent of a dataset that already has a
|
|
.Sy snapshot_limit
|
|
does not override the ancestor's
|
|
.Sy snapshot_limit ,
|
|
but rather imposes an additional limit.
|
|
The limit is not enforced if the user is allowed to change the limit.
|
|
For example, this means that recursive snapshots taken from the global zone are
|
|
counted against each delegated dataset within a zone.
|
|
This feature must be enabled to be used
|
|
.Po see
|
|
.Xr zpool-features 5
|
|
.Pc .
|
|
.It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
|
|
Limits the amount of space consumed by the specified user.
|
|
User space consumption is identified by the
|
|
.Sy userspace@ Ns Em user
|
|
property.
|
|
.Pp
|
|
Enforcement of user quotas may be delayed by several seconds.
|
|
This delay means that a user might exceed their quota before the system notices
|
|
that they are over quota and begins to refuse additional writes with the
|
|
.Er EDQUOT
|
|
error message.
|
|
See the
|
|
.Nm zfs Cm userspace
|
|
subcommand 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 userquota
|
|
privilege with
|
|
.Nm zfs Cm allow ,
|
|
can get and set everyone's quota.
|
|
.Pp
|
|
This property is not available on volumes, on file systems before version 4, or
|
|
on pools before version 15.
|
|
The
|
|
.Sy userquota@ Ns Em ...
|
|
properties are not displayed by
|
|
.Nm zfs Cm get Sy all .
|
|
The user's name must be appended after the
|
|
.Sy @
|
|
symbol, using one of the following forms:
|
|
.Bl -bullet
|
|
.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
|
|
.Pp
|
|
Files created on Linux always have POSIX owners.
|
|
.It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
|
|
The
|
|
.Sy userobjquota
|
|
is similar to
|
|
.Sy userquota
|
|
but it limits the number of objects a user can create. Please refer to
|
|
.Sy userobjused
|
|
for more information about how objects are counted.
|
|
.It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
|
|
Limits the amount of space consumed by the specified group.
|
|
Group space consumption is identified by the
|
|
.Sy groupused@ Ns Em group
|
|
property.
|
|
.Pp
|
|
Unprivileged users can access only their own groups' space usage.
|
|
The root user, or a user who has been granted the
|
|
.Sy groupquota
|
|
privilege with
|
|
.Nm zfs Cm allow ,
|
|
can get and set all groups' quotas.
|
|
.It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
|
|
The
|
|
.Sy groupobjquota
|
|
is similar to
|
|
.Sy groupquota
|
|
but it limits number of objects a group can consume. Please refer to
|
|
.Sy userobjused
|
|
for more information about how objects are counted.
|
|
.It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
|
|
Limits the amount of space consumed by the specified project. Project
|
|
space consumption is identified by the
|
|
.Sy projectused@ Ns Em project
|
|
property. Please refer to
|
|
.Sy projectused
|
|
for more information about how project is identified and set/changed.
|
|
.Pp
|
|
The root user, or a user who has been granted the
|
|
.Sy projectquota
|
|
privilege with
|
|
.Nm zfs allow ,
|
|
can access all projects' quota.
|
|
.It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none
|
|
The
|
|
.Sy projectobjquota
|
|
is similar to
|
|
.Sy projectquota
|
|
but it limits number of objects a project can consume. Please refer to
|
|
.Sy userobjused
|
|
for more information about how objects are counted.
|
|
.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether this dataset can be modified.
|
|
The default value is
|
|
.Sy off .
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy ro
|
|
and
|
|
.Sy rw
|
|
mount options.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name,
|
|
.Sy rdonly .
|
|
.It Sy recordsize Ns = Ns Em size
|
|
Specifies a suggested block size for files in the file system.
|
|
This property is designed solely for use with database workloads that access
|
|
files in fixed-size records.
|
|
ZFS automatically tunes block sizes according to internal algorithms optimized
|
|
for typical access patterns.
|
|
.Pp
|
|
For databases that create very large files but access them in small random
|
|
chunks, these algorithms may be suboptimal.
|
|
Specifying a
|
|
.Sy recordsize
|
|
greater than or equal to the record size of the database can result in
|
|
significant performance gains.
|
|
Use of this property for general purpose file systems is strongly discouraged,
|
|
and may adversely affect performance.
|
|
.Pp
|
|
The size specified must be a power of two greater than or equal to 512 and less
|
|
than or equal to 128 Kbytes.
|
|
If the
|
|
.Sy large_blocks
|
|
feature is enabled on the pool, the size may be up to 1 Mbyte.
|
|
See
|
|
.Xr zpool-features 5
|
|
for details on ZFS feature flags.
|
|
.Pp
|
|
Changing the file system's
|
|
.Sy recordsize
|
|
affects only files created afterward; existing files are unaffected.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name,
|
|
.Sy recsize .
|
|
.It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
|
|
Controls what types of metadata are stored redundantly.
|
|
ZFS stores an extra copy of metadata, so that if a single block is corrupted,
|
|
the amount of user data lost is limited.
|
|
This extra copy is in addition to any redundancy provided at the pool level
|
|
.Pq e.g. by mirroring or RAID-Z ,
|
|
and is in addition to an extra copy specified by the
|
|
.Sy copies
|
|
property
|
|
.Pq up to a total of 3 copies .
|
|
For example if the pool is mirrored,
|
|
.Sy copies Ns = Ns 2 ,
|
|
and
|
|
.Sy redundant_metadata Ns = Ns Sy most ,
|
|
then ZFS stores 6 copies of most metadata, and 4 copies of data and some
|
|
metadata.
|
|
.Pp
|
|
When set to
|
|
.Sy all ,
|
|
ZFS stores an extra copy of all metadata.
|
|
If a single on-disk block is corrupt, at worst a single block of user data
|
|
.Po which is
|
|
.Sy recordsize
|
|
bytes long
|
|
.Pc
|
|
can be lost.
|
|
.Pp
|
|
When set to
|
|
.Sy most ,
|
|
ZFS stores an extra copy of most types of metadata.
|
|
This can improve performance of random writes, because less metadata must be
|
|
written.
|
|
In practice, at worst about 100 blocks
|
|
.Po of
|
|
.Sy recordsize
|
|
bytes each
|
|
.Pc
|
|
of user data can be lost if a single on-disk block is corrupt.
|
|
The exact behavior of which metadata blocks are stored redundantly may change in
|
|
future releases.
|
|
.Pp
|
|
The default value is
|
|
.Sy all .
|
|
.It Sy refquota Ns = Ns Em size Ns | Ns Sy none
|
|
Limits the amount of space a dataset can consume.
|
|
This property enforces a hard limit on the amount of space used.
|
|
This hard limit does not include space used by descendents, including file
|
|
systems and snapshots.
|
|
.It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
|
|
The minimum amount of space guaranteed to a dataset, not including its
|
|
descendents.
|
|
When the amount of space used is below this value, the dataset is treated as if
|
|
it were taking up the amount of space specified by
|
|
.Sy refreservation .
|
|
The
|
|
.Sy refreservation
|
|
reservation is accounted for in the parent datasets' space used, and counts
|
|
against the parent datasets' quotas and reservations.
|
|
.Pp
|
|
If
|
|
.Sy refreservation
|
|
is set, a snapshot is only allowed if there is enough free pool space outside of
|
|
this reservation to accommodate the current number of
|
|
.Qq referenced
|
|
bytes in the dataset.
|
|
.Pp
|
|
If
|
|
.Sy refreservation
|
|
is set to
|
|
.Sy auto ,
|
|
a volume is thick provisioned
|
|
.Po or
|
|
.Qq not sparse
|
|
.Pc .
|
|
.Sy refreservation Ns = Ns Sy auto
|
|
is only supported on volumes.
|
|
See
|
|
.Sy volsize
|
|
in the
|
|
.Sx Native Properties
|
|
section for more information about sparse volumes.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name,
|
|
.Sy refreserv .
|
|
.It Sy relatime Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls the manner in which the access time is updated when
|
|
.Sy atime=on
|
|
is set. Turning this property on causes the access time to be updated relative
|
|
to the modify or change time. Access time is only updated if the previous
|
|
access time was earlier than the current modify or change time or if the
|
|
existing access time hasn't been updated within the past 24 hours. The default
|
|
value is
|
|
.Sy off .
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy relatime
|
|
and
|
|
.Sy norelatime
|
|
mount options.
|
|
.It Sy reservation Ns = Ns Em size Ns | Ns Sy none
|
|
The minimum amount of space guaranteed to a dataset and its descendants.
|
|
When the amount of space used is below this value, the dataset is treated as if
|
|
it were taking up the amount of space specified by its reservation.
|
|
Reservations are accounted for in the parent datasets' space used, and count
|
|
against the parent datasets' quotas and reservations.
|
|
.Pp
|
|
This property can also be referred to by its shortened column name,
|
|
.Sy reserv .
|
|
.It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
|
|
Controls what is cached in the secondary cache
|
|
.Pq L2ARC .
|
|
If this property is set to
|
|
.Sy all ,
|
|
then both user data and metadata is cached.
|
|
If this property is set to
|
|
.Sy none ,
|
|
then neither user data nor metadata is cached.
|
|
If this property is set to
|
|
.Sy metadata ,
|
|
then only metadata is cached.
|
|
The default value is
|
|
.Sy all .
|
|
.It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether the setuid bit is respected for the file system.
|
|
The default value is
|
|
.Sy on .
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy suid
|
|
and
|
|
.Sy nosuid
|
|
mount options.
|
|
.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
|
|
Controls whether the file system is shared by using
|
|
.Sy Samba USERSHARES
|
|
and what options are to be used. Otherwise, the file system is automatically
|
|
shared and unshared with the
|
|
.Nm zfs Cm share
|
|
and
|
|
.Nm zfs Cm unshare
|
|
commands. If the property is set to on, the
|
|
.Xr net 8
|
|
command is invoked to create a
|
|
.Sy USERSHARE .
|
|
.Pp
|
|
Because SMB shares requires a resource name, a unique resource name is
|
|
constructed from the dataset name. The constructed name is a copy of the
|
|
dataset name except that the characters in the dataset name, which would be
|
|
invalid in the resource name, are replaced with underscore (_) characters.
|
|
Linux does not currently support additional options which might be available
|
|
on Solaris.
|
|
.Pp
|
|
If the
|
|
.Sy sharesmb
|
|
property is set to
|
|
.Sy off ,
|
|
the file systems are unshared.
|
|
.Pp
|
|
The share is created with the ACL (Access Control List) "Everyone:F" ("F"
|
|
stands for "full permissions", ie. read and write permissions) and no guest
|
|
access (which means Samba must be able to authenticate a real user, system
|
|
passwd/shadow, LDAP or smbpasswd based) by default. This means that any
|
|
additional access control (disallow specific user specific access etc) must
|
|
be done on the underlying file system.
|
|
.It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
|
|
Controls whether the file system is shared via NFS, and what options are to be
|
|
used.
|
|
A file system with a
|
|
.Sy sharenfs
|
|
property of
|
|
.Sy off
|
|
is managed with the
|
|
.Xr exportfs 8
|
|
command and entries in the
|
|
.Em /etc/exports
|
|
file.
|
|
Otherwise, the file system is automatically shared and unshared with the
|
|
.Nm zfs Cm share
|
|
and
|
|
.Nm zfs Cm unshare
|
|
commands.
|
|
If the property is set to
|
|
.Sy on ,
|
|
the dataset is shared using the default options:
|
|
.Pp
|
|
.Em sec=sys,rw,crossmnt,no_subtree_check
|
|
.Pp
|
|
See
|
|
.Xr exports 5
|
|
for the meaning of the default options. Otherwise, the
|
|
.Xr exportfs 8
|
|
command is invoked with options equivalent to the contents of this property.
|
|
.Pp
|
|
When the
|
|
.Sy sharenfs
|
|
property is changed for a dataset, the dataset and any children inheriting the
|
|
property are re-shared with the new options, only if the property was previously
|
|
.Sy off ,
|
|
or if they were shared before the property was changed.
|
|
If the new property is
|
|
.Sy off ,
|
|
the file systems are unshared.
|
|
.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
|
|
Provide a hint to ZFS about handling of synchronous requests in this dataset.
|
|
If
|
|
.Sy logbias
|
|
is set to
|
|
.Sy latency
|
|
.Pq the default ,
|
|
ZFS will use pool log devices
|
|
.Pq if configured
|
|
to handle the requests at low latency.
|
|
If
|
|
.Sy logbias
|
|
is set to
|
|
.Sy throughput ,
|
|
ZFS will not use configured pool log devices.
|
|
ZFS will instead optimize synchronous operations for global pool throughput and
|
|
efficient use of resources.
|
|
.It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible
|
|
Controls whether the volume snapshot devices under
|
|
.Em /dev/zvol/<pool>
|
|
are hidden or visible. The default value is
|
|
.Sy hidden .
|
|
.It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
|
|
Controls whether the
|
|
.Pa .zfs
|
|
directory is hidden or visible in the root of the file system as discussed in
|
|
the
|
|
.Em Snapshots
|
|
section of
|
|
.Xr zfsconcepts 8 .
|
|
The default value is
|
|
.Sy hidden .
|
|
.It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
|
|
Controls the behavior of synchronous requests
|
|
.Pq e.g. fsync, O_DSYNC .
|
|
.Sy standard
|
|
is the
|
|
.Tn POSIX
|
|
specified behavior of ensuring all synchronous requests are written to stable
|
|
storage and all devices are flushed to ensure data is not cached by device
|
|
controllers
|
|
.Pq this is the default .
|
|
.Sy always
|
|
causes every file system transaction to be written and flushed before its
|
|
system call returns.
|
|
This has a large performance penalty.
|
|
.Sy disabled
|
|
disables synchronous requests.
|
|
File system transactions are only committed to stable storage periodically.
|
|
This option will give the highest performance.
|
|
However, it is very dangerous as ZFS would be ignoring the synchronous
|
|
transaction demands of applications such as databases or NFS.
|
|
Administrators should only use this option when the risks are understood.
|
|
.It Sy version Ns = Ns Em N Ns | Ns Sy current
|
|
The on-disk version of this file system, which is independent of the pool
|
|
version.
|
|
This property can only be set to later supported versions.
|
|
See the
|
|
.Nm zfs Cm upgrade
|
|
command.
|
|
.It Sy volsize Ns = Ns Em size
|
|
For volumes, specifies the logical size of the volume.
|
|
By default, creating a volume establishes a reservation of equal size.
|
|
For storage pools with a version number of 9 or higher, a
|
|
.Sy refreservation
|
|
is set instead.
|
|
Any changes to
|
|
.Sy volsize
|
|
are reflected in an equivalent change to the reservation
|
|
.Po or
|
|
.Sy refreservation
|
|
.Pc .
|
|
The
|
|
.Sy volsize
|
|
can only be set to a multiple of
|
|
.Sy volblocksize ,
|
|
and cannot be zero.
|
|
.Pp
|
|
The reservation is kept equal to the volume's logical size to prevent unexpected
|
|
behavior for consumers.
|
|
Without the reservation, the volume could run out of space, resulting in
|
|
undefined behavior or data corruption, depending on how the volume is used.
|
|
These effects can also occur when the volume size is changed while it is in use
|
|
.Pq particularly when shrinking the size .
|
|
Extreme care should be used when adjusting the volume size.
|
|
.Pp
|
|
Though not recommended, a
|
|
.Qq sparse volume
|
|
.Po also known as
|
|
.Qq thin provisioned
|
|
.Pc
|
|
can be created by specifying the
|
|
.Fl s
|
|
option to the
|
|
.Nm zfs Cm create Fl V
|
|
command, or by changing the value of the
|
|
.Sy refreservation
|
|
property
|
|
.Po or
|
|
.Sy reservation
|
|
property on pool version 8 or earlier
|
|
.Pc
|
|
after the volume has been created.
|
|
A
|
|
.Qq sparse volume
|
|
is a volume where the value of
|
|
.Sy refreservation
|
|
is less than the size of the volume plus the space required to store its
|
|
metadata.
|
|
Consequently, writes to a sparse volume can fail with
|
|
.Er ENOSPC
|
|
when the pool is low on space.
|
|
For a sparse volume, changes to
|
|
.Sy volsize
|
|
are not reflected in the
|
|
.Sy refreservation.
|
|
A volume that is not sparse is said to be
|
|
.Qq thick provisioned .
|
|
A sparse volume can become thick provisioned by setting
|
|
.Sy refreservation
|
|
to
|
|
.Sy auto .
|
|
.It Sy volmode Ns = Ns Cm default | full | geom | dev | none
|
|
This property specifies how volumes should be exposed to the OS.
|
|
Setting it to
|
|
.Sy full
|
|
exposes volumes as fully fledged block devices, providing maximal
|
|
functionality. The value
|
|
.Sy geom
|
|
is just an alias for
|
|
.Sy full
|
|
and is kept for compatibility.
|
|
Setting it to
|
|
.Sy dev
|
|
hides its partitions.
|
|
Volumes with property set to
|
|
.Sy none
|
|
are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc,
|
|
that can be suitable for backup purposes.
|
|
Value
|
|
.Sy default
|
|
means that volumes exposition is controlled by system-wide tunable
|
|
.Va zvol_volmode ,
|
|
where
|
|
.Sy full ,
|
|
.Sy dev
|
|
and
|
|
.Sy none
|
|
are encoded as 1, 2 and 3 respectively.
|
|
The default values is
|
|
.Sy full .
|
|
.It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether regular files should be scanned for viruses when a file is
|
|
opened and closed.
|
|
In addition to enabling this property, the virus scan service must also be
|
|
enabled for virus scanning to occur.
|
|
The default value is
|
|
.Sy off .
|
|
This property is not used on Linux.
|
|
.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa
|
|
Controls whether extended attributes are enabled for this file system. Two
|
|
styles of extended attributes are supported either directory based or system
|
|
attribute based.
|
|
.Pp
|
|
The default value of
|
|
.Sy on
|
|
enables directory based extended attributes. This style of extended attribute
|
|
imposes no practical limit on either the size or number of attributes which
|
|
can be set on a file. Although under Linux the
|
|
.Xr getxattr 2
|
|
and
|
|
.Xr setxattr 2
|
|
system calls limit the maximum size to 64K. This is the most compatible
|
|
style of extended attribute and is supported by all OpenZFS implementations.
|
|
.Pp
|
|
System attribute based xattrs can be enabled by setting the value to
|
|
.Sy sa .
|
|
The key advantage of this type of xattr is improved performance. Storing
|
|
extended attributes as system attributes significantly decreases the amount of
|
|
disk IO required. Up to 64K of data may be stored per-file in the space
|
|
reserved for system attributes. If there is not enough space available for
|
|
an extended attribute then it will be automatically written as a directory
|
|
based xattr. System attribute based extended attributes are not accessible
|
|
on platforms which do not support the
|
|
.Sy xattr=sa
|
|
feature.
|
|
.Pp
|
|
The use of system attribute based xattrs is strongly encouraged for users of
|
|
SELinux or POSIX ACLs. Both of these features heavily rely on extended
|
|
attributes and benefit significantly from the reduced access time.
|
|
.Pp
|
|
The values
|
|
.Sy on
|
|
and
|
|
.Sy off
|
|
are equivalent to the
|
|
.Sy xattr
|
|
and
|
|
.Sy noxattr
|
|
mount options.
|
|
.It Sy jailed Ns = Ns Cm off | on
|
|
Controls whether the dataset is managed from a jail. See the
|
|
.Qq Sx Jails
|
|
section in
|
|
.Xr zfs 8
|
|
for more information. Jails are a FreeBSD feature and are not relevant on
|
|
other platforms. The default value is
|
|
.Cm off .
|
|
.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
|
|
Controls whether the dataset is managed from a non-global zone. Zones are a
|
|
Solaris feature and are not relevant on other platforms. The default value is
|
|
.Sy off .
|
|
.El
|
|
.Pp
|
|
The following three properties cannot be changed after the file system is
|
|
created, and therefore, should be set when the file system is created.
|
|
If the properties are not set with the
|
|
.Nm zfs Cm create
|
|
or
|
|
.Nm zpool Cm create
|
|
commands, these properties are inherited from the parent dataset.
|
|
If the parent dataset lacks these properties due to having been created prior to
|
|
these features being supported, the new file system will have the default values
|
|
for these properties.
|
|
.Bl -tag -width ""
|
|
.It Xo
|
|
.Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
|
|
.Sy insensitive Ns | Ns Sy mixed
|
|
.Xc
|
|
Indicates whether the file name matching algorithm used by the file system
|
|
should be case-sensitive, case-insensitive, or allow a combination of both
|
|
styles of matching.
|
|
The default value for the
|
|
.Sy casesensitivity
|
|
property is
|
|
.Sy sensitive .
|
|
Traditionally,
|
|
.Ux
|
|
and
|
|
.Tn POSIX
|
|
file systems have case-sensitive file names.
|
|
.Pp
|
|
The
|
|
.Sy mixed
|
|
value for the
|
|
.Sy casesensitivity
|
|
property indicates that the file system can support requests for both
|
|
case-sensitive and case-insensitive matching behavior.
|
|
Currently, case-insensitive matching behavior on a file system that supports
|
|
mixed behavior is limited to the SMB server product.
|
|
For more information about the
|
|
.Sy mixed
|
|
value behavior, see the "ZFS Administration Guide".
|
|
.It Xo
|
|
.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
|
|
.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
|
|
.Xc
|
|
Indicates whether the file system should perform a
|
|
.Sy unicode
|
|
normalization of file names whenever two file names are compared, and which
|
|
normalization algorithm should be used.
|
|
File names are always stored unmodified, names are normalized as part of any
|
|
comparison process.
|
|
If this property is set to a legal value other than
|
|
.Sy none ,
|
|
and the
|
|
.Sy utf8only
|
|
property was left unspecified, the
|
|
.Sy utf8only
|
|
property is automatically set to
|
|
.Sy on .
|
|
The default value of the
|
|
.Sy normalization
|
|
property is
|
|
.Sy none .
|
|
This property cannot be changed after the file system is created.
|
|
.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
|
|
Indicates whether the file system should reject file names that include
|
|
characters that are not present in the
|
|
.Sy UTF-8
|
|
character code set.
|
|
If this property is explicitly set to
|
|
.Sy off ,
|
|
the normalization property must either not be explicitly set or be set to
|
|
.Sy none .
|
|
The default value for the
|
|
.Sy utf8only
|
|
property is
|
|
.Sy off .
|
|
This property cannot be changed after the file system is created.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Sy casesensitivity ,
|
|
.Sy normalization ,
|
|
and
|
|
.Sy utf8only
|
|
properties are also new permissions that can be assigned to non-privileged users
|
|
by using the ZFS delegated administration feature.
|
|
.Ss "Temporary Mount Point Properties"
|
|
When a file system is mounted, either through
|
|
.Xr mount 8
|
|
for legacy mounts or the
|
|
.Nm zfs Cm mount
|
|
command for normal file systems, its mount options are set according to its
|
|
properties.
|
|
The correlation between properties and mount options is as follows:
|
|
.Bd -literal
|
|
PROPERTY MOUNT OPTION
|
|
atime atime/noatime
|
|
canmount auto/noauto
|
|
devices dev/nodev
|
|
exec exec/noexec
|
|
readonly ro/rw
|
|
relatime relatime/norelatime
|
|
setuid suid/nosuid
|
|
xattr xattr/noxattr
|
|
.Ed
|
|
.Pp
|
|
In addition, these options can be set on a per-mount basis using the
|
|
.Fl o
|
|
option, without affecting the property that is stored on disk.
|
|
The values specified on the command line override the values stored in the
|
|
dataset.
|
|
The
|
|
.Sy nosuid
|
|
option is an alias for
|
|
.Sy nodevices Ns \&, Ns Sy nosetuid .
|
|
These properties are reported as
|
|
.Qq temporary
|
|
by the
|
|
.Nm zfs Cm get
|
|
command.
|
|
If the properties are changed while the dataset is mounted, the new setting
|
|
overrides any temporary settings.
|
|
.Ss "User Properties"
|
|
In addition to the standard native properties, ZFS supports arbitrary user
|
|
properties.
|
|
User properties have no effect on ZFS behavior, but applications or
|
|
administrators can use them to annotate datasets
|
|
.Pq file systems, volumes, and snapshots .
|
|
.Pp
|
|
User property names must contain a colon
|
|
.Pq Qq Sy \&:
|
|
character to distinguish them from native properties.
|
|
They may contain lowercase letters, numbers, and the following punctuation
|
|
characters: colon
|
|
.Pq Qq Sy \&: ,
|
|
dash
|
|
.Pq Qq Sy - ,
|
|
period
|
|
.Pq Qq Sy \&. ,
|
|
and underscore
|
|
.Pq Qq Sy _ .
|
|
The expected convention is that the property name is divided into two portions
|
|
such as
|
|
.Em module Ns \&: Ns Em property ,
|
|
but this namespace is not enforced by ZFS.
|
|
User property names can be at most 256 characters, and cannot begin with a dash
|
|
.Pq Qq Sy - .
|
|
.Pp
|
|
When making programmatic use of user properties, it is strongly suggested to use
|
|
a reversed
|
|
.Sy DNS
|
|
domain name for the
|
|
.Em module
|
|
component of property names to reduce the chance that two
|
|
independently-developed packages use the same property name for different
|
|
purposes.
|
|
.Pp
|
|
The values of user properties are arbitrary strings, are always inherited, and
|
|
are never validated.
|
|
All of the commands that operate on properties
|
|
.Po Nm zfs Cm list ,
|
|
.Nm zfs Cm get ,
|
|
.Nm zfs Cm set ,
|
|
and so forth
|
|
.Pc
|
|
can be used to manipulate both native properties and user properties.
|
|
Use the
|
|
.Nm zfs Cm inherit
|
|
command to clear a user property.
|
|
If the property is not defined in any parent dataset, it is removed entirely.
|
|
Property values are limited to 8192 bytes.
|