Managing ZFS Properties
Dataset properties are managed through the zfs command's set, inherit, and get
subcommands.
Setting ZFS Properties
You can use the zfs set command to modify any settable dataset property.
Or, you can use the zfs create command to set properties when the dataset
is created. For a list of settable dataset properties, see Settable ZFS Native Properties. The zfs set command
takes a property/value sequence in the format of property=value and a dataset name.
The following example sets the atime property to off for tank/home. Only
one property can be set or modified during each zfs set invocation.
# zfs set atime=off tank/home
In addition, any file system property can be set when the file
system is created. For example:
# zfs create -o atime=off tank/home
You can specify numeric properties by using the following easy to understand suffixes
(in order of magnitude): BKMGTPEZ. Any of these suffixes can be followed
by an optional b, indicating bytes, with the exception of the B suffix,
which already indicates bytes. The following four invocations of zfs set are equivalent numeric expressions
indicating that the quota property be set to the value of 50 Gbytes
on the tank/home/marks file system:
# zfs set quota=50G tank/home/marks
# zfs set quota=50g tank/home/marks
# zfs set quota=50GB tank/home/marks
# zfs set quota=50gb tank/home/marks
Values of non-numeric properties are case-sensitive and must be lowercase, with the exception
of mountpoint and sharenfs. The values of these properties can have mixed
upper and lower case letters.
For more information about the zfs set command, see zfs(1M).
Inheriting ZFS Properties
All settable properties, with the exception of quotas and reservations, inherit their value
from their parent, unless a quota or reservation is explicitly set on the
child. If no ancestor has an explicit value set for an inherited property,
the default value for the property is used. You can use the
zfs inherit command to clear a property setting, thus causing the setting to be
inherited from the parent.
The following example uses the zfs set command to turn on compression for the
tank/home/bonwick file system. Then, zfs inherit is used to unset the compression property, thus causing
the property to inherit the default setting of off. Because neither home nor
tank have the compression property set locally, the default value is used. If both
had compression on, the value set in the most immediate ancestor would be
used (home in this example).
# zfs set compression=on tank/home/bonwick
# zfs get -r compression tank
NAME PROPERTY VALUE SOURCE
tank compression off default
tank/home compression off default
tank/home/bonwick compression on local
# zfs inherit compression tank/home/bonwick
# zfs get -r compression tank
NAME PROPERTY VALUE SOURCE
tank compression off default
tank/home compression off default
tank/home/bonwick compression off default
The inherit subcommand is applied recursively when the -r option is specified. In
the following example, the command causes the value for the compression property to be
inherited by tank/home and any descendents it might have.
# zfs inherit -r compression tank/home
Note - Be aware that the use of the -r option clears the current property
setting for all descendent datasets.
For more information about the zfs command, see zfs(1M).
Querying ZFS Properties
The simplest way to query property values is by using the zfs list
command. For more information, see Listing Basic ZFS Information. However, for complicated queries and for
scripting, use the zfs get command to provide more detailed information in a customized format.
You can use the zfs get command to retrieve any dataset property. The following
example shows how to retrieve a single property on a dataset:
# zfs get checksum tank/ws
NAME PROPERTY VALUE SOURCE
tank/ws checksum on default
The fourth column, SOURCE, indicates where this property value has been set from.
The following table defines the meaning of the possible source values.
Table 5-3 Possible SOURCE Values (zfs get)
Source Value |
Description |
|---|
default |
This
property was never explicitly set for this dataset or any of its ancestors.
The default value for this property is being used. |
inherited from dataset-name |
This property value
is being inherited from the parent as specified by dataset-name. |
local |
This property value was
explicitly set for this dataset by using zfs set. |
temporary |
This property value was set
by using the zfs mount -o option and is only valid for the
lifetime of the mount. For more information about temporary mount point properties, see
Using Temporary Mount Properties. |
- (none) |
This property is a read-only property. Its value is generated by
ZFS. |
You can use the special keyword all to retrieve all dataset properties. The
following example uses the all keyword to retrieve all existing dataset properties:
# zfs get all tank
NAME PROPERTY VALUE SOURCE
tank type filesystem -
tank creation Wed Jan 23 9:57 2008 -
tank used 120K -
tank available 33.1G -
tank referenced 24.0K -
tank compressratio 1.00x -
tank mounted yes -
tank quota none default
tank reservation none default
tank recordsize 128K default
tank mountpoint /tank default
tank sharenfs off default
tank checksum on default
tank compression off default
tank atime on default
tank devices on default
tank exec on default
tank setuid on default
tank readonly off default
tank zoned off default
tank snapdir hidden default
tank aclmode groupmask default
tank aclinherit secure default
tank canmount on default
tank shareiscsi off default
tank xattr on default
tank copies 1 default
tank version 3 -
tank utf8only off -
tank normalization none -
tank casesensitivity sensitive -
tank vscan off default
tank nbmand off default
tank sharesmb off default
tank refquota none default
tank refreservation none default
The -s option to zfs get enables you to specify, by source value, the
type of properties to display. This option takes a comma-separated list indicating the
desired source types. Only properties with the specified source type are displayed. The
valid source types are local, default, inherited, temporary, and none. The following
example shows all properties that have been locally set on pool.
# zfs get -s local all pool
NAME PROPERTY VALUE SOURCE
pool compression on local
Any of the above options can be combined with the -r option to
recursively display the specified properties on all children of the specified dataset. In
the following example, all temporary properties on all datasets within tank are recursively
displayed:
# zfs get -r -s temporary all tank
NAME PROPERTY VALUE SOURCE
tank/home atime off temporary
tank/home/bonwick atime off temporary
tank/home/marks atime off temporary
A recent feature enables you to make queries with the zfs get command without
specifying a target file system, which means it operates on all pools or
file systems. For example:
# zfs get -s local all
tank/home atime off local
tank/home/bonwick atime off local
tank/home/marks quota 50G local
For more information about the zfs get command, see zfs(1M).
Querying ZFS Properties for Scripting
The zfs get command supports the -H and -o options, which are designed
for scripting. The -H option indicates that any header information should be omitted
and that all white space should come in the form of tab. Uniform
white space allows for easily parseable data. You can use the -o option
to customize the output. This option takes a comma-separated list of values to
be output. All properties defined in Introducing ZFS Properties, along with the literals name, value, property
and source can be supplied in the -o list.
The following example shows how to retrieve a single value by using the
-H and -o options of zfs get.
# zfs get -H -o value compression tank/home
on
The -p option reports numeric values as their exact values. For example, 1
Mbyte would be reported as 1000000. This option can be used as follows:
# zfs get -H -o value -p used tank/home
182983742
You can use the -r option along with any of the above options
to recursively retrieve the requested values for all descendents. The following example uses
the -r, -o, and -H options to retrieve the dataset name and
the value of the used property for export/home and its descendents, while omitting
any header output:
# zfs get -H -o name,value -r used export/home
export/home 5.57G
export/home/marks 1.43G
export/home/maybee 2.15G
