mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
ca0ee966b8
Specify the requirements for the base image in the pvics manpage. Reviewed-by: Holger Dengler <dengler@linux.ibm.com> Signed-off-by: Finn Callies <fcallies@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
356 lines
10 KiB
Groff
356 lines
10 KiB
Groff
.\" Copyright IBM Corp.
|
|
.\" s390-tools is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the MIT license. See LICENSE for details.
|
|
.\"
|
|
.TH PVICS 8 "April 2026" "s390-tools"
|
|
|
|
.SH NAME
|
|
pvics \- Convert qcow2 KVM guest images to EBC-ready SEL images
|
|
|
|
.SH SYNOPSIS
|
|
.B pvics
|
|
.I ACTION
|
|
.RB [ \-h | \-\-help ]
|
|
.RB [ \-c | \-\-config
|
|
.IR CONFIG_FILE ]
|
|
.RB [ \-i | \-\-image
|
|
.IR BASE_IMAGE ]
|
|
|
|
.SH DESCRIPTION
|
|
Use the \fBpvics\fR 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:
|
|
.IP \(bu 2
|
|
Retrieving information about a given base image
|
|
.IP \(bu 2
|
|
Converting a base image according to a configuration
|
|
.IP \(bu 2
|
|
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.
|
|
|
|
.SH Base Image Prerequisites
|
|
The following prerequisites have to be fulfilled by the base image:
|
|
.IP \(bu 2
|
|
label of boot partition set to boot
|
|
.IP \(bu 2
|
|
label of root partition set to root
|
|
.IP \(bu 2
|
|
guest is to be backed by a qcow2 image
|
|
.IP \(bu 2
|
|
an initramfs containing the dracut module 95sel-ebc which is part of s390-tools
|
|
.IP \(bu 2
|
|
a boot loader specifying that initramfs and a kernel parameter line on which root is specified by label
|
|
.IP \(bu 2
|
|
any line starting with default= should be removed from /etc/zipl.conf
|
|
|
|
.SH ACTIONS
|
|
.TP
|
|
.B list
|
|
Retrieve information about a given base image. This action displays available
|
|
boot loader entries from \fB/boot/loader/entries\fR, along with kernel and
|
|
initramfs hashes and the kernel command line. This is useful for:
|
|
.RS
|
|
.IP \(bu 2
|
|
Determining valid values for the \fBboot-loader-entry\fR configuration option
|
|
.IP \(bu 2
|
|
Comparing components between base and converted images
|
|
.IP \(bu 2
|
|
Verifying image contents before conversion
|
|
.RE
|
|
|
|
.TP
|
|
.B convert
|
|
Convert a base image according to the configuration file. This action:
|
|
.RS
|
|
.IP \(bu 2
|
|
Fetches kernel, initramfs, and kernel command line from the specified boot
|
|
loader entry
|
|
.IP \(bu 2
|
|
Builds a SEL image using \fBpvimg\fR(1)
|
|
.IP \(bu 2
|
|
Updates \fB/boot/bootmap\fR to boot into the SEL image
|
|
.RE
|
|
.IP
|
|
The resulting image will be a SEL guest image. It requires encryption to be
|
|
fully EBC-ready (unless \fBno-ebc\fR is enabled in the configuration).
|
|
|
|
.TP
|
|
.B encrypt
|
|
Encrypt the root file system and prepare EBC resources. This action:
|
|
.RS
|
|
.IP \(bu 2
|
|
Generates secure defaults (CCK, extension secret, LUKS keys) if not provided
|
|
.IP \(bu 2
|
|
Encrypts the root file system using LUKS with PAES
|
|
.IP \(bu 2
|
|
Populates \fB/boot/sics/\fR with add/-secret requests
|
|
.IP \(bu 2
|
|
Creates \fBtoc.pol\fR and \fBtoc.asr\fR for integrity protection
|
|
.RE
|
|
.IP
|
|
This action requires EBC. The guest can boot only by using PAES to open the root file system.
|
|
|
|
.TP
|
|
.B full
|
|
Perform both \fBconvert\fR and \fBencrypt\fR actions in sequence. This is
|
|
equivalent to running \fBconvert\fR followed by \fBencrypt\fR, but in a single
|
|
invocation.
|
|
|
|
.SH ARGUMENTS
|
|
.TP
|
|
.I ACTION
|
|
The action to perform: \fBlist\fR, \fBconvert\fR, \fBencrypt\fR, or \fBfull\fR.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-h ", " \-\-help
|
|
Display help message and exit.
|
|
|
|
.TP
|
|
.BR \-c ", " \-\-config " " \fICONFIG_FILE\fR
|
|
Path to the YAML configuration file. See \fBpvics.yaml\fR(5) for the
|
|
configuration file format and options.
|
|
.br
|
|
Required for \fBconvert\fR, \fBencrypt\fR, and \fBfull\fR actions.
|
|
.br
|
|
Not required for the \fBlist\fR action.
|
|
|
|
.TP
|
|
.BR \-i ", " \-\-image " " \fIBASE_IMAGE\fR
|
|
Path to the base qcow2 image file to process. Required for all actions.
|
|
|
|
.SH CONVERSION PROCESS
|
|
The conversion process consists of three phases:
|
|
|
|
.SS 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 \fBrd.sel-ebc\fR to the kernel command line to trigger the
|
|
SEL EBC dracut module (unless \fBno-ebc\fR is enabled) and appends any
|
|
user-provided kernel parameters from the configuration.
|
|
|
|
.SS SEL Image Build
|
|
The SEL image is built using \fBpvimg\fR(1) with the fetched components.
|
|
Additional options may be specified in the configuration file via
|
|
\fB.convert.pvimg-create-options\fR.
|
|
|
|
.SS Bootmap Update
|
|
The tool updates the bootmap to boot into the new SEL image:
|
|
.IP \(bu 2
|
|
Existing boot loader entries in \fB/boot/loader/entries/*.conf\fR are renamed
|
|
to \fB*.conf.old\fR
|
|
.IP \(bu 2
|
|
A new entry \fBsel-ebc.conf\fR is created that points to \fB/boot/sel-ebc.img\fR
|
|
.IP \(bu 2
|
|
\fBzipl\fR(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
|
|
\fB/var/log/sel-ebc-zipl.log\fR.
|
|
|
|
.SH ENCRYPTION PROCESS
|
|
The encryption process consists of three phases:
|
|
|
|
.SS Secure Default Generation
|
|
If not provided in the configuration, the following are generated from
|
|
\fB/dev/random\fR:
|
|
.IP \(bu 2
|
|
Customer communication key (CCK)
|
|
.IP \(bu 2
|
|
Root file system LUKS encryption key
|
|
.IP \(bu 2
|
|
Extension secret for add/-secret requests
|
|
.IP \(bu 2
|
|
LUKS passphrase
|
|
|
|
.SS Root File System Encryption
|
|
The root file system is encrypted using the following steps:
|
|
.IP 1. 3
|
|
Resize the qcow2 image to accommodate the LUKS header
|
|
.IP 2. 3
|
|
Resize the root partition (but not the file system) to fit the LUKS header
|
|
.IP 3. 3
|
|
Encrypt the root file system using LUKS
|
|
.IP 4. 3
|
|
Reformat the LUKS header from AES to PAES (Protected AES)
|
|
|
|
.SS 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.
|
|
|
|
.SS SICS Population
|
|
The SEL Image Customization Source directory (\fB/boot/sics\fR) is populated
|
|
with the following secrets as add/-secret requests:
|
|
.IP \(bu 2
|
|
Customer communication key (CCK)
|
|
.IP \(bu 2
|
|
LUKS encryption key
|
|
.IP \(bu 2
|
|
LUKS passphrase
|
|
.IP \(bu 2
|
|
Any additional add/-secret requests specified in the configuration
|
|
|
|
All automatically built add/-secret requests are added to \fBtoc.pol\fR, which verifies the
|
|
completeness of \fB/boot/sics\fR. User-supplied add/-secret requests from the configuration
|
|
are also added. Finally, \fBtoc.asr\fR is built as a meta secret that links
|
|
to \fBtoc.pol\fR for integrity protection.
|
|
|
|
.SH BUILDING SEL IMAGES WITHOUT EBC
|
|
While the primary purpose of \fBpvics\fR is to create EBC-ready SEL images with
|
|
encrypted root file systems, it can also build SEL images without EBC
|
|
functionality using the \fBno-ebc\fR configuration option.
|
|
|
|
When \fBno-ebc: true\fR is set in the configuration:
|
|
.IP \(bu 2
|
|
The \fBconvert\fR action builds a SEL image without EBC-specific flags
|
|
.IP \(bu 2
|
|
The \fBencrypt\fR action is completely skipped
|
|
.IP \(bu 2
|
|
The \fBfull\fR action becomes equivalent to \fBconvert\fR only
|
|
.IP \(bu 2
|
|
The \fBrd.sel-ebc\fR kernel parameter is not added
|
|
.IP \(bu 2
|
|
\fB--enable-cck-update\fR and \fB--disable-image-encryption\fR flags are not
|
|
passed to \fBpvimg\fR
|
|
|
|
This mode is useful for:
|
|
.IP \(bu 2
|
|
Single-party image creation where the same entity performs conversion,
|
|
customization, and encryption
|
|
.IP \(bu 2
|
|
Testing SEL guest functionality without EBC complexity
|
|
.IP \(bu 2
|
|
Development and debugging scenarios
|
|
.IP \(bu 2
|
|
Simplified SEL image generation workflows
|
|
|
|
.SH OUTPUT FILES
|
|
All output files are written to the directory specified by the \fBout\fR
|
|
configuration option:
|
|
|
|
.TP
|
|
\fB<out>/image.qcow2\fR
|
|
The converted SEL image (after \fBconvert\fR or \fBfull\fR action)
|
|
|
|
.TP
|
|
\fB<out>/cck.key\fR
|
|
Customer communication key (generated if not provided)
|
|
|
|
.TP
|
|
\fB<out>/extension.secret\fR
|
|
Extension secret for add/-secret requests (generated if not provided)
|
|
|
|
.TP
|
|
\fB<out>/rfs.key\fR
|
|
Root file system LUKS encryption key (generated if not provided)
|
|
|
|
.TP
|
|
\fB<out>/passphrase\fR
|
|
LUKS passphrase (generated if not provided)
|
|
|
|
.TP
|
|
\fB<out>/*.asr\fR
|
|
Generated add-secret request files
|
|
|
|
.SH TEMPORARY FILES
|
|
.TP
|
|
\fB/tmp/tmp.*\fR
|
|
Log file (filename logged at startup)
|
|
|
|
.SH EXIT STATUS
|
|
.TP
|
|
.B 0
|
|
Success
|
|
.TP
|
|
.B 1
|
|
General error (invalid arguments, missing files, operation failure)
|
|
|
|
.SH EXAMPLES
|
|
.SS List Boot Loader Entries
|
|
.nf
|
|
pvics list \-\-image /path/to/base-image.qcow2
|
|
.fi
|
|
|
|
.SS Convert Image Only
|
|
.nf
|
|
pvics convert \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
|
.fi
|
|
|
|
.SS Encrypt Image Only
|
|
.nf
|
|
pvics encrypt \-\-config /path/to/config.yaml \-\-image /path/to/converted-image.qcow2
|
|
.fi
|
|
|
|
.SS Full Conversion and Encryption
|
|
.nf
|
|
pvics full \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
|
.fi
|
|
|
|
.SS Build SEL Image Without EBC
|
|
.nf
|
|
# config.yaml contains: no-ebc: true
|
|
pvics convert \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
|
.fi
|
|
|
|
.SH FILES
|
|
.TP
|
|
\fB/boot/loader/entries/*.conf\fR
|
|
Boot loader entry files in the base image
|
|
|
|
.TP
|
|
\fB/boot/sel-ebc.img\fR
|
|
The resulting SEL image file in the guest
|
|
|
|
.TP
|
|
\fB/boot/sics/\fR
|
|
SEL image-customization source directory that contains EBC resources
|
|
|
|
.TP
|
|
\fB/boot/sics/toc.pol\fR
|
|
Table-of-contents policy file that lists all add/-secret requests
|
|
|
|
.TP
|
|
\fB/boot/sics/toc.asr\fR
|
|
Meta secret for integrity protection of toc.pol
|
|
|
|
.TP
|
|
\fB/var/log/sel-ebc-zipl.log\fR
|
|
Log file for zipl bootmap update operations
|
|
|
|
.SH NOTES
|
|
.IP \(bu 2
|
|
All operations are performed on a copy of the original base image.
|
|
.IP \(bu 2
|
|
The tool requires root privileges for file-system operations.
|
|
.IP \(bu 2
|
|
The LUKS device is named \fBcryptroot\fR.
|
|
.IP \(bu 2
|
|
The temporary working directory is created at \fB/opt/sel-<UUID>\fR.
|
|
.IP \(bu 2
|
|
The \fBno-verify\fR option should not be used in production environments.
|
|
.IP \(bu 2
|
|
Generated secrets are written to the output directory and should be secured
|
|
appropriately.
|
|
|
|
.SH SEE ALSO
|
|
.BR pvics.yaml (5),
|
|
.BR pvsecret (1),
|
|
.BR pvimg (1),
|
|
.BR pvebc (8),
|
|
.BR zipl (8),
|
|
.BR cryptsetup (8),
|
|
.BR lsinitrd (1)
|
|
.PP
|
|
Linux on IBM Z and IBM LinuxONE: Secure Execution for Linux documentation
|
|
|
|
.SH AUTHOR
|
|
IBM Corporation
|