| .\" |
| .\" 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 <josh@sysmgr.org> |
| .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. |
| .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. |
| .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. |
| .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. |
| .\" Copyright (c) 2014 Integros [integros.com] |
| .\" Copyright 2019 Richard Laager. All rights reserved. |
| .\" Copyright 2018 Nexenta Systems, Inc. |
| .\" Copyright 2018 Joyent, Inc. |
| .\" |
| .Dd April 30, 2019 |
| .Dt ZFS 8 SMM |
| .Os Linux |
| .Sh NAME |
| .Nm zfs |
| .Nd configures ZFS file systems |
| .Sh SYNOPSIS |
| .Nm |
| .Fl ?V |
| .Nm |
| .Cm create |
| .Op Fl p |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem |
| .Nm |
| .Cm create |
| .Op Fl ps |
| .Op Fl b Ar blocksize |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Fl V Ar size Ar volume |
| .Nm |
| .Cm destroy |
| .Op Fl Rfnprv |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm destroy |
| .Op Fl Rdnprv |
| .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns |
| .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... |
| .Nm |
| .Cm destroy |
| .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark |
| .Nm |
| .Cm snapshot |
| .Op Fl r |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... |
| .Nm |
| .Cm rollback |
| .Op Fl Rfr |
| .Ar snapshot |
| .Nm |
| .Cm clone |
| .Op Fl p |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar snapshot Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm promote |
| .Ar clone-filesystem |
| .Nm |
| .Cm rename |
| .Op Fl f |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Nm |
| .Cm rename |
| .Op Fl fp |
| .Ar filesystem Ns | Ns Ar volume |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm rename |
| .Fl r |
| .Ar snapshot Ar snapshot |
| .Nm |
| .Cm list |
| .Op Fl r Ns | Ns Fl d Ar depth |
| .Op Fl Hp |
| .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc |
| .Oo Fl s Ar property Oc Ns ... |
| .Oo Fl S Ar property Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... |
| .Nm |
| .Cm set |
| .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... |
| .Nm |
| .Cm get |
| .Op Fl r Ns | Ns Fl d Ar depth |
| .Op Fl Hp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... |
| .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... |
| .Nm |
| .Cm inherit |
| .Op Fl rS |
| .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... |
| .Nm |
| .Cm upgrade |
| .Nm |
| .Cm upgrade |
| .Fl v |
| .Nm |
| .Cm upgrade |
| .Op Fl r |
| .Op Fl V Ar version |
| .Fl a | Ar filesystem |
| .Nm |
| .Cm userspace |
| .Op Fl Hinp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Nm |
| .Cm groupspace |
| .Op Fl Hinp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Nm |
| .Cm projectspace |
| .Op Fl Hp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Nm |
| .Cm project |
| .Oo Fl d Ns | Ns Fl r Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Nm |
| .Cm project |
| .Fl C |
| .Oo Fl kr Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Nm |
| .Cm project |
| .Fl c |
| .Oo Fl 0 Ns Oc |
| .Oo Fl d Ns | Ns Fl r Ns Oc |
| .Op Fl p Ar id |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Nm |
| .Cm project |
| .Op Fl p Ar id |
| .Oo Fl rs Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Nm |
| .Cm mount |
| .Nm |
| .Cm mount |
| .Op Fl Olv |
| .Op Fl o Ar options |
| .Fl a | Ar filesystem |
| .Nm |
| .Cm unmount |
| .Op Fl f |
| .Fl a | Ar filesystem Ns | Ns Ar mountpoint |
| .Nm |
| .Cm share |
| .Fl a | Ar filesystem |
| .Nm |
| .Cm unshare |
| .Fl a | Ar filesystem Ns | Ns Ar mountpoint |
| .Nm |
| .Cm bookmark |
| .Ar snapshot bookmark |
| .Nm |
| .Cm send |
| .Op Fl DLPRbcehnpvw |
| .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot |
| .Ar snapshot |
| .Nm |
| .Cm send |
| .Op Fl LPcenvw |
| .Op Fl i Ar snapshot Ns | Ns Ar bookmark |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Nm |
| .Cm send |
| .Op Fl Penv |
| .Fl t Ar receive_resume_token |
| .Nm |
| .Cm receive |
| .Op Fl Fhnsuv |
| .Op Fl o Sy origin Ns = Ns Ar snapshot |
| .Op Fl o Ar property Ns = Ns Ar value |
| .Op Fl x Ar property |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Nm |
| .Cm receive |
| .Op Fl Fhnsuv |
| .Op Fl d Ns | Ns Fl e |
| .Op Fl o Sy origin Ns = Ns Ar snapshot |
| .Op Fl o Ar property Ns = Ns Ar value |
| .Op Fl x Ar property |
| .Ar filesystem |
| .Nm |
| .Cm receive |
| .Fl A |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm allow |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm allow |
| .Op Fl dglu |
| .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm allow |
| .Op Fl dl |
| .Fl e Ns | Ns Sy everyone |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm allow |
| .Fl c |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm allow |
| .Fl s No @ Ns Ar setname |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm unallow |
| .Op Fl dglru |
| .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm unallow |
| .Op Fl dlr |
| .Fl e Ns | Ns Sy everyone |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm unallow |
| .Op Fl r |
| .Fl c |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm unallow |
| .Op Fl r |
| .Fl s @ Ns Ar setname |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Nm |
| .Cm hold |
| .Op Fl r |
| .Ar tag Ar snapshot Ns ... |
| .Nm |
| .Cm holds |
| .Op Fl rH |
| .Ar snapshot Ns ... |
| .Nm |
| .Cm release |
| .Op Fl r |
| .Ar tag Ar snapshot Ns ... |
| .Nm |
| .Cm diff |
| .Op Fl FHt |
| .Ar snapshot Ar snapshot Ns | Ns Ar filesystem |
| .Nm |
| .Cm program |
| .Op Fl jn |
| .Op Fl t Ar instruction-limit |
| .Op Fl m Ar memory-limit |
| .Ar pool script |
| .Op -- |
| .Ar arg1 No ... |
| .Nm |
| .Cm load-key |
| .Op Fl nr |
| .Op Fl L Ar keylocation |
| .Fl a | Ar filesystem |
| .Nm |
| .Cm unload-key |
| .Op Fl r |
| .Fl a | Ar filesystem |
| .Nm |
| .Cm change-key |
| .Op Fl l |
| .Op Fl o Ar keylocation Ns = Ns Ar value |
| .Op Fl o Ar keyformat Ns = Ns Ar value |
| .Op Fl o Ar pbkdf2iters Ns = Ns Ar value |
| .Ar filesystem |
| .Nm |
| .Cm change-key |
| .Fl i |
| .Op Fl l |
| .Ar filesystem |
| .Nm |
| .Cm version |
| .Sh DESCRIPTION |
| The |
| .Nm |
| command configures ZFS datasets within a ZFS storage pool, as described in |
| .Xr zpool 8 . |
| A dataset is identified by a unique path within the ZFS namespace. |
| For example: |
| .Bd -literal |
| pool/{filesystem,volume,snapshot} |
| .Ed |
| .Pp |
| where the maximum length of a dataset name is |
| .Dv MAXNAMELEN |
| .Pq 256 bytes |
| and the maximum amount of nesting allowed in a path is 50 levels deep. |
| .Pp |
| A dataset can be one of the following: |
| .Bl -tag -width "file system" |
| .It Sy file system |
| A ZFS dataset of type |
| .Sy filesystem |
| can be mounted within the standard system namespace and behaves like other file |
| systems. |
| While ZFS file systems are designed to be POSIX compliant, known issues exist |
| that prevent compliance in some cases. |
| Applications that depend on standards conformance might fail due to non-standard |
| behavior when checking file system free space. |
| .It Sy volume |
| A logical volume exported as a raw or block device. |
| This type of dataset should only be used when a block device is required. |
| File systems are typically used in most environments. |
| .It Sy snapshot |
| A read-only version of a file system or volume at a given point in time. |
| It is specified as |
| .Ar filesystem Ns @ Ns Ar name |
| or |
| .Ar volume Ns @ Ns Ar name . |
| .It Sy bookmark |
| Much like a |
| .Sy snapshot , |
| but without the hold on on-disk data. It can be used as the source of a send |
| (but not for a receive). It is specified as |
| .Ar filesystem Ns # Ns Ar name |
| or |
| .Ar volume Ns # Ns Ar name . |
| .El |
| .Ss ZFS File System Hierarchy |
| A ZFS storage pool is a logical collection of devices that provide space for |
| datasets. |
| A storage pool is also the root of the ZFS file system hierarchy. |
| .Pp |
| 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 |
| .Xr zpool 8 |
| command. |
| .Pp |
| See |
| .Xr zpool 8 |
| for more information on creating and administering pools. |
| .Ss Snapshots |
| 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. |
| .Pp |
| Snapshots can have arbitrary names. |
| Snapshots of volumes can be cloned or rolled back, visibility is determined |
| by the |
| .Sy snapdev |
| property of the parent volume. |
| .Pp |
| File system snapshots can be accessed under the |
| .Pa .zfs/snapshot |
| 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 |
| .Pa .zfs |
| directory can be controlled by the |
| .Sy snapdir |
| property. |
| .Ss Bookmarks |
| A bookmark is like a snapshot, a read-only copy of a file system or volume. |
| Bookmarks can be created extremely quickly, compared to snapshots, and they |
| consume no additional space within the pool. Bookmarks can also have arbitrary |
| names, much like snapshots. |
| .Pp |
| Unlike snapshots, bookmarks can not be accessed through the filesystem in any |
| way. From a storage standpoint a bookmark just provides a way to reference |
| when a snapshot was created as a distinct object. Bookmarks are initially |
| tied to a snapshot, not the filesystem or volume, and they will survive if the |
| snapshot itself is destroyed. Since they are very light weight there's little |
| incentive to destroy them. |
| .Ss Clones |
| 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. |
| .Pp |
| 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 |
| .Sy origin |
| property exposes this dependency, and the |
| .Cm destroy |
| command lists any such dependencies, if they exist. |
| .Pp |
| The clone parent-child dependency relationship can be reversed by using the |
| .Cm promote |
| subcommand. |
| This causes the |
| .Qq 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" |
| Creating a ZFS file system is a simple operation, so the number of file systems |
| per system is likely to be numerous. |
| To cope with this, ZFS automatically manages mounting and unmounting file |
| systems without the need to edit the |
| .Pa /etc/fstab |
| file. |
| All automatically managed file systems are mounted by ZFS at boot time. |
| .Pp |
| By default, file systems are mounted under |
| .Pa /path , |
| where |
| .Ar path |
| is the name of the file system in the ZFS namespace. |
| Directories are created and destroyed as needed. |
| .Pp |
| A file system can also have a mount point set in the |
| .Sy mountpoint |
| property. |
| This directory is created as needed, and ZFS automatically mounts the file |
| system when the |
| .Nm zfs Cm mount Fl a |
| command is invoked |
| .Po without editing |
| .Pa /etc/fstab |
| .Pc . |
| The |
| .Sy mountpoint |
| property can be inherited, so if |
| .Em pool/home |
| has a mount point of |
| .Pa /export/stuff , |
| then |
| .Em pool/home/user |
| automatically inherits a mount point of |
| .Pa /export/stuff/user . |
| .Pp |
| A file system |
| .Sy mountpoint |
| property of |
| .Sy none |
| prevents the file system from being mounted. |
| .Pp |
| If needed, ZFS file systems can also be managed with traditional tools |
| .Po |
| .Nm mount , |
| .Nm umount , |
| .Pa /etc/fstab |
| .Pc . |
| If a file system's mount point is set to |
| .Sy legacy , |
| ZFS makes no attempt to manage the file system, and the administrator is |
| responsible for mounting and unmounting the file system. Because pools must |
| be imported before a legacy mount can succeed, administrators should ensure |
| that legacy mounts are only attempted after the zpool import process |
| finishes at boot time. For example, on machines using systemd, the mount |
| option |
| .Pp |
| .Nm x-systemd.requires=zfs-import.target |
| .Pp |
| will ensure that the zfs-import completes before systemd attempts mounting |
| the filesystem. See systemd.mount(5) for details. |
| .Ss Deduplication |
| Deduplication is the process for removing redundant data at the block level, |
| reducing the total amount of data stored. If a file system has the |
| .Sy dedup |
| property enabled, duplicate data blocks are removed synchronously. The result |
| is that only unique data is stored and common components are shared among files. |
| .Pp |
| Deduplicating data is a very resource-intensive operation. It is generally |
| recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when |
| you enable deduplication. Calculating the exact requirement depends heavily |
| on the type of data stored in the pool. |
| .Pp |
| Enabling deduplication on an improperly-designed system can result in |
| performance issues (slow IO and administrative operations). It can potentially |
| lead to problems importing a pool due to memory exhaustion. Deduplication |
| can consume significant processing power (CPU) and memory as well as generate |
| additional disk IO. |
| .Pp |
| Before creating a pool with deduplication enabled, ensure that you have planned |
| your hardware requirements appropriately and implemented appropriate recovery |
| practices, such as regular backups. As an alternative to deduplication |
| consider using |
| .Sy compression=on , |
| as a less resource-intensive alternative. |
| .Ss Native Properties |
| Properties are divided into two types, native properties and user-defined |
| .Po or |
| .Qq user |
| .Pc |
| properties. |
| Native properties either export internal statistics or control ZFS behavior. |
| In addition, native properties are either editable or read-only. |
| User properties have no effect on ZFS 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 |
| .Sx User Properties |
| section, below. |
| .Pp |
| 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 |
| .Pq file systems, volumes, or snapshots . |
| .Pp |
| The values of numeric properties can be specified using human-readable suffixes |
| .Po for example, |
| .Sy k , |
| .Sy KB , |
| .Sy M , |
| .Sy Gb , |
| and so forth, up to |
| .Sy Z |
| for zettabyte |
| .Pc . |
| The following are all valid |
| .Pq and equal |
| specifications: |
| .Li 1536M, 1.5g, 1.50GB . |
| .Pp |
| The values of non-numeric properties are case sensitive and must be lowercase, |
| except for |
| .Sy mountpoint , |
| .Sy sharenfs , |
| and |
| .Sy sharesmb . |
| .Pp |
| 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. |
| .Bl -tag -width "usedbyrefreservation" |
| .It Sy available |
| 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. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy avail . |
| .It Sy compressratio |
| For non-snapshots, the compression ratio achieved for the |
| .Sy used |
| space of this dataset, expressed as a multiplier. |
| The |
| .Sy used |
| property includes descendant datasets, and, for clones, does not include the |
| space shared with the origin snapshot. |
| For snapshots, the |
| .Sy compressratio |
| is the same as the |
| .Sy refcompressratio |
| property. |
| Compression can be turned on by running: |
| .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . |
| The default value is |
| .Sy off . |
| .It Sy createtxg |
| The transaction group (txg) in which the dataset was created. Bookmarks have |
| the same |
| .Sy createtxg |
| as the snapshot they are initially tied to. This property is suitable for |
| ordering a list of snapshots, e.g. for incremental send and receive. |
| .It Sy creation |
| The time this dataset was created. |
| .It Sy clones |
| For snapshots, this property is a comma-separated list of filesystems or volumes |
| which are clones of this snapshot. |
| The clones' |
| .Sy origin |
| property is this snapshot. |
| If the |
| .Sy clones |
| property is not empty, then this snapshot can not be destroyed |
| .Po even with the |
| .Fl r |
| or |
| .Fl f |
| options |
| .Pc . |
| The roles of origin and clone can be swapped by promoting the clone with the |
| .Nm zfs Cm promote |
| command. |
| .It Sy defer_destroy |
| This property is |
| .Sy on |
| if the snapshot has been marked for deferred destroy by using the |
| .Nm zfs Cm destroy Fl d |
| command. |
| Otherwise, the property is |
| .Sy off . |
| .It Sy encryptionroot |
| For encrypted datasets, indicates where the dataset is currently inheriting its |
| encryption key from. Loading or unloading a key for the |
| .Sy encryptionroot |
| will implicitly load / unload the key for any inheriting datasets (see |
| .Nm zfs Cm load-key |
| and |
| .Nm zfs Cm unload-key |
| for details). |
| Clones will always share an |
| encryption key with their origin. See the |
| .Sx Encryption |
| section for details. |
| .It Sy filesystem_count |
| The total number of filesystems and volumes that exist under this location in |
| the dataset tree. |
| This value is only available when a |
| .Sy filesystem_limit |
| has been set somewhere in the tree under which the dataset resides. |
| .It Sy keystatus |
| Indicates if an encryption key is currently loaded into ZFS. The possible |
| values are |
| .Sy none , |
| .Sy available , |
| and |
| .Sy unavailable . |
| See |
| .Nm zfs Cm load-key |
| and |
| .Nm zfs Cm unload-key . |
| .It Sy guid |
| The 64 bit GUID of this dataset or bookmark which does not change over its |
| entire lifetime. When a snapshot is sent to another pool, the received |
| snapshot has the same GUID. Thus, the |
| .Sy guid |
| is suitable to identify a snapshot across pools. |
| .It Sy logicalreferenced |
| The amount of space that is |
| .Qq logically |
| accessible by this dataset. |
| See the |
| .Sy referenced |
| property. |
| The logical space ignores the effect of the |
| .Sy compression |
| and |
| .Sy copies |
| properties, giving a quantity closer to the amount of data that applications |
| see. |
| However, it does include space consumed by metadata. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy lrefer . |
| .It Sy logicalused |
| The amount of space that is |
| .Qq logically |
| consumed by this dataset and all its descendents. |
| See the |
| .Sy used |
| property. |
| The logical space ignores the effect of the |
| .Sy compression |
| and |
| .Sy copies |
| properties, giving a quantity closer to the amount of data that applications |
| see. |
| However, it does include space consumed by metadata. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy lused . |
| .It Sy mounted |
| For file systems, indicates whether the file system is currently mounted. |
| This property can be either |
| .Sy yes |
| or |
| .Sy no . |
| .It Sy objsetid |
| A unique identifier for this dataset within the pool. Unlike the dataset's |
| .Sy guid |
| , the |
| .Sy objsetid |
| of a dataset is not transferred to other pools when the snapshot is copied |
| with a send/receive operation. |
| The |
| .Sy objsetid |
| can be reused (for a new datatset) after the dataset is deleted. |
| .It Sy origin |
| For cloned file systems or volumes, the snapshot from which the clone was |
| created. |
| See also the |
| .Sy clones |
| property. |
| .It Sy receive_resume_token |
| For filesystems or volumes which have saved partially-completed state from |
| .Sy zfs receive -s , |
| this opaque token can be provided to |
| .Sy zfs send -t |
| to resume and complete the |
| .Sy zfs receive . |
| .It Sy referenced |
| The amount of data that is accessible by this dataset, which may or may not be |
| shared with other datasets in the pool. |
| When a snapshot or clone is created, it initially references the same amount of |
| space as the file system or snapshot it was created from, since its contents are |
| identical. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy refer . |
| .It Sy refcompressratio |
| The compression ratio achieved for the |
| .Sy referenced |
| space of this dataset, expressed as a multiplier. |
| See also the |
| .Sy compressratio |
| property. |
| .It Sy snapshot_count |
| The total number of snapshots that exist under this location in the dataset |
| tree. |
| This value is only available when a |
| .Sy snapshot_limit |
| has been set somewhere in the tree under which the dataset resides. |
| .It Sy type |
| The type of dataset: |
| .Sy filesystem , |
| .Sy volume , |
| or |
| .Sy snapshot . |
| .It Sy used |
| The amount of space consumed by this dataset and all its descendents. |
| This is the value that is checked against this dataset's quota and reservation. |
| The space used does not include this dataset's reservation, but does take into |
| account the reservations 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 this dataset is recursively destroyed, is the |
| greater of its space used and its reservation. |
| .Pp |
| The used space of a snapshot |
| .Po see the |
| .Sx Snapshots |
| section |
| .Pc |
| is space that is referenced exclusively by this snapshot. |
| If this snapshot is destroyed, the amount of |
| .Sy used |
| space will be freed. |
| Space that is shared by multiple snapshots isn't accounted for in this metric. |
| When a snapshot is destroyed, space that was previously shared with this |
| snapshot can become unique to snapshots adjacent to it, thus changing the used |
| space of those snapshots. |
| The used space of the latest snapshot can also be affected by changes in the |
| file system. |
| Note that the |
| .Sy used |
| space of a snapshot is a subset of the |
| .Sy written |
| space of the snapshot. |
| .Pp |
| 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 |
| .Xr fsync 2 |
| or |
| .Dv O_SYNC |
| does not necessarily guarantee that the space usage information is updated |
| immediately. |
| .It Sy usedby* |
| The |
| .Sy usedby* |
| properties decompose the |
| .Sy used |
| properties into the various reasons that space is used. |
| Specifically, |
| .Sy used No = |
| .Sy usedbychildren No + |
| .Sy usedbydataset No + |
| .Sy usedbyrefreservation No + |
| .Sy usedbysnapshots . |
| These properties are only available for datasets created on |
| .Nm zpool |
| .Qo version 13 Qc |
| pools. |
| .It Sy usedbychildren |
| The amount of space used by children of this dataset, which would be freed if |
| all the dataset's children were destroyed. |
| .It Sy usedbydataset |
| The amount of space used by this dataset itself, which would be freed if the |
| dataset were destroyed |
| .Po after first removing any |
| .Sy refreservation |
| and destroying any necessary snapshots or descendents |
| .Pc . |
| .It Sy usedbyrefreservation |
| The amount of space used by a |
| .Sy refreservation |
| set on this dataset, which would be freed if the |
| .Sy refreservation |
| was removed. |
| .It Sy usedbysnapshots |
| The amount of space consumed by snapshots of this dataset. |
| In particular, it is the amount of space that would be freed if all of this |
| dataset's snapshots were destroyed. |
| Note that this is not simply the sum of the snapshots' |
| .Sy used |
| properties because space can be shared by multiple snapshots. |
| .It Sy userused Ns @ Ns Em user |
| The amount of space consumed by the specified user in this dataset. |
| Space is charged to the owner of each file, as displayed by |
| .Nm ls Fl l . |
| The amount of space charged is displayed by |
| .Nm du |
| and |
| .Nm ls Fl s . |
| See the |
| .Nm zfs Cm userspace |
| subcommand for more information. |
| .Pp |
| Unprivileged users can access only their own space usage. |
| The root user, or a user who has been granted the |
| .Sy userused |
| privilege with |
| .Nm zfs Cm allow , |
| can access everyone's usage. |
| .Pp |
| The |
| .Sy userused Ns @ Ns Em ... |
| properties are not displayed by |
| .Nm zfs Cm get Sy all . |
| The user's name must be appended after the @ symbol, using one of the following |
| forms: |
| .Bl -bullet -width "" |
| .It |
| .Em POSIX name |
| .Po for example, |
| .Sy joe |
| .Pc |
| .It |
| .Em POSIX numeric ID |
| .Po for example, |
| .Sy 789 |
| .Pc |
| .It |
| .Em SID name |
| .Po for example, |
| .Sy joe.smith@mydomain |
| .Pc |
| .It |
| .Em SID numeric ID |
| .Po for example, |
| .Sy S-1-123-456-789 |
| .Pc |
| .El |
| .Pp |
| Files created on Linux always have POSIX owners. |
| .It Sy userobjused Ns @ Ns Em user |
| The |
| .Sy userobjused |
| property is similar to |
| .Sy userused |
| but instead it counts the number of objects consumed by a user. This property |
| counts all objects allocated on behalf of the user, it may differ from the |
| results of system tools such as |
| .Nm df Fl i . |
| .Pp |
| When the property |
| .Sy xattr=on |
| is set on a file system additional objects will be created per-file to store |
| extended attributes. These additional objects are reflected in the |
| .Sy userobjused |
| value and are counted against the user's |
| .Sy userobjquota . |
| When a file system is configured to use |
| .Sy xattr=sa |
| no additional internal objects are normally required. |
| .It Sy userrefs |
| This property is set to the number of user holds on this snapshot. |
| User holds are set by using the |
| .Nm zfs Cm hold |
| command. |
| .It Sy groupused Ns @ Ns Em group |
| The amount of space consumed by the specified group in this dataset. |
| Space is charged to the group of each file, as displayed by |
| .Nm ls Fl l . |
| See the |
| .Sy userused Ns @ Ns Em user |
| property for more information. |
| .Pp |
| Unprivileged users can only access their own groups' space usage. |
| The root user, or a user who has been granted the |
| .Sy groupused |
| privilege with |
| .Nm zfs Cm allow , |
| can access all groups' usage. |
| .It Sy groupobjused Ns @ Ns Em group |
| The number of objects consumed by the specified group in this dataset. |
| Multiple objects may be charged to the group for each file when extended |
| attributes are in use. See the |
| .Sy userobjused Ns @ Ns Em user |
| property for more information. |
| .Pp |
| Unprivileged users can only access their own groups' space usage. |
| The root user, or a user who has been granted the |
| .Sy groupobjused |
| privilege with |
| .Nm zfs Cm allow , |
| can access all groups' usage. |
| .It Sy projectused Ns @ Ns Em project |
| The amount of space consumed by the specified project in this dataset. Project |
| is identified via the project identifier (ID) that is object-based numeral |
| attribute. An object can inherit the project ID from its parent object (if the |
| parent has the flag of inherit project ID that can be set and changed via |
| .Nm chattr Fl /+P |
| or |
| .Nm zfs project Fl s ) |
| when being created. The privileged user can set and change object's project |
| ID via |
| .Nm chattr Fl p |
| or |
| .Nm zfs project Fl s |
| anytime. Space is charged to the project of each file, as displayed by |
| .Nm lsattr Fl p |
| or |
| .Nm zfs project . |
| See the |
| .Sy userused Ns @ Ns Em user |
| property for more information. |
| .Pp |
| The root user, or a user who has been granted the |
| .Sy projectused |
| privilege with |
| .Nm zfs allow , |
| can access all projects' usage. |
| .It Sy projectobjused Ns @ Ns Em project |
| The |
| .Sy projectobjused |
| is similar to |
| .Sy projectused |
| but instead it counts the number of objects consumed by project. When the |
| property |
| .Sy xattr=on |
| is set on a fileset, ZFS will create additional objects per-file to store |
| extended attributes. These additional objects are reflected in the |
| .Sy projectobjused |
| value and are counted against the project's |
| .Sy projectobjquota . |
| When a filesystem is configured to use |
| .Sy xattr=sa |
| no additional internal objects are required. See the |
| .Sy userobjused Ns @ Ns Em user |
| property for more information. |
| .Pp |
| The root user, or a user who has been granted the |
| .Sy projectobjused |
| privilege with |
| .Nm zfs allow , |
| can access all projects' objects usage. |
| .It Sy volblocksize |
| For volumes, specifies the block size of the volume. |
| The |
| .Sy blocksize |
| cannot be changed once the volume has been written, so it should be set at |
| volume creation time. |
| The default |
| .Sy blocksize |
| for volumes is 8 Kbytes. |
| Any power of 2 from 512 bytes to 128 Kbytes is valid. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy volblock . |
| .It Sy written |
| The amount of space |
| .Sy referenced |
| by this dataset, that was written since the previous snapshot |
| .Pq i.e. that is not referenced by the previous snapshot . |
| .It Sy written Ns @ Ns Em snapshot |
| The amount of |
| .Sy referenced |
| space written to this dataset since the specified snapshot. |
| This is the space that is referenced by this dataset but was not referenced by |
| the specified snapshot. |
| .Pp |
| The |
| .Em snapshot |
| may be specified as a short snapshot name |
| .Po just the part after the |
| .Sy @ |
| .Pc , |
| in which case it will be interpreted as a snapshot in the same filesystem as |
| this dataset. |
| The |
| .Em snapshot |
| may be a full snapshot name |
| .Po Em filesystem Ns @ Ns Em snapshot Pc , |
| which for clones may be a snapshot in the origin's filesystem |
| .Pq or the origin of the origin's filesystem, etc. |
| .El |
| .Pp |
| The following native properties can be used to change the behavior of a ZFS |
| dataset. |
| .Bl -tag -width "" |
| .It Xo |
| .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns |
| .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x |
| .Xc |
| Controls how ACEs are inherited when files and directories are created. |
| .Bl -tag -width "passthrough-x" |
| .It Sy discard |
| does not inherit any ACEs. |
| .It Sy noallow |
| only inherits inheritable ACEs that specify |
| .Qq deny |
| permissions. |
| .It Sy restricted |
| default, removes the |
| .Sy write_acl |
| and |
| .Sy write_owner |
| permissions when the ACE is inherited. |
| .It Sy passthrough |
| inherits all inheritable ACEs without any modifications. |
| .It Sy passthrough-x |
| same meaning as |
| .Sy passthrough , |
| except that the |
| .Sy owner@ , |
| .Sy group@ , |
| and |
| .Sy everyone@ |
| ACEs inherit the execute permission only if the file creation mode also requests |
| the execute bit. |
| .El |
| .Pp |
| When the property value is set to |
| .Sy passthrough , |
| files are created with a mode determined by the inheritable ACEs. |
| If no inheritable ACEs exist that affect the mode, then the mode is set in |
| accordance to the requested mode from the application. |
| .Pp |
| The |
| .Sy aclinherit |
| property does not apply to POSIX ACLs. |
| .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl |
| Controls whether ACLs are enabled and if so what type of ACL to use. |
| .Bl -tag -width "posixacl" |
| .It Sy off |
| default, when a file system has the |
| .Sy acltype |
| property set to off then ACLs are disabled. |
| .It Sy noacl |
| an alias for |
| .Sy off |
| .It Sy posixacl |
| indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are |
| not functional on other platforms. POSIX ACLs are stored as an extended |
| attribute and therefore will not overwrite any existing NFSv4 ACLs which |
| may be set. |
| .El |
| .Pp |
| To obtain the best performance when setting |
| .Sy posixacl |
| users are strongly encouraged to set the |
| .Sy xattr=sa |
| property. This will result in the POSIX ACL being stored more efficiently on |
| disk. But as a consequence, all new extended attributes will only be |
| accessible from OpenZFS implementations which support the |
| .Sy xattr=sa |
| property. See the |
| .Sy xattr |
| property for more details. |
| .It Sy atime Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether the access time for files is updated when they are read. |
| Turning this property off avoids producing write traffic when reading files and |
| can result in significant performance gains, though it might confuse mailers |
| and other similar utilities. The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy atime |
| and |
| .Sy noatime |
| mount options. The default value is |
| .Sy on . |
| See also |
| .Sy relatime |
| below. |
| .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto |
| If this property is set to |
| .Sy off , |
| the file system cannot be mounted, and is ignored by |
| .Nm zfs Cm mount Fl a . |
| Setting this property to |
| .Sy off |
| is similar to setting the |
| .Sy mountpoint |
| property to |
| .Sy none , |
| except that the dataset still has a normal |
| .Sy mountpoint |
| property, which can be inherited. |
| Setting this property to |
| .Sy off |
| allows datasets to be used solely as a mechanism to inherit properties. |
| One example of setting |
| .Sy canmount Ns = Ns Sy off |
| is to have two datasets with the same |
| .Sy mountpoint , |
| so that the children of both datasets appear in the same directory, but might |
| have different inherited characteristics. |
| .Pp |
| When set to |
| .Sy noauto , |
| a dataset can only be mounted and unmounted explicitly. |
| The dataset is not mounted automatically when the dataset is created or |
| imported, nor is it mounted by the |
| .Nm zfs Cm mount Fl a |
| command or unmounted by the |
| .Nm zfs Cm unmount Fl a |
| command. |
| .Pp |
| This property is not inherited. |
| .It Xo |
| .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns |
| .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns |
| .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr |
| .Xc |
| Controls the checksum used to verify data integrity. |
| The default value is |
| .Sy on , |
| which automatically selects an appropriate algorithm |
| .Po currently, |
| .Sy fletcher4 , |
| but this may change in future releases |
| .Pc . |
| The value |
| .Sy off |
| disables integrity checking on user data. |
| The value |
| .Sy noparity |
| not only disables integrity but also disables maintaining parity for user data. |
| This setting is used internally by a dump device residing on a RAID-Z pool and |
| should not be used by any other dataset. |
| Disabling checksums is |
| .Sy NOT |
| a recommended practice. |
| .Pp |
| The |
| .Sy sha512 , |
| .Sy skein , |
| and |
| .Sy edonr |
| checksum algorithms require enabling the appropriate features on the pool. |
| These pool features are not supported by GRUB and must not be used on the |
| pool if GRUB needs to access the pool (e.g. for /boot). |
| .Pp |
| Please see |
| .Xr zpool-features 5 |
| for more information on these algorithms. |
| .Pp |
| Changing this property affects only newly-written data. |
| .It Xo |
| .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns |
| .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle |
| .Xc |
| Controls the compression algorithm used for this dataset. |
| .Pp |
| Setting compression to |
| .Sy on |
| indicates that the current default compression algorithm should be used. |
| The default balances compression and decompression speed, with compression ratio |
| and is expected to work well on a wide variety of workloads. |
| Unlike all other settings for this property, |
| .Sy on |
| does not select a fixed compression type. |
| As new compression algorithms are added to ZFS and enabled on a pool, the |
| default compression algorithm may change. |
| The current default compression algorithm is either |
| .Sy lzjb |
| or, if the |
| .Sy lz4_compress |
| feature is enabled, |
| .Sy lz4 . |
| .Pp |
| The |
| .Sy lz4 |
| compression algorithm is a high-performance replacement for the |
| .Sy lzjb |
| algorithm. |
| It features significantly faster compression and decompression, as well as a |
| moderately higher compression ratio than |
| .Sy lzjb , |
| but can only be used on pools with the |
| .Sy lz4_compress |
| feature set to |
| .Sy enabled . |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy lz4_compress |
| feature. |
| .Pp |
| The |
| .Sy lzjb |
| compression algorithm is optimized for performance while providing decent data |
| compression. |
| .Pp |
| The |
| .Sy gzip |
| compression algorithm uses the same compression as the |
| .Xr gzip 1 |
| command. |
| You can specify the |
| .Sy gzip |
| level by using the value |
| .Sy gzip- Ns Em N , |
| where |
| .Em N |
| is an integer from 1 |
| .Pq fastest |
| to 9 |
| .Pq best compression ratio . |
| Currently, |
| .Sy gzip |
| is equivalent to |
| .Sy gzip-6 |
| .Po which is also the default for |
| .Xr gzip 1 |
| .Pc . |
| .Pp |
| The |
| .Sy zle |
| compression algorithm compresses runs of zeros. |
| .Pp |
| This property can also be referred to by its shortened column name |
| .Sy compress . |
| Changing this property affects only newly-written data. |
| .Pp |
| When any setting except |
| .Sy off |
| is selected, compression will explicitly check for blocks consisting of only |
| zeroes (the NUL byte). When a zero-filled block is detected, it is stored as |
| a hole and not compressed using the indicated compression algorithm. |
| .Pp |
| Any block being compressed must be no larger than 7/8 of its original size |
| after compression, otherwise the compression will not be considered worthwhile |
| and the block saved uncompressed. Note that when the logical block is less than |
| 8 times the disk sector size this effectively reduces the necessary compression |
| ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2 |
| or less of their original size. |
| .It Xo |
| .Sy context Ns = Ns Sy none Ns | Ns |
| .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level |
| .Xc |
| This flag sets the SELinux context for all files in the file system under |
| a mount point for that file system. See |
| .Xr selinux 8 |
| for more information. |
| .It Xo |
| .Sy fscontext Ns = Ns Sy none Ns | Ns |
| .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level |
| .Xc |
| This flag sets the SELinux context for the file system file system being |
| mounted. See |
| .Xr selinux 8 |
| for more information. |
| .It Xo |
| .Sy defcontext Ns = Ns Sy none Ns | Ns |
| .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level |
| .Xc |
| This flag sets the SELinux default context for unlabeled files. See |
| .Xr selinux 8 |
| for more information. |
| .It Xo |
| .Sy rootcontext Ns = Ns Sy none Ns | Ns |
| .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level |
| .Xc |
| This flag sets the SELinux context for the root inode of the file system. See |
| .Xr selinux 8 |
| for more information. |
| .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 |
| Controls the number of copies of data stored for this dataset. |
| These copies are in addition to any redundancy provided by the pool, for |
| example, mirroring or RAID-Z. |
| The copies are stored on different disks, if possible. |
| The space used by multiple copies is charged to the associated file and dataset, |
| changing the |
| .Sy used |
| property and counting against quotas and reservations. |
| .Pp |
| Changing this property only affects newly-written data. |
| Therefore, set this property at file system creation time by using the |
| .Fl o Sy copies Ns = Ns Ar N |
| option. |
| .Pp |
| Remember that ZFS will not import a pool with a missing top-level vdev. Do |
| .Sy NOT |
| create, for example a two-disk striped pool and set |
| .Sy copies=2 |
| on some datasets thinking you have setup redundancy for them. When a disk |
| fails you will not be able to import the pool and will have lost all of your |
| data. |
| .Pp |
| Encrypted datasets may not have |
| .Sy copies Ns = Ns Em 3 |
| since the implementation stores some encryption metadata where the third copy |
| would normally be. |
| .It Sy devices Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether device nodes can be opened on this file system. |
| The default value is |
| .Sy on . |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy dev |
| and |
| .Sy nodev |
| mount options. |
| .It Xo |
| .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns |
| .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns |
| .Sy edonr,verify |
| .Xc |
| Configures deduplication for a dataset. The default value is |
| .Sy off . |
| The default deduplication checksum is |
| .Sy sha256 |
| (this may change in the future). When |
| .Sy dedup |
| is enabled, the checksum defined here overrides the |
| .Sy checksum |
| property. Setting the value to |
| .Sy verify |
| has the same effect as the setting |
| .Sy sha256,verify. |
| .Pp |
| If set to |
| .Sy verify , |
| ZFS will do a byte-to-byte comparsion in case of two blocks having the same |
| signature to make sure the block contents are identical. Specifying |
| .Sy verify |
| is mandatory for the |
| .Sy edonr |
| algorithm. |
| .Pp |
| Unless necessary, deduplication should NOT be enabled on a system. See |
| .Sx Deduplication |
| above. |
| .It Xo |
| .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns |
| .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k |
| .Xc |
| Specifies a compatibility mode or literal value for the size of dnodes in the |
| file system. The default value is |
| .Sy legacy . |
| Setting this property to a value other than |
| .Sy legacy |
| requires the large_dnode pool feature to be enabled. |
| .Pp |
| Consider setting |
| .Sy dnodesize |
| to |
| .Sy auto |
| if the dataset uses the |
| .Sy xattr=sa |
| property setting and the workload makes heavy use of extended attributes. This |
| may be applicable to SELinux-enabled systems, Lustre servers, and Samba |
| servers, for example. Literal values are supported for cases where the optimal |
| size is known in advance and for performance testing. |
| .Pp |
| Leave |
| .Sy dnodesize |
| set to |
| .Sy legacy |
| if you need to receive a send stream of this dataset on a pool that doesn't |
| enable the large_dnode feature, or if you need to import this pool on a system |
| that doesn't support the large_dnode feature. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy dnsize . |
| .It Xo |
| .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns |
| .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns |
| .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm |
| .Xc |
| Controls the encryption cipher suite (block cipher, key length, and mode) used |
| for this dataset. Requires the |
| .Sy encryption |
| feature to be enabled on the pool. |
| Requires a |
| .Sy keyformat |
| to be set at dataset creation time. |
| .Pp |
| Selecting |
| .Sy encryption Ns = Ns Sy on |
| when creating a dataset indicates that the default encryption suite will be |
| selected, which is currently |
| .Sy aes-256-gcm . |
| In order to provide consistent data protection, encryption must be specified at |
| dataset creation time and it cannot be changed afterwards. |
| .Pp |
| For more details and caveats about encryption see the |
| .Sy Encryption |
| section. |
| .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase |
| Controls what format the user's encryption key will be provided as. This |
| property is only set when the dataset is encrypted. |
| .Pp |
| Raw keys and hex keys must be 32 bytes long (regardless of the chosen |
| encryption suite) and must be randomly generated. A raw key can be generated |
| with the following command: |
| .Bd -literal |
| # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1 |
| .Ed |
| .Pp |
| Passphrases must be between 8 and 512 bytes long and will be processed through |
| PBKDF2 before being used (see the |
| .Sy pbkdf2iters |
| property). Even though the |
| encryption suite cannot be changed after dataset creation, the keyformat can be |
| with |
| .Nm zfs Cm change-key . |
| .It Xo |
| .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path> |
| .Xc |
| Controls where the user's encryption key will be loaded from by default for |
| commands such as |
| .Nm zfs Cm load-key |
| and |
| .Nm zfs Cm mount Cm -l . |
| This property is only set for encrypted datasets which are encryption roots. If |
| unspecified, the default is |
| .Sy prompt. |
| .Pp |
| Even though the encryption suite cannot be changed after dataset creation, the |
| keylocation can be with either |
| .Nm zfs Cm set |
| or |
| .Nm zfs Cm change-key . |
| If |
| .Sy prompt |
| is selected ZFS will ask for the key at the command prompt when it is required |
| to access the encrypted data (see |
| .Nm zfs Cm load-key |
| for details). This setting will also allow the key to be passed in via STDIN, |
| but users should be careful not to place keys which should be kept secret on |
| the command line. If a file URI is selected, the key will be loaded from the |
| specified absolute file path. |
| .It Sy pbkdf2iters Ns = Ns Ar iterations |
| Controls the number of PBKDF2 iterations that a |
| .Sy passphrase |
| encryption key should be run through when processing it into an encryption key. |
| This property is only defined when encryption is enabled and a keyformat of |
| .Sy passphrase |
| is selected. The goal of PBKDF2 is to significantly increase the |
| computational difficulty needed to brute force a user's passphrase. This is |
| accomplished by forcing the attacker to run each passphrase through a |
| computationally expensive hashing function many times before they arrive at the |
| resulting key. A user who actually knows the passphrase will only have to pay |
| this cost once. As CPUs become better at processing, this number should be |
| raised to ensure that a brute force attack is still not possible. The current |
| default is |
| .Sy 350000 |
| and the minimum is |
| .Sy 100000 . |
| This property may be changed with |
| .Nm zfs Cm change-key . |
| .It Sy exec Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether processes can be executed from within this file system. |
| The default value is |
| .Sy on . |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy exec |
| and |
| .Sy noexec |
| mount options. |
| .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none |
| Limits the number of filesystems and volumes that can exist under this point in |
| the dataset tree. |
| The limit is not enforced if the user is allowed to change the limit. |
| Setting a |
| .Sy filesystem_limit |
| to |
| .Sy on |
| a descendent of a filesystem that already has a |
| .Sy filesystem_limit |
| does not override the ancestor's |
| .Sy filesystem_limit , |
| but rather imposes an additional limit. |
| This feature must be enabled to be used |
| .Po see |
| .Xr zpool-features 5 |
| .Pc . |
| .It Sy special_small_blocks Ns = Ns Em size |
| This value represents the threshold block size for including small file |
| blocks into the special allocation class. Blocks smaller than or equal to this |
| value will be assigned to the special allocation class while greater blocks |
| will be assigned to the regular class. Valid values are zero or a power of two |
| from 512B up to 1M. The default size is 0 which means no small file blocks |
| will be allocated in the special class. |
| .Pp |
| Before setting this property, a special class vdev must be added to the |
| pool. See |
| .Xr zpool 8 |
| for more details on the special allocation class. |
| .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy |
| Controls the mount point used for this file system. |
| See the |
| .Sx Mount Points |
| section for more information on how this property is used. |
| .Pp |
| When the |
| .Sy mountpoint |
| property is changed for a file system, the file system and any children that |
| inherit the mount point are unmounted. |
| If the new value is |
| .Sy legacy , |
| then they remain unmounted. |
| Otherwise, they are automatically remounted in the new location if the property |
| was previously |
| .Sy legacy |
| or |
| .Sy none , |
| or if they were mounted before the property was changed. |
| In addition, any shared file systems are unshared and shared in the new |
| location. |
| .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether the file system should be mounted with |
| .Sy nbmand |
| .Pq Non Blocking mandatory locks . |
| This is used for SMB clients. |
| Changes to this property only take effect when the file system is umounted and |
| remounted. |
| See |
| .Xr mount 8 |
| for more information on |
| .Sy nbmand |
| mounts. This property is not used on Linux. |
| .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on |
| Allow mounting on a busy directory or a directory which already contains |
| files or directories. This is the default mount behavior for Linux file systems. |
| For consistency with OpenZFS on other platforms overlay mounts are |
| .Sy off |
| by default. Set to |
| .Sy on |
| to enable overlay mounts. |
| .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata |
| Controls what is cached in the primary cache |
| .Pq ARC . |
| If this property is set to |
| .Sy all , |
| then both user data and metadata is cached. |
| If this property is set to |
| .Sy none , |
| then neither user data nor metadata is cached. |
| If this property is set to |
| .Sy metadata , |
| then only metadata is cached. |
| The default value is |
| .Sy all . |
| .It Sy quota Ns = Ns Em size Ns | Ns Sy none |
| Limits the amount of space a dataset and its descendents can consume. |
| This property enforces a hard limit on the amount of space used. |
| This includes all space consumed by descendents, including file systems and |
| snapshots. |
| Setting a quota on a descendent of a dataset that already has a quota does not |
| override the ancestor's quota, but rather imposes an additional limit. |
| .Pp |
| Quotas cannot be set on volumes, as the |
| .Sy volsize |
| property acts as an implicit quota. |
| .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none |
| Limits the number of snapshots that can be created on a dataset and its |
| descendents. |
| Setting a |
| .Sy snapshot_limit |
| on a descendent of a dataset that already has a |
| .Sy snapshot_limit |
| does not override the ancestor's |
| .Sy snapshot_limit , |
| but rather imposes an additional limit. |
| The limit is not enforced if the user is allowed to change the limit. |
| For example, this means that recursive snapshots taken from the global zone are |
| counted against each delegated dataset within a zone. |
| This feature must be enabled to be used |
| .Po see |
| .Xr zpool-features 5 |
| .Pc . |
| .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none |
| Limits the amount of space consumed by the specified user. |
| User space consumption is identified by the |
| .Sy userspace@ Ns Em user |
| property. |
| .Pp |
| Enforcement of user quotas may be delayed by several seconds. |
| This delay means that a user might exceed their quota before the system notices |
| that they are over quota and begins to refuse additional writes with the |
| .Er EDQUOT |
| error message. |
| See the |
| .Nm zfs Cm userspace |
| subcommand for more information. |
| .Pp |
| Unprivileged users can only access their own groups' space usage. |
| The root user, or a user who has been granted the |
| .Sy userquota |
| privilege with |
| .Nm zfs Cm allow , |
| can get and set everyone's quota. |
| .Pp |
| This property is not available on volumes, on file systems before version 4, or |
| on pools before version 15. |
| The |
| .Sy userquota@ Ns Em ... |
| properties are not displayed by |
| .Nm zfs Cm get Sy all . |
| The user's name must be appended after the |
| .Sy @ |
| symbol, using one of the following forms: |
| .Bl -bullet |
| .It |
| .Em POSIX name |
| .Po for example, |
| .Sy joe |
| .Pc |
| .It |
| .Em POSIX numeric ID |
| .Po for example, |
| .Sy 789 |
| .Pc |
| .It |
| .Em SID name |
| .Po for example, |
| .Sy joe.smith@mydomain |
| .Pc |
| .It |
| .Em SID numeric ID |
| .Po for example, |
| .Sy S-1-123-456-789 |
| .Pc |
| .El |
| .Pp |
| Files created on Linux always have POSIX owners. |
| .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none |
| The |
| .Sy userobjquota |
| is similar to |
| .Sy userquota |
| but it limits the number of objects a user can create. Please refer to |
| .Sy userobjused |
| for more information about how objects are counted. |
| .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none |
| Limits the amount of space consumed by the specified group. |
| Group space consumption is identified by the |
| .Sy groupused@ Ns Em group |
| property. |
| .Pp |
| Unprivileged users can access only their own groups' space usage. |
| The root user, or a user who has been granted the |
| .Sy groupquota |
| privilege with |
| .Nm zfs Cm allow , |
| can get and set all groups' quotas. |
| .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none |
| The |
| .Sy groupobjquota |
| is similar to |
| .Sy groupquota |
| but it limits number of objects a group can consume. Please refer to |
| .Sy userobjused |
| for more information about how objects are counted. |
| .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none |
| Limits the amount of space consumed by the specified project. Project |
| space consumption is identified by the |
| .Sy projectused@ Ns Em project |
| property. Please refer to |
| .Sy projectused |
| for more information about how project is identified and set/changed. |
| .Pp |
| The root user, or a user who has been granted the |
| .Sy projectquota |
| privilege with |
| .Nm zfs allow , |
| can access all projects' quota. |
| .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none |
| The |
| .Sy projectobjquota |
| is similar to |
| .Sy projectquota |
| but it limits number of objects a project can consume. Please refer to |
| .Sy userobjused |
| for more information about how objects are counted. |
| .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether this dataset can be modified. |
| The default value is |
| .Sy off . |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy ro |
| and |
| .Sy rw |
| mount options. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy rdonly . |
| .It Sy recordsize Ns = Ns Em size |
| 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 tunes block sizes according to internal algorithms optimized |
| for typical access patterns. |
| .Pp |
| For databases that create very large files but access them in small random |
| chunks, these algorithms may be suboptimal. |
| Specifying a |
| .Sy 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. |
| .Pp |
| The size specified must be a power of two greater than or equal to 512 and less |
| than or equal to 128 Kbytes. |
| If the |
| .Sy large_blocks |
| feature is enabled on the pool, the size may be up to 1 Mbyte. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags. |
| .Pp |
| Changing the file system's |
| .Sy recordsize |
| affects only files created afterward; existing files are unaffected. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy recsize . |
| .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most |
| Controls what types of metadata are stored redundantly. |
| ZFS stores an extra copy of metadata, so that if a single block is corrupted, |
| the amount of user data lost is limited. |
| This extra copy is in addition to any redundancy provided at the pool level |
| .Pq e.g. by mirroring or RAID-Z , |
| and is in addition to an extra copy specified by the |
| .Sy copies |
| property |
| .Pq up to a total of 3 copies . |
| For example if the pool is mirrored, |
| .Sy copies Ns = Ns 2 , |
| and |
| .Sy redundant_metadata Ns = Ns Sy most , |
| then ZFS stores 6 copies of most metadata, and 4 copies of data and some |
| metadata. |
| .Pp |
| When set to |
| .Sy all , |
| ZFS stores an extra copy of all metadata. |
| If a single on-disk block is corrupt, at worst a single block of user data |
| .Po which is |
| .Sy recordsize |
| bytes long |
| .Pc |
| can be lost. |
| .Pp |
| When set to |
| .Sy most , |
| ZFS stores an extra copy of most types of metadata. |
| This can improve performance of random writes, because less metadata must be |
| written. |
| In practice, at worst about 100 blocks |
| .Po of |
| .Sy recordsize |
| bytes each |
| .Pc |
| of user data can be lost if a single on-disk block is corrupt. |
| The exact behavior of which metadata blocks are stored redundantly may change in |
| future releases. |
| .Pp |
| The default value is |
| .Sy all . |
| .It Sy refquota Ns = Ns Em size Ns | Ns Sy none |
| Limits the amount of space a dataset can consume. |
| This property enforces a hard limit on the amount of space used. |
| This hard limit does not include space used by descendents, including file |
| systems and snapshots. |
| .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto |
| The minimum amount of space guaranteed to a dataset, not including its |
| descendents. |
| When the amount of space used is below this value, the dataset is treated as if |
| it were taking up the amount of space specified by |
| .Sy refreservation . |
| The |
| .Sy refreservation |
| reservation is accounted for in the parent datasets' space used, and counts |
| against the parent datasets' quotas and reservations. |
| .Pp |
| If |
| .Sy refreservation |
| is set, a snapshot is only allowed if there is enough free pool space outside of |
| this reservation to accommodate the current number of |
| .Qq referenced |
| bytes in the dataset. |
| .Pp |
| If |
| .Sy refreservation |
| is set to |
| .Sy auto , |
| a volume is thick provisioned |
| .Po or |
| .Qq not sparse |
| .Pc . |
| .Sy refreservation Ns = Ns Sy auto |
| is only supported on volumes. |
| See |
| .Sy volsize |
| in the |
| .Sx Native Properties |
| section for more information about sparse volumes. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy refreserv . |
| .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off |
| Controls the manner in which the access time is updated when |
| .Sy atime=on |
| is set. Turning this property on causes the access time to be updated relative |
| to the modify or change time. Access time is only updated if the previous |
| access time was earlier than the current modify or change time or if the |
| existing access time hasn't been updated within the past 24 hours. The default |
| value is |
| .Sy off . |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy relatime |
| and |
| .Sy norelatime |
| mount options. |
| .It Sy reservation Ns = Ns Em size Ns | Ns Sy none |
| The minimum amount of space guaranteed to a dataset and its descendants. |
| When the amount of space used is below this value, the dataset is treated as if |
| it were taking up the amount of space specified by its reservation. |
| Reservations are accounted for in the parent datasets' space used, and count |
| against the parent datasets' quotas and reservations. |
| .Pp |
| This property can also be referred to by its shortened column name, |
| .Sy reserv . |
| .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata |
| Controls what is cached in the secondary cache |
| .Pq L2ARC . |
| If this property is set to |
| .Sy all , |
| then both user data and metadata is cached. |
| If this property is set to |
| .Sy none , |
| then neither user data nor metadata is cached. |
| If this property is set to |
| .Sy metadata , |
| then only metadata is cached. |
| The default value is |
| .Sy all . |
| .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether the setuid bit is respected for the file system. |
| The default value is |
| .Sy on . |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy suid |
| and |
| .Sy nosuid |
| mount options. |
| .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts |
| Controls whether the file system is shared by using |
| .Sy Samba USERSHARES |
| and what options are to be used. Otherwise, the file system is automatically |
| shared and unshared with the |
| .Nm zfs Cm share |
| and |
| .Nm zfs Cm unshare |
| commands. If the property is set to on, the |
| .Xr net 8 |
| command is invoked to create a |
| .Sy USERSHARE . |
| .Pp |
| 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 |
| invalid in the resource name, are replaced with underscore (_) characters. |
| Linux does not currently support additional options which might be available |
| on Solaris. |
| .Pp |
| If the |
| .Sy sharesmb |
| property is set to |
| .Sy off , |
| the file systems are unshared. |
| .Pp |
| The share is created with the ACL (Access Control List) "Everyone:F" ("F" |
| stands for "full permissions", ie. read and write permissions) and no guest |
| access (which means Samba must be able to authenticate a real user, system |
| passwd/shadow, LDAP or smbpasswd based) by default. This means that any |
| additional access control (disallow specific user specific access etc) must |
| be done on the underlying file system. |
| .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts |
| Controls whether the file system is shared via NFS, and what options are to be |
| used. |
| A file system with a |
| .Sy sharenfs |
| property of |
| .Sy off |
| is managed with the |
| .Xr exportfs 8 |
| command and entries in the |
| .Em /etc/exports |
| file. |
| Otherwise, the file system is automatically shared and unshared with the |
| .Nm zfs Cm share |
| and |
| .Nm zfs Cm unshare |
| commands. |
| If the property is set to |
| .Sy on , |
| the dataset is shared using the default options: |
| .Pp |
| .Em sec=sys,rw,crossmnt,no_subtree_check |
| .Pp |
| See |
| .Xr exports 5 |
| for the meaning of the default options. Otherwise, the |
| .Xr exportfs 8 |
| command is invoked with options equivalent to the contents of this property. |
| .Pp |
| When the |
| .Sy sharenfs |
| 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 |
| .Sy off , |
| or if they were shared before the property was changed. |
| If the new property is |
| .Sy off , |
| the file systems are unshared. |
| .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput |
| Provide a hint to ZFS about handling of synchronous requests in this dataset. |
| If |
| .Sy logbias |
| is set to |
| .Sy latency |
| .Pq the default , |
| ZFS will use pool log devices |
| .Pq if configured |
| to handle the requests at low latency. |
| If |
| .Sy logbias |
| is set to |
| .Sy throughput , |
| ZFS will not use configured pool log devices. |
| ZFS will instead optimize synchronous operations for global pool throughput and |
| efficient use of resources. |
| .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible |
| Controls whether the volume snapshot devices under |
| .Em /dev/zvol/<pool> |
| are hidden or visible. The default value is |
| .Sy hidden . |
| .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible |
| Controls whether the |
| .Pa .zfs |
| directory is hidden or visible in the root of the file system as discussed in |
| the |
| .Sx Snapshots |
| section. |
| The default value is |
| .Sy hidden . |
| .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled |
| Controls the behavior of synchronous requests |
| .Pq e.g. fsync, O_DSYNC . |
| .Sy standard |
| is the |
| .Tn POSIX |
| specified behavior of ensuring all synchronous requests are written to stable |
| storage and all devices are flushed to ensure data is not cached by device |
| controllers |
| .Pq this is the default . |
| .Sy always |
| causes every file system transaction to be written and flushed before its |
| system call returns. |
| This has a large performance penalty. |
| .Sy disabled |
| disables synchronous requests. |
| File system transactions are only committed to stable storage periodically. |
| This option will give the highest performance. |
| However, it is very dangerous as ZFS would be ignoring the synchronous |
| transaction demands of applications such as databases or NFS. |
| Administrators should only use this option when the risks are understood. |
| .It Sy version Ns = Ns Em N Ns | Ns Sy current |
| The on-disk version of this file system, which is independent of the pool |
| version. |
| This property can only be set to later supported versions. |
| See the |
| .Nm zfs Cm upgrade |
| command. |
| .It Sy volsize Ns = Ns Em size |
| For volumes, specifies the logical size of the volume. |
| By default, creating a volume establishes a reservation of equal size. |
| For storage pools with a version number of 9 or higher, a |
| .Sy refreservation |
| is set instead. |
| Any changes to |
| .Sy volsize |
| are reflected in an equivalent change to the reservation |
| .Po or |
| .Sy refreservation |
| .Pc . |
| The |
| .Sy volsize |
| can only be set to a multiple of |
| .Sy volblocksize , |
| and cannot be zero. |
| .Pp |
| The reservation is kept equal to the volume's logical size to prevent unexpected |
| behavior for consumers. |
| Without the reservation, the volume could run out of space, resulting 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 |
| .Pq particularly when shrinking the size . |
| Extreme care should be used when adjusting the volume size. |
| .Pp |
| Though not recommended, a |
| .Qq sparse volume |
| .Po also known as |
| .Qq thin provisioned |
| .Pc |
| can be created by specifying the |
| .Fl s |
| option to the |
| .Nm zfs Cm create Fl V |
| command, or by changing the value of the |
| .Sy refreservation |
| property |
| .Po or |
| .Sy reservation |
| property on pool version 8 or earlier |
| .Pc |
| after the volume has been created. |
| A |
| .Qq sparse volume |
| is a volume where the value of |
| .Sy refreservation |
| is less than the size of the volume plus the space required to store its |
| metadata. |
| Consequently, writes to a sparse volume can fail with |
| .Er ENOSPC |
| when the pool is low on space. |
| For a sparse volume, changes to |
| .Sy volsize |
| are not reflected in the |
| .Sy refreservation. |
| A volume that is not sparse is said to be |
| .Qq thick provisioned . |
| A sparse volume can become thick provisioned by setting |
| .Sy refreservation |
| to |
| .Sy auto . |
| .It Sy volmode Ns = Ns Cm default | full | geom | dev | none |
| This property specifies how volumes should be exposed to the OS. |
| Setting it to |
| .Sy full |
| exposes volumes as fully fledged block devices, providing maximal |
| functionality. The value |
| .Sy geom |
| is just an alias for |
| .Sy full |
| and is kept for compatibility. |
| Setting it to |
| .Sy dev |
| hides its partitions. |
| Volumes with property set to |
| .Sy none |
| are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc, |
| that can be suitable for backup purposes. |
| Value |
| .Sy default |
| means that volumes exposition is controlled by system-wide tunable |
| .Va zvol_volmode , |
| where |
| .Sy full , |
| .Sy dev |
| and |
| .Sy none |
| are encoded as 1, 2 and 3 respectively. |
| The default values is |
| .Sy full . |
| .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether regular files should be scanned for viruses when a file is |
| opened and closed. |
| In addition to enabling this property, the virus scan service must also be |
| enabled for virus scanning to occur. |
| The default value is |
| .Sy off . |
| This property is not used on Linux. |
| .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa |
| Controls whether extended attributes are enabled for this file system. Two |
| styles of extended attributes are supported either directory based or system |
| attribute based. |
| .Pp |
| The default value of |
| .Sy on |
| enables directory based extended attributes. This style of extended attribute |
| imposes no practical limit on either the size or number of attributes which |
| can be set on a file. Although under Linux the |
| .Xr getxattr 2 |
| and |
| .Xr setxattr 2 |
| system calls limit the maximum size to 64K. This is the most compatible |
| style of extended attribute and is supported by all OpenZFS implementations. |
| .Pp |
| System attribute based xattrs can be enabled by setting the value to |
| .Sy sa . |
| The key advantage of this type of xattr is improved performance. Storing |
| extended attributes as system attributes significantly decreases the amount of |
| disk IO required. Up to 64K of data may be stored per-file in the space |
| reserved for system attributes. If there is not enough space available for |
| an extended attribute then it will be automatically written as a directory |
| based xattr. System attribute based extended attributes are not accessible |
| on platforms which do not support the |
| .Sy xattr=sa |
| feature. |
| .Pp |
| The use of system attribute based xattrs is strongly encouraged for users of |
| SELinux or POSIX ACLs. Both of these features heavily rely of extended |
| attributes and benefit significantly from the reduced access time. |
| .Pp |
| The values |
| .Sy on |
| and |
| .Sy off |
| are equivalent to the |
| .Sy xattr |
| and |
| .Sy noxattr |
| mount options. |
| .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off |
| Controls whether the dataset is managed from a non-global zone. Zones are a |
| Solaris feature and are not relevant on Linux. The default value is |
| .Sy off . |
| .El |
| .Pp |
| The following three properties cannot be changed after the file system is |
| created, and therefore, should be set when the file system is created. |
| If the properties are not set with the |
| .Nm zfs Cm create |
| or |
| .Nm zpool Cm create |
| commands, these properties are inherited from the parent dataset. |
| If the parent dataset lacks these properties due to having been created prior to |
| these features being supported, the new file system will have the default values |
| for these properties. |
| .Bl -tag -width "" |
| .It Xo |
| .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns |
| .Sy insensitive Ns | Ns Sy mixed |
| .Xc |
| Indicates whether the file name matching algorithm used by the file system |
| should be case-sensitive, case-insensitive, or allow a combination of both |
| styles of matching. |
| The default value for the |
| .Sy casesensitivity |
| property is |
| .Sy sensitive . |
| Traditionally, |
| .Ux |
| and |
| .Tn POSIX |
| file systems have case-sensitive file names. |
| .Pp |
| The |
| .Sy mixed |
| value for the |
| .Sy casesensitivity |
| property indicates that the file system can support requests for both |
| case-sensitive and case-insensitive matching behavior. |
| Currently, case-insensitive matching behavior on a file system that supports |
| mixed behavior is limited to the SMB server product. |
| For more information about the |
| .Sy mixed |
| value behavior, see the "ZFS Administration Guide". |
| .It Xo |
| .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns |
| .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD |
| .Xc |
| Indicates whether the file system should perform a |
| .Sy unicode |
| normalization of file names whenever two file names are compared, and which |
| normalization algorithm should be used. |
| File names are always stored unmodified, names are normalized as part of any |
| comparison process. |
| If this property is set to a legal value other than |
| .Sy none , |
| and the |
| .Sy utf8only |
| property was left unspecified, the |
| .Sy utf8only |
| property is automatically set to |
| .Sy on . |
| The default value of the |
| .Sy normalization |
| property is |
| .Sy none . |
| This property cannot be changed after the file system is created. |
| .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off |
| Indicates whether the file system should reject file names that include |
| characters that are not present in the |
| .Sy UTF-8 |
| character code set. |
| If this property is explicitly set to |
| .Sy off , |
| the normalization property must either not be explicitly set or be set to |
| .Sy none . |
| The default value for the |
| .Sy utf8only |
| property is |
| .Sy off . |
| This property cannot be changed after the file system is created. |
| .El |
| .Pp |
| The |
| .Sy casesensitivity , |
| .Sy normalization , |
| and |
| .Sy utf8only |
| properties are also new permissions that can be assigned to non-privileged users |
| by using the ZFS delegated administration feature. |
| .Ss "Temporary Mount Point Properties" |
| When a file system is mounted, either through |
| .Xr mount 8 |
| for legacy mounts or the |
| .Nm zfs Cm mount |
| command for normal file systems, its mount options are set according to its |
| properties. |
| The correlation between properties and mount options is as follows: |
| .Bd -literal |
| PROPERTY MOUNT OPTION |
| atime atime/noatime |
| canmount auto/noauto |
| devices dev/nodev |
| exec exec/noexec |
| readonly ro/rw |
| relatime relatime/norelatime |
| setuid suid/nosuid |
| xattr xattr/noxattr |
| .Ed |
| .Pp |
| In addition, these options can be set on a per-mount basis using the |
| .Fl o |
| option, without affecting the property that is stored on disk. |
| The values specified on the command line override the values stored in the |
| dataset. |
| The |
| .Sy nosuid |
| option is an alias for |
| .Sy nodevices Ns \&, Ns Sy nosetuid . |
| These properties are reported as |
| .Qq temporary |
| by the |
| .Nm zfs Cm get |
| command. |
| If the properties are changed while the dataset is mounted, the new setting |
| overrides any temporary settings. |
| .Ss "User Properties" |
| In addition to the standard native properties, ZFS supports arbitrary user |
| properties. |
| User properties have no effect on ZFS behavior, but applications or |
| administrators can use them to annotate datasets |
| .Pq file systems, volumes, and snapshots . |
| .Pp |
| User property names must contain a colon |
| .Pq Qq Sy \&: |
| character to distinguish them from native properties. |
| They may contain lowercase letters, numbers, and the following punctuation |
| characters: colon |
| .Pq Qq Sy \&: , |
| dash |
| .Pq Qq Sy - , |
| period |
| .Pq Qq Sy \&. , |
| and underscore |
| .Pq Qq Sy _ . |
| The expected convention is that the property name is divided into two portions |
| such as |
| .Em module Ns \&: Ns Em property , |
| but this namespace is not enforced by ZFS. |
| User property names can be at most 256 characters, and cannot begin with a dash |
| .Pq Qq Sy - . |
| .Pp |
| When making programmatic use of user properties, it is strongly suggested to use |
| a reversed |
| .Sy DNS |
| domain name for the |
| .Em module |
| component of property names to reduce the chance that two |
| independently-developed packages use the same property name for different |
| purposes. |
| .Pp |
| The values of user properties are arbitrary strings, are always inherited, and |
| are never validated. |
| All of the commands that operate on properties |
| .Po Nm zfs Cm list , |
| .Nm zfs Cm get , |
| .Nm zfs Cm set , |
| and so forth |
| .Pc |
| can be used to manipulate both native properties and user properties. |
| Use the |
| .Nm zfs Cm inherit |
| command to clear a user property. |
| If the property is not defined in any parent dataset, it is removed entirely. |
| Property values are limited to 8192 bytes. |
| .Ss ZFS Volumes as Swap |
| ZFS volumes may be used as swap devices. After creating the volume with the |
| .Nm zfs Cm create Fl V |
| command set up and enable the swap area using the |
| .Xr mkswap 8 |
| and |
| .Xr swapon 8 |
| commands. Do not swap to a file on a ZFS file system. A ZFS swap file |
| configuration is not supported. |
| .Ss Encryption |
| Enabling the |
| .Sy encryption |
| feature allows for the creation of encrypted filesystems and volumes. ZFS |
| will encrypt file and zvol data, file attributes, ACLs, permission bits, |
| directory listings, FUID mappings, and |
| .Sy userused |
| / |
| .Sy groupused |
| data. ZFS will not encrypt metadata related to the pool structure, including |
| dataset and snapshot names, dataset hierarchy, properties, file size, file |
| holes, and deduplication tables (though the deduplicated data itself is |
| encrypted). |
| .Pp |
| Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) |
| does not require re-encrypting the entire dataset. Datasets can be scrubbed, |
| resilvered, renamed, and deleted without the encryption keys being loaded (see the |
| .Nm zfs Cm load-key |
| subcommand for more info on key loading). |
| .Pp |
| Creating an encrypted dataset requires specifying the |
| .Sy encryption |
| and |
| .Sy keyformat |
| properties at creation time, along with an optional |
| .Sy keylocation |
| and |
| .Sy pbkdf2iters . |
| After entering an encryption key, the |
| created dataset will become an encryption root. Any descendant datasets will |
| inherit their encryption key from the encryption root by default, meaning that |
| loading, unloading, or changing the key for the encryption root will implicitly |
| do the same for all inheriting datasets. If this inheritance is not desired, |
| simply supply a |
| .Sy keyformat |
| when creating the child dataset or use |
| .Nm zfs Cm change-key |
| to break an existing relationship, creating a new encryption root on the child. |
| Note that the child's |
| .Sy keyformat |
| may match that of the parent while still creating a new encryption root, and |
| that changing the |
| .Sy encryption |
| property alone does not create a new encryption root; this would simply use a |
| different cipher suite with the same key as its encryption root. The one |
| exception is that clones will always use their origin's encryption key. |
| As a result of this exception, some encryption-related properties (namely |
| .Sy keystatus , |
| .Sy keyformat , |
| .Sy keylocation , |
| and |
| .Sy pbkdf2iters ) |
| do not inherit like other ZFS properties and instead use the value determined |
| by their encryption root. Encryption root inheritance can be tracked via the |
| read-only |
| .Sy encryptionroot |
| property. |
| .Pp |
| Encryption changes the behavior of a few ZFS |
| operations. Encryption is applied after compression so compression ratios are |
| preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data |
| the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from |
| the encryption suite, which provides additional protection against maliciously |
| altered data. Deduplication is still possible with encryption enabled but for |
| security, datasets will only dedup against themselves, their snapshots, and |
| their clones. |
| .Pp |
| There are a few limitations on encrypted datasets. Encrypted data cannot be |
| embedded via the |
| .Sy embedded_data |
| feature. Encrypted datasets may not have |
| .Sy copies Ns = Ns Em 3 |
| since the implementation stores some encryption metadata where the third copy |
| would normally be. Since compression is applied before encryption datasets may |
| be vulnerable to a CRIME-like attack if applications accessing the data allow |
| for it. Deduplication with encryption will leak information about which blocks |
| are equivalent in a dataset and will incur an extra CPU cost per block written. |
| .Sh SUBCOMMANDS |
| All subcommands that modify state are logged persistently to the pool in their |
| original form. |
| .Bl -tag -width "" |
| .It Nm Fl ? |
| Displays a help message. |
| .It Xo |
| .Nm |
| .Fl V, -version |
| .Xc |
| An alias for the |
| .Nm zfs Cm version |
| subcommand. |
| .It Xo |
| .Nm |
| .Cm create |
| .Op Fl p |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem |
| .Xc |
| Creates a new ZFS file system. |
| The file system is automatically mounted according to the |
| .Sy mountpoint |
| property inherited from the parent. |
| .Bl -tag -width "-o" |
| .It Fl o Ar property Ns = Ns Ar value |
| Sets the specified property as if the command |
| .Nm zfs Cm set Ar property Ns = Ns Ar value |
| was invoked at the same time the dataset was created. |
| Any editable ZFS property can also be set at creation time. |
| Multiple |
| .Fl o |
| options can be specified. |
| An error results if the same property is specified in multiple |
| .Fl o |
| options. |
| .It Fl p |
| Creates all the non-existing parent datasets. |
| Datasets created in this manner are automatically mounted according to the |
| .Sy mountpoint |
| property inherited from their parent. |
| Any property specified on the command line using the |
| .Fl o |
| option is ignored. |
| If the target filesystem already exists, the operation completes successfully. |
| .El |
| .It Xo |
| .Nm |
| .Cm create |
| .Op Fl ps |
| .Op Fl b Ar blocksize |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Fl V Ar size Ar volume |
| .Xc |
| Creates a volume of the given size. |
| The volume is exported as a block device in |
| .Pa /dev/zvol/path , |
| where |
| .Em path |
| is the name of the volume in the ZFS namespace. |
| The size represents the logical size as exported by the device. |
| By default, a reservation of equal size is created. |
| .Pp |
| .Ar size |
| is automatically rounded up to the nearest 128 Kbytes to ensure that the volume |
| has an integral number of blocks regardless of |
| .Sy blocksize . |
| .Bl -tag -width "-b" |
| .It Fl b Ar blocksize |
| Equivalent to |
| .Fl o Sy volblocksize Ns = Ns Ar blocksize . |
| If this option is specified in conjunction with |
| .Fl o Sy volblocksize , |
| the resulting behavior is undefined. |
| .It Fl o Ar property Ns = Ns Ar value |
| Sets the specified property as if the |
| .Nm zfs Cm set Ar property Ns = Ns Ar value |
| command was invoked at the same time the dataset was created. |
| Any editable ZFS property can also be set at creation time. |
| Multiple |
| .Fl o |
| options can be specified. |
| An error results if the same property is specified in multiple |
| .Fl o |
| options. |
| .It Fl p |
| Creates all the non-existing parent datasets. |
| Datasets created in this manner are automatically mounted according to the |
| .Sy mountpoint |
| property inherited from their parent. |
| Any property specified on the command line using the |
| .Fl o |
| option is ignored. |
| If the target filesystem already exists, the operation completes successfully. |
| .It Fl s |
| Creates a sparse volume with no reservation. |
| See |
| .Sy volsize |
| in the |
| .Sx Native Properties |
| section for more information about sparse volumes. |
| .El |
| .It Xo |
| .Nm |
| .Cm destroy |
| .Op Fl Rfnprv |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Destroys the given dataset. |
| By default, the command unshares any file systems that are currently shared, |
| unmounts any file systems that are currently mounted, and refuses to destroy a |
| dataset that has active dependents |
| .Pq children or clones . |
| .Bl -tag -width "-R" |
| .It Fl R |
| Recursively destroy all dependents, including cloned file systems outside the |
| target hierarchy. |
| .It Fl f |
| Force an unmount of any file systems using the |
| .Nm unmount Fl f |
| command. |
| This option has no effect on non-file systems or unmounted file systems. |
| .It Fl n |
| Do a dry-run |
| .Pq Qq No-op |
| deletion. |
| No data will be deleted. |
| This is useful in conjunction with the |
| .Fl v |
| or |
| .Fl p |
| flags to determine what data would be deleted. |
| .It Fl p |
| Print machine-parsable verbose information about the deleted data. |
| .It Fl r |
| Recursively destroy all children. |
| .It Fl v |
| Print verbose information about the deleted data. |
| .El |
| .Pp |
| Extreme care should be taken when applying either the |
| .Fl r |
| or the |
| .Fl R |
| options, as they can destroy large portions of a pool and cause unexpected |
| behavior for mounted file systems in use. |
| .It Xo |
| .Nm |
| .Cm destroy |
| .Op Fl Rdnprv |
| .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns |
| .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... |
| .Xc |
| The given snapshots are destroyed immediately if and only if the |
| .Nm zfs Cm destroy |
| command without the |
| .Fl d |
| option would have destroyed it. |
| Such immediate destruction would occur, for example, if the snapshot had no |
| clones and the user-initiated reference count were zero. |
| .Pp |
| If a snapshot does not qualify for immediate destruction, it is marked for |
| deferred deletion. |
| In this state, it exists as a usable, visible snapshot until both of the |
| preconditions listed above are met, at which point it is destroyed. |
| .Pp |
| An inclusive range of snapshots may be specified by separating the first and |
| last snapshots with a percent sign. |
| The first and/or last snapshots may be left blank, in which case the |
| filesystem's oldest or newest snapshot will be implied. |
| .Pp |
| Multiple snapshots |
| .Pq or ranges of snapshots |
| of the same filesystem or volume may be specified in a comma-separated list of |
| snapshots. |
| Only the snapshot's short name |
| .Po the part after the |
| .Sy @ |
| .Pc |
| should be specified when using a range or comma-separated list to identify |
| multiple snapshots. |
| .Bl -tag -width "-R" |
| .It Fl R |
| Recursively destroy all clones of these snapshots, including the clones, |
| snapshots, and children. |
| If this flag is specified, the |
| .Fl d |
| flag will have no effect. |
| .It Fl d |
| Destroy immediately. If a snapshot cannot be destroyed now, mark it for |
| deferred destruction. |
| .It Fl n |
| Do a dry-run |
| .Pq Qq No-op |
| deletion. |
| No data will be deleted. |
| This is useful in conjunction with the |
| .Fl p |
| or |
| .Fl v |
| flags to determine what data would be deleted. |
| .It Fl p |
| Print machine-parsable verbose information about the deleted data. |
| .It Fl r |
| Destroy |
| .Pq or mark for deferred deletion |
| all snapshots with this name in descendent file systems. |
| .It Fl v |
| Print verbose information about the deleted data. |
| .Pp |
| Extreme care should be taken when applying either the |
| .Fl r |
| or the |
| .Fl R |
| options, as they can destroy large portions of a pool and cause unexpected |
| behavior for mounted file systems in use. |
| .El |
| .It Xo |
| .Nm |
| .Cm destroy |
| .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark |
| .Xc |
| The given bookmark is destroyed. |
| .It Xo |
| .Nm |
| .Cm snapshot |
| .Op Fl r |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... |
| .Xc |
| Creates snapshots with the given names. |
| All previous modifications by successful system calls to the file system are |
| part of the snapshots. |
| Snapshots are taken atomically, so that all snapshots correspond to the same |
| moment in time. |
| .Nm zfs Cm snap |
| can be used as an alias for |
| .Nm zfs Cm snapshot. |
| See the |
| .Sx Snapshots |
| section for details. |
| .Bl -tag -width "-o" |
| .It Fl o Ar property Ns = Ns Ar value |
| Sets the specified property; see |
| .Nm zfs Cm create |
| for details. |
| .It Fl r |
| Recursively create snapshots of all descendent datasets |
| .El |
| .It Xo |
| .Nm |
| .Cm rollback |
| .Op Fl Rfr |
| .Ar snapshot |
| .Xc |
| Roll back the given dataset to a previous snapshot. |
| When a dataset is rolled back, all data that has changed since the snapshot is |
| discarded, and the dataset reverts to the state at the time of the snapshot. |
| By default, the command refuses to roll back to a snapshot other than the most |
| recent one. |
| In order to do so, all intermediate snapshots and bookmarks must be destroyed by |
| specifying the |
| .Fl r |
| option. |
| .Pp |
| The |
| .Fl rR |
| options do not recursively destroy the child snapshots of a recursive snapshot. |
| Only direct snapshots of the specified filesystem are destroyed by either of |
| these options. |
| To completely roll back a recursive snapshot, you must rollback the individual |
| child snapshots. |
| .Bl -tag -width "-R" |
| .It Fl R |
| Destroy any more recent snapshots and bookmarks, as well as any clones of those |
| snapshots. |
| .It Fl f |
| Used with the |
| .Fl R |
| option to force an unmount of any clone file systems that are to be destroyed. |
| .It Fl r |
| Destroy any snapshots and bookmarks more recent than the one specified. |
| .El |
| .It Xo |
| .Nm |
| .Cm clone |
| .Op Fl p |
| .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar snapshot Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Creates a clone of the given snapshot. |
| See the |
| .Sx Clones |
| section for details. |
| The target dataset can be located anywhere in the ZFS hierarchy, and is created |
| as the same type as the original. |
| .Bl -tag -width "-o" |
| .It Fl o Ar property Ns = Ns Ar value |
| Sets the specified property; see |
| .Nm zfs Cm create |
| for details. |
| .It Fl p |
| Creates all the non-existing parent datasets. |
| Datasets created in this manner are automatically mounted according to the |
| .Sy mountpoint |
| property inherited from their parent. |
| If the target filesystem or volume already exists, the operation completes |
| successfully. |
| .El |
| .It Xo |
| .Nm |
| .Cm promote |
| .Ar clone-filesystem |
| .Xc |
| Promotes a clone file system to no longer be dependent on its |
| .Qq origin |
| snapshot. |
| This makes it possible to destroy the file system that the clone was created |
| from. |
| The clone parent-child dependency relationship is reversed, so that the origin |
| file system becomes a clone of the specified file system. |
| .Pp |
| The snapshot that was cloned, and any snapshots previous to this snapshot, are |
| now owned by the promoted clone. |
| The space they use moves from the origin file system to the promoted clone, so |
| enough space must be available to accommodate these snapshots. |
| No new space is consumed by this operation, but the space accounting is |
| adjusted. |
| The promoted clone must not have any conflicting snapshot names of its own. |
| The |
| .Cm rename |
| subcommand can be used to rename any conflicting snapshots. |
| .It Xo |
| .Nm |
| .Cm rename |
| .Op Fl f |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Xc |
| .It Xo |
| .Nm |
| .Cm rename |
| .Op Fl fp |
| .Ar filesystem Ns | Ns Ar volume |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Renames the given dataset. |
| The new target can be located anywhere in the ZFS hierarchy, with the exception |
| of snapshots. |
| Snapshots can only be renamed within the parent file system or volume. |
| When renaming a snapshot, the parent file system of the snapshot does not need |
| to be specified as part of the second argument. |
| Renamed file systems can inherit new mount points, in which case they are |
| unmounted and remounted at the new mount point. |
| .Bl -tag -width "-a" |
| .It Fl f |
| Force unmount any filesystems that need to be unmounted in the process. |
| .It Fl p |
| Creates all the nonexistent parent datasets. |
| Datasets created in this manner are automatically mounted according to the |
| .Sy mountpoint |
| property inherited from their parent. |
| .El |
| .It Xo |
| .Nm |
| .Cm rename |
| .Fl r |
| .Ar snapshot Ar snapshot |
| .Xc |
| Recursively rename the snapshots of all descendent datasets. |
| Snapshots are the only dataset that can be renamed recursively. |
| .It Xo |
| .Nm |
| .Cm list |
| .Op Fl r Ns | Ns Fl d Ar depth |
| .Op Fl Hp |
| .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc |
| .Oo Fl s Ar property Oc Ns ... |
| .Oo Fl S Ar property Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... |
| .Xc |
| Lists the property information for the given datasets in tabular form. |
| If specified, you can list property information by the absolute pathname or the |
| relative pathname. |
| By default, all file systems and volumes are displayed. |
| Snapshots are displayed if the |
| .Sy listsnaps |
| property is |
| .Sy on |
| .Po the default is |
| .Sy off |
| .Pc . |
| The following fields are displayed: |
| .Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns . |
| .Bl -tag -width "-H" |
| .It Fl H |
| Used for scripting mode. |
| Do not print headers and separate fields by a single tab instead of arbitrary |
| white space. |
| .It Fl S Ar property |
| Same as the |
| .Fl s |
| option, but sorts by property in descending order. |
| .It Fl d Ar depth |
| Recursively display any children of the dataset, limiting the recursion to |
| .Ar depth . |
| A |
| .Ar depth |
| of |
| .Sy 1 |
| will display only the dataset and its direct children. |
| .It Fl o Ar property |
| A comma-separated list of properties to display. |
| The property must be: |
| .Bl -bullet |
| .It |
| One of the properties described in the |
| .Sx Native Properties |
| section |
| .It |
| A user property |
| .It |
| The value |
| .Sy name |
| to display the dataset name |
| .It |
| The value |
| .Sy space |
| to display space usage properties on file systems and volumes. |
| This is a shortcut for specifying |
| .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns |
| .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t |
| .Sy filesystem Ns \&, Ns Sy volume |
| syntax. |
| .El |
| .It Fl p |
| Display numbers in parsable |
| .Pq exact |
| values. |
| .It Fl r |
| Recursively display any children of the dataset on the command line. |
| .It Fl s Ar property |
| A property for sorting the output by column in ascending order based on the |
| value of the property. |
| The property must be one of the properties described in the |
| .Sx Properties |
| section or the value |
| .Sy name |
| to sort by the dataset name. |
| Multiple properties can be specified at one time using multiple |
| .Fl s |
| property options. |
| Multiple |
| .Fl s |
| options are evaluated from left to right in decreasing order of importance. |
| The following is a list of sorting criteria: |
| .Bl -bullet |
| .It |
| Numeric types sort in numeric order. |
| .It |
| String types sort in alphabetical order. |
| .It |
| Types inappropriate for a row sort that row to the literal bottom, regardless of |
| the specified ordering. |
| .El |
| .Pp |
| If no sorting options are specified the existing behavior of |
| .Nm zfs Cm list |
| is preserved. |
| .It Fl t Ar type |
| A comma-separated list of types to display, where |
| .Ar type |
| is one of |
| .Sy filesystem , |
| .Sy snapshot , |
| .Sy volume , |
| .Sy bookmark , |
| or |
| .Sy all . |
| For example, specifying |
| .Fl t Sy snapshot |
| displays only snapshots. |
| .El |
| .It Xo |
| .Nm |
| .Cm set |
| .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... |
| .Xc |
| Sets the property or list of properties to the given value(s) for each dataset. |
| Only some properties can be edited. |
| See the |
| .Sx Properties |
| section for more information on what properties can be set and acceptable |
| values. |
| Numeric values can be specified as exact values, or in a human-readable form |
| with a suffix of |
| .Sy B , K , M , G , T , P , E , Z |
| .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, |
| or zettabytes, respectively |
| .Pc . |
| User properties can be set on snapshots. |
| For more information, see the |
| .Sx User Properties |
| section. |
| .It Xo |
| .Nm |
| .Cm get |
| .Op Fl r Ns | Ns Fl d Ar depth |
| .Op Fl Hp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... |
| .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... |
| .Xc |
| Displays properties for the given datasets. |
| If no datasets are specified, then the command displays properties for all |
| datasets on the system. |
| For each property, the following columns are displayed: |
| .Bd -literal |
| name Dataset name |
| property Property name |
| value Property value |
| source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP, |
| \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP). |
| .Ed |
| .Pp |
| All columns are displayed by default, though this can be controlled by using the |
| .Fl o |
| option. |
| This command takes a comma-separated list of properties as described in the |
| .Sx Native Properties |
| and |
| .Sx User Properties |
| sections. |
| .Pp |
| The value |
| .Sy all |
| can be used to display all properties that apply to the given dataset's type |
| .Pq filesystem, volume, snapshot, or bookmark . |
| .Bl -tag -width "-H" |
| .It Fl H |
| Display output in a form more easily parsed by scripts. |
| Any headers are omitted, and fields are explicitly separated by a single tab |
| instead of an arbitrary amount of space. |
| .It Fl d Ar depth |
| Recursively display any children of the dataset, limiting the recursion to |
| .Ar depth . |
| A depth of |
| .Sy 1 |
| will display only the dataset and its direct children. |
| .It Fl o Ar field |
| A comma-separated list of columns to display. |
| .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source |
| is the default value. |
| .It Fl p |
| Display numbers in parsable |
| .Pq exact |
| values. |
| .It Fl r |
| Recursively display properties for any children. |
| .It Fl s Ar source |
| A comma-separated list of sources to display. |
| Those properties coming from a source other than those in this list are ignored. |
| Each source must be one of the following: |
| .Sy local , |
| .Sy default , |
| .Sy inherited , |
| .Sy temporary , |
| .Sy received , |
| and |
| .Sy none . |
| The default value is all sources. |
| .It Fl t Ar type |
| A comma-separated list of types to display, where |
| .Ar type |
| is one of |
| .Sy filesystem , |
| .Sy snapshot , |
| .Sy volume , |
| .Sy bookmark , |
| or |
| .Sy all . |
| .El |
| .It Xo |
| .Nm |
| .Cm inherit |
| .Op Fl rS |
| .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... |
| .Xc |
| Clears the specified property, causing it to be inherited from an ancestor, |
| restored to default if no ancestor has the property set, or with the |
| .Fl S |
| option reverted to the received value if one exists. |
| See the |
| .Sx Properties |
| section for a listing of default values, and details on which properties can be |
| inherited. |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively inherit the given property for all children. |
| .It Fl S |
| Revert the property to the received value if one exists; otherwise operate as |
| if the |
| .Fl S |
| option was not specified. |
| .El |
| .It Xo |
| .Nm |
| .Cm upgrade |
| .Xc |
| Displays a list of file systems that are not the most recent version. |
| .It Xo |
| .Nm |
| .Cm upgrade |
| .Fl v |
| .Xc |
| Displays a list of currently supported file system versions. |
| .It Xo |
| .Nm |
| .Cm upgrade |
| .Op Fl r |
| .Op Fl V Ar version |
| .Fl a | Ar filesystem |
| .Xc |
| Upgrades file systems to a new on-disk version. |
| Once this is done, the file systems will no longer be accessible on systems |
| running older versions of the software. |
| .Nm zfs Cm send |
| streams generated from new snapshots of these file systems cannot be accessed on |
| systems running older versions of the software. |
| .Pp |
| In general, the file system version is independent of the pool version. |
| See |
| .Xr zpool 8 |
| for information on the |
| .Nm zpool Cm upgrade |
| command. |
| .Pp |
| In some cases, the file system version and the pool version are interrelated and |
| the pool version must be upgraded before the file system version can be |
| upgraded. |
| .Bl -tag -width "-V" |
| .It Fl V Ar version |
| Upgrade to the specified |
| .Ar version . |
| If the |
| .Fl V |
| flag is not specified, this command upgrades to the most recent version. |
| This |
| option can only be used to increase the version number, and only up to the most |
| recent version supported by this software. |
| .It Fl a |
| Upgrade all file systems on all imported pools. |
| .It Ar filesystem |
| Upgrade the specified file system. |
| .It Fl r |
| Upgrade the specified file system and all descendent file systems. |
| .El |
| .It Xo |
| .Nm |
| .Cm userspace |
| .Op Fl Hinp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Xc |
| Displays space consumed by, and quotas on, each user in the specified filesystem |
| or snapshot. |
| This corresponds to the |
| .Sy userused@ Ns Em user , |
| .Sy userobjused@ Ns Em user , |
| .Sy userquota@ Ns Em user, |
| and |
| .Sy userobjquota@ Ns Em user |
| properties. |
| .Bl -tag -width "-H" |
| .It Fl H |
| Do not print headers, use tab-delimited output. |
| .It Fl S Ar field |
| Sort by this field in reverse order. |
| See |
| .Fl s . |
| .It Fl i |
| Translate SID to POSIX ID. |
| The POSIX ID may be ephemeral if no mapping exists. |
| Normal POSIX interfaces |
| .Po for example, |
| .Xr stat 2 , |
| .Nm ls Fl l |
| .Pc |
| perform this translation, so the |
| .Fl i |
| option allows the output from |
| .Nm zfs Cm userspace |
| to be compared directly with those utilities. |
| However, |
| .Fl i |
| may lead to confusion if some files were created by an SMB user before a |
| SMB-to-POSIX name mapping was established. |
| In such a case, some files will be owned by the SMB entity and some by the POSIX |
| entity. |
| However, the |
| .Fl i |
| option will report that the POSIX entity has the total usage and quota for both. |
| .It Fl n |
| Print numeric ID instead of user/group name. |
| .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... |
| Display only the specified fields from the following set: |
| .Sy type , |
| .Sy name , |
| .Sy used , |
| .Sy quota . |
| The default is to display all fields. |
| .It Fl p |
| Use exact |
| .Pq parsable |
| numeric output. |
| .It Fl s Ar field |
| Sort output by this field. |
| The |
| .Fl s |
| and |
| .Fl S |
| flags may be specified multiple times to sort first by one field, then by |
| another. |
| The default is |
| .Fl s Sy type Fl s Sy name . |
| .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... |
| Print only the specified types from the following set: |
| .Sy all , |
| .Sy posixuser , |
| .Sy smbuser , |
| .Sy posixgroup , |
| .Sy smbgroup . |
| The default is |
| .Fl t Sy posixuser Ns \&, Ns Sy smbuser . |
| The default can be changed to include group types. |
| .El |
| .It Xo |
| .Nm |
| .Cm groupspace |
| .Op Fl Hinp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Xc |
| Displays space consumed by, and quotas on, each group in the specified |
| filesystem or snapshot. |
| This subcommand is identical to |
| .Nm zfs Cm userspace , |
| except that the default types to display are |
| .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . |
| .It Xo |
| .Nm |
| .Cm projectspace |
| .Op Fl Hp |
| .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc |
| .Oo Fl s Ar field Oc Ns ... |
| .Oo Fl S Ar field Oc Ns ... |
| .Ar filesystem Ns | Ns Ar snapshot |
| .Xc |
| Displays space consumed by, and quotas on, each project in the specified |
| filesystem or snapshot. This subcommand is identical to |
| .Nm zfs Cm userspace , |
| except that the project identifier is numeral, not name. So need neither |
| the option |
| .Sy -i |
| for SID to POSIX ID nor |
| .Sy -n |
| for numeric ID, nor |
| .Sy -t |
| for types. |
| .It Xo |
| .Nm |
| .Cm project |
| .Oo Fl d Ns | Ns Fl r Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Xc |
| List project identifier (ID) and inherit flag of file(s) or directories. |
| .Bl -tag -width "-d" |
| .It Fl d |
| Show the directory project ID and inherit flag, not its childrens. It will |
| overwrite the former specified |
| .Fl r |
| option. |
| .It Fl r |
| Show on subdirectories recursively. It will overwrite the former specified |
| .Fl d |
| option. |
| .El |
| .It Xo |
| .Nm |
| .Cm project |
| .Fl C |
| .Oo Fl kr Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Xc |
| Clear project inherit flag and/or ID on the file(s) or directories. |
| .Bl -tag -width "-k" |
| .It Fl k |
| Keep the project ID unchanged. If not specified, the project ID will be reset |
| as zero. |
| .It Fl r |
| Clear on subdirectories recursively. |
| .El |
| .It Xo |
| .Nm |
| .Cm project |
| .Fl c |
| .Oo Fl 0 Ns Oc |
| .Oo Fl d Ns | Ns Fl r Ns Oc |
| .Op Fl p Ar id |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Xc |
| Check project ID and inherit flag on the file(s) or directories, report the |
| entries without project inherit flag or with different project IDs from the |
| specified (via |
| .Fl p |
| option) value or the target directory's project ID. |
| .Bl -tag -width "-0" |
| .It Fl 0 |
| Print file name with a trailing NUL instead of newline (by default), like |
| "find -print0". |
| .It Fl d |
| Check the directory project ID and inherit flag, not its childrens. It will |
| overwrite the former specified |
| .Fl r |
| option. |
| .It Fl p |
| Specify the referenced ID for comparing with the target file(s) or directories' |
| project IDs. If not specified, the target (top) directory's project ID will be |
| used as the referenced one. |
| .It Fl r |
| Check on subdirectories recursively. It will overwrite the former specified |
| .Fl d |
| option. |
| .El |
| .It Xo |
| .Nm |
| .Cm project |
| .Op Fl p Ar id |
| .Oo Fl rs Ns Oc |
| .Ar file Ns | Ns Ar directory Ns ... |
| .Xc |
| .Bl -tag -width "-p" |
| Set project ID and/or inherit flag on the file(s) or directories. |
| .It Fl p |
| Set the file(s)' or directories' project ID with the given value. |
| .It Fl r |
| Set on subdirectories recursively. |
| .It Fl s |
| Set project inherit flag on the given file(s) or directories. It is usually used |
| for setup tree quota on the directory target with |
| .Fl r |
| option specified together. When setup tree quota, by default the directory's |
| project ID will be set to all its descendants unless you specify the project |
| ID via |
| .Fl p |
| option explicitly. |
| .El |
| .It Xo |
| .Nm |
| .Cm mount |
| .Xc |
| Displays all ZFS file systems currently mounted. |
| .It Xo |
| .Nm |
| .Cm mount |
| .Op Fl Olv |
| .Op Fl o Ar options |
| .Fl a | Ar filesystem |
| .Xc |
| Mount ZFS filesystem on a path described by its |
| .Sy mountpoint |
| property, if the path exists and is empty. If |
| .Sy mountpoint |
| is set to |
| .Em legacy , |
| the filesystem should be instead mounted using |
| .Xr mount 8 . |
| .Bl -tag -width "-O" |
| .It Fl O |
| Perform an overlay mount. Allows mounting in non-empty |
| .Sy mountpoint . |
| See |
| .Xr mount 8 |
| for more information. |
| .It Fl a |
| Mount all available ZFS file systems. |
| Invoked automatically as part of the boot process if configured. |
| .It Ar filesystem |
| Mount the specified filesystem. |
| .It Fl o Ar options |
| An optional, comma-separated list of mount options to use temporarily for the |
| duration of the mount. |
| See the |
| .Sx Temporary Mount Point Properties |
| section for details. |
| .It Fl l |
| Load keys for encrypted filesystems as they are being mounted. This is |
| equivalent to executing |
| .Nm zfs Cm load-key |
| on each encryption root before mounting it. Note that if a filesystem has a |
| .Sy keylocation |
| of |
| .Sy prompt |
| this will cause the terminal to interactively block after asking for the key. |
| .It Fl v |
| Report mount progress. |
| .El |
| .It Xo |
| .Nm |
| .Cm unmount |
| .Op Fl f |
| .Fl a | Ar filesystem Ns | Ns Ar mountpoint |
| .Xc |
| Unmounts currently mounted ZFS file systems. |
| .Bl -tag -width "-a" |
| .It Fl a |
| Unmount all available ZFS file systems. |
| Invoked automatically as part of the shutdown process. |
| .It Ar filesystem Ns | Ns Ar mountpoint |
| Unmount the specified filesystem. |
| The command can also be given a path to a ZFS file system mount point on the |
| system. |
| .It Fl f |
| Forcefully unmount the file system, even if it is currently in use. |
| .El |
| .It Xo |
| .Nm |
| .Cm share |
| .Fl a | Ar filesystem |
| .Xc |
| Shares available ZFS file systems. |
| .Bl -tag -width "-a" |
| .It Fl a |
| Share all available ZFS file systems. |
| Invoked automatically as part of the boot process. |
| .It Ar filesystem |
| Share the specified filesystem according to the |
| .Sy sharenfs |
| and |
| .Sy sharesmb |
| properties. |
| File systems are shared when the |
| .Sy sharenfs |
| or |
| .Sy sharesmb |
| property is set. |
| .El |
| .It Xo |
| .Nm |
| .Cm unshare |
| .Fl a | Ar filesystem Ns | Ns Ar mountpoint |
| .Xc |
| Unshares currently shared ZFS file systems. |
| .Bl -tag -width "-a" |
| .It Fl a |
| Unshare all available ZFS file systems. |
| Invoked automatically as part of the shutdown process. |
| .It Ar filesystem Ns | Ns Ar mountpoint |
| Unshare the specified filesystem. |
| The command can also be given a path to a ZFS file system shared on the system. |
| .El |
| .It Xo |
| .Nm |
| .Cm bookmark |
| .Ar snapshot bookmark |
| .Xc |
| Creates a bookmark of the given snapshot. |
| Bookmarks mark the point in time when the snapshot was created, and can be used |
| as the incremental source for a |
| .Nm zfs Cm send |
| command. |
| .Pp |
| This feature must be enabled to be used. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy bookmarks |
| feature. |
| .It Xo |
| .Nm |
| .Cm send |
| .Op Fl DLPRbcehnpvw |
| .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot |
| .Ar snapshot |
| .Xc |
| Creates a stream representation of the second |
| .Ar snapshot , |
| which is written to standard output. |
| The output can be redirected to a file or to a different system |
| .Po for example, using |
| .Xr ssh 1 |
| .Pc . |
| By default, a full stream is generated. |
| .Bl -tag -width "-D" |
| .It Fl D, -dedup |
| Generate a deduplicated stream. |
| \fBDeduplicated send is deprecated and will be removed in a future release.\fR |
| (In the future, the flag will be accepted but a regular, non-deduplicated |
| stream will be generated.) |
| Blocks which would have been sent multiple times in the send stream will only be |
| sent once. |
| The receiving system must also support this feature to receive a deduplicated |
| stream. |
| This flag can be used regardless of the dataset's |
| .Sy dedup |
| property, but performance will be much better if the filesystem uses a |
| dedup-capable checksum |
| .Po for example, |
| .Sy sha256 |
| .Pc . |
| .It Fl I Ar snapshot |
| Generate a stream package that sends all intermediary snapshots from the first |
| snapshot to the second snapshot. |
| For example, |
| .Fl I Em @a Em fs@d |
| is similar to |
| .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . |
| The incremental source may be specified as with the |
| .Fl i |
| option. |
| .It Fl L, -large-block |
| Generate a stream which may contain blocks larger than 128KB. |
| This flag has no effect if the |
| .Sy large_blocks |
| pool feature is disabled, or if the |
| .Sy recordsize |
| property of this filesystem has never been set above 128KB. |
| The receiving system must have the |
| .Sy large_blocks |
| pool feature enabled as well. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy large_blocks |
| feature. |
| .It Fl P, -parsable |
| Print machine-parsable verbose information about the stream package generated. |
| .It Fl R, -replicate |
| Generate a replication stream package, which will replicate the specified |
| file system, and all descendent file systems, up to the named snapshot. |
| When received, all properties, snapshots, descendent file systems, and clones |
| are preserved. |
| .Pp |
| If the |
| .Fl i |
| or |
| .Fl I |
| flags are used in conjunction with the |
| .Fl R |
| flag, an incremental replication stream is generated. |
| The current values of properties, and current snapshot and file system names are |
| set when the stream is received. |
| If the |
| .Fl F |
| flag is specified when this stream is received, snapshots and file systems that |
| do not exist on the sending side are destroyed. If the |
| .Fl R |
| flag is used to send encrypted datasets, then |
| .Fl w |
| must also be specified. |
| .It Fl e, -embed |
| Generate a more compact stream by using |
| .Sy WRITE_EMBEDDED |
| records for blocks which are stored more compactly on disk by the |
| .Sy embedded_data |
| pool feature. |
| This flag has no effect if the |
| .Sy embedded_data |
| feature is disabled. |
| The receiving system must have the |
| .Sy embedded_data |
| feature enabled. |
| If the |
| .Sy lz4_compress |
| feature is active on the sending system, then the receiving system must have |
| that feature enabled as well. Datasets that are sent with this flag may not be |
| received as an encrypted dataset, since encrypted datasets cannot use the |
| .Sy embedded_data |
| feature. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy embedded_data |
| feature. |
| .It Fl b, -backup |
| Sends only received property values whether or not they are overridden by local |
| settings, but only if the dataset has ever been received. Use this option when |
| you want |
| .Nm zfs Cm receive |
| to restore received properties backed up on the sent dataset and to avoid |
| sending local settings that may have nothing to do with the source dataset, |
| but only with how the data is backed up. |
| .It Fl c, -compressed |
| Generate a more compact stream by using compressed WRITE records for blocks |
| which are compressed on disk and in memory |
| .Po see the |
| .Sy compression |
| property for details |
| .Pc . |
| If the |
| .Sy lz4_compress |
| feature is active on the sending system, then the receiving system must have |
| that feature enabled as well. |
| If the |
| .Sy large_blocks |
| feature is enabled on the sending system but the |
| .Fl L |
| option is not supplied in conjunction with |
| .Fl c , |
| then the data will be decompressed before sending so it can be split into |
| smaller block sizes. |
| .It Fl w, -raw |
| For encrypted datasets, send data exactly as it exists on disk. This allows |
| backups to be taken even if encryption keys are not currently loaded. The |
| backup may then be received on an untrusted machine since that machine will |
| not have the encryption keys to read the protected data or alter it without |
| being detected. Upon being received, the dataset will have the same encryption |
| keys as it did on the send side, although the |
| .Sy keylocation |
| property will be defaulted to |
| .Sy prompt |
| if not otherwise provided. For unencrypted datasets, this flag will be |
| equivalent to |
| .Fl Lec . |
| Note that if you do not use this flag for sending encrypted datasets, data will |
| be sent unencrypted and may be re-encrypted with a different encryption key on |
| the receiving system, which will disable the ability to do a raw send to that |
| system for incrementals. |
| .It Fl h, -holds |
| Generate a stream package that includes any snapshot holds (created with the |
| .Sy zfs hold |
| command), and indicating to |
| .Sy zfs receive |
| that the holds be applied to the dataset on the receiving system. |
| .It Fl i Ar snapshot |
| Generate an incremental stream from the first |
| .Ar snapshot |
| .Pq the incremental source |
| to the second |
| .Ar snapshot |
| .Pq the incremental target . |
| The incremental source can be specified as the last component of the snapshot |
| name |
| .Po the |
| .Sy @ |
| character and following |
| .Pc |
| and it is assumed to be from the same file system as the incremental target. |
| .Pp |
| If the destination is a clone, the source may be the origin snapshot, which must |
| be fully specified |
| .Po for example, |
| .Em pool/fs@origin , |
| not just |
| .Em @origin |
| .Pc . |
| .It Fl n, -dryrun |
| Do a dry-run |
| .Pq Qq No-op |
| send. |
| Do not generate any actual send data. |
| This is useful in conjunction with the |
| .Fl v |
| or |
| .Fl P |
| flags to determine what data will be sent. |
| In this case, the verbose output will be written to standard output |
| .Po contrast with a non-dry-run, where the stream is written to standard output |
| and the verbose output goes to standard error |
| .Pc . |
| .It Fl p, -props |
| Include the dataset's properties in the stream. |
| This flag is implicit when |
| .Fl R |
| is specified. |
| The receiving system must also support this feature. Sends of encrypted datasets |
| must use |
| .Fl w |
| when using this flag. |
| .It Fl v, -verbose |
| Print verbose information about the stream package generated. |
| This information includes a per-second report of how much data has been sent. |
| .Pp |
| The format of the stream is committed. |
| You will be able to receive your streams on future versions of ZFS. |
| .El |
| .It Xo |
| .Nm |
| .Cm send |
| .Op Fl LPcenvw |
| .Op Fl i Ar snapshot Ns | Ns Ar bookmark |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Xc |
| Generate a send stream, which may be of a filesystem, and may be incremental |
| from a bookmark. |
| If the destination is a filesystem or volume, the pool must be read-only, or the |
| filesystem must not be mounted. |
| When the stream generated from a filesystem or volume is received, the default |
| snapshot name will be |
| .Qq --head-- . |
| .Bl -tag -width "-L" |
| .It Fl L, -large-block |
| Generate a stream which may contain blocks larger than 128KB. |
| This flag has no effect if the |
| .Sy large_blocks |
| pool feature is disabled, or if the |
| .Sy recordsize |
| property of this filesystem has never been set above 128KB. |
| The receiving system must have the |
| .Sy large_blocks |
| pool feature enabled as well. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy large_blocks |
| feature. |
| .It Fl P, -parsable |
| Print machine-parsable verbose information about the stream package generated. |
| .It Fl c, -compressed |
| Generate a more compact stream by using compressed WRITE records for blocks |
| which are compressed on disk and in memory |
| .Po see the |
| .Sy compression |
| property for details |
| .Pc . |
| If the |
| .Sy lz4_compress |
| feature is active on the sending system, then the receiving system must have |
| that feature enabled as well. |
| If the |
| .Sy large_blocks |
| feature is enabled on the sending system but the |
| .Fl L |
| option is not supplied in conjunction with |
| .Fl c , |
| then the data will be decompressed before sending so it can be split into |
| smaller block sizes. |
| .It Fl w, -raw |
| For encrypted datasets, send data exactly as it exists on disk. This allows |
| backups to be taken even if encryption keys are not currently loaded. The |
| backup may then be received on an untrusted machine since that machine will |
| not have the encryption keys to read the protected data or alter it without |
| being detected. Upon being received, the dataset will have the same encryption |
| keys as it did on the send side, although the |
| .Sy keylocation |
| property will be defaulted to |
| .Sy prompt |
| if not otherwise provided. For unencrypted datasets, this flag will be |
| equivalent to |
| .Fl Lec . |
| Note that if you do not use this flag for sending encrypted datasets, data will |
| be sent unencrypted and may be re-encrypted with a different encryption key on |
| the receiving system, which will disable the ability to do a raw send to that |
| system for incrementals. |
| .It Fl e, -embed |
| Generate a more compact stream by using |
| .Sy WRITE_EMBEDDED |
| records for blocks which are stored more compactly on disk by the |
| .Sy embedded_data |
| pool feature. |
| This flag has no effect if the |
| .Sy embedded_data |
| feature is disabled. |
| The receiving system must have the |
| .Sy embedded_data |
| feature enabled. |
| If the |
| .Sy lz4_compress |
| feature is active on the sending system, then the receiving system must have |
| that feature enabled as well. Datasets that are sent with this flag may not be |
| received as an encrypted dataset, since encrypted datasets cannot use the |
| .Sy embedded_data |
| feature. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags and the |
| .Sy embedded_data |
| feature. |
| .It Fl i Ar snapshot Ns | Ns Ar bookmark |
| Generate an incremental send stream. |
| The incremental source must be an earlier snapshot in the destination's history. |
| It will commonly be an earlier snapshot in the destination's file system, in |
| which case it can be specified as the last component of the name |
| .Po the |
| .Sy # |
| or |
| .Sy @ |
| character and following |
| .Pc . |
| .Pp |
| If the incremental target is a clone, the incremental source can be the origin |
| snapshot, or an earlier snapshot in the origin's filesystem, or the origin's |
| origin, etc. |
| .It Fl n, -dryrun |
| Do a dry-run |
| .Pq Qq No-op |
| send. |
| Do not generate any actual send data. |
| This is useful in conjunction with the |
| .Fl v |
| or |
| .Fl P |
| flags to determine what data will be sent. |
| In this case, the verbose output will be written to standard output |
| .Po contrast with a non-dry-run, where the stream is written to standard output |
| and the verbose output goes to standard error |
| .Pc . |
| .It Fl v, -verbose |
| Print verbose information about the stream package generated. |
| This information includes a per-second report of how much data has been sent. |
| .El |
| .It Xo |
| .Nm |
| .Cm send |
| .Op Fl Penv |
| .Fl t |
| .Ar receive_resume_token |
| .Xc |
| Creates a send stream which resumes an interrupted receive. |
| The |
| .Ar receive_resume_token |
| is the value of this property on the filesystem or volume that was being |
| received into. |
| See the documentation for |
| .Sy zfs receive -s |
| for more details. |
| .It Xo |
| .Nm |
| .Cm receive |
| .Op Fl Fhnsuv |
| .Op Fl o Sy origin Ns = Ns Ar snapshot |
| .Op Fl o Ar property Ns = Ns Ar value |
| .Op Fl x Ar property |
| .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot |
| .Xc |
| .It Xo |
| .Nm |
| .Cm receive |
| .Op Fl Fhnsuv |
| .Op Fl d Ns | Ns Fl e |
| .Op Fl o Sy origin Ns = Ns Ar snapshot |
| .Op Fl o Ar property Ns = Ns Ar value |
| .Op Fl x Ar property |
| .Ar filesystem |
| .Xc |
| Creates a snapshot whose contents are as specified in the stream provided on |
| standard input. |
| If a full stream is received, then a new file system is created as well. |
| Streams are created using the |
| .Nm zfs Cm send |
| subcommand, which by default creates a full stream. |
| .Nm zfs Cm recv |
| can be used as an alias for |
| .Nm zfs Cm receive. |
| .Pp |
| If an incremental stream is received, then the destination file system must |
| already exist, and its most recent snapshot must match the incremental stream's |
| source. |
| For |
| .Sy zvols , |
| the destination device link is destroyed and recreated, which means the |
| .Sy zvol |
| cannot be accessed during the |
| .Cm receive |
| operation. |
| .Pp |
| When a snapshot replication package stream that is generated by using the |
| .Nm zfs Cm send Fl R |
| command is received, any snapshots that do not exist on the sending location are |
| destroyed by using the |
| .Nm zfs Cm destroy Fl d |
| command. |
| .Pp |
| Deduplicated send streams can be generated by using the |
| .Nm zfs Cm send Fl D |
| command. |
| \fBThe ability to send and receive deduplicated send streams is deprecated.\fR |
| In the future, the ability to receive a deduplicated send stream with |
| .Nm zfs Cm receive |
| will be removed. |
| However, in the future, a utility will be provided to convert a |
| deduplicated send stream to a regular (non-deduplicated) stream. |
| This future utility will require that the send stream be located in a |
| seek-able file, rather than provided by a pipe. |
| .Pp |
| If |
| .Fl o Em property Ns = Ns Ar value |
| or |
| .Fl x Em property |
| is specified, it applies to the effective value of the property throughout |
| the entire subtree of replicated datasets. Effective property values will be |
| set ( |
| .Fl o |
| ) or inherited ( |
| .Fl x |
| ) on the topmost in the replicated subtree. In descendant datasets, if the |
| property is set by the send stream, it will be overridden by forcing the |
| property to be inherited from the top‐most file system. Received properties |
| are retained in spite of being overridden and may be restored with |
| .Nm zfs Cm inherit Fl S . |
| Specifying |
| .Fl o Sy origin Ns = Ns Em snapshot |
| is a special case because, even if |
| .Sy origin |
| is a read-only property and cannot be set, it's allowed to receive the send |
| stream as a clone of the given snapshot. |
| .Pp |
| Raw encrypted send streams (created with |
| .Nm zfs Cm send Fl w |
| ) may only be received as is, and cannot be re-encrypted, decrypted, or |
| recompressed by the receive process. Unencrypted streams can be received as |
| encrypted datasets, either through inheritance or by specifying encryption |
| parameters with the |
| .Fl o |
| options. Note that the |
| .Sy keylocation |
| property cannot be overridden to |
| .Sy prompt |
| during a receive. This is because the receive process itself is already using |
| stdin for the send stream. Instead, the property can be overridden after the |
| receive completes. |
| .Pp |
| The added security provided by raw sends adds some restrictions to the send |
| and receive process. ZFS will not allow a mix of raw receives and non-raw |
| receives. Specifically, any raw incremental receives that are attempted after |
| a non-raw receive will fail. Non-raw receives do not have this restriction and, |
| therefore, are always possible. Because of this, it is best practice to always |
| use either raw sends for their security benefits or non-raw sends for their |
| flexibility when working with encrypted datasets, but not a combination. |
| .Pp |
| The reason for this restriction stems from the inherent restrictions of the |
| AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption, |
| each block of data is encrypted against a randomly generated number known as |
| the "initialization vector" (IV), which is stored in the filesystem metadata. |
| This number is required by the encryption algorithms whenever the data is to |
| be decrypted. Together, all of the IVs provided for all of the blocks in a |
| given snapshot are collectively called an "IV set". When ZFS performs a raw |
| send, the IV set is transferred from the source to the destination in the send |
| stream. When ZFS performs a non-raw send, the data is decrypted by the source |
| system and re-encrypted by the destination system, creating a snapshot with |
| effectively the same data, but a different IV set. In order for decryption to |
| work after a raw send, ZFS must ensure that the IV set used on both the source |
| and destination side match. When an incremental raw receive is performed on |
| top of an existing snapshot, ZFS will check to confirm that the "from" |
| snapshot on both the source and destination were using the same IV set, |
| ensuring the new IV set is consistent. |
| .Pp |
| The name of the snapshot |
| .Pq and file system, if a full stream is received |
| that this subcommand creates depends on the argument type and the use of the |
| .Fl d |
| or |
| .Fl e |
| options. |
| .Pp |
| If the argument is a snapshot name, the specified |
| .Ar snapshot |
| is created. |
| If the argument is a file system or volume name, a snapshot with the same name |
| as the sent snapshot is created within the specified |
| .Ar filesystem |
| or |
| .Ar volume . |
| If neither of the |
| .Fl d |
| or |
| .Fl e |
| options are specified, the provided target snapshot name is used exactly as |
| provided. |
| .Pp |
| The |
| .Fl d |
| and |
| .Fl e |
| options cause the file system name of the target snapshot to be determined by |
| appending a portion of the sent snapshot's name to the specified target |
| .Ar filesystem . |
| If the |
| .Fl d |
| option is specified, all but the first element of the sent snapshot's file |
| system path |
| .Pq usually the pool name |
| is used and any required intermediate file systems within the specified one are |
| created. |
| If the |
| .Fl e |
| option is specified, then only the last element of the sent snapshot's file |
| system name |
| .Pq i.e. the name of the source file system itself |
| is used as the target file system name. |
| .Bl -tag -width "-F" |
| .It Fl F |
| Force a rollback of the file system to the most recent snapshot before |
| performing the receive operation. |
| If receiving an incremental replication stream |
| .Po for example, one generated by |
| .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I |
| .Pc , |
| destroy snapshots and file systems that do not exist on the sending side. |
| .It Fl d |
| Discard the first element of the sent snapshot's file system name, using the |
| remaining elements to determine the name of the target file system for the new |
| snapshot as described in the paragraph above. |
| .It Fl e |
| Discard all but the last element of the sent snapshot's file system name, using |
| that element to determine the name of the target file system for the new |
| snapshot as described in the paragraph above. |
| .It Fl h |
| Skip the receive of holds. There is no effect if holds are not sent. |
| .It Fl n |
| Do not actually receive the stream. |
| This can be useful in conjunction with the |
| .Fl v |
| option to verify the name the receive operation would use. |
| .It Fl o Sy origin Ns = Ns Ar snapshot |
| Forces the stream to be received as a clone of the given snapshot. |
| If the stream is a full send stream, this will create the filesystem |
| described by the stream as a clone of the specified snapshot. |
| Which snapshot was specified will not affect the success or failure of the |
| receive, as long as the snapshot does exist. |
| If the stream is an incremental send stream, all the normal verification will be |
| performed. |
| .It Fl o Em property Ns = Ns Ar value |
| Sets the specified property as if the command |
| .Nm zfs Cm set Em property Ns = Ns Ar value |
| was invoked immediately before the receive. When receiving a stream from |
| .Nm zfs Cm send Fl R , |
| causes the property to be inherited by all descendant datasets, as through |
| .Nm zfs Cm inherit Em property |
| was run on any descendant datasets that have this property set on the |
| sending system. |
| .Pp |
| Any editable property can be set at receive time. Set-once properties bound |
| to the received data, such as |
| .Sy normalization |
| and |
| .Sy casesensitivity , |
| cannot be set at receive time even when the datasets are newly created by |
| .Nm zfs Cm receive . |
| Additionally both settable properties |
| .Sy version |
| and |
| .Sy volsize |
| cannot be set at receive time. |
| .Pp |
| The |
| .Fl o |
| option may be specified multiple times, for different properties. An error |
| results if the same property is specified in multiple |
| .Fl o |
| or |
| .Fl x |
| options. |
| .Pp |
| The |
| .Fl o |
| option may also be used to override encryption properties upon initial |
| receive. This allows unencrypted streams to be received as encrypted datasets. |
| To cause the received dataset (or root dataset of a recursive stream) to be |
| received as an encryption root, specify encryption properties in the same |
| manner as is required for |
| .Nm |
| .Cm create . |
| For instance: |
| .Bd -literal |
| # zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile |
| .Ed |
| .Pp |
| Note that |
| .Op Fl o Ar keylocation Ns = Ns Ar prompt |
| may not be specified here, since stdin is already being utilized for the send |
| stream. Once the receive has completed, you can use |
| .Nm |
| .Cm set |
| to change this setting after the fact. Similarly, you can receive a dataset as |
| an encrypted child by specifying |
| .Op Fl x Ar encryption |
| to force the property to be inherited. Overriding encryption properties (except |
| for |
| .Sy keylocation Ns ) |
| is not possible with raw send streams. |
| .It Fl s |
| If the receive is interrupted, save the partially received state, rather |
| than deleting it. |
| Interruption may be due to premature termination of the stream |
| .Po e.g. due to network failure or failure of the remote system |
| if the stream is being read over a network connection |
| .Pc , |
| a checksum error in the stream, termination of the |
| .Nm zfs Cm receive |
| process, or unclean shutdown of the system. |
| .Pp |
| The receive can be resumed with a stream generated by |
| .Nm zfs Cm send Fl t Ar token , |
| where the |
| .Ar token |
| is the value of the |
| .Sy receive_resume_token |
| property of the filesystem or volume which is received into. |
| .Pp |
| To use this flag, the storage pool must have the |
| .Sy extensible_dataset |
| feature enabled. |
| See |
| .Xr zpool-features 5 |
| for details on ZFS feature flags. |
| .It Fl u |
| File system that is associated with the received stream is not mounted. |
| .It Fl v |
| Print verbose information about the stream and the time required to perform the |
| receive operation. |
| .It Fl x Em property |
| Ensures that the effective value of the specified property after the |
| receive is unaffected by the value of that property in the send stream (if any), |
| as if the property had been excluded from the send stream. |
| .Pp |
| If the specified property is not present in the send stream, this option does |
| nothing. |
| .Pp |
| If a received property needs to be overridden, the effective value will be |
| set or inherited, depending on whether the property is inheritable or not. |
| .Pp |
| In the case of an incremental update, |
| .Fl x |
| leaves any existing local setting or explicit inheritance unchanged. |
| .Pp |
| All |
| .Fl o |
| restrictions (e.g. set-once) apply equally to |
| .Fl x . |
| .El |
| .It Xo |
| .Nm |
| .Cm receive |
| .Fl A |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Abort an interrupted |
| .Nm zfs Cm receive Fl s , |
| deleting its saved partially received state. |
| .It Xo |
| .Nm |
| .Cm allow |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Displays permissions that have been delegated on the specified filesystem or |
| volume. |
| See the other forms of |
| .Nm zfs Cm allow |
| for more information. |
| .Pp |
| Delegations are supported under Linux with the exception of |
| .Sy mount , |
| .Sy unmount , |
| .Sy mountpoint , |
| .Sy canmount , |
| .Sy rename , |
| and |
| .Sy share . |
| These permissions cannot be delegated because the Linux |
| .Xr mount 8 |
| command restricts modifications of the global namespace to the root user. |
| .It Xo |
| .Nm |
| .Cm allow |
| .Op Fl dglu |
| .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| .It Xo |
| .Nm |
| .Cm allow |
| .Op Fl dl |
| .Fl e Ns | Ns Sy everyone |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Delegates ZFS administration permission for the file systems to non-privileged |
| users. |
| .Bl -tag -width "-d" |
| .It Fl d |
| Allow only for the descendent file systems. |
| .It Fl e Ns | Ns Sy everyone |
| Specifies that the permissions be delegated to everyone. |
| .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... |
| Explicitly specify that permissions are delegated to the group. |
| .It Fl l |
| Allow |
| .Qq locally |
| only for the specified file system. |
| .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... |
| Explicitly specify that permissions are delegated to the user. |
| .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... |
| Specifies to whom the permissions are delegated. |
| Multiple entities can be specified as a comma-separated list. |
| If neither of the |
| .Fl gu |
| options are specified, then the argument is interpreted preferentially as the |
| keyword |
| .Sy everyone , |
| then as a user name, and lastly as a group name. |
| To specify a user or group named |
| .Qq everyone , |
| use the |
| .Fl g |
| or |
| .Fl u |
| options. |
| To specify a group with the same name as a user, use the |
| .Fl g |
| options. |
| .It Xo |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Xc |
| The permissions to delegate. |
| Multiple permissions may be specified as a comma-separated list. |
| Permission names are the same as ZFS subcommand and property names. |
| See the property list below. |
| Property set names, which begin with |
| .Sy @ , |
| may be specified. |
| See the |
| .Fl s |
| form below for details. |
| .El |
| .Pp |
| If neither of the |
| .Fl dl |
| options are specified, or both are, then the permissions are allowed for the |
| file system or volume, and all of its descendents. |
| .Pp |
| Permissions are generally the ability to use a ZFS subcommand or change a ZFS |
| property. |
| The following permissions are available: |
| .Bd -literal |
| NAME TYPE NOTES |
| allow subcommand Must also have the permission that is |
| being allowed |
| clone subcommand Must also have the 'create' ability and |
| 'mount' ability in the origin file system |
| create subcommand Must also have the 'mount' ability. |
| Must also have the 'refreservation' ability to |
| create a non-sparse volume. |
| destroy subcommand Must also have the 'mount' ability |
| diff subcommand Allows lookup of paths within a dataset |
| given an object number, and the ability |
| to create snapshots necessary to |
| 'zfs diff'. |
| load-key subcommand Allows loading and unloading of encryption key |
| (see 'zfs load-key' and 'zfs unload-key'). |
| change-key subcommand Allows changing an encryption key via |
| 'zfs change-key'. |
| mount subcommand Allows mount/umount of ZFS datasets |
| promote subcommand Must also have the 'mount' and 'promote' |
| ability in the origin file system |
| receive subcommand Must also have the 'mount' and 'create' |
| ability |
| rename subcommand Must also have the 'mount' and 'create' |
| ability in the new parent |
| rollback subcommand Must also have the 'mount' ability |
| send subcommand |
| share subcommand Allows sharing file systems over NFS |
| or SMB protocols |
| snapshot subcommand Must also have the 'mount' ability |
| |
| groupquota other Allows accessing any groupquota@... |
| property |
| groupused other Allows reading any groupused@... property |
| userprop other Allows changing any user property |
| userquota other Allows accessing any userquota@... |
| property |
| userused other Allows reading any userused@... property |
| projectobjquota other Allows accessing any projectobjquota@... |
| property |
| projectquota other Allows accessing any projectquota@... property |
| projectobjused other Allows reading any projectobjused@... property |
| projectused other Allows reading any projectused@... property |
| |
| aclinherit property |
| acltype property |
| atime property |
| canmount property |
| casesensitivity property |
| checksum property |
| compression property |
| copies property |
| devices property |
| exec property |
| filesystem_limit property |
| mountpoint property |
| nbmand property |
| normalization property |
| primarycache property |
| quota property |
| readonly property |
| recordsize property |
| refquota property |
| refreservation property |
| reservation property |
| secondarycache property |
| setuid property |
| sharenfs property |
| sharesmb property |
| snapdir property |
| snapshot_limit property |
| utf8only property |
| version property |
| volblocksize property |
| volsize property |
| vscan property |
| xattr property |
| zoned property |
| .Ed |
| .It Xo |
| .Nm |
| .Cm allow |
| .Fl c |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Sets |
| .Qq create time |
| permissions. |
| These permissions are granted |
| .Pq locally |
| to the creator of any newly-created descendent file system. |
| .It Xo |
| .Nm |
| .Cm allow |
| .Fl s No @ Ns Ar setname |
| .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Defines or adds permissions to a permission set. |
| The set can be used by other |
| .Nm zfs Cm allow |
| commands for the specified file system and its descendents. |
| Sets are evaluated dynamically, so changes to a set are immediately reflected. |
| Permission sets follow the same naming restrictions as ZFS file systems, but the |
| name must begin with |
| .Sy @ , |
| and can be no more than 64 characters long. |
| .It Xo |
| .Nm |
| .Cm unallow |
| .Op Fl dglru |
| .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| .It Xo |
| .Nm |
| .Cm unallow |
| .Op Fl dlr |
| .Fl e Ns | Ns Sy everyone |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| .It Xo |
| .Nm |
| .Cm unallow |
| .Op Fl r |
| .Fl c |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Removes permissions that were granted with the |
| .Nm zfs Cm allow |
| command. |
| No permissions are explicitly denied, so other permissions granted are still in |
| effect. |
| For example, if the permission is granted by an ancestor. |
| If no permissions are specified, then all permissions for the specified |
| .Ar user , |
| .Ar group , |
| or |
| .Sy everyone |
| are removed. |
| Specifying |
| .Sy everyone |
| .Po or using the |
| .Fl e |
| option |
| .Pc |
| only removes the permissions that were granted to everyone, not all permissions |
| for every user and group. |
| See the |
| .Nm zfs Cm allow |
| command for a description of the |
| .Fl ldugec |
| options. |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively remove the permissions from this file system and all descendents. |
| .El |
| .It Xo |
| .Nm |
| .Cm unallow |
| .Op Fl r |
| .Fl s No @ Ns Ar setname |
| .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns |
| .Ar setname Oc Ns ... Oc |
| .Ar filesystem Ns | Ns Ar volume |
| .Xc |
| Removes permissions from a permission set. |
| If no permissions are specified, then all permissions are removed, thus removing |
| the set entirely. |
| .It Xo |
| .Nm |
| .Cm hold |
| .Op Fl r |
| .Ar tag Ar snapshot Ns ... |
| .Xc |
| Adds a single reference, named with the |
| .Ar tag |
| argument, to the specified snapshot or snapshots. |
| Each snapshot has its own tag namespace, and tags must be unique within that |
| space. |
| .Pp |
| If a hold exists on a snapshot, attempts to destroy that snapshot by using the |
| .Nm zfs Cm destroy |
| command return |
| .Er EBUSY . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Specifies that a hold with the given tag is applied recursively to the snapshots |
| of all descendent file systems. |
| .El |
| .It Xo |
| .Nm |
| .Cm holds |
| .Op Fl rH |
| .Ar snapshot Ns ... |
| .Xc |
| Lists all existing user references for the given snapshot or snapshots. |
| .Bl -tag -width "-r" |
| .It Fl r |
| Lists the holds that are set on the named descendent snapshots, in addition to |
| listing the holds on the named snapshot. |
| .It Fl H |
| Do not print headers, use tab-delimited output. |
| .El |
| .It Xo |
| .Nm |
| .Cm release |
| .Op Fl r |
| .Ar tag Ar snapshot Ns ... |
| .Xc |
| Removes a single reference, named with the |
| .Ar tag |
| argument, from the specified snapshot or snapshots. |
| The tag must already exist for each snapshot. |
| If a hold exists on a snapshot, attempts to destroy that snapshot by using the |
| .Nm zfs Cm destroy |
| command return |
| .Er EBUSY . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively releases a hold with the given tag on the snapshots of all |
| descendent file systems. |
| .El |
| .It Xo |
| .Nm |
| .Cm diff |
| .Op Fl FHt |
| .Ar snapshot Ar snapshot Ns | Ns Ar filesystem |
| .Xc |
| Display the difference between a snapshot of a given filesystem and another |
| snapshot of that filesystem from a later time or the current contents of the |
| filesystem. |
| The first column is a character indicating the type of change, the other columns |
| indicate pathname, new pathname |
| .Pq in case of rename , |
| change in link count, and optionally file type and/or change time. |
| The types of change are: |
| .Bd -literal |
| - The path has been removed |
| + The path has been created |
| M The path has been modified |
| R The path has been renamed |
| .Ed |
| .Bl -tag -width "-F" |
| .It Fl F |
| Display an indication of the type of file, in a manner similar to the |
| .Fl |
| option of |
| .Xr ls 1 . |
| .Bd -literal |
| B Block device |
| C Character device |
| / Directory |
| > Door |
| | Named pipe |
| @ Symbolic link |
| P Event port |
| = Socket |
| F Regular file |
| .Ed |
| .It Fl H |
| Give more parsable tab-separated output, without header lines and without |
| arrows. |
| .It Fl t |
| Display the path's inode change time as the first column of output. |
| .El |
| .It Xo |
| .Nm |
| .Cm program |
| .Op Fl jn |
| .Op Fl t Ar instruction-limit |
| .Op Fl m Ar memory-limit |
| .Ar pool script |
| .Op -- |
| .Ar arg1 No ... |
| .Xc |
| Executes |
| .Ar script |
| as a ZFS channel program on |
| .Ar pool . |
| The ZFS channel |
| program interface allows ZFS administrative operations to be run |
| programmatically via a Lua script. |
| The entire script is executed atomically, with no other administrative |
| operations taking effect concurrently. |
| A library of ZFS calls is made available to channel program scripts. |
| Channel programs may only be run with root privileges. |
| .sp |
| For full documentation of the ZFS channel program interface, see the manual |
| page for |
| .Xr zfs-program 8 . |
| .Bl -tag -width "" |
| .It Fl j |
| Display channel program output in JSON format. When this flag is specified and |
| standard output is empty - channel program encountered an error. The details of |
| such an error will be printed to standard error in plain text. |
| .It Fl n |
| Executes a read-only channel program, which runs faster. |
| The program cannot change on-disk state by calling functions from |
| the zfs.sync submodule. |
| The program can be used to gather information such as properties and |
| determining if changes would succeed (zfs.check.*). |
| Without this flag, all pending changes must be synced to disk before |
| a channel program can complete. |
| .It Fl t Ar instruction-limit |
| Limit the number of Lua instructions to execute. |
| If a channel program executes more than the specified number of instructions, |
| it will be stopped and an error will be returned. |
| The default limit is 10 million instructions, and it can be set to a maximum of |
| 100 million instructions. |
| .It Fl m Ar memory-limit |
| Memory limit, in bytes. |
| If a channel program attempts to allocate more memory than the given limit, |
| it will be stopped and an error returned. |
| The default memory limit is 10 MB, and can be set to a maximum of 100 MB. |
| .sp |
| All remaining argument strings are passed directly to the channel program as |
| arguments. |
| See |
| .Xr zfs-program 8 |
| for more information. |
| .El |
| .It Xo |
| .Nm |
| .Cm load-key |
| .Op Fl nr |
| .Op Fl L Ar keylocation |
| .Fl a | Ar filesystem |
| .Xc |
| Load the key for |
| .Ar filesystem , |
| allowing it and all children that inherit the |
| .Sy keylocation |
| property to be accessed. The key will be expected in the format specified by the |
| .Sy keyformat |
| and location specified by the |
| .Sy keylocation |
| property. Note that if the |
| .Sy keylocation |
| is set to |
| .Sy prompt |
| the terminal will interactively wait for the key to be entered. Loading a key |
| will not automatically mount the dataset. If that functionality is desired, |
| .Nm zfs Cm mount Sy -l |
| will ask for the key and mount the dataset. Once the key is loaded the |
| .Sy keystatus |
| property will become |
| .Sy available . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively loads the keys for the specified filesystem and all descendent |
| encryption roots. |
| .It Fl a |
| Loads the keys for all encryption roots in all imported pools. |
| .It Fl n |
| Do a dry-run |
| .Pq Qq No-op |
| load-key. This will cause zfs to simply check that the |
| provided key is correct. This command may be run even if the key is already |
| loaded. |
| .It Fl L Ar keylocation |
| Use |
| .Ar keylocation |
| instead of the |
| .Sy keylocation |
| property. This will not change the value of the property on the dataset. Note |
| that if used with either |
| .Fl r |
| or |
| .Fl a , |
| .Ar keylocation |
| may only be given as |
| .Sy prompt . |
| .El |
| .It Xo |
| .Nm |
| .Cm unload-key |
| .Op Fl r |
| .Fl a | Ar filesystem |
| .Xc |
| Unloads a key from ZFS, removing the ability to access the dataset and all of |
| its children that inherit the |
| .Sy keylocation |
| property. This requires that the dataset is not currently open or mounted. Once |
| the key is unloaded the |
| .Sy keystatus |
| property will become |
| .Sy unavailable . |
| .Bl -tag -width "-r" |
| .It Fl r |
| Recursively unloads the keys for the specified filesystem and all descendent |
| encryption roots. |
| .It Fl a |
| Unloads the keys for all encryption roots in all imported pools. |
| .El |
| .It Xo |
| .Nm |
| .Cm change-key |
| .Op Fl l |
| .Op Fl o Ar keylocation Ns = Ns Ar value |
| .Op Fl o Ar keyformat Ns = Ns Ar value |
| .Op Fl o Ar pbkdf2iters Ns = Ns Ar value |
| .Ar filesystem |
| .Xc |
| .It Xo |
| .Nm |
| .Cm change-key |
| .Fl i |
| .Op Fl l |
| .Ar filesystem |
| .Xc |
| Allows a user to change the encryption key used to access a dataset. This |
| command requires that the existing key for the dataset is already loaded into |
| ZFS. This command may also be used to change the |
| .Sy keylocation , |
| .Sy keyformat , |
| and |
| .Sy pbkdf2iters |
| properties as needed. If the dataset was not previously an encryption root it |
| will become one. Alternatively, the |
| .Fl i |
| flag may be provided to cause an encryption root to inherit the parent's key |
| instead. |
| .Bl -tag -width "-r" |
| .It Fl l |
| Ensures the key is loaded before attempting to change the key. This is |
| effectively equivalent to |
| .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem |
| .It Fl o Ar property Ns = Ns Ar value |
| Allows the user to set encryption key properties ( |
| .Sy keyformat , |
| .Sy keylocation , |
| and |
| .Sy pbkdf2iters |
| ) while changing the key. This is the only way to alter |
| .Sy keyformat |
| and |
| .Sy pbkdf2iters |
| after the dataset has been created. |
| .It Fl i |
| Indicates that zfs should make |
| .Ar filesystem |
| inherit the key of its parent. Note that this command can only be run on an |
| encryption root that has an encrypted parent. |
| .El |
| .It Xo |
| .Nm |
| .Cm version |
| .Xc |
| Displays the software version of the |
| .Nm |
| userland utility and the zfs kernel module. |
| .El |
| .Sh EXIT STATUS |
| The |
| .Nm |
| utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line |
| options were specified. |
| .Sh EXAMPLES |
| .Bl -tag -width "" |
| .It Sy Example 1 No Creating a ZFS File System Hierarchy |
| The following commands create a file system named |
| .Em pool/home |
| and a file system named |
| .Em pool/home/bob . |
| The mount point |
| .Pa /export/home |
| is set for the parent file system, and is automatically inherited by the child |
| file system. |
| .Bd -literal |
| # zfs create pool/home |
| # zfs set mountpoint=/export/home pool/home |
| # zfs create pool/home/bob |
| .Ed |
| .It Sy Example 2 No Creating a ZFS Snapshot |
| The following command creates a snapshot named |
| .Sy yesterday . |
| This snapshot is mounted on demand in the |
| .Pa .zfs/snapshot |
| directory at the root of the |
| .Em pool/home/bob |
| file system. |
| .Bd -literal |
| # zfs snapshot pool/home/bob@yesterday |
| .Ed |
| .It Sy Example 3 No Creating and Destroying Multiple Snapshots |
| The following command creates snapshots named |
| .Sy yesterday |
| of |
| .Em pool/home |
| and all of its descendent file systems. |
| Each snapshot is mounted on demand in the |
| .Pa .zfs/snapshot |
| directory at the root of its file system. |
| The second command destroys the newly created snapshots. |
| .Bd -literal |
| # zfs snapshot -r pool/home@yesterday |
| # zfs destroy -r pool/home@yesterday |
| .Ed |
| .It Sy Example 4 No Disabling and Enabling File System Compression |
| The following command disables the |
| .Sy compression |
| property for all file systems under |
| .Em pool/home . |
| The next command explicitly enables |
| .Sy compression |
| for |
| .Em pool/home/anne . |
| .Bd -literal |
| # zfs set compression=off pool/home |
| # zfs set compression=on pool/home/anne |
| .Ed |
| .It Sy Example 5 No Listing ZFS Datasets |
| The following command lists all active file systems and volumes in the system. |
| Snapshots are displayed if the |
| .Sy listsnaps |
| property is |
| .Sy on . |
| The default is |
| .Sy off . |
| See |
| .Xr zpool 8 |
| for more information on pool properties. |
| .Bd -literal |
| # zfs list |
| NAME USED AVAIL REFER MOUNTPOINT |
| pool 450K 457G 18K /pool |
| pool/home 315K 457G 21K /export/home |
| pool/home/anne 18K 457G 18K /export/home/anne |
| pool/home/bob 276K 457G 276K /export/home/bob |
| .Ed |
| .It Sy Example 6 No Setting a Quota on a ZFS File System |
| The following command sets a quota of 50 Gbytes for |
| .Em pool/home/bob . |
| .Bd -literal |
| # zfs set quota=50G pool/home/bob |
| .Ed |
| .It Sy Example 7 No Listing ZFS Properties |
| The following command lists all properties for |
| .Em pool/home/bob . |
| .Bd -literal |
| # zfs get all pool/home/bob |
| NAME PROPERTY VALUE SOURCE |
| pool/home/bob type filesystem - |
| pool/home/bob creation Tue Jul 21 15:53 2009 - |
| pool/home/bob used 21K - |
| pool/home/bob available 20.0G - |
| pool/home/bob referenced 21K - |
| pool/home/bob compressratio 1.00x - |
| pool/home/bob mounted yes - |
| pool/home/bob quota 20G local |
| pool/home/bob reservation none default |
| pool/home/bob recordsize 128K default |
| pool/home/bob mountpoint /pool/home/bob default |
| pool/home/bob sharenfs off default |
| pool/home/bob checksum on default |
| pool/home/bob compression on local |
| pool/home/bob atime on default |
| pool/home/bob devices on default |
| pool/home/bob exec on default |
| pool/home/bob setuid on default |
| pool/home/bob readonly off default |
| pool/home/bob zoned off default |
| pool/home/bob snapdir hidden default |
| pool/home/bob acltype off default |
| pool/home/bob aclinherit restricted default |
| pool/home/bob canmount on default |
| pool/home/bob xattr on default |
| pool/home/bob copies 1 default |
| pool/home/bob version 4 - |
| pool/home/bob utf8only off - |
| pool/home/bob normalization none - |
| pool/home/bob casesensitivity sensitive - |
| pool/home/bob vscan off default |
| pool/home/bob nbmand off default |
| pool/home/bob sharesmb off default |
| pool/home/bob refquota none default |
| pool/home/bob refreservation none default |
| pool/home/bob primarycache all default |
| pool/home/bob secondarycache all default |
| pool/home/bob usedbysnapshots 0 - |
| pool/home/bob usedbydataset 21K - |
| pool/home/bob usedbychildren 0 - |
| pool/home/bob usedbyrefreservation 0 - |
| .Ed |
| .Pp |
| The following command gets a single property value. |
| .Bd -literal |
| # zfs get -H -o value compression pool/home/bob |
| on |
| .Ed |
| The following command lists all properties with local settings for |
| .Em pool/home/bob . |
| .Bd -literal |
| # zfs get -r -s local -o name,property,value all pool/home/bob |
| NAME PROPERTY VALUE |
| pool/home/bob quota 20G |
| pool/home/bob compression on |
| .Ed |
| .It Sy Example 8 No Rolling Back a ZFS File System |
| The following command reverts the contents of |
| .Em pool/home/anne |
| to the snapshot named |
| .Sy yesterday , |
| deleting all intermediate snapshots. |
| .Bd -literal |
| # zfs rollback -r pool/home/anne@yesterday |
| .Ed |
| .It Sy Example 9 No Creating a ZFS Clone |
| The following command creates a writable file system whose initial contents are |
| the same as |
| .Em pool/home/bob@yesterday . |
| .Bd -literal |
| # zfs clone pool/home/bob@yesterday pool/clone |
| .Ed |
| .It Sy Example 10 No Promoting a ZFS Clone |
| The following commands illustrate how to test out changes to a file system, and |
| then replace the original file system with the changed one, using clones, clone |
| promotion, and renaming: |
| .Bd -literal |
| # zfs create pool/project/production |
| populate /pool/project/production with data |
| # zfs snapshot pool/project/production@today |
| # zfs clone pool/project/production@today pool/project/beta |
| make changes to /pool/project/beta and test them |
| # zfs promote pool/project/beta |
| # zfs rename pool/project/production pool/project/legacy |
| # zfs rename pool/project/beta pool/project/production |
| once the legacy version is no longer needed, it can be destroyed |
| # zfs destroy pool/project/legacy |
| .Ed |
| .It Sy Example 11 No Inheriting ZFS Properties |
| The following command causes |
| .Em pool/home/bob |
| and |
| .Em pool/home/anne |
| to inherit the |
| .Sy checksum |
| property from their parent. |
| .Bd -literal |
| # zfs inherit checksum pool/home/bob pool/home/anne |
| .Ed |
| .It Sy Example 12 No Remotely Replicating ZFS Data |
| The following commands send a full stream and then an incremental stream to a |
| remote machine, restoring them into |
| .Em poolB/received/fs@a |
| and |
| .Em poolB/received/fs@b , |
| respectively. |
| .Em poolB |
| must contain the file system |
| .Em poolB/received , |
| and must not initially contain |
| .Em poolB/received/fs . |
| .Bd -literal |
| # zfs send pool/fs@a | \e |
| ssh host zfs receive poolB/received/fs@a |
| # zfs send -i a pool/fs@b | \e |
| ssh host zfs receive poolB/received/fs |
| .Ed |
| .It Sy Example 13 No Using the zfs receive -d Option |
| The following command sends a full stream of |
| .Em poolA/fsA/fsB@snap |
| to a remote machine, receiving it into |
| .Em poolB/received/fsA/fsB@snap . |
| The |
| .Em fsA/fsB@snap |
| portion of the received snapshot's name is determined from the name of the sent |
| snapshot. |
| .Em poolB |
| must contain the file system |
| .Em poolB/received . |
| If |
| .Em poolB/received/fsA |
| does not exist, it is created as an empty file system. |
| .Bd -literal |
| # zfs send poolA/fsA/fsB@snap | \e |
| ssh host zfs receive -d poolB/received |
| .Ed |
| .It Sy Example 14 No Setting User Properties |
| The following example sets the user-defined |
| .Sy com.example:department |
| property for a dataset. |
| .Bd -literal |
| # zfs set com.example:department=12345 tank/accounting |
| .Ed |
| .It Sy Example 15 No Performing a Rolling Snapshot |
| The following example shows how to maintain a history of snapshots with a |
| consistent naming scheme. |
| To keep a week's worth of snapshots, the user destroys the oldest snapshot, |
| renames the remaining snapshots, and then creates a new snapshot, as follows: |
| .Bd -literal |
| # zfs destroy -r pool/users@7daysago |
| # zfs rename -r pool/users@6daysago @7daysago |
| # zfs rename -r pool/users@5daysago @6daysago |
| # zfs rename -r pool/users@4daysago @5daysago |
| # zfs rename -r pool/users@3daysago @4daysago |
| # zfs rename -r pool/users@2daysago @3daysago |
| # zfs rename -r pool/users@yesterday @2daysago |
| # zfs rename -r pool/users@today @yesterday |
| # zfs snapshot -r pool/users@today |
| .Ed |
| .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System |
| The following commands show how to set |
| .Sy sharenfs |
| property options to enable |
| .Sy rw |
| access for a set of |
| .Sy IP |
| addresses and to enable root access for system |
| .Sy neo |
| on the |
| .Em tank/home |
| file system. |
| .Bd -literal |
| # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home |
| .Ed |
| .Pp |
| If you are using |
| .Sy DNS |
| for host name resolution, specify the fully qualified hostname. |
| .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset |
| The following example shows how to set permissions so that user |
| .Sy cindys |
| can create, destroy, mount, and take snapshots on |
| .Em tank/cindys . |
| The permissions on |
| .Em tank/cindys |
| are also displayed. |
| .Bd -literal |
| # zfs allow cindys create,destroy,mount,snapshot tank/cindys |
| # zfs allow tank/cindys |
| ---- Permissions on tank/cindys -------------------------------------- |
| Local+Descendent permissions: |
| user cindys create,destroy,mount,snapshot |
| .Ed |
| .Pp |
| Because the |
| .Em tank/cindys |
| mount point permission is set to 755 by default, user |
| .Sy cindys |
| will be unable to mount file systems under |
| .Em tank/cindys . |
| Add an ACE similar to the following syntax to provide mount point access: |
| .Bd -literal |
| # chmod A+user:cindys:add_subdirectory:allow /tank/cindys |
| .Ed |
| .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset |
| The following example shows how to grant anyone in the group |
| .Sy staff |
| to create file systems in |
| .Em tank/users . |
| This syntax also allows staff members to destroy their own file systems, but not |
| destroy anyone else's file system. |
| The permissions on |
| .Em tank/users |
| are also displayed. |
| .Bd -literal |
| # zfs allow staff create,mount tank/users |
| # zfs allow -c destroy tank/users |
| # zfs allow tank/users |
| ---- Permissions on tank/users --------------------------------------- |
| Permission sets: |
| destroy |
| Local+Descendent permissions: |
| group staff create,mount |
| .Ed |
| .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset |
| The following example shows how to define and grant a permission set on the |
| .Em tank/users |
| file system. |
| The permissions on |
| .Em tank/users |
| are also displayed. |
| .Bd -literal |
| # zfs allow -s @pset create,destroy,snapshot,mount tank/users |
| # zfs allow staff @pset tank/users |
| # zfs allow tank/users |
| ---- Permissions on tank/users --------------------------------------- |
| Permission sets: |
| @pset create,destroy,mount,snapshot |
| Local+Descendent permissions: |
| group staff @pset |
| .Ed |
| .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset |
| The following example shows to grant the ability to set quotas and reservations |
| on the |
| .Em users/home |
| file system. |
| The permissions on |
| .Em users/home |
| are also displayed. |
| .Bd -literal |
| # zfs allow cindys quota,reservation users/home |
| # zfs allow users/home |
| ---- Permissions on users/home --------------------------------------- |
| Local+Descendent permissions: |
| user cindys quota,reservation |
| cindys% zfs set quota=10G users/home/marks |
| cindys% zfs get quota users/home/marks |
| NAME PROPERTY VALUE SOURCE |
| users/home/marks quota 10G local |
| .Ed |
| .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset |
| The following example shows how to remove the snapshot permission from the |
| .Sy staff |
| group on the |
| .Em tank/users |
| file system. |
| The permissions on |
| .Em tank/users |
| are also displayed. |
| .Bd -literal |
| # zfs unallow staff snapshot tank/users |
| # zfs allow tank/users |
| ---- Permissions on tank/users --------------------------------------- |
| Permission sets: |
| @pset create,destroy,mount,snapshot |
| Local+Descendent permissions: |
| group staff @pset |
| .Ed |
| .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset |
| The following example shows how to see what has changed between a prior |
| snapshot of a ZFS dataset and its current state. |
| The |
| .Fl F |
| option is used to indicate type information for the files affected. |
| .Bd -literal |
| # zfs diff -F tank/test@before tank/test |
| M / /tank/test/ |
| M F /tank/test/linked (+1) |
| R F /tank/test/oldname -> /tank/test/newname |
| - F /tank/test/deleted |
| + F /tank/test/created |
| M F /tank/test/modified |
| .Ed |
| .It Sy Example 23 No Creating a bookmark |
| The following example create a bookmark to a snapshot. This bookmark |
| can then be used instead of snapshot in send streams. |
| .Bd -literal |
| # zfs bookmark rpool@snapshot rpool#bookmark |
| .Ed |
| .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System |
| The following example show how to share SMB filesystem through ZFS. Note that |
| that a user and his/her password must be given. |
| .Bd -literal |
| # smbmount //127.0.0.1/share_tmp /mnt/tmp \\ |
| -o user=workgroup/turbo,password=obrut,uid=1000 |
| .Ed |
| .Pp |
| Minimal |
| .Em /etc/samba/smb.conf |
| configuration required: |
| .Pp |
| Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to |
| communicate with Samba. This is the default behavior for most Linux |
| distributions. |
| .Pp |
| Samba must be able to authenticate a user. This can be done in a number of |
| ways, depending on if using the system password file, LDAP or the Samba |
| specific smbpasswd file. How to do this is outside the scope of this manual. |
| Please refer to the |
| .Xr smb.conf 5 |
| man page for more information. |
| .Pp |
| See the |
| .Sy USERSHARE section |
| of the |
| .Xr smb.conf 5 |
| man page for all configuration options in case you need to modify any options |
| to the share afterwards. Do note that any changes done with the |
| .Xr net 8 |
| command will be undone if the share is ever unshared (such as at a reboot etc). |
| .El |
| .Sh INTERFACE STABILITY |
| .Sy Committed . |
| .Sh SEE ALSO |
| .Xr attr 1 , |
| .Xr gzip 1 , |
| .Xr ssh 1 , |
| .Xr chmod 2 , |
| .Xr fsync 2 , |
| .Xr stat 2 , |
| .Xr write 2 , |
| .Xr acl 5 , |
| .Xr attributes 5 , |
| .Xr exports 5 , |
| .Xr exportfs 8 , |
| .Xr mount 8 , |
| .Xr net 8 , |
| .Xr selinux 8 , |
| .Xr zfs-program 8 , |
| .Xr zpool 8 |