X-Git-Url: https://git.siccegge.de//index.cgi?p=forks%2Fvmdebootstrap.git;a=blobdiff_plain;f=vmdebootstrap.8.in;h=56afc3c2fe0ca27f7489704f5dd4e8d2e0ac4558;hp=8eceba12fcab611ee6ff34e4f15498bed7d9e6b2;hb=HEAD;hpb=d4538dd8232752804485f0b75558f0f07b74ce19 diff --git a/vmdebootstrap.8.in b/vmdebootstrap.8.in index 8eceba1..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 . .\" @@ -17,6 +17,20 @@ .SH NAME vmdebootstrap \- install basic Debian system into virtual disk image .SH SYNOPSIS +.B vmdebootstrap +\-\-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] [\-\-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, @@ -34,31 +48,358 @@ 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 -The image will be using +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. -It has an empty root password. -The image 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 +.IP \-\-verbose +report what is going on +.IP \-\-image=FILE +put created disk image in FILE +.IP \-\-size=SIZE +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://http.debian.net/debian/) +.IP \-\-arch=ARCH +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 (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. 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 +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. +.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. +.IP \-\-no\-extlinux +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 +.IP \-\-no-default-configs +clear list of configuration files to read +.IP \-\-config=FILE +add FILE to config files +.SH Logging: +.IP \-\-log=FILE +write log entries to FILE (default is to not write log files at all); +use "syslog" to log to system log, or "none" to disable logging +.IP \-\-log-level=LEVEL +log at LEVEL, one of debug, info, warning, error, critical, fatal (default: debug) +.IP \-\-log-max=SIZE +rotate logs larger than SIZE, zero for never (default: 0) +.IP \-\-log-keep=N +keep last N logs (10) +.IP \-\-log-mode=MODE +set permissions of new log files to MODE (octal; default 0600) +.SH Peformance: +.IP \-\-dump-memory-profile=METHOD +make memory profiling dumps using METHOD, which is one of: +none, simple, meliae, or heapy (default: simple) +.IP \-\-memory-dump-interval=SECONDS +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: +.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 -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 +.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 debootstrap (8) +, +.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.