README 6.47 KB
Newer Older
1
README for vmdb2 or vmdebootstrap 2nd generation     ; -*- mode: markdown;-*-
2 3
=============================================================================

4 5 6 7
[vmdb2][] is a program for producing a disk image with Debian
installed.

[vmdb2]: https://vmdb2.liw.fi/
Lars Wirzenius's avatar
Lars Wirzenius committed
8 9 10 11

Introduction
-----------------------------------------------------------------------------

Lars Wirzenius's avatar
Lars Wirzenius committed
12 13
[vmdebootstrap][] installs Debian onto a disk image. It is like the
[debootstrap][] tool, except the end result is a bootable disk image,
14 15 16
not a directory. vmdebootstrap takes care of creating partitions, and
filesystems, and allows some more customization than the older
vmdebootstrap does.
Lars Wirzenius's avatar
Lars Wirzenius committed
17

Lars Wirzenius's avatar
Lars Wirzenius committed
18
vmdebootstrap is also a messy pile of kludge, and rather inflexible.
Lars Wirzenius's avatar
Lars Wirzenius committed
19 20
vmdb2 is a re-implementation from scratch, without a need for
backwards compatibility. It aims to provide more flexibility than
Lars Wirzenius's avatar
Lars Wirzenius committed
21
vmdebootstrap, without becoming anywhere near as complicated. Think of
Lars Wirzenius's avatar
Lars Wirzenius committed
22
vmdb2 as "vmdebootstrap the second generation". The name has changed
Stuart Prescott's avatar
Stuart Prescott committed
23
to allow the two tools to installable in parallel, which is important
24
for a transition period.
Lars Wirzenius's avatar
Lars Wirzenius committed
25 26

The main user-visible difference between vmdebootstrap and vmdb2 is
Lars Wirzenius's avatar
Lars Wirzenius committed
27 28 29
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's avatar
Lars Wirzenius committed
30 31

(Lars Wirzenius wrote both vmdebootstrap and vmdb2 and is entitled to
Lars Wirzenius's avatar
Lars Wirzenius committed
32 33
sneer at his younger self. It's his way of dealing with the mountain
of guilt of making something as awful as vmdebootstrap.)
Lars Wirzenius's avatar
Lars Wirzenius committed
34 35 36 37

[vmdebootstrap]: http://liw.fi/vmdebootstrap/
[debootstrap]: https://packages.debian.org/unstable/debootstrap

38

39 40 41
Getting vmdb2
-----------------------------------------------------------------------------

42
vmdb2 source code is available via git:
43 44 45

* <http://git.liw.fi/vmdb2>

46 47 48
It used to be on GitHub as well, but was withdrawn from there due to
GitHub being a proprietary service and a dislike of its development
workflow.
49

50 51 52 53 54 55 56
Requirements:

The following tools are used by vmdb2 (Debian package names in brackets).

* `kpartx` [kpartx, mkpart command]
* `parted` [`parted`, mklabel command]
* `qemu-img` [`qemu-utils`, mkimg command]
57
* `qemu-user-static` [`qemu-user-static`, qemu-debootstrap command]
58 59 60

The following Python modules are used by vmdb2 (Debian package names in brackets).

61 62 63
* cliapp [`python3-cliapp`]
* jinja2 [`python3-jinja2`]
* yaml [`python3-yaml`]
64

65

66 67 68 69 70 71
Dependencies for smoke.sh
-----------------------------------------------------------------------------

You probably need the following installed to run the smoke test:

- git
72 73 74 75
- python3-coverage-test-runner
- python3-cliapp
- python3-jinja2
- pylint3
76 77 78 79 80 81 82 83 84
- cmdtest 0.31 or later
- qemu-utils
- parted
- kpartx
- debootstrap
- expect
- qemu-system


Lars Wirzenius's avatar
Lars Wirzenius committed
85 86 87 88 89 90
Tutorial
-----------------------------------------------------------------------------

To use vmdb2, git clone the source and at the root of the source tree
run the following command:

91
    sudo ./vmdb2 --output simple.img simple.vmdb --log simple.log
Lars Wirzenius's avatar
Lars Wirzenius committed
92 93

`--output simple.img` specifies that the output image is called
94
`simple.img`, the specification is `simple.vmdb` and the log file goes
Lars Wirzenius's avatar
Lars Wirzenius committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120
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)
121
* apt (install packagers in chroot with apt)
Lars Wirzenius's avatar
Lars Wirzenius committed
122 123 124 125 126 127
* 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)

128
See `simple.vmdb` for examples. Note how the file uses Jinja2
Lars Wirzenius's avatar
Lars Wirzenius committed
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
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.


150 151 152 153 154 155 156
Hacking
-----------------------------------------------------------------------------

To run automated tests:

    ./check

Lars Wirzenius's avatar
Lars Wirzenius committed
157 158
You'll need the yarn program (part of the [cmdtest][] package), and
also [CoverageTestRunner][] for running the unit tests.
159 160

[cmdtest]: http://liw.fi/cmdtest/
Lars Wirzenius's avatar
Lars Wirzenius committed
161 162 163
[CoverageTestRunner]: http://liw.fi/coverage-test-runner/


164 165 166 167 168 169 170 171
Contact
-----------------------------------------------------------------------------

To contact Lars, email is best: `liw@liw.fi`.

There is an IRC channel for vmdb2: irc.oftc.net network, `#vmdb2`.


Lars Wirzenius's avatar
Lars Wirzenius committed
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
Legalese
-----------------------------------------------------------------------------

Copyright 2017  Lars Wirzenius

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

=*= License: GPL-3+ =*=