Managing ZFS File Systems

This chapter provides detailed information about managing ZFS file systems. Concepts such as hierarchical file system layout, property inheritance, and automatic mount point management and share interactions are included in this chapter.

A ZFS file system is a lightweight POSIX file system that is built on top of a storage pool. File systems can be dynamically created and destroyed without requiring you to allocate or format any underlying space. Because file systems are so lightweight and because they are the central point of administration in ZFS, you are likely to create many of them.

ZFS file systems are administered by using the zfs command. The zfs command provides a set of subcommands that perform specific operations on file systems. This chapter describes these subcommands in detail. Snapshots, volumes, and clones are also managed by using this command, but these features are only covered briefly in this chapter. For detailed information about snapshots and clones, see Working With ZFS Snapshots and Clones. For detailed information about emulated volumes, see ZFS Volumes.

The term dataset is used in this chapter as a generic term to refer to a file system, snapshot, clone, or volume.

The following sections are provided in this chapter:

• Creating and Destroying ZFS File Systems

• Introducing ZFS Properties

• Querying ZFS File System Information

• Managing ZFS Properties

• Mounting and Sharing ZFS File Systems

• ZFS Quotas and Reservations

• Saving and Restoring ZFS Data

5.1. Creating and Destroying ZFS File Systems

ZFS file systems can be created and destroyed by using the zfs create and zfs destroy commands.

• Creating a ZFS File System

• Destroying a ZFS File System

• Renaming a ZFS File System

5.1.1. Creating a ZFS File System

ZFS file systems are created by using the zfs create command. The create subcommand takes a single argument: the name of the file system to create. The file system name is specified as a path name starting from the name of the pool:

pool-name/[filesystem-name/]filesystem-name

The pool name and initial file system names in the path identify the location in the hierarchy where the new file system will be created. All the intermediate file system names must already exist in the pool. The last name in the path identifies the name of the file system to be created. The file system name must satisfy the naming conventions defined in ZFS Component Naming Requirements.

In the following example, a file system named bonwick is created in the tank/home file system.

# zfs create tank/home/bonwick

ZFS automatically mounts the newly created file system if it is created successfully. By default, file systems are mounted as /dataset, using the path provided for the file system name in the create subcommand. In this example, the newly created bonwick file system is at /tank/home/bonwick. For more information about automanaged mount points, see Managing ZFS Mount Points.

For more information about the zfs create command, see zfs(1M).

You can set file system properties when the file system is created.

In the following example, a mount point of /export/zfs is specified and is created for the tank/home file system.

# zfs create -o mountpoint=/export/zfs tank/home

For more information about file system properties, see Introducing ZFS Properties.

5.1.2. Destroying a ZFS File System

To destroy a ZFS file system, use the zfs destroy command. The destroyed file system is automatically unmounted and unshared. For more information about automatically managed mounts or automatically managed shares, see Automatic Mount Points.

In the following example, the tabriz file system is destroyed.

# zfs destroy tank/home/tabriz

No confirmation prompt appears with the destroy subcommand. Use it with extreme caution.

If the file system to be destroyed is busy and so cannot be unmounted, the zfs destroy command fails. To destroy an active file system, use the -f option. Use this option with caution as it can unmount, unshare, and destroy active file systems, causing unexpected application behavior.

# zfs destroy tank/home/ahrens
cannot unmount 'tank/home/ahrens': Device busy

# zfs destroy -f tank/home/ahrens

The zfs destroy command also fails if a file system has children. To recursively destroy a file system and all its descendents, use the -r option. Note that a recursive destroy also destroys snapshots so use this option with caution.

# zfs destroy tank/ws
cannot destroy 'tank/ws': filesystem has children
use '-r' to destroy the following datasets:
tank/ws/billm
tank/ws/bonwick
tank/ws/maybee

# zfs destroy -r tank/ws

If the file system to be destroyed has indirect dependents, even the recursive destroy command described above fails. To force the destruction of all dependents, including cloned file systems outside the target hierarchy, the -R option must be used. Use extreme caution with this option.

# zfs destroy -r tank/home/schrock
cannot destroy 'tank/home/schrock': filesystem has dependent clones
use '-R' to destroy the following datasets:
tank/clones/schrock-clone

# zfs destroy -R tank/home/schrock

No confirmation prompt appears with the -f, -r, or -R options so use these options carefully.

For more information about snapshots and clones, see Working With ZFS Snapshots and Clones.

5.1.3. Renaming a ZFS File System

File systems can be renamed by using the zfs rename command. Using the rename subcommand can perform the following operations:

• Change the name of a file system

• Relocate the file system to a new location within the ZFS hierarchy

• Change the name of a file system and relocate it with the ZFS hierarchy

The following example uses the rename subcommand to do a simple rename of a file system:

# zfs rename tank/home/kustarz tank/home/kustarz_old

This example renames the kustarz file system to kustarz_old.

The following example shows how to use zfs rename to relocate a file system.

# zfs rename tank/home/maybee tank/ws/maybee

In this example, the maybee file system is relocated from tank/home to tank/ws. When you relocate a file system through rename, the new location must be within the same pool and it must have enough space to hold this new file system. If the new location does not have enough space, possibly because it has reached its quota, the rename will fail.

For more information about quotas, see ZFS Quotas and Reservations.

The rename operation attempts an unmount/remount sequence for the file system and any descendent file systems. The rename fails if the operation is unable to unmount an active file system. If this problem occurs, you will need to force unmount the file system.

For information about renaming snapshots, see Renaming ZFS Snapshots.

5.2. Introducing ZFS Properties

Properties are the main mechanism that you use to control the behavior of file systems, volumes, snapshots, and clones. Unless stated otherwise, the properties defined in the section apply to all the dataset types.

• ZFS Read-Only Native Properties

• Settable ZFS Native Properties

• ZFS User Properties

Properties are divided into two types, native properties and user defined properties. Native properties either export internal statistics or control ZFS file system behavior. In addition, native properties are either settable or read-only. User properties have no effect on ZFS file system behavior, but you can use them to annotate datasets in a way that is meaningful in your environment. For more information on user properties, see ZFS User Properties.

Most settable properties are also inheritable. An inheritable property is a property that, when set on a parent, is propagated down to all of its descendents.

All inheritable properties have an associated source. The source indicates how a property was obtained. The source of a property can have the following values:

local

A local source indicates that the property was explicitly set on the dataset by using the zfs set command as described in Setting ZFS Properties.

inherited from dataset-name

A value of inherited from dataset-name means that the property was inherited from the named ancestor.

default

A value of default means that the property setting was not inherited or set locally. This source is a result of no ancestor having the property as source local.

The following table identifies both read-only and settable native ZFS file system properties. Read-only native properties are identified as such. All other native properties listed in this table are settable. For information about user properties, see ZFS User Properties.

5.2.1. ZFS Read-Only Native Properties

Read-only native properties are properties that can be retrieved but cannot be set. Read-only native properties are not inherited. Some native properties are specific to a particular type of dataset. In such cases, the particular dataset type is mentioned in the description in ZFS Native Property Descriptions.

The read-only native properties are listed here and are described in ZFS Native Property Descriptions.

• available

• creation

• mounted

• origin

• compressratio

• referenced

• type

• used

  For detailed information, see The used Property.

For more information on space accounting, including the used, referenced, and available properties, see ZFS Space Accounting.

The used Property

The amount of space consumed by this dataset and all its descendents. This value is checked against the dataset's quota and reservation. The space used does not include the dataset's reservation, but does consider the reservation of any descendent datasets. The amount of space that a dataset consumes from its parent, as well as the amount of space that is freed if the dataset is recursively destroyed, is the greater of its space used and its reservation.

When snapshots are created, their space is initially shared between the snapshot and the file system, and possibly with previous snapshots. As the file system changes, space that was previously shared becomes unique to the snapshot, and counted in the snapshot's space used. Additionally, deleting snapshots can increase the amount of space unique to (and used by) other snapshots. For more information about snapshots and space issues, see Out of Space Behavior.

The amount of space used, available, or referenced does not take into account pending changes. Pending changes are generally accounted for within a few seconds. Committing a change to a disk using fsync(3C) or O_SYNC does not necessarily guarantee that the space usage information will be updated immediately.

5.2.2. Settable ZFS Native Properties

Settable native properties are properties whose values can be both retrieved and set. Settable native properties are set by using the zfs set command, as described in Setting ZFS Properties or by using the zfs create command as described in Creating a ZFS File System. With the exceptions of quotas and reservations, settable native properties are inherited. For more information about quotas and reservations, see ZFS Quotas and Reservations.

Some settable native properties are specific to a particular type of dataset. In such cases, the particular dataset type is mentioned in the description in ZFS Native Property Descriptions. If not specifically mentioned, a property applies to all dataset types: file systems, volumes, clones, and snapshots.

The settable properties are listed here and are described in ZFS Native Property Descriptions.

• aclinherit

  For a detailed description, see ACL Property Modes.

• aclmode

  For a detailed description, see ACL Property Modes.

• atime

• canmount

• casesensitivity

• checksum

• compression

• copies

• devices

• exec

• mountpoint

• nbmand

• normalization

• quota

• readonly

• recordsize

  For a detailed description, see The recordsize Property.

• refquota

• refreservation

• reservation

• sharenfs

• sharesmb

• setuid

• snapdir

• vscan

• utf8only

• volsize

  For a detailed description,see The volsize Property.

• volblocksize

• zoned

The canmount Property

If this property is set to no, the file system cannot be mounted by using the zfs mount or zfs mount -a commands. This property is similar to setting the mountpoint property to none, except that the dataset still has a normal mountpoint property that can be inherited. For example, you can set this property to no, establish inheritable properties for descendent file systems, but the file system itself is never mounted nor it is accessible to users. In this case, the parent file system with this property set to no is serving as a container so that you can set attributes on the container, but the container itself is never accessible.

In the following example, userpool is created and the canmount property is set to off. Mount points for descendent user file systems are set to one common mount point, /export/home. Properties that are set on the parent file system are inherited by descendent file systems, but the parent file system itself is never mounted.

# zpool create userpool mirror c0t5d0 c1t6d0
# zfs set canmount=off userpool
# zfs set mountpoint=/export/home userpool
# zfs set compression=on userpool
# zfs create userpool/user1
# zfs create userpool/user2
# zfs list -r userpool
NAME             USED  AVAIL  REFER  MOUNTPOINT
userpool         140K  8.24G  24.5K  /export/home
userpool/user1  24.5K  8.24G  24.5K  /export/home/user1
userpool/user2  24.5K  8.24G  24.5K  /export/home/user2

The casesensitivity Property

This property indicates whether the file name matching algorithm used by the file system should be casesensitive, caseinsensitive, or allow a combination of both styles of matching (mixed).

When a case-insensitive matching request is made of a mixed sensitivity file system, the behavior is generally the same as would be expected of a purely case-insensitive file system. The difference is that a mixed sensitivity file system might contain directories with multiple names that are unique from a case-sensitive perspective, but not unique from the case-insensitive perspective.

For example, a directory might contain files foo, Foo, and FOO. If a request is made to case-insensitively match any of the possible forms of foo, (for example foo, FOO, FoO, fOo, and so on) one of the three existing files is chosen as the match by the matching algorithm. Exactly which file the algorithm chooses as a match is not guaranteed, but what is guaranteed is that the same file is chosen as a match for any of the forms of foo. The file chosen as a case-insensitive match for foo, FOO, foO, Foo, and so on, is always the same, so long as the directory remains unchanged.

The utf8only, normalization, and casesensitivity properties are also new permissions that can be assigned to non-privileged users by using ZFS delegated administration. For more information, see Delegating ZFS Permissions.

The recordsize Property

Specifies a suggested block size for files in the file system.

This property is designed solely for use with database workloads that access files in fixed-size records. ZFS automatically adjust block sizes according to internal algorithms optimized for typical access patterns. For databases that create very large files but access the files in small random chunks, these algorithms may be suboptimal. Specifying a recordsize greater than or equal to the record size of the database can result in significant performance gains. Use of this property for general purpose file systems is strongly discouraged, and may adversely affect performance. The size specified must be a power of two greater than or equal to 512 and less than or equal to 128 Kbytes. Changing the file system's recordsize only affects files created afterward. Existing files are unaffected.

This property can also be referred to by its shortened column name, recsize.

The sharesmb Property

This property enabled sharing of ZFS file systems with the Solaris CIFS service, and identifies options to be used.

Because SMB shares requires a resource name, a unique resource name is constructed from the dataset name. The constructed name is a copy of the dataset name except that the characters in the dataset name, which would be illegal in the resource name, are replaced with underbar (_) characters. A pseudo property name is also supported that allows you to replace the dataset name with a specific name. The specific name is then used to replace the prefix dataset in the case of inheritance.

For example, if the dataset, data/home/john, is set to name=john, then data/home/john has a resource name of john. If a child dataset of data/home/john/backups exists, it has a resource name of john_backups. When the sharesmb property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously set to off, or if they were shared before the property was changed. If the new property is set to off, the file systems are unshared.

For examples of using the sharesmb property, see Sharing ZFS Files in a Solaris CIFS Environment.

The volsize Property

The logical size of the volume. By default, creating a volume establishes a reservation for the same amount. Any changes to volsize are reflected in an equivalent change to the reservation. These checks are used to prevent unexpected behavior for users. A volume that contains less space than it claims is available can result in undefined behavior or data corruption, depending on how the volume is used. These effects can also occur when the volume size is changed while it is in use, particularly when you shrink the size. Extreme care should be used when adjusting the volume size.

Though not recommended, you can create a sparse volume by specifying the -s flag to zfs create -V, or by changing the reservation once the volume has been created. A sparse volume is defined as a volume where the reservation is not equal to the volume size. For a sparse volume, changes to volsize are not reflected in the reservation.

For more information about using volumes, see ZFS Volumes.

5.2.3. ZFS User Properties

In addition to the standard native properties, ZFS supports arbitrary user properties. User properties have no effect on ZFS behavior, but you can use them to annotate datasets with information that is meaningful in your environment.

User property names must conform to the following characteristics:

• Contain a colon (':') character to distinguish them from native properties.

• Contain lowercase letters, numbers, and the following punctuation characters: ':', + ,'.', '_'.

• Maximum user property name is 256 characters.

The expected convention is that the property name is divided into the following two components but this namespace is not enforced by ZFS:

module:property

When making programmatic use of user properties, use a reversed DNS domain name for the module component of property names to reduce the chance that two independently-developed packages will use the same property name for different purposes. Property names that begin with "com.sun." are reserved for use by Sun Microsystems.

The values of user properties have the following characteristics:

• Arbitrary strings that are always inherited and are never validated.

• Maximum user property value is 1024 characters.

For example:

# zfs set dept:users=finance userpool/user1
# zfs set dept:users=general userpool/user2
# zfs set dept:users=itops userpool/user3

All of the commands that operate on properties, such as zfs list, zfs get, zfs set, and so on, can be used to manipulate both native properties and user properties.

For example:

zfs get -r dept:users userpool
NAME            PROPERTY    VALUE           SOURCE
userpool        dept:users  all             local
userpool/user1  dept:users  finance         local
userpool/user2  dept:users  general         local
userpool/user3  dept:users  itops           local

To clear a user property, use the zfs inherit command. For example:

# zfs inherit -r dept:users userpool

If the property is not defined in any parent dataset, it is removed entirely.

5.3. Querying ZFS File System Information

The zfs list command provides an extensible mechanism for viewing and querying dataset information. Both basic and complex queries are explained in this section.

5.3.1. Listing Basic ZFS Information

You can list basic dataset information by using the zfs list command with no options. This command displays the names of all datasets on the system including their used, available, referenced, and mountpoint properties. For more information about these properties, see Introducing ZFS Properties.

For example:

# zfs list
NAME                   USED  AVAIL  REFER  MOUNTPOINT
pool                   476K  16.5G    21K  /pool
pool/clone              18K  16.5G    18K  /pool/clone
pool/home              296K  16.5G    19K  /pool/home
pool/home/marks        277K  16.5G   277K  /pool/home/marks
pool/home/marks@snap      0      -   277K  -
pool/test               18K  16.5G    18K  /test

You can also use this command to display specific datasets by providing the dataset name on the command line. Additionally, use the -r option to recursively display all descendents of that dataset. For example:

# zfs list -r pool/home/marks
NAME                   USED  AVAIL  REFER  MOUNTPOINT
pool/home/marks        277K  16.5G   277K  /pool/home/marks
pool/home/marks@snap      0      -   277K  -

You use zfs list command with absolute pathnames for datasets, snapshots, and volumes. For example:

# zfs list /pool/home/marks
NAME              USED  AVAIL  REFER  MOUNTPOINT
pool/home/marks   277K  16.5G   277K  /pool/home/marks

The following example shows how to display tank/home/chua and all of its descendent datasets.

# zfs list -r tank/home/chua
NAME                        USED  AVAIL  REFER  MOUNTPOINT 
tank/home/chua		          26.0K  4.81G  10.0K  /tank/home/chua 
tank/home/chua/projects       16K  4.81G   9.0K  /tank/home/chua/projects
tank/home/chua/projects/fs1    8K  4.81G     8K  /tank/home/chua/projects/fs1 
tank/home/chua/projects/fs2    8K  4.81G     8K  /tank/home/chua/projects/fs2

For additional information about the zfs list command, see zfs(1M).

5.3.2. Creating Complex ZFS Queries

The zfs list output can be customized by using of the -o, -f, and -H options.

You can customize property value output by using the -o option and a comma-separated list of desired properties. Supply any dataset property as a valid value. For a list of all supported dataset properties, see Introducing ZFS Properties. In addition to the properties defined there, the -o option list can also contain the literal name to indicate that the output should include the name of the dataset.

The following example uses zfs list to display the dataset name, along with the sharenfs and mountpoint properties.

# zfs list -o name,sharenfs,mountpoint
NAME                   SHARENFS         MOUNTPOINT
tank                   off              /tank
tank/home              on               /tank/home
tank/home/ahrens       on               /tank/home/ahrens
tank/home/bonwick      on               /tank/home/bonwick
tank/home/chua         on               /tank/home/chua
tank/home/eschrock     on               legacy
tank/home/moore        on               /tank/home/moore
tank/home/tabriz       ro               /tank/home/tabriz

You can use the -t option to specify the types of datasets to display. The valid types are described in the following table.

The -t options takes a comma-separated list of the types of datasets to be displayed. The following example uses the -t and -o options simultaneously to show the name and used property for all file systems:

# zfs list -t filesystem -o name,used
NAME              USED
pool              476K
pool/clone         18K
pool/home         296K
pool/home/marks   277K
pool/test          18K

You can use the -H option to omit the zfs list header from the generated output. With the -H option, all white space is output as tabs. This option can be useful when you need parseable output, for example, when scripting. The following example shows the output generated from using the zfs list command with the -H option:

# zfs list -H -o name
pool
pool/clone
pool/home
pool/home/marks
pool/home/marks@snap
pool/test

5.4. Managing ZFS Properties

Dataset properties are managed through the zfs command's set, inherit, and get subcommands.

• Setting ZFS Properties

• Inheriting ZFS Properties

• Querying ZFS Properties

5.4.1. 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).

5.4.2. 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

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).

5.4.3. 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.

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

5.5. Mounting and Sharing ZFS File Systems

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

• Managing ZFS Mount Points

• Mounting ZFS File Systems

• Using Temporary Mount Properties

• Unmounting ZFS File Systems

• Sharing and Unsharing ZFS File Systems

5.5.1. Managing ZFS Mount Points

By default, all ZFS file systems are mounted by ZFS at boot by using SMF's svc://system/filesystem/local service. File systems are mounted under /path, where path is the name of the file system.

You can override the default mount point by setting the mountpoint property to a specific path by using the zfs set command. ZFS automatically creates this mount point, if needed, and automatically mounts this file system when the zfs mount -a command is invoked, without requiring you 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 its mountpoint property.

The mountpoint property can be set to none to prevent the file system from being mounted. In addition, the canmount property is available for determining whether a file system can be mounted. For more information about the canmount property, see The canmount Property.

If desired, file systems can also be explicitly managed through legacy mount interfaces by setting the mountpoint property to legacy by using zfs set. Doing so prevents ZFS from automatically mounting and managing this file system. Legacy tools including the mount and umount commands, and the /etc/vfstab file must be used instead. For more information about legacy mounts, see Legacy Mount Points.

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

• Automatic mount point behavior

• Legacy mount point behavior

Automatic Mount Points

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

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

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

Any dataset whose mountpoint property is not legacy is managed by ZFS. In the following example, a dataset is created whose mount point is automatically 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                        -

You can also explicitly set the mountpoint property as shown in the following example:

# 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 file system 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 file system due to it being active, an error is reported and a forced manual unmount is necessary.

Legacy Mount Points

You can manage ZFS file systems with legacy tools by setting the mountpoint property to legacy. Legacy file systems must be managed through the mount and umount commands and the /etc/vfstab file. ZFS does not automatically mount legacy file systems on boot, and the ZFS mount and umount command do not operate on datasets of this type. The following examples show how to set up and manage a ZFS dataset in legacy mode:

# zfs set mountpoint=legacy tank/home/eschrock
# mount -F zfs tank/home/eschrock /mnt

In addition, you must mount them by creating entries in the /etc/vfstab file. Otherwise, the system/filesystem/local service enters maintenance mode when the system boots.

To automatically mount a legacy file system on boot, you must add an entry to the /etc/vfstab file. The following example shows what the entry in the /etc/vfstab file might look like:

#device         device        mount           FS      fsck    mount   mount
#to mount       to fsck       point           type    pass    at boot options
#

tank/home/eschrock -		/mnt		   zfs		-		yes		-	

Note that the device to fsck and fsck pass entries are set to -. This syntax is because the fsck command is not applicable to ZFS file systems. For more information regarding data integrity and the lack of need for fsck in ZFS, see Transactional Semantics.

5.5.2. Mounting ZFS File Systems

ZFS automatically mounts file systems when file systems are created or when the system boots. Use of the zfs mount command is necessary only when changing mount options or explicitly mounting or unmounting file systems.

The zfs mount command with no arguments shows all currently mounted file systems that are managed by ZFS. Legacy managed mount points are not displayed. For example:

# zfs mount
tank                            /tank
tank/home                       /tank/home
tank/home/bonwick               /tank/home/bonwick
tank/ws                         /tank/ws

You can use the -a option to mount all ZFS managed file systems. Legacy managed file systems are not mounted. For example:

# zfs mount -a

By default, ZFS does not allow mounting on top of a nonempty directory. To force a mount on top of a nonempty directory, you must use the -O option. For example:

# zfs mount tank/home/lalt
cannot mount '/export/home/lalt': directory is not empty
use legacy mountpoint to allow this behavior, or use the -O flag
# zfs mount -O tank/home/lalt

Legacy mount points must be managed through legacy tools. An attempt to use ZFS tools results in an error. For example:

# zfs mount pool/home/billm
cannot mount 'pool/home/billm': legacy mountpoint
use mount(1M) to mount this filesystem
# mount -F zfs tank/home/billm

When a file system is mounted, it uses a set of mount options based on the property values associated with the dataset. The correlation between properties and mount options is as follows:

Property

Mount Options

devices

devices/nodevices

exec

exec/noexec

readonly

ro/rw

setuid

setuid/nosetuid

The mount option nosuid is an alias for nodevices,nosetuid.

You can use the NFSv4 mirror mount features to help you better manage NFS-mounted ZFS home directories. For a description of mirror mounts, see ZFS and File System Mirror Mounts.

5.5.3. Using Temporary Mount Properties

If any of the above options are set explicitly by using the -o option with the zfs mount command, the associated property value is temporarily overridden. These property values are reported as temporary by the zfs get command and revert back to their original settings when the file system is unmounted. If a property value is changed while the dataset is mounted, the change takes effect immediately, overriding any temporary setting.

In the following example, the read-only mount option is temporarily set on the tank/home/perrin file system:

# zfs mount -o ro tank/home/perrin

In this example, the file system is assumed to be unmounted. To temporarily change a property on a file system that is currently mounted, you must use the special remount option. In the following example, the atime property is temporarily changed to off for a file system that is currently mounted:

# zfs mount -o remount,noatime tank/home/perrin
# zfs get atime tank/home/perrin
NAME             PROPERTY      VALUE                      SOURCE
tank/home/perrin atime         off                        temporary

For more information about the zfs mount command, see zfs(1M).

5.5.4. Unmounting ZFS File Systems

You can unmount file systems by using the zfs unmount subcommand. The unmount command can take either the mount point or the file system name as arguments.

In the following example, a file system is unmounted by file system name:

# zfs unmount tank/home/tabriz

In the following example, the file system is unmounted by mount point:

# zfs unmount /export/home/tabriz

The unmount command fails if the file system is active or busy. To forceably unmount a file system, you can use the -f option. Be cautious when forceably unmounting a file system, if its contents are actively being used. Unpredictable application behavior can result.

# zfs unmount tank/home/eschrock
cannot unmount '/export/home/eschrock': Device busy
# zfs unmount -f tank/home/eschrock

To provide for backwards compatibility, the legacy umount command can be used to unmount ZFS file systems. For example:

# umount /export/home/bob

For more information about the zfs umount command, see zfs(1M).

5.5.5. Sharing and Unsharing ZFS File Systems

Similar to mount points, ZFS can automatically share file systems by using the sharenfs property. Using this method, you do not have to modify the /etc/dfs/dfstab file when a new file system is added. The sharenfs property is a comma-separated list of options to pass to the share command. The special value on is an alias for the default share options, which are read/write permissions for anyone. The special value off indicates that the file system is not managed by ZFS and can be shared through traditional means, such as the /etc/dfs/dfstab file. All file systems whose sharenfs property is not off are shared during boot.

Controlling Share Semantics

By default, all file systems are unshared. To share a new file system, use zfs set syntax similar to the following:

# zfs set sharenfs=on tank/home/eschrock

The property is inherited, and file systems are automatically shared on creation if their inherited property is not off. For example:

# zfs set sharenfs=on tank/home
# zfs create tank/home/bricker
# zfs create tank/home/tabriz
# zfs set sharenfs=ro tank/home/tabriz

Both tank/home/bricker and tank/home/tabriz are initially shared writable because they inherit the sharenfs property from tank/home. Once the property is set to ro (readonly), tank/home/tabriz is shared read-only regardless of the sharenfs property that is set for tank/home.

Unsharing ZFS File Systems

While most file systems are automatically shared and unshared during boot, creation, and destruction, file systems sometimes need to be explicitly unshared. To do so, use the zfs unshare command. For example:

# zfs unshare tank/home/tabriz

This command unshares the tank/home/tabriz file system. To unshare all ZFS file systems on the system, you need to use the -a option.

# zfs unshare -a

Sharing ZFS File Systems

Most of the time the automatic behavior of ZFS, sharing on boot and creation, is sufficient for normal operation. If, for some reason, you unshare a file system, you can share it again by using the zfs share command. For example:

# zfs share tank/home/tabriz

You can also share all ZFS file systems on the system by using the -a option.

# zfs share -a

Legacy Share Behavior

If the sharenfs property is off, then ZFS does not attempt to share or unshare the file system at any time. This setting enables you to administer through traditional means such as the /etc/dfs/dfstab file.

Unlike the traditional mount command, the traditional share and unshare commands can still function on ZFS file systems. As a result, you can manually share a file system with options that are different from the settings of the sharenfs property. This administrative model is discouraged. Choose to either manage NFS shares completely through ZFS or completely through the /etc/dfs/dfstab file. The ZFS administrative model is designed to be simpler and less work than the traditional model. However, in some cases, you might still want to control file system sharing behavior through the familiar model.

5.5.6. Sharing ZFS Files in a Solaris CIFS Environment

The sharesmb property is provided to share ZFS files by using the Solaris CIFS software product. When this property is set on a ZFS file system, these shares are visible to CIFS client systems. For more information about using the CIFS software product, see the System Administration Guide: Windows Interoperability.

For a detailed description of the sharesmb property, see The sharesmb Property.

# svcadm enable -r smb/server
svcadm: svc:/milestone/network depends on svc:/network/physical, which has multiple instances.
# svcs | grep smb
online         10:47:15 svc:/network/smb/server:default

# zpool create sandbox mirror c0t2d0 c0t4d0
# zfs create sandbox/fs1
# zfs set sharesmb=on sandbox/fs1

# sharemgr show -vp
default nfs=()
zfs nfs=()
    zfs/sandbox/fs1 smb=()
          sandbox_fs1=/sandbox/fs1

# zfs create sandbox/fs2
# zfs set sharesmb=name=myshare sandbox/fs2
# sharemgr show -vp
default nfs=()
zfs nfs=()
    zfs/sandbox/fs1 smb=()
          sandbox_fs1=/sandbox/fs1
    zfs/sandbox/fs2 smb=()
          myshare=/sandbox/fs2

# zfs create sandbox/fs2/fs2_sub1
# sharemgr show -vp
default nfs=()
zfs nfs=()
    zfs/sandbox/fs1 smb=()
          sandbox_fs1=/sandbox/fs1
    zfs/sandbox/fs2 smb=()
          myshare=/sandbox/fs2
          myshare_fs2_sub1=/sandbox/fs2/fs2_sub1

# zfs set sharesmb=off sandbox/fs2
# sharemgr show -vp
default nfs=()
zfs nfs=()
    zfs/sandbox/fs1 smb=()
          sandbox_fs1=/sandbox/fs1

In this example, the sharesmb property is set on the pool's top-level file system. The descendent file systems are automatically shared.

# zpool create sandbox mirror c0t2d0 c0t4d0
# zfs set sharesmb=on sandbox
# zfs create sandbox/fs1
# zfs create sandbox/fs2

The top-level file system has a resource name of sandbox, but the descendents have their dataset name appended to the resource name.

# sharemgr show -vp
default nfs=()
zfs nfs=()
    zfs/sandbox smb=()
          sandbox=/sandbox
          sandbox_fs1=/sandbox/fs1       smb=()
          sandbox_fs2=/sandbox/fs2       smb=()

5.6. ZFS Quotas and Reservations

ZFS supports quotas and reservations at the file system level. You can use the quota property to set a limit on the amount of space a file system can use. In addition, you can use the reservation property to guarantee that some amount of space is available to a file system. Both properties apply to the dataset they are set on and all descendents of that dataset.

That is, if a quota is set on the tank/home dataset, the total amount of space used by tank/home and all of its descendents cannot exceed the quota. Similarly, if tank/home is given a reservation, tank/home and all of its descendents draw from that reservation. The amount of space used by a dataset and all of its descendents is reported by the used property.

In addition to the quota and reservation property, the refquota and refreservation properties are available to manage file system space without accounting for space consumed by descendents, such as snapshots and clones.

Consider the following points to determine which quota and reservations features might better manage your file systems:

• The quota and reservation properties are convenient for managing space consumed by datasets.

• The refquota and refreservation properties are appropriate for managing space consumed by datasets and snapshots.

• Setting refquota or refreservation higher than quota or reservation have no effect. If you set the quota or refquota properties, operations that try to exceed either value fail. It is possible to a exceed a quota that is greater than refquota. If some snapshot blocks are dirtied, you might actually exceed the quota before you exceed the refquota.

For more information, see the examples below.

5.6.1. Setting Quotas on ZFS File Systems

ZFS quotas can be set and displayed by using the zfs set and zfs get commands. In the following example, a quota of 10 Gbytes is set on tank/home/bonwick.

# zfs set quota=10G tank/home/bonwick
# zfs get quota tank/home/bonwick
NAME              PROPERTY      VALUE                      SOURCE
tank/home/bonwick quota         10.0G                      local

ZFS quotas also impact the output of the zfs list and df commands. For example:

# zfs list
NAME                   USED  AVAIL  REFER  MOUNTPOINT
tank/home             16.5K  33.5G  8.50K  /export/home
tank/home/bonwick     15.0K  10.0G  8.50K  /export/home/bonwick
tank/home/bonwick/ws  6.50K  10.0G  8.50K  /export/home/bonwick/ws
# df -h /export/home/bonwick
Filesystem             size   used  avail capacity  Mounted on
tank/home/bonwick       10G     8K    10G     1%    /export/home/bonwick

Note that although tank/home has 33.5 Gbytes of space available, tank/home/bonwick and tank/home/bonwick/ws only have 10 Gbytes of space available, due to the quota on tank/home/bonwick.

You cannot set a quota to an amount less than is currently being used by a dataset. For example:

# zfs set quota=10K tank/home/bonwick
cannot set quota for 'tank/home/bonwick': size is less than current used or 
reserved space

You can set a refquota on a dataset that limits the amount of space that the dataset can consume. This hard limit does not include space that is consumed by snapshots and clones. For example:

# zfs set refquota=10g students/studentA
# zfs list
NAME                USED  AVAIL  REFER  MOUNTPOINT
profs               106K  33.2G    18K  /profs
students           57.7M  33.2G    19K  /students
students/studentA  57.5M  9.94G  57.5M  /students/studentA
# zfs snapshot students/studentA@today
# zfs list
NAME                      USED  AVAIL  REFER  MOUNTPOINT
profs                     106K  33.2G    18K  /profs
students                 57.7M  33.2G    19K  /students
students/studentA        57.5M  9.94G  57.5M  /students/studentA
students/studentA@today      0      -  57.5M  -

For additional convenience, you can set another quota on a dataset to help manage the space that is consumed by snapshots. For example:

# zfs set quota=20g students/studentA
# zfs list
NAME                      USED  AVAIL  REFER  MOUNTPOINT
profs                     106K  33.2G    18K  /profs
students                 57.7M  33.2G    19K  /students
students/studentA        57.5M  9.94G  57.5M  /students/studentA
students/studentA@today      0      -  57.5M  -

In this scenario, studentA can bump into the refquota (10 Gbytes) hard limit and remove files to recover even if snapshots exist.

In the above example, the smaller of the two quotas (10 Gbytes versus 20 Gbytes) is displayed in the zfs list output. To see the value of both quotas, use the zfs get command. For example:

# zfs get refquota,quota students/studentA
NAME               PROPERTY  VALUE              SOURCE
students/studentA  refquota  10G                local
students/studentA  quota     20G                local

5.6.2. Setting Reservations on ZFS File Systems

A ZFS reservation is an allocation of space from the pool that is guaranteed to be available to a dataset. As such, you cannot reserve space for a dataset if that space is not currently available in the pool. The total amount of all outstanding unconsumed reservations cannot exceed the amount of unused space in the pool. ZFS reservations can be set and displayed by using the zfs set and zfs get commands. For example:

# zfs set reservation=5G tank/home/moore
# zfs get reservation tank/home/moore
NAME             PROPERTY      VALUE                      SOURCE
tank/home/moore  reservation   5.00G                      local

ZFS reservations can affect the output of the zfs list command. For example:

# zfs list
NAME                   USED  AVAIL  REFER  MOUNTPOINT
tank/home             5.00G  33.5G  8.50K  /export/home
tank/home/moore       15.0K  10.0G  8.50K  /export/home/moore

Note that tank/home is using 5 Gbytes of space, although the total amount of space referred to by tank/home and its descendents is much less than 5 Gbytes. The used space reflects the space reserved for tank/home/moore. Reservations are considered in the used space of the parent dataset and do count against its quota, reservation, or both.

# zfs set quota=5G pool/filesystem
# zfs set reservation=10G pool/filesystem/user1
cannot set reservation for 'pool/filesystem/user1': size is greater than 
available space

A dataset can use more space than its reservation, as long as space is available in the pool that is unreserved and the dataset's current usage is below its quota. A dataset cannot consume space that has been reserved for another dataset.

Reservations are not cumulative. That is, a second invocation of zfs set to set a reservation does not add its reservation to the existing reservation. Rather, the second reservation replaces the first reservation.

# zfs set reservation=10G tank/home/moore
# zfs set reservation=5G tank/home/moore
# zfs get reservation tank/home/moore
NAME             PROPERTY      VALUE                      SOURCE
tank/home/moore  reservation   5.00G                      local

You can set a refreservation to guarantee space for a dataset that does not include space consumed by snapshots and clones. The refreservation reservation is accounted for in the parent datasets' space used, and counts against the parent datasets' quotas and reservations. For example:

# zfs set refreservation=10g profs/prof1
# zfs list
NAME                      USED  AVAIL  REFER  MOUNTPOINT
profs                    10.0G  23.2G    19K  /profs
profs/prof1                10G  33.2G    18K  /profs/prof1

You can also set a reservation on the same dataset to guarantee dataset space and snapshot space. For example:

# zfs set reservation=20g profs/prof1
# zfs list
NAME                      USED  AVAIL  REFER  MOUNTPOINT
profs                    20.0G  13.2G    19K  /profs
profs/prof1                10G  33.2G    18K  /profs/prof1

Regular reservations are accounted for in the parent's used space.

In the above example, the smaller of the two quotas (10 Gbytes versus 20 Gbytes) is displayed in the zfs list output. To see the value of both quotas, use the zfs get command. For example:

# zfs get reservation,refreserv profs/prof1
NAME         PROPERTY        VALUE        SOURCE
profs/prof1  reservation     20G          local
profs/prof1  refreservation  10G          local

If refreservation is set, a snapshot is only allowed if enough free pool space exists outside of this reservation to accommodate the current number of referenced bytes in the dataset.