vmdebootstrap.8.in

   1 .\" Copyright 2011 Lars Wirzenius <liw@liw.fi>
   2 .\"
   3 .\" This program is free software: you can redistribute it and/or modify
   4 .\" it under the terms of the GNU General Public License as published by
   5 .\" the Free Software Foundation, either version 3 of the License, or
   6 .\" (at your option) any later version.
   7 .\"
   8 .\" This program is distributed in the hope that it will be useful,
   9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 .\" GNU General Public License for more details.
  12 .\"
  13 .\" You should have received a copy of the GNU General Public License
  14 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15 .\"
  16 .TH VMDEBOOTSTRAP 8
  17 .SH NAME
  18 vmdebootstrap \- install basic Debian system into virtual disk image
  19 .SH SYNOPSIS
  20 .B vmdebootstrap
  21 --image=FILE --size=SIZE [--mirror=URL] [--distribution=NAME]
  22 .PP
  23 .B vmdebootstrap
  24 [--output=FILE] [--verbose | --no-verbose] --image=FILE --size=SIZE
  25 [--tarball=FILE] [--mirror=URL] [--arch=ARCH] [--distribution=NAME]
  26 [--package=PACKAGE] [--custom-package=DEB] [--no-kernel]
  27 [--enable-dhcp | --no-enable-dhcp] [--root-password=PASSWORD]
  28 [--customize=SCRIPT] [--hostname=HOSTNAME] [--user=USER/PASSWORD]
  29 [--serial-console | --no-serial-console] [--sudo | --no-sudo] [--owner=OWNER]
  30 [--bootsize=BOOTSIZE] [--boottype=FSTYPE] [--foreign=PATH] [--variant=VARIANT]
  31 [--no-extlinux]
  32 .SH DESCRIPTION
  33 .B vmdebootstrap
  34 installs a basic Debian system into a virtual disk image,
  35 for use with virtual machines,
  36 such as KVM, Qemu, or VirtualBox.
  37 It is like
  38 .BR debootstrap (8),
  39 which does the same thing, but puts the system into a directory,
  40 for use with
  41 .BR chroot (8).
  42 (In fact,
  43 .B vmdebootstrap
  44 is a wrapper around
  45 .BR debootstrap ).
  46 .PP
  47 You need to run
  48 .B vmdebootstrap
  49 as root.
  50 .PP
  51 To use the image,
  52 you probably want to create a virtual machine using your preferred
  53 virtualization technology, such as
  54 .BR kvm (1),
  55 or
  56 .BR qemu (1).
  57 Configure the virtual machine to use the image you've created.
  58 Then start the virtual machine,
  59 and log into it via its console to configure it.
  60 .PP
  61 Unless the \-\-no\-extlinux option is specified, the image will use
  62 .BR extlinux (1)
  63 as a boot loader.
  64 The imagehas an empty root password and will not have networking configured.
  65 Set the root password before you configure networking.
  66 .SH OPTIONS
  67 .IP \-\-output=FILE
  68 write output to FILE, instead of standard output
  69 .IP \-\-verbose
  70 report what is going on
  71 .IP \-\-image=FILE
  72 put created disk image in FILE
  73 .IP \-\-size=SIZE
  74 create a disk image of size SIZE (1000000000)
  75 .IP \-\-tarball=FILE
  76 tar up the disk's contents in FILE
  77 .IP \-\-mirror=URL
  78 use MIRROR as package source (http://cdn.debian.net/debian/)
  79 .IP \-\-arch=ARCH
  80 architecture to use (amd64)
  81 .IP \-\-distribution=NAME
  82 release to use (stable)
  83 .IP \-\-package=PACKAGE
  84 install PACKAGE onto system
  85 .IP \-\-custom-package=DEB
  86 install package in DEB file onto system (not from mirror)
  87 .IP \-\-no-kernel
  88 do not install a linux package
  89 .IP \-\-enable-dhcp
  90 enable DHCP on eth0
  91 .IP \-\-root-password=PASSWORD
  92 set root password
  93 .IP \-\-customize=SCRIPT
  94 run SCRIPT after setting up system
  95 .IP \-\-hostname=HOSTNAME
  96 set name to HOSTNAME (debian)
  97 .IP \-\-user=USER/PASSWORD
  98 create USER with PASSWORD
  99 .IP \-\-owner=OWNER
 100 change the owner of the final image from root to the specified user.
 101 .IP \-\-serial-console
 102 configure image to use a serial console
 103 .IP \-\-sudo
 104 install sudo, and if user is created, add them to sudo group
 105 .IP \-\-bootsize=BOOTSIZE
 106 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.
 107 .IP \-\-boottype=FSTYPE
 108 Filesystem to use for the /boot partition. (default ext2)
 109 .IP \-\-foreign=PATH
 110 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.
 111 .IP \-\-no\-extlinux
 112 Skip installation of extlinux. needs a customize script to make the image bootable. Useful for architectures where extlinux is not supportable.
 113 .SH Configuration files and settings:
 114 .IP \-\-dump-config
 115 write out the entire current configuration
 116 .IP \-\-no-default-configs
 117 clear list of configuration files to read
 118 .IP \-\-config=FILE
 119 add FILE to config files
 120 .SH Logging:
 121 .IP \-\-log=FILE
 122 write log entries to FILE (default is to not write log files at all);
 123 use "syslog" to log to system log, or "none" to disable logging
 124 .IP \-\-log-level=LEVEL
 125 log at LEVEL, one of debug, info, warning, error, critical, fatal (default: debug)
 126 .IP \-\-log-max=SIZE
 127 rotate logs larger than SIZE, zero for never (default: 0)
 128 .IP \-\-log-keep=N
 129 keep last N logs (10)
 130 .IP \-\-log-mode=MODE
 131 set permissions of new log files to MODE (octal;  default 0600)
 132 .SH Peformance:
 133 .IP \-\-dump-memory-profile=METHOD
 134 make memory profiling dumps using METHOD, which is one of:
 135 none, simple, meliae, or heapy (default: simple)
 136 .IP \-\-memory-dump-interval=SECONDS
 137 make memory profiling dumps at least SECONDS apart
 138 .SH EXAMPLE
 139 To create an image for the stable release of Debian:
 140 .nf
 141 .IP
 142 sudo vmdebootstrap --image test.img --size 1g \\
 143     --log test.log --log-level debug --verbose \\
 144     --mirror http://mirror.lan/debian/
 145 .PP
 146 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:
 147 .IP
 148 sudo chmod a+w ./test.img
 149 .PP
 150 Execute using qemu, e.g. on amd64 using qemu-system-x86_64:
 151 .IP
 152 qemu-system-x86_64 ./test.img
 153 .PP
 154 (This loads the image in a new window.)
 155 .PP
 156 .SH "SEE ALSO"
 157 .BR debootstrap (8)
 158 ,
 159 .BR qemu (1)
 160 .
 161 .SH BUGS
 162 Please provide the config section of the logfile when reporting bugs, as well as the complete command line.