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 +++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 154 insertions(+), 4 deletions(-) (limited to 'man') 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. -- cgit v1.2.1