ahurac/qemush
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

README : suppression du wrap dur

Browse source
This commit is contained in:
Ahurac 2024-03-25 18:26:36 +01:00
parent 4446e64adc
commit b356e5d6a5
1 changed files with 20 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
README.md
View file

@ -4,40 +4,28 @@
## How does it work ## How does it work
`qemush` allows to run commands as Unix user `qemu` to manage virtual `qemush` allows to run commands as Unix user `qemu` to manage virtual machines and their disks associated.
machines and their disks associated.
## Why ## Why
`qemush` is **daemonless**: no bloaty long running process is needed for `qemush` is **daemonless**: no bloaty long running process is needed for `qemush` to work.
`qemush` to work.
`qemush` is **lightweight**: it only consists in a shell script to `qemush` is **lightweight**: it only consists in a shell script to automate repeated tasks and force good practices.
automate repeated tasks and force good practices.
`qemush` needs **few dependencies**: see section `qemush` needs **few dependencies**: see section [Dependencies](#dependencies) for details.
[Dependencies](#dependencies) for details.
`qemush` is **hackable**: you can [write your own launching `qemush` is **hackable**: you can [write your own launching scripts](#writing-a-launching-script) to make it work as intended.
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 `qemush` is **easy to setup**: you can make it work in a few steps, see section [Installation instructions](#installation-instructions).
section [Installation instructions](#installation-instructions).
## Good practices? ## Good practices?
Here is a list of good practices forced by `qemush`. Here is a list of good practices forced by `qemush`.
- **Processes running as user `qemu`**: members of group `qemu` can manage - **Processes running as user `qemu`**: members of group `qemu` can manage the same virtual machines
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
- **Modularization**: `qemush` launching scripts are intended to be - **Copy-on-write**: images are formatted using `qcow2` to use less space on disk
stackable to reuse common `qemu` parameters in all virtual machines - **Process detachment**: you can log out and have your virtual machines still running, control them via Unix sockets
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` ? ## 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. 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 All dependencies are common packages for a distribution, you'll be able to grab them from your favorite packages sources.
grab them from your favorite packages sources.
- `qemu` - this is literally a QEMU wrapper so there's a chance you'll - `qemu` - this is literally a QEMU wrapper so there's a chance you'll need it
need it
- A POSIX compliant shell - `bash` (POSIX mode), `*ash`, `*ksh` are POSIX shells - A POSIX compliant shell - `bash` (POSIX mode), `*ash`, `*ksh` are POSIX shells
- `coreutils` - used for basic OS operations - `coreutils` - used for basic OS operations
- `sudo` - execute commands as `qemu` - `sudo` - execute commands as `qemu`
@ -62,9 +48,7 @@ need it
### QEMU user and group ### QEMU user and group
`qemush` acts as Unix user `qemu` to manage virtual machines. You need to `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:
create a system user `qemu` that cannot login, with any home directory,
in an Unix group of the same name. Example:
```sh ```sh
# Example if the qemu user doesn't exist # 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 useradd -r -s /bin/nologin qemu
``` ```
For ease of use, you need to grant every user in the `qemu` group via 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.
`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) ### Via `Makefile` (recommended)
Just run the following command at the root of this repository to install Just run the following command at the root of this repository to install `qemush` (previous step is **mandatory**) :
`qemush` (previous step is **mandatory**) :
```sh ```sh
make make
@ -87,14 +68,12 @@ make
> And what if I don't want to bindly run this obscure `Makefile` ??? > 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 You'd be right. The next section is the exhaustive list of steps handled by the `Makefile` for the installation process.
by the `Makefile` for the installation process.
### Manual installation (what does the `Makefile` do) ### Manual installation (what does the `Makefile` do)
- Create `disks`, `launchers` and `bin` directories in `~qemu` - Create `disks`, `launchers` and `bin` directories in `~qemu`
- Copy `qemush` scripts parts from `qemu/bin` in `~qemu/bin` with mode - Copy `qemush` scripts parts from `qemu/bin` in `~qemu/bin` with mode `740`
`740`
- Compile C programs from `src` 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`
- Copy `bin/qemush` to `/usr/local/bin/qemush` with mode `755` - Copy `bin/qemush` to `/usr/local/bin/qemush` with mode `755`
@ -103,11 +82,9 @@ by the `Makefile` for the installation process.
### Writing a launching script ### Writing a launching script
The default text editor used by `qemush` is `nvim`, but it can be The default text editor used by `qemush` is `nvim`, but it can be overriden by the `EDITOR` environment variable.
overriden by the `EDITOR` environment variable.
Run the following command to start editing a launching script by the name Run the following command to start editing a launching script by the name of your choice:
of your choice:
```sh ```sh
qemush edit "$name" qemush edit "$name"
@ -117,8 +94,7 @@ Example scripts are available in this repo's `qemu/launchers` folder.
### Launching a virtual machine ### Launching a virtual machine
Virtual machines are identified by the name of their launching scripts. Virtual machines are identified by the name of their launching scripts. You can launch any machine with the following command:
You can launch any machine with the following command:
```sh ```sh
qemush start "$name" qemush start "$name"