X-Git-Url: https://git.siccegge.de//index.cgi?p=forks%2Fvmdebootstrap.git;a=blobdiff_plain;f=vmdebootstrap.8.in;h=56afc3c2fe0ca27f7489704f5dd4e8d2e0ac4558;hp=663958facaf5bca936b0dfa91520552c2d9fb85f;hb=HEAD;hpb=969da62d6ad1dbd96683645067acef035a79207e diff --git a/vmdebootstrap.8.in b/vmdebootstrap.8.in index 663958f..56afc3c 100644 --- a/vmdebootstrap.8.in +++ b/vmdebootstrap.8.in @@ -1,15 +1,15 @@ .\" Copyright 2011 Lars Wirzenius -.\" +.\" .\" This program is free software: you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation, either version 3 of the License, or .\" (at your option) any later version. -.\" +.\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. -.\" +.\" .\" You should have received a copy of the GNU General Public License .\" along with this program. If not, see . .\" @@ -18,17 +18,19 @@ vmdebootstrap \- install basic Debian system into virtual disk image .SH SYNOPSIS .B vmdebootstrap ---image=FILE --size=SIZE [--mirror=URL] [--distribution=NAME] +\-\-image=FILE \-\-size=SIZE [\-\-mirror=URL] [\-\-distribution=NAME] .PP .B vmdebootstrap -[--output=FILE] [--verbose | --no-verbose] --image=FILE --size=SIZE -[--tarball=FILE] [--mirror=URL] [--arch=ARCH] [--distribution=NAME] -[--package=PACKAGE] [--custom-package=DEB] [--no-kernel] -[--enable-dhcp | --no-enable-dhcp] [--root-password=PASSWORD] -[--customize=SCRIPT] [--hostname=HOSTNAME] [--user=USER/PASSWORD] -[--serial-console | --no-serial-console] [--sudo | --no-sudo] [--owner=OWNER] -[--bootsize=BOOTSIZE] [--boottype=FSTYPE] [--foreign=PATH] [--variant=VARIANT] -[--no-extlinux] +[\-\-output=FILE] [\-\-verbose |\-\-no-verbose] \-\-image=FILE \-\-size=SIZE +[\-\-tarball=FILE] [\-\-mirror=URL] [\-\-arch=ARCH] [\-\-distribution=NAME] +[\-\-package=PACKAGE] [\-\-custom-package=DEB] [\-\-no-kernel] [\-\-kernel-package] +[\-\-enable-dhcp | \-\-no-enable-dhcp] [\-\-root-password=PASSWORD] +[\-\-customize=SCRIPT] [\-\-hostname=HOSTNAME] [\-\-user=USER/PASSWORD] +[\-\-serial-console | \-\-no-serial-console] [\-\-sudo |\-\-no-sudo] [\-\-owner=OWNER] +[\-\-bootsize=BOOTSIZE] [\-\-boottype=FSTYPE] [\-\-roottype=FSTYPE] [\-\-foreign=PATH] +[\-\-variant=VARIANT] [\-\-no-extlinux] [\-\-squash] [\-\-configure-apt] +[\-\-grub] [\-\-apt-mirror] [\-\-pkglist] [\-\-use\-efi] [\-\-efi\-size] +[\-\-debootstrapopts] .SH DESCRIPTION .B vmdebootstrap installs a basic Debian system into a virtual disk image, @@ -46,23 +48,135 @@ is a wrapper around .PP You need to run .B vmdebootstrap -as root. +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. .PP To use the image, you probably want to create a virtual machine using your preferred -virtualization technology, such as +virtualization technology, such as .BR kvm (1), or .BR qemu (1). Configure the virtual machine to use the image you've created. -Then start the virtual machine, +Then start the virtual machine, (see +.B EXAMPLES +) and log into it via its console to configure it. -.PP -Unless the \-\-no\-extlinux option is specified, the image will use +The image has an empty root password and will not have networking +configured by default. Set the root password before you configure +networking. +.SH NETWORKING +The \-\-enable\-networking option uses the /etc/network/interfaces.d/ +source directory, with the default settings for +.B lo +and +.B eth0 +being added to /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 /etc/network/interfaces.d/setup: + + auto eth0 + iface eth0 inet dhcp + +For systems running newer versions of systemd, the interface name needs +to be set in advance of the first boot instead of being dependent on the +boot itself. See the http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/ +.B vmdebootstrap +disables this behaviour by symlinking /dev/null to /etc/udev/rules.d/80-net-setup-link.rules + +.SH BOOTLOADERS +Unless the \-\-no\-extlinux or \-\-grub options are specified, the +image will use .BR extlinux (1) as a boot loader. -The imagehas an empty root password and will not have networking configured. -Set the root password before you configure networking. +.B bootsize +is not recommended when using +.B extlinux +\- use grub instead. +Versions of grub2 in wheezy +can fail to install in the VM, at which point 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 that +.B grub-legacy +is not supported. +.B vmdebootstrap +also supports +.B 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. +.B 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. +.SH INSTALLATION IMAGES AND VIRTUAL MACHINES +.B 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.) +.PP +.B vmdebootstrap +assumes that all operations take place on a local image file, not a +physical block device / removable media. +.PP +.B 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. +.PP +This has implications for +.B u-boot +support in some cases. If the device can support reading the bootloader +from a known partition, like the beaglebone-black, then +.B 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, +.B vmdebootstrap +is unable to include that bootloader image into the virtual machine image. +.PP +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 +.B 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. +.PP +It is possible to wrap +.B vmdebootstrap +in such a way as to prepare a +.B 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 +.B 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. .SH OPTIONS .IP \-\-output=FILE write output to FILE, instead of standard output @@ -75,41 +189,116 @@ create a disk image of size SIZE (1000000000) .IP \-\-tarball=FILE tar up the disk's contents in FILE .IP \-\-mirror=URL -use MIRROR as package source (http://cdn.debian.net/debian/) +use MIRROR as package source (http://http.debian.net/debian/) .IP \-\-arch=ARCH -architecture to use (amd64) +architecture to use (amd64) - if using an architecture which the +host system cannot execute, ensure the \-\-foreign option is also +used. .IP \-\-distribution=NAME -release to use (stable) +release to use (defaults to stable). The release needs to be a valid +Debian or Ubuntu release name or codename. .IP \-\-package=PACKAGE install PACKAGE onto system .IP \-\-custom-package=DEB install package in DEB file onto system (not from mirror) .IP \-\-no-kernel do not install a linux package +.IP \-\-kernel-package +If \-\-no-kernel is not used and the auto-selection of the +.B linux-image-586 +or +.B linux-image-armmp +or +.B linux-image-$ARCH +package is not suitable, the kernel package can be specified +explicitly. .IP \-\-enable-dhcp enable DHCP on eth0 .IP \-\-root-password=PASSWORD set root password .IP \-\-customize=SCRIPT -run SCRIPT after setting up system +run SCRIPT after setting up system. If the script does not exist in the current +working directory, /usr/share/vmdebootstrap/examples/ will be checked as a +fallback. The script needs to be executable and is passed the root directory of +the debootstrap as the only argument. Use chroot if you need to execute binaries +within the debootstrap. .IP \-\-hostname=HOSTNAME set name to HOSTNAME (debian) .IP \-\-user=USER/PASSWORD create USER with PASSWORD .IP \-\-owner=OWNER change the owner of the final image from root to the specified user. -.IP \-\-serial-console +.IP \-\-serial\-console configure image to use a serial console +.IP \-\-serial-console-command +set the command to manage the serial console which will be appended to +/etc/inittab. Default is "/sbin/getty \-L ttyS0 115200 vt100", resulting in a line +.BR "S0:23:respawn:/sbin/getty \-L ttyS0 115200 vt100" .IP \-\-sudo install sudo, and if user is created, add them to sudo group .IP \-\-bootsize=BOOTSIZE -If specified, create a /boot partition of the given size within the image. Debootstrapping will fail if this is too small for the selected kernel package. +If specified, create a /boot partition of the given size within the image. +Debootstrapping will fail if this is too small for the selected kernel package. .IP \-\-boottype=FSTYPE Filesystem to use for the /boot partition. (default ext2) +.IP \-\-roottype=FSTYPE +Filesystem to use for the / (root) partition. (default ext4) +.IP \-\-swap=SWAPSIZE +If specified, create a swap partition of the given size within the image. +Debootstrapping will fail if this results in a root partition which is +too small for the selected packages. The minimum swap space is 256Mb as +the default memory allocation of QEMU is 128Mb. A default 1Gb image is +not likely to have enough space for a swap partition as well. .IP \-\-foreign=PATH -Path to the binfmt_handler to enable foreign support in debootstrap. e.g. /usr/bin/qemu-arm-static - note foreign debootstraps may take a signficant amount of time to complete and that debootstrap will retry five times if packages fail to install by default. +Path to the binfmt_handler to enable foreign support in debootstrap. +e.g. /usr/bin/qemu-arm-static \- note foreign debootstraps may take a signficant +amount of time to complete and that debootstrap will retry five times if +packages fail to install by default. .IP \-\-no\-extlinux -Skip installation of extlinux. needs a customize script to make the image bootable. Useful for architectures where extlinux is not supportable. +Skip installation of extlinux. needs a customize script to make the image +bootable. Useful for architectures where extlinux is not supportable. +Depending on how the image is to be booted, the \-\-mbr option may also be +necessary with extlinux. +.IP \-\-squash +Run mksquashfs against the final image using xz compression \- requires +squashfs-tools to be installed. The final file will have the .squashfs suffix. +By default, mksquashfs is allowed to use all processors which may result +in high load. Run mksquashfs separately if you need to control the number +of processors used per run. squashfs can also have issues with large image +files (where large is a factor of the amount of data inside the image rather +than the size of the image itself). These errors can result in invalid +images (e.g. image does not boot) or corrupted images (truncated file). +This is a known bug in squashfs. Avoid using the \-\-squash option and +consider squashing the loopback mounted directory tree of the image. +.B +vmdebootstrap +will check if the squashed filesystem is less than 1MB and leave the +unsquashed image in place with a warning about a possible squashfs +failure. +.IP \-\-configure\-apt +Use the specified mirror and distribution to create a suitable apt source inside +the VM. Can be useful if debootstrap fails to create it automatically. +.IP \-\-apt\-mirror +Use the specified mirror inside the image instead of the mirror used to +build the image. This is useful if you have a local mirror to make building +the image quicker but the image needs to run even if that mirror is not +available. +.IP \-\-grub +Disable extlinux installation and configure grub2 instead. grub2 will be added to +the list of packages to install. update-grub will be called once the debootstrap is +complete and grub-install will be called in the image. +.IP \-\-debootstrapopts +Pass additional options to debootstrap as a quoted list of options +and values, separated by spaces. +e.g. --debootstrapopts="variant=buildd no-check-gpg components=main,contrib". +See debootstrap \-\-help and debootstrap (1) for valid options. +.IP \-\-no\-acpid +Disable installation of acpid if not required, otherwise acpid will be +installed if \-\-foreign is not used. +.IP \-\-pkglist +Output a list of package names installed inside the image. Useful if you +need to track the relevant source packages used inside the image for +licence compliance. .SH Configuration files and settings: .IP \-\-dump-config write out the entire current configuration @@ -137,26 +326,80 @@ none, simple, meliae, or heapy (default: simple) make memory profiling dumps at least SECONDS apart .SH EXAMPLE To create an image for the stable release of Debian: -.nf .IP -sudo vmdebootstrap --image test.img --size 1g \\ - --log test.log --log-level debug --verbose \\ - --mirror http://mirror.lan/debian/ +sudo vmdebootstrap \-\-image test.img \-\-size 1g \\ + \-\-log test.log \-\-log-level debug \-\-verbose \\ + \-\-mirror http://mirror.lan/debian/ .PP -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: +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: .IP sudo chmod a+w ./test.img .PP Execute using qemu, e.g. on amd64 using qemu-system-x86_64: .IP -qemu-system-x86_64 ./test.img +qemu-system-x86_64 -drive format=raw,file=./test.img +.PP +(This loads the image in a new window.) Note the use of -drive +file=,format=raw which is needed for newer versions of QEMU. +.PP +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 +.B +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: +.IP +$ qemu-system-x86_64 \-L /usr/share/ovmf/ -machine accel=kvm \\ + \-m 4096 \-smp 2 \-drive format=raw,file=test.img +.PP +For further examples, including u-boot support for beaglebone-black, +see /usr/share/vmdebootstrap/examples +.SH 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. .PP -(This loads the image in a new window.) +.B 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. +.PP +Note that if you are also using a separate /boot partition in your options to +.B vmdebootstrap +it may well be the boot partition which needs to be enlarged rather than +the entire image. +.PP +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. +.PP +There are two types of examples for ARM devices available with +.B 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 +.B 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. .PP .SH "SEE ALSO" .BR debootstrap (8) , -.BR qemu (1) +.BR qemu-system-x86_64 (1) +, +.BR grub-install (8) . .SH BUGS Please provide the config section of the logfile when reporting bugs, as well as the complete command line.