qemush/README.md

qemush - An Unix philosophy respecting QEMU wrapper written in shell

How does it work

qemush allows to run commands as Unix user qemu to manage virtual machines and their disks associated.

Why

qemush is daemonless: no bloaty long running process is needed for qemush to work.

qemush is lightweight: it only consists in a shell script to automate repeated tasks and force good practices.

qemush needs few dependencies: see section Dependencies for details.

qemush is hackable: you can write your own launching scripts to make it work as intended.

qemush is easy to setup: you can make it work in a few steps, see section Installation instructions.

Good practices?

Here is a list of good practices forced by qemush.

• Processes running as user qemu: members of group qemu can manage the same virtual machines
• Modularization: qemush launching scripts are intended to be stackable to reuse common qemu parameters in all virtual machines needing them
• Process supervision: qemush uses screen to supervise processes and keep track of them
• Copy-on-write: images are formatted using qcow2 to use less space on disk

Dependencies

All dependencies are common packages for a distribution, you'll be able to grab them from your packages sources.

• qemu - this is literally a QEMU wrapper so there's a chance you'll need it
• bash - the qemush interpreter
• coreutils - used for basic OS operations
• sudo - execute commands as qemu
• screen - for process supervision
• source-highlight - for syntax highlighting when displaying launching scripts
• diskpath - see Add qemush modules in ~qemu/bin
• any text editor - used for builtin function to edit launching scripts

You can run qemush depcheck to check if all dependencies are met.

Installation instructions

QEMU user and group

qemush acts as Unix user qemu to manage virtual machines. You need to create a system user qemu that cannot login, with any home directory, in an Unix group of the same name. Example:

# Example if the qemu user doesn't exist
# Make sure /etc/shells contains /bin/nologin
useradd -r -s /bin/nologin qemu

For ease of use, you need to grant every user in the qemu group via sudo the right to execute commands as qemu. You can find an example sudoers rule in this repo's etc/sudoers.d folder.

Add qemush in the PATH

Use your preferred way to add the qemush script to a folder of PATH. Recommended: copy the script in /usr/local/bin to make it effortlessly system wide.

Add qemush modules in ~qemu/bin

qemush needs reusable script modules like diskpath in its custom bin folder located at ~qemu/bin. You can add them directly via qemush from this repo via the following command :

qemush do 'mkdir -p ~/bin && cp -v qemu/bin/* "$_"'

Extra: add first-free-port in PATH

first-free-port is a small C program designed accordingly to the Unix philosophy to show in stdout the first free (not listening) TCP port after argv[1], or argv[1] if it is free. You will need it to allocate ports to protocols like SPICE in your launching scripts (example in qemu/bin/*-spice).

Example qemush command to add the program to a local qemu bin folder :

qemush do 'mkdir ~/bin && cc -o "${_}/first-free-port" src/first-free-port.c'

Usage

Writing a launching script

The default text editor used by qemush is nvim, but it can be overriden by the EDITOR environment variable.

Run the following command to start editing a launching script by the name of your choice:

qemush edit "$name"

Example scripts are available in this repo's qemu/bin folder.

Launching a virtual machine

Virtual machines are identified by the name of their launching scripts. You can launch any machine with the following command:

qemush start "$name"

You can also list all available virtual machines by running this command:

qemush ls

Other uses

You can show the full list of possible actions by running this command:

qemush help