PVICS.YAML(5)

📦 version 2.44.1, in opensuse-leap 16.0

💅 pvics.yaml(5) — like, the whole manual, bestie 🎀

okay so this is pvics.yaml(5), a File Formats Manual page, and it's genuinely the glow-up guide for your config file. no cap, it's a lot, but we're gonna get through it together 🫶

✨ NAME ✨

pvics.yaml — the configuration file for the pvics SEL EBC image conversion tool. that's the whole vibe. it's giving "let me tell you how to build your image" 💖

🌸 DESCRIPTION 🌸

so pvics.yaml is a YAML-formatted config file, and the pvics tool reads it to control the conversion of your existing qcow2 KVM guest images into EBC-ready Secure Execution for Linux (SEL) images. iconic, honestly.

the config file specifies all the parameters for:

  • image conversion
  • root file system encryption
  • early boot customization (EBC) resource preparation

ngl, if you wanna know the detailed tea about what the tool actually does and how the conversion process goes down, go read pvics(8). that's the main character. this page is the supporting cast 💅

🦋 FILE FORMAT 🦋

the config file uses YAML syntax, and it's got these top-level sections:

  • Global Options — general settings that apply to all actions
  • Certificate Chain — certificate verification configuration
  • Conversion Options — settings specific to the convert action
  • Encryption Options — settings specific to the encrypt action

👑 GLOBAL OPTIONS 👑

  • no-verify: boolean — disables certificate chain verification for pv commands when it's set to true. Default: false.
⚠️ WARNING: do not disable certificate chain verification in production environments. i'm serious. bestie. do not. 😭
  • no-ebc: boolean — controls whether EBC functionality gets used. when it's set to true, you get a SEL guest image created without using EBC. Default: false. when it's enabled, here's what happens:
    • the encrypt action is skipped
    • the full action behaves exactly the same as the convert action
    • default pvimg options are not added — only the user-provided options you specified in .convert.pvimg-create-options get used
    • the rd.sel-ebc kernel parameter is not added
  • out: path — (REQUIRED) local directory path used for output files. every generated file (converted images, keys, ASRs) gets written into this directory. it's the designated drop zone 🎀
  • hkds: list — (REQUIRED) list of paths to host-key-documents (HKDs). paths may contain wildcard patterns, like data/*.hkd. Example:
hkds:
  - data/*.hkd
  - /path/to/specific.hkd

🔥 CERTIFICATE CHAIN 🔥

the certificate-chain section holds all the relevant files for verification of the certificate chain. this section is REQUIRED if no-verify is false, and UNUSED if no-verify is true. so like, pick a lane 💀

for more detailed info about certificate chain verification, see pvsecret(1) — that's the deep lore.

  • certificate-chain.certs: list — list of paths to certificate files. paths may contain wildcard patterns. Example:
certs:
  - data/*.cert
  • certificate-chain.crls: list — list of paths to certificate revocation list (CRL) files. paths may contain wildcard patterns too. Example:
crls:
  - data/*.crl
  • certificate-chain.offline: boolean — enables offline mode for the pvsecret create command. when true, no network access is attempted for certificate verification. airplane mode but make it security ✈️
  • certificate-chain.root-ca: path — path to the root Certificate Authority (CA) file for the certificate chain. the source of truth, the mothership, the root of all roots 🌳

⭐ CONVERSION OPTIONS ⭐

the convert section is where the image conversion phase config lives. these options are used only when you run the convert or full actions — they have no effect on any other actions. like, read the room, other actions 🙈

  • convert.boot-loader-entry: string — (REQUIRED) title of an existing boot loader entry from the base image. this entry specifies which kernel, initramfs, and kernel command line to use for the SEL image. pro tip: use the list action to display the available boot loader entries in the base image. window shopping but for kernels 💖
  • convert.sel-kernel-parameter: string — (OPTIONAL) additional kernel parameters to append to the kernel command line of the resulting SEL image. the rd.sel-ebc parameter is always prepended automatically (unless no-ebc is true). so don't worry, it's handled. Example:
sel-kernel-parameter: swiotlb=524288
  • convert.pvimg-create-options: string — (OPTIONAL) extra options to pass to the pvimg command during SEL image creation. see pvimg(1) for the available options — go check, i'll wait 🧚

💜 ENCRYPTION OPTIONS 💜

the encrypt section is all about root filesystem encryption and EBC resource preparation phase config. these options are used only when running the encrypt or full actions, and they're completely ignored when no-ebc is true. bye bestie 👋

  • encrypt.cck: path — (OPTIONAL) path to the customer communication key (CCK) file. if you don't supply it, a CCK will be generated from /dev/random and written to <out>/cck.key. it literally makes one for you, slay ✨
  • encrypt.extension-secret: path — (OPTIONAL) path to the extension secret file used for pvsecret create commands. if not supplied, an extension secret gets generated from /dev/random and written to <out>/extension.secret. REQUIRED if encrypt.add-secret-requests is used. in that case, the extension secret must match the one used in the supplied add/-secret requests. no mismatches, that's the rule 😤
  • encrypt.luks-key: path — (OPTIONAL) path to the LUKS encryption key file for the root filesystem. if not supplied, a key gets generated from /dev/random and written to <out>/rfs.key.
  • encrypt.luks-passphrase: path — (OPTIONAL) path to a file that contains the LUKS passphrase. if not supplied, a passphrase gets generated from /dev/random and written to <out>/passphrase. fresh out of the random generator 🍓
  • encrypt.luks-key-asr-name: string — (OPTIONAL) name of the add-secret request that contains the LUKS encryption key. Default: rfs-luks-key.
  • encrypt.luks-key-size: integer — (OPTIONAL) key size in bits for the LUKS encryption key. valid values: 256 or 512. if not specified, the size is determined from the supplied key file, or a default size is used for generated keys. mystery sizing, but make it documented 💅
  • encrypt.add-secret-requests: list — (OPTIONAL) list of paths to additional add/-secret request files to be added during boot. paths may contain wildcard patterns. when you use this option:
    • encrypt.extension-secret is REQUIRED
    • the supplied extension secret must match the extension secret used in all supplied add/-secret requests Example:
add-secret-requests:
  - data/*.asr
  - /path/to/custom.asr

🌈 EXAMPLES 🌈

✨ Minimal Configuration for EBC ✨

out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"

✨ Configuration with Custom Encryption Keys ✨

out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"
  sel-kernel-parameter: swiotlb=524288
  pvimg-create-options: --enable-pckmo-hmac
encrypt:
  cck: /path/to/cck.key
  luks-key: /path/to/rfs.key
  luks-passphrase: /path/to/passphrase
  luks-key-size: 512

✨ Configuration with Additional ASRs ✨

out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"
encrypt:
  extension-secret: /path/to/extension.secret
  add-secret-requests:
    - /path/to/*.asr

✨ SEL Image Without EBC ✨

no-ebc: true
out: /path/to/output
hkds:
  - /path/to/*.hkd
convert:
  boot-loader-entry: "My Boot Entry"

🎀 FILES 🎀

here's where everything lives, bestie:

  • /boot/loader/entries/*.conf — boot loader entry files in the base image
  • /boot/sel-ebc.img — the resulting SEL image file
  • /boot/sics/ — SEL Image customization source directory containing EBC resources
  • /boot/sics/toc.pol — table of contents policy file listing 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

🔍 SEE ALSO 🔍

go read these, they're all connected, iykyk:

okay that's the entire page, you ate that 💅✨ go forth and configure, bestie. this was s390-tools, April 2026, page PVICS.YAML(5) — and that's the whole sign-off, mwah 🫶💖🎀

📦 where this page comes from