]> git.siccegge.de Git - forks/vmdebootstrap.git/blob - README
Improve wandboard support
[forks/vmdebootstrap.git] / README
1 README for vmdebootstrap
2 ========================
3
4 `debootstrap` installs a basic Debian system into a directory, for use with
5 `chroot`(8). `vmdebootstrap` is a wrapper around it to install Debian into
6 a disk image, which can be used with a virtual machine (such as KVM).
7
8 See the manual page and `vmdebootstrap --help` for details on how to
9 use the program. The manual page has an example.
10
11 Limitations
12 -----------
13
14 `vmdebootstrap` is aimed principally at creating virtual machines, not
15 installers or prebuilt installation images. It is possible to create
16 prebuilt installation images for some devices but this depends on the
17 specific device. (A 'prebuilt installation image' is a single image file
18 which can be written to physical media in a single operation and which
19 allows the device to boot directly into a fully installed system - in a
20 similar way to how a virtual machine would behave.)
21
22 * `vmdebootstrap` assumes that all operations take place on a local image
23 file, not a physical block device / removable media.
24 * `vmdebootstrap` is intended to be used with tools like `qemu` on the
25 command line to launch a new virtual machine. Not all devices have
26 virtualisation support in hardware.
27
28 This has implications for `u-boot` support in some cases. If the device
29 can support reading the bootloader from a known partition, like the
30 Beaglebone-black, then `vmdebootstrap` can provide space for the bootloader
31 and the image will work as a prebuilt installation image. If the device
32 expects that the bootloader exists at a specific offset and therefore
33 requires that the bootloader is written as an image not as a binary which
34 can be copied into an existing partition, `vmdebootstrap` is unable to
35 include that bootloader image into the virtual machine image.
36
37 It is possible to wrap `vmdebootstrap` in such a way as to prepare a
38 *physical block device* with a bootloader image and then deploy the
39 bootstrap on top. However, this does require physical media to be
40 inserted and removed each time the wrapper is executed. Once you have
41 working media, an image can be created using ``dd`` to read back from
42 the media to an image file, allowing other media to be written with a
43 single image file. To do this, use the `--tarball` option to `vmdebootstrap`
44 instead of the `--image`` option. Then setup the physical media and
45 bootloader image as required for the device, redefine the partitions to
46 make space for the rootfs, create a filesystem on the physical media and
47 unpack the `vmdebootstrap` tarball onto that filesystem.
48
49 What you need
50 -------------
51
52 In order to use vmdebootstrap, you'll need a few things:
53
54 * debootstrap
55 * extlinux
56 * qemu-img (in the qemu-utils package in Debian)
57 * parted
58 * mbr
59 * kpartx
60 * python-cliapp (see http://liw.fi/cliapp/)
61
62
63 Legalese
64 --------
65
66 Copyright 2011-2013 Lars Wirzenius
67 Copyright 2012 Codethink Limited
68
69 This program is free software: you can redistribute it and/or modify
70 it under the terms of the GNU General Public License as published by
71 the Free Software Foundation, either version 3 of the License, or
72 at your option) any later version.
73
74 This program is distributed in the hope that it will be useful,
75 but WITHOUT ANY WARRANTY; without even the implied warranty of
76 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
77 GNU General Public License for more details.
78
79 You should have received a copy of the GNU General Public License
80 along with this program. If not, see <http://www.gnu.org/licenses/>.
81