You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
josch 7dcf15a5f5 resolve conflict 10 years ago
beagleboard add beagleboard, minimal, routerstationpro 10 years ago
default resolve conflict 10 years ago
goldel-gta04 add proot support 10 years ago
kirkwood add proot support 10 years ago
minimal add beagleboard, minimal, routerstationpro 10 years ago
notioninkadam add proot support 10 years ago
om-gta02 add proot support 10 years ago
routerstationpro add beagleboard, minimal, routerstationpro 10 years ago
touchbook add proot support 10 years ago
.gitignore initial commit 13 years ago
README update README 12 years ago
TODO add proot support 10 years ago
polystrap-nb polystrap-nb: error messages reviewed 13 years ago add proot support 10 years ago


Polystrap is a tool to create a foreign architecture rootfs without needing
superuser privileges by using multistrap, fakeroot, fakechroot and qemu user
mode emulation from the qemu-user package.


qemu >= 1.0 is required for this to work out of the box. For older qemu
versions, the (now outdated) instructions in the rest of this section:

To make qemu user mode emulation work you need to install the packages
qemu-user and binfmt-support. Until bug #632192 is fixed you will have to
provide properly filled /etc/qemu-binfmt/$arch/ directories. $arch is a qemu
arch (eg: arm for arm, armel and armhf). "properly filled" means, that you have
to provide a root directory tree in that directory that fits the architecture
you want to bootstrap debian for. There are a couple of ways to achieve that:

1. manually download and `dpkg -x` the required packages into

2. copy over a just extracted multistrap run for your target system into

3. run the following multistrap.conf, configured for your target system to
create a root directory tree that you copy into /etc/qemu-binfmt/$arch/


packages=libc6 libselinux1 libacl1 man-db libstdc++6 libfreetype6 libx11-6 libfontconfig1

You can also avoid all this trouble by either waiting for #632192 to be fixed
or by applying the patch from there to qemu.

Since support for QEMU_LD_PREFIX has now been added upstream it is now already
part of


Additionally you will need to have copies of and for your target architecture in /usr/lib/<arch-triplet>/.
Get the debian packages of fakeroot and fakechroot for your target architecture
and copy the shared libraries into /usr/lib/<arch-triplet>/. For example for
armel do:

sudo mkdir -p /usr/lib/arm-linux-gnueabi/
dpkg-deb --fsys-tarfile fakeroot_1.14.5-1_armel.deb | sudo tar -xf - --strip-components=4 -C /usr/lib/arm-linux-gnueabi/ ./usr/lib/libfakeroot/
dpkg -x libfakechroot_2.15-1_armel.deb /

Alternatively, since libfakechroot is multiarch you can also do:

apt-get install libfakechroot:armel

if your system supports it instead of the last two lines.


While I wanted to build without superuser privileges, multistrap would never
offer mechanisms that would allow me to do so. Hence I wrote this script which
wraps multistrap. Since I wanted to keep it as simple as possible, a fully
functional polystrap will need nothing more than a multistrap.conf, a hooks
directory and a rootfs tree skeleton. Stuff like packages directory, and config
file are optional and can be replaced by editing multistrap.conf and passing
commandline options. Without comments the scripts is currently around 120 lines
and I have no intention to make it much more complex.

Polystrap is invoked as such:


BOARD is a directory that at least contains a multistrap.conf. The
multistrap.conf may contain variables from

In the normal case BOARD will contain some additional bits.

	BOARD/config - A file that is sourced by ./ and
	                  contains variable declarations like:
	                      SUITE   - stable, testing, unstable
	                      ARCH    - armel, armhf, amd64, i386
	                      ROOTDIR - where the rootfs is created
	                      MIRROR  - debian mirror to use for packages
	                  The file is not strictly needed because the options
	                  can also be set by commandline arguments and the
	                  script will fall back to ./default/config.
	                  Correct settings for ARCH and ROOTDIR are necessary
	                  for proper operation, whereas other parameters are
	                  only used if your multistrap.conf references them.
	BOARD/debconfseed.txt - as the name suggests
	BOARD/hooks  - A directory that contains files that are sourced by
	                  polystrap after packages are installed.
	BOARD/packages - Contains files with one debian package per line.
	                    Grouping packages by that allows easier selection.
	BOARD/root   - Contains a rootfs tree that is copied to the target
	                  directory after packages are unpacked by multistrap.

Reasonable examples of how those pieces look like can be found in the defaults

Everything from the BOARD/config file can be overwritten by commandline

	-s suite
	-a arch
	-d rootdir
	-m mirror
	-v verbose (set -x)
	-f force (overwrite existing directories)

Additionally the following option allows to specify a list of packages that is
then used instead of the contents of the BOARD/packages directory:

	-p packages

How the script works:

 *) re-execute itself in fakeroot
 *) source default/config
 *) source BOARD/config
 *) determine package selection by BOARD/packages or commandline argument
 *) create multistrap.conf in /tmp from BOARD/multistrap.conf
 *) run multistrap
 *) copy contents of BOARD/root
 *) copy qemu usermode binary
 *) set debconf selections
 *) run preinst scripts
 *) configure packages
 *) source BOARD/hooks
 *) cleanup
 *) generate tarball

When creating a directory for a new target one can either just copy the defaut
directory or use the ./ script which will use symlinks where it
makes sense, will not copy the whole package selection and will set hostname
according to the target name.