cloudhost/README.md

# cloudhost

Start the required operating system with its distribution-specific launcher:

```bash
./run-debian13.py
./run-almalinux10.py
./run-fedora44.py
./run-windows11.py
```

All virtual machines use OVMF/UEFI firmware. Each launcher creates a private,
persistent `OVMF_VARS_4M.fd` variable store in the VM state directory.

Closing the QEMU window stops a foreground VM. To keep the launcher in the
background while still showing the graphical window:

```bash
./run-debian13.py --daemon
```

The launcher uses KVM when `/dev/kvm` is accessible, forwards host port `2222`
to guest port `22`, and creates `.vm/debian13/disk.qcow2` as a 20G writable overlay with the
original qcow2 image as its backing file. The base image therefore stays
unchanged. Run `./run-debian13.py --help` for the supported environment
variables.

The Debian VM hardware (accelerator, 8G memory, 8 CPUs, drives, network) is
defined in the QEMU config file `qemu/debian13.ini`; the machine type and
architecture-specific devices are in `qemu/debian13-amd64.ini` and
`qemu/debian13-arm64.ini`. Edit these files to change the settings. The
launcher fills in the `${...}` file path placeholders of `qemu/debian13.ini`,
writes the result to `.vm/debian13/qemu.ini` and starts QEMU with
`-readconfig` for that file followed by the one for the guest architecture.
QEMU arguments given after `--` override the config files, for example
`./run-debian13.py -- -m 4G -smp 4`.

The launchers accept `--state-dir DIR` to keep
the VM disk, seed ISO, UEFI variables, PID file and console log in `DIR`
instead of the default `.vm/<name>/`. The option takes precedence over the
corresponding `*_STATE_DIR` environment variable:

```bash
./run-debian13.py --state-dir /srv/vms/debian13-test --daemon
```

If `.vm/debian13/seed.iso` is missing, the launcher automatically builds it
from `seediso/debian13/user-data`, `seediso/debian13/meta-data`, and
`seediso/debian13/network-config` before starting the VM.

Image download URLs and implementation are maintained in the `vm-images`
submodule. Clone this repository with its submodules, or initialize it later:

```bash
git submodule update --init --recursive
```

The launchers prefer `vm-images/download-images.sh` when the submodule is
initialized. Otherwise, they fall back to `../vm-images/download-images.sh`
for compatibility with the previous sibling-repository layout. Set
`VM_IMAGE_HELPER` to use another helper path explicitly.

If the Debian base image is missing, the launcher calls the selected image
helper with `debian13`.

## AlmaLinux 10

Start an AlmaLinux 10 Generic Cloud VM with:

```bash
./run-almalinux10.py
```

When the shared AlmaLinux image is missing, the launcher calls the selected
image helper with `almalinux10`. It creates the writable
overlay `.vm/almalinux10/disk.qcow2` and uses the NoCloud configuration in
`seediso/almalinux10/`. SSH is forwarded to host port `2223` by default:

```bash
ssh -p 2223 guofang@localhost
```

AlmaLinux settings use the `ALMA_VM_` prefix. For example:

```bash
ALMA_VM_MEMORY=4G ALMA_VM_CPUS=4 ALMA_VM_SSH_PORT=2224 ./run-almalinux10.py
```

Run `./run-almalinux10.py --help` for all supported settings. The seed ISO is
stored alongside the VM disk at `.vm/almalinux10/seed.iso`. If it already
exists after editing its source files, rebuild it explicitly with
`./seediso/almalinux10/build-seed.sh .vm/almalinux10/seed.iso`.

## Fedora 44

Start a Fedora 44 Cloud Base VM with:

```bash
./run-fedora44.py
```

The launcher downloads the `fedora44` image through the shared helper when it
is missing, creates `.vm/fedora44/disk.qcow2`, and builds its NoCloud seed from
`seediso/fedora44/`. SSH is forwarded to host port `2224` by default:

```bash
ssh -p 2224 guofang@localhost
```

On the first boot, cloud-init updates package metadata and installs Fedora's
GNOME package group through its native package module, then reboots the guest.
Keep the VM running until this initial installation and reboot have completed.

Fedora settings use the `FEDORA_VM_` prefix. Run `./run-fedora44.py --help`
for the complete list of overrides.

## Windows 11 23H2

On first boot, the Windows 11 launcher creates a writable system-disk overlay
from the shared Windows 11 QCOW2 base image:

```bash
./run-windows11.py
```

It creates a persistent 64G disk at `.vm/windows11/disk.qcow2`, automatically
partitions it, completes OOBE, creates the local administrator `guofang` with
the initial password `wang`, and enables Remote Desktop on
`localhost:3389`. During the first login it also installs and enables the
Windows OpenSSH Server on `localhost:2222` and silently installs the VirtIO
Windows guest tools. It also installs the host's configured SSH public key for
passwordless administrator login. The installer includes the VirtIO drivers, SPICE vdagent,
and QEMU Guest Agent. Connect with `ssh guofang@localhost -p 2222`. The launcher
exposes the vdagent channel for host/guest clipboard integration and the QEMU Guest Agent at
`.vm/windows11/qemu-guest-agent.sock`. Change the password after first login.
The generated answer-file ISO is stored beside the disk as
`.vm/windows11/seed.iso`.

To install from the Windows ISO instead, use `./run-windows11.py
--install-from-iso`. This choice only applies while creating a missing system
disk; subsequent starts always boot the existing system disk normally. During
ISO installation, the launcher resolves its tools ISO through the shared image
helper and downloads it when missing. Override the base QCOW2, source ISO,
tools ISO, resources, RDP port, or SSH port with the `WIN11_VM_` environment
variables shown by `./run-windows11.py --help`. For example, when the VirtIO ISO
is elsewhere:

```bash
WIN11_VM_TOOLS_ISO=/custom/path/virtio-win.iso ./run-windows11.py --install-from-iso
```