PVIMG-CREATE(1)

💖 PVIMG-CREATE(1) 💖

hiii bestie, welcome to the Pvimg Manual! This page is all about pvimg-create, the command that creates an IBM Secure Execution image. It's giving secure-boot glam, no cap. Let's get into it. ✨

---

🎀 NAME 🎀

pvimg-create — create an IBM Secure Execution image. Periodt.

---

🌸 SYNOPSIS 🌸

pvimg create [OPTIONS] --kernel <FILE> --output <FILE> --host-key-document <FILE> <--no-verify|--cert <FILE>>

---

💅 DESCRIPTION 💅

okay so, you use pvimg to generate a single bootable image file with encrypted and integrity-protected parts. The command requires a kernel image, a host-key document, certificates for the host-key document verification, and an output file name. Optionally, you can specify an initial RAM filesystem, and a file containing the kernel parameters. 🫶

If the command should be run offline, use the --offline option and specify the certificate revocation lists (CRLs) by using the --crl option. Should special circumstances require it, you can optionally specify your own keys for the encryption by using the experimental options. For all certificates, CRLs, and host-key documents, both the PEM and DER input formats are supported. 💖

In the resulting image file, a plain text boot loader, the encrypted components for kernel, initial RAM disk, kernel parameters, and the encrypted and integrity-protected header are concatenated. The header contains metadata necessary for running the guest in protected mode. ✨

Use this image file as a kernel image for zipl or for a direct kernel boot using QEMU.

---

🔥 OPTIONS 🔥

• -i, --kernel, --image <FILE> — use the content of FILE as a raw binary Linux kernel.
  • The Linux kernel must be a raw binary s390x Linux kernel. The ELF format is not supported. 😭
• -r, --ramdisk <FILE> — use the content of FILE as the Linux initial RAM disk.
• -p, --parmfile <FILE> — use the content of FILE as the Linux kernel command line.
  • The Linux kernel command line must be shorter than the maximum kernel command line size supported by the given Linux kernel.
• -o, --output <FILE> — write the generated Secure Execution boot image to FILE.
• -k, --host-key-document <FILE> — use FILE as a host-key document.
  • Can be specified multiple times and must be specified at least once.
• --no-verify — disable the host-key document verification.
  • Does not require the host-key documents to be valid. Do not use for a production request unless you verified the host-key document beforehand. 🚨
• -C, --cert <FILE> — use FILE as a certificate to verify the host-key or keys.
  • The certificates are used to establish a chain of trust for the verification of the host-key documents. Specify this option twice to specify the IBM Z signing key and the intermediate CA certificate (signed by the root CA).
• --crl <FILE> — use FILE as a certificate revocation list (CRL).
  • The list is used to check whether a certificate of the chain of trust is revoked. Specify this option multiple times to use multiple CRLs.
• --offline — make no attempt to download CRLs.
• --root-ca <ROOT_CA> — use FILE as the root-CA certificate for the verification.
  • If omitted, the system wide-root CAs installed on the system are used. Use this only if you trust the specified certificate.
• --no-component-check — disable all input component checks.
  • For example, for the Linux kernel, it tests if the given kernel looks like a raw binary s390x kernel.
• --overwrite — overwrite an existing Secure Execution boot image.
• --hdr-version <VERSION> — specify the Secure Execution header version to use. [default: '1']
  • Possible values:
    • 1: Version 1 - uses traditional cryptographic keys.
    • 2: Version 2 - uses hybrid (post-quantum) cryptographic keys.
• --cck, --comm-key <FILE> — use the content of FILE as the customer-communication key (CCK).
  • The file must contain exactly 32 bytes of data. In previous versions, this option was called --comm-key.
• --hdr-key <FILE> — use the content of FILE as the Secure Execution header protection key.
  • The file must contain exactly 32 bytes of data. If the option is not specified, the Secure Execution header protection key is a randomly generated key.
• --image-key <FILE> — use the content of FILE as the image encryption key.
  • The file must contain exactly 64 bytes of data.
• --enable-dump — enable Secure Execution guest dump support. This option requires the --cck or --enable-cck-update option.
• --disable-dump — disable Secure Execution guest dump support (default).
• --enable-cck-extension-secret — Add-secret requests must provide an extension secret that matches the CCK-derived extension secret. This option requires the --cck option.
• --disable-cck-extension-secret — Add-secret requests don't have to provide the CCK-derived extension secret (default).
• --enable-cck-update — enable CCK update support. Requires z17 or up. This option cannot be used in conjunction with the --enable-cck-extension-secret option.
• --disable-cck-update — disable CCK update support (default).
• --enable-pckmo — enable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption functions (default).
• --disable-pckmo — disable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption functions.
• --enable-pckmo-hmac — enable the support for the HMAC PCKMO key encryption function (default for header version 2).
• --disable-pckmo-hmac — disable the support for the HMAC PCKMO key encryption function (default for header version 1).
• --enable-backup-keys — enable the support for backup target keys.
• --disable-backup-keys — disable the support for backup target keys (default).
• --enable-image-encryption — enable encryption of the image components (default).
  • The image components are: the kernel, ramdisk, and kernel command line.
• --disable-image-encryption — disable encryption of the image components.
  • The image components are: the kernel, ramdisk, and kernel command line. Use only if the components used do not contain any confidential content (for example, secrets like non-public cryptographic keys).
• --flags <FLAGS> — set control flags using comma-separated flag names.
  • Specify flags to enable using their names.
  • Possible values:
    • confidential-dump: Confidential guest dump support.
    • pckmo-dea-tdea: DEA/TDEA PCKMO key encryption support.
    • pckmo-aes: AES PCKMO key encryption support.
    • pckmo-ecc: ECC PCKMO key encryption support.
    • pckmo-hmac: HMAC PCKMO key encryption support.
    • backup-target-keys: Backup target keys support.
    • cck-extension-secret-enforcement: CCK-derived extension secret enforcement for add-secret requests.
    • cck-update: CCK update support.
    • no-component-encryption: Image components without encryption.
• --disable-flags <FLAGS> — set control flags using comma-separated flag names.
  • Specify flags to disable using their names.
  • Possible values:
    • confidential-dump: Confidential guest dump support.
    • pckmo-dea-tdea: DEA/TDEA PCKMO key encryption support.
    • pckmo-aes: AES PCKMO key encryption support.
    • pckmo-ecc: ECC PCKMO key encryption support.
    • pckmo-hmac: HMAC PCKMO key encryption support.
    • backup-target-keys: Backup target keys support.
    • cck-extension-secret-enforcement: CCK-derived extension secret enforcement for add-secret requests.
    • cck-update: CCK update support.
    • no-component-encryption: Image components without encryption.
• -h, --help — print help (see a summary with -h).

---

🌈 EXIT STATUS 🌈

• 0 — Program finished successfully.
  • The command was executed successfully. slay. ✅
• 1 — Generic error.
  • Something went wrong during the operation. Refer to the error message.
• 2 — Usage error.
  • The command was used incorrectly, for example: unsupported command line flag, or wrong number of arguments.

---

🍓 EXAMPLES 🍓

These are examples of how to generate an IBM Secure Execution image in /boot/secure-linux, using the kernel file /boot/vmlinuz, the initrd in /boot/initrd.img, the kernel parameters contained in parmfile, the intermediate CA in DigiCertCA.crt, the IBM Z signing key in ibm-z-host-key-signing.crt, and the host-key document in host_key.crt. An AES-256 GCM key is stored in comm-key, which is used when creating a Secure Execution image with guest dump support enabled in the second example. 💖

Generate an IBM Secure Execution image:

pvimg create -i /boot/vmlinuz -r /boot/initrd.img -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/secure-linux

Generate an IBM Secure Execution image with Secure Execution guest dump support:

pvimg create -i /boot/vmlinuz -r /boot/initrd.img -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/secure-linux --enable-dump --cck comm-key

---

🦋 NOTES 🦋

1. The genprotimg(1) command is a symbolic link to the pvimg-create(1) command.
2. An ELF file cannot be used as a Linux kernel image.
3. Remember to re-run zipl after updating an IBM Secure Execution image. this one is important, bestie 🫶

---

👑 SEE ALSO 👑

pvimg(1), zipl(8), qemu(1)

---

💖 that's the whole page, bestie — source/version s390-tools, date 2026-08-11, PVIMG-CREATE(1) out 💖