From 798c2d3d32921ddf8ebe59b92fcde689ecbf3be5 Mon Sep 17 00:00:00 2001
From: Maxime Van Hees <maxime.vanhees99@gmail.com>
Date: Wed, 30 Jul 2025 16:05:08 +0200
Subject: [PATCH] draft doc

---
 alpine-cloud_hypervisor.md | 157 +++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 alpine-cloud_hypervisor.md

diff --git a/alpine-cloud_hypervisor.md b/alpine-cloud_hypervisor.md
new file mode 100644
index 0000000..e6a6376
--- /dev/null
+++ b/alpine-cloud_hypervisor.md
@@ -0,0 +1,157 @@
+# How to Install and Run Alpine Linux with Cloud Hypervisor
+
+This guide walks you through installing Alpine Linux into a QCOW2 disk image using QEMU, and then running that image with [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor). It includes all the steps you’ll need, from creating the disk, performing the OS install, preparing kernel/initramfs, and finally running the VM with Cloud Hypervisor.
+
+---
+
+## **Goal**
+
+- **Install Alpine Linux into a disk image using QEMU**
+- **Extract the installed kernel and initramfs from the disk**
+- **Boot the VM with Cloud Hypervisor, using direct kernel/initramfs boot**
+
+---
+
+## **Prerequisites**
+
+- Ubuntu (or Debian-based) host
+- `sudo` privileges
+
+---
+
+## **Instructions**
+
+### 1. **Install required tools**
+
+```sh
+sudo apt update
+sudo apt install -y qemu-utils wget curl qemu-system-x86 libguestfs-tools
+```
+
+### 2. **Download Cloud Hypervisor binary**
+
+```sh
+wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v47.0/cloud-hypervisor-static
+chmod +x cloud-hypervisor-static
+```
+
+### 3. **Download Alpine Linux ISO**
+
+We will download the `alpine-virt` ISO, which is similar to the standard ISO but has a slimmed down kernel and is optimized for virtual systems.
+```sh
+wget https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-virt-3.22.1-x86_64.iso
+```
+
+### 4. **Create a blank disk image**
+
+The command below will create a blank disk image called `alpine-vm.qcow2` with a size of 2GB. 
+```sh
+qemu-img create -f qcow2 alpine-vm.qcow2 2G
+```
+
+### 5. **Install Alpine into the disk image**
+
+> **NOTE:** _Cloud Hypervisor does not emulate legacy BIOS/UEFI, so we use QEMU for the initial install._
+```sh
+qemu-system-x86_64 -m 1024M \
+    -cdrom alpine-standard-3.22.1-x86_64.iso \
+    -drive file=alpine-vm.qcow2,format=qcow2 \
+    -boot d \
+    -net nic -net user,hostfwd=tcp::2222-:22 \
+    -nographic
+```
+- **Inside the VM:**
+    - Log in as `root` (no password by default).
+    - Run `setup-alpine` and complete the installation steps.
+
+### 6. **(Optional): Boot into the installed Alpine system with QEMU**
+
+1. Boot into VM:
+
+```sh
+qemu-system-x86_64 \
+    -m 1024M \
+    -drive file=alpine-vm.qcow2,format=qcow2 \
+    -net nic -net user,hostfwd=tcp::2222-:22 \
+    -nographic
+```
+
+2. Install `curl` and `k3s` on the VM:
+
+```sh
+apk update
+apk add curl
+curl -sfL https://get.k3s.io | sh -
+```
+
+### 7. **Enable serial console in Alpine VM**
+
+Edit the `/etc/update-extlinux.conf` in the VM and set:
+
+```sh
+serial_port=0
+```
+
+This ensures the kernel output is available on the serial port, which we use later when launching the VM with Cloud Hypervisor (using the `--serial tty` command line argument).
+
+
+### 8. **Extract kernel, initramfs and kernel parameters from the installed disk**
+> **NOTE**: You only need to mount the QCOW2 disk once to get all necessary files and information.
+
+1. Mount the disk using guestmount
+
+```sh
+sudo guestmount -a alpine-vm.qcow2 -i /mnt
+```
+
+2. Copy the kernel and initramfs:
+
+```sh
+cp /mnt/boot/vmlinuz-lts ./vmlinuz-lts
+cp /mnt/boot/initramfs-lts ./initramfs-lts
+```
+
+3. Get the kernel command line parameters and the root UUID:
+
+```sh
+cat /mnt/boot/extlinux.conf
+```
+
+Look for the `APPEND` line under your boot label (e.g. `LABEL lts`). Example:
+
+```maxima
+LABEL lts
+  MENU DEFAULT
+  MENU LABEL Linux lts
+  LINUX vmlinuz-lts
+  INITRD initramfs-lts
+  APPEND root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4
+```
+
+- Copy everything from `root=UUID=...` to the end of the line (after `APPEND`).
+- You will use this as your kernel command line in Cloud Hypervisor
+
+4. Unmount the disk
+
+```sh
+guestunmount /mnt
+```
+
+### 9. Boot Alpine VM with Cloud Hypervisor
+
+Use the kernel and initramfs you extracted, and set the full kernel command line (adjust UUID and modules as needed):
+
+```sh
+./cloud-hypervisor-static \
+  --kernel ./vmlinuz-lts \
+  --initramfs ./initramfs-lts \
+  --disk path=alpine-vm.qcow2 \
+  --cpus boot=2 \
+  --memory size=1024M \
+  --net "tap=,mac=,ip=192.168.100.2,mask=255.255.255.0" \
+  --serial tty \
+  --cmdline "console=ttyS0 root=UUID=8b578951-b524-42b9-a757-67fa90b56ec8 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4" \
+  --console off
+```
+
+- **Replace the UUID and modules with your values from step 8.**
\ No newline at end of file