= control-vm.sh
// vim:syntax=asciidoc:fileencoding=utf-8:ts=4:expandtab:linebreak:wrap
:toc:

This repository contains a simple bash script to start and stop virtual machines run by QEMU and KVM and to connect to them via SSH or VNC or SPICE.

The newest version can be probably found on https://git.holgersson.xyz/nfr/control-vm.

NOTE: While the author already runs this software in "production" on his private setup he would still consider some parts as beta quality.
As usual it's strongly recommended to create backups first and read through the bash script to understand roughly what it does.

== Usage
[source, shell]
----
./control-vm.sh <name of your virtual machine> start | shutdown | stop | connect | save | restore | pause | resume
----

NOTE: You do not see any `setup` command there as I've implemented no one-shot boot from ISO so far.

== Installation and setup
Please install the following tools which are used by the script:

- `bash`
- `>=qemu-10.0.0`
- `socat`
- `remote-viewer` as part of virt-viewer (https://virt-manager.org)

=== Packages on Gentoo/Linux
On Gentoo/Linux the packages can be installed by the package manager:
[source,shell]
----
emerge --ask --verbose app-emulation/qemu net-misc/socat app-emulation/virt-viewer sys-firmware/edk2
----

Please ensure the following USE flags:

- `USE="vnc spice"` for `app-emulation/virt-viewer`

=== Directory and files
Create a directory to store your VM images and metadata.
Let it be readable and writeable for the user who executes QEMU.
Copy this script into that directory.

For each Guest do the following:
. Create a directory named exactly as the guest (case sensitive).
. Create an qcow2 image named virtual-machine.img inside
   the newly created directory.
. Create a configuration file named exactly as the guest plus a suffix `.bash`.
. Fill in the data from the example below into the configuration file.
. Control the vm by calling: `./control-vm.sh <guest> <operation>`,
    e.g. `./control-vm.sh Gentoo-guest start`,
    or   `./control-vm.sh Gentoo-guest connect`,
    or   `./control-vm.sh Gentoo-guest shudown`.

You should have a setup like this now:
[source,bash]
----
  $(pwd)/
  $(pwd)/control-vm.sh
  $(pwd)/Gentoo-guest-1/virtual-machine.img
  $(pwd)/Gentoo-guest-1/virtual-machine.bash
----

== Configuration of the guest
Create a file with the guest's parameters and name it same as the "GUEST_NAME" plus a ".bash" suffix, so we can easily assume the name later.

[source,bash]
----
cat << _EOF > "${GUEST_NAME}/virtual-machine.bash"
# Provide the GUEST_NAME which is used in further configuration.
GUEST_NAME="Guest-OS"
# Configure the number of CPUs. Simplified and based on
# `qemu-system-<arch> -smp help`.
CPU_CORES="8"
MEMORY="16384"
NET="True"
SOUND="True"
SSH_PORT=""
# Configure any of the arches QEMU supports in QEMU's notation.
# Leave it empty or omit it for x86_64.
ARCH=""
# Disable EFI and enable BIOS fallback mode with unsetting EFI_MACHINE.
# EFI=""
# Enable the SPICE socket.
UI="True"
CLIPBOARD="True"
_EOF
----

== Contact
If you have questions, suggestions or want to brag about your other qemu managing tools feel free to write an email or conact via IRC or mastodon:

  - mail: `nils.freydank@posteo.de`
  - IRC: `holgersson` on libera.chat and oftc, mostly in Gentoo related channels
  - mastodon: `https://maly.io/@holgersson`

== Copyright
The bash script and its documentation is licensed as MIT, copyright by Nils Freydank.

The used software has each its own license, but is all FLOSS software.