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)