control-vm.sh

Table of Contents

• Usage
• Installation and setup
  • Packages on Gentoo/Linux
  • Directory and files
• Configuration of the guest
• Contact
• Copyright

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

./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:

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:

  $(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.

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.