.\" 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/>.
.\"
.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] 
[--enable-dhcp | --no-enable-dhcp] [--root-password=PASSWORD]
[--customize=SCRIPT] [--hostname=HOSTNAME] [--user=USER/PASSWORD]
[--serial-console | --no-serial-console] [--sudo | --no-sudo]
.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.
.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,
and log into it via its console to configure it.
.PP
The image will be using
.BR extlinux (1)
as a boot loader.
It has an empty root password.
The image will not have networking configured.
Set the root password before you configure networking.
.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://cdn.debian.net/debian/)
.IP \-\-arch=ARCH
architecture to use (amd64)
.IP \-\-distribution=NAME
release to use (stable)
.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 \-\-enable-dhcp
enable DHCP on eth0
.IP \-\-root-password=PASSWORD
set root password
.IP \-\-customize=SCRIPT
run SCRIPT after setting up system
.IP \-\-hostname=HOSTNAME
set name to HOSTNAME (debian)
.IP \-\-user=USER/PASSWORD
create USER with PASSWORD
.IP \-\-serial-console
configure image to use a serial console
.IP \-\-sudo
install sudo, and if user is created, add them to sudo group
.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:
.nf
.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:
.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
.PP
(This loads the image in a new window.)
.PP
.SH "SEE ALSO"
.BR debootstrap (8)
,
.BR qemu (1)
.