summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorNeil Williams <codehelp@debian.org>2015-09-13 12:37:06 +0100
committerNeil Williams <codehelp@debian.org>2015-09-13 12:37:06 +0100
commit1a73e6a6882d01231b2a4d4d353ca931806ddd89 (patch)
treeab17e18e215976035e62942c8c92917697caa7f0 /man
parent1001c3b9f14f139a1e46d442dd39acde348c9264 (diff)
downloadvmdebootstrap-1a73e6a6882d01231b2a4d4d353ca931806ddd89.tar.gz
replace manpage with rst output
Diffstat (limited to 'man')
-rw-r--r--man/conf.py6
-rw-r--r--man/vmdebootstrap.rst152
2 files changed, 154 insertions, 4 deletions
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.