Add: some more text to the manual

1 files changed, 155 insertions, 6 deletions

diff --git a/doc/en/000.mdwn b/doc/en/000.mdwn
index e4bc243..96cab72 100644
--- a/doc/en/000.mdwn
+++ b/doc/en/000.mdwn
@@ -1,19 +1,47 @@
 ---
-title: Building system images with vmdb2
+title: Building Debian system images with vmdb2
 author: Lars Wirzenius
 date: work-in-progress
 ...
 
 # Introduction
 
-- what is vmdb2 for?
-- how does it differ from other image building tools?
-- especially vmdebootstrap
+`vmdb2` installes [Debian][] **system images**. The image may be in a
+disk image file or a block device, such as a real hard disk, a
+partition, a logical volume, or similar.
+
+Other similar software exists, such as `vmdebootstrap`, an earlier
+attempt by the same author.
+
+[Debian]: https://www.debian.org
+
+## Why vmdb2 given vmdebootstrap already existed
+
+`vmdebootstrap` was the first attempt by Lars Wirzenius to write a
+tool to build system images. It turned out to not be well designed.
+Specifically, it was not easily extensible to be as flexible as a tool
+of this sort should be.
+
+## Why vmdb2 given other tools already exist
+
+Lars likes to write tools for himself and had some free time. He
+sometimes prefers to write his own tools rather than spend time and
+energy evaluating existing tools.
+
+Also, he felt ashamed of how messy `vmdebootstrap` turned out to be.
+
+If nobody else likes `vmdb2`, that just means Lars had some fun on his
+own.
 
 # Installation
 
-- .deb
-- git clone and run from source tree
+You can install `vmdb2` from a .deb package on [code.liw.fi/debian][],
+Lars's personal APT repository. You can also get the source code with
+git from [vmdb2 git][], and run `./vmdb2` from the source tree: the
+program doesn't need to be installed anywhere.
+
+[code.liw.fi/debian]: http://code.liw.fi/debian/
+[vmdb2 git]: http://git.liw.fi/vmdb2
 
 # Quick start
 
@@ -21,6 +49,127 @@ date: work-in-progress
 - command to run vmdb2 and produce an image
 - command to run vm using image
 
+`vmdb2` requires an **image specification file** as input. Here is a
+small example:
+
+~~~
+steps:
+  - mkimg: "{{ output }}"
+    size: 4G
+
+  - mklabel: msdos
+    device: "{{ output }}"
+
+  - mkpart: primary
+    device: "{{ output }}"
+    start: 0%
+    end: 100%
+    part-tag: root-part
+
+  - mkfs: ext4
+    partition: root-part
+
+  - mount: root-part
+    fs-tag: root-fs
+
+  - unpack-rootfs: root-fs
+
+  - debootstrap: stretch
+    mirror: http://http.debian.net/debian
+    target: root-fs
+    unless: rootfs_unpacked
+
+  - apt: linux-image-amd64
+    fs-tag: root-fs
+    unless: rootfs_unpacked
+
+  - cache-rootfs: root-fs
+    unless: rootfs_unpacked
+
+  - chroot: root-fs
+    shell: |
+      apt -y install python
+
+  - shell: |
+      printf '[pc]\n%s hostname=pc\n' "$ROOT" > pc.inventory
+      ansible-playbook -i pc.inventory -c chroot pc.yml
+    root-fs: root-fs
+
+  - grub: bios
+    root-fs: root-fs
+    root-part: root-part
+    device: "{{ output }}"
+~~~
+
+It's a bit of a mouthful, and needs to be unpacked to be understood,
+though every part is really quite simple. First of all, the file is in
+[YAML][] format, which is a standard format not specific to `vmdb2` at
+all. The top level is the `steps` key, which has as its value a list
+of **steps**. The steps instruct `vmdb2` what it should do, and in
+which order, to build the image.
+
+[YAML]: https://en.wikipedia.org/wiki/YAML
+
+The previous `vmdebootstrap` program hard coded the sequence of steps
+to build an image, and provided command line options to vary the steps
+in minor ways. The `vmdb2` approach gives more flexibility with less
+complexity, and is more easily testable.
+
+Each step consists of a set of key/value pairs. For example, the first
+step creates a disk image file:
+
+      - mkimg: "{{ output }}"
+        size: 4G
+
+`mkimg` identifies the step. The value is a [Jinja2][] template. In
+this case, the template expands to the value of the `output` variable,
+which contains the value of the `--output` command line option,
+meaning the name of the output file. Jinja2 is a powerful templating
+engine, and `vmdb2` uses it, amongst other reasons, to avoid
+implementing a custom language for using variables.
+
+[Jinja2]: http://jinja.pocoo.org/
+
+The `size` key specifies the size of the disk image file that gets
+created. `vmdb2` uses the `qemu-img` tool to create the image file and
+the size value can be anything that `qemu-img` accepts.
+
+The rest of the steps create a partition table (`mklabel`), a
+partition (`mkpart`), and a filesystem (`mkfs`), as well as mount the
+filesystem as the root filesystem. Partitions and mount points get
+assigned **tags**, which allow later steps to refer to them, without
+having to hardcode a directory or device name. Those tend to be a bit
+random and vary from run to run, so hardcoding wouldn't work anyway.
+
+The `debootstrap` step runs `debootstrap`, i.e., actually installs
+Debian into the image. This can take a while, so `vmdb2` provides a
+caching mechanism, to speed up iterations (unlike you, Lars never gets
+things right the first one). This caching is done by using the
+`--rootfs-tarball` command line option and the `unpack-rootfs` step,
+and the `unless: rootfs_unpacked` key/value pair in selected steps.
+Caching works like this: the filename given to `--rootfs-tarball` is
+the cache filename. The `unpack-rootfs` looks for the cache file; if
+it exists, it unpacks it, and sets the `rootfs_unpacked` variable to a
+Boolean true value. Any other step can be tagged with `unless`, and if
+the named value is true, the step is skipped. Thus, if the cache file
+exists, the `debootstrap` step is skipped. Finally, the `cache-rootfs`
+step creates a compressed tar archive of the filesystem, and that step
+is also skipped if the `unless` tells `vmdb2` to skip it.
+
+At the end, the `grub` step installs the GRUB bootloader. The example
+installs a version compatible with traditional PC BIOS systems, which
+works fine with virtual machine providers. A variabnt to support UEFI
+systems is also available.
+
+To run `vmdb2` with the above example, run a command like this:
+
+    vmdb2 pc.vmdb --output foo.img --rootfs-tarball foo.tar.gz
+
+This tells `vmdb2` to read the image specification file from
+`pc.vmdb`, place the output in `foo.img` and use `foo.tar.gz` as the
+cache tar archive.
+
+
 # Configuration
 
 - command line options, list them and give summary of use