DOKK / manpages / debian 10 / mmdebstrap / mmdebstrap.1.en
MMDEBSTRAP(1) User Contributed Perl Documentation MMDEBSTRAP(1)

mmdebstrap - multi-mirror Debian chroot creation

mmdebstrap [OPTION...] [SUITE [TARGET [MIRROR...]]]

mmdebstrap creates a Debian chroot of SUITE into TARGET from one or more MIRRORs. It is meant as an alternative to the debootstrap tool (see section DEBOOTSTRAP). In contrast to debootstrap it uses apt to resolve dependencies and is thus able to use more than one mirror and resolve more complex dependencies.

If no MIRROR option is provided, <http://deb.debian.org/debian> is used, except if data was given on standard input in which case the lines read from there are used as the content of the chroot's sources.list file. If SUITE is a stable release name and no MIRROR is specified, then mirrors for updates and security are automatically added. If a MIRROR option starts with "deb " or "deb-src " then it is used as a one-line-style format entry for apt's sources.list inside the chroot. If a MIRROR option contains a "://" then it is interpreted as a mirror URI and the apt line inside the chroot is assembled as "deb [arch=A] B C D" where A is the host's native architecture, B is the MIRROR, C is the given SUITE and D is the components given via --components (defaults to "main"). If a MIRROR option happens to be an existing file, then its contents are pasted into the chroot's sources.list. This can be used to supply a deb822 style sources.list. If MIRROR is "-" then standard input is pasted into the chroot's sources.list. If there was data on standard input but no "-" mirror was listed, the lines read from standard input will be appended to the end of the chroot's sources.list. More than one mirror can be specified and are appended to the chroot's sources.list in the given order. If any mirror contains a https URI, then the packages apt-transport-https and ca-certificates will be installed inside the chroot. If any mirror contains a tor+xxx URI, then the apt-transport-tor package will be installed inside the chroot.

The optional TARGET argument can either be the path to a directory, the path to a tarball filename or "-". If TARGET ends with ".tar", or with any of the filename extensions listed in the section COMPRESSION, then TARGET will be interpreted as a path to a tarball filename. If TARGET is the path to a tarball filename or if TARGET is "-" or if no TARGET was specified, mmdebstrap will create a temporary chroot directory in $TMPDIR or /tmp. If TARGET is the path to a tarball filename, mmdebstrap will create a tarball of that directory and store it as TARGET, optionally applying a compression algorithm as indicated by its filename extension. If TARGET is "-" or if no TARGET was specified, then an uncompressed tarball of that directory will be sent to standard output. If TARGET does not end in ".tar" or with any of the filename extensions listed in the section COMPRESSION, then TARGET will be interpreted as the path to a directory. If the directory already exists, it must either be empty or only contain an empty "lost+found" directory. If a directory is chosen as output in any other mode than sudo, then its contents will have wrong ownership information and special device files will be missing.

The SUITE may be a valid release code name (eg, sid, stretch, jessie) or a symbolic name (eg, unstable, testing, stable, oldstable). Any suite name that works with apt on the given mirror will work. If no SUITE was specified, then a single MIRROR "-" is added and thus the information of the desired suite has to come from standard input as part of a valid apt sources.list file.

All status output is printed to standard error unless --logfile is used to redirect it to a file or --quiet or --silent is used to suppress any output on standard error. Help and version information will be printed to standard error with the --help and --version options, respectively. Otherwise, an uncompressed tarball might be sent to standard output if TARGET is "-" or if no TARGET was specified.

Options are case insensitive. Short options may be bundled. Long options require a double dash and may be abbreviated to uniqueness.

Print this help text and exit.
Print the mmdebstrap version and exit.
Choose which package set to install. Valid variant names are extract, custom, essential, apt, required, minbase, buildd, important, debootstrap, -, and standard. The default variant is required. See the section VARIANTS for more information.
Choose how to perform the chroot operation and create a filesystem with ownership information different from the current user. Valid mode names are auto, sudo, root, unshare, fakeroot, fakechroot and proot. The default mode is auto. See the section MODES for more information.
Pass arbitrary options to apt. Will be added to /etc/apt/apt.conf.d/99mmdebstrap inside the chroot. Can be specified multiple times. Each option will be appended to 99mmdebstrap. A semicolon will be added at the end of the option if necessary. If the command line argument is an existing file, the content of the file will be appended to 99mmdebstrap verbatim.

Examples:

    --aptopt='Acquire::Check-Valid-Until "false"'
    --aptopt='Acquire::Languages { "environment"; "en"; }'
    --aptopt='Acquire::Languages "none"'
    --aptopt='Apt::Install-Recommends "true"'
    --aptopt='Acquire::http { Proxy "http://127.0.0.1:3142"; }'
    --aptopt='APT::Sandbox::User "root"'
Pass arbitrary options to dpkg. Will be added to /etc/dpkg/dpkg.cfg.d/99mmdebstrap inside the chroot. Can be specified multiple times. Each option will be appended to 99mmdebstrap. If the command line argument is an existing file, the content of the file will be appended to 99mmdebstrap verbatim.

Example: --dpkgopt="path-exclude=/usr/share/man/*"

Comma separated list of packages which will be installed in addition to the packages installed by the specified variant. The direct and indirect hard dependencies will also be installed. The behaviour of this option depends on the selected variant. The extract and custom variants install no packages by default, so for these variants, the packages specified by this option will be the only ones that get either extracted or installed by dpkg, respectively. For all other variants, apt is used to install the additional packages. The essential variant does not include apt and thus, the include option will only work when the chrootless mode is selected and thus apt from the outside can be used.
Comma separated list of components like main, contrib and non-free which will be used for all URI-only MIRROR arguments.
Comma separated list of architectures. The first architecture is the native architecture inside the chroot. The remaining architectures will be added to the foreign dpkg architectures. Without this option, the native architecture of the chroot defaults to the native architecture of the system running mmdebstrap.
Do not write anything to standard error. If used together with --verbose or --debug, only the last option will take effect.
Instead of progress bars, write the dpkg and apt output directly to standard error. If used together with --quiet or --debug, only the last option will take effect.
In addition to the output produced by --verbose, write detailed debugging information to standard error. Errors will print a backtrace. If used together with --quiet or --verbose, only the last option will take effect.
Instead of writing status information to standard error, write it into the file given by filename.

Creating a Debian chroot requires not only permissions for running chroot but also the ability to create files owned by the superuser. The selected mode decides which way this is achieved.

This mode automatically selects a fitting mode. If the effective user id is the one of the superuser, then the sudo mode is chosen. Otherwise, the unshare mode is picked if the system has the sysctl "kernel.unprivileged_userns_clone" set to 1. Should that not be the case and if the proot binary exists, the proot mode is chosen. Lastly, the fakechroot is used if the fakechroot binary exists.
This mode directly executes chroot and is the same mode of operation as is used by debootstrap. It is the only mode that can directly create a directory chroot with the right permissions. If the chroot directory is not accessible by the _apt user, then apt sandboxing will be automatically disabled.
This mode uses Linux user namespaces to allow unpriviliged use of chroot and creation of files that appear to be owned by the superuser inside the unshared namespace. A directory chroot created with this mode will end up with wrong permissions. Choose to create a tarball instead.
This mode will exec mmdebstrap again under "fakechroot fakeroot". A directory chroot created with this mode will end up with wrong permissions. Choose to create a tarball instead.
This mode will carry out all calls to chroot with proot instead. Since permissions are only retained while proot is still running, this will lead to wrong permissions in the final directory and tarball. This mode is useful if you plan to use the chroot with proot.
Uses the dpkg option "--force-script-chrootless" to install packages into TARGET without dpkg and apt inside target but using apt and dpkg from the machine running mmdebstrap. Maintainer scripts are run without chrooting into TARGET and rely on their dependencies being installed on the machine running mmdebstrap.

All package sets also include the direct and indirect hard dependencies (but not recommends) of the selected package sets. The variants minbase, buildd and -, resemble the package sets that debootstrap would install with the same --variant argument.

Installs nothing by default (not even "Essential:yes" packages). Packages given by the "--include" option are extracted but will not be installed.
Installs nothing by default (not even "Essential:yes" packages). Packages given by the "--include" option will be installed. If another mode than chrootless was selected and dpkg was not part of the included package set, then this variant will fail because it cannot configure the packages.
"Essential:yes" packages.
The essential set plus apt.
The essential set plus all packages with Priority:required and apt.
The minbase set plus build-essential.
The required set plus all packages with Priority:important. This is the default of debootstrap.
The important set plus all packages with Priority:standard.

Use like debootstrap:

    $ sudo mmdebstrap unstable ./unstable-chroot

Without superuser privileges:

    $ mmdebstrap unstable unstable-chroot.tar

With no command line arguments at all. The chroot content is entirely defined by a sources.list file on standard input.

    $ mmdebstrap < /etc/apt/sources.list > unstable-chroot.tar

Drop locales (but not the symlink to the locale name alias database), translated manual packages (but not the untranslated ones), and documentation (but not copyright and Debian changelog).

    $ mmdebstrap --variant=essential \
        --dpkgopt='path-exclude=/usr/share/man/*' \
        --dpkgopt='path-include=/usr/share/man/man[1-9]/*' \
        --dpkgopt='path-exclude=/usr/share/locale/*' \
        --dpkgopt='path-include=/usr/share/locale/locale.alias' \
        --dpkgopt='path-exclude=/usr/share/doc/*' \
        --dpkgopt='path-include=/usr/share/doc/*/copyright' \
        --dpkgopt='path-include=/usr/share/doc/*/changelog.Debian.*' \
        unstable debian-unstable.tar

Use as debootstrap replacement in sbuild-createchroot:

    $ sbuild-createchroot --debootstrap=mmdebstrap \
        --make-sbuild-tarball ~/.cache/sbuild/unstable-amd64.tar.gz \
        unstable $(mktemp -d)

By setting "SOURCE_DATE_EPOCH" the result will be reproducible over multiple runs with the same options and mirror content.

This section lists some differences to debootstrap.

  • More than one mirror possible
  • Default mirrors for stable releases include updates and security mirror
  • Multiple ways to operate as non-root: fakechroot, proot, unshare
  • 3-6 times faster
  • Can create a chroot with only "Essential:yes" packages and their dependencies
  • Reproducible output by default if $SOURCE_DATE_EPOCH is set
  • Can create output on filesystems with nodev set
  • apt cache and lists are cleaned at the end
  • foreign architecture chroots using qemu-user

Limitations in comparison to debootstrap:

  • Only runs on systems with apt installed
  • No SCRIPT argument
  • No --second-stage option.

mmdebstrap will choose a suitable compressor for the output tarball depending on the filename extension. The following mapping from filename extension to compressor applies:

 extension compressor
 --------------------
 .tar      none
 .gz       gzip
 .tgz      gzip
 .taz      gzip
 .Z        compress
 .taZ      compress
 .bz2      bzip2
 .tbz      bzip2
 .tbz2     bzip2
 .tz2      bzip2
 .lz       lzip
 .lzma     lzma
 .tlz      lzma
 .lzo      lzop
 .lz4      lz4
 .xz       xz
 .txz      xz
 .zst      zstd

As of version 1.19.5, dpkg does not provide facilities preventing it from reading the dpkg configuration of the machine running mmdebstrap. Therefore, until this dpkg limitation is fixed, a default dpkg configuration is recommended on machines running mmdebstrap.

    debootstrap(8)
2019-05-04 perl v5.28.1