qemush/README.md

136 lines
3.9 KiB
Markdown
Raw Normal View History

# `qemush` - A suckless QEMU wrapper written in shell
2023-12-04 12:00:35 +01:00
2023-12-05 22:24:41 +01:00
[![Please don't upload to GitHub](https://nogithub.codeberg.page/badge.svg)](https://nogithub.codeberg.page)
2023-12-04 12:00:35 +01:00
## How does it work
2023-12-04 16:21:53 +01:00
`qemush` allows to run commands as Unix user `qemu` to manage virtual
machines and their disks associated.
2023-12-04 12:00:35 +01:00
## Why
`qemush` is **daemonless**: no bloaty long running process is needed for
2023-12-04 16:21:53 +01:00
`qemush` to work.
`qemush` is **lightweight**: it only consists in a shell script to
2023-12-04 16:21:53 +01:00
automate repeated tasks and force good practices.
`qemush` needs **few dependencies**: see section
2023-12-04 16:21:53 +01:00
[Dependencies](#dependencies) for details.
`qemush` is **hackable**: you can [write your own launching
2023-12-04 22:45:12 +01:00
scripts](#writing-a-launching-script) to make it work as intended.
2023-12-04 16:21:53 +01:00
`qemush` is **easy to setup**: you can make it work in a few steps, see
2023-12-04 16:21:53 +01:00
section [Installation instructions](#installation-instructions).
2023-12-04 12:00:35 +01:00
## 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
2024-01-21 00:23:33 +01:00
keep track of them
- **Copy-on-write**: images are formatted using `qcow2` to use less space
on disk
2024-01-22 23:57:00 +01:00
- **Process detachment**: you can log out and have your virtual machines
still running, control them via Unix sockets
2023-12-04 12:00:35 +01:00
## Dependencies
All dependencies are common packages for a distribution, you'll be able to
grab them from your favorite packages sources.
2023-12-04 16:21:53 +01:00
- `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`
2024-01-22 23:38:39 +01:00
- `socat` - monitor machines via Unix sockets
- `diskpath` and `sockpath` - see [Installation
instructions](#installation-instructions)
2023-12-04 22:49:38 +01:00
- any text editor - used for builtin function to edit launching scripts
2023-12-04 12:00:35 +01:00
## Installation instructions
2023-12-04 16:21:53 +01:00
### 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:
2023-12-04 16:21:53 +01:00
```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.
### Via `Makefile` (recommended)
2023-12-04 16:21:53 +01:00
Just run the following command at the root of this repository to install
`qemush` (previous step is **mandatory**) :
```sh
make
```
> And what if I don't want to bindly run this obscure `Makefile` ???
You'd be right. The next section is the exhaustive list of steps handled
by the `Makefile` for the installation process.
### Manual installation (what does the `Makefile` do)
- Create `disks`, `launchers` and `bin` directories in `~qemu`
- Copy `qemush` scripts parts from `qemu/bin` in `~qemu/bin` with mode
`740`
- Compile C programs from `src` in `~qemu/bin` with mode `740`
- Copy the default launching scripts to `~qemu/launchers` with mode `740`
- Copy `bin/qemush` to `/usr/local/bin/qemush` with mode `755`
2023-12-04 16:21:53 +01:00
## 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:
2023-12-04 16:21:53 +01:00
```sh
qemush edit "$name"
```
2024-01-23 00:01:05 +01:00
Example scripts are available in this repo's `qemu/launchers` folder.
2023-12-04 16:21:53 +01:00
### Launching a virtual machine
Virtual machines are identified by the name of their launching scripts.
You can launch any machine with the following command:
2023-12-04 16:21:53 +01:00
```sh
qemush start "$name"
```
2023-12-04 22:43:58 +01:00
You can also list all available virtual machines by running this command:
2023-12-04 22:43:58 +01:00
```sh
qemush ls
```
2023-12-06 11:25:39 +01:00
### Other uses
You can show the full list of possible actions by running this command:
```sh
qemush help
```