Managing ZFS Properties

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 a 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 followed by
a dataset name. Only one property can be set or modified during
each zfs set invocation.

The following example sets the atime property to off for tank/home.

# zfs set atime=off tank/home

In addition, any file system property can be set when a file
system is created. For example:

# zfs create -o atime=off tank/home

You can specify numeric property values by using the following easy-to-understand suffixes (in
increasing 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
that set the quota property be set to the value of 50 GB
on the tank/home/marks file system:

The values of non-numeric properties are case-sensitive and must be in lowercase letters,
with the exception of mountpoint and sharenfs. The values of these properties
can have mixed upper and lower case letters.

Inheriting ZFS Properties

All settable properties, with the exception of quotas and reservations, inherit their value
from the parent dataset, unless a quota or reservation is explicitly set on
the descendent dataset. 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 value, thus causing the value to
be inherited from the parent dataset.

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 clear the compression property, thus causing
the property to inherit the default value of off. Because neither home nor
tank has the compression property set locally, the default value is used. If both
had compression enabled, the value set in the most immediate ancestor would be
used (home in this example).

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.

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 value on a dataset:

The fourth column, SOURCE, indicates the origin of this property value. The following
table defines the possible source values.

Table 6-3 Possible SOURCE Values (zfs get Command)

Source Value

Description

default

This property value was never explicitly
set for this dataset or any of its ancestors. The default value for
this property is being used.

inherited fromdataset-name

This property value is inherited from the
parent dataset specified in 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 duration of the mount.
For more information about temporary mount point properties, see Using Temporary Mount Properties.

- (none)

This property is
read-only. Its value is generated by ZFS.

You can use the special keyword all to retrieve all dataset property values.
The following examples use the all keyword:

Note - The casesensitivity, nbmand, normalization, sharesmb, utf8only, and vscan properties are not fully operational
in the Oracle Solaris 10 release because the Oracle Solaris SMB service is
not supported in the Oracle Solaris 10 release.

The -s option to zfs get enables you to specify, by source type, the
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:

Querying ZFS Properties for Scripting

The zfs get command supports the -H and -o options, which are designed
for scripting. You can use the -H option to omit header information and
to replace white space with the Tab character. Uniform white space allows for
easily parseable data. You can use the -o option to customize the output
in the following ways:

A comma-separated list of literal fields, name, value, property, and source, to be output followed by a space and an argument, which is a comma-separated list of properties.

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
MB 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 preceding options,
to recursively retrieve the requested values for all descendents. The following example uses
the -H, -o, and -r options to retrieve the dataset name and
the value of the used property for export/home and its descendents, while omitting
the header output: