qemush/README.md

# `qemush` - An Unix philosophy respecting QEMU wrapper written in shell

[![Please don't upload to GitHub](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page)

## 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](#dependencies) for details.

`qemush` is **hackable**: you can [write your own launching
scripts](#writing-a-launching-script) to make it work as intended.

`qemush` is **easy to setup**: you can make it work in a few steps, see
section [Installation instructions](#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
- any text editor - used for builtin function to edit launching scripts

## 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:

```sh
# 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.

### 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
:

```sh
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:

```sh
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:

```sh
qemush start "$name"
```

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

```sh
qemush ls
```

### Other uses

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

```sh
qemush help
```