X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=man%2Fman8%2Fzfs.8;h=be28f2b62a86bdeae9e698b30ae2b2b07a339a49;hb=6e91a72fe3ff8bb282490773bd687632f3e8c79d;hp=2e1ffc6ea728de0d918332c4e5c27bd6cd9de3e0;hpb=5b72a38d68453c91bf57cba11789a240199b695d;p=mirror_zfs.git diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index 2e1ffc6ea..be28f2b62 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -27,9 +27,10 @@ .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. .\" Copyright (c) 2014 Integros [integros.com] .\" Copyright 2016 Richard Laager. All rights reserved. -.\" Copyright 2017 Nexenta Systems, Inc. +.\" Copyright 2018 Nexenta Systems, Inc. +.\" Copyright 2018 Joyent, Inc. .\" -.Dd January 10, 2018 +.Dd Jan 05, 2019 .Dt ZFS 8 SMM .Os Linux .Sh NAME @@ -113,7 +114,7 @@ .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 ... -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... .Nm .Cm inherit .Op Fl rS @@ -145,6 +146,34 @@ .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 @@ -166,7 +195,7 @@ .Ar snapshot bookmark .Nm .Cm send -.Op Fl DLPRcenpvw +.Op Fl DLPRbcenpvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Nm @@ -260,7 +289,7 @@ .Ar tag Ar snapshot Ns ... .Nm .Cm holds -.Op Fl r +.Op Fl rH .Ar snapshot Ns ... .Nm .Cm release @@ -272,7 +301,7 @@ .Ar snapshot Ar snapshot Ns | Ns Ar filesystem .Nm .Cm program -.Op Fl n +.Op Fl jn .Op Fl t Ar timeout .Op Fl m Ar memory_limit .Ar pool script @@ -311,7 +340,8 @@ pool/{filesystem,volume,snapshot} .Pp where the maximum length of a dataset name is .Dv MAXNAMELEN -.Pq 256 bytes . +.Pq 256 bytes +and the maximum amount of nesting allowed in a path is 50 levels deep. .Pp A dataset can be one of the following: .Bl -tag -width "file system" @@ -685,6 +715,16 @@ This property can be either .Sy yes or .Sy no . +.It Sy objsetid +A unique identifier for this dataset within the pool. Unlike the dataset's +.Sy guid +, the +.Sy objsetid +of a dataset is not transferred to other pools when the snapshot is copied +with a send/receive operation. +The +.Sy objsetid +can be reused (for a new datatset) after the dataset is deleted. .It Sy origin For cloned file systems or volumes, the snapshot from which the clone was created. @@ -905,6 +945,56 @@ The root user, or a user who has been granted the 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 @@ -989,7 +1079,7 @@ accordance to the requested mode from the application. .Pp The .Sy aclinherit -property does not apply to posix ACLs. +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" @@ -1001,8 +1091,8 @@ property set to off then ACLs are disabled. 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 +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 @@ -1011,8 +1101,8 @@ 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 of this all new extended attributes will only be +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 @@ -1101,15 +1191,14 @@ The and .Sy edonr checksum algorithms require enabling the appropriate features on the pool. +These algorithms are not supported by GRUB and should not be set on the +.Sy bootfs +filesystem when using GRUB to boot the system. Please see .Xr zpool-features 5 for more information on these algorithms. .Pp Changing this property affects only newly-written data. -.Pp -Salted checksum algorithms -.Pq Cm edonr , skein -are currently not supported for any filesystem on the boot pools. .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 @@ -1252,6 +1341,36 @@ and .Sy nodev mount options. .It Xo +.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns +.Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns +.Sy edonr,verify +.Xc +Configures deduplication for a dataset. The default value is +.Sy off . +The default deduplication checksum is +.Sy sha256 +(this may change in the future). When +.Sy dedup +is enabled, the checksum defined here overrides the +.Sy checksum +property. Setting the value to +.Sy verify +has the same effect as the setting +.Sy sha256,verify. +.Pp +If set to +.Sy verify , +ZFS will do a byte-to-byte comparsion in case of two blocks having the same +signature to make sure the block contents are identical. Specifying +.Sy verify +is mandatory for the +.Sy edonr +algorithm. +.Pp +Unless necessary, deduplication should NOT be enabled on a system. See +.Sx Deduplication +above. +.It Xo .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k .Xc @@ -1332,9 +1451,9 @@ 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 +.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 @@ -1400,6 +1519,16 @@ 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. 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 @@ -1566,6 +1695,27 @@ is similar to 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 @@ -1661,7 +1811,7 @@ 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 +.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 @@ -1679,6 +1829,22 @@ 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 @@ -1893,22 +2059,39 @@ Extreme care should be used when adjusting the volume size. Though not recommended, a .Qq sparse volume .Po also known as -.Qq thin provisioning +.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 reservation after the volume has been created. +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 reservation is less then the volume size. +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 reservation. +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 @@ -1975,7 +2158,7 @@ on platforms which do not support the 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 +SELinux or POSIX ACLs. Both of these features heavily rely of extended attributes and benefit significantly from the reduced access time. .Pp The values @@ -2429,7 +2612,8 @@ If this flag is specified, the .Fl d flag will have no effect. .It Fl d -Defer snapshot deletion. +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 @@ -2632,9 +2816,8 @@ property is .Po the default is .Sy off .Pc . -The following fields are displayed, -.Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns -.Sy mountpoint . +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. @@ -2755,7 +2938,7 @@ section. .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 ... -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark 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 @@ -2765,8 +2948,8 @@ For each property, the following columns are displayed: name Dataset name property Property name value Property value - source Property source. Can either be local, default, - temporary, inherited, or none (-). + 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 @@ -2811,6 +2994,7 @@ Each source must be one of the following: .Sy default , .Sy inherited , .Sy temporary , +.Sy received , and .Sy none . The default value is all sources. @@ -3000,6 +3184,114 @@ except that the default types to display are .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . .It Xo .Nm +.Cm projectspace +.Op Fl Hp +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc +.Oo Fl s Ar field Oc Ns ... +.Oo Fl S Ar field Oc Ns ... +.Ar filesystem Ns | Ns Ar snapshot +.Xc +Displays space consumed by, and quotas on, each project in the specified +filesystem or snapshot. This subcommand is identical to +.Nm zfs Cm userspace , +except that the project identifier is numeral, not name. So need neither +the option +.Sy -i +for SID to POSIX ID nor +.Sy -n +for numeric ID, nor +.Sy -t +for types. +.It Xo +.Nm +.Cm project +.Oo Fl d Ns | Ns Fl r Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +List project identifier (ID) and inherit flag of file(s) or directories. +.Bl -tag -width "-d" +.It Fl d +Show the directory project ID and inherit flag, not its childrens. It will +overwrite the former specified +.Fl r +option. +.It Fl r +Show on subdirectories recursively. It will overwrite the former specified +.Fl d +option. +.El +.It Xo +.Nm +.Cm project +.Fl C +.Oo Fl kr Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +Clear project inherit flag and/or ID on the file(s) or directories. +.Bl -tag -width "-k" +.It Fl k +Keep the project ID unchanged. If not specified, the project ID will be reset +as zero. +.It Fl r +Clear on subdirectories recursively. +.El +.It Xo +.Nm +.Cm project +.Fl c +.Oo Fl 0 Ns Oc +.Oo Fl d Ns | Ns Fl r Ns Oc +.Op Fl p Ar id +.Ar file Ns | Ns Ar directory Ns ... +.Xc +Check project ID and inherit flag on the file(s) or directories, report the +entries without project inherit flag or with different project IDs from the +specified (via +.Fl p +option) value or the target directory's project ID. +.Bl -tag -width "-0" +.It Fl 0 +Print file name with a trailing NUL instead of newline (by default), like +"find -print0". +.It Fl d +Check the directory project ID and inherit flag, not its childrens. It will +overwrite the former specified +.Fl r +option. +.It Fl p +Specify the referenced ID for comparing with the target file(s) or directories' +project IDs. If not specified, the target (top) directory's project ID will be +used as the referenced one. +.It Fl r +Check on subdirectories recursively. It will overwrite the former specified +.Fl d +option. +.El +.It Xo +.Nm +.Cm project +.Op Fl p Ar id +.Oo Fl rs Ns Oc +.Ar file Ns | Ns Ar directory Ns ... +.Xc +.Bl -tag -width "-p" +Set project ID and/or inherit flag on the file(s) or directories. +.It Fl p +Set the file(s)' or directories' project ID with the given value. +.It Fl r +Set on subdirectories recursively. +.It Fl s +Set project inherit flag on the given file(s) or directories. It is usually used +for setup tree quota on the directory target with +.Fl r +option specified together. When setup tree quota, by default the directory's +project ID will be set to all its descendants unless you specify the project +ID via +.Fl p +option explicitly. +.El +.It Xo +.Nm .Cm mount .Xc Displays all ZFS file systems currently mounted. @@ -3114,7 +3406,7 @@ feature. .It Xo .Nm .Cm send -.Op Fl DLPRcenpvw +.Op Fl DLPRbcenpvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Xc @@ -3210,6 +3502,14 @@ See 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 @@ -3620,6 +3920,34 @@ results if the same property is specified in multiple 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. @@ -3709,7 +4037,8 @@ command restricts modifications of the global namespace to the root user. .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 -.br +.Xc +.It Xo .Nm .Cm allow .Op Fl dl @@ -3812,6 +4141,11 @@ 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 @@ -3887,7 +4221,8 @@ and can be no more than 64 characters long. .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 -.br +.Xc +.It Xo .Nm .Cm unallow .Op Fl dlr @@ -3895,7 +4230,8 @@ and can be no more than 64 characters long. .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 -.br +.Xc +.It Xo .Nm .Cm unallow .Op Fl r @@ -3969,7 +4305,7 @@ of all descendent file systems. .It Xo .Nm .Cm holds -.Op Fl r +.Op Fl rH .Ar snapshot Ns ... .Xc Lists all existing user references for the given snapshot or snapshots. @@ -3977,6 +4313,8 @@ Lists all existing user references for the given snapshot or snapshots. .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 @@ -4043,7 +4381,7 @@ Display the path's inode change time as the first column of output. .It Xo .Nm .Cm program -.Op Fl n +.Op Fl jn .Op Fl t Ar timeout .Op Fl m Ar memory_limit .Ar pool script @@ -4065,6 +4403,10 @@ 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 @@ -4456,9 +4798,9 @@ renames the remaining snapshots, and then creates a new snapshot, as follows: # zfs destroy -r pool/users@7daysago # zfs rename -r pool/users@6daysago @7daysago # zfs rename -r pool/users@5daysago @6daysago -# zfs rename -r pool/users@yesterday @5daysago -# zfs rename -r pool/users@yesterday @4daysago -# zfs rename -r pool/users@yesterday @3daysago +# zfs rename -r pool/users@4daysago @5daysago +# zfs rename -r pool/users@3daysago @4daysago +# zfs rename -r pool/users@2daysago @3daysago # zfs rename -r pool/users@yesterday @2daysago # zfs rename -r pool/users@today @yesterday # zfs snapshot -r pool/users@today