Provided by: mmdebstrap_0.4.1-6_all 
NAME
mmdebstrap - multi-mirror Debian chroot creation
SYNOPSIS
mmdebstrap [OPTION...] [SUITE [TARGET [MIRROR...]]]
DESCRIPTION
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
Options are case insensitive. Short options may be bundled. Long options require a double dash and may be
abbreviated to uniqueness.
-h,--help
Print this help text and exit.
--version
Print the mmdebstrap version and exit.
--variant=name
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.
--mode=name
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.
--aptopt=option|file
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"'
--dpkgopt=option|file
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/*"
--include=pkg1[,pkg2,...]
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.
--components=comp1[,comp2,...]
Comma separated list of components like main, contrib and non-free which will be used for all
URI-only MIRROR arguments.
--architectures=native[,foreign1,...]
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.
-q,--quiet, -s,--silent
Do not write anything to standard error. If used together with --verbose or --debug, only the
last option will take effect.
-v,--verbose
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.
-d,--debug
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.
--logfile=filename
Instead of writing status information to standard error, write it into the file given by
filename.
MODES
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.
auto 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
fakechroot binary exists, the fakechroot mode is chosen. Lastly, the proot mode is used if the
proot binary exists.
sudo, root
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.
unshare 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.
fakeroot, fakechroot
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.
proot 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.
chrootless
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.
VARIANTS
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.
extract Installs nothing by default (not even "Essential:yes" packages). Packages given by the
"--include" option are extracted but will not be installed.
custom 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
"Essential:yes" packages.
apt The essential set plus apt.
required, minbase
The essential set plus all packages with Priority:required and apt.
buildd The minbase set plus build-essential.
important, debootstrap, -
The required set plus all packages with Priority:important. This is the default of debootstrap.
standard
The important set plus all packages with Priority:standard.
EXAMPLES
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)
ENVIRONMENT VARIABLES
By setting "SOURCE_DATE_EPOCH" the result will be reproducible over multiple runs with the same options
and mirror content.
DEBOOTSTRAP
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.
COMPRESSION
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
BUGS
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.
SEE ALSO
debootstrap(8)