1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
---
title: Building Debian system images with vmdb2
author: Lars Wirzenius
date: work-in-progress
...
Introduction
=============================================================================
vmdb2 builds disk images with Debian installed. The images can be used
for virtual machines, or can be written to USB flash memory devices,
and hardware computers can be booted off them. It is a successor of
the vmdebootstrap program, written by the same author, to fix a number
of architectural problems with the old program. The new program is not
compatible with the old one; that would've required keeping the
problems, as well.
This manual is published as HTML at
<https://vmdb2-manual.liw.fi/> and as a PDF at
<https://vmdb2-manual.liw.fi/vmdb2.pdf>.
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 and improving existing tools. He admits this is a
character flaw.
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
=============================================================================
You can get vmdb2 by getting the source code from git:
git clone git://git.liw.fi/vmdb2
You can then run it from the source tree:
sudo /path/to/vmdb2/vmdb2 ...
In Debian 10 ("buster") and its derivatives, you can also install the
vmdb2 package:
apt install vmdb2
For any other systems, we have no instructions. If you figure it out,
please tell us how.
Getting started
=============================================================================
vmdb2 works by reading specification file with instructions for how an
image should be built, using YAML syntax, and following those
instructions. A minimal specification file example:
steps:
- mkimg: "{{ output }}"
size: 4G
- mklabel: gpt
device: "{{ output }}"
- mkpart: primary
device: "{{ output }}"
start: 0%
end: 100%
tag: root
- kpartx: "{{ output }}"
- mkfs: ext4
partition: root
- mount: root
- debootstrap: buster
mirror: http://deb.debian.org/debian
target: root
- apt: install
packages:
- linux-image-amd64
tag: root
- grub: bios
tag: root
console: serial
The above creates a four gigabyte file, creates a GPT partition table,
a single partition, with an ext4 filesystem, and installs Debian release
buster onto it. It also installs a kernel, and a boot loader.
To use this, save the specification into `test.vmdb`, and run the
following command:
sudo vmdb2 --output test.img --verbose test.vmdb
Alternatively the specification can be passed in via stdin by setting the
file name to `-`, lke so:
cat test.vmdb | sudo vmdb2 --output test.img --verbose -
This will take a long time, mostly at the `debootstrap` step.
Unpartitioned images
-----------------------------------------------------------------------------
At this time, vmdb2 does not support building unpartitioned images, or
images without a partition table. Such support may be added later. If
this would be useful, do tell the authors.
Tags
-----------------------------------------------------------------------------
Instead of device filenames, vmdb2 steps refer to block devices inside
the image, and their mount points, by symbolic names called tags. Tags
are any names that the user likes, and vmdb2 does not assign meaning
to them. They're just strings.
Jinja2 expansion
-----------------------------------------------------------------------------
To refer to the filename specified with the `--output` or `--image`
command line options, you can use [Jinja2](http://jinja.pocoo.org/)
templating. The variables `output` and `image` can be used.
- mkimg: "{{ output }}"
- mklabel: "{{ image }}"
The difference is that `--output` creates a new file, or truncates an
existing file, whereas `--images` requires the file to already exist.
The former is better for image file, the latter for real block
devices.
Speed up image creation by caching the root filesystem
-----------------------------------------------------------------------------
Building an image can take several minutes, and that's with fast
access to a Debian mirror and an SSD. The slowest part is typically
running debootstrap, and that always results in the same output, for a
given Debian release. This means its easy to cache.
vmdb2 has the two actions `cache-roots` and `unpack-rootfs` and the
command line option `--rootfs-tarball` to allow user to cache. The
user uses the option to name a file. `cache-rootfs` takes the root
filesystem and stores it into the file as a compress tar archive
("tarball"). `unpack-rootfs` unpacks the tarball. This allows vmdb2 to
skip running debootstrap needlessly.
The specify which steps should be skipped, the `unless` field can be
used: `unpack-rootfs` sets the `rootfs_unpacked` flag if it actually
unpacks a tarball, and `unless` allows checking for that flag. If the
tarball doesn't exist, the flag is not set.
- unpack-rootfs: root
- debootstrap: buster
target: root
unless: rootfs_unpacked
- cache-rootfs: root
unless: rootfs_unpacked
If the tarball exists, it is unpacked, and the `debootstrap` and
`cache-rootfs` steps are skipped.
It's possible to have any number of steps between the unpack and the
cache steps. However, note that if you change anything within those
steps, or time passes and you want to include the new packages that
have made it into Debian, you need to delete the tarball so it is run
again.
TODO: unless, caching, tags, jinja2
Step reference manual
=============================================================================
|
