diff options
Diffstat (limited to 'man/vmdebootstrap.rst')
| -rw-r--r-- | man/vmdebootstrap.rst | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/man/vmdebootstrap.rst b/man/vmdebootstrap.rst new file mode 100644 index 0000000..09356c5 --- /dev/null +++ b/man/vmdebootstrap.rst @@ -0,0 +1,190 @@ +VMDebootstrap +############# + +Purpose +******* +vmdebootstrap is a helper to install basic Debian system into virtual +disk image. It wraps **debootstrap**. You need to run :file:`vmdebootstrap` +as root. If the ``--verbose`` option is not used, no output will be +sent to the command line. If the ``--log`` option is not used, no +output will be sent to any log files either. + +To use the image, you probably want to create a virtual machine using +your preferred virtualization technology, such as file:`kvm` or +file:`qemu`. Configure the virtual machine to use the image you've +created. Then start the virtual machine and log into it via its console +to configure it. The image has an empty root password and will not have +networking configured by default. Set the root password before you +configure networking. + +Networking +********** + +The ``--enable-networking`` option uses the :file:`/etc/network/interfaces.d/` +source directory, with the default settings for ``lo`` and ``eth0`` +being added to :file:`/etc/network/interfaces.d/setup`. Other networking +configuration can be specified using a customisation script. +Localhost settings would be:: + + auto lo + iface lo inet loopback + +If ``--enable-dhcp`` is specified, these settings are also included +into :file:`/etc/network/interfaces.d/setup`:: + + auto eth0 + iface eth0 inet dhcp + +Bootloaders +*********** + +Unless the ``--no-extlinux`` or ``--grub`` options are specified, the +image will use ``extlinux`` as a boot loader. ``bootsize`` is not +recommended when using ``extlinux`` - use ``grub`` instead. + +Versions of grub2 in wheezy +=========================== + +Grub2 in wheezy can fail to install in the VM, at which point +:file:`vmdebootstrap` will fall back to ``extlinux``. It may still be +possible to complete the installation of ``grub2`` after booting the +VM as the problem may be related to the need to use loopback devices +during the ``grub-install`` operation. Details of the error will appear +in the vmdebootstrap log file, if enabled with the ``--log`` option. + +.. note:: **grub-legacy** is not supported. + +:file:`vmdebootstrap` also supports **EFI**. + +Use ``--use-uefi`` to use ``grub-efi`` instead of ``grub-pc``. If the +default 5Mb is not enough space, use the ``--esp-size`` option to +specify a different size for the EFI partition. Registered firmware is +not supported as it would need to be done after boot. If the system you +are creating is for more than just a VM or live image, you will likely +need a larger ESP, up to 500Mb. + +UBoot +===== + +UBoot needs manual configuration via the customisation hook scripts, +typically support requires adding ``u-boot`` using ``--package`` and then +copying or manipulating the relevant ``u-boot`` files in the customisation +script. Examples are included for beaglebone-black. + +Installation images and virtual machines +**************************************** + +:file:`vmdebootstrap`` is aimed principally at creating virtual machines, +not installers or prebuilt installation images. It is possible to create +prebuilt installation images for some devices but this depends on the +specific device. (A 'prebuilt installation image' is a single image file +which can be written to physical media in a single operation and which +allows the device to boot directly into a fully installed system - in +a similar way to how a virtual machine would behave.) + +:file:`vmdebootstrap` assumes that all operations take place on a local +image file, not a physical block device / removable media. + +:file:`vmdebootstrap` is intended to be used with tools like ``qemu`` on +the command line to launch a new virtual machine. Not all devices have +virtualisation support in hardware. + +This has implications for file:`u-boot` support in some cases. If the +device can support reading the bootloader from a known partition, like +the beaglebone-black, then :file:`vmdebootstrap` can provide space for +the bootloader and the image will work as a prebuilt installation image. +If the device expects that the bootloader exists at a specific offset +and therefore requires that the bootloader is written as an image not +as a binary which can be copied into an existing partition, +:file:vmdebootstrap` is unable to include that bootloader image into +the virtual machine image. + +The beagleboneblack.sh script in the examples/ directory provides a worked +example to create a prebuilt installation image. However, the beagleboneblack +itself does not support virtualisation in hardware, so is unable to launch +a virtual machine. Other devices, like the Cubietruck or Wandboard need +:file:`u-boot` at a predefined offset but can launch a virtual machine +using ``qemu``, so the cubietruck and wandboard6q scripts in the +examples/ directory relate to building images for virtual machines once +the device is already installed and booted into a suitable kernel. + +It is possible to wrap :file:`vmdebootstrap` in such a way as to prepare +a physical block device with a bootloader image and then deploy the +bootstrap on top. However, this does require physical media to be +inserted and removed each time the wrapper is executed. To do this, use +the ``--tarball`` option instead of the ``--image`` option. Then setup +the physical media and bootloader image manually, as required for the +device, redefine the partitions to make space for the rootfs, create a +filesystem on the physical media and unpack the :file:`vmdebootstrap` +tarball onto that filesystem. Once you have working media, an image can be +created using dd to read back from the media to an image file, allowing +other media to be written with a single image file. + +Example +******* + +To create an image for the stable release of Debian:: + + sudo vmdebootstrap --image test.img --size 1g \\ + --log test.log --log-level debug --verbose \\ + --mirror http://mirror.lan/debian/ + +To run the test image, make sure it is writeable. Use the ``--owner`` +option to set mode 0644 for the specified user or use chmod manually:: + + sudo chmod a+w ./test.img + +Execute using qemu, e.g. on amd64 using qemu-system-x86_64:: + + qemu-system-x86_64 -drive format=raw,file=./test.img + +(This loads the image in a new window.) Note the use of ``-drive +file=<img>,format=raw`` which is needed for newer versions of QEMU. + +There is EFI firmware available to use with QEMU when testing images built +using the UEFI support, but this software is in Debian non-free due to patent +concerns. If you choose to install ``ovmf`` to test UEFI builds, a +secondary change is also needed to symlink the provided ``OVMF.fd`` to +the file required by QEMU: ``bios-256k.bin`` and then tell QEMU about +the location of this file with the -L option:: + + $ qemu-system-x86_64 -L /usr/share/ovmf/ -machine accel=kvm \\ + -m 4096 -smp 2 -drive format=raw,file=test.img + +For further examples, including u-boot support for beaglebone-black, +see ``/usr/share/vmdebootstrap/examples`` + +Notes +***** + +If you get problems with the bootstrap process, run a similar bootstrap +call directly and chroot into the directory to investigate the failure. +The actual debootstrap call is part of the vmdebootstrap logfile. The +debootstrap logfile, if any, will be copied into your current working +directory on error. + +:file:`debootstrap` will download all the apt archive files into the apt cache and does not +remove them before starting the configuration of the packages. This can +mean that debootstrap can fail due to a lack of space on the device if +the VM size is small. vmdebootstrap cleans up the apt cache once debootstrap +has finished but this doesn't help if the package unpack or configuration +steps use up all of the space in the meantime. Avoid this problem by +specifying a larger size for the image. + +.. note:: if you are also using a separate /boot partition in your options to + :file:`vmdebootstrap` it may well be the boot partition which needs + to be enlarged rather than the entire image. + +It is advisable to change the mirror in the example scripts to a mirror +closer to your location, particularly if you need to do repeated builds. +Use the --apt-mirror option to specify the apt mirror to be used inside +the image, after boot. + +There are two types of examples for ARM devices available with +:file:`vmdebootstrap`: prebuilt installation images (like the beaglebone-black) and virtual +machine images (cubietruck and wandboard). ARM devices which do not +support hypervisor mode and which also rely on the bootloader being at +a specific offset instead of using a normal partition will +**not** be supportable by vmdebootstrap. Similarly, devices which support +hypervisor will only be supported using virtual machine images, unless +the bootloader can be executed from a normal partition. |