4.3 KiB
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 groupqemu
can manage the same virtual machines - Modularization:
qemush
launching scripts are intended to be stackable to reuse commonqemu
parameters in all virtual machines needing them - Process supervision:
qemush
usesscreen
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 itbash
- theqemush
interpretercoreutils
- used for basic OS operationssudo
- execute commands asqemu
screen
- for process supervisionsource-highlight
- for syntax highlighting when displaying launching scriptsdiskpath
- see Installation instructions Addqemush
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