docs: Guide to add new Host/Guest OS images for new OS support.

LakshmiSaiHarika · LakshmiSaiHarika · commit 33772ab8f305 · 2026-03-02T12:28:24.000-08:00
Signed-off-by: Harika Nittala &lt;lnittala@amd.com&gt;
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
 The purpose of this repository is to provide a unified framework for testing and certifying operating system support for [AMD Secure Encrypted Virtualization (SEV)](https://www.amd.com/en/developer/sev.html) features. These are hardware-enabled security features that provide confidentiality and integrity of VM memory through per-VM encryption keys. Self-service tools are provided to run a series of certification tests using an AMD EPYC server, allowing for any user/organization to verify SEV support on a particular OS. 
 
-**Note**: Currently only linux distributions supported by [`mkosi`](https://github.com/systemd/mkosi) are compatible with this framework.
+**Note**: Currently only linux distributions supported by [`mkosi`](https://github.com/systemd/mkosi) are compatible with this framework. Please take a look at few important key points about `sev-certify` project [here](#key-points).
 
 ## Certification Matrix
 
@@ -44,4 +44,11 @@ Host and Guest images are constructed in GitHub Workflows via [`mkosi`](https://
 [hardware-tables]: ./docs/certifications.md#certification-levels-by-hardware
 [cert-definitions]: ./docs/certifications.md#certification-level-definitions
 
+Users seeking to verify [AMD Secure Encrypted Virtualization (SEV) features](https://www.amd.com/en/developer/sev.html) features for an Operating System not included in the current`sev-certify` project can utilize our guide [here](./docs/how-to-add-new-os-images.md).
 
+## Key Points
+- Host and guest artifacts under 'devel' tag in sev-certify are purely for development and testing purpose, and may not be a good fit for production purpose.
+- Each host image will have an embedded guest image.
+- When a host image is booted on the server, host images are installed in RAM.
+- Guest images will "fail" if SNP isn't enabled.
+- Host will automatically reboot when done.
diff --git a/docs/how-to-add-new-os-images.md b/docs/how-to-add-new-os-images.md
@@ -0,0 +1,159 @@
+# Create, test and publish new guest/host OS images
+
+You are advised to refer to the linux distribution files in [mkosi upstream distribution](https://github.com/systemd/mkosi/tree/main/mkosi/distribution) to determine OS support for configuring and building new OS support within the `sev-certify` project. If the OS support is unavailable, you can connect with mkosi community via forums, mailing lists, or the [mkosi GitHub issue tracker](https://github.com/systemd/mkosi/issues).
+
+You can create and publish new host or guest images in `sev-certify` with `mkosi` tool in the following steps:
+
+- <u>**Fork sev-certify:**</u> Begin by creating your own fork of the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) project.
+
+- <u>**Develop New mkosi Templates for Host and Guest OS Images:**</u> Within your forked repository, you should:
+  - Create new OS directories named `host-<new-os-name>-<new-os-release>` and `guest-<new-os-name>-<new-os-release>` in the `sev-certify/images` directory.
+  - Find an existing OS template in the `sev-certify` project that resembles your new OS. For example, to create a CentOS linux image, you can refer to the Fedora linux mkosi template.
+  - Start configuring your new mkosi template by copying the identified similar linux templates into your new OS directories.
+
+  If your new mkosi template differs from all existing templates, ensure to meet the minimum linux package requirements as detailed in the configuration [section](#configure-new-mkosi-template-for-host-and-guest-os-images).
+
+- <u>**Integrate New OS Release into GitHub Workflow**</u>  Add new host/guest OS images to your forked `sev-certify` GitHub repository by including the new OS release in the `distro matrix` of the `build-and-release.yml` workflow located in `sev-certify/.github/workflows`:
+  ```
+      - distro: <new-os-name>
+        release: <new-os-release>
+  ```
+
+- <u>**Build new Host and Guest OS images:**</u> You can choose between two methods to build new host and guest OS images:
+  - **Option 1:** Preferred for the users who plan to build their new host/guest OS images <u>within their forked `sev-certify` GH repository</u> after pushing their new mkosi templates.
+
+    Trigger `build-and-release.yml` GitHub workflow manually in your forked `sev-certify` github repository to create the new OS host and guest images. Then, verify for successful execution with the built new host and guest OS images under `devel` tag.
+
+    If the `build-and-release` workflow fails, you need to troubleshoot for the error in the workflow log, implement changes, and retest until successful execution.
+
+  - **Option 2**: Suitable for those who want to build locally using the `mkosi` command before updating their forked repository.
+
+    Ensure that the mkosi tool compatible with the `sev-certify` project is installed on your system. `mkosi` installation instructions are available [here](#install-mkosi-on-your-system)
+
+    Then, build new host/guest OS images using `mkosi` in `sev-certify` directory:
+
+    ```
+    mkosi --image-id=host-<new-os-name>-<new-os-release> \
+    -C images/host-<new-os-name>-<new-os-release> build
+    ```
+    Host image, host Kernel, host boot ramfs are generated in the `host-<new-os-name>-<new-os-release>` directory.
+
+    ```
+    mkosi --image-id=host-<new-os-name>-<new-os-release> \
+    -C images/host-<new-os-name>-<new-os-release> build
+    ```
+    Guest image, guest Kernel, guest boot ramfs are generated in the `host-<new-os-name>-<new-os-release>` directory.
+
+    Ubuntu users encountering AppArmor-related permission errors with mkosi should refer to this [exception](#exceptions).
+
+- <u>**Test the New OS Host/Guest Images:**</u> To test the built guest image, you should:
+  - **Retrieve the built guest image** either by downloading the new guest OS image `guest-<new-os-name>-<new-os-release>` under `devel` tag of your forked repository, (or) use the locally built guest OS image `images/guest-<new-os-name>-<new-os-release>/guest-<new-os-name>-<new-os-release>.efi` on the system.
+  - Launch the built guest image on SEV-enabled host following the instructions in this [guide](https://github.com/AMDEPYC/sev-certify/blob/main/docs/how-to-run-guest-manually.md).
+
+
+To test the host image, you should:
+  - **Fetch the built host image** either by downloading the new host OS image `host-<new-os-name>-<new-os-release>` under `devel` tag of your forked repository (or) use the locally built host OS image `images/guest-<new-os-name>-<new-os-release>/guest-<new-os-name>-<new-os-release>.efi` on the system.
+  - Boot the built host image on your SNP-enabled test server using HTTPboot/dispatch process to test the newly built host OS image on bare metal and generate new OS certificate under your forked `sev-certify` issues using this [guide](https://github.com/AMDEPYC/sev-certify/blob/main/docs/how-to-generate-certs.md#forking-amdepycsev-certify-for-certification-testing). Host image will automatically reboot when done.
+
+- <u>**Submit a Pull Request for the New OS:**</u> Once all tests are passed, create a pull request to integrate your new OS support into the `sev-certify` upstream.
+
+**NOTE:** Ensure that all GitHub workflow tests pass on your last pushed commit to facilitate integration into the upstream repository.
+
+## Configure new mkosi template for Host and Guest OS images
+### Host OS Image Configuration
+Create a `mkosi.conf` file under `sev-certify/images/host-<new-os-name>-<new-os-release>` folder. Ensure it includes:
+  ```
+  [Include]
+  # Include required modules in the host image
+  Include=../../modules/host
+
+  [Distribution]
+  Distribution=<new-os-name>
+  Release=<new-os-release>
+
+  [Content]
+  Packages=
+    # Required host OS packages to certify Host OS in sev-certify
+    <host-kernel-package>
+    <qemu-package>
+    <ovmf-package>
+
+    # Required host OS package dependencies for sev-certify framework execution
+    <systemd-package>
+    <systemd-resolved-package>
+    <systemd-journal-remote-package>
+    <openssl-package>
+    <xxd-package>
+    <python3-pip-package>
+    <python3-emoji-package>
+    <jq-package>
+    <avahi-daemon-package>
+  ```
+
+### Guest OS Image Configuration
+Create a `mkosi.conf` in `sev-certify/images/guest-<new-os-name>-<new-os-release>` folder. It should contain:
+
+Sample `mkosi.conf` content for new guest OS image has below minimum requirements:
+  ```
+  [Include]
+  # Include required modules in the guest image
+  Include=../../modules/guest
+
+  [Distribution]
+  Distribution=<new-os-distro>
+  Release=<new-os-release>
+
+  [Content]
+  Packages=
+  # Required guest OS packages to certify Guest OS in sev-certify
+  <guest-kernel-package>
+
+  # Required guest OS package dependencies for sev-certify framework execution
+  <systemd-package>
+  <systemd-boot-package>
+  <systemd-boot-resolved-package>
+  <systemd-journal-remote-package>
+  <openssl-package>
+  <ca-certificates-package>
+  <jq-package>
+  <xxd-package>
+  ```
+## Install mkosi on your System
+You should:
+- Identify the mkosi version compatible with the sev-certify project in `Install dependencies` task from the workflow [build-and-release.yml](https://github.com/AMDEPYC/sev-certify/blob/main/.github/workflows/build-and-release.yml). For now, it uses Ubuntu Plucky release version 25.3.
+- Install mkosi:
+  - **Option 1:** Use your OS package manager to install a compatible mkosi version.  A list of supported Linux Distributions for mkosi package can be found under `tags` on the [mkosi GitHub page](https://github.com/systemd/mkosi). Alternatively, you can build from the source following Option 2 instructions.
+  - **Option 2:** Build and install mkosi from the source repository
+
+    Build mkosi from source and update `MKOSI_VERSION` to match with the `mkosi` version used in the sev-certify upstream.
+    ```bash
+    cd /tmp
+    export MKOSI_VERSION=v25.3
+    git clone https://github.com/systemd/mkosi.git
+    cd mkosi
+    git checkout $MKOSI_VERSION
+    ```
+
+    Install it manually since mkosi might not be in all package managers by default. Inside the /tmp/mkosi directory, run the following:
+    ```bash
+    sudo make install
+    ```
+
+    After make finishes, optionally move the mkosi script. For example:
+    ```bash
+    sudo mv mkosi /usr/local/bin
+    ```
+    Verify mkosi installation with:
+    ```bash
+    mkosi --version
+    ```
+    The displayed version should match the version used in sev-certify upstream.
+
+## Exceptions
+
+### Important Note for Ubuntu Users
+Permission errors related to AppArmor while running mkosi are recognized and documented in [systemd/mkosi#3265](https://github.com/systemd/mkosi/issues/3265). Please take a look at this issue to tackle this permission error.
+
+## References
+- **Debian based OS:** Sample PR to add Ubuntu 25.10 OS Support into the `sev-certify` project is available in this [link](https://github.com/AMDEPYC/sev-certify/pull/222).
+- **RH based OS:** Sample PR to add Rocky 10 OS Support into the `sev-certify` project is available in this [link](https://github.com/AMDEPYC/sev-certify/pull/87/).
