---
name: "rootstrap"
section: "1"
platform: "linux"
package: "rootstrap"
version: "0.3.25-1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/rootstrap"
---

# rootstrap(1)

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)](/chroot/2.md)  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)](/apt_preferences/5.md)).  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)](/apt.conf/5.md)). 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)](/apt-get/8.md)). 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)](/debootstrap/8.md)**,  **[apt\_preferences(5)](/apt_preferences/5.md)**,  **[apt.conf(5)](/apt.conf/5.md)**,  **[debconf(7)](/debconf/7.md)**,  **[linux(1)](/linux/1.md)**;  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