diff options
Diffstat (limited to 'vmdebootstrap.8.in')
| -rw-r--r-- | vmdebootstrap.8.in | 393 |
1 files changed, 0 insertions, 393 deletions
diff --git a/vmdebootstrap.8.in b/vmdebootstrap.8.in deleted file mode 100644 index 0364bed..0000000 --- a/vmdebootstrap.8.in +++ /dev/null @@ -1,393 +0,0 @@ -.\" Copyright 2011 Lars Wirzenius <liw@liw.fi> -.\" -.\" 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 <http://www.gnu.org/licenses/>. -.\" -.TH VMDEBOOTSTRAP 8 -.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] -.SH DESCRIPTION -.B vmdebootstrap -installs a basic Debian system into a virtual disk image, -for use with virtual machines, -such as KVM, Qemu, or VirtualBox. -It is like -.BR debootstrap (8), -which does the same thing, but puts the system into a directory, -for use with -.BR chroot (8). -(In fact, -.B vmdebootstrap -is a wrapper around -.BR debootstrap ). -.PP -You need to run -.B 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. -.PP -To use the image, -you probably want to create a virtual machine using your preferred -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, (see -.B EXAMPLES -) -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. -.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 - -.SH BOOTLOADERS -Unless the \-\-no\-extlinux or \-\-grub options are specified, the -image will use -.BR extlinux (1) -as a boot loader. -.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 \-\-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: -.IP -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=<img>,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 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. |