Dataset properties are managed through the zfs command's set, inherit, and get subcommands.
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 sizes): 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 20 GB on the users/home/mark file system:
# zfs set quota=20G users/home/mark # zfs set quota=20g users/home/mark # zfs set quota=20GB users/home/mark # zfs set quota=20gb users/home/mark
If you attempt to set a property on a file system that is 100% full, you will see a message similar to the following:
# zfs set quota=20gb users/home/mark cannot set property for '/users/home/mark': out of space
The values of non-numeric properties are case-sensitive and must be in lowercase letters, with the exception of mountpoint. The values of this property can have mixed upper and lower case letters.
For more information about the zfs set command, see the zfs(1M) man page.
All settable properties, with the exception of quotas and reservations, inherit their value from the parent file system, unless a quota or reservation is explicitly set on the descendent file system. 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 file system.
The following example uses the zfs set command to turn on compression for the tank/home/jeff 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).
# zfs set compression=on tank/home/jeff # zfs get -r compression tank/home NAME PROPERTY VALUE SOURCE tank/home compression off default tank/home/eric compression off default tank/home/eric@today compression - - tank/home/jeff compression on local # zfs inherit compression tank/home/jeff # zfs get -r compression tank/home NAME PROPERTY VALUE SOURCE tank/home compression off default tank/home/eric compression off default tank/home/eric@today compression - - tank/home/jeff 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
For more information about the zfs inherit command, see the see zfs(1M) man page.
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:
# zfs get checksum tank/ws NAME PROPERTY VALUE SOURCE tank/ws checksum on default
The fourth column, SOURCE, indicates the origin of this property value. The following table defines the possible source values.
|
You can use the special keyword all to retrieve all dataset property values. The following examples use the all keyword:
# zfs get all tank/home NAME PROPERTY VALUE SOURCE tank/home aclinherit restricted default tank/home aclmode discard default tank/home atime on default tank/home available 274G - tank/home canmount on default tank/home casesensitivity mixed - tank/home checksum on default tank/home compression off default tank/home compressratio 1.00x - tank/home copies 1 default tank/home creation Tue Jul 30 10:08 2013 - tank/home dedup off default tank/home defaultgroupquota none - tank/home defaultuserquota none - tank/home devices on default tank/home encryption off - tank/home exec on default tank/home keychangedate - default tank/home keysource none default tank/home keystatus none - tank/home logbias latency default tank/home mlslabel none - tank/home mounted yes - tank/home mountpoint /tank/home default tank/home multilevel off - tank/home nbmand off default tank/home normalization none - tank/home primarycache all default tank/home quota none default tank/home readonly off default tank/home recordsize 128K default tank/home referenced 31K - tank/home refquota none default tank/home refreservation none default tank/home rekeydate - default tank/home reservation none default tank/home rstchown on default tank/home secondarycache all default tank/home setuid on default tank/home shadow none - tank/home share.* ... default tank/home snapdir hidden default tank/home sync standard default tank/home type filesystem - tank/home used 31K - tank/home usedbychildren 0 - tank/home usedbydataset 31K - tank/home usedbyrefreservation 0 - tank/home usedbysnapshots 0 - tank/home utf8only off - tank/home version 6 - tank/home vscan off default tank/home xattr on default tank/home zoned off default
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 tank/ws.
# zfs get -s local all tank/ws NAME PROPERTY VALUE SOURCE tank/ws 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 file system. In the following example, all temporary properties on all file systems within tank/home are recursively displayed:
# zfs get -r -s temporary all tank/home NAME PROPERTY VALUE SOURCE tank/home atime off temporary tank/home/jeff atime off temporary tank/home/mark quota 20G temporary
You can query property values by using the zfs get command without specifying a target file system, which means the command operates on all pools or file systems. For example:
# zfs get -s local all tank/home atime off local tank/home/jeff atime off local tank/home/mark quota 20G local
For more information about the zfs get command, see the zfs(1M) man page.
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:
The literal name can be used with a comma-separated list of properties as defined in the Introducing ZFS Properties section.
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 file system name and the value of the used property for export/home and its descendents, while omitting the header output:
# zfs get -H -o name,value -r used export/home