116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# `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](#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 can compile it and add
|
|
it to your `PATH` if you need to allocate ports to protocols like SPICE in
|
|
your launching scripts (example in `qemu/bin/*-spice`). Its source is in
|
|
`src` folder of this repository.
|
|
|
|
## 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
|
|
```
|