Provided by: multistrap_2.1.6ubuntu3_all bug

Name

       multistrap - multiple repository bootstraps

Synopsis

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

Options

       -?|-h|--help|--version - output the help text and exit successfully.

       --dry-run - collate all the configuration settings and output a bare
       summary.

       --simulate - same as --dry-run

       (The following options can also be set in the configuration file.)

       -a|--arch - architecture of the packages to put into the multistrap.

       -d|--dir - directory into which the bootstrap will be installed.

       -f|--file - configuration file for multistrap [required]

       --tidy-up - remove apt cache data, downloaded Packages files and the
       apt package cache. Same as cleanup=true.

       --no-auth - allow the use of unauthenticated repositories. Same as
       noauth=true

       --source-dir DIR - move the contents of var/cache/apt/archives/ from
       inside the chroot to the specified external directory, then add the
       Debian source packages for each used binary. Same as retainsources=DIR
       If the specified directory does not exist, nothing is done. Requires
       --tidy-up in order to calculate the full list of source packages,
       including dependencies.

Description

       multistrap provides a debootstrap-like method based on apt and extended
       to provide support for multiple repositories, using a configuration
       file to specify the relevant suites, architecture, extra packages and
       the mirror to use for each bootstrap.

       The aim is to create a complete bootstrap / root filesystem with all
       packages installed and configured, instead of just the base system.

       Example configuration:

        [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
        # 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=lenny

       This will result in a completely normal debootstrap of Debian lenny
       from the specified mirror, for armel in '/opt/multistrap/'. (This
       configuration is retained in the package as
       /usr/share/multistrap/lenny.conf)

       Specify a package to extend the multistrap to include that package and
       all dependencies of that package.

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

       Specify which repositories will be available to the final system at
       boot by listing the section names in the aptsources general option,
       e.g. to exclude some internal sources or when using a local mirror when
       building the rootfs.

       Section names are case-insensitive.

       All dependencies are resolved only by apt, using all bootstrap
       repositories, to use only the most recent and most suitable
       dependencies. Note that multistrap turns off Install-Recommends so if
       the multistrap needs a package that is only a Recommended dependency,
       the recommended package needs to be specified in the packages line
       explicitly. See "Explicit suite specification" for more information 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.

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
       if you have some internal or local sources which are not accessible to
       the installed root filesystem.

       "bootstrap" lists the sections which will be used to create the
       multistrap itself. Only packages listed in "bootstrap" will be
       downloaded and unpacked by multistrap.

       Make sure "bootstrap" lists all 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 - this spelling is still supported but new
       configuration files should be "bootstrap" instead.

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 - it is not packed into a .tgz once complete.

       'bootstrap' lists the Sections which will be used to specify the
       packages which 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, e.g. if you need to use a local repository
       to generate the rootfs which will not 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.

       The order of section names in either list is not important.

       As with debootstrap, multistrap will continue after errors, as long as
       the configuration file can be correctly parsed.

       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.

Section settings

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

       The section name (in [] brackets) needs to be unique for this
       configuration file and 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".

       'source' is the apt source to use for this Section. (To use a local
       source on the same machine, ensure you use "copy://" not "file://", so
       that 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.

       '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 must be
       the suite, not the codename.

       Suites change from time to time: (oldstable, stable, testing, sid) The
       codename (etch, lenny, squeeze, sid) does not change.

Secure Apt

       To use authenticated apt repositories, multistrap either needs to be
       able to install an appropriate keyring package from the existing apt
       sources outside the multistrap environment or have the relevant keys
       already configured using apt-key on the host system.

       If relevant packages exist, 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 one repository does not have a suitable keyring available.
       Not all packages need keyring packages, if you configure apt-key
       appropriately.

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

       All configuration of apt-key needs to be done for the machine running
       multistrap itself.

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.

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.

       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),
       /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 not 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.

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.

       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.

       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.

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

       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 the 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

Restricting package selection

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

        grep-available  -FPriority 'required' -sPackage

       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.

       Packages with Priority: important or standard are never included by
       "multistrap" unless specifically included in a "packages=" option in a
       section specified in the "bootstrap" general option.

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.

       The multistrap default is to turn recommends OFF.

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

Explicit suite specification

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

       "multistrap" can operate with and without the explicit suite option,
       the default is to let apt use the most recent version from the
       collection of specified bootstrap sources.

       Explicit suite specification has no effect on the final installed
       system - if your aptsources includes a repository which in turn
       includes a newer version of the package(s) specified explicitly, the
       next "apt-get upgrade" on the device will bring in the newer version.

       Also, when specifying packages to get from a specific suite, apt will
       also try and ensure that the dependencies for that package are also
       from the same suite and this can cause apt to be unable to resolve the
       complete set of dependencies. In this situation, being explicit about
       one package selection may require being explicit about some (not
       necessarily all) of the dependencies of that package as well.

       When using this support in Lenny, ensure that each section uses the
       suite (oldstable, stable, testing, sid) and not the codename (etch,
       lenny, squeeze, sid) in the "suite" configuration item as the version
       of apt in Lenny and previous cannot use the codename.

       To test, on Lenny, try:

        $ sudo apt-get install apt/stable

       Compare with

        $ sudo apt-get install apt/lenny

Omitting deb-src listings

       Some multistrap environments do not need access to the Debian sources
       of packages being installed, typically this is required 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

fakeroot

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

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

       The same problem applies to "apt-get install" and therefore the
       installation of the keyring package on the host system is also skipped
       if fakeroot is detected.