From 1a73e6a6882d01231b2a4d4d353ca931806ddd89 Mon Sep 17 00:00:00 2001 From: Neil Williams Date: Sun, 13 Sep 2015 12:37:06 +0100 Subject: replace manpage with rst output --- man/conf.py | 6 +- man/vmdebootstrap.rst | 152 ++++++++++++++++++- vmdebootstrap.8.in | 393 -------------------------------------------------- 3 files changed, 154 insertions(+), 397 deletions(-) delete mode 100644 vmdebootstrap.8.in diff --git a/man/conf.py b/man/conf.py index 7d80f0a..59a123f 100644 --- a/man/conf.py +++ b/man/conf.py @@ -10,9 +10,9 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import subprocess import sys import os +import subprocess # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -49,7 +49,7 @@ copyright = u'2015, Neil Williams' # built documents. # # The short X.Y version. -version = subprocess.Popen(r'./version.py', cwd=r'..', stdout=subprocess.PIPE).stdout.read() +version = subprocess.Popen(['python', 'setup.py', '-V'], cwd=r'..', stdout=subprocess.PIPE).stdout.read() # The full version, including alpha/beta/rc tags. release = version @@ -206,6 +206,6 @@ intersphinx_mapping = {'http://docs.python.org/': None} # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('vmdebootstrap', 'vmdebootstrap', u'vmdebootstrap', + ('vmdebootstrap', 'vmdebootstrap', u'install basic Debian system into virtual disk image', [u'Neil Williams'], 1), ] diff --git a/man/vmdebootstrap.rst b/man/vmdebootstrap.rst index 09356c5..10a1301 100644 --- a/man/vmdebootstrap.rst +++ b/man/vmdebootstrap.rst @@ -3,6 +3,7 @@ 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 @@ -17,6 +18,155 @@ 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. +Synopsis +******** + +:: + + $ sudo vmdebootstrap --image=FILE --size=SIZE [--mirror=URL] [--distribution=NAME] + +Options +******* + + --output=FILE write output to FILE, instead of standard output + --verbose report what is going on + --image=FILE put created disk image in FILE + --size=SIZE create a disk image of size SIZE (1000000000) + --tarball=FILE tar up the disk's contents in FILE + --mirror=URL use MIRROR as package source (http://http.debian.net/debian/) + --arch=ARCH architecture to use (amd64) - if using an + architecture which the host system cannot execute, + ensure the --foreign option is also used. + --distribution=NAME release to use (defaults to stable). The release + needs to be a valid Debian or Ubuntu release name + or codename. + --debootstrapopts="command=option,command=option" + Supply options and arguments to ``debootstrap``. + See **debootstrap (1)** for more information. This + replaces the ``--variant`` support in previous versions + of :file:`vmdebootstrap`. + --package=PACKAGE install PACKAGE onto system + --custom-package=DEB install package in DEB file onto system (not + from mirror) + --no-kernel do not install a linux package + --kernel-package If --no-kernel is not used and the auto-selection + of the **linux-image-586** or **linux-image-armmp** + or **linux-image-$ARCH** package is not suitable, + the kernel package can be specified explicitly. + --enable-dhcp enable DHCP on eth0 + --root-password=PASSWORD + set root password + --customize=SCRIPT run SCRIPT after setting up system. If the script + does not exist in the current working directory, + :file:`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. + --hostname=HOSTNAME set name to HOSTNAME (debian) + --user=USERSTRING create USER with PASSWORD. The USERSTRING needs to + be of the format: USER/PASSSWORD. + --owner=OWNER change the owner of the final image from root to + the specified user. + --serial-console configure image to use a serial console + --serial-console-command + set the command to manage the serial console which + will be appended to :file:`/etc/inittab`. Default + is ``/sbin/getty \-L ttyS0 115200 vt100``, resulting + in a line:: + + "S0:23:respawn:/sbin/getty \-L ttyS0 115200 vt100" + + --sudo install sudo, and if user is created, add them to + sudo group + --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 and upgrading such a kernel package is + likely to need two or three times the space of the + installed kernel. + --boottype=FSTYPE Filesystem to use for the /boot partition. (default ext2) + --roottype=FSTYPE Filesystem to use for the / (root) partition. (default ext4) + --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. + --foreign=PATH Path to the binfmt_handler to enable foreign support + in debootstrap. e.g. :file:`/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. + --no-extlinux Skip installation of extlinux. needs a customize script + or alternative bootloader 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. + --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. + ``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. + --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. + --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. + --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. + --no-acpid Disable installation of acpid if not required, otherwise + acpid will be installed if --foreign is not used. + --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. + +Configuration files and settings +******************************** + + --dump-config write out the entire current configuration + --no-default-configs clear list of configuration files to read + --config=FILE add FILE to config files + +Logging +******* + + --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. + --log-level=LEVEL log at LEVEL, one of debug, info, warning, error, + critical, fatal (default: debug). + --log-max=SIZE rotate logs larger than SIZE, zero for never (default: 0) + --log-keep=N keep last N logs (10) + --log-mode=MODE set permissions of new log files to MODE (octal; default 0600) + +Peformance +********** + + --dump-memory-profile=METHOD + make memory profiling dumps using METHOD, which is one + of: none, simple, meliae, or heapy (default: simple) + --memory-dump-interval=SECONDS + make memory profiling dumps at least SECONDS apart + Networking ********** @@ -171,7 +321,7 @@ 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 +.. caution:: 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. 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 -.\" -.\" 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 . -.\" -.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=,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. -- cgit v1.2.1