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 * python-distro-info
  62
  63 Running vmdebootstrap from git
  64 ------------------------------
  65
  66 $ sudo PYTHONPATH=. ./bin/vmdebootstrap
  67
  68 This has changed slightly with version 1.0 with the need for
  69 PYTHONPATH to reference the module approach for support handlers.
  70
  71 pylint
  72 ------
  73
  74 vmdebootstrap uses pylint and contains comments to disable certain
  75 pylint checks in certain areas. pylint compatibility will make it
  76 easier to accept patches, just follow the existing pattern
  77 of pylint usage. pylint is far from perfect but can be helpful.
  78
  79 Testing UEFI support
  80 --------------------
  81
  82 There is EFI firmware available to use with QEMU when testing images
  83 built using the UEFI support, but this software is in Debian non-free
  84 due to patent concerns. If you choose to use it to test UEFI builds,
  85 a secondary change is also needed to symlink the provided OVMF.fd to
  86 the file required by QEMU: bios-256k.bin and then tell QEMU about the
  87 location of this file with the -L option:
  88
  89 $ qemu-system-x86_64 -L /usr/share/ovmf/ -machine accel=kvm \
  90   -m 4096 -smp 2 -drive file=amd64.img,format=raw
  91
  92 Note the use of -drive file=<img>,format=raw which is needed for newer
  93 versions of QEMU.
  94
  95 The vmextract helper
  96 --------------------
  97
  98 Once the image is built, various files can be generated or modified
  99 during the install operations and some of these files can be useful
 100 when testing the image. One example is the initrd built by the process
 101 of installing a Debian kernel. Rather than having to mount the image
 102 and copy the files manually, the vmextract helper can do it for you,
 103 without needing root privileges.
 104
 105 $ /usr/share/vmdebootstrap/vmextract.py --verbose \
 106   --image bbb/bbb-debian-armmp.img --boot \
 107   --path /boot/initrd.img-3.14-2-armmp \
 108   --path /lib/arm-linux-gnueabihf/libresolv.so.2
 109
 110 This uses python-guestfs (a Recommended package for vmdebootstrap) to
 111 prepare a read-only version of the image - in this case with the /boot
 112 partition also mounted - and copies files out into the current working
 113 directory.
 114
 115 Legalese
 116 --------
 117
 118 Copyright 2011-2013  Lars Wirzenius
 119 Copyright 2012  Codethink Limited
 120
 121 This program is free software: you can redistribute it and/or modify
 122 it under the terms of the GNU General Public License as published by
 123 the Free Software Foundation, either version 3 of the License, or
 124 at your option) any later version.
 125
 126 This program is distributed in the hope that it will be useful,
 127 but WITHOUT ANY WARRANTY; without even the implied warranty of
 128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 129 GNU General Public License for more details.
 130
 131 You should have received a copy of the GNU General Public License
 132 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 133