diff options
Diffstat (limited to 'usr/src/man/man1m/zfs.1m')
| -rw-r--r-- | usr/src/man/man1m/zfs.1m | 466 |
1 files changed, 445 insertions, 21 deletions
diff --git a/usr/src/man/man1m/zfs.1m b/usr/src/man/man1m/zfs.1m index d80006ddeb..c9b25085cd 100644 --- a/usr/src/man/man1m/zfs.1m +++ b/usr/src/man/man1m/zfs.1m @@ -151,7 +151,7 @@ .Cm mount .Nm .Cm mount -.Op Fl Ov +.Op Fl Olv .Op Fl o Ar options .Fl a | Ar filesystem .Nm @@ -169,7 +169,7 @@ .Ar snapshot bookmark .Nm .Cm send -.Op Fl DLPRcenpv +.Op Fl DLPRcenpvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Nm @@ -276,6 +276,22 @@ .Op Fl m Ar memory_limit .Ar pool script .Op Ar arg1 No ... +.Nm +.Cm load-key +.Op Fl rn +.Op Fl L Ar keylocation +.Op Fl a Ns | Ns Ar filesystem +.Nm +.Cm unload-key +.Op Fl r +.Op Fl a Ns | Ns Ar filesystem +.Nm +.Cm change-key +.Op Fl l +.Op Fl o Sy keylocation Ns = Ns Ar value +.Op Fl o Sy keyformat Ns = Ns Ar value +.Op Fl o Sy pbkdf2iters Ns = Ns Ar value +.Ar filesystem .Sh DESCRIPTION The .Nm @@ -582,6 +598,21 @@ if the snapshot has been marked for deferred destroy by using the 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 +.Po see +.Nm zfs Cm load-key +and +.Nm zfs Cm unload-key +.Pc . +Clones will always share an encryption key with their origin. +See the +.Sy Encryption +section for details. .It Sy filesystem_count The total number of filesystems and volumes that exist under this location in the dataset tree. @@ -596,6 +627,16 @@ GUID. Thus, the .Sy guid is suitable to identify a snapshot across pools. +.It Sy keystatus +Indicates if an encryption key is currently loaded into ZFS. +The possible values are +.Sy none , available , +and +.Sy unavailable . +See +.Nm Cm load-key +and +.Nm Cm unload-key . .It Sy logicalreferenced The amount of space that is .Qq logically @@ -1111,6 +1152,78 @@ option. Controls whether device nodes can be opened on this file system. The default value is .Sy on . +.It Xo +.Sy encryption Ns = Ns Sy on Ns | Ns Sy off 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 +.Pq block cipher, key length, and mode +used for this dataset. +Requires the 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 +.Sx 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 for encrypted datasets which are encryption roots. +.Pp +Raw keys and hex keys must be 32 bytes long +.Pq 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 +.Po see the +.Nm pbkdf2iters +property +.Pc . +Even though the encryption suite cannot be changed after dataset creation, the +keyformat can be with +.Nm Cm change-key . +.It Sy keylocation Ns = Ns Sy prompt Ns | Ns Ar file://<absolute file path> +Controls where the user's encryption key will be loaded from by default for +commands such as +.Nm Cm load-key +and +.Nm Cm mount Fl 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 Cm set +or +.Nm 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 +.Po see +.Nm Cm load-key +.Pc . +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 exec Ns = Ns Sy on Ns | Ns Sy off Controls whether processes can be executed from within this file system. The default value is @@ -1179,6 +1292,24 @@ See for more information on .Sy nbmand mounts. +.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 350000 and the minimum is 100000. +This property may be changed with +.Nm Cm change-key . .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 . @@ -1568,7 +1699,7 @@ Controls the behavior of synchronous requests .Pq e.g. fsync, O_DSYNC . .Sy standard is the -.Tn POSIX +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 @@ -1646,7 +1777,7 @@ when the pool is low on space. For a sparse volume, changes to .Sy volsize are not reflected in the -.Sy refreservation. +.Sy refreservation . A volume that is not sparse is said to be .Qq thick provisioned . A sparse volume can become thick provisioned by setting @@ -1698,7 +1829,7 @@ property is Traditionally, .Ux and -.Tn POSIX +POSIX file systems have case-sensitive file names. .Pp The @@ -1857,6 +1988,83 @@ installed or upgraded, use the and .Xr dumpadm 1M commands. +.Ss "Encryption" +Enabling the +.Sy encryption +feature allows for the creation of encrypted filesystems and volumes. +ZFS will encrypt all user data including file and zvol data, file attributes, +ACLs, permission bits, directory listings, FUID mappings, and userused/groupused +data. +ZFS +will not encrypt metadata related to the pool structure, including dataset +names, dataset hierarchy, file size, file holes, and dedup tables. +Key rotation is managed internally by the ZFS kernel module and changing the +user's key does not require re-encrypting the entire dataset. +Datasets can be scrubbed, resilvered, renamed, and deleted without the +encryption keys being loaded +.Po see the +.Nm Cm load-key +subcommand for more info on key loading +.Pc . +.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 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 Sy 3 +since the implementation stores some encryption metadata where the third copy +would normally be. +Since compression is applied before encryption datasets may be vulnerable to a +CRIME-like attack if applications accessing the data allow for it. +Deduplication with encryption will leak information about which blocks are +equivalent in a dataset and will incur an extra CPU cost per block written. .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their original form. @@ -2621,7 +2829,7 @@ Displays all ZFS file systems currently mounted. .It Xo .Nm .Cm mount -.Op Fl Ov +.Op Fl Olv .Op Fl o Ar options .Fl a | Ar filesystem .Xc @@ -2635,6 +2843,16 @@ for more information. .It Fl a Mount all available ZFS file systems. Invoked automatically as part of the boot process. +.It Fl l +Load keys for encrypted filesystems as they are being mounted. +This is equivalent to executing +.Nm 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 Ar filesystem Mount the specified filesystem. .It Fl o Ar options @@ -2720,7 +2938,7 @@ feature. .It Xo .Nm .Cm send -.Op Fl DLPRcenpv +.Op Fl DLPRcenpvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Xc @@ -2733,7 +2951,7 @@ The output can be redirected to a file or to a different system .Pc . By default, a full stream is generated. .Bl -tag -width "-D" -.It Fl D, -dedup +.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. @@ -2756,7 +2974,7 @@ is similar to The incremental source may be specified as with the .Fl i option. -.It Fl L, -large-block +.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 @@ -2771,9 +2989,9 @@ See for details on ZFS feature flags and the .Sy large_blocks feature. -.It Fl P, -parsable +.It Fl P , -parsable Print machine-parsable verbose information about the stream package generated. -.It Fl R, -replicate +.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 @@ -2792,7 +3010,12 @@ 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. -.It Fl e, -embed +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 @@ -2808,12 +3031,16 @@ 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 c, -compressed +.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 @@ -2854,7 +3081,7 @@ be fully specified not just .Em @origin .Pc . -.It Fl n, -dryrun +.It Fl n , -dryrun Do a dry-run .Pq Qq No-op send. @@ -2868,13 +3095,35 @@ 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 +.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. -.It Fl v, -verbose +Sends of encrypted datasets must use +.Fl w +when using this flag. +.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 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 @@ -2884,7 +3133,7 @@ You will be able to receive your streams on future versions of ZFS . .It Xo .Nm .Cm send -.Op Fl Lce +.Op Fl Lcew .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc @@ -2896,7 +3145,7 @@ 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 +.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 @@ -2911,7 +3160,7 @@ See for details on ZFS feature flags and the .Sy large_blocks feature. -.It Fl c, -compressed +.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 @@ -2930,7 +3179,7 @@ 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 e, -embed +.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 @@ -2946,6 +3195,10 @@ 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 @@ -2966,6 +3219,25 @@ character and following 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 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. .El .It Xo .Nm @@ -3005,7 +3277,7 @@ Streams are created using the subcommand, which by default creates a full stream. .Nm zfs Cm recv can be used as an alias for -.Nm zfs Cm receive. +.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 @@ -3025,6 +3297,55 @@ destroyed by using the .Nm zfs Cm destroy Fl d command. .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 +ds 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 @@ -3236,6 +3557,10 @@ 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 @@ -3541,6 +3866,105 @@ See .Xr zfs-program 1M for more information. .El +.It Xo +.Nm Cm load-key +.Op Fl nr +.Op Fl L Ar keylocation +.Fl a Ns | Ns filesystem +.Xc +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 . +.Bl -tag -width Ds +.It Fl a +Loads the keys for all encryption roots in all imported pools. +.It Fl n +Do a dry-run +.Cm 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 r +Recursively loads the keys for the specified filesystem and all descendent +encryption roots. +.El +.It Xo +.Nm +.Cm unload-key +.Op Fl r +.Fl a Ns | Ns Ar filesystem +.Xc +Unloads a key from ZFS, removing the ability to access the dataset and all of +its children that inherit the +.Sy encryption +property. +This requires that the dataset is not currently open or mounted. +Once the key is unloaded the +.Sy keystatus +property will be set to +.Sy unavailable . +.Bl -tag -width Ds +.It Fl a +Unloads the keys for all encryption roots in all imported pools. +.It Fl r +Recursively unloads the keys for the specified filesystem and all descendent +encryption roots. +.El +.It Xo +.Nm +.Cm change-key +.Op Fl il +.Op Fl o Sy keylocation Ns = Ns Ar value +.Op Fl o Sy keyformat Ns = Ns Ar value +.Op Fl o Sy pbkdf2iters Ns = Ns Ar value +.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 , 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 Ds +.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. +.It Fl l +Ensures the key is loaded before attempting to change the key. +This is effectively equivalent to +.Qq Nm Cm load-key Ar filesystem ; Nm Cm change-key Ar filesystem . +.It Fl o Sy property Ns = Ns Ar value +Allows the user to set encryption key properties +.Pq +.Sy keyformat , 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. +.El .El .Sh EXIT STATUS The |