Ubuntu Manpage: rootstrap — Construct a root filesystem image in a file

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

AUTHOR

       Rootstrap was written by Matt Zimmerman mdz@debian.org

                                                                                     rootstrap(1)