zfs [-?]
zfs help subcommand | help | property property-name | permission
zfs help -l properties
zfs create -o encryption=on [-o keysource=raw | hex |
passphrase,prompt | file://|pkcs11:|https://] ... dataset
zfs clone [-p] [-K] [-o property=value] ... snapshot filesystem|volume
zfs get [-r|-d depth][-Hp][-o all | field[,...]] [-s source[,...]]
all | property[,...] filesystem|volume|snapshot ...
zfs key -l | {-a | [-r] filesystem|volume}
zfs key -u [-f] {-a | [-r] filesystem|volume}
zfs key -c [-o keysource=value] {-a | [-r] filesystem|volume}
zfs key -K {-a | [-r] filesystem|volume}
zfs mount
zfs mount [-vO] [-o options] -a | filesystem
zfs unmount [-f] -a | filesystem|mountpoint
The zfs create -o encryption command encrypts a newly created ZFS dataset within a ZFS storage pool, as described in zpool(1M).
Encryption is the process in which data is encoded for privacy and a key is needed by the data owner to access the encoded data. You can set an encryption policy when a ZFS dataset is created, but the policy cannot be changed. See the encryption and keysource property descriptions in the “Native Properties” section for details.
Dataset encryption is inherited permanently and cannot be removed during dataset cloning. When receiving a replicated dataset stream, the destination dataset must have encryption enabled if encryption is desired. Otherwise, the data is stored as clear text. A fully replicated stream of an encrypted dataset results in an encrypted dataset but under a newly generated key. The stream itself is not encrypted.
The following native properties related to ZFS encryption consist of read-only statistics about the dataset. These properties cannot be set nor inherited. Native properties apply to all dataset types unless otherwise noted. For a full description and list of ZFS native properties, see zfs(1M).
The date of the last wrapping key change from a zfs key –c operation on a given dataset. If no key change operation has been performed, keychangedate is the same as the creation date.
Identifies the encryption key status for the dataset. The availability of a dataset's key is indicated by showing the status of available or unavailable. For datasets that do not have encryption enabled, none is displayed.
For file systems, indicates whether the file system is currently mounted. This property can be either yes or no.
The date of the last data encryption key change from a zfs key –K or zfs clone –K operation on this dataset. If no rekey operation has been performed, rekeydate is the same as creation date.
The following 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 zfs create or zpool 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.
Defines the encryption algorithm and key length that is used for the encrypted dataset. The on value is equal to aes-128-ccm. The default value is off. When encryption is set to a value other than off, the checksum property is set to sha256+mac and becomes readonly.
A regular user can create an encrypted file and manage key operations if the user is delegated the appropriate permissions, such as create, mount, keysource, checksum, and encryption.
The following properties must be specified at creation time and can modified by using special commands:
Defines the format and location of the key that wraps the dataset keys. The key must be present when the dataset is created, mounted, or loaded by using the zfs key –l command.
The keysource property accepts two values: format determines how the key is presented; locator identifies where the key is coming from.
format accepts three values:
raw: the raw key bytes
hex: a hexadecimal key string
passphrase: a character string that generates a key
locator accepts two values:
prompt: You are prompted for a key or a passphrase when the dataset is created or mounted
file:///filename: the key or a passphrase file location in a file system
pkcs11: A URI describing the location of a key or a passphrase in a PKCS#11 token
https://location: The key or a passphrase file location on a secure server. Transporting key information in the clear using this method is not recommended. A GET on the URL returns just the key value or the passphrase, according to what was requested in the format part of the keysource.
When using an https:// locator for the keysource, the certificate that the server presents must be one that is trusted by libcurl and OpenSSL. Add your own trust anchor or self signed certificate to the certificate store in /etc/openssl/certs. Place the PEM format certificate into the /etc/certs/CA directory and run the svcadm refresh ca-certificates command.
See “Examples” for examples of creating a key by using the https:// locator.
To change the wrapping key value or the key, you must run the zfs key –c command. If only the key location needs to changed, for example, a filename change, then use the zfs set command with the keysource property. Note that no checking is performed by ZFS when only the key location is changed with the zfs set command, such as whether the new location has a valid wrapping key.
If keysource is not specified and not inherited, then the default keysource is set to passphrase,prompt for a dataset that has encryption on and is set to none for a dataset that has encryption off.
All subcommands that modify state are logged persistently to the pool in their original form.
Displays a help message.
Displays zfs command usage information. You can display help for a specific command, property, or delegated permission. If you display help for a specific command or property, the command syntax or property value is displayed. Using zfs help without any arguments displays a complete list of zfs commands.
Displays zfs property information, including whether the property value is editable and inheritable, and their possible values.
Creates a new ZFS file system with encryption enabled, which uses aes-128-ccm See the encryption property description for a list of supported encryption algorithms.
Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent. Any property specified on the command line using the –o option is ignored. If the target filesystem already exists, the operation completes successfully.
Sets the encryption property to value. Multiple –o options can be specified. An error results if the same property is specified in multiple –o options.
Creates a clone of the given snapshot. See the “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.
Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according to the mountpoint property inherited from their parent. If the target filesystem or volume already exists, the operation completes successfully.
Sets the specified property; see zfs create for details.
Creates a new data encryption key in the keychain for this dataset. Data written in the clone uses the new data encryption key, which is distinct from its original snapshot.
Sets the keysource property to the given value for each dataset. You can only change the keysource location. If you want to change the wrapping key value, use the zfs key –c command.
Recursively apply the effective value of the setting throughout the subtree of child datasets. The effective value may be set or inherited, depending on the property.
Displays properties for the given datasets.
Recursively display properties for the given datasets.
Recursively display any descendent datasets, limiting the recursion to depth. A depth of 1 will display only the dataset and its direct children.
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.
Loads the encryption key for a dataset and any datasets that inherit the key. The key that is provided with this command is not the actual key that is used to encrypt the dataset. It is a wrapping key for the set of data encryption keys for the dataset.
Loads the wrapping key to unlock the encrypted dataset and datasets that inherit the key. This command loads the key based on what is defined by the dataset's keysource property.
During a pool import, a key load operation is performed when a dataset is mounted. During boot, if the wrapping key is available and the keysource is not set to prompt, the key load operation is performed.
Apply to all datasets in all pools on the system.
Apply the operation recursively to all datasets below the named file system or volume.
Unloads the encryption key for a dataset and any datasets that inherit the key.
Unmounts the dataset and then attempts to unload the wrapping key for an encrypted dataset and datasets that inherit the key. If successful, the dataset is not accessible and is unmounted.
Attempts to force unmount the dataset before attempting to unload the key. If not specified, a normal unmount is attempted.
Apply to all datasets in all pools on the system.
Apply the operation recursively to all datasets below the named file system or volume.
Changes the wrapping key. If the new key has a different format or locator, the keysource property must be included as part of the command. Only the keysource property can be changed as part of the zfs key –c command.
Changes the wrapping key for the key of an encrypted dataset and the datasets that inherit it. The existing key must already have been loaded before the key change operation can occur. ZFS does not prompt you for the existing passphrase.
Property to be changed as part of the key change operation. The keysource property is the only option that can be changed as part of a key change operation.
You must have permission to change the keysource properties.
Apply to all datasets in all pools on the system.
Apply the operation recursively to all datasets below the named file system or volume.
Creates a new data encryption key. The new data encryption key is wrapped by the same wrapping key as any existing data encryption keys for this dataset.
Creates a new data encryption key for this dataset. Data written after this operation will use the new data encryption key.
Apply to all datasets in all pools on the system.
Apply the operation recursively to all datasets below the named file system or volume.
Mounts ZFS file systems. Invoked automatically as part of the boot process. For a full description of zfs mount syntax, see zfs(1M).
Mount the specified filesystem.
A zfs mount operation of an encrypted dataset might prompt you for a key, depending on the keysource property value. This might occur, for example, if the keysource locator is set to prompt.
Unmounts currently mounted ZFS file systems. Invoked automatically as part of the shutdown process. For a full description of zfs unmount syntax, see zfs(1M).
Unmount the specified filesystem. The command can also be given a path to a ZFS file system mount point on the system.
For an encrypted dataset, the key is not unloaded when the file system is unmounted. To unload the key, see zfs key.
The following example shows how to create an encrypted dataset by using a passphrase prompt, which is the default value of the keysource property. This example assumes that the tank/home dataset is not encrypted.
# zfs create -o encryption=on tank/home/bob Enter passphrase for 'tank/home/bob/': ********** Enter again: **********
In the following example, the pktool(1) command is used to generate a raw key to a file. Next, an encrypted dataset (tank/home/anne) is created with the aes-256-ccm algorithm and the raw key file that was generated by pktool.
# pktool genkey keystore=file outkey=/media/stick/mykey \ keytype=aes keylen=256 # zfs create -o encryption=aes-256-ccm \ -o keysource=raw,file:///rmdisk/stick/mykey tank/home/anne
This example shows how to create an encrypted ZFS file system that retrieves the passphrase that is stored at an https location.
# zfs create -o encryption=on \ -o keysource=passphrase,https://keys.example.com/keys/42 tank/home/fs1
This example shows how to generate a raw key in a PKCS#11 token. Then, an encrypted dataset is created with the raw PKCS#11 key that was generated from pktool.
# pktool genkey keystore=pkcs11 keytype=aes keylen=128 label=fs2 Enter PIN for Sun Software PKCS#11 softtoken: xxxxx # zfs create -o encryption=on -o keysource=raw,pkcs11:object=fs2 \ tank/home/fs2 Enter PKCS#11 token PIN for 'tank/home/fs2': xxxxx
This example shows how to generate a raw key in a KMS token. Then, an encrypted dataset is created with the raw KMS key that was generated from pktool.
# pktool genkey keystore=pkcs11 keytype=aes keylen=256 token=KMS \ label=fs3 Enter PIN for KMS: xxxxx # zfs create -o encryption=aes-256-ccm \ -o keysource="raw,pkcs11:token=KMS;object=fs3" tank/home/fs3 Enter 'KMS' PKCS#11 token PIN for 'tank/home/fs3': xxxxxExample 2 Creating an Encrypted Dataset with a Different Encryption Algorithm
In this example, any tank/home datasets inherit the keysource properties, but the tank/home/bob dataset is created by using a different encryption algorithm.
# zpool create tank .... # zfs create -o encryption=on tank/home # zfs get keystatus tank/home NAME PROPERTY VALUE SOURCE tank/home keystatus available - # zfs create -o encryption=aes-256-ccm tank/home/bobExample 3 Inheriting Encryption and Keysource Properties
In this example, all of the tank/home datasets inherit the encryption and keysource properties.
# zpool create -O encryption=on -o keysource=raw,file:///... tank ... # zfs create tank/homeExample 4 Changing an Encrypted Dataset's Wrapping Key and Keysource
This example shows how to change a dataset's wrapping key to a new key defined by the dataset's keysource property.
# zfs create -o encryption=aes-256-ccm -o keysource=raw,file:///etc/keyfile \ tank/home/rory # zfs get keysource tank/home/rory NAME PROPERTY VALUE SOURCE tank/home/rory keysource raw,file:///etc/keyfile local # zfs key -c -o keysource=passphrase,prompt tank/home/rory Enter passphrase for 'tank/home/rory/': ********** Enter again: ********** # zfs get keychangedate tank/home/rory NAME PROPERTY VALUE SOURCE tank/home/rory keychangedate Thu Jun 28 14:32 2012 local
The following example shows how to change the http location of dataset's wrapping key.
# zfs get keysource tank/home/bob NAME PROPERTY VALUE SOURCE tank/home/bob keysource passphrase,prompt local # zfs set keysource=passphrase,https://internal.example.com/keys/bob/zfs \ tank/home/bob
You must have the delegated key and keychange permissions to change the keysource property.
Example 5 Rekeying the Dataset's Encryption KeyThis example shows how to change a dataset's encryption key, which is neither visible nor managed by you or an administrator. The dataset's encryption key is wrapped (encrypted) by the key specified in the keysource property.
# zfs key -K tank/project42 # zfs get rekeydate,creation tank/project42
You must have the delegated keychange permission to perform a key change operation.
Example 6 Customizing the Encrypted Dataset's Wrapping KeyThe following examples illustrate that the wrapping key size does not have to match the key size specified for the encryption property.
# zfs create -o encryption=aes-128-gcm -o keysource=raw,file:///k256 \ /tank/home/amy
In the above example, the encryption key size is 128 and the wrapping key size is 256.
# zfs create -o encryption=aes-256-gcm -o keysource=raw,file:///k192 \ /tank/home/rose
In the above example, the encryption key size is 256 and the wrapping key size is 192.
The following exit values are returned:
Successful completion.
An error occurred.
Invalid command line options were specified.
See attributes(5) for descriptions of the following attributes:
|
chmod(1), chown(1), pktool(1), ssh(1), mount(1M), zfs(1M), zpool(1M), chmod(2), chown(2), stat(2), write(2), attributes(5)
For information about using other ZFS features, see zfs_allow(1M), zfs_share(1M), zfs(1M), and the Managing ZFS File Systems in Oracle Solaris 11.2 .