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
|
---
title: vmdb2 manual
...
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.
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
- mkfs: ext4
partition: root
- mount: root
- debootstrap: stretch
mirror: http://deb.debian.org/debian
target: root
- apt: install
packages:
- linux-image-amd64
tag: root-fs
- grub: bios
tag: root
The above creates a four gigabyte file, creates a GPT partition table,
a single partition, with a filesystem, and installs Debian release
stretch 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 test.vmdb --output test.img --verbose
This will take a long time, mostly at the `debootstrap` step.
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 creasing 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. Thhe
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: stretch
target: root
unless: rootfs-unpacked
- cache-rootfs: root
unless: rootfs-unpacked
If the tarball exists, it's 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 the steps, you need to
delete the tarball to run them.
TODO: unless, caching, tags, jinja2
Step reference manual
=============================================================================
|
