zfsadm encrypt

Purpose

zfsadm encrypt encrypts a zFS aggregate.

Options

-aggregate name

Specifies the name of the aggregate to be encrypted. The aggregate name is not case-sensitive. It is always converted to uppercase.

-cancel

Cancels an in-progress encrypt operation for the specified aggregate.

-help

Prints the online help for this command. All other valid options that are specified with this option are ignored.

-keylabel label

Specifies an identifier that is used to locate keys in the cryptographic key data set (CKDS) or the public key data set (PKDS). The key label is typically managed by the ICSF administrator. See z/OS Cryptographic Services ICSF Application Programmer's Guide for more information.

The -keylabel option is only needed when a zFS aggregate is encrypted for the first time if it was not specified when the VSAM linear data set was created. The -keylabel option is not needed in the following situations:

• If encryption is resumed from a partially encrypted zFS aggregate, or
• If the key label was already defined by using either the zfsadm define command with the -keylabel option or the IDCAMS DEFINE CLUSTER command with the KEYLABEL keyword, as described in DEFINE CLUSTER z/OS DFSMS Access Method Services Commands.

-level

Prints the level of the command. This option is useful when you are diagnosing a problem. Except for -help, all other valid options that are specified with -level are ignored.

-trace file_name

Specifies the name of the file that will have the trace records written into it. The trace file can be a z/OS UNIX file, an existing MVS sequential data set, or a member of either an existing partitioned data set (PDS) or partitioned data set extended (PDSE). Use this option only at the direction of IBM Support.

For information about preallocation instructions for debugging, see Step 5 (Optional) Preallocate data sets for debugging in zFS installation and configuration steps.

Because MVS data set names must be fully qualified, z/OS UNIX has special rules for specifying MVS data set names in the shell environment. For more information, see Specifying MVS data set names in the shell environment in z/OS UNIX System Services Command Reference.

Usage notes

1. The zfsadm encrypt command is a long-running administrative command that uses DFSMS access method encryption to encrypt an existing zFS aggregate. Only symbolic links, ACLs, regular files, and fragmented v4 directories can be encrypted.
2. The command must be issued from a z/OS V2R3 or later system, and the zFS file system must be zFS owned on a z/OS V2R3 or later system. The aggregate must be at least aggregate version 1.5 and mounted read/write. Do not use this command before you have migrated all your systems to z/OS V2R3 or later. If there are systems that are active prior to z/OS V2R3 in the shared file system environment, encryption will not take place.
3. To process the encryption request, the long-running command thread pool must have an available foreground thread. See the IOEFSPRM configuration option long_cmd_threads for information about controlling the size of the long-running foreground and background thread pools. The option is described in IOEFSPRM.
4. An encryption operation can be interrupted by using the -cancel option or during a shutdown. It can also be interrupted when the shell command unmount or TSO/E command UNMOUNT is issued with the force option. If the encryption operation is interrupted, the zFS aggregate can be left with both encrypted and unencrypted files. This partial state is allowed. Another zfsadm encrypt command can be issued to resume the encryption operation for the rest of files after the interruption.
5. You cannot encrypt an aggregate that is in a partially compressed or partially decompressed state. In other words, if compression or decompression was interrupted for an aggregate, you cannot encrypt it.
6. After the aggregate is fully encrypted, any newly created files will be encrypted. Applications can still access the aggregate while it is being encrypted. The backup change activity flag is set if any data is encrypted.
7. Use either the zfsadm fsinfo or MODIFY FSINFO command to display whether an aggregate is encrypted or being encrypted. Progress of the encrypt operation can be seen in the owner status display.
8. The zfsadm fileinfo command can be used to indicate whether a particular file is encrypted.
9. If you encrypt an aggregate that contains files or directories in fragmented format, the files or directories will be converted to blocked format. If there are not enough free 8 K blocks to do the conversion, the encryption can run out of space. In this case, a dynamic grow will be attempted.
10. The encryption conversion process will clear all unused areas of the file system. This action is called scrubbing.
11. Extended format VSAM data sets record the encryption status for each control interval in the dataset, providing improved integrity checking. Therefore, it is recommended that new zFS data sets be defined with the extended format option.
12. Aggregates with active file backups cannot be encrypted.

Privilege required

The issuer must be logged in as a root user (UID=0) or have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.

Related information