diff options
author | Lars Wirzenius <liw@liw.fi> | 2017-03-29 13:54:56 +0300 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2017-03-29 13:54:56 +0300 |
commit | 786c1c7f5d00dd4bd9541f87358005df066dc7b7 (patch) | |
tree | bb2f670f780943a2248bcf7dfda1f2fa1589dcf5 | |
parent | 3d884fa36487e5aecf6811138744b720b22c9f76 (diff) | |
download | vmdb2-786c1c7f5d00dd4bd9541f87358005df066dc7b7.tar.gz |
Update README
-rw-r--r-- | README | 89 |
1 files changed, 77 insertions, 12 deletions
@@ -6,32 +6,97 @@ vmdb2 is a program for producing a disk image with Debian installed. Introduction ----------------------------------------------------------------------------- -[vmdebootstrap][] installs Debian onto a disk, or disk image. It is -like the [debootstrap][] tool, except the end result is a disk or disk -image, not a directory. vmdebootstrap takes care of creating -partitions, and filesystems, and allows some more customization than -vmdebootstrap does. +[vmdebootstrap][] installs Debian onto a disk image. It is like the +[debootstrap][] tool, except the end result is a bootable disk image, +not a directory (FIXME: can't yet install a bootloader). vmdebootstrap +takes care of creating partitions, and filesystems, and allows some +more customization than the older vmdebootstrap does. -vmdebootstrap is also a messy pile of kludge, and not flexible enough. +vmdebootstrap is also a messy pile of kludge, and rather inflexible. vmdb2 is a re-implementation from scratch, without a need for backwards compatibility. It aims to provide more flexibility than -vmdeboostrap, without becoming anywhere near as complicated. Think of +vmdebootstrap, without becoming anywhere near as complicated. Think of vmdb2 as "vmdebootstrap the second generation". The name has changed to allow the two tools to installable in paralllel. The main user-visible difference between vmdebootstrap and vmdb2 is -that the older program provides extensibitlity via a legion of command -line options and the newer program by having the user user a domain -specific language to express what kind of Debian system they want to -create. +that the older program provides extensibility via a legion of command +line options and the newer program by providing a domain specific +language to express what kind of Debian system is to be created. (Lars Wirzenius wrote both vmdebootstrap and vmdb2 and is entitled to -sneer at his younger self.) +sneer at his younger self. It's his way of dealing with the mountain +of guilt of making something as awful as vmdebootstrap.) [vmdebootstrap]: http://liw.fi/vmdebootstrap/ [debootstrap]: https://packages.debian.org/unstable/debootstrap +Tutorial +----------------------------------------------------------------------------- + +To use vmdb2, git clone the source and at the root of the source tree +run the following command: + + sudo ./vmdb2 --output simple.img simple.yaml --log simple.log + +`--output simple.img` specifies that the output image is called +`simple.img`, the specification is `simple.yaml` and the log file goes +to `simple.log`. + + +Plugins and steps +----------------------------------------------------------------------------- + +The `vmdb2` architecture consists of a main program that reads the +input file, finds a matching "step runner" for each step used in the +input file, and then runs the steps in order. If there's a problem, it +runs corresponding "teardown" steps in reverse order of the steps. + +A step might be "mount this filesystem", and the corresponding +teardown is "unmount". + +Steps (and teardowns) are provided by plugins; see the `vmdb/plugins` +directory in the source tree. Steps are intended to be very cohesive +and lowly coupled. They may share some state (such as mounted +filesystems) via the `State` object, but not in any other way. A +plugin may provide multiple steps. + +See the plugin directory for which steps currently exist. A list of +steps that will become incomplete as soon as development continues: + +* chroot (run shell snippet in chroot) +* shell (run shell snippet without chroot) +* debootstrap (run deboostrap) +* kernel (installs kernel) +* mkimg (create disk image) +* mklabel (create partition table on a disk image) +* mkpart (create partition) +* mkfs (create filesystem in a partition) +* mount (mount filesystem, teardown unmounts it automatically) + +See `simple.yaml` for examples. Note how the file uses Jinja2 +templating for value fields to get value of `--output` in the right +places. Also note how creating a partition or mounting a filesystem +assigns a "tag" that can be referenced in steps where the +partition/filesystem is needed, without having to know the actual path +to the device node or mount point. + + +Writing plugins +----------------------------------------------------------------------------- + +More step runners would be good, and will be added based on +actual reported needs by users ("I need to have this to..."), not +speculatively ("This seems like a good idea"). + +To write a plugin, see the existing ones for examples, and put it in +`vmdb/plugins/foo_plugin.py` for some value of `foo`. + +Plugins are meant to be very easy to write. If not, there's probably +something wrong with `vmdb2`. Please raise the issue. + + Hacking ----------------------------------------------------------------------------- |