What is debvm?
==============

The purpose of this tool is creating and running simple virtual machines based
on Debian releases. A typical application is testing. Consequently, this has
been designed to work without root privileges[^1]. Rather than do thing itself,
it builds primarily on
[mmdebstrap](https://gitlab.mister-muffin.de/josch/mmdebstrap/) and
[qemu](http://www.qemu.org/).

How do you use it?
==================

The first tool is `debvm-create`. It creates a rootfs ext4 raw filesystem
image. This image has configurable architecture, hostname, root's ssh key,
Debian mirror, and release as well as image size and included packages. In
essence, it is a wrapper constructing a complex `mmdebstrap` invocation.

Given such an image, `debvm-run` can be used to run it. It extracts the kernel
and initrd from the filesystem image and constructs a suitable `qemu`
invocation.

What do I need?
===============

A regular user account[^1] suffices. The following Debian packages should be
installed:
 * `arch-test` (when running foreign images)
 * `e2fsprogs`
 * `genext2fs` (used by `mmdebstrap`)
 * `mmdebstrap`
 * `qemu-system-something`
 * `qemu-user-static` (when creating foreign images)

What is this image format precisely?
====================================

The image is a sparse ext4 file system image. It contains the root filesystem
of a (Debian) installation including an init system and a kernel. There is no
partition table or bootloader. The following paths are assumed inside:
 * `/bin/true` is used to detect the architecture of an image
 * `/vmlinuz` must be a symbolic link pointing to a regular file containing
   the kernel.
 * `/initrd.img` must be a symbolic link pointing to a regular file containing
   the initrd image.

License
=======

The debvm tools are licensed under the MIT license.

Contributors
============

 * Helmut Grohne (main author)
 * Johannes Schauer Marin Rodrigues (main author of `mmdebstrap`)

[^1] This technically is a lie. It employs user namespaces and thus requires
     the setuid binary `newuidmap` as well as a suitable subuid allocation.