svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
zfs_encrypt(8)
System Administration Commands zfs_encrypt(8)
NAME
zfs_encrypt - encrypting ZFS file systems
SYNOPSIS
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 create -o encryption=on [-o keysource=hex,cluster:keyname] ...
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 [-t type] [-M] [-S] {-a | [-r] filesystem|volume}
zfs key -u [-t type] [-f] {-a | [-r] filesystem|volume}
zfs key -c [-t type] [-o keysource=value] {-a | [-r] filesystem|volume}
zfs key -K [-t type] {-a | [-r] filesystem|volume}
zfs mount
zfs mount [-vO] [-o options] -a | filesystem
zfs unmount [-f] -a | filesystem|mountpoint
DESCRIPTION
The zfs create -o encryption command encrypts a newly created ZFS
dataset within a ZFS storage pool, as described in zpool(8).
Encryption
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 can‐
not 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 dur‐
ing 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 repli‐
cated stream of an encrypted dataset results in an encrypted dataset
but under a newly generated key. The stream itself is not encrypted.
ZFS Send/Recv Considerations
A send stream created from an encrypted dataset in a source zpool that
is at version 46 or above (Compact File Metadata for Encryption) can
only be received into a destination zpool that is also at version 46 or
above.
A send stream created from an unencrypted dataset can have encryption
enabled as part of the receive (either by overriding properties or by
inheritance from the destination) only when received into a zpool at
zpool version 46 or above: Compact File Metadata for Encryption.
Native ZFS Encryption Properties
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 oth‐
erwise noted. For a full description and list of ZFS native properties,
see zfs(8).
keychangedate
The date of the last wrapping key change from a zfs key -c opera‐
tion on a given dataset. If no key change operation has been per‐
formed, keychangedate has no value. Some releases incorrectly had
this as same as the creation date.
keystatus
Identifies the encryption key status for the dataset. The avail‐
ability of a key of a dataset is indicated by showing the status of
available or unavailable. For datasets that do not have encryption
enabled, none is displayed.
mounted
For file systems, indicates whether the file system is currently
mounted. This property can be either yes or no.
rekeydate
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 has no value. Some releases incor‐
rectly had this as same as the 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 com‐
mands, 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.
encryption=off | on | aes-128-ccm | aes-192-ccm | aes-256-ccm |
aes-128-gcm | aes-192-gcm | aes-256-gcm
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 read‐
only.
A regular user can create an encrypted file and manage key opera‐
tions if the user is delegated the appropriate permissions, such as
create, mount, keysource, checksum, and encryption.
Note -
Deduplication is available only with aes-128-ccm, aes-192-ccm,
and aes-256-ccm modes. The dedup property can be set on a dataset
when encryption uses either aes-128-gcm, aes-192-gcm, or
aes-256-gcm modes, though it will not produce dedupable blocks.
The reason the dedup property can be set on datasets with a gcm
mode is that the dedup property can be inherited if a filesystem
lower in the hierarchy has a ccm mode.
All settings for compression are valid when encryption is
enabled.
The following properties must be specified at creation time and can
modified by using special commands:
keysource=raw | hex | passphrase,prompt | file://|pkcs11:|https://
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:
o raw: the raw key bytes
o hex: a hexadecimal key string
o passphrase: a character string that generates a key
locator accepts two values:
o prompt: You are prompted for a key or a passphrase when
the dataset is created or mounted
o file:///filename: the key or a passphrase file location
in a file system
o pkcs11: A URI describing the location of a key or a
passphrase in a PKCS#11 token
o 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 cer‐
tificate 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 be 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.
For a keysource location using https:// the negotiate header will
be used to allow the client to authenticate to the server using
GSSAPI or Kerberos when client creds can be acquired. To use this
either a host keytab is required or kinit must have been run by the
user running zfs(8) to acquire an appropriate TGT. The negotiation
and acquisition are automatic and have no configuration options.
keysource=hex,cluster:keyname
Can only be used with Solaris Cluster when using ZFS based
Encrypted Cluster file systems. The key and associated keyname is
stored in Solaris Cluster and the keyname uniquely identifies the
key.
SUBCOMMANDS
All subcommands that modify state are logged persistently to the pool
in their original form.
zfs ?
Displays a help message.
zfs help command | help | property property-name | permission
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.
zfs help -l properties
Displays zfs property information, including whether the property
value is editable and inheritable, and their possible values.
zfs create [-p] [-o encryption=on] [-o keysource=raw | hex |
passphrase,prompt | file://|pkcs11:|https://] ... filesystem
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.
-p
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 com‐
pletes successfully.
-o encryption=value
Sets the encryption property to value. Multiple -o options can
be specified. An error results if the same property is speci‐
fied in multiple -o options.
zfs clone [-p] [-K] [-o property=value] ... snapshot filesystem|volume
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.
-p
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.
-o property=value
Sets the specified property; see zfs create for details.
-K
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.
zfs set keysource=value filesystem|volume| ...
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.
-r
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.
zfs get encryption | keysource | keystatus | rekeydate filesystem|vol‐
ume| ...
Displays properties for the given datasets.
-r
Recursively displays properties for the given datasets.
-d depth
Recursively displays any descendent datasets, limiting the
recursion to depth. A depth of 1 will display only the dataset
and its direct children.
-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.
zfs key -l [-t type] [-M] [-S] {-a | [-r] filesystem|volume}
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 wrap‐
ping key for the set of data encryption keys for the dataset.
-l
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 key of the dataset.keysource prop‐
erty.
During a pool import, a key load operation is performed when a
dataset is mounted. During boot, if the wrapping key is avail‐
able and the keysource is not set to prompt, the key load oper‐
ation is performed.
-a
Applies to all the datasets in all the pools on the system.
-r
Applies the operation recursively to all the datasets below the
named file system or volume.
-t type
Only applies to the datasets that match this type.
-M
Does not mount file systems after loading their keys.
-S
Does not share file systems after loading their keys.
zfs key -u [-t type] [-f] | {-a | [-r] filesystem|volume}
Unloads the encryption key for a dataset, and any datasets that
inherit the key.
-u
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.
-f
Attempts to force unmount the dataset before attempting to
unload the key. If not specified, a normal unmount is
attempted.
-a
Applies to all the datasets in all pools on the system.
-r
Applies the operation recursively to all the datasets below the
named file system or volume.
-t type
Only applies to the datasets that match this type.
zfs key -c [-t type] [-o keysource=value] | {-a | [-r] filesystem|vol‐
ume}
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.
-c
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.
-o property=value
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.
-a
Applies to all the datasets in all pools on the system.
-r
Applies the operation recursively to all the datasets below the
named file system or volume.
-t type
Only applies to the datasets that match this type.
zfs key -K [-t type] {-a | [-r] filesystem|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.
-K
Creates a new data encryption key for this dataset. Data writ‐
ten after this operation will use the new data encryption key.
-a
Applies to all the datasets in all pools on the system.
-r
Applies the operation recursively to all the datasets below the
named file system or volume.
-t type
Only applies to the datasets that match this type.
zfs mount
zfs mount [-vO] [-o options] -a | filesystem
Mounts ZFS file systems. Invoked automatically as part of the boot
process. For a full description of zfs mount syntax, see zfs(8).
filesystem
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.
zfs unmount [-f] -a | filesystem|mountpoint
Unmounts currently mounted ZFS file systems. Invoked automatically
as part of the shutdown process. For a full description of zfs
unmount syntax, see zfs(8).
filesystem|mountpoint
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.
EXAMPLES
Example 1 Creating an Encrypted Dataset
The following example shows how to create an encrypted dataset by using
a passphrase prompt, which is the default value of the keysource prop‐
erty. 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 cre‐
ated with the aes-256-ccm algorithm and the raw key file that was gen‐
erated 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 gen‐
erated 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': xxxxx
Example 2 Creating an Encrypted Dataset with a Different Encryption
Algorithm
In this example, any tank/home datasets inherit the keysource proper‐
ties, 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/bob
Example 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/home
Example 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 Key
This 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 Key
The 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.
Example 7 Using Pinfile to Create an Encrypted Dataset
The following command uses the -o option with the pinfile attribute
(see sshd(8)) to create an encrypted dataset.
# zfs create -o encryption=aes-256-ccm -o \
keysource="raw,pkcs11:token=KMS;object=Key1;pinfile=/var/user/root/AgentPin" \
rpool/export/home/jack/Test
Example 8 Loading Keys Only for Volumes
The following command uses the -t option to restrict the key load oper‐
ation to ZFS volumes only.
# zfs key -l -t volume -a
Example 9 Loading the Key for ZFS Filesystems Without Mounting Them
The following example uses the -t and -M options to restrict the key
load operation to ZFS filesystems only, and leaves them unmounted.
# zfs key -l -t filesystem -M -r tank/mystuff
Example 10 Loading the Key for ZFS Filesystems Without Sharing Them
The following example uses the -t and -S options to restrict the key
load operation to ZFS filesystems only, and leaves them mounted, but
not yet shared.
# zfs key -l -t filesystem -S -r tank/mystuff
Example 11 Enabling Encryption Manually During ZFS Receive
The following example turns on encryption for newly created dataset
tank/mystuff during ZFS receive of unencrypted dataset source/mystuff.
# zfs send source/mystuff@mysnap | \
zfs receive -o encryption=on -o keysource=raw,file:///... tank/mystuff
Example 12 Enabling Encryption by Inheritance During ZFS Receive
The following example sends unencrypted dataset source/mystuff and
receives it into encrypted destination tank. Encryption properties for
tank/mystuff will be inherited from tank.
# zpool create -O encryption=on -O keysource=raw,file:///... tank ...
# zfs send source/mystuff@mysnap | zfs receive tank/mystuff
EXIT STATUS
The following exit values are returned:
0 Successful completion.
1 An error occurred.
2 Invalid command line options were specified.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitysystem/file-system/zfs _ Interface Stabili‐
tyCommitted
SEE ALSO
chmod(1), chown(1), pktool(1), ssh(1), chmod(2), chown(2), stat(2),
write(2), attributes(7), mount(8), sshd(8), zfs(8), zpool(8)
For information about using other ZFS features, see zfs_allow(8),
zfs_share(8), zfs(8), and the Managing ZFS File Systems in Oracle
Solaris 11.4.
Oracle Solaris 11.4 17 Nov 2020 zfs_encrypt(8)