Background

Multistrap is a tool that does essentially the same job as debootstrap, using an entirely different method, and then extends the functionality to support automated creation of complete, bootable, root filesystems. It can merge packages from different repositories to make the rootfs. Extra packages are added to the rootfs simply by listing them - all dependencies are taken care of. Current development in multistrap is to support user-specified scripts being added as hooks during the unpacking phase to add customised startup scripts and configure things like device nodes.

It was designed primarily for making root filesystems for foreign architecture embedded systems, but in fact can be used for many tasks where one might also use debootstrap.

Its main limitation compared to debootstrap is that it uses apt and dpkg directly so can only work on a debian system - debootstrap depends on nothing but shell, wget, binutils and thus can run pretty-much anywhere.

The main advantage with multistrap is the flexibility to mix packages from different repositories and different suites and manage customised variants with configuration files.

Use

Multistrap is available in squeeze or later. It is written in Perl and uses apt to chose a requested set of packages and their dependencies, then unpack (but not configure) those packages. This leaves a rootfs which just needs to be mounted (or chrooted) and configured with dpkg --configure -a.

Because it uses apt, the mixing of multiple repositories is automatic and apt features such as the use of proxies are all available.

For embedded use some modification to the generated rootfs are often needed in order to make it bootable enough to be configured. An example is given below of a script to do this. See Customising Rootfs below. Development is ongoing to incorporate such support into hooks which can be called during the multistrap operation.

Manpage

MultistrapManPage

Options

You can choose to keep a copy of all the debs downloaded during the process (by setting the retainsources option to be the path in which they should be stored. This is the binary packages downloaded, not the corresponding sources. But does mean you have a cache of the stuff you made your rootfs with.

Syntax

Basic syntax is:

multistrap [-a arch] -d [dir] -f config_file

nearly all the config is done in the config_file

Configuration

You need a config file which contains at least one repository stanza, like:

[Grip]
packages=ntpdate udev lrzsz netcat telnetd
source=http://www.emdebian.org/grip
keyring=emdebian-archive-keyring
suite=lenny

And you need to list that stanza title ('Grip') in the 'aptsources' line. And specify one repository in the debootstrap line, which is used as the 'main' repository, from which the list of 'priority: Required' packages is taken.

A directory in which to prepare the rootfs, and an arch to use are the last two items (which can be specified on the command line).

Here is a minimal example, which just does makes a normal Debian rootfs. use a command like: sudo multistrap -a armel -d /multistrap-debian-lenny -f simple-config

simple-config

[General]
unpack=true
bootstrap=Grip
aptsources=Debian

[Grip]
packages=ntpdate udev lrzsz netcat telnetd
source=http://www.emdebian.org/grip
keyring=emdebian-archive-keyring
suite=lenny

[Debian]
packages=
source=http://ftp.uk.debian.org/debian
keyring=debian-archive-keyring
suite=lenny

Grip/Debian example

Here is an example for an arm embedded system (balloonboard), where the rootfs is an emdebian Grip base, augmented by security updates, some extra packages from debian proper and some local packages from an internal repository.

Use it with a command like sudo multistrap -f grip-config

[General]
# arch and directory can be specified on the command line.
arch=armel
directory=/opt/multistrap/
# same as --tidy-up option if set to true
cleanup=true
# retain the sources outside the rootfs for distribution
# specify a directory to which all the .debs can be moved.
# or override with the --source-dir option.
retainsources=
# same as --no-auth option if set to true
# keyring packages listed in each debootstrap will
# still be installed.
noauth=true
# retries not needed.
#retries=5
# extract all downloaded archives
unpack=true
# the order of sections is no longer important.
# debootstrap determines which repository is used to
# calculate the list of Priority: required packages
bootstrap=Grip Updates
# the order of sections is no longer important.
# aptsources is a list of sections to be listed
# in the /etc/apt/sources.list.d/multistrap.sources.list
# of the target.
aptsources=Grip Updates Debian

[Grip]
packages=ntpdate udev lrzsz netcat telnetd
source=http://www.emdebian.org/grip
keyring=emdebian-archive-keyring
suite=lenny

[Updates]
packages=apt
source=http://www.emdebian.org/grip
keyring=emdebian-archive-keyring
suite=lenny-proposed-updates

# fallback
[Debian]
packages=
source=http://ftp.uk.debian.org/debian
keyring=debian-archive-keyring
suite=lenny

Package selection by Priority

debootstrap and cdebootstrap select all packages with Priority: required and Priority: important from the Debian mirror by default.

Multistrap selects only Priority: required by default, and even that can be turned off by setting omitrequired=true in [General] section of the config file and then individually specifying all of the Priority: required packages which you do want installed.

grep-available  -FPriority 'required' -sPackage
grep-available  -FPriority 'important' -sPackage

Note that the individual selection of required packages can lead to untested combinations and configurations. Take particular care with packages flagged as Essential: yes as these packages will not be listed as dependencies in most packages but will cause the system to fail entirely if omitted.

It is generally useful to test such configurations with your native architecture to at least ensure that the combination can be installed and that normal chroot operations can at least be performed.

Creating device nodes from a device table file

DeviceTableScripting allows multistrap to create device nodes from a simple device table text file.

Components support

Emdebian Grip dropped components with the Wheezy Grip 3.0 release. If you are using Squeeze Grip, 2.0, please read about Multistrap/ComponentSupport for more information on how to mix development, java, documentation or debug packages with an Emdebian Grip base package set.

Customisation

Multistrap/CustomisingRootfs

Debugging package selection failures

Multistrap can report failure messages when apt is unable to resolve the entire dependency chain. It is not a bug in multistrap when this happens - the problem lies in the selection of packages and the mix of suites involved. There are various methods to debug such situations:

  1. Mimic the call to apt - in the multistrap output, above the failure message, is a long line of commands to apt-get. Copy that entire line into an editor. Re-run the multistrap command with cleanup set to false to preserve the apt sources list and apt data, then run the entire apt-get command manually. This is now a normal apt debugging problem and relies on picking out which packages are actually causing the problem rather than those which are being ruled out by apt as a result of the problem. Somewhere in the dependency chain, you will find a package or a couple of packages which cannot be installed using the apt sources you have specified in your bootstrap instruction. Once you know which packages causing the problem, try to explicitly install only those packages using the same apt-get command. Use Ctrl-C to halt apt if you pick the wrong ones. You can continue to debug the problem by editing the long command to be a call to apt-cache options policy package to see why apt is preferring a particular version of a package.

  2. Switch to the native architecture - trim down your package selection to the base package set (i.e. with only apt listed in the packages field for any included section) and create a temporary chroot on your desktop / laptop machine. In the adapted configuration, ensure that your aptsources line matches your bootstrap line even if your final installation would differ. Also change cleanup to false. chroot into the new directory and then use apt to see what the problems are with your package selection by individually trying to install each one using the apt sources which you are expecting apt to use in the bootstrap phase of your original config.

  3. Use components - if you have an Emdebian base package set and then try to add build tools and/or development packages from Debian, you will need to take account of Multistrap/ComponentSupport and how Emdebian divides up the archive for development, debug, java and documentation packages.

  4. Note that explicitsuite is hard to get right. Think carefully about which packages are listed for which sections as every package in that section must be available at an installable version in the suite specified in that section. Sometimes, dependencies need to be specified explicitly, even when such dependencies would not be necessary without explicitsuite. When there are problems, use a native architecture, comment out some packages and work out what is needed by building the chroot with a partial package list then work inside the chroot to see what apt actually wants to get the selection you want.

Flat file archives

To use multistrap with flat file archives (e.g. those created by mini-dinstall or some Ubuntu PPA repositories), see Multistrap/FlatFileArchives

MultiArch support

Multistrap checks your version of dpkg to see if multiple architectures can be supported in /etc/dpkg/dpkg.cfg.d/ and disables the relevant support if not found. You can check your own system with the same test:

dpkg --print-foreign-architectures ; echo $?

Zero on success, non-zero on error.

Details of MultiArch support

Debconf and pre-seeding

See Debconf preseeding support

Steps for Squeeze and later

Inside the chroot (using qemu-static or after booting and using chroot, as appropriate):

/var/lib/dpkg/info/dash.preinst install

A configscript which can be used with multistrap to do the configuration could look like:

export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true
export LC_ALL=C LANGUAGE=C LANG=C
/var/lib/dpkg/info/dash.preinst install
dpkg --configure -a
mount proc -t proc /proc
dpkg --configure -a

Environment

Multistrap/Environment

Native handling

Multistrap/NativeHandling

Cross chroot preparation

Multistrap in Debian experimental is being extended to allow the creation of a cross-building chroot which is compatible with pbuilder. The principle is to add toolchain packages from the Emdebian repositories and then add hooks to pbuilder which can set up the cross-dependencies.

Partial Mirrors

Multistrap/PartialMirrors

Cascading configuration

To support multiple variants of a basic (common) configuration, multistrap is also being extended to allow configuration files to include other (more general) configuration files. i.e. the most detailed / specific configuration file is specified on the command line and that file includes another file which is shared by other configurations.

Base file:

/usr/share/multistrap/crosschroot.conf

Variations:

/usr/share/multistrap/armel.conf

Specifying just the armel.conf file will get the rest of the settings from crosschroot.conf so that common changes only need to be made in a single file.

See also http://www.emdebian.org/multistrap/cascades.html

For discussion about these features, ask on the debian-embedded mailing list.

Troubleshooting

Package configuration of dash fails with a dpkg-divert error

During package configuration, if you get an error like:

# dpkg --configure dash
Setting up dash (0.5.5.1-7.4em1) ...
No diversion 'diversion of /bin/sh by dash', none removed.
This should never be reached
dpkg: error processing dash (--configure):
 subprocess installed post-installation script returned error exit status 1
Errors were encountered while processing:
 dash

You probably forgot to manually run dash preinst script. See section #Steps_for_Squeeze_and_later

Patch Policy

  1. Never include whitespace changes, this is not python, there is no equivalent to PEP8.
  2. Never include stylistic changes - the current style of multistrap is the authoritative style for multistrap code, even if it is inconsistent in places.
  3. Each patch needs to be a single functional change, across multiple files where appropriate. Never include unrelated changes in a single patch.
  4. Each patch must be fully documented so that the reason for each change is clear. Bug reports in the Debian BTS are strongly recommended before existing functionality is changed or new functionality introduced.
  5. Do not remove existing functionality or introduce changes which make existing functionality inoperative.
  6. Documentation changes only to be made for changes in behaviour introduced via the functional changes already covered in a different patch.
  7. Never move or rename files.
  8. All patches must be against current SVN and rebased and resubmitted upon request.
  9. Translations are not encouraged outside of a translation request made on the debian-l10n mailing list.
  10. All translation changes need to be as bugs in the Debian BTS and the entire PO file must always be attached to the bug. Patches to a .po file are never acceptable. All .po changes must result in 100% of strings being translated with no fuzzy translations and no missing strings. All .po changes must be valid according to msgfmt -c.
  11. Send patches to the maintainer directly, not a mailing list. As above, using the Debian BTS is strongly recommended to ensure that patches are not forgotten or lost.


CategoryEmdebian