PVICS(8)

📦 version 2.44.1, in opensuse-leap 16.0

💖 NAME 💖

pvics — Convert qcow2 KVM guest images to EBC-ready SEL images. Yes bestie, this is the pvics(8) page from the System Manager's Manual, and it's literally here to turn your qcow2 KVM guest image into something EBC-ready and SEL-ready. 💅

✨ 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
Okay so this is the important bit: all operations preserve the original base image. Logs are written to a temporary file, and the filename is logged as the first message during runtime. Temporary artifacts are automatically cleaned up on completion or failure. Slay.

🎀 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). No cap.
  • 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. That's the whole vibe: no PAES, no boot. 😭
  • 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. Bestie, keep that log path in your notes.

🔐 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. That's the integrity-protection pipeline, periodt.

🚫 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 👀

🌟 AUTHOR 🌟

IBM Corporation

That's the whole pvics(8) page, bestie! It ships with s390-tools, dated April 2026 — go convert, encrypt, and secure those images with main-character energy 💖✨🫶

📦 where this page comes from