openshift-docs/modules/ibm-z-secure-execution.adoc

// Module included in the following assemblies:
//
// * installing/installing_ibm_z/installing-ibm-z-kvm.adoc
// * installing/installing_ibm_z/installing-restricted-networks-ibm-z-kvm.adoc

:_mod-docs-content-type: PROCEDURE
[id="installing-rhcos-using-ibm-secure-execution_{context}"]
= Installing {op-system} using {ibm-title} Secure Execution

Before you install {op-system} using {ibm-name} Secure Execution, you must prepare the underlying infrastructure.

.Prerequisites

* {ibm-name} z15 or later, or {ibm-linuxone-name} III or later.
* {op-system-base-full} 8 or later.
* You have a bootstrap Ignition file. The file is not protected, enabling others to view and edit it.
* You have verified that the boot image has not been altered after installation.
* You must run all your nodes as {ibm-name} Secure Execution guests.

.Procedure

. Prepare your {op-system-base} KVM host to support {ibm-name} Secure Execution.

** By default, KVM hosts do not support guests in {ibm-name} Secure Execution mode. To support guests in {ibm-name} Secure Execution mode, KVM hosts must boot in LPAR mode with the kernel parameter specification `prot_virt=1`. To enable `prot_virt=1` on {op-system-base} 8, follow these steps:

.. Navigate to `/boot/loader/entries/` to modify your bootloader configuration file `*.conf`.
.. Add the kernel command line parameter `prot_virt=1`.
.. Run the `zipl` command and reboot your system.
+
KVM hosts that successfully start with support for {ibm-name} Secure Execution for Linux issue the following kernel message:
+
[source,terminal]
----
prot_virt: Reserving <amount>MB as ultravisor base storage.
----
.. To verify that the KVM host now supports {ibm-name} Secure Execution, run the following command:
+
[source,terminal]
----
# cat /sys/firmware/uv/prot_virt_host
----
+
.Example output
+
[source,terminal]
----
1
----
The value of this attribute is 1 for Linux instances that detect their environment as consistent with that of a secure host. For other instances, the value is 0.

. Add your host keys to the KVM guest via Ignition.
+
During the first boot, {op-system} looks for your host keys to re-encrypt itself with them. {op-system} searches for files starting with `ibm-z-hostkey-` in the `/etc/se-hostkeys` directory. All host keys, for each machine the cluster is running on, must be loaded into the directory by the administrator. After first boot, you cannot run the VM on any other machines.
+
[NOTE]
====
You need to prepare your Ignition file on a safe system. For example, another {ibm-name} Secure Execution guest.
====
+
For example:
+
[source,terminal]
----
{
  "ignition": { "version": "3.0.0" },
  "storage": {
    "files": [
      {
        "path": "/etc/se-hostkeys/ibm-z-hostkey-<your-hostkey>.crt",
        "contents": {
          "source": "data:;base64,<base64 encoded hostkey document>"
        },
        "mode": 420
      },
      {
        "path": "/etc/se-hostkeys/ibm-z-hostkey-<your-hostkey>.crt",
        "contents": {
          "source": "data:;base64,<base64 encoded hostkey document>"
        },
        "mode": 420
      }
    ]
  }
}
```
----
+
[NOTE]
====
You can add as many host keys as required if you want your node to be able to run on multiple {ibm-z-name} machines.
====
. To generate the Base64 encoded string, run the following command:
+
[source,terminal]
----
base64 <your-hostkey>.crt
----
+
Compared to guests not running {ibm-name} Secure Execution, the first boot of the machine is longer because the entire image is encrypted with a randomly generated LUKS passphrase before the Ignition phase.

. Add Ignition protection
+
To protect the secrets that are stored in the Ignition config file from being read or even modified, you must encrypt the Ignition config file.
+
[NOTE]
====
To achieve the desired security, Ignition logging and local login are disabled by default when running {ibm-name} Secure Execution.
====
.. Fetch the public GPG key for the `secex-qemu.qcow2` image and encrypt the Ignition config with the key by running the following command:
+
[source,terminal]
----
gpg --recipient-file /path/to/ignition.gpg.pub --yes --output /path/to/config.ign.gpg --verbose --armor --encrypt /path/to/config.ign
----

. Follow the fast-track installation of {op-system} to install nodes by using the {ibm-name} Secure Execution QCOW image.
+
[NOTE]
====
Before you start the VM, replace `serial=ignition` with `serial=ignition_crypted`, and add the `launchSecurity` parameter.
====

.Verification

When you have completed the fast-track installation of {op-system} and Ignition runs at the first boot, verify if decryption is successful.

** If the decryption is successful, you can expect an output similar to the following example:
+
.Example output
[source,terminal]
----
[    2.801433] systemd[1]: Starting coreos-ignition-setup-user.service - CoreOS Ignition User Config Setup...

[    2.803959] coreos-secex-ignition-decrypt[731]: gpg: key <key_name>: public key "Secure Execution (secex) 38.20230323.dev.0" imported
[    2.808874] coreos-secex-ignition-decrypt[740]: gpg: encrypted with rsa4096 key, ID <key_name>, created <yyyy-mm-dd>
[  OK  ] Finished coreos-secex-igni…S Secex Ignition Config Decryptor.
----

** If the decryption fails, you can expect an output similar to the following example:
+
.Example output
[source,terminal]
----
Starting coreos-ignition-s…reOS Ignition User Config Setup...
[    2.863675] coreos-secex-ignition-decrypt[729]: gpg: key <key_name>: public key "Secure Execution (secex) 38.20230323.dev.0" imported
[    2.869178] coreos-secex-ignition-decrypt[738]: gpg: encrypted with RSA key, ID <key_name>
[    2.870347] coreos-secex-ignition-decrypt[738]: gpg: public key decryption failed: No secret key
[    2.870371] coreos-secex-ignition-decrypt[738]: gpg: decryption failed: No secret key
----