5.4.3 Querying Properties

The simplest way to query property values is zfs list (see 5.3.1 Listing Basic Information). However, for complicated queries and scripting, the zfs get subcommand can provide more detailed information in a customized format.

The zfs get subcommand can be used to retrieve any dataset property. The example below 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 table below defines the meaning of the possible source values.

Table 5-2 Possible SOURCE Values (zfs get)

The special keyword all can be used to retrieve all dataset properties. The example below uses the all keyword to retrieve all existing dataset properties.

# zfs get all pool
NAME             PROPERTY       VALUE                      SOURCE
pool             type           filesystem                 -
pool             creation       Sat Nov 12 11:41 2005      -
pool             used           32K                        -
pool             available      33.5G                      -
pool             referenced     8K                         -
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    on                         local
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        visible                    default
pool             aclmode        groupmask                  default
pool             aclinherit     secure                     default

The -s option to zfs get provides the ability to specify, by source value, the type of properties to be output. This option takes a comma separated list indicating the source types desired. Any property that does not have the specified source type isn't displayed. The valid source types are: local, default, inherited, temporary, and none. The example below 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 get the specified properties on all children of the specified dataset. The following example recursively retrieves all temporary properties on all datasets within tank.

# 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

5.4.4 Querying Properties for Scripting

The zfs get subcommand supports the -H and -o options. These options are designed for scripting. The -H indicates that any header information should be omitted and that all white space should come in the form of tabs; uniform white space allows for easily parseable data. The -o option allows the user to customize the output. This option takes a comma separated list of values to be output. All properties, defined in 5.2 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 using the -H and -o options of zfs get.

# zfs get -H -o value compression tank/home
on

A-p option is supported that 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

The -r option along with any of the above options can be used to recursively get the requested value(s) for all descendants. The following example uses the -r, -o, and -H options to output 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

5.5 Mounting and Sharing File Systems

This section describes how mount points and shared filesystems are managed in ZFS.

5.5.1 Managing Mount Points

By default, all ZFS filesystems are mounted by ZFS at boot via the svc://system/filesystem/local smf(5) service. Filesystems are mounted under /path, where path is the name of the filesystem.

The default mount point can be overridden by setting the mountpoint property to a specific path using the zfs set command. ZFS automatically creates this mount point, if needed, and automatically mounts this filesystems when zfs mount -a is invoked, without having to edit the /etc/vfstab file.

The mountpoint property is inherited. For example, if pool/home has mountpoint set to /export/stuff, then pool/home/user inherits /export/stuff/user for mountpoint.

The mountpoint property can be set to none to prevent the filesystem from being mounted.

If desired, filesystems can also be explicitly managed through legacy mount interfaces by setting the mountpoint property to legacy via zfs set. Doing so prevents ZFS from automatically mounting and managing this filesystem; legacy tools including the mount and umount commands, and the /etc/vfstab file must be used instead. Legacy mounts are discussed in more detail below.

When changing mount point management strategies, the following behaviors apply:

5.5.1.1 Automatic Mount Points

• When changing from legacy or none, ZFS automatically mounts the filesystem.

• If ZFS is currently managing the filesystem but it is currently unmounted, and the mountpoint property is changed, the filesystem remains unmounted.

The default mount point for the root dataset can also be set at creation time by using zpool create's -m option. For more information on creating pools, see 4.4.1 Creating a Pool.

Any dataset whose mountpoint property is not legacy is managed by ZFS. The example below creates a dataset that is managed by ZFS.

# zfs create pool/filesystem
# zfs get mountpoint pool/filesystem
NAME             PROPERTY      VALUE                      SOURCE
pool/filesystem  mountpoint    /pool/filesystem           default
# zfs get mounted pool/filesystem
NAME             PROPERTY      VALUE                      SOURCE
pool/filesystem  mounted       yes                        -

The mountpoint property can also be explicitly set as shown in the example below.

# zfs set mountpoint=/mnt pool/filesystem
# zfs get mountpoint pool/filesystem
NAME             PROPERTY      VALUE                      SOURCE
pool/filesystem  mountpoint    /mnt                       local
# zfs get mounted pool/filesystem
NAME             PROPERTY      VALUE                      SOURCE
pool/filesystem  mounted       yes                        -

When the mountpoint property is changed, the filesystem is automatically unmounted from the old mount point and remounted to the new mount point. Mount point directories are created as needed. If ZFS is unable to unmount a filesystem, due to it being active, an error is reported and a forced manual unmount will be necessary.