~ubuntu-virt/vmbuilder/trunk

.TH UBUNTU-VM-BUILDER 1 "May 2008"

.SH NAME

ubuntu-vm-builder \- build ubuntu based virtual machines

.SH SYNOPSIS

.B ubuntu-vm-builder <vm> <suite>

[\fIOPTIONS\fR]...

.SH DESCRIPTION

This manual page documents the

.B ubuntu-vm-builder

command.

.B ubuntu-vm-builder

is a program that builds virtual machines based on Ubuntu. You can pass command line options to add extra packages, remove packages, choose which version of Ubuntu, which mirror etc. On recent hardware with plenty of RAM, tmpdir in /dev/shm or using a tmpfs, and a local mirror, you can bootstrap a vm in less than a minute.

 

 

.SH PARAMETERS AND OPTIONS

.TP

.B NOTE 

There may be many more options than this. See ubuntu-vm-builder --help for more information

.TP

.B <vm>

Generate images for the specified virtualisation software

.TP

.B <suite>

Use the specified Ubuntu suite (ie: interpid, hardy, gutsy, etc....)

 

 

.SS Guest definition options

.TP

.B \-\-kernel-flavour FLAVOUR

The kernel image flavour to install from: virtual, server, generic or others availble kernels (default: virtual for versions >= gutsy on i386, server otherwise)

.TP

.B \-\-components COMP1,COMP2,...,COMPN

A comma seperaed list of distro components to include (e.g. main,universe). This defaults to "main"

.TP

.B \-\-addpkg PKG

Install PKG into the guest (can be specfied multiple times)

.TP

.B \-\-removepkg PKG

Remove PKG from the guest (can be specfied multiple times)

.TP

.B \-a, \-\-arch ARCH

Specify the target architecture.

Valid options: i386 amd64 lpia. Defaults to the same as the running system.

.TP

.B \-\-user USERNAME

Set the name of the user to be added. Default: ubuntu.

.TP

.B \-\-name FULLNAME

Set the full name of the user to be added. Default: Ubuntu.

.TP

.B \-\-pass PASSWORD

Set the password for the user. Default: ubuntu.

.TP

.B \-\-hostname NAME

Set NAME as the hostname of the guest. Default: ubuntu

.TP

.B \-\-mem NN

Assign NN megabytes of memory to the guest vm.  Default: 128

 

 

.SS Guest networking options

.TP

.B \-\-domain DOMAIN

Set DOMAIN as the domain name of the guest. Default: The domain of the machine running this script.

.TP

.B \-\-ip ADDRESS

Ip address in dotted form (defaults to dhcp if not specified)

.TP

Options below are discarded if --ip is not specified

.RS

.B \-\-mask VALUE

IP mask in dotted form (default: 255.255.255.0)

.TP

.B \-\-net VALUE

IP net address (default: X.X.X.0)

.TP

.B \-\-bcast VALUE

IP broadcast (default: X.X.X.255)

.TP

.B \-\-gw ADDRESS

Gateway address (default: X.X.X.1)

.TP

.B \-\-dns ADDRESS

Name server address (default: X.X.X.1)

.RE

 

.SS Guest partitioning options

.TP

.B \-\-raw PATH

Specify the path to a raw file or device to install in.  Can be specified multiple time in conjunction with --part, paths will be used in the order presented. Make sure that the raw element(s) specified have enough free space.

.TP

.B \-\-part PATH

Allows to specify a partition table in partfile each line of partfile should specify (root first):

.RS

.RS

mountpoint size

.RE

where size is in megabytes. You can have up to 4 virtual disks, a new disk starts on a line with '---'. 

ie :

.RS

 root 1000

 /opt 1000

 swap 256

 ---

 /var 2000

 /log 1500

.RE

.RE

.TP

The following three options are not used if --part is specified:

.RS

.B \-\-rootsize SIZE

The size in MB of the root filesystem (default 1000)

.TP

.B \-\-optsize SIZE

The size in MB of the /opt filesystem (default 4000)

.TP

.B \-\-swapsize SIZE

The size in MB of the swap partition (default 1000)

.RE

 

.SS Environment definitions options

.TP

.B \-d, \-\-dest

Specify the destination directory.  Default: ubuntu-vm-$SUITE-$ARCH

.TP

.B \-t, \-\-tmp PATH

Use PATH as temporary working area for the image generation. 

Defaults to $TMPDIR or /tmp if $TMPDIR is not defined.  

If it is set to "-" data the data will go the same directory as -d if specified with a full path or the current directory if not.

.TP

.B \-\-tmpfs OPTIONS

Use a tmpfs as the working directory, specifying its options 

or "-" to use tmpfs default when no options are passed (different from the 

defaults below, see tmpfs manual)

 Defaults: suid,dev,size=1G

.TP

.B \-\-iso PATH

Use an iso image as the source for installation of file. Full path to the iso must be provided. 

If --mirror is also provided, it will be used in the final sources.list of the vm.

This requires suite and kernel parameter to match what is available on the iso, obviously.

.TP

.B \-\-mirror URL

Use Ubuntu mirror at URL. Default: http://archive.ubuntu.com/ubuntu for official architectures and http://ports.ubuntu.com/ubuntu-ports otherwise.

.TP

.B \-\-security-mirror URL

Use Ubuntu security mirror at URL instead of the default,

which is http://security.ubuntu.com/ubuntu for official

arches and http://ports.ubuntu.com/ubuntu-ports otherwise

.TP

.B \-\-ssh-key PATH

Add the given ssh public key file (absolute path) to the root's authorized keys and install openssh-server (WARNING: this has strong security implications)

.TP

.B \-\-ssh-user-key PATH

Add the given ssh public key file (absolute path) to the user's authorized keys and install openssh-server (WARNING: this has strong security implications)

.TP

.B \-\-exec PATH

Run the given script file specified by PATH. You can use 'chroot root <cmd>' to execute code in the guest. See additional details in the 'EXEC EXPLANATIONS' chapter.

.TP

.B \-\-firstboot PATH

Specify a script that will be copied into the guest and executed the first time the machine boots.  This script must not be interactive.

.TP

.B \-\-firstlogin PATH

Specify a script that will be copied into the guest and will be executed the first time the user logs in. This script can be interactive.

 

.SS Utilities

.TP

.B \-o, \-\-overwrite

Force overwrite of destination dirctory if it already exists.

.TP

.B \-h, \-\-help

Self-explanatory.

.TP

.B \-\-in-place

Install directly into the filesystem images. This is needed if your $TMPDIR is nodev and/or nosuid, but will result in slightly larger file system images.

.TP

.B \-v, \-\-verbose

Causes the display of a lot of information which are mainly interesting while debugging.

.TP

.B \-c PATH

Specify a file to read the configuration from (defaults to ~/.ubuntu-vm-builder). See CONFIGURATION FILE below.

 

 

.SS Obsolete

.TP

.B \-\-no\-opt

OBSOLETE - /opt partition is not created by default anymore

 

 

.SS Virtual Machine Specific options

.TP

.B kvm, qemu:

.RS

.TP

.B \-\-libvirt URI

Add resulting VM to the libvirt hypervisor at uri.

.TP

.B \-\-templates DIR

Specify where libvirt.tmpl is stored. Uses /usr/share/ubuntu-vm-builder/templates directory by default.

.RE

.B vmserver, wmw6:

.RS

.TP

.B \-\-templates DIR

Specify where vmware.tmpl is stored. Uses /usr/share/ubuntu-vm-builder/templates directory by default.

.RE

 

.SH CONFIGURATION FILE

 Most parameters can also be defined in the system's  configuration (/etc/ubuntu-vm-builder) or user's configuration (~/.ubuntu-vm-builder), or in a file specified by -c PATH.

 The files are automatically generated with default values the first time ubuntu-vm-builder is ran. See comments in the config file for more details on possible values, it should be self explanatory.

 User configuration is read after the system configuration, so it has precedence over it.

 In most cases, parameters have precedence over the configuration file, with the exception of list type parameters (ie: PKGCMD) which will see parameters added to the list predefined in the configuration file.

 

.SH EXEC EXPLANATIONS

 The --exec parameter allows to specify the full path name of a script that will be executed after the base system is installed (except grub) whose files hierarchy is in a directory named 'root' and has not yet been copied to the target virtual devices.

 The script is not in a chroot by default, so you can still copy file from the host file system (using full path name) to the destination files hierarchy which is in a subdirectory of the current working directory ($PWD) named 'root'.

 To execute commands in the target system's environment, you will need to prefix it with 'chroot root'.

 If the script returns an error, ubuntu-vm-builder will not continue to build the vm. 

 It is recommended to keep this script non interactive.

.TP

.B Sample script

.RS

 #Copy some file from the users home to the target user's home 

 cp -a ~/.gnome root/home/ubuntu/

 #Execute a command in the target system

 chroot root touch /var/log/syslog

 exit 0

.RE

.SH AUTHOR

ubuntu-vm-builder and this man page was written by Soren Hansen <soren@canonical.com> and is copyright 2007-2008 Canonical Ltd.