Managing Filesystems

This chapter provides detailed information about managing ZFS filesystems. Included are such concepts as hierarchical filesystem layout, property inheritance, and automatic mount point management and share interactions.

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

ZFS filesystems are administered via the zfs command. The zfs(1M) command provides a set of subcommands which perform specific operations on filesystems. The following sections of this document describe these subcommands in detail. Snapshots, volumes, and clones are also managed through the use of zfs(1M), but will only be covered briefly in this section. For detailed information about snapshots and clones, see Chapter 6, ZFS Snapshots and Clones. For detailed information about volumes, see 8.1 Emulated Volumes.

Note: The term dataset is used in this section as a generic term to refer to a filesystem, snapshot, clone, or volume.

The following sections are provided in this chapter.

• 5.1 Creating and Destroying Filesystems

• 5.2 ZFS Properties

• 5.3 Querying Filesystem Information

• 5.4 Managing Properties

• 5.5 Mounting and Sharing File Systems

• 5.6 Quotas and Reservations

• 5.7 Backing Up and Restoring ZFS Data

5.1 Creating and Destroying Filesystems

Filesystems can be created and destroyed by using the zfs create and zfs destroy commands.

5.1.1 Creating a Filesystem

Filesystems are created by using the zfs create command. When creating a filesystem, the create subcommand takes a single argument: the name of the filesystem to create. The filesystem 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 filesystem names in the path identify the location in the hierarchy where the new filesystem should be created. All the intermediate filesystem names must already exist in the pool. The last name in the path, identifies the name of the filesystem to be created. The filesystem name must satisfy the naming conventions defined in 1.3 ZFS Component Naming Conventions.

The following example creates a filesystem named bonwick at tank/home.

# zfs create tank/home/bonwick

Upon successful creation, ZFS automatically mounts the newly created filesystem. By default, filesystems are mounted as /dataset, using the path provided for the filesystem name in the create subcommand. In the above example, the newly created bonwick filesystem would be mounted at /tank/home/bonwick. For more information on auto-managed mount points, see 5.5.1 Managing Mount Points.

5.1.2 Destroying a Filesystem

To destroy a filesystem, use the zfs destroy command. The destroyed filesystem is automatically unmounted and unshared. For more information on auto-managed mounts or auto-managed shares, see 5.5.1.1 Automatic Mount Points. The following example destroys the tabriz filesystem.

# zfs destroy tank/home/tabriz

If the filesystem to be destroyed is busy (and so cannot be unmounted), the zfs destroy command will not succeed. To force the destruction of an active filesystem, the -f option must be used. This option should be used with caution as it can unmount, unshare, and destroy active filesystems, causing unexpected application behavior.

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

# zfs destroy -f tank/home/ahrens

Thezfs destroy command also fails if a filesystem has children. To force a recursive destruction of a filesystem and all its descendants, the -r option must be used. Note that a recursive destroy also destroys snapshots. Great care should be taken when using this option.

# 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 filesystem to be destroyed has indirect dependants, even the recursive destroy command described above fails. To force the destruction of all dependants, including cloned filesystems outside the target hierarchy, the -R option must be used. This option should be used with extreme caution.

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

# zfs destroy -R tank/home/schrock

For more information about snapshots and clones, see Chapter 6, ZFS Snapshots and Clones.

5.1.3 Renaming a Filesystem

Filesystems can be renamed by using the zfs rename command. A rename can change the name of a filesystem and/or it can relocate the filesystem to a new location within the ZFS hierarchy. The first example below uses the rename subcommand to do a simple rename of a filesystem.

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

The example above renames the kustarz filesystem to kustarz_old. The next example shows how to use zfs rename to relocate a filesystem.

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

In the above example, the maybee filesystem was relocated from tank/home to tank/ws. When relocating through rename, the new location must be within the same pool and it must have enough space to hold this new filesystem. If the new location does not have enough space, possibly because it has reached its quota (see 5.6 Quotas and Reservations for more information), the rename will fail.

The rename operation attempts an unmount/remount sequence for the filesystem and any descendant filesystems. The rename fails if it is unable to unmount an active filesystem. If this occurs, manual intervention is needed to force unmount the filesystem(s).

For information about renaming snapshots, see 6.1.1.1 Renaming ZFS Snapshots.

5.2 ZFS Properties

Properties are the main mechanism used to control the behavior of filesystems, volumes, snapshots, and clones. Unless explicitly called out, the properties defined in the section apply to all the dataset types.

Properties are either readonly statistics, or settable properties. Most settable properties are also inheritable, where an inheritable property is one that, when set on a parent, is propagated down to all descendants.

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