initial checkin

1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..63a2c0f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+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.