NAME
rootstrap — Construct a root filesystem image in a file
SYNOPSIS
rootstrap [options ...] imagefile
DESCRIPTION
rootstrap is a tool for creating root filesystem images. It was
written primarily for use with User-Mode Linux, but may be useful for
other purposes as well.
Because it uses User-Mode Linux to bootstrap itself, rootstrap can be
used without root privileges on the host system, which are normally
required for this task in order to use chroot(2) and mount and unmount
filesystems. Rootstrap boots UML and uses tools from the host
filesystem to perform installation and configuration tasks.
Note: since roostrap needs to access the host filesystem it requires an
UML kernel with hostfs built-in (CONFIG_HOSTFS=y), not as module.
OPTIONS
-s, --image-size
Sets the initial size of the image, in megabytes, overriding
the initialsize option in rootstrap.conf.
-o logfile
Log the output of the creation process to logfile instead of
to standard output.
-u args, --umlargs args
Pass additional arguments to user-mode linux when booting to
create the image. Supplements the ’umlargs’ option in
rootstrap.conf.
Configuration
The configuration file consists of sections, starting with a
"[section]" header, followed by "option=value" entries. Long values
are allowed to span multiple lines if each continued line is indented
with whitespace.
With the exception of the special section "global", sections are named
after a corresponding module. When that module is executed, it
receives the option/value pairs in its section as environment
variables. All modules inherit global options as environment
variables, except where overridden by options within their specific
section. At least PATH must be set here, in addition to the required
parameters listed below under [global].
Documentation for configurable modules distributed with rootstrap is
included below. This section is currently incomplete.
Note that the modules shipped with rootstrap have a recommended
ordering due to their cooperation in building the guest OS image,
equivalent modules can be used for each of these tasks:
1. setup guest network (if you need it for OS installation)
2. create the target filesystem
3. mount target filesystem in the guest Linux
4. OS installation
5. UML basic setup (device nodes, kernel modules, etc.)
6. Tweaking (here you should have a fully working OS to play with)
7. unmount the target filesystem
Modules
[global]
Contains configuration options that affect the operation of rootstrap
itself, or several modules.
fstype The type of filesystem to create (ext2, ext3, reiserfs, etc.)
This parameter is mandatory.
umlargs Additional arguments to user-mode linux passed when booting
to create the image.
PATH The PATH environment variable to pass to modules. This
parameter is mandatory.
initialsize
The initial size of the filesystem image (in megabytes).
This must be large enough to contain a complete installed
system as produced by the selected modules. It will be
created sparsely, so additional space is not entirely
allocated until it is used. This parameter is mandatory.
freespace The amount of free space to leave on the filesystem (in
megabytes). The filesystem will be resized, if possible, to
adjust the amount of free space to approximately this amount.
This parameter is optional.
modules The list of modules to invoke, in order. Each module will be
searched for in several directories, listed in the FILES
section below, and passed environment variables based on the
options set in the corresponding section of the configuration
file. This parameter is mandatory.
debug When set to "true" make rootstrap spawn a shell when a module
script fails allowing further debugging actions. The shell
will have the same environment as the failing script so you
could simply invoke sh -x /path/to/module to see
what’s going wrong. Moreover the shell exit value will be
used to tell rootstrap to: re-evaluate the script when 1
(with exit 1) or continue with the next one when 2 (with exit
2); all other values will make rootstrap fail with an error.
This parameter is optional.
[network]
Network configuration. This module configures virtual networking with
the user-mode Linux system used to build the filesystem image. Its
presence is not strictly necessary, if the selected modules do not
require network access (for example, with a local package mirror) and
the network module is not included in the global "modules" list.
interface The name of the network interface to configure inside the UML
virtual machine, typically "eth0". This parameter is
mandatory.
host The IP address of the host side of the interface (the host on
which rootstrap is run), as visible to the UML virtual
machine. This parameter is mandatory.
uml The IP address of the UML side of the interface (where the
system is being built). The value "dhcp" is also accepted and
makes rootstrap try to configure the network interface
through DHCP. This parameter is mandatory.
transport The type of virtual networking interface to be used.
Typically "tuntap". Other available transports are "slirp"
and "daemon". This parameter is mandatory.
netmask The netmask for the network interface (applies to both
sides). This parameter is mandatory.
hostname The host name to use for the created UML virtual machine.
This parameter is optional.
gateway A default gateway to be used by the user-mode Linux system.
This parameter is optional.
domain The local domain name.
nameserver
The DNS server to use for domain name resolution inside the
UML virtual machine. This parameter is optional, but useful
if you do not have a name server running on the host.
[mkfs]
This module creates the filesystem for the rootfs. It uses the fstype
global parameter.
[mount]
This module mounts the root filesystem where the OS image is going to
be created. It uses the fstype global parameter.
[umount]
This module unmounts the root filesystem and /proc.
[uml]
Creates /etc/fstab and necessary device nodes, it eventually copies
kernel modules into the target image. It uses the fstype global
parameter.
kernel_modules
How to deal with kernel modules for the guest Linux. It can
be one of none, hostfs or copy, defaults to the latter which
copies the available modules in the target filesystem.
kernel_modules_dir
The directory where kernel_modules are located on
the host filesystem. It defaults to /usr/lib/uml/modules
install_modules
This parameter is superseeded by kernel_modules and
kernel_modules_dir. It accepts a boolean value (true/false).
[debian]
Debian installation. This module installs a basic Debian system using
debootstrap.
dist The distribution to install (e.g., potato, woody, etc.)
mirror A URL for a Debian archive containing the base packages.
This must be a URL understood by debootstrap, which as of
this writing includes URLs understood by wget, and file:
URLs.
exclude A list of packages which should be excluded (never installed
at all). It is quite possible to produce a broken system, or
fail to build a system at all, if this option is used
improperly. It is useful for excluding packages, such as
pcmcia-cs, which are typically not necessary for UML and
other applications.
Corresponds to debootstrap’s --exclude option
purge A list of packages which should be removed after installation
is complete. Use this for packages which are required during
installation, but may be removed afterward. The same warning
applies as with the exclude option.
Packages are removed with dpkg --purge.
include A list of packages which should be included in the initial
set of packages to install.
Corresponds to debootstrap’s --include option.
install Extra packages to install via apt after initial debootstrap
install.
See also the sources option.
debconf_preseed_file
A file containing a debconf DB to be used as default. Read
debconf documentation and see your
/var/cache/debconf/config.dat for examples and caveats.
sources Sources for target’s sources.list. If no value is given the
default is the main section of mirror. NOTE: you can provide
multiple lines if each new line is indented with blank
spaces.
preferences
Preferences for target’s apt preferences file (see
apt_preferences(5)). NOTE: you can provide multiple lines if
each new line is indented with blank spaces. Multiple
apt_preferences stanzas are allowed provided that they are
separated by a line containing only a dot (".") and obviously
indented as specified above.
apt_conf Apt configuration for target’s apt.conf file (see
apt.conf(5)). The file will be created before installing
additional packages so it will be already effective then.
NOTE: you can provide multiple lines if each new line is
indented with blank spaces.
apt_force_yes
Will make rootstrap use the --force-yes switch to install
debian packages. This useful when you need to install
packages from sources that don’t use a Release.gpg file and
thus failing apt key authentication. It can be either true
or false and defaults to the former.
Be careful anyway as using this option "will cause apt to
continue without prompting if it is doing something
potentially harmful" (from apt-get(8)). This option is
provided standalone instead of forcing its inclusion in
apt_conf to avoid causing destructive actions later when
using apt-get from the UML instance.
Custom modules
Custom modules can very easily be used by rootstrap, in addition to (or
in place of) the supplied modules. See FILES below for locations that
are searched for modules.
When a module is invoked, the filesystem being created is mounted on
$TARGET, /dev, /etc and /tmp are tmpfs filesystems internal to the UML
system, while the root filesystem is a hostfs mount of the system where
rootstrap is running, to have access to the above shadowed directories
the full host filesystem is available on $HOST. /lib/modules is tmpfs
too and bind mounted to the host’s /usr/lib/uml/modules to let scripts
load necessary kernel modules. This means that most software on the
host system should be available and work as expected. The working
directory where rootstrap is run is available as $WORKDIR. The
environment is generated from the configuration file as described
above.
Be careful about modules ordering (see CONFIGURATION above), you’ll
mostly want to plug into the tweaking step to perform custom
configurations.
To debug modules enable the debug global parameter, see its description
fro more hints.
FILES
/etc/rootstrap/rootstrap.conf
System-wide default configuration
rootstrap.conf
Local overrides
/usr/lib/rootstrap/modules
Modules distributed with rootstrap
/etc/rootstrap/modules
System-wide overrides and additional modules
modules Local overrides and additional modules
SEE ALSO
debootstrap(8), apt_preferences(5), apt.conf(5), debconf(7), linux(1);
locally installed User-Mode Linux documentation or http://user-
mode-linux.sourceforge.net/ (link to URL http://user-mode-
linux.sourceforge.net/)
AUTHOR
Rootstrap was written by Matt Zimmerman mdz@debian.org
rootstrap(1)