diff --git a/cmd/remote-session.go b/cmd/remote-session.go index c45a204fb4..54e2563336 100644 --- a/cmd/remote-session.go +++ b/cmd/remote-session.go @@ -138,6 +138,9 @@ func runCreate(c *cobra.Command, args []string) error { "--pull=always", "--privileged", "--security-opt=label=disable", "--volume", remoteSessionOpts.CreateWorkdir, "--workdir", remoteSessionOpts.CreateWorkdir, + // Mount required volume for buildextend-secex, it will be empty on + // non-s390x builders. + // See: https://github.com/coreos/coreos-assembler/blob/main/docs/cosa/buildextend-secex.md "--volume=secex-data:/data.secex:ro", "--uidmap=1000:0:1", "--uidmap=0:1:1000", "--uidmap=1001:1001:64536", "--device=/dev/kvm", "--device=/dev/fuse", "--tmpfs=/tmp", diff --git a/docs/cosa.md b/docs/cosa.md index ca9469309f..6b49864abb 100644 --- a/docs/cosa.md +++ b/docs/cosa.md @@ -42,7 +42,7 @@ other platforms or cloud providers: | Name | Description | | ---- | ----------- | | [buildextend-live](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-live) | Generate the Live ISO -| [buildextend-{dasd,metal,metal4k,qemu}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-metal) | Generate artifacts for the given platforms +| [buildextend-{dasd,metal,metal4k,qemu,secex}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-buildextend-metal) | Generate artifacts for the given platforms | [buildextend-{aliyun,aws,azure,digitalocean,exoscale,gcp,vultr}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-ore-wrapper) | Generate artifacts for the given platforms | [buildextend-{azurestack,ibmcloud,openstack,vmware}](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-artifact-disk) | Generate artifacts for the given platforms | [{aliyun,aws}-replicate](https://github.com/coreos/coreos-assembler/blob/main/src/cmd-ore-wrapper) | Replicate images on the platforms (AMIs for AWS) diff --git a/docs/cosa/buildextend-secex.md b/docs/cosa/buildextend-secex.md new file mode 100644 index 0000000000..5eaa6a63a0 --- /dev/null +++ b/docs/cosa/buildextend-secex.md @@ -0,0 +1,43 @@ +--- +parent: CoreOS Assembler Command Line Reference +nav_order: 1 +--- + +# cosa buildextend-secex + +This buildextend command is used to build QEMU images that are enabled for IBM Secure Execution on IBM Z. +In order to build a QEMU image protected by IBM Secure Execution, you need to provide a host key to encrypt it. + +For more information on IBM Secure Execution on IBM Z, refer to the [IBM Documentation](https://www.ibm.com/docs/en/linux-on-systems?topic=ibmz-secure-execution). + +The command is intended to be used in the RHCOS CI together with the universal host key, such that the image can be booted on any IBM Z machine that supports IBM Secure Execution. +This results in a few specifics to note: +- The resulting image will only be encrypted with a single host key, to enable firstboot. +- The host key will not be written to the image. +- The host key(s) need to be provided later during firstboot through Ignition. + - The firstboot service will fail when no host key is provided, as the sdboot-image can not be recreated. + - Write the host key(s) to: `/etc/se-hostkeys/ibm-z-hostkey-.crt` + +To facilitate this, `buildextend-secex` can take 2 mutually exclusive additional arguments: `--genprotimgvm ` and `--hostkey `. +If none is provided, `--genprotimgvm` is used with default values. + +## `--genprotimgvm ` (default) + +Default Value: `/data.secex/genprotimgvm.qcow2` + +This path is the default behavior. It assumes that the host key is not directly available, but is supplied through an IBM Secure Execution protected VM only. + +The QEMU image will be built normally. However, it will not run `genprotimg` or `zipl`, but instead save the required input for the command to a temporary location. +After the build, the provided VM will run. The VM is used to isolate and protect the `genprotimg` command, so that the universal host key is not exposed. +A provided bash script is called before and after the `genprotimg` command, to fullfil the following steps: +1. Copy the required kernel, initramfs, and parmfile to the VM +2. Move the sdboot-image to the disk +3. Call `zipl`to make the image bootable. +This enables us to copy the required kernel, initramfs and parmfile to the VM and afterwards move the sdboot-image to the disk, as well as calling `zipl` to make the image bootable. + +## `--hostkey ` + +This path is intended for local development, but can be used for custom builds. The path takes a singe host key file, which is used to build the image. + +Instead of running `genprotimg` and `zipl` in a separate VM, they run during the build process. Otherwise, the build is identical to the `--genprotimgvm`. +Note: It is still assumed that the host key is provided via Ignition during firstboot.