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. For a list of settable dataset properties, see Settable ZFS 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

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

Non-numeric properties are case-sensitive and must be lowercase, with the exception of mountpoint and sharenfs. These properties may 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 is 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                      inherited from tank/home

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 descendants 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 descendant 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 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 pool
NAME             PROPERTY       VALUE                      SOURCE
pool             type           filesystem                 -
pool             creation       Mon Mar 13 11:41 2006      -
pool             used           2.62M                      -
pool             available      33.5G                      -
pool             referenced     10.5K                      -
pool             compressratio  1.00x                      -
pool             mounted        yes                        -
pool             quota          none                       default
pool             reservation    none                       default
pool             recordsize     128K                       default
pool             mountpoint     /pool                      default
pool             sharenfs       off                        default
pool             checksum       on                         default
pool             compression    off                        default
pool             atime          on                         default
pool             devices        on                         default
pool             exec           on                         default
pool             setuid         on                         default
pool             readonly       off                        default
pool             zoned          off                        default
pool             snapdir        hidden                     default
pool             aclmode        groupmask                  default
pool             aclinherit     secure                     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

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 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 descendants. 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 descendants, 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