'\" t

.\"

.\" CDDL HEADER START

.\"

.\" The contents of this file are subject to the terms of the

.\" Common Development and Distribution License (the "License").

.\" You may not use this file except in compliance with the License.

.\"

.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

.\" or http://www.opensolaris.org/os/licensing.

.\" See the License for the specific language governing permissions

.\" and limitations under the License.

.\"

.\" When distributing Covered Code, include this CDDL HEADER in each

.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.

.\" If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying

.\" information: Portions Copyright [yyyy] [name of copyright owner]

.\"

.\" CDDL HEADER END

.\"

.\"

.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.

.\" Copyright 2011 Joshua M. Clulow <[email protected]>

.\" Copyright (c) 2012 by Delphix. All rights reserved.

.\" Copyright (c) 2012, Joyent, Inc. All rights reserved.

.\" Copyright 2012 Nexenta Systems, Inc. All Rights Reserved.

.\"

.SH NAME

zfs \- configures ZFS file systems

.SH SYNOPSIS

.LP

.nf

\fBzfs\fR [\fB-?\fR]

.fi

.LP

.nf

\fBzfs\fR \fBcreate\fR [\fB-p\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fIfilesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBcreate\fR [\fB-ps\fR] [\fB-b\fR \fIblocksize\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fB-V\fR \fIsize\fR \fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBdestroy\fR [\fB-fnpRrv\fR] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBdestroy\fR [\fB-dnpRrv\fR] \fIfilesystem\fR|\fIvolume\fR@\fIsnap\fR[%\fIsnap\fR][,...]

.fi

.LP

.nf

\fBzfs\fR \fBsnapshot\fR [\fB-r\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR]...

      \fIfilesystem@snapname\fR|\fIvolume@snapname\fR...

.fi

.LP

.nf

\fBzfs\fR \fBrollback\fR [\fB-rRf\fR] \fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBclone\fR [\fB-p\fR] [\fB-o\fR \fIproperty\fR=\fIvalue\fR] ... \fIsnapshot\fR \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBpromote\fR \fIclone-filesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBrename\fR [\fB-f\fR] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR

     \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBrename\fR [\fB-fp\fR] \fIfilesystem\fR|\fIvolume\fR \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBrename\fR \fB-r\fR \fIsnapshot\fR \fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBlist\fR [\fB-r\fR|\fB-d\fR \fIdepth\fR][\fB-H\fR][\fB-o\fR \fIproperty\fR[,...]] [\fB-t\fR \fItype\fR[,...]]

     [\fB-s\fR \fIproperty\fR] ... [\fB-S\fR \fIproperty\fR] ... [\fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR] ...

.fi

.LP

.nf

\fBzfs\fR \fBset\fR \fIproperty\fR=\fIvalue\fR \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR ...

.fi

.LP

.nf

\fBzfs\fR \fBget\fR [\fB-r\fR|\fB-d\fR \fIdepth\fR][\fB-Hp\fR][\fB-o\fR \fIfield\fR[,...]] [\fB-t\fR \fItype\fR[,...]] 

    [\fB-s\fR \fIsource\fR[,...]] "\fIall\fR" | \fIproperty\fR[,...] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR ...

.fi

.LP

.nf

\fBzfs\fR \fBinherit\fR [\fB-r\fR] \fIproperty\fR \fIfilesystem\fR|\fIvolume|snapshot\fR ...

.fi

.LP

.nf

\fBzfs\fR \fBupgrade\fR [\fB-v\fR]

.fi

.LP

.nf

\fBzfs\fR \fBupgrade\fR [\fB-r\fR] [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIfilesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBuserspace\fR [\fB-Hinp\fR] [\fB-o\fR \fIfield\fR[,...]] [\fB-s\fR \fIfield\fR] ...

    [\fB-S\fR \fIfield\fR] ... [\fB-t\fR \fItype\fR[,...]] \fIfilesystem\fR|\fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBgroupspace\fR [\fB-Hinp\fR] [\fB-o\fR \fIfield\fR[,...]] [\fB-s\fR \fIfield\fR] ...

    [\fB-S\fR \fIfield\fR] ... [\fB-t\fR \fItype\fR[,...]] \fIfilesystem\fR|\fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBmount\fR

.fi

.LP

.nf

\fBzfs\fR \fBmount\fR [\fB-vO\fR] [\fB-o \fIoptions\fR\fR] \fB-a\fR | \fIfilesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBunmount\fR [\fB-f\fR] \fB-a\fR | \fIfilesystem\fR|\fImountpoint\fR

.fi

.LP

.nf

\fBzfs\fR \fBshare\fR \fB-a\fR | \fIfilesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBunshare\fR \fB-a\fR \fIfilesystem\fR|\fImountpoint\fR

.fi

.LP

.nf

\fBzfs\fR \fBsend\fR [\fB-DnPpRrv\fR] [\fB-\fR[\fBiI\fR] \fIsnapshot\fR] \fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBreceive\fR [\fB-vnFu\fR] \fIfilesystem\fR|\fIvolume\fR|\fIsnapshot\fR

.fi

.LP

.nf

\fBzfs\fR \fBreceive\fR [\fB-vnFu\fR] [\fB-d\fR|\fB-e\fR] \fIfilesystem\fR

.fi

.LP

.nf

\fBzfs\fR \fBallow\fR \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBallow\fR [\fB-ldug\fR] "\fIeveryone\fR"|\fIuser\fR|\fIgroup\fR[,...] \fIperm\fR|\fI@setname\fR[,...]

     \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBallow\fR [\fB-ld\fR] \fB-e\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBallow\fR \fB-c\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBallow\fR \fB-s\fR @\fIsetname\fR \fIperm\fR|@\fIsetname\fR[,...] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBunallow\fR [\fB-rldug\fR] "\fIeveryone\fR"|\fIuser\fR|\fIgroup\fR[,...] [\fIperm\fR|@\fIsetname\fR[,... ]]

     \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBunallow\fR [\fB-rld\fR] \fB-e\fR [\fIperm\fR|@\fIsetname\fR[,... ]] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBunallow\fR [\fB-r\fR] \fB-c\fR [\fIperm\fR|@\fIsetname\fR[ ... ]] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBunallow\fR [\fB-r\fR] \fB-s\fR @\fIsetname\fR [\fIperm\fR|@\fIsetname\fR[,... ]] \fIfilesystem\fR|\fIvolume\fR

.fi

.LP

.nf

\fBzfs\fR \fBhold\fR [\fB-r\fR] \fItag\fR \fIsnapshot\fR...

.fi

.LP

.nf

\fBzfs\fR \fBholds\fR [\fB-r\fR] \fIsnapshot\fR...

.fi

.LP

.nf

\fBzfs\fR \fBrelease\fR [\fB-r\fR] \fItag\fR \fIsnapshot\fR...

.fi

.LP

.nf

\fBzfs\fR \fBdiff\fR [\fB-FHt\fR] \fIsnapshot\fR \fIsnapshot|filesystem\fR

.SH DESCRIPTION

.sp

.LP

The \fBzfs\fR command configures \fBZFS\fR datasets within a \fBZFS\fR storage

pool, as described in \fBzpool\fR(1M). A dataset is identified by a unique path

within the \fBZFS\fR namespace. For example:

.sp

.in +2

.nf

pool/{filesystem,volume,snapshot}

.fi

.in -2

.sp

.sp

.LP

where the maximum length of a dataset name is \fBMAXNAMELEN\fR (256 bytes).

.sp

.LP

A dataset can be one of the following:

.sp

.ne 2

.na

\fB\fIfile system\fR\fR

.ad

.sp .6

.RS 4n

A \fBZFS\fR dataset of type \fBfilesystem\fR can be mounted within the standard

system namespace and behaves like other file systems. While \fBZFS\fR file

systems are designed to be \fBPOSIX\fR compliant, known issues exist that

prevent compliance in some cases. Applications that depend on standards

conformance might fail due to nonstandard behavior when checking file system

free space.

.RE

.sp

.ne 2

.na

\fB\fIvolume\fR\fR

.ad

.sp .6

.RS 4n

A logical volume exported as a raw or block device. This type of dataset should

only be used under special circumstances. File systems are typically used in

most environments.

.RE

.sp

.ne 2

.na

\fB\fIsnapshot\fR\fR

.ad

.sp .6

.RS 4n

A read-only version of a file system or volume at a given point in time. It is

specified as \fIfilesystem@name\fR or \fIvolume@name\fR.

.RE

.SS "ZFS File System Hierarchy"

.sp

.LP

A \fBZFS\fR storage pool is a logical collection of devices that provide space

for datasets. A storage pool is also the root of the \fBZFS\fR file system

hierarchy.

.sp

.LP

The root of the pool can be accessed as a file system, such as mounting and

unmounting, taking snapshots, and setting properties. The physical storage

characteristics, however, are managed by the \fBzpool\fR(1M) command.

.sp

.LP

See \fBzpool\fR(1M) for more information on creating and administering pools.

.SS "Snapshots"

.sp

.LP

A snapshot is a read-only copy of a file system or volume. Snapshots can be

created extremely quickly, and initially consume no additional space within the

pool. As data within the active dataset changes, the snapshot consumes more

data than would otherwise be shared with the active dataset.

.sp

.LP

Snapshots can have arbitrary names. Snapshots of volumes can be cloned or

rolled back, but cannot be accessed independently.

.sp

.LP

File system snapshots can be accessed under the \fB\&.zfs/snapshot\fR directory

in the root of the file system. Snapshots are automatically mounted on demand

and may be unmounted at regular intervals. The visibility of the \fB\&.zfs\fR

directory can be controlled by the \fBsnapdir\fR property.

.SS "Clones"

.sp

.LP

A clone is a writable volume or file system whose initial contents are the same

as another dataset. As with snapshots, creating a clone is nearly

instantaneous, and initially consumes no additional space.

.sp

.LP

Clones can only be created from a snapshot. When a snapshot is cloned, it

creates an implicit dependency between the parent and child. Even though the

clone is created somewhere else in the dataset hierarchy, the original snapshot

cannot be destroyed as long as a clone exists. The \fBorigin\fR property

exposes this dependency, and the \fBdestroy\fR command lists any such

dependencies, if they exist.

.sp

.LP

The clone parent-child dependency relationship can be reversed by using the

\fBpromote\fR subcommand. This causes the "origin" file system to become a

clone of the specified file system, which makes it possible to destroy the file

system that the clone was created from.

.SS "Mount Points"

.sp

.LP

Creating a \fBZFS\fR file system is a simple operation, so the number of file

systems per system is likely to be numerous. To cope with this, \fBZFS\fR

automatically manages mounting and unmounting file systems without the need to

edit the \fB/etc/vfstab\fR file. All automatically managed file systems are

mounted by \fBZFS\fR at boot time.

.sp

.LP

By default, file systems are mounted under \fB/\fIpath\fR\fR, where \fIpath\fR

is the name of the file system in the \fBZFS\fR namespace. Directories are

created and destroyed as needed.

.sp

.LP

A file system can also have a mount point set in the \fBmountpoint\fR property.

This directory is created as needed, and \fBZFS\fR automatically mounts the

file system when the \fBzfs mount -a\fR command is invoked (without editing

\fB/etc/vfstab\fR). The \fBmountpoint\fR property can be inherited, so if

\fBpool/home\fR has a mount point of \fB/export/stuff\fR, then

\fBpool/home/user\fR automatically inherits a mount point of

\fB/export/stuff/user\fR.

.sp

.LP

A file system \fBmountpoint\fR property of \fBnone\fR prevents the file system

from being mounted.

.sp

.LP

If needed, \fBZFS\fR file systems can also be managed with traditional tools

(\fBmount\fR, \fBumount\fR, \fB/etc/vfstab\fR). If a file system's mount point

is set to \fBlegacy\fR, \fBZFS\fR makes no attempt to manage the file system,

and the administrator is responsible for mounting and unmounting the file

system.

.SS "Zones"

.sp

.LP

A \fBZFS\fR file system can be added to a non-global zone by using the

\fBzonecfg\fR \fBadd fs\fR subcommand. A \fBZFS\fR file system that is added to

a non-global zone must have its \fBmountpoint\fR property set to \fBlegacy\fR.

.sp

.LP

The physical properties of an added file system are controlled by the global

administrator. However, the zone administrator can create, modify, or destroy

files within the added file system, depending on how the file system is

mounted.

.sp

.LP

A dataset can also be delegated to a non-global zone by using the \fBzonecfg\fR

\fBadd dataset\fR subcommand. You cannot delegate a dataset to one zone and the

children of the same dataset to another zone. The zone administrator can change

properties of the dataset or any of its children. However, the \fBquota\fR

property is controlled by the global administrator.

.sp

.LP

A \fBZFS\fR volume can be added as a device to a non-global zone by using the

\fBzonecfg\fR \fBadd device\fR subcommand. However, its physical properties can

be modified only by the global administrator.

.sp

.LP

For more information about \fBzonecfg\fR syntax, see \fBzonecfg\fR(1M).

.sp

.LP

After a dataset is delegated to a non-global zone, the \fBzoned\fR property is

automatically set. A zoned file system cannot be mounted in the global zone,

since the zone administrator might have to set the mount point to an

unacceptable value.

.sp

.LP

The global administrator can forcibly clear the \fBzoned\fR property, though

this should be done with extreme care. The global administrator should verify

that all the mount points are acceptable before clearing the property.

.SS "Native Properties"

.sp

.LP

Properties are divided into two types, native properties and user-defined (or

"user") properties. Native properties either export internal statistics or

control \fBZFS\fR behavior. In addition, native properties are either editable

or read-only. User properties have no effect on \fBZFS\fR behavior, but you can

use them to annotate datasets in a way that is meaningful in your environment.

For more information about user properties, see the "User Properties" section,

below.

.sp

.LP

Every dataset has a set of properties that export statistics about the dataset

as well as control various behaviors. Properties are inherited from the parent

unless overridden by the child. Some properties apply only to certain types of

datasets (file systems, volumes, or snapshots).

.sp

.LP

The values of numeric properties can be specified using human-readable suffixes

(for example, \fBk\fR, \fBKB\fR, \fBM\fR, \fBGb\fR, and so forth, up to \fBZ\fR

for zettabyte). The following are all valid (and equal) specifications:

.sp

.in +2

.nf

1536M, 1.5g, 1.50GB

.fi

.in -2

.sp

.sp

.LP

The values of non-numeric properties are case sensitive and must be lowercase,

except for \fBmountpoint\fR, \fBsharenfs\fR, and \fBsharesmb\fR.

.sp

.LP

The following native properties consist of read-only statistics about the

dataset. These properties can be neither set, nor inherited. Native properties

apply to all dataset types unless otherwise noted.

.sp

.ne 2

.na

\fB\fBavailable\fR\fR

.ad

.sp .6

.RS 4n

The amount of space available to the dataset and all its children, assuming

that there is no other activity in the pool. Because space is shared within a

pool, availability can be limited by any number of factors, including physical

pool size, quotas, reservations, or other datasets within the pool.

.sp

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

\fBavail\fR.

.RE

.sp

.ne 2

.na

\fB\fBcompressratio\fR\fR

.ad

.sp .6

.RS 4n

For non-snapshots, the compression ratio achieved for the \fBused\fR

space of this dataset, expressed as a multiplier.  The \fBused\fR

property includes descendant datasets, and, for clones, does not include

the space shared with the origin snapshot.  For snapshots, the

\fBcompressratio\fR is the same as the \fBrefcompressratio\fR property.

Compression can be turned on by running: \fBzfs set compression=on

\fIdataset\fR\fR. The default value is \fBoff\fR.

.RE

.sp

.ne 2

.na

\fB\fBcreation\fR\fR

.ad

.sp .6

.RS 4n

The time this dataset was created.

.RE

.sp

.ne 2

.na

\fB\fBclones\fR\fR

.ad

.sp .6

.RS 4n

For snapshots, this property is a comma-separated list of filesystems or

volumes which are clones of this snapshot.  The clones' \fBorigin\fR property

is this snapshot.  If the \fBclones\fR property is not empty, then this

snapshot can not be destroyed (even with the \fB-r\fR or \fB-f\fR options).

.RE

.sp

.ne 2

.na

\fB\fBdefer_destroy\fR\fR