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