MULTISTRAP(1)

📦 version 2.2.11, in debian bookworm, ubuntu jammy, ubuntu noble

✨ multistrap — multiple repository bootstraps 💖

okay bestie, welcome to MULTISTRAP(1), straight out of the User Contributed Perl Documentation section 🎀. This is the tool that builds you a whole root filesystem from multiple repos at once, and yes, she ate. Let's get into it 🌸

🌈 SYNOPSIS 🌈

multistrap [-a ARCH] [-d DIR] -f CONFIG_FILE
multistrap [--simulate] -f CONFIG_FILE
multistrap -?|-h|--help|--version

look at her. three little invocation lines, three little moods 💅

💅 OPTIONS 💅

  • -?, -h, --help, --version — spits out the help text and exits successfully, no cap. she's proud of herself and she should be ✨
  • --dry-run — collates every single configuration setting together and outputs a bare summary. like a lil vibe check on your config before you commit 🦋
  • --simulate — same as --dry-run. literally the same thing, different name, both iconic 👑
The following options can also be set in the configuration file. (so you can put them in the file or on the command line, your choice bestie 💖)
  • -a, --arch — the architecture of the packages that go into the multistrap.
  • -d, --dir — the directory the bootstrap gets installed into.
  • -f, --file — the configuration file for multistrap. this one is required, no skipping it 🚨
  • -s, --shortcut — a shortened version of -f, for files that live in known locations. lazy girl summer but make it efficient ✨
  • --tidy-up — removes apt cache data, the downloaded Packages files, and the apt package cache. same as cleanup=true. she's a cleaner 🧚
  • --no-auth — allows the use of unauthenticated repositories. same as noauth=true. (yes this is the "trust me bro" option, know what you're doing 💀)
  • --source-dir DIR — moves the contents of var/cache/apt/archives/ from inside the chroot out to the external directory you specify, then adds the Debian source packages for each used binary. same as retainsources=DIR.

if the specified directory does not exist, nothing is done — she's not gonna make it for you 🙈

this one requires --tidy-up in order to calculate the full list of source packages, including dependencies.

🌸 DESCRIPTION 🌸

multistrap gives you a debootstrap-like method based on apt, but extended so it can support multiple repositories — all of it driven by a configuration file that specifies the relevant suites, architecture, extra packages, and the mirror to use for each bootstrap. multi-repo main character energy 💖

the whole aim? build a complete bootstrap / root filesystem with all packages installed and configured — not just the base system. she does not do half measures, periodt ✨

in most cases, you're gonna need to make a configuration file for each different multistrap usage. here's an example configuration, bestie:

 [General]
 arch=armel
 directory=/opt/multistrap/
 # same as --tidy-up option if set to true
 cleanup=true
 # same as --no-auth option if set to true
 # keyring packages listed in each bootstrap will
 # still be installed.
 noauth=false
 # extract all downloaded archives (default is true)
 unpack=true
 # whether to add the /suite to be explicit about where apt
 # needs to look for packages. Default is false.
 explicitsuite=false
 # enable MultiArch for the specified architectures
 # default is empty
 multiarch=
 # aptsources is a list of sections to be used
 # the /etc/apt/sources.list.d/multistrap.sources.list
 # of the target. Order is not important
 aptsources=Debian
 # the bootstrap option determines which repository
 # is used to calculate the list of Priority: required packages
 # and which packages go into the rootfs.
 # The order of sections is not important.
 bootstrap=Debian

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

what you get from that is a completely normal bootstrap of Debian Jessie from the specified mirror, for armel, in '/opt/multistrap/' 🎀. (this exact configuration is retained in the package as /usr/share/multistrap/jessie.conf)

specify a package to extend the multistrap so it includes that package and all the dependencies of that package. 👑

specify more repositories for the bootstrap by adding new sections. the section names need to be listed in the bootstrap general option for the packages to actually be included in the bootstrap.

specify which repositories will be available to the final system at boot by listing those section names in the aptsources general option — like, e.g. to exclude some internal sources, or when you're using a local mirror while building the rootfs. 🌈

section names are case-insensitive. (all comparisons happen after conversion to lower case, so don't stress about your caps lock 💅)

all dependencies are resolved only by apt, using all bootstrap repositories, so you get only the most recent and most suitable dependencies. heads up though: multistrap turns off Install-Recommends, so if the multistrap needs a package that is only a Recommended dependency, you have to specify that recommended package in the packages line explicitly. see "Explicit suite specification" for more info on getting specific packages from specific suites.

'Architecture' and 'directory' can be overridden on the command line. some other general options also have command line options. 🦋

🌟 Online examples and documentation 🌟

multistrap supports a whole range of permutations, so go check the wiki and the emdebian website for more info and example configurations:

multistrap also includes an example configuration file with a full list of all supported config file options: /usr/share/doc/multistrap/examples/full.conf — go read it, it's giving reference material 📚

⭐ Shortcuts ⭐

in a similar manner to debootstrap, multistrap supports referring to configuration files in known locations via shortcuts. when you use the --shortcut option, multistrap will look for files in /usr/share/multistrap and then /etc/multistrap.d/, appending a '.conf' suffix to the shortcut you specified.

these two commands are equivalent:

 $ sudo multistrap -s sid
 $ sudo multistrap -f /usr/share/multistrap/sid.conf

note that multistrap will still fail if the configuration file itself does not set the directory or the architecture. she can't read your mind bestie 😭

💜 Repositories 💜

aptsources lists the sections which should be used to create the /etc/apt/sources.list.d/multistrap.list apt sources in the final system. not all aptsources have to appear in the bootstrap section — that's for when you have some internal or local sources that aren't accessible to the installed root filesystem. 🙈

bootstrap lists the sections which will be used to create the multistrap itself. only packages listed in bootstrap get downloaded and unpacked by multistrap. that's the rule 👑

make sure bootstrap lists all the sections you need for apt to be able to find all the packages to be unpacked for the multistrap. 🔥

(older versions of multistrap supported the same option under the debootstrap name — that spelling is still supported, but new configuration files should use bootstrap instead. legacy behavior, we love her but she's retired 💅)

🎀 General settings: 🎀

'arch' can be overridden on the command line using the --arch option.

'directory' specifies the top level directory where the bootstrap will be created — and note, it is not packed into a .tgz once complete.

'bootstrap' lists the Sections which will be used to specify the packages that will be downloaded (and optionally unpacked) into the bootstrap.

'aptsources' lists the Sections which will be used to specify the apt sources in the final system. like, e.g. if you need to use a local repository to generate the rootfs which won't be available to the device at runtime, list that section in bootstrap but not in aptsources.

if you want a package to be in the rootfs, it must be specified in the bootstrap list under General. no shortcuts ✨

the order of section names in either list is not important. 🌸

if markauto is set to true, multistrap will request apt to mark all packages specified in the combined packages list as manually installed, and all dependencies not explicitly listed as automatically installed in the APT extended state database. markauto can be used independently of unpack. 🦋

as with debootstrap, multistrap will continue after errors — as long as the configuration file can be correctly parsed. she's resilient like that 💪

multistrap also implements the machine:variant support originally used in Emdebian Crush, although in a different implementation. using the cascading configuration support, particular machine:variant combinations can be supported by simple changes on the command line. 👑

setting tarballname to true also packs up the final filesystem into a tarball. 📦

note that multistrap ignores any unrecognised options in the config file — this allows for backwards-compatible behaviour, as well as overloading the multistrap config files to support other tools (like pbuilder). use the --simulate option to see the combined configuration settings. 🧚

however — if the config file itself cannot be parsed, multistrap will abort. check that the config file has a key and a value for each line, other than comments. values must all be on the same line as the key. that's the dealbreaker, bestie 💀

🌈 Section settings 🌈

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

the section name (in [] brackets) needs to be unique for this configuration file and for any configuration files which this file includes. section names are case insensitive (all comparisons happen after conversion to lower case). 💅

'packages' is the list of packages to be added when this Section is listed in bootstrap — all package names must be listed on a single line, or the file will fail to parse. 😭

one alternative is to define your list of packages as multiple groups, with packages separated on a functional / dependency basis — like, e.g. base, Xorg, networking, etc. — and list each group under 'bootstrap'. that's the organized-girl method 🎀

 bootstrap=base networking

 [base]
 packages=udev mtd-utils
 source=http://http.debian.net/debian
 keyring=debian-archive-keyring
 suite=jessie

 [networking]
 packages=netbase ifupdown iproute net-tools samba
 source=http://http.debian.net/debian
 keyring=debian-archive-keyring
 suite=jessie

as a special case, multistrap also supports multiple packages keys per section — one line for each. other keys cannot be repeated in this manner. only packages gets to do that, she's the favorite 💖

 [Emdebian]
 packages=udev mtd-utils netbase ifupdown iproute
 packages=busybox net-tools samba
 source=http://http.debian.net/debian
 keyring=debian-archive-keyring
 suite=jessie

'source' is the apt source to use for this Section. if you want to use a local source on the same machine, make sure you use copy:// and not file:// — that way apt is told to copy the packages into the rootfs instead of assuming it can try to download them later, because that "later" will never actually happen bestie 🙈💀

'keyring' lists the package which contains the key used by the source listed in this Section. if no keyring is specified, the noauth option must be set to true. see Secure Apt. 🔐

'suite' is the suite to use from this source. note that this should be the suite, not the codename. ✨

suites change from time to time: (oldstable, stable, testing, sid) — but the codename (squeeze, wheezy, jessie, sid) does not change. iykyk 👑

🔐 Secure Apt 🔐

okay so bestie, if you wanna use authenticated apt repositories, multistrap needs to be able to install an appropriate keyring package from the existing apt sources outside the multistrap environment into the destination system. ✨

and here's the annoying part, lowkey: those keyring packages cannot be downloaded from the repositories specified in the multistrap configuration — and that's because "apt" needs the keyring to be updated before it can even use repositories it didn't previously know about. it's giving chicken-and-egg 😭

so if relevant packages exist, you specify them in the 'keyring' option for each repository. multistrap will then check that apt has already installed this package so that the repository can be authenticated before any packages are downloaded from it. 🫶

note that all repositories to be used with multistrap must be authenticated or apt will fail. similarly, secure apt can only be disabled for all repositories (by using the --no-auth command line option or setting the general noauth option in the configuration file), even if only <em>one</em> repository doesn't have a suitable keyring available. yeah. all or nothing, periodt.

the keyring package(s) will also be installed inside the multistrap environment to match the installed apt sources for the multistrap. 💅

🌀 State 🌀

multistrap is stateless — if the directory exists, it will simply proceed as normal and apt will try to pick up where it left off. no drama, no memory, just vibes and resumption. 💫

🌱 Root Filesystem Configuration 🌱

multistrap unpacks the downloaded packages but other stages of system configuration are not attempted. examples include:

 /etc/inittab
 /etc/fstab
 /etc/hosts
 /etc/securetty
 /etc/modules
 /etc/hostname
 /etc/network/interfaces
 /etc/init.d
 /etc/dhcp3

any device-specific device nodes will also need to be created using MAKEDEV or "device-table.pl" — a helper script that can work around some of the issues with MAKEDEV. device-table.pl requires a device table file along the lines of the one in the mtd-utils source package. see /usr/share/doc/multistrap/examples/device_table.txt 👀

once multistrap has successfully created the basic file and directory layout, other device-specific scripts are needed before the filesystem can be packaged up and installed onto the target device. like, it's not done-done yet bestie, there's more steps 🧚

once installed, the packages themselves need to be configured using the package maintainer scripts and "dpkg --configure -a", unless this is a native multistrap.

for "dpkg" to work, /proc and /sysfs must be mounted (or mountable), and /dev/pts is also recommended. 💜

see also: http://wiki.debian.org/Multistrap

🌸 Environment 🌸

to configure the unpacked packages (whether in native or cross mode), certain environment variables are needed:

debconf needs to be told to accept that user interaction is not desired:

 DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true

perl needs to be told to accept that no locales are available inside the chroot and not to complain:

 LC_ALL=C LANGUAGE=C LANG=C

then, dpkg can configure the packages:

chroot method (PATH = top directory of chroot):

 DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
 LC_ALL=C LANGUAGE=C LANG=C chroot /PATH/ dpkg --configure -a

at a login shell:

 # export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true
 # export LC_ALL=C LANGUAGE=C LANG=C
 # dpkg --configure -a

(as above, dpkg needs /proc and /sysfs mounted first.) 🫠

🦋 Native mode - multistrap 🦋

multistrap was <em>not</em> intended for native support — it was developed for cross architecture support. in order for multiple repositories to be used, multistrap only unpacks the packages selected by apt.

in native mode, various post-multistrap operations are likely to be needed that debootstrap would do for you:

  1. copy /etc/hosts into the chroot
  2. clean the environment to unset LANGUAGE, LC_ALL and LANG to silence nuisance perl warnings that obscure other errors

(an alternative to unset the localisation variables is to add locales to your multistrap configuration file in the 'packages' option.

a native multistrap can be used directly with chroot, so "multistrap" runs "dpkg --configure -a" at the end of the multistrap process, unless the ignorenativearch option is set to true in the General section of the configuration file. 💅)

👑 Daemons in chroots 👑

depending on which system you using to provide the packages for "multistrap", native chroots should generally not allow daemons to start inside the chroot. use /usr/share/multistrap/chroot.sh as your "setupscript" or include that script in your own setup script.

 setupscript=/usr/share/multistrap/chroot.sh

chroot.sh copes with systems using sysvinit and upstart. ⭐

see also

 http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt

🌈 Cascading configuration 🌈

to support multiple variants of a basic (common) configuration, "multistrap" allows 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. it's giving family tree of configs 🌳

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. iconic, honestly.

it is strongly recommended that any changes to the configuration files involved in any particular cascade are tested using the "--simulate" option to multistrap which will output a summary of the options that have been set once the cascade is complete. note that multistrap does not warn you if a configuration file contains an unrecognised option (for future compatibility with backported configurations), so a simple typo can result in an option not being set. 💀 typos are silent killers bestie, use --simulate.

🎀 Machine:variant support 🎀

the old packages.conf variables from emsandbox can all be converted into "multistrap" configuration variables. the machine:variant support in "multistrap" concentrates on the scripts, config.sh and setup.sh

note: machine:variant support is likely to be replaced by the hook functionality described below. ⚠️

once "multistrap" has unpacked the downloaded packages, the "setup.sh" can be called, passing the location and architecture of the root filesystem, so that other fine tuning can take place. at this stage, any operations inside a foreign architecture rootfs must not try to execute any binaries within the rootfs. as the final stage of the multistrap process, "config.sh" is copied into the root directory of the rootfs. 🫶

one advantage of using machine:variant support is that the entire rootfilesystem can be managed by a single call to multistrap — this is useful when building root filesystems in userspace.

to enable machine:variant support, specify the path to the scripts to be called in the variant configuration file (General section):

 [General]
 include=/path/to/general.conf
 setupscript=/path/to/setup.sh
 configscript=/path/to/config.sh

ensure that both the setupscript and the configscript are executable or "multistrap" will ignore the script. 🙈

✨ Example configscript.sh ✨

 #!/bin/sh

 set -e

 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
 umount /proc

for more information, see the Wiki: http://wiki.debian.org/Multistrap

🌟 Mounting /dev and /proc for chroot configuration 🌟

/proc can be mounted inside the chroot, as above:

 mount proc -t proc /proc

however, /dev should be mounted from outside the chroot, before running any "configscript.sh" in the chroot:

 cd /path/chroot/
 sudo tar -xzf /path/multistrap.tgz
 sudo mount /dev -o bind ./dev/
 sudo chroot . ./configscript.sh || true

🍓 Restricting package selection 🍓

"multistrap" includes Required packages by default, the current list of packages on your own machine can be seen using:

 grep-available  -FPriority 'required' -sPackage

(the actual list is calculated from the downloaded Packages files and may differ from the output of "grep-available".)

if the OmitRequired option is set to true, these packages will not be added — whilst useful, this option can easily lead to a useless rootfs. only the packages specified manually in the configuration files will be used in the calculations — dependencies of those packages will be added but no others. 😭

⭐ Adding Priority: important packages ⭐

"multistrap" can imitate "debootstrap" by automatically adding all packages from all sections where the downloaded Packages file lists the package as Priority: important. the default is <em>not</em> to add such packages unless individually included in a "packages=" option in a section specified in the "bootstrap" general option. to add all such packages, set the addimportant option to true in the general section.

 addimportant=true

Priority: important can only operate for all sections listed in the "bootstrap" option. this may cause some confusion when mixing suites. 🌀

it is not possible to enable addimportant and omitrequired in the same configuration. "multistrap" will exit with error code 7 if any configuration results in addimportant and omitrequired both being set to true. (this includes the effects of including other configuration files.) 💀

💜 Recommends behaviour 💜

the Debian default behaviour after the Lenny release was to consider recommended packages as extra packages to be installed when any one package is selected. recommended packages are those which the maintainer considers that would be present on "most" installations of that package and allowing Recommends means allowing Recommends of recommended packages and so on. it's giving recursion, but make it packages 🌈

the multistrap default is to turn recommends OFF. 🙅

set the allowrecommends option to true in the General section to use typical Debian behaviour. ✨

🌸 Default release 🌸

okay so multistrap has an option that lets you explicitly set the default release apt should use: aptdefaultrelease. bestie, this decides which release apt reaches for when it's grabbing the base system packages — and no, it is not the same thing as pinning (pinning is about how apt behaves after installation, iykyk). By default multistrap sets the default-release to the wildcard * unless you name a release in the aptdefaultrelease field. and heads up: any release you name here must also be defined in a stanza that's referenced in the bootstrap list, or apt will straight up fail. 😭

So if you wanna install a specific version of a package from a newer release than the one you set as default, you also need explicitsuite set to true — but only if that package exists at any version in the default release. Also (and this is the part that gets people 💀): any packages that package has a strict dependency on (like = rather than >=) have to be explicitly added to the packages line in the stanza for the version you want, even though that package doesn't need to be listed to grab it from the default release. This is just typical apt behaviour, fr fr — it is not a bug in multistrap.

The combo of default release + explicit suite + apt preferences can get complex fast, and bugs from it can be genuinely impossible to spot. So multistrap always prints out the complete apt command line — like, go test that command yourself (using the files multistrap wrote out) to see what's actually going on. Remember: all dependency resolution and all the logic deciding which version of a specific package lands in your multistrap chroot is entirely apt's business. All multistrap can do is hand files and command line options over to apt. periodt. 💅

See also: apt preferences.

✨ Explicit suite specification ✨

Sometimes apt needs to be told to grab a particular package from a particular suite, ignoring a more recent version sitting in another suite within the same set of sources.

multistrap works both with and without the explicit suite option. Default behaviour is letting apt use the most recent version from the collection of specified bootstrap sources. 🦋

Now, real talk: explicit suite specification has no effect on the final installed system. If your aptsources includes a repository that itself includes a newer version of the explicitly specified package(s), the very next apt-get upgrade on the device will pull in that newer version. so yeah, that's a thing. 🙈

Also, when you tell apt to grab packages from a specific suite, apt will also try to make sure that package's dependencies come from the same suite — and this can make apt unable to resolve the complete dependency set. In that situation, being explicit about one package selection might mean you have to be explicit about some (not necessarily all) of that package's dependencies too.

When you're using explicitsuite, be careful with stable-proposed-updates or other temporary locations — if the package migrates into another suite and gets removed from the temporary one (as happens with *-proposed-updates), multistrap won't be able to find the package at all. 😭

Explicit suite handling is really hard to get right. In general, the move is: make a small bootstrap chroot of your native arch, chroot into it, add the relevant apt sources, and work out exactly which commands are needed to get the right mix of packages. Avoid specifying explicit versions to sort out problems — work with suites only. Apt preferences / pinning might be useful here, see Apt preferences. 💖

🎀 Apt preferences 🎀

If a suitable file is listed in the aptpreferences option of the General section of the config file, that file gets copied into the apt preferences directory of the bootstrap before apt is first used.

When an apt preferences file is provided, the Default-Release behaviour of multistrap is disabled. 👑

And like with other external scripts and files, the content of the apt preferences file is beyond the scope of this manpage. multistrap doesn't try to verify the supplied file either — it only makes sure it can be read. that's it, that's the whole vibe check.

🌈 Omitting deb-src listings 🌈

Some multistrap environments don't need access to the Debian sources of the packages being installed — typically this is what you want when preparing a build (or cross-build) chroot using multistrap.

To turn off this additional source (and save both download time and apt-cache size), use the omitdebsrc field in each Section. ✨

 [Baked]
 packages=
 source=http://www.emdebian.org/baked
 keyring=emdebian-archive-keyring
 suite=testing
 omitdebsrc=true

omitdebsrc is necessary when using packages from debian-ports, where packages don't have sources — except unreleased.

🧚 fakeroot 🧚

Foreign architecture bootstraps can operate under fakeroot (and multistrap is designed to do as much as it can within a single call to make that easier 🫶), but the configuration stage — which normally happens with a native architecture bootstrap — requires chroot, and chroot itself will not operate under fakeroot.

So if multistrap detects that fakeroot is in use, native mode configuration is skipped, with a reminder warning. 🌸

The exact same problem applies to apt-get install, which means installing the keyring package on the host system is also skipped if fakeroot is detected.

💜 Handling problematic packages 💜

Sometimes a particular package will fail to even unpack properly if other packages haven't already been unpacked. This can happen when dpkg diversions aren't set up correctly, or if the package Pre-Depends on an executable that lives in another package.

multistrap offers two ways to handle these problems. A package can be listed as reinstall or as additional. Each section in the multistrap configuration file can have a single reinstall or additional listing — or both. 💅

Reinstall means the package will be downloaded and unpacked as normal — alongside all the other packages — but will then be reinstalled at the end by running the preinst maintainer script with the upgrade argument. dpkg will then continue the rest of the configuration of that package.

Additional adds a second round of apt-get install to the multistrap process — after the initial unpacking. The additional package then gets downloaded and unpacked. If running natively, the additional package is downloaded, unpacked and configured after all the rest of the packages have been downloaded, unpacked and configured.

Neither reinstall nor additional should be seen as anything more than workarounds 😬 — and wishlist bugs should be filed in Debian against the packages which require these mechanisms (or against the packages which would prevent the particular package from operating normally).

🍓 Debconf preseeding 🍓

Adding a debconf seed can help configure packages to a particular setting instead of the package default, which matters when the configuration runs non-interactively. See http://www.debian-administration.org/articles/394 for info on how to create seed files. 🦋

Multiple seed files can be specified with the debconfseed field in the [General] section, separated by spaces:

 debconfseed=seed1 seed2

Files that don't exist or can't be opened are silently ignored 🙈. Check the results of the parsing using the --simulate option to multistrap. The preseeding files get copied to a preseed directory in /tmp inside the rootfs.

To actually use the preseeding, add a section to the configscript.sh, before any calls to dpkg --configure -a. like, e.g. :

 #!/bin/sh

 set -e

 export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true
 export LC_ALL=C LANGUAGE=C LANG=C
 if [ -d /tmp/preseeds/ ]; then
    for file in `ls -1 /tmp/preseeds/*`; do
    debconf-set-selections $file
    done
 fi
 dpkg --configure -a

🌟 Hooks 🌟

If a hook directory (hookdir=) is specified in the General section of the multistrap configuration file, the hook scripts which are executable will be run from outside the multistrap directory, at these stages:

💫 download hooks 💫

Executed before unpacking is started, immediately after the packages have been downloaded. Download hooks are executable scripts in the specified hook directory with a filename beginning with download.

💫 native hooks 💫

Native hook scripts are executed only in native mode — immediately before starting the configuration of the downloaded packages, and again upon completion of the package configuration. Native hooks get called with the absolute path and the current progress state, start or end.

Native scripts are executable scripts in the specified hook directory with a filename beginning with native.

💫 completion hooks 💫

Executed immediately before the tarball is created, or before multistrap exits if it isn't configured to create a tarball.

Completion scripts are executable scripts in the specified hook directory with a filename beginning with completion.

Hooks are passed the absolute path to the directory which will be the top level directory of the chroot or multistrap system. Hooks that can't be resolved using realpath, or which aren't executable, will be ignored.

All hooks of one type get sorted into alphabetical order before they're run. 🔤

Note that multistrap does not rollback the effects of hooks if errors happen. However, multistrap will report the accumulated errors as warnings. If a hook exits non-zero, the exit value is converted to a positive number and added to the total warning count, which is reported at the end of the operation. 💀

👑 Output 👑

multistrap can produce a lot of output — informational messages go to STDOUT, errors and warnings go to STDERR. Calls to apt and dpkg respect that same pattern, so trimming the combined multistrap output down to just the errors is simple if that's what you want. 💅

multistrap accumulates error states from non-fatal processes within the operation and reports those as warnings on STDERR, as well as exiting with the accumulated error count. This includes hooks which report non-zero exit values.

😭 Bugs 😭

As multistrap gets more complex, bugs will creep into the package. Please report all bugs to the Debian BTS using the reportbug tool, and please attach all configuration files. If your config needs to access local or private apt repositories, please check your config with the latest version of multistrap in Debian using the --simulate option, and include that report in your bug report. 🫶

The --simulate option output is regularly expanded to help users debug problems in configuration files.

Please also check (and update) the Multistrap wiki at http://wiki.debian.org/Multistrap and the Multistrap webpage content at http://www.emdebian.org/multistrap/ before filing bugs. Various people on the debian-embedded@lists.debian.org mailing list and the #emdebian IRC channel on irc.oftc.net can help too, if your config file doesn't parse correctly. You'd need to put the --simulate output on a pastebin website and drop the URL in your message. ✨

✨ MultiArch support ✨

okay bestie, real talk time: MultiArch support is experimental. Like, it's giving "we're trying something, be nice" energy. Please report issues and file bugs with full details of your setup, the full multistrap config file, and the errors that got reported. The more deets you drop, the more we can actually help. 🫶

multistrap overrides the existing multiarch support of the external system, so that a MultiArch aware system can still create a non-MultiArch chroot from repositories which do not support all of the architectures supported by the external dpkg. Iconic behaviour, honestly.

If multiarch is enabled within the multistrap chroot, multistrap writes out the list into /var/lib/dpkg/arch inside the chroot. That's the receipt. 🧾

For multiple architectures, specify the option once and use a space separated list for the architecture list. And bestie, please — ensure you include what will be the host architecture of the chroot. Don't forget it, it matters. 👑

See also http://wiki.debian.org/Multiarch/

[General]
...
multiarch=i386 armel armhf

Each Section will install packages from the base architecture unless the Architecture option is specified for particular sections. So you can absolutely mix it up. 💅

[Foreign]
packages=libgcc1 libc6
architecture=armel
source=http://ftp.uk.debian.org/debian
keyring=debian-archive-keyring
suite=sid

In the --simulate output, the architecture(s) specified in the MultiArch option will be listed under the "Foreign architectures" listing. And packages for a specific architecture will be listed as the package name followed by a colon followed by the architecture, like:

libgcc1:armel libc6:armel

and that's the whole page, bestie!! you made it to the end 🎀 This one came from perl v5.30.0, dated 2020-03-22, and it lives at MULTISTRAP(1). Go build something slay with it. periodt. 💖✨🦋

📦 where this page comes from