From 870fc32fc94fcc5108868b4a64cb694c72dc2e21 Mon Sep 17 00:00:00 2001 From: Ross Williams Date: Tue, 12 Nov 2019 14:17:40 -0500 Subject: [PATCH] Reorganize zfs(8) man page into sections Most subcommands got their own manpages (e.g. create). Some related commands grouped into a single manpage and symlinks created (e.g. set, get, and inherit). I did this when topics were either too short to warrant their own file or so interrelated that a user would want to refer between commands in the same file. Corrected .Sx internal references to .Xr cross refs; lots of .Sx references from when text was all in zfs.8 needed to be changed to .Xr zfs-$SUBCOMMAND 8 cross references. Divided subcommand list in zfs(8) into sections of related functionality. This required writing new descriptions for some commands. Preserved ".Os Linux", `.Os` macro parsing behavior differs between mandoc from the "BSD" mandoc package (available on Ubuntu) and man from Ubuntu's man-db package, which calls groff to format the manpages. Groff handles the `.Os` macro differently and wrongly, defaulting it to "BSD" in `/usr/share/groff/*/tmac/mdoc/doc-common`, instead of getting the default from `uname`. A future set of changes will introduce build-time preprocessing of manpages for platform-specific documentation and can insert the correct operating system name. Added SEE ALSO sections, the newly-divided zfs-*.8 subcommand man pages needed their own SEE ALSO sections pointing to related subcommands and, in some cases, documentation from other packages (e.g. zfs-share.8). Reviewed-by: Matt Ahrens Reviewed-by: Kjeld Schouten Reviewed-by: Sean Eric Fagan Reviewed-by: Brian Behlendorf Signed-off-by: Ross Williams Closes #9559 --- man/man8/Makefile.am | 34 + man/man8/zfs-allow.8 | 372 +++ man/man8/zfs-bookmark.8 | 63 + man/man8/zfs-change-key.8 | 1 + man/man8/zfs-clone.8 | 77 + man/man8/zfs-create.8 | 245 ++ man/man8/zfs-destroy.8 | 178 ++ man/man8/zfs-diff.8 | 91 + man/man8/zfs-get.8 | 1 + man/man8/zfs-groupspace.8 | 1 + man/man8/zfs-hold.8 | 110 + man/man8/zfs-inherit.8 | 1 + man/man8/zfs-list.8 | 169 ++ man/man8/zfs-load-key.8 | 272 ++ man/man8/zfs-mount.8 | 127 + man/man8/zfs-project.8 | 153 ++ man/man8/zfs-projectspace.8 | 1 + man/man8/zfs-promote.8 | 69 + man/man8/zfs-receive.8 | 365 +++ man/man8/zfs-recv.8 | 1 + man/man8/zfs-redact.8 | 1 + man/man8/zfs-release.8 | 1 + man/man8/zfs-rename.8 | 91 + man/man8/zfs-rollback.8 | 81 + man/man8/zfs-send.8 | 597 +++++ man/man8/zfs-set.8 | 188 ++ man/man8/zfs-share.8 | 88 + man/man8/zfs-snapshot.8 | 83 + man/man8/zfs-unallow.8 | 1 + man/man8/zfs-unload-key.8 | 1 + man/man8/zfs-unmount.8 | 1 + man/man8/zfs-upgrade.8 | 106 + man/man8/zfs-userspace.8 | 186 ++ man/man8/zfs.8 | 4987 ++--------------------------------- man/man8/zfsconcepts.8 | 198 ++ man/man8/zfsprops.8 | 1884 +++++++++++++ 36 files changed, 5998 insertions(+), 4827 deletions(-) create mode 100644 man/man8/zfs-allow.8 create mode 100644 man/man8/zfs-bookmark.8 create mode 120000 man/man8/zfs-change-key.8 create mode 100644 man/man8/zfs-clone.8 create mode 100644 man/man8/zfs-create.8 create mode 100644 man/man8/zfs-destroy.8 create mode 100644 man/man8/zfs-diff.8 create mode 120000 man/man8/zfs-get.8 create mode 120000 man/man8/zfs-groupspace.8 create mode 100644 man/man8/zfs-hold.8 create mode 120000 man/man8/zfs-inherit.8 create mode 100644 man/man8/zfs-list.8 create mode 100644 man/man8/zfs-load-key.8 create mode 100644 man/man8/zfs-mount.8 create mode 100644 man/man8/zfs-project.8 create mode 120000 man/man8/zfs-projectspace.8 create mode 100644 man/man8/zfs-promote.8 create mode 100644 man/man8/zfs-receive.8 create mode 120000 man/man8/zfs-recv.8 create mode 120000 man/man8/zfs-redact.8 create mode 120000 man/man8/zfs-release.8 create mode 100644 man/man8/zfs-rename.8 create mode 100644 man/man8/zfs-rollback.8 create mode 100644 man/man8/zfs-send.8 create mode 100644 man/man8/zfs-set.8 create mode 100644 man/man8/zfs-share.8 create mode 100644 man/man8/zfs-snapshot.8 create mode 120000 man/man8/zfs-unallow.8 create mode 120000 man/man8/zfs-unload-key.8 create mode 120000 man/man8/zfs-unmount.8 create mode 100644 man/man8/zfs-upgrade.8 create mode 100644 man/man8/zfs-userspace.8 create mode 100644 man/man8/zfsconcepts.8 create mode 100644 man/man8/zfsprops.8 diff --git a/man/man8/Makefile.am b/man/man8/Makefile.am index 5401ff06f..c6e4249e3 100644 --- a/man/man8/Makefile.am +++ b/man/man8/Makefile.am @@ -4,7 +4,41 @@ dist_man_MANS = \ vdev_id.8 \ zdb.8 \ zfs.8 \ + zfsconcepts.8 \ + zfsprops.8 \ + zfs-allow.8 \ + zfs-bookmark.8 \ + zfs-change-key.8 \ + zfs-clone.8 \ + zfs-create.8 \ + zfs-destroy.8 \ + zfs-diff.8 \ + zfs-get.8 \ + zfs-groupspace.8 \ + zfs-hold.8 \ + zfs-inherit.8 \ + zfs-list.8 \ + zfs-load-key.8 \ + zfs-mount.8 \ zfs-program.8 \ + zfs-project.8 \ + zfs-projectspace.8 \ + zfs-promote.8 \ + zfs-receive.8 \ + zfs-recv.8 \ + zfs-redact.8 \ + zfs-release.8 \ + zfs-rename.8 \ + zfs-rollback.8 \ + zfs-send.8 \ + zfs-set.8 \ + zfs-share.8 \ + zfs-snapshot.8 \ + zfs-unallow.8 \ + zfs-unload-key.8 \ + zfs-unmount.8 \ + zfs-upgrade.8 \ + zfs-userspace.8 \ zgenhostid.8 \ zinject.8 \ zpool.8 \ diff --git a/man/man8/zfs-allow.8 b/man/man8/zfs-allow.8 new file mode 100644 index 000000000..2e1fc98e9 --- /dev/null +++ b/man/man8/zfs-allow.8 @@ -0,0 +1,372 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-ALLOW 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm allow +.Nd Delegates ZFS administration permission for the file systems to non-privileged users. +.Sh SYNOPSIS +.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 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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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. +.El diff --git a/man/man8/zfs-bookmark.8 b/man/man8/zfs-bookmark.8 new file mode 100644 index 000000000..04d4af556 --- /dev/null +++ b/man/man8/zfs-bookmark.8 @@ -0,0 +1,63 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-BOOKMARK 8 SMM +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm bookmark +.Nd Creates a bookmark of the given snapshot. +.Sh SYNOPSIS +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.Xr zfs-send 8 +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. +.El +.Sh SEE ALSO +.Xr zfs-destroy 8 , +.Xr zfs-send 8 , +.Xr zfs-snapshot 8 diff --git a/man/man8/zfs-change-key.8 b/man/man8/zfs-change-key.8 new file mode 120000 index 000000000..d027a419d --- /dev/null +++ b/man/man8/zfs-change-key.8 @@ -0,0 +1 @@ +zfs-load-key.8 \ No newline at end of file diff --git a/man/man8/zfs-clone.8 b/man/man8/zfs-clone.8 new file mode 100644 index 000000000..5daf3bde2 --- /dev/null +++ b/man/man8/zfs-clone.8 @@ -0,0 +1,77 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-CLONE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm clone +.Nd Creates a clone of the given snapshot. +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +See the +.Em Clones +section of +.Xr zfsconcepts 8 +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 +.El +.Sh SEE ALSO +.Xr zfs-promote 8 , +.Xr zfs-snapshot 8 diff --git a/man/man8/zfs-create.8 b/man/man8/zfs-create.8 new file mode 100644 index 000000000..6aef2bb57 --- /dev/null +++ b/man/man8/zfs-create.8 @@ -0,0 +1,245 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-CREATE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm create +.Nd Creates a new ZFS file system. +.Sh SYNOPSIS +.Nm zfs +.Cm create +.Op Fl Pnpv +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.It Xo +.Nm +.Cm create +.Op Fl Pnpv +.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. +.It Fl n +Do a dry-run +.Pq Qq No-op +creation. +No datasets will be created. +This is useful in conjunction with the +.Fl v +or +.Fl P +flags to validate properties that are passed via +.Fl o +options and those implied by other options. +The actual dataset creation can still fail due to insufficient privileges or +available capacity. +.It Fl P +Print machine-parsable verbose information about the created dataset. +Each line of output contains a key and one or two values, all separated by tabs. +The +.Sy create_ancestors +and +.Sy create +keys have +.Em filesystem +as their only value. +The +.Sy create_ancestors +key only appears if the +.Fl p +option is used. +The +.Sy property +key has two values, a property name that property's value. +The +.Sy property +key may appear zero or more times, once for each property that will be set local +to +.Em filesystem +due to the use of the +.Fl o +option. +.It Fl v +Print verbose information about the created dataset. +.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 +.Em Native Properties +section of +.Xr zfsprops 8 +for more information about sparse volumes. +.It Fl n +Do a dry-run +.Pq Qq No-op +creation. +No datasets will be created. +This is useful in conjunction with the +.Fl v +or +.Fl P +flags to validate properties that are passed via +.Fl o +options and those implied by other options. +The actual dataset creation can still fail due to insufficient privileges or +available capacity. +.It Fl P +Print machine-parsable verbose information about the created dataset. +Each line of output contains a key and one or two values, all separated by tabs. +The +.Sy create_ancestors +and +.Sy create +keys have +.Em volume +as their only value. +The +.Sy create_ancestors +key only appears if the +.Fl p +option is used. +The +.Sy property +key has two values, a property name that property's value. +The +.Sy property +key may appear zero or more times, once for each property that will be set local +to +.Em volume +due to the use of the +.Fl b +or +.Fl o +options, as well as +.Sy refreservation +if the volume is not sparse. +.It Fl v +Print verbose information about the created dataset. +.El +.El +.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. +.Sh SEE ALSO +.Xr zfs-destroy 8 , +.Xr zfs-list 8 , +.Xr zpool-create 8 diff --git a/man/man8/zfs-destroy.8 b/man/man8/zfs-destroy.8 new file mode 100644 index 000000000..edd9ee809 --- /dev/null +++ b/man/man8/zfs-destroy.8 @@ -0,0 +1,178 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-DESTROY 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm destroy +.Nd Destroys the given dataset(s), snapshot(s), or bookmark. +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.Ql zfs 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. +.El +.Sh SEE ALSO +.Xr zfs-create 8 , +.Xr zfs-hold 8 diff --git a/man/man8/zfs-diff.8 b/man/man8/zfs-diff.8 new file mode 100644 index 000000000..e1c19df7d --- /dev/null +++ b/man/man8/zfs-diff.8 @@ -0,0 +1,91 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-DIFF 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm diff +.Nd Display the difference between two snapshots of a given filesystem. +.Sh SYNOPSIS +.Nm +.Cm diff +.Op Fl FHt +.Ar snapshot Ar snapshot Ns | Ns Ar filesystem +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.El +.Sh SEE ALSO +.Xr zfs-snapshot 8 diff --git a/man/man8/zfs-get.8 b/man/man8/zfs-get.8 new file mode 120000 index 000000000..c70b41ae4 --- /dev/null +++ b/man/man8/zfs-get.8 @@ -0,0 +1 @@ +zfs-set.8 \ No newline at end of file diff --git a/man/man8/zfs-groupspace.8 b/man/man8/zfs-groupspace.8 new file mode 120000 index 000000000..8bc2f1df3 --- /dev/null +++ b/man/man8/zfs-groupspace.8 @@ -0,0 +1 @@ +zfs-userspace.8 \ No newline at end of file diff --git a/man/man8/zfs-hold.8 b/man/man8/zfs-hold.8 new file mode 100644 index 000000000..200c17ebf --- /dev/null +++ b/man/man8/zfs-hold.8 @@ -0,0 +1,110 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-HOLD 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm hold +.Nd Hold a snapshot to prevent it being removed with the zfs destroy command. +.Sh SYNOPSIS +.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 ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.El +.Sh SEE ALSO +.Xr zfs-destroy 8 diff --git a/man/man8/zfs-inherit.8 b/man/man8/zfs-inherit.8 new file mode 120000 index 000000000..c70b41ae4 --- /dev/null +++ b/man/man8/zfs-inherit.8 @@ -0,0 +1 @@ +zfs-set.8 \ No newline at end of file diff --git a/man/man8/zfs-list.8 b/man/man8/zfs-list.8 new file mode 100644 index 000000000..54292eb1c --- /dev/null +++ b/man/man8/zfs-list.8 @@ -0,0 +1,169 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-LIST 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm list +.Nd Lists the property information for the given datasets in tabular form. +.Sh SYNOPSIS +.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 ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +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 +.Em Native Properties +section of +.Xr zfsprops 8 +.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 +.Em Properties +section of +.Xr zfsprops 8 +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 +.El +.Sh SEE ALSO +.Xr zfs-get 8 , +.Xr zfsprops 8 diff --git a/man/man8/zfs-load-key.8 b/man/man8/zfs-load-key.8 new file mode 100644 index 000000000..bf255d96d --- /dev/null +++ b/man/man8/zfs-load-key.8 @@ -0,0 +1,272 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-LOAD-KEY 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm load-key +.Nd Load, unload, or change the encryption key used to access a dataset. +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.Po +see +.Xr zfs-mount 8 +.Pc . +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 +.El +.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 SEE ALSO +.Xr zfs-create 8 , +.Xr zfs-set 8 , +.Xr zfsprops 8 diff --git a/man/man8/zfs-mount.8 b/man/man8/zfs-mount.8 new file mode 100644 index 000000000..40229cc0b --- /dev/null +++ b/man/man8/zfs-mount.8 @@ -0,0 +1,127 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-MOUNT 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm mount +.Nd Manage mount state of ZFS file systems. +.Sh SYNOPSIS +.Nm +.Cm mount +.Nm +.Cm mount +.Op Fl Oflv +.Op Fl o Ar options +.Fl a | Ar filesystem +.Nm +.Cm unmount +.Op Fl fu +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Sh DESCRIPTION +.Bl -tag -width "" +.It Xo +.Nm +.Cm mount +.Xc +Displays all ZFS file systems currently mounted. +.It Xo +.Nm +.Cm mount +.Op Fl Oflv +.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 +.Em Temporary Mount Point Properties +section of +.Xr zfsprops 8 +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. +.It Fl f +Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets). +.El +.It Xo +.Nm +.Cm unmount +.Op Fl fu +.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 Fl f +Forcefully unmount the file system, even if it is currently in use. +.It Fl u +Unload keys for any encryption roots unmounted by this command. +.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. +.El +.El diff --git a/man/man8/zfs-project.8 b/man/man8/zfs-project.8 new file mode 100644 index 000000000..3fd7f11e6 --- /dev/null +++ b/man/man8/zfs-project.8 @@ -0,0 +1,153 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-PROJECT 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm project +.Nd List, set, or clear project ID and/or inherit flag on the file(s) or directories. +.Sh SYNOPSIS +.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 ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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 children. 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 children. 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 +Set project ID and/or inherit flag on the file(s) or directories. +.Bl -tag -width "-p" +.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 +.El +.Sh SEE ALSO +.Xr zfs-projectspace 8 diff --git a/man/man8/zfs-projectspace.8 b/man/man8/zfs-projectspace.8 new file mode 120000 index 000000000..8bc2f1df3 --- /dev/null +++ b/man/man8/zfs-projectspace.8 @@ -0,0 +1 @@ +zfs-userspace.8 \ No newline at end of file diff --git a/man/man8/zfs-promote.8 b/man/man8/zfs-promote.8 new file mode 100644 index 000000000..9e1893f43 --- /dev/null +++ b/man/man8/zfs-promote.8 @@ -0,0 +1,69 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-PROMOTE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm promote +.Nd Promotes a clone file system to no longer be dependent on its origin snapshot. +.Sh SYNOPSIS +.Nm +.Cm promote +.Ar clone-filesystem +.Sh DESCRIPTION +.Bl -tag -width "" +.It Xo +.Nm +.Cm promote +.Ar clone-filesystem +.Xc +The +.Cm promote +command 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 +.Xr zfs-rename 8 +subcommand can be used to rename any conflicting snapshots. +.El +.Sh SEE ALSO +.Xr zfs-clone 8 diff --git a/man/man8/zfs-receive.8 b/man/man8/zfs-receive.8 new file mode 100644 index 000000000..ac5711ca6 --- /dev/null +++ b/man/man8/zfs-receive.8 @@ -0,0 +1,365 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-RECEIVE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm receive +.Nd Creates a snapshot whose contents are as specified in the stream provided on standard input. +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +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. +.El +.Sh SEE ALSO +.Xr zfs-send 8 diff --git a/man/man8/zfs-recv.8 b/man/man8/zfs-recv.8 new file mode 120000 index 000000000..f11b7add7 --- /dev/null +++ b/man/man8/zfs-recv.8 @@ -0,0 +1 @@ +zfs-receive.8 \ No newline at end of file diff --git a/man/man8/zfs-redact.8 b/man/man8/zfs-redact.8 new file mode 120000 index 000000000..f7c605788 --- /dev/null +++ b/man/man8/zfs-redact.8 @@ -0,0 +1 @@ +zfs-send.8 \ No newline at end of file diff --git a/man/man8/zfs-release.8 b/man/man8/zfs-release.8 new file mode 120000 index 000000000..58809d66a --- /dev/null +++ b/man/man8/zfs-release.8 @@ -0,0 +1 @@ +zfs-hold.8 \ No newline at end of file diff --git a/man/man8/zfs-rename.8 b/man/man8/zfs-rename.8 new file mode 100644 index 000000000..272538398 --- /dev/null +++ b/man/man8/zfs-rename.8 @@ -0,0 +1,91 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-RENAME 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm rename +.Nd Renames the given dataset (filesystem or snapshot). +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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. +.El diff --git a/man/man8/zfs-rollback.8 b/man/man8/zfs-rollback.8 new file mode 100644 index 000000000..2100f595d --- /dev/null +++ b/man/man8/zfs-rollback.8 @@ -0,0 +1,81 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-ROLLBACK 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm rollback +.Nd Roll back the given dataset to a previous snapshot. +.Sh SYNOPSIS +.Nm +.Cm rollback +.Op Fl Rfr +.Ar snapshot +.Sh DESCRIPTION +.Bl -tag -width "" +.It Xo +.Nm +.Cm rollback +.Op Fl Rfr +.Ar snapshot +.Xc +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 +.El +.Sh SEE ALSO +.Xr zfs-snapshot 8 diff --git a/man/man8/zfs-send.8 b/man/man8/zfs-send.8 new file mode 100644 index 000000000..0171166eb --- /dev/null +++ b/man/man8/zfs-send.8 @@ -0,0 +1,597 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-SEND 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm send +.Nd Generate a send stream, which may be of a filesystem, and may be incremental from a bookmark. +.Sh SYNOPSIS +.Nm +.Cm send +.Op Fl DLPRbcehnpvw +.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot +.Ar snapshot +.Nm +.Cm send +.Op Fl DLPRcenpvw +.Op Fl i Ar snapshot Ns | Ns Ar bookmark +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot +.Nm +.Cm send +.Fl -redact Ar redaction_bookmark +.Op Fl DLPcenpv +.br +.Op Fl i Ar snapshot Ns | Ns Ar bookmark +.Ar snapshot +.Nm +.Cm send +.Op Fl Penv +.Fl t +.Ar receive_resume_token +.Nm +.Cm redact +.Ar snapshot redaction_bookmark +.Ar redaction_snapshot Ns ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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. +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 DLPRcenpvw +.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 +.Fl -redact Ar redaction_bookmark +.Op Fl DLPcenpv +.br +.Op Fl i Ar snapshot Ns | Ns Ar bookmark +.Ar snapshot +.Xc +Generate a redacted send stream. +This send stream contains all blocks from the snapshot being sent that aren't +included in the redaction list contained in the bookmark specified by the +.Fl -redact +(or +.Fl -d +) flag. +The resulting send stream is said to be redacted with respect to the snapshots +the bookmark specified by the +.Fl -redact No flag was created with. +The bookmark must have been created by running +.Sy zfs redact +on the snapshot being sent. +.sp +This feature can be used to allow clones of a filesystem to be made available on +a remote system, in the case where their parent need not (or needs to not) be +usable. +For example, if a filesystem contains sensitive data, and it has clones where +that sensitive data has been secured or replaced with dummy data, redacted sends +can be used to replicate the secured data without replicating the original +sensitive data, while still sharing all possible blocks. +A snapshot that has been redacted with respect to a set of snapshots will +contain all blocks referenced by at least one snapshot in the set, but will +contain none of the blocks referenced by none of the snapshots in the set. +In other words, if all snapshots in the set have modified a given block in the +parent, that block will not be sent; but if one or more snapshots have not +modified a block in the parent, they will still reference the parent's block, so +that block will be sent. +Note that only user data will be redacted. +.sp +When the redacted send stream is received, we will generate a redacted +snapshot. +Due to the nature of redaction, a redacted dataset can only be used in the +following ways: +.sp +1. To receive, as a clone, an incremental send from the original snapshot to one +of the snapshots it was redacted with respect to. +In this case, the stream will produce a valid dataset when received because all +blocks that were redacted in the parent are guaranteed to be present in the +child's send stream. +This use case will produce a normal snapshot, which can be used just like other +snapshots. +.sp +2. To receive an incremental send from the original snapshot to something +redacted with respect to a subset of the set of snapshots the initial snapshot +was redacted with respect to. +In this case, each block that was redacted in the original is still redacted +(redacting with respect to additional snapshots causes less data to be redacted +(because the snapshots define what is permitted, and everything else is +redacted)). +This use case will produce a new redacted snapshot. +.sp +3. To receive an incremental send from a redaction bookmark of the original +snapshot that was created when redacting with respect to a subset of the set of +snapshots the initial snapshot was created with respect to +anything else. +A send stream from such a redaction bookmark will contain all of the blocks +necessary to fill in any redacted data, should it be needed, because the sending +system is aware of what blocks were originally redacted. +This will either produce a normal snapshot or a redacted one, depending on +whether the new send stream is redacted. +.sp +4. To receive an incremental send from a redacted version of the initial +snapshot that is redacted with respect to a subject of the set of snapshots the +initial snapshot was created with respect to. +A send stream from a compatible redacted dataset will contain all of the blocks +necessary to fill in any redacted data. +This will either produce a normal snapshot or a redacted one, depending on +whether the new send stream is redacted. +.sp +5. To receive a full send as a clone of the redacted snapshot. +Since the stream is a full send, it definitionally contains all the data needed +to create a new dataset. +This use case will either produce a normal snapshot or a redacted one, depending +on whether the full send stream was redacted. +.sp +These restrictions are detected and enforced by \fBzfs receive\fR; a +redacted send stream will contain the list of snapshots that the stream is +redacted with respect to. +These are stored with the redacted snapshot, and are used to detect and +correctly handle the cases above. Note that for technical reasons, raw sends +and redacted sends cannot be combined at this time. +.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 redact +.Ar snapshot redaction_bookmark +.Ar redaction_snapshot Ns ... +.Xc +Generate a new redaction bookmark. +In addition to the typical bookmark information, a redaction bookmark contains +the list of redacted blocks and the list of redaction snapshots specified. +The redacted blocks are blocks in the snapshot which are not referenced by any +of the redaction snapshots. +These blocks are found by iterating over the metadata in each redaction snapshot +to determine what has been changed since the target snapshot. +Redaction is designed to support redacted zfs sends; see the entry for +.Sy zfs send +for more information on the purpose of this operation. +If a redact operation fails partway through (due to an error or a system +failure), the redaction can be resumed by rerunning the same command. +.El +.Ss Redaction +ZFS has support for a limited version of data subsetting, in the form of +redaction. Using the +.Sy zfs redact +command, a +.Sy redaction bookmark +can be created that stores a list of blocks containing sensitive information. When +provided to +.Sy zfs +.Sy send , +this causes a +.Sy redacted send +to occur. Redacted sends omit the blocks containing sensitive information, +replacing them with REDACT records. When these send streams are received, a +.Sy redacted dataset +is created. A redacted dataset cannot be mounted by default, since it is +incomplete. It can be used to receive other send streams. In this way datasets +can be used for data backup and replication, with all the benefits that zfs send +and receive have to offer, while protecting sensitive information from being +stored on less-trusted machines or services. +.Pp +For the purposes of redaction, there are two steps to the process. A redact +step, and a send/receive step. First, a redaction bookmark is created. This is +done by providing the +.Sy zfs redact +command with a parent snapshot, a bookmark to be created, and a number of +redaction snapshots. These redaction snapshots must be descendants of the +parent snapshot, and they should modify data that is considered sensitive in +some way. Any blocks of data modified by all of the redaction snapshots will +be listed in the redaction bookmark, because it represents the truly sensitive +information. When it comes to the send step, the send process will not send +the blocks listed in the redaction bookmark, instead replacing them with +REDACT records. When received on the target system, this will create a +redacted dataset, missing the data that corresponds to the blocks in the +redaction bookmark on the sending system. The incremental send streams from +the original parent to the redaction snapshots can then also be received on +the target system, and this will produce a complete snapshot that can be used +normally. Incrementals from one snapshot on the parent filesystem and another +can also be done by sending from the redaction bookmark, rather than the +snapshots themselves. +.Pp +In order to make the purpose of the feature more clear, an example is +provided. Consider a zfs filesystem containing four files. These files +represent information for an online shopping service. One file contains a list +of usernames and passwords, another contains purchase histories, a third +contains click tracking data, and a fourth contains user preferences. The +owner of this data wants to make it available for their development teams to +test against, and their market research teams to do analysis on. The +development teams need information about user preferences and the click +tracking data, while the market research teams need information about purchase +histories and user preferences. Neither needs access to the usernames and +passwords. However, because all of this data is stored in one ZFS filesystem, +it must all be sent and received together. In addition, the owner of the data +wants to take advantage of features like compression, checksumming, and +snapshots, so they do want to continue to use ZFS to store and transmit their +data. Redaction can help them do so. First, they would make two clones of a +snapshot of the data on the source. In one clone, they create the setup they +want their market research team to see; they delete the usernames and +passwords file, and overwrite the click tracking data with dummy +information. In another, they create the setup they want the development teams +to see, by replacing the passwords with fake information and replacing the +purchase histories with randomly generated ones. They would then create a +redaction bookmark on the parent snapshot, using snapshots on the two clones +as redaction snapshots. The parent can then be sent, redacted, to the target +server where the research and development teams have access. Finally, +incremental sends from the parent snapshot to each of the clones can be send +to and received on the target server; these snapshots are identical to the +ones on the source, and are ready to be used, while the parent snapshot on the +target contains none of the username and password data present on the source, +because it was removed by the redacted send operation. +.Sh SEE ALSO +.Xr zfs-bookmark 8 , +.Xr zfs-receive 8 , +.Xr zfs-redact 8 , +.Xr zfs-snapshot 8 diff --git a/man/man8/zfs-set.8 b/man/man8/zfs-set.8 new file mode 100644 index 000000000..f1aeef15d --- /dev/null +++ b/man/man8/zfs-set.8 @@ -0,0 +1,188 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-SET 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm set +.Nd Sets the property or list of properties to the given value(s) for each dataset. +.Sh SYNOPSIS +.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 ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +Only some properties can be edited. +See +.Xr zfsprops 8 +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 +.Em User Properties +section of +.Xr zfsprops 8 . +.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 +.Em Native Properties +and +.Em User Properties +sections of +.Xr zfsprops 8 . +.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 +.Xr zfsprops 8 +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 +.El +.Sh SEE ALSO +.Xr zfs-list 8 , +.Xr zfsprops 8 diff --git a/man/man8/zfs-share.8 b/man/man8/zfs-share.8 new file mode 100644 index 000000000..3b0ef791e --- /dev/null +++ b/man/man8/zfs-share.8 @@ -0,0 +1,88 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-SHARE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm share +.Nd Shares and unshares available ZFS filesystems. +.Sh SYNOPSIS +.Nm +.Cm share +.Fl a | Ar filesystem +.Nm +.Cm unshare +.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.El +.Sh SEE ALSO +.Xr exports 5 , +.Xr smb.conf 5 , +.Xr zfsprops 8 diff --git a/man/man8/zfs-snapshot.8 b/man/man8/zfs-snapshot.8 new file mode 100644 index 000000000..b8d8367f8 --- /dev/null +++ b/man/man8/zfs-snapshot.8 @@ -0,0 +1,83 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-SNAPSHOT 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm snapshot +.Nd Creates snapshots with the given names. +.Sh SYNOPSIS +.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 ... +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +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 +.Em Snapshots +section of +.Xr zfsconcepts 8 +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 +.El +.Sh SEE ALSO +.Xr zfs-bookmark 8 , +.Xr zfs-clone 8 , +.Xr zfs-destroy 8 , +.Xr zfs-diff 8 , +.Xr zfs-hold 8 , +.Xr zfs-rename 8 , +.Xr zfs-rollback 8 , +.Xr zfs-send 8 diff --git a/man/man8/zfs-unallow.8 b/man/man8/zfs-unallow.8 new file mode 120000 index 000000000..8886f334b --- /dev/null +++ b/man/man8/zfs-unallow.8 @@ -0,0 +1 @@ +zfs-allow.8 \ No newline at end of file diff --git a/man/man8/zfs-unload-key.8 b/man/man8/zfs-unload-key.8 new file mode 120000 index 000000000..d027a419d --- /dev/null +++ b/man/man8/zfs-unload-key.8 @@ -0,0 +1 @@ +zfs-load-key.8 \ No newline at end of file diff --git a/man/man8/zfs-unmount.8 b/man/man8/zfs-unmount.8 new file mode 120000 index 000000000..be0d9dbf6 --- /dev/null +++ b/man/man8/zfs-unmount.8 @@ -0,0 +1 @@ +zfs-mount.8 \ No newline at end of file diff --git a/man/man8/zfs-upgrade.8 b/man/man8/zfs-upgrade.8 new file mode 100644 index 000000000..6cd06e2c9 --- /dev/null +++ b/man/man8/zfs-upgrade.8 @@ -0,0 +1,106 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-UPGRADE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm upgrade +.Nd Manage upgrading the on-disk version of filesystems. +.Sh SYNOPSIS +.Nm +.Cm upgrade +.Nm +.Cm upgrade +.Fl v +.Nm +.Cm upgrade +.Op Fl r +.Op Fl V Ar version +.Fl a | Ar filesystem +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.El +.Sh SEE ALSO +.Xr zpool-upgrade 8 diff --git a/man/man8/zfs-userspace.8 b/man/man8/zfs-userspace.8 new file mode 100644 index 000000000..50bca9115 --- /dev/null +++ b/man/man8/zfs-userspace.8 @@ -0,0 +1,186 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFS-USERSPACE 8 +.Os Linux +.Sh NAME +.Nm zfs Ns Pf - Cm userspace +.Nd Displays space consumed by, and quotas on, each user or group in the specified filesystem or snapshot. +.Sh SYNOPSIS +.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 +.Sh DESCRIPTION +.Bl -tag -width "" +.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 +.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 +.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. +.El +.Sh SEE ALSO +.Xr zfs-set 8 , +.Xr zfsprops 8 diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index e391b9810..1f100ab9e 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -31,7 +31,7 @@ .\" Copyright 2019 Joyent, Inc. .\" .Dd June 30, 2019 -.Dt ZFS 8 SMM +.Dt ZFS 8 .Os Linux .Sh NAME .Nm zfs @@ -40,307 +40,10 @@ .Nm .Fl ?V .Nm -.Cm create -.Op Fl Pnpv -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem -.Nm -.Cm create -.Op Fl Pnpsv -.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 Oflv -.Op Fl o Ar options -.Fl a | Ar filesystem -.Nm -.Cm unmount -.Op Fl fu -.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 DLPcenpvw -.Oo Fl i Ar snapshot Ns | Ns Ar bookmark -.Oc -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot -.Nm -.Cm send -.Fl -redact Ar redaction_bookmark -.Op Fl DLPcenpv -.Op Fl i Ar snapshot Ns | Ns Ar bookmark -.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 redact -.Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... -.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 +.Nm +.Cm +.Op Ar .Sh DESCRIPTION The .Nm @@ -381,172 +84,16 @@ or .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 +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 +For details see +.Xr zfsconcepts 8 . +.Ss Properties Properties are divided into two types, native properties and user-defined .Po or .Qq user @@ -556,1991 +103,20 @@ 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 dataset) 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 redact_snaps -For bookmarks, this is the list of snapshot guids the bookmark contains a redaction -list for. -For snapshots, this is the list of snapshot guids the snapshot is redacted with -respect to. -.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 comparison 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-ccm . -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 -.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 128K. 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/ -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 snapshotted, 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. +For more information about properties, see the +.Xr zfsprops 8 man page. .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, +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. -.Ss Redaction -ZFS has support for a limited version of data subsetting, in the form of -redaction. Using the -.Sy zfs redact -command, a -.Sy redaction bookmark -can be created that stores a list of blocks containing sensitive information. When -provided to -.Sy zfs -.Sy send , -this causes a -.Sy redacted send -to occur. Redacted sends omit the blocks containing sensitive information, -replacing them with REDACT records. When these send streams are received, a -.Sy redacted dataset -is created. A redacted dataset cannot be mounted by default, since it is -incomplete. It can be used to receive other send streams. In this way datasets -can be used for data backup and replication, with all the benefits that zfs send -and receive have to offer, while protecting sensitive information from being -stored on less-trusted machines or services. -.Pp -For the purposes of redaction, there are two steps to the process. A redact -step, and a send/receive step. First, a redaction bookmark is created. This is -done by providing the -.Sy zfs redact -command with a parent snapshot, a bookmark to be created, and a number of -redaction snapshots. These redaction snapshots must be descendants of the -parent snapshot, and they should modify data that is considered sensitive in -some way. Any blocks of data modified by all of the redaction snapshots will -be listed in the redaction bookmark, because it represents the truly sensitive -information. When it comes to the send step, the send process will not send -the blocks listed in the redaction bookmark, instead replacing them with -REDACT records. When received on the target system, this will create a -redacted dataset, missing the data that corresponds to the blocks in the -redaction bookmark on the sending system. The incremental send streams from -the original parent to the redaction snapshots can then also be received on -the target system, and this will produce a complete snapshot that can be used -normally. Incrementals from one snapshot on the parent filesystem and another -can also be done by sending from the redaction bookmark, rather than the -snapshots themselves. -.Pp -In order to make the purpose of the feature more clear, an example is -provided. Consider a zfs filesystem containing four files. These files -represent information for an online shopping service. One file contains a list -of usernames and passwords, another contains purchase histories, a third -contains click tracking data, and a fourth contains user preferences. The -owner of this data wants to make it available for their development teams to -test against, and their market research teams to do analysis on. The -development teams need information about user preferences and the click -tracking data, while the market research teams need information about purchase -histories and user preferences. Neither needs access to the usernames and -passwords. However, because all of this data is stored in one ZFS filesystem, -it must all be sent and received together. In addition, the owner of the data -wants to take advantage of features like compression, checksumming, and -snapshots, so they do want to continue to use ZFS to store and transmit their -data. Redaction can help them do so. First, they would make two clones of a -snapshot of the data on the source. In one clone, they create the setup they -want their market research team to see; they delete the usernames and -passwords file, and overwrite the click tracking data with dummy -information. In another, they create the setup they want the development teams -to see, by replacing the passwords with fake information and replacing the -purchase histories with randomly generated ones. They would then create a -redaction bookmark on the parent snapshot, using snapshots on the two clones -as redaction snapshots. The parent can then be sent, redacted, to the target -server where the research and development teams have access. Finally, -incremental sends from the parent snapshot to each of the clones can be send -to and received on the target server; these snapshots are identical to the -ones on the source, and are ready to be used, while the parent snapshot on the -target contains none of the username and password data present on the source, -because it was removed by the redacted send operation. +data. +For an overview of encryption see the +.Xr zfs-load-key 8 command manual. .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their original form. @@ -2549,2394 +125,148 @@ original form. Displays a help message. .It Xo .Nm -.Fl V, -version +.Fl V , -version .Xc An alias for the .Nm zfs Cm version subcommand. .It Xo .Nm -.Cm create -.Op Fl Pnpv -.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. -.It Fl n -Do a dry-run -.Pq Qq No-op -creation. -No datasets will be created. -This is useful in conjunction with the -.Fl v -or -.Fl P -flags to validate properties that are passed via -.Fl o -options and those implied by other options. -The actual dataset creation can still fail due to insufficient privileges or -available capacity. -.It Fl P -Print machine-parsable verbose information about the created dataset. -Each line of output contains a key and one or two values, all separated by tabs. -The -.Sy create_ancestors -and -.Sy create -keys have -.Em filesystem -as their only value. -The -.Sy create_ancestors -key only appears if the -.Fl p -option is used. -The -.Sy property -key has two values, a property name that property's value. -The -.Sy property -key may appear zero or more times, once for each property that will be set local -to -.Em filesystem -due to the use of the -.Fl o -option. -.It Fl v -Print verbose information about the created dataset. -.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. -.It Fl n -Do a dry-run -.Pq Qq No-op -creation. -No datasets will be created. -This is useful in conjunction with the -.Fl v -or -.Fl P -flags to validate properties that are passed via -.Fl o -options and those implied by other options. -The actual dataset creation can still fail due to insufficient privileges or -available capacity. -.It Fl P -Print machine-parsable verbose information about the created dataset. -Each line of output contains a key and one or two values, all separated by tabs. -The -.Sy create_ancestors -and -.Sy create -keys have -.Em volume -as their only value. -The -.Sy create_ancestors -key only appears if the -.Fl p -option is used. -The -.Sy property -key has two values, a property name that property's value. -The -.Sy property -key may appear zero or more times, once for each property that will be set local -to -.Em volume -due to the use of the -.Fl b -or -.Fl o -options, as well as -.Sy refreservation -if the volume is not sparse. -.It Fl v -Print verbose information about the created dataset. -.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 children. 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 children. 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 Oflv -.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. -.It Fl f -Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets). -.El -.It Xo -.Nm -.Cm unmount -.Op Fl fu -.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 Fl f -Forcefully unmount the file system, even if it is currently in use. -.It Fl u -Unload keys for any encryption roots unmounted by this command. -.El -.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 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. -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 DLPRcenpvw -.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 -.Fl -redact Ar redaction_bookmark -.Op Fl DLPcenpv -.br -.Op Fl i Ar snapshot Ns | Ns Ar bookmark -.Ar snapshot -.Xc -Generate a redacted send stream. -This send stream contains all blocks from the snapshot being sent that aren't -included in the redaction list contained in the bookmark specified by the -.Fl -redact -(or -.Fl -d -) flag. -The resulting send stream is said to be redacted with respect to the snapshots -the bookmark specified by the -.Fl -redact No flag was created with. -The bookmark must have been created by running -.Sy zfs redact -on the snapshot being sent. -.sp -This feature can be used to allow clones of a filesystem to be made available on -a remote system, in the case where their parent need not (or needs to not) be -usable. -For example, if a filesystem contains sensitive data, and it has clones where -that sensitive data has been secured or replaced with dummy data, redacted sends -can be used to replicate the secured data without replicating the original -sensitive data, while still sharing all possible blocks. -A snapshot that has been redacted with respect to a set of snapshots will -contain all blocks referenced by at least one snapshot in the set, but will -contain none of the blocks referenced by none of the snapshots in the set. -In other words, if all snapshots in the set have modified a given block in the -parent, that block will not be sent; but if one or more snapshots have not -modified a block in the parent, they will still reference the parent's block, so -that block will be sent. -Note that only user data will be redacted. -.sp -When the redacted send stream is received, we will generate a redacted -snapshot. -Due to the nature of redaction, a redacted dataset can only be used in the -following ways: -.sp -1. To receive, as a clone, an incremental send from the original snapshot to one -of the snapshots it was redacted with respect to. -In this case, the stream will produce a valid dataset when received because all -blocks that were redacted in the parent are guaranteed to be present in the -child's send stream. -This use case will produce a normal snapshot, which can be used just like other -snapshots. -.sp -2. To receive an incremental send from the original snapshot to something -redacted with respect to a subset of the set of snapshots the initial snapshot -was redacted with respect to. -In this case, each block that was redacted in the original is still redacted -(redacting with respect to additional snapshots causes less data to be redacted -(because the snapshots define what is permitted, and everything else is -redacted)). -This use case will produce a new redacted snapshot. -.sp -3. To receive an incremental send from a redaction bookmark of the original -snapshot that was created when redacting with respect to a subset of the set of -snapshots the initial snapshot was created with respect to -anything else. -A send stream from such a redaction bookmark will contain all of the blocks -necessary to fill in any redacted data, should it be needed, because the sending -system is aware of what blocks were originally redacted. -This will either produce a normal snapshot or a redacted one, depending on -whether the new send stream is redacted. -.sp -4. To receive an incremental send from a redacted version of the initial -snapshot that is redacted with respect to a subject of the set of snapshots the -initial snapshot was created with respect to. -A send stream from a compatible redacted dataset will contain all of the blocks -necessary to fill in any redacted data. -This will either produce a normal snapshot or a redacted one, depending on -whether the new send stream is redacted. -.sp -5. To receive a full send as a clone of the redacted snapshot. -Since the stream is a full send, it definitionally contains all the data needed -to create a new dataset. -This use case will either produce a normal snapshot or a redacted one, depending -on whether the full send stream was redacted. -.sp -These restrictions are detected and enforced by \fBzfs receive\fR; a -redacted send stream will contain the list of snapshots that the stream is -redacted with respect to. -These are stored with the redacted snapshot, and are used to detect and -correctly handle the cases above. Note that for technical reasons, raw sends -and redacted sends cannot be combined at this time. -.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 -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 redact -.Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... -.Xc -Generate a new redaction bookmark. -In addition to the typical bookmark information, a redaction bookmark contains -the list of redacted blocks and the list of redaction snapshots specified. -The redacted blocks are blocks in the snapshot which are not referenced by any -of the redaction snapshots. -These blocks are found by iterating over the metadata in each redaction snapshot -to determine what has been changed since the target snapshot. -Redaction is designed to support redacted zfs sends; see the entry for -.Sy zfs send -for more information on the purpose of this operation. -If a redact operation fails partway through (due to an error or a system -failure), the redaction can be resumed by rerunning the same command. -.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 +.Ss Dataset Management +.Bl -tag -width "" +.It Xr zfs-list 8 +Lists the property information for the given datasets in tabular form. +.It Xr zfs-create 8 +Creates a new ZFS file system or volume. +.It Xr zfs-destroy 8 +Destroys the given dataset(s), snapshot(s), or bookmark. +.It Xr zfs-rename 8 +Renames the given dataset (filesystem or snapshot). +.It Xr zfs-upgrade 8 +Manage upgrading the on-disk version of filesystems. +.El +.Ss Snapshots +.Bl -tag -width "" +.It Xr zfs-snapshot 8 +Creates snapshots with the given names. +.It Xr zfs-rollback 8 +Roll back the given dataset to a previous snapshot. +.It Xo +.Xr zfs-hold 8 / +.Xr zfs-release 8 +.Xc +Add or remove a hold reference to the specified snapshot or snapshots. +If a hold exists on a snapshot, attempts to destroy that snapshot by using the +.Nm zfs Cm destroy +command return +.Er EBUSY . +.It Xr zfs-diff 8 +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. +.El +.Ss Clones +.Bl -tag -width "" +.It Xr zfs-clone 8 +Creates a clone of the given snapshot. +.It Xr zfs-promote 8 +Promotes a clone file system to no longer be dependent on its +.Qq origin +snapshot. +.El +.Ss Send & Receive +.Bl -tag -width "" +.It Xr zfs-send 8 +Generate a send stream, which may be of a filesystem, and may be incremental +from a bookmark. +.It Xr zfs-receive 8 +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 +.Xr zfs-send 8 +subcommand, which by default creates a full stream. +.It Xr zfs-bookmark 8 +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. +.It Xr zfs-redact 8 +Generate a new redaction bookmark. +This feature can be used to allow clones of a filesystem to be made available on +a remote system, in the case where their parent need not (or needs to not) be +usable. +.El +.Ss Properties +.Bl -tag -width "" +.It Xr zfs-get 8 +Displays properties for the given datasets. +.It Xr zfs-set 8 +Sets the property or list of properties to the given value(s) for each dataset. +.It Xr zfs-inherit 8 +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. +.El +.Ss Quotas +.Bl -tag -width "" +.It Xo +.Xr zfs-userspace 8 / +.Xr zfs-groupspace 8 / +.Xr zfs-projectspace 8 +.Xc +Displays space consumed by, and quotas on, each user, group, or project +in the specified filesystem or snapshot. +.It Xr zfs-project 8 +List, set, or clear project ID and/or inherit flag on the file(s) or directories. +.El +.Ss Mountpoints +.Bl -tag -width "" +.It Xr zfs-mount 8 +Displays all ZFS file systems currently mounted, or mount ZFS filesystem +on a path described by its +.Sy mountpoint +property. +.It Xr zfs-unmount 8 +Unmounts currently mounted ZFS file systems. +.El +.Ss Shares +.Bl -tag -width "" +.It Xr zfs-share 8 +Shares available ZFS file systems. +.It Xr zfs-unshare 8 +Unshares currently shared ZFS file systems. +.El +.Ss Delegated Administration +.Bl -tag -width "" +.It Xr zfs-allow 8 +Delegate permissions on the specified filesystem or volume. +.It Xr zfs-unallow 8 +Remove delegated permissions on the specified filesystem or volume. +.El +.Ss Encryption +.Bl -tag -width "" +.It Xr zfs-change-key 8 +Add or change an encryption key on the specified dataset. +.It Xr zfs-load-key 8 +Load the key for the specified encrypted dataset, enabling access. +.It Xr zfs-unload-key 8 +Unload a key for the specified dataset, removing the ability to access the dataset. +.El +.Ss Channel Programs +.Bl -tag -width "" +.It Xr zfs-program 8 +Execute ZFS administrative operations +programmatically via a Lua script-language channel program. +.El .Sh EXIT STATUS The .Nm @@ -5321,14 +651,14 @@ R F /tank/test/oldname -> /tank/test/newname 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. +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. +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 @@ -5339,12 +669,13 @@ Minimal 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. +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. +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. @@ -5354,7 +685,8 @@ See the 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 +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 @@ -5375,5 +707,6 @@ command will be undone if the share is ever unshared (such as at a reboot etc). .Xr mount 8 , .Xr net 8 , .Xr selinux 8 , -.Xr zfs-program 8 , +.Xr zfsconcepts 8 , +.Xr zfsprops 8 , .Xr zpool 8 diff --git a/man/man8/zfsconcepts.8 b/man/man8/zfsconcepts.8 new file mode 100644 index 000000000..6eeb897b4 --- /dev/null +++ b/man/man8/zfsconcepts.8 @@ -0,0 +1,198 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFSCONCEPTS 8 +.Os Linux +.Sh NAME +.Nm zfsconcepts +.Nd An overview of ZFS concepts. +.Sh DESCRIPTION +.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. diff --git a/man/man8/zfsprops.8 b/man/man8/zfsprops.8 new file mode 100644 index 000000000..5aed2ec15 --- /dev/null +++ b/man/man8/zfsprops.8 @@ -0,0 +1,1884 @@ +.\" +.\" 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 +.\" 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 2019 Joyent, Inc. +.\" +.Dd June 30, 2019 +.Dt ZFSPROPS 8 +.Os Linux +.Sh NAME +.Nm zfsprops +.Nd Native properties and user-defined of ZFS datasets. +.Sh DESCRIPTION +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. +.Ss Native Properties +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 +.Em Encryption +section of +.Xr zfs-load-key 8 +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 dataset) 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 redact_snaps +For bookmarks, this is the list of snapshot guids the bookmark contains a redaction +list for. +For snapshots, this is the list of snapshot guids the snapshot is redacted with +respect to. +.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 +.Em Snapshots +section of +.Xr zfsconcepts 8 +.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 comparison 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 the +.Em Deduplication +section of +.Xr zfsconcepts 8 . +.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-ccm . +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 +.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 128K. 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 +.Em Mount Points +section of +.Xr zfsconcepts 8 +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/ +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 +.Em Snapshots +section of +.Xr zfsconcepts 8 . +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 snapshotted, 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.