.\" 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/>.
.\"
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,
.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
.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
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=<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
-(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.
projects / forks / vmdebootstrap.git / blobdiff