Compare commits
6 commits
c094078f4e
...
c24dbcdabb
Author | SHA1 | Date | |
---|---|---|---|
c24dbcdabb | |||
c114fe0b08 | |||
a6f39f4365 | |||
cb396f723f | |||
b356e5d6a5 | |||
4446e64adc |
2 changed files with 32 additions and 48 deletions
68
README.md
68
README.md
|
@ -4,40 +4,28 @@
|
|||
|
||||
## How does it work
|
||||
|
||||
`qemush` allows to run commands as Unix user `qemu` to manage virtual
|
||||
machines and their disks associated.
|
||||
`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 **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` 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` 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 **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).
|
||||
`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
|
||||
keep track of them
|
||||
- **Copy-on-write**: images are formatted using `qcow2` to use less space
|
||||
on disk
|
||||
- **Process detachment**: you can log out and have your virtual machines
|
||||
still running, control them via Unix sockets
|
||||
- **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 keep track of them
|
||||
- **Copy-on-write**: images are formatted using `qcow2` to use less space on disk
|
||||
- **Process detachment**: you can log out and have your virtual machines still running, control them via Unix sockets
|
||||
|
||||
## Is it better than `libvirt` ?
|
||||
|
||||
|
@ -47,11 +35,9 @@ No. `qemush` and `libvirt` are for different use cases. `qemush` will allow you
|
|||
|
||||
From version 0.9.0, `qemush` is written in pure POSIX shell! The previous dependency on `bash` was removed in consequence.
|
||||
|
||||
All dependencies are common packages for a distribution, you'll be able to
|
||||
grab them from your favorite packages sources.
|
||||
All dependencies are common packages for a distribution, you'll be able to grab them from your favorite packages sources.
|
||||
|
||||
- `qemu` - this is literally a QEMU wrapper so there's a chance you'll
|
||||
need it
|
||||
- `qemu` - this is literally a QEMU wrapper so there's a chance you'll need it
|
||||
- A POSIX compliant shell - `bash` (POSIX mode), `*ash`, `*ksh` are POSIX shells
|
||||
- `coreutils` - used for basic OS operations
|
||||
- `sudo` - execute commands as `qemu`
|
||||
|
@ -62,9 +48,7 @@ need it
|
|||
|
||||
### 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:
|
||||
`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
|
||||
|
@ -72,14 +56,11 @@ in an Unix group of the same name. Example:
|
|||
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.
|
||||
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)
|
||||
|
||||
Just run the following command at the root of this repository to install
|
||||
`qemush` (previous step is **mandatory**) :
|
||||
Just run the following command at the root of this repository to install `qemush` (previous step is **mandatory**) :
|
||||
|
||||
```sh
|
||||
make
|
||||
|
@ -87,27 +68,23 @@ 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.
|
||||
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`
|
||||
- Create `disks`, `launchers`, `shared`, `sockets/monitors`, `socket/spice` 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 the default launching scripts to `~qemu/launchers` with mode `740` ; this is optional but the one called `kvm` is the reference `qemush` launching script!
|
||||
- Copy `bin/qemush` to `/usr/local/bin/qemush` with mode `755`
|
||||
|
||||
## Usage
|
||||
|
||||
### Writing a launching script
|
||||
|
||||
The default text editor used by `qemush` is `nvim`, but it can be
|
||||
overriden by the `EDITOR` environment variable.
|
||||
The default text editor used by `qemush` is `vi`, 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:
|
||||
Run the following command to start editing a launching script by the name of your choice:
|
||||
|
||||
```sh
|
||||
qemush edit "$name"
|
||||
|
@ -117,8 +94,7 @@ Example scripts are available in this repo's `qemu/launchers` 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:
|
||||
Virtual machines are identified by the name of their launching scripts. You can launch any machine with the following command:
|
||||
|
||||
```sh
|
||||
qemush start "$name"
|
||||
|
|
12
bin/qemush
12
bin/qemush
|
@ -23,7 +23,7 @@ perror() {
|
|||
public_help() {
|
||||
name=$(basename "$0")
|
||||
|
||||
exec cat << EOF
|
||||
cat << EOF
|
||||
${name}: usage:
|
||||
${name} running - (default behaviour) list running VMs
|
||||
${name} ls - list available VMs
|
||||
|
@ -53,12 +53,20 @@ error_usage() {
|
|||
|
||||
# Function to start a virtual machine
|
||||
public_start() {
|
||||
if [ "$1" = -f ] || [ "$1" = --foreground ]; then
|
||||
daemonize=
|
||||
else
|
||||
daemonize=-daemonize
|
||||
fi
|
||||
|
||||
while echo "$1" | grep -q '^-'; do shift; done;
|
||||
|
||||
export QEMUSH_NAME="$1"
|
||||
|
||||
set -- "$@" \
|
||||
-name "$QEMUSH_NAME" \
|
||||
-monitor "unix:$(pathof socket),server,nowait" \
|
||||
-daemonize
|
||||
$daemonize
|
||||
|
||||
if ! "$@"; then
|
||||
perror "error launching virtual machine \"${QEMUSH_NAME}\""
|
||||
|
|
Loading…
Reference in a new issue