From e80d3b4726cda6829404d7c639c4460033a8ce89 Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Wed, 14 Aug 2024 17:01:50 -0700 Subject: [PATCH] chore(document-custom-kernels): Add initial documentation on custom kernels --- doc/admin-guide/custom-kernels.md | 131 ++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 doc/admin-guide/custom-kernels.md diff --git a/doc/admin-guide/custom-kernels.md b/doc/admin-guide/custom-kernels.md new file mode 100644 index 0000000..4979730 --- /dev/null +++ b/doc/admin-guide/custom-kernels.md @@ -0,0 +1,131 @@ +Custom Kernels in krata +======================= + +Krata supports using custom kernels instead of the default Edera-provided +kernel both on a system-wide and zone-wide basis. Krata also supports using +a custom host kernel, as long as it meets certain technical requirements. + +System-wide default kernel for zones +------------------------------------ + +The standard system-wide default kernel for zones is stored in +`/var/lib/krata/zone/kernel` which is the kernel image that should be +booted for the zone, and `/var/lib/krata/zone/addons.squashfs`, +which contains a set of kernel modules that should be mounted in the +zone. + +Zone-wide alternative kernels via OCI +------------------------------------- + +Krata also supports fetching alternative kernel images for use in zones +via OCI repositories. These kernel images are distributed like any other +OCI image, but are not intended to be directly executed by an OCI runtime. + +To select an alternative kernel, you can supply the `-k` option to the +`kratactl zone launch` command that specifies an OCI tag to pull the +alternative kernel image from. + +OCI-based kernel image contents +------------------------------- + +OCI-based kernel images contain the following files: + +* `/kernel/image`: The kernel image itself. + +* `/kernel/addons.squashfs`: A squashfs file containing the kernel + modules for a given kernel image. + +* `/kernel/metadata`: A file containing the following metadata fields + in `KEY=VALUE` format: + - `KERNEL_ARCH`: The kernel architecture (`x86_64` or `aarch64`) + - `KERNEL_VERSION`: The kernel version + - `KERNEL_FLAVOR`: The kernel flavor (examples: `standard`, `dom0` or `openpax`) + - `KERNEL_CONFIG`: The digest for the relevant configuration file stored in the OCI + repository + - `KERNEL_TAGS`: The OCI tags this kernel image was originally built for + (example: `latest`) + +Minimum requirements for a zone-wide/system-wide kernel +------------------------------------------------------- + +The following configuration options must be set: + +``` +CONFIG_XEN=y +CONFIG_XEN_PV=y +CONFIG_XEN_512GB=y +CONFIG_XEN_PV_SMP=y +CONFIG_XEN_PVHVM=y +CONFIG_XEN_PVHVM_SMP=y +CONFIG_XEN_PVHVM_GUEST=y +CONFIG_XEN_SAVE_RESTORE=y +CONFIG_XEN_PVH=y +CONFIG_XEN_PV_MSR_SAFE=y +CONFIG_PCI_XEN=y +CONFIG_NET_9P_XEN=y +CONFIG_XEN_PCIDEV_FRONTEND=y +CONFIG_XEN_BLKDEV_FRONTEND=y +CONFIG_XEN_NETDEV_FRONTEND=y +CONFIG_INPUT_XEN_KBDDEV_FRONTEND=y +CONFIG_HVC_XEN=y +CONFIG_HVC_XEN_FRONTEND=y +CONFIG_XEN_FBDEV_FRONTEND=m +CONFIG_XEN_BALLOON=y +CONFIG_XEN_BALLOON_MEMORY_HOTPLUG=y +CONFIG_XEN_MEMORY_HOTPLUG_LIMIT=512 +CONFIG_XEN_SCRUB_PAGES_DEFAULT=y +CONFIG_XEN_DEV_EVTCHN=y +CONFIG_XEN_BACKEND=y +CONFIG_XENFS=y +CONFIG_XEN_COMPAT_XENFS=y +CONFIG_XEN_SYS_HYPERVISOR=y +CONFIG_XEN_XENBUS_FRONTEND=y +CONFIG_SWIOTLB_XEN=y +CONFIG_XEN_HAVE_PVMMU=y +CONFIG_XEN_EFI=y +CONFIG_XEN_AUTO_XLATE=y +CONFIG_XEN_ACPI=y +CONFIG_XEN_HAVE_VPMU=y +CONFIG_XEN_GRANT_DMA_OPS=y +CONFIG_XEN_VIRTIO=y +``` + +It is possible to copy these options into a `.config` file and then use +`make olddefconfig` to build the rest of the kernel configuration, which +you can then use to build a kernel as desired. + +The [kernels][edera-kernels] repository provides some example configurations +and can generate a Dockerfile which will build a kernel image. + + [edera-kernels]: https://github.com/edera-dev/kernels + +Minimum requirements for a host kernel +-------------------------------------- + +The configuration options above are also required for a host kernel. +In addition, the following options are also required: + +``` +CONFIG_XEN_PV_DOM0=y +CONFIG_XEN_DOM0=y +CONFIG_PCI_XEN=y +CONFIG_XEN_PCIDEV_BACKEND=y +CONFIG_XEN_BLKDEV_BACKEND=y +CONFIG_XEN_NETDEV_BACKEND=y +CONFIG_XEN_SCSI_BACKEND=y +CONFIG_XEN_PVCALLS_BACKEND=y +CONFIG_TCG_XEN=m +CONFIG_XEN_WDT=y +CONFIG_XEN_DEV_EVTCHN=y +CONFIG_XEN_GNTDEV=y +CONFIG_XEN_GRANT_DEV_ALLOC=y +CONFIG_XEN_GRANT_DMA_ALLOC=y +CONFIG_SWIOTLB_XEN=y +CONFIG_XEN_PRIVCMD=y +CONFIG_XEN_ACPI_PROCESSOR=y +CONFIG_XEN_MCE_LOG=y +``` + +Build and install the kernel as you normally would for your system. +Assuming GRUB is the bootloader, it will automatically detect the new +host kernel when you run `grub-mkconfig` or `grub2-mkconfig`.