PVICS(8)

NAME
pvics - Convert qcow2 KVM guest images to EBC-ready SEL images

SYNOPSIS
pvics ACTION [-h|--help] [-c|--config CONFIG_FILE] [-i|--image BASE_IMAGE]

DESCRIPTION
Use the pvics tool to convert existing QEMU Copy/-On/-Write version 2(qcow2) KVM guest images into images that are ready for Early Boot Customization (EBC) and Secure Execution for Linux (SEL). The tool encrypts the root file system and prepares all resources required for EBC. The tool operates on a copy of the original base image and performs operations in three main phases:

•   Retrieving information about a given base image

•   Converting a base image according to a configuration

•   Encrypting the root file system and preparing EBC resources All operations preserve the original base image. Logs are written to a temporary file, with the filename logged as the first message during runtime. Temporary artifacts are automatically cleaned up on completion or failure.

Base Image Prerequisites
The following prerequisites have to be fulfilled by the base image:

•   label of boot partition set to boot

•   label of root partition set to root

•   guest is to be backed by a qcow2 image

•   an initramfs containing the dracut module 95sel-ebc which is part of s390-tools

•   a boot loader specifying that initramfs and a kernel parameter line on which root is specified by label

•   any line starting with default= should be removed from /etc/zipl.conf

ACTIONS

list
    Retrieve information about a given base image. This action displays available boot loader entries from /boot/loader/entries, along with kernel and initramfs hashes and the kernel command line. This is useful for:

    •   Determining valid values for the boot-loader-entry configuration option

    •   Comparing components between base and converted images

    •   Verifying image contents before conversion

convert
    Convert a base image according to the configuration file. This action:

    •   Fetches kernel, initramfs, and kernel command line from the specified boot loader entry

    •   Builds a SEL image using pvimg(1)

    •   Updates /boot/bootmap to boot into the SEL image

    The resulting image will be a SEL guest image. It requires encryption to be fully EBC-ready (unless no-ebc is enabled in the configuration).

encrypt
    Encrypt the root file system and prepare EBC resources. This action:

    •   Generates secure defaults (CCK, extension secret, LUKS keys) if not provided

    •   Encrypts the root file system using LUKS with PAES

    •   Populates /boot/sics/ with add/-secret requests

    •   Creates toc.pol and toc.asr for integrity protection

    This action requires EBC. The guest can boot only by using PAES to open the root file system.

full
    Perform both convert and encrypt actions in sequence. This is equivalent to running convert followed by encrypt, but in a single invocation.

ARGUMENTS

ACTION
    The action to perform: list, convert, encrypt, or full.

OPTIONS

-h, --help
    Display help message and exit.

-c, --config CONFIG_FILE
    Path to the YAML configuration file. See pvics.yaml(5) for the configuration file format and options.
    Required for convert, encrypt, and full actions.
    Not required for the list action.

-i, --image BASE_IMAGE
    Path to the base qcow2 image file to process. Required for all actions.

CONVERSION PROCESS
The conversion process consists of three phases:

  Component Fetching
The tool retrieves the kernel, initramfs, and kernel command line from the boot loader entry specified in the configuration file. The components are validated to ensure they meet SEL EBC requirements. The tool prepends rd.sel-ebc to the kernel command line to trigger the SEL EBC dracut module (unless no-ebc is enabled) and appends any user-provided kernel parameters from the configuration.

  SEL Image Build
The SEL image is built using pvimg(1) with the fetched components. Additional options may be specified in the configuration file via .convert.pvimg-create-options.

  Bootmap Update
The tool updates the bootmap to boot into the new SEL image:

•   Existing boot loader entries in /boot/loader/entries/*.conf are renamed to *.conf.old

•   A new entry sel-ebc.conf is created that points to /boot/sel-ebc.img

•   zipl(8) is run to update the bootmap. The guest is temporarily started to update the bootmap using libvirt on z/Architecture or qemu on non-z/Architecture architectures. Failures are logged to /var/log/sel-ebc-zipl.log.

ENCRYPTION PROCESS
The encryption process consists of three phases:

  Secure Default Generation
If not provided in the configuration, the following are generated from /dev/random:

•   Customer communication key (CCK)

•   Root file system LUKS encryption key

•   Extension secret for add/-secret requests

•   LUKS passphrase

  Root File System Encryption
The root file system is encrypted using the following steps:

1.  Resize the qcow2 image to accommodate the LUKS header

2.  Resize the root partition (but not the file system) to fit the LUKS header

3.  Encrypt the root file system using LUKS

4.  Reformat the LUKS header from AES to PAES (Protected AES)

  AES to PAES Conversion
The LUKS header is converted from standard AES encryption to protected AES (PAES). With PAES, encryption secrets are stored in the ultravisor secret store rather than directly in the LUKS header.

  SICS Population
The SEL Image Customization Source directory (/boot/sics) is populated with the following secrets as add/-secret requests:

•   Customer communication key (CCK)

•   LUKS encryption key

•   LUKS passphrase

•   Any additional add/-secret requests specified in the configuration All automatically built add/-secret requests are added to toc.pol, which verifies the completeness of /boot/sics. User-supplied add/-secret requests from the configuration are also added. Finally, toc.asr is built as a meta secret that links to toc.pol for integrity protection.

BUILDING SEL IMAGES WITHOUT EBC
While the primary purpose of pvics is to create EBC-ready SEL images with encrypted root file systems, it can also build SEL images without EBC functionality using the no-ebc configuration option. When no-ebc: true is set in the configuration:

•   The convert action builds a SEL image without EBC-specific flags

•   The encrypt action is completely skipped

•   The full action becomes equivalent to convert only

•   The rd.sel-ebc kernel parameter is not added

•   --enable-cck-update and --disable-image-encryption flags are not passed to pvimg This mode is useful for:

•   Single-party image creation where the same entity performs conversion, customization, and encryption

•   Testing SEL guest functionality without EBC complexity

•   Development and debugging scenarios

•   Simplified SEL image generation workflows

OUTPUT FILES
All output files are written to the directory specified by the out configuration option:

<out>/image.qcow2
    The converted SEL image (after convert or full action)

<out>/cck.key
    Customer communication key (generated if not provided)

<out>/extension.secret
    Extension secret for add/-secret requests (generated if not provided)

<out>/rfs.key
    Root file system LUKS encryption key (generated if not provided)

<out>/passphrase
    LUKS passphrase (generated if not provided)

<out>/*.asr
    Generated add-secret request files

TEMPORARY FILES

/tmp/tmp.*
    Log file (filename logged at startup)

EXIT STATUS

0   Success

1   General error (invalid arguments, missing files, operation failure)

EXAMPLES

  List Boot Loader Entries
pvics list --image /path/to/base-image.qcow2

  Convert Image Only
pvics convert --config /path/to/config.yaml --image /path/to/base-image.qcow2

  Encrypt Image Only
pvics encrypt --config /path/to/config.yaml --image /path/to/converted-image.qcow2

  Full Conversion and Encryption
pvics full --config /path/to/config.yaml --image /path/to/base-image.qcow2

  Build SEL Image Without EBC
# config.yaml contains: no-ebc: true
pvics convert --config /path/to/config.yaml --image /path/to/base-image.qcow2

FILES

/boot/loader/entries/*.conf
    Boot loader entry files in the base image

/boot/sel-ebc.img
    The resulting SEL image file in the guest

/boot/sics/
    SEL image-customization source directory that contains EBC resources

/boot/sics/toc.pol
    Table-of-contents policy file that lists all add/-secret requests

/boot/sics/toc.asr
    Meta secret for integrity protection of toc.pol

/var/log/sel-ebc-zipl.log
    Log file for zipl bootmap update operations

NOTES

•   All operations are performed on a copy of the original base image.

•   The tool requires root privileges for file-system operations.

•   The LUKS device is named cryptroot.

•   The temporary working directory is created at /opt/sel-<UUID>.

•   The no-verify option should not be used in production environments.

•   Generated secrets are written to the output directory and should be secured appropriately.

SEE ALSO
pvics.yaml(5), pvsecret(1), pvimg(1), pvebc(8), zipl(8), cryptsetup(8), lsinitrd(1)

Linux on IBM Z and IBM LinuxONE: Secure Execution for Linux documentation

AUTHOR
IBM Corporation