.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MMDEBSTRAP 1"
.TH MMDEBSTRAP 1 2024-02-26 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
mmdebstrap \- multi\-mirror Debian chroot creation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBmmdebstrap\fR [\fBOPTION...\fR] [\fISUITE\fR [\fITARGET\fR [\fIMIRROR\fR...]]]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBmmdebstrap\fR creates a Debian chroot of \fISUITE\fR into \fITARGET\fR from one or
more \fIMIRROR\fRs. It is meant as an alternative to the debootstrap tool (see
section \fBDEBOOTSTRAP\fR). In contrast to debootstrap it uses apt to resolve
dependencies and is thus able to use more than one mirror and resolve more
complex dependency relationships. See section \fBOPERATION\fR for an overview of
how \fBmmdebstrap\fR works internally.
.PP
The \fISUITE\fR option may either be a valid release code name (eg, sid, bookworm,
trixie) or a symbolic name (eg, unstable, testing, stable, oldstable). Any
suite name that works with apt on the given mirror will work. The \fISUITE\fR
option is optional if no \fITARGET\fR and no \fIMIRROR\fR option is provided.  If
\&\fISUITE\fR is missing, then the information of the desired suite has to come from
standard input as part of a valid apt sources.list file or be set up via hooks.
The value of the \fISUITE\fR argument will be used to determine which apt index to
use for finding out the set of \f(CW\*(C`Essential:yes\*(C'\fR packages and/or the set of
packages with the right priority for the selected variant. This functionality
can be disabled by choosing the empty string for \fISUITE\fR. See the section
\&\fBVARIANTS\fR for more information.
.PP
The \fITARGET\fR option may either be the path to a directory, the path to a
tarball filename, the path to a squashfs image, the path to an ext2 image, a
FIFO, a character special device, or \f(CW\*(C`\-\*(C'\fR.  The \fITARGET\fR option is optional if
no \fIMIRROR\fR option is provided. If \fITARGET\fR is missing or if \fITARGET\fR is
\&\f(CW\*(C`\-\*(C'\fR, an uncompressed tarball will be sent to standard output. Without the
\&\fB\-\-format\fR option, \fITARGET\fR will be used to choose the format. See the
section \fBFORMATS\fR for more information.
.PP
The \fIMIRROR\fR option may either be provided as a URI, in apt one-line format,
as a path to a file in apt's one-line or deb822\-format, or \f(CW\*(C`\-\*(C'\fR.  If no
\&\fIMIRROR\fR option is provided, then <http://deb.debian.org/debian> is used as
the default. If \fISUITE\fR does not refer to "unstable" or "testing", then
\&\fISUITE\fR\-updates and \fISUITE\fR\-security mirrors are automatically added. If a
\&\fIMIRROR\fR option starts with "deb " or "deb-src " then it is used as a one-line
format entry for apt's sources.list inside the chroot. If a \fIMIRROR\fR 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 \fIMIRROR\fR, C is the given \fISUITE\fR and D is the
components given via \fB\-\-components\fR (defaults to "main"). If a \fIMIRROR\fR
option happens to be an existing file, then its contents are written into the
chroot's sources.list (if the first \fIMIRROR\fR is a file in one-line format) or
into the chroot's sources.list.d directory, named with the extension .list or
\&.sources, depending on whether the file is in one-line or deb822 format,
respectively.  If \fIMIRROR\fR is \f(CW\*(C`\-\*(C'\fR then standard input is pasted into 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 you specify a https or tor
\&\fIMIRROR\fR and you want the chroot to be able to update itself, don't forget to
also install the ca-certificates package, the apt-transport-https package for
apt versions less than 1.5 and/or the apt-transport-tor package using the
\&\fB\-\-include\fR option, as necessary.
.PP
All status output is printed to standard error unless \fB\-\-logfile\fR is used to
redirect it to a file or \fB\-\-quiet\fR or \fB\-\-silent\fR is used to suppress any
output on standard error. Help and version information will be printed to
standard error with the \fB\-\-help\fR and \fB\-\-version\fR options, respectively.
Otherwise, an uncompressed tarball might be sent to standard output if
\&\fITARGET\fR is \f(CW\*(C`\-\*(C'\fR or if no \fITARGET\fR was specified.
.SH OPTIONS
.IX Header "OPTIONS"
Options are case insensitive. Short options may be bundled. Long options
require a double dash and may be abbreviated to uniqueness. Options can be
placed anywhere on the command line, even before or mixed with the \fISUITE\fR,
\&\fITARGET\fR, and \fIMIRROR\fR arguments. A double dash \f(CW\*(C`\-\-\*(C'\fR can be used to stop
interpreting command line arguments as options to allow \fISUITE\fR, \fITARGET\fR and
\&\fIMIRROR\fR arguments that start with a single or double dash. Option order only
matters for options that can be passed multiple times as documented below.
.IP \fB\-h,\-\-help\fR 8
.IX Item "-h,--help"
Print synopsis and options of this man page and exit.
.IP \fB\-\-man\fR 8
.IX Item "--man"
Show the full man page as generated from Perl POD in a pager. This requires
the perldoc program from the perl-doc package. This is the same as running:
.Sp
.Vb 1
\&    pod2man /usr/bin/mmdebstrap | man \-l \-
.Ve
.IP \fB\-\-version\fR 8
.IX Item "--version"
Print the \fBmmdebstrap\fR version and exit.
.IP \fB\-\-variant\fR=\fIname\fR 8
.IX Item "--variant=name"
Choose which package set to install. Valid variant \fIname\fRs are \fBextract\fR,
\&\fBcustom\fR, \fBessential\fR, \fBapt\fR, \fBrequired\fR, \fBminbase\fR, \fBbuildd\fR,
\&\fBimportant\fR, \fBdebootstrap\fR, \fB\-\fR, and \fBstandard\fR. The default variant is
\&\fBdebootstrap\fR. See the section \fBVARIANTS\fR for more information.
.IP \fB\-\-mode\fR=\fIname\fR 8
.IX Item "--mode=name"
Choose how to perform the chroot operation and create a filesystem with
ownership information different from the current user. Valid mode \fIname\fRs are
\&\fBauto\fR, \fBsudo\fR, \fBroot\fR, \fBunshare\fR, \fBfakeroot\fR, \fBfakechroot\fR and
\&\fBchrootless\fR.  The default mode is \fBauto\fR. See the section \fBMODES\fR for more
information.
.IP \fB\-\-format\fR=\fIname\fR 8
.IX Item "--format=name"
Choose the output format. Valid format \fIname\fRs are \fBauto\fR, \fBdirectory\fR,
\&\fBtar\fR, \fBsquashfs\fR, \fBext2\fR and \fBnull\fR. The default format is \fBauto\fR. See
the section \fBFORMATS\fR for more information.
.IP \fB\-\-aptopt\fR=\fIoption\fR|\fIfile\fR 8
.IX Item "--aptopt=option|file"
Pass arbitrary \fIoption\fRs to apt. Will be permamently added to
\&\fI/etc/apt/apt.conf.d/99mmdebstrap\fR inside the chroot. Use hooks for temporary
configuration options. Can be specified multiple times. Each \fIoption\fR 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 \fIfile\fR, the content of
the file will be appended to 99mmdebstrap verbatim.
.Sp
Example: This is necessary for allowing old timestamps from snapshot.debian.org
.Sp
.Vb 2
\&    \-\-aptopt=\*(AqAcquire::Check\-Valid\-Until "false"\*(Aq
\&    \-\-aptopt=\*(AqApt::Key::gpgvcommand "/usr/libexec/mmdebstrap/gpgvnoexpkeysig"\*(Aq
.Ve
.Sp
Example: Settings controlling download of package description translations
.Sp
.Vb 2
\&    \-\-aptopt=\*(AqAcquire::Languages { "environment"; "en"; }\*(Aq
\&    \-\-aptopt=\*(AqAcquire::Languages "none"\*(Aq
.Ve
.Sp
Example: Enable installing Recommends (by default \fBmmdebstrap\fR doesn't)
.Sp
.Vb 1
\&    \-\-aptopt=\*(AqApt::Install\-Recommends "true"\*(Aq
.Ve
.Sp
Example: Configure apt-cacher or apt-cacher-ng as an apt proxy
.Sp
.Vb 1
\&    \-\-aptopt=\*(AqAcquire::http { Proxy "http://127.0.0.1:3142"; }\*(Aq
.Ve
.Sp
Example: For situations in which the apt sandbox user cannot access the chroot
.Sp
.Vb 1
\&    \-\-aptopt=\*(AqAPT::Sandbox::User "root"\*(Aq
.Ve
.Sp
Example: Minimizing the number of packages installed from experimental
.Sp
.Vb 3
\&    \-\-aptopt=\*(AqAPT::Solver "aspcud"\*(Aq
\&    \-\-aptopt=\*(AqAPT::Solver::aspcud::Preferences
\&       "\-count(solution,APT\-Release:=/a=experimental/),\-removed,\-changed,\-new"\*(Aq
.Ve
.IP \fB\-\-keyring\fR=\fIfile\fR|\fIdirectory\fR 8
.IX Item "--keyring=file|directory"
Change the default keyring to use by apt during the initial setup. This is
similar to setting \fBDir::Etc::Trusted\fR and \fBDir::Etc::TrustedParts\fR using
\&\fB\-\-aptopt\fR except that the latter setting will be permanently stored in the
chroot while the keyrings passed via \fB\-\-keyring\fR will only be visible to apt
as run by \fBmmdebstrap\fR. Do not use \fB\-\-keyring\fR if apt inside the chroot needs
to know about your keys after the initial chroot creation by \fBmmdebstrap\fR.
This option is mainly intended for users who use \fBmmdebstrap\fR as a
\&\fBdeboostrap\fR drop-in replacement. As such, it is probably not what you want to
use if you use \fBmmdebstrap\fR with more than a single mirror unless you pass it
a directory containing all the keyrings you need.
.Sp
By default, the local setting of \fBDir::Etc::Trusted\fR and
\&\fBDir::Etc::TrustedParts\fR are used to choose the keyring used by apt as run by
\&\fBmmdebstrap\fR. These two locations are set to \fI/etc/apt/trusted.gpg\fR and
\&\fI/etc/apt/trusted.gpg.d\fR by default. Depending on whether a file or directory
is passed to this option, the former and latter default can be changed,
respectively.  Since apt only supports a single keyring file and directory,
respectively, you can \fBnot\fR use this option to pass multiple files and/or
directories. Using the \f(CW\*(C`\-\-keyring\*(C'\fR argument in the following way is equal to
keeping the default:
.Sp
.Vb 1
\&    \-\-keyring=/etc/apt/trusted.gpg \-\-keyring=/etc/apt/trusted.gpg.d
.Ve
.Sp
If you need to pass multiple keyrings, use the \f(CW\*(C`signed\-by\*(C'\fR option when
specifying the mirror like this:
.Sp
.Vb 1
\&    mmdebstrap mysuite out.tar "deb [signed\-by=/path/to/key.gpg] http://..."
.Ve
.Sp
Another reason to use \f(CW\*(C`signed\-by\*(C'\fR instead of \fB\-\-keyring\fR is if apt inside the
chroot needs to know by what key the repository is signed even after the
initial chroot creation.
.Sp
The \f(CW\*(C`signed\-by\*(C'\fR option will automatically be added to the final
\&\f(CW\*(C`sources.list\*(C'\fR if the keyring required for the selected \fISUITE\fR is not yet
trusted by apt. Automatically adding the \f(CW\*(C`signed\-by\*(C'\fR option in these cases
requires \f(CW\*(C`gpg\*(C'\fR to be installed. If \f(CW\*(C`gpg\*(C'\fR and \f(CW\*(C`ubuntu\-archive\-keyring\*(C'\fR are
installed, then you can create a Ubuntu Bionic chroot on Debian like this:
.Sp
.Vb 1
\&    mmdebstrap bionic ubuntu\-bionic.tar
.Ve
.Sp
The resulting chroot will have a \f(CW\*(C`source.list\*(C'\fR with a \f(CW\*(C`signed\-by\*(C'\fR option
pointing to \fI/usr/share/keyrings/ubuntu\-archive\-keyring.gpg\fR.
.Sp
You do not need to use \fB\-\-keyring\fR or \f(CW\*(C`signed\-by\*(C'\fR if you placed the keys that
apt needs to know about into \fI/etc/apt/trusted.gpg.d\fR in the \fB\-\-setup\-hook\fR
(which is before \f(CW\*(C`apt update\*(C'\fR runs), for example by using the \fBcopy-in\fR
special hook. You also need to copy your keys into the chroot explicitly if the
key you passed via \f(CW\*(C`signed\-by\*(C'\fR points to a location that is not otherwise
populated during chroot creation (for example by installing a keyring package).
.IP \fB\-\-dpkgopt\fR=\fIoption\fR|\fIfile\fR 8
.IX Item "--dpkgopt=option|file"
Pass arbitrary \fIoption\fRs to dpkg. Will be permanently added to
\&\fI/etc/dpkg/dpkg.cfg.d/99mmdebstrap\fR inside the chroot. Use hooks for temporary
configuration options. Can be specified multiple times. Each \fIoption\fR will be
appended to 99mmdebstrap. If the command line argument is an existing \fIfile\fR,
the content of the file will be appended to 99mmdebstrap verbatim.
.Sp
Example: Exclude paths to reduce chroot size
.Sp
.Vb 7
\&    \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/man/*\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-include=/usr/share/man/man[1\-9]/*\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/locale/*\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-include=/usr/share/locale/locale.alias\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/doc/*\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-include=/usr/share/doc/*/copyright\*(Aq
\&    \-\-dpkgopt=\*(Aqpath\-include=/usr/share/doc/*/changelog.Debian.*\*(Aq
.Ve
.IP \fB\-\-include\fR=\fIpkg1\fR[,\fIpkg2\fR,...] 8
.IX Item "--include=pkg1[,pkg2,...]"
Comma or whitespace 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 \fBextract\fR and \fBcustom\fR 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. Package names are directly passed to apt and thus, you
can use apt features like \f(CW\*(C`pkg/suite\*(C'\fR, \f(CW\*(C`pkg=version\*(C'\fR, \f(CW\*(C`pkg\-\*(C'\fR, use a glob or
regex for \f(CW\*(C`pkg\*(C'\fR, use apt patterns or pass a path to a .deb package file (see
below for notes concerning passing the path to a .deb package file in
\&\fBunshare\fR mode). See \fBapt\fR\|(8) for the supported syntax.
.Sp
The option can be specified multiple times and the packages are concatenated in
the order in which they are given on the command line. If later list items are
repeated, then they get dropped so that the resulting package list is free of
duplicates. So the following are equivalent:
.Sp
.Vb 3
\&    \-\-include="pkg1/stable pkg2=1.0 pkg3\-"
\&    \-\-include=pkg1/stable,pkg2=1.0,pkg3\-,,,
\&    \-\-incl=pkg1/stable \-\-incl="pkg2=1.0 pkg3\-" \-\-incl=pkg2=1.0,pkg3\-
.Ve
.Sp
Since the list of packages is separated by comma or whitespace, it is not
possible to mix apt patterns or .deb package file paths containing either
commas or whitespace with normal package names. If you do, your patterns and
paths will be split by comma and whitespace as well and become useless. To pass
such a pattern or package file path, put them into their own \fB\-\-include\fR
option. If the argument to \fB\-\-include\fR starts with an apt pattern or with a
file path, then it will not be split:
.Sp
.Vb 2
\&    \-\-include="?or(?priority(required), ?priority(important))"
\&    \-\-include="./path/to/deb with spaces/and,commas/foo.deb"
.Ve
.Sp
Specifically, all arguments to \fB\-\-include\fR that start with a \f(CW\*(C`?\*(C'\fR, \f(CW\*(C`!\*(C'\fR, \f(CW\*(C`~\*(C'\fR,
\&\f(CW\*(C`(\*(C'\fR, \f(CW\*(C`/\*(C'\fR, \f(CW\*(C`./\*(C'\fR or \f(CW\*(C`../\*(C'\fR are not split and treated as single arguments to
apt. To add more packages, use multiple \fB\-\-include\fR options. To disable this
detection of patterns and paths, start the argument to \fB\-\-include\fR with a
comma or whitespace.
.Sp
If you pass the path to a .deb package file using \fB\-\-include\fR, \fBmmdebstrap\fR
will ensure that the path exists. If the path is a relative path, it will
internally by converted to an absolute path. Since apt (outside the chroot)
passes paths to dpkg (on the inside) verbatim, you have to make the .deb
package available under the same path inside the chroot as well or otherwise
dpkg inside the chroot will be unable to access it. This can be achieved using
a setup-hook. A hook that automatically makes the contents of \f(CW\*(C`file://\*(C'\fR
mirrors as well as .deb packages given with \fB\-\-include\fR available inside the
chroot is provided by \fBmmdebstrap\fR as
\&\fB\-\-hook\-dir=/usr/share/mmdebstrap/hooks/file\-mirror\-automount\fR. This hook
takes care of copying all relevant file to their correct locations and cleans
up those files at the end. In \fBunshare\fR mode, the .deb package paths have to
be accessible by the unshared user as well. This means that the package itself
likely must be made world-readable and all directory components on the path to
it world-executable.
.IP \fB\-\-components\fR=\fIcomp1\fR[,\fIcomp2\fR,...] 8
.IX Item "--components=comp1[,comp2,...]"
Comma or whitespace separated list of components like main, contrib, non-free
and non-free-firmware which will be used for all URI-only \fIMIRROR\fR arguments.
The option can be specified multiple times and the components are concatenated
in the order in which they are given on the command line. If later list items
are repeated, then they get dropped so that the resulting component list is
free of duplicates. So the following are equivalent:
.Sp
.Vb 3
\&    \-\-components="main contrib non\-free non\-free\-firmware"
\&    \-\-components=main,contrib,non\-free,non\-free\-firmware
\&    \-\-comp=main \-\-comp="contrib non\-free" \-\-comp="main,non\-free\-firmware"
.Ve
.IP \fB\-\-architectures\fR=\fInative\fR[,\fIforeign1\fR,...] 8
.IX Item "--architectures=native[,foreign1,...]"
Comma or whitespace separated list of architectures. The first architecture is
the \fInative\fR architecture inside the chroot. The remaining architectures will
be added to the foreign dpkg architectures. Without this option, the \fInative\fR
architecture of the chroot defaults to the native architecture of the system
running \fBmmdebstrap\fR. The option can be specified multiple times and values
are concatenated. If later list items are repeated, then they get dropped so
that the resulting list is free of duplicates. So the following are
equivalent:
.Sp
.Vb 3
\&    \-\-architectures="amd64 armhf mipsel"
\&    \-\-architectures=amd64,armhf,mipsel
\&    \-\-arch=amd64 \-\-arch="armhf mipsel" \-\-arch=armhf,mipsel
.Ve
.IP "\fB\-\-simulate\fR, \fB\-\-dry\-run\fR" 8
.IX Item "--simulate, --dry-run"
Run apt-get with \fB\-\-simulate\fR. Only the package cache is initialized but no
binary packages are downloaded or installed. Use this option to quickly check
whether a package selection within a certain suite and variant can in principle
be installed as far as their dependencies go. If the output is a tarball, then
no output is produced. If the output is a directory, then the directory will be
left populated with the skeleton files and directories necessary for apt to run
in it. No hooks are executed in with \fB\-\-simulate\fR or \fB\-\-dry\-run\fR.
.IP \fB\-\-setup\-hook\fR=\fIcommand\fR 8
.IX Item "--setup-hook=command"
Execute arbitrary \fIcommand\fRs right after initial setup (directory creation,
configuration of apt and dpkg, ...) but before any packages are downloaded or
installed. At that point, the chroot directory does not contain any
executables and thus cannot be chroot-ed into. See section \fBHOOKS\fR for more
information.
.Sp
Example: add additional apt sources entries on top of the default ones:
.Sp
.Vb 1
\&    \-\-setup\-hook=\*(Aqecho "deb http..." > "$1"/etc/apt/sources.list.d/custom.list\*(Aq
.Ve
.Sp
Example: Setup chroot for installing a sub-essential busybox-based chroot
with \-\-variant=custom
\&\-\-include=dpkg,busybox,libc\-bin,base\-files,base\-passwd,debianutils
.Sp
.Vb 6
\&    \-\-setup\-hook=\*(Aqmkdir \-p "$1/bin"\*(Aq
\&    \-\-setup\-hook=\*(Aqfor p in awk cat chmod chown cp diff echo env grep less ln
\&        mkdir mount rm rmdir sed sh sleep sort touch uname mktemp; do
\&        ln \-s busybox "$1/bin/$p"; done\*(Aq
\&    \-\-setup\-hook=\*(Aqecho root:x:0:0:root:/root:/bin/sh > "$1/etc/passwd"\*(Aq
\&    \-\-setup\-hook=\*(Aqprintf "root:x:0:\enmail:x:8:\enutmp:x:43:\en" > "$1/etc/group"\*(Aq
.Ve
.Sp
For a more elegant way for setting up a sub-essential busybox-based chroot, see
the \fB\-\-hook\-dir\fR option below.
.IP \fB\-\-extract\-hook\fR=\fIcommand\fR 8
.IX Item "--extract-hook=command"
Execute arbitrary \fIcommand\fRs after the Essential:yes packages have been
extracted but before installing them. See section \fBHOOKS\fR for more
information.
.Sp
Example: Install busybox symlinks
.Sp
.Vb 1
\&    \-\-extract\-hook=\*(Aqchroot "$1" /bin/busybox \-\-install \-s\*(Aq
.Ve
.IP \fB\-\-essential\-hook\fR=\fIcommand\fR 8
.IX Item "--essential-hook=command"
Execute arbitrary \fIcommand\fRs after the Essential:yes packages have been
installed but before installing the remaining packages. The hook is not
executed for the \fBextract\fR and \fBcustom\fR variants. See section \fBHOOKS\fR for
more information.
.Sp
Example: Enable unattended upgrades
.Sp
.Vb 3
\&    \-\-essential\-hook=\*(Aqecho unattended\-upgrades
\&        unattended\-upgrades/enable_auto_updates boolean true
\&        | chroot "$1" debconf\-set\-selections\*(Aq
.Ve
.Sp
Example: Select Europe/Berlin as the timezone
.Sp
.Vb 4
\&    \-\-essential\-hook=\*(Aqecho tzdata tzdata/Areas select Europe
\&        | chroot "$1" debconf\-set\-selections\*(Aq
\&    \-\-essential\-hook=\*(Aqecho tzdata tzdata/Zones/Europe select Berlin
\&        | chroot "$1" debconf\-set\-selections\*(Aq
.Ve
.IP \fB\-\-customize\-hook\fR=\fIcommand\fR 8
.IX Item "--customize-hook=command"
Execute arbitrary \fIcommand\fRs after the chroot is set up and all packages got
installed but before final cleanup actions are carried out. See section
\&\fBHOOKS\fR for more information.
.Sp
Example: Add a user without a password
.Sp
.Vb 3
\&    \-\-customize\-hook=\*(Aqchroot "$1" useradd \-\-home\-dir /home/user
\&        \-\-create\-home user\*(Aq
\&    \-\-customize\-hook=\*(Aqchroot "$1" passwd \-\-delete user\*(Aq
.Ve
.Sp
Example: set up \fI/etc/hostname\fR and \fI/etc/hosts\fR
.Sp
.Vb 2
\&    \-\-customize\-hook=\*(Aqecho host > "$1/etc/hostname"\*(Aq
\&    \-\-customize\-hook=\*(Aqecho "127.0.0.1 localhost host" > "$1/etc/hosts"\*(Aq
.Ve
.Sp
Example: to mimic \fBdebootstrap\fR behaviour, \fBmmdebstrap\fR copies from the host.
Remove them in a \fB\-\-customize\-hook\fR to make the chroot reproducible across
multiple hosts:
.Sp
.Vb 2
\&    \-\-customize\-hook=\*(Aqrm "$1"/etc/resolv.conf\*(Aq
\&    \-\-customize\-hook=\*(Aqrm "$1"/etc/hostname\*(Aq
.Ve
.IP \fB\-\-hook\-directory\fR=\fIdirectory\fR 8
.IX Item "--hook-directory=directory"
Execute scripts in \fIdirectory\fR with filenames starting with \f(CW\*(C`setup\*(C'\fR,
\&\f(CW\*(C`extract\*(C'\fR, \f(CW\*(C`essential\*(C'\fR or \f(CW\*(C`customize\*(C'\fR, at the respective stages during an
mmdebstrap run. The files must be marked executable. Their extension is
ignored. Subdirectories are not traversed. This option is a short-hand for
specifying the remaining four hook options individually for each file in the
directory. If there are more than one script for a stage, then they are added
alphabetically. This is useful in cases, where a user wants to run the same
hooks frequently. For example, given a directory \f(CW\*(C`./hooks\*(C'\fR with two scripts
\&\f(CW\*(C`setup01\-foo.sh\*(C'\fR and \f(CW\*(C`setup02\-bar.sh\*(C'\fR, this call:
.Sp
.Vb 1
\&    mmdebstrap \-\-customize=./scriptA \-\-hook\-dir=./hooks \-\-setup=./scriptB
.Ve
.Sp
is equivalent to this call:
.Sp
.Vb 2
\&    mmdebstrap \-\-customize=./scriptA \-\-setup=./hooks/setup01\-foo.sh \e
\&        \-\-setup=./hooks/setup02\-bar.sh \-\-setup=./scriptB
.Ve
.Sp
The option can be specified multiple times and scripts are added to the
respective hooks in the order the options are given on the command line. Thus,
if the scripts in two directories depend upon each other, the scripts must be
placed into a common directory and be named such that they get added in the
correct order.
.Sp
Example 1: Run mmdebstrap with eatmydata
.Sp
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/eatmydata
.Ve
.Sp
Example 2: Setup chroot for installing a sub-essential busybox-based chroot
.Sp
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/busybox
.Ve
.Sp
Example 3: Automatically mount all directories referenced by \f(CW\*(C`file://\*(C'\fR mirrors
into the chroot
.Sp
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/file\-mirror\-automount
.Ve
.IP \fB\-\-skip\fR=\fIstage\fR[,\fIstage\fR,...] 8
.IX Item "--skip=stage[,stage,...]"
\&\fBmmdebstrap\fR tries hard to implement sensible defaults and will try to stop
you before shooting yourself in the foot. This option is for when you are sure
you know what you are doing and allows one to skip certain actions and safety
checks. See section \fBOPERATION\fR for a list of possible arguments and their
context. The option can be specified multiple times or you can separate
multiple values by comma or whitespace.
.IP "\fB\-q,\-\-quiet\fR, \fB\-s,\-\-silent\fR" 8
.IX Item "-q,--quiet, -s,--silent"
Do not write anything to standard error. If used together with \fB\-\-verbose\fR or
\&\fB\-\-debug\fR, only the last option will take effect.
.IP \fB\-v,\-\-verbose\fR 8
.IX Item "-v,--verbose"
Instead of progress bars, write the dpkg and apt output directly to standard
error. If used together with \fB\-\-quiet\fR or \fB\-\-debug\fR, only the last option
will take effect.
.IP \fB\-d,\-\-debug\fR 8
.IX Item "-d,--debug"
In addition to the output produced by \fB\-\-verbose\fR, write detailed debugging
information to standard error. Errors will print a backtrace. If used together
with \fB\-\-quiet\fR or \fB\-\-verbose\fR, only the last option will take effect.
.IP \fB\-\-logfile\fR=\fIfilename\fR 8
.IX Item "--logfile=filename"
Instead of writing status information to standard error, write it into the
file given by \fIfilename\fR.
.SH MODES
.IX Header "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.
.IP \fBauto\fR 8
.IX Item "auto"
This mode automatically selects a fitting mode. If the effective user id is the
one of the superuser, then the \fBsudo\fR mode is chosen. Otherwise, the
\&\fBunshare\fR mode is picked if \fI/etc/subuid\fR and \fI/etc/subgid\fR are set up
correctly. Should that not be the case and if the fakechroot binary exists, the
\&\fBfakechroot\fR mode is chosen.
.IP "\fBsudo\fR, \fBroot\fR" 8
.IX Item "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. This mode
needs to be able to mount and thus requires \f(CW\*(C`CAP_SYS_ADMIN\*(C'\fR.
.IP \fBunshare\fR 8
.IX Item "unshare"
When used as a normal (not root) user, this mode uses Linux user namespaces to
allow unprivileged use of chroot and creation of files that appear to be owned
by the superuser inside the unshared namespace. A tarball created in this mode
will be bit-by-bit identical to a tarball created with the \fBroot\fR mode. With
this mode, the only binaries that will run as the root user will be
\&\fBnewuidmap\fR\|(1) and \fBnewgidmap\fR\|(1) via their setuid bit. Running those
successfully requires \fI/etc/subuid\fR and \fI/etc/subgid\fR to have an entry for
your username. This entry was usually created by \fBadduser\fR\|(8) already.
.Sp
The unshared user will not automatically have access to the same files as you
do. This is intentional and an additional security against unintended changes
to your files that could theoretically result from running \fBmmdebstrap\fR and
package maintainer scripts. To copy files in and out of the chroot, either use
globally readable or writable directories or use special hooks like \fBcopy-in\fR
and \fBcopy-out\fR.
.Sp
Besides the user namespace, the mount, pid (process ids), uts (hostname) and
ipc namespaces will be unshared as well. See the man pages of \fBnamespaces\fR\|(7)
and \fBunshare\fR\|(2) as well as the manual pages they are linking to.
.Sp
A directory chroot created with this mode will end up with wrong ownership
information (seen from outside the unshared user namespace). For correct
ownership information, the directory must be accessed from a user namespace
with the right subuid/subgid offset, like so:
.Sp
.Vb 2
\&    $ lxc\-usernsexec \-\- lxc\-unshare \-s \*(AqMOUNT|PID|UTSNAME|IPC\*(Aq \-\- \e
\&    > /usr/sbin/chroot ./debian\-rootfs /bin/bash
.Ve
.Sp
Or without LXC:
.Sp
.Vb 1
\&    $ mmdebstrap \-\-unshare\-helper /usr/sbin/chroot ./debian\-rootfs /bin/bash
.Ve
.Sp
Or, if you don't mind using superuser privileges and have systemd-nspawn
available and you know your subuid/subgid offset (100000 in this example):
.Sp
.Vb 2
\&    $ sudo systemd\-nspawn \-\-private\-users=100000 \e
\&    > \-\-directory=./debian\-rootfs /bin/bash
.Ve
.Sp
A directory created in \fBunshare\fR mode cannot be removed the normal way.
Instead, use something like this:
.Sp
.Vb 1
\&    $ unshare \-\-map\-root\-user \-\-map\-auto rm \-rf ./debian\-rootfs
.Ve
.Sp
If this mode is used as the root user, the user namespace is not unshared (but
the mount namespace and other still are) and created directories will have
correct ownership information. This is also useful in cases where the root user
wants the benefits of an unshared mount namespace to prevent accidentally
messing up the system.
.IP "\fBfakeroot\fR, \fBfakechroot\fR" 8
.IX Item "fakeroot, fakechroot"
This mode will exec \fBmmdebstrap\fR again under \f(CW\*(C`fakechroot fakeroot\*(C'\fR. A
directory chroot created with this mode will end up with wrong permissions. If
you need a directory then run \fBmmdebstrap\fR under \f(CW\*(C`fakechroot fakeroot \-s
fakeroot.env\*(C'\fR and use \f(CW\*(C`fakeroot.env\*(C'\fR later when entering the chroot with
\&\f(CW\*(C`fakechroot fakeroot \-i fakeroot.env chroot ...\*(C'\fR. This mode will not work if
maintainer scripts are unable to handle \f(CW\*(C`LD_PRELOAD\*(C'\fR correctly like the
package \fBinitramfs-tools\fR until version 0.132. This mode will also not work
with a different libc inside the chroot than on the outside. See the section
\&\fBLIMITATIONS\fR in \fBfakechroot\fR\|(1).
.IP \fBchrootless\fR 8
.IX Item "chrootless"
Uses the dpkg option \f(CW\*(C`\-\-force\-script\-chrootless\*(C'\fR to install packages into
\&\fITARGET\fR without dpkg and apt inside \fITARGET\fR but using apt and dpkg from the
machine running \fBmmdebstrap\fR. Maintainer scripts are run without chrooting
into \fITARGET\fR and rely on their dependencies being installed on the machine
running \fBmmdebstrap\fR. Only very few packages support this mode. Namely, as of
2022, not all essential packages support it.  See
https://wiki.debian.org/Teams/Dpkg/Spec/InstallBootstrap or the
dpkg-root-support usertag of debian\-dpkg@lists.debian.org in the Debian bug
tracking system. \fBWARNING\fR: if this option is used carelessly with packages
that do not support \f(CW\*(C`DPKG_ROOT\*(C'\fR, this mode can result in undesired changes to
the system running \fBmmdebstrap\fR because maintainer-scripts will be run without
\&\fBchroot\fR\|(1). Make sure to run this mode without superuser privileges and/or
inside a throw-away chroot environment like so:
.Sp
.Vb 4
\&    mmdebstrap \-\-variant=apt \-\-include=mmdebstrap \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" mmdebstrap \-\-mode=chrootless
\&                          \-\-variant=apt unstable chrootless.tar\*(Aq \e
\&        \-\-customize\-hook=\*(Aqcopy\-out chrootless.tar .\*(Aq unstable /dev/null
.Ve
.SH VARIANTS
.IX Header "VARIANTS"
All package sets also include the direct and indirect hard dependencies (but
not recommends) of the selected package sets. The variants \fBminbase\fR,
\&\fBbuildd\fR and \fB\-\fR, resemble the package sets that debootstrap would install
with the same \fI\-\-variant\fR argument. The release with a name matching the
\&\fISUITE\fR argument as well as the native architecture will be used to determine
the \f(CW\*(C`Essential:yes\*(C'\fR and priority values. To select packages with matching
priority from any suite, specify the empty string for \fISUITE\fR. The default
variant is \fBdebootstrap\fR.
.IP \fBextract\fR 8
.IX Item "extract"
Installs nothing by default (not even \f(CW\*(C`Essential:yes\*(C'\fR packages). Packages
given by the \f(CW\*(C`\-\-include\*(C'\fR option are extracted but will not be installed.
.IP \fBcustom\fR 8
.IX Item "custom"
Installs nothing by default (not even \f(CW\*(C`Essential:yes\*(C'\fR packages). Packages
given by the \f(CW\*(C`\-\-include\*(C'\fR option will be installed.  If another mode than
\&\fBchrootless\fR was selected and dpkg was not part of the included package set,
then this variant will fail because it cannot configure the packages.
.IP \fBessential\fR 8
.IX Item "essential"
\&\f(CW\*(C`Essential:yes\*(C'\fR packages. If \fISUITE\fR is a non-empty string, then only
packages from the archive with suite or codename matching \fISUITE\fR will be
considered for selection of \f(CW\*(C`Essential:yes\*(C'\fR packages.
.IP \fBapt\fR 8
.IX Item "apt"
The \fBessential\fR set plus apt. This variant uses the fact that \fBapt\fR treats
itself as essential and thus running \f(CW\*(C`apt\-get dist\-upgrade\*(C'\fR without any
packages installed will install the \fBessential\fR set plus \fBapt\fR. If you just
want \fBessential\fR and \fBapt\fR, then this variant is faster than using the
\&\fBessential\fR variant and adding \fBapt\fR via \f(CW\*(C`\-\-include\*(C'\fR because all packages
get installed at once. The downside of this variant is, that if it should
happen that an \fBessential\fR package is not installable, then it will just get
ignored without throwing an error.
.IP \fBbuildd\fR 8
.IX Item "buildd"
The \fBessential\fR set plus apt and build-essential.
It is roughly equivalent to running mmdebstrap with
.Sp
.Vb 1
\&    \-\-variant=essential \-\-include="apt,build\-essential"
.Ve
.IP "\fBrequired\fR, \fBminbase\fR" 8
.IX Item "required, minbase"
The \fBessential\fR set plus all packages with Priority:required.
It is roughly equivalent to running mmdebstrap with
.Sp
.Vb 1
\&    \-\-variant=essential \-\-include="?priority(required)"
.Ve
.IP "\fBimportant\fR, \fBdebootstrap\fR, \fB\-\fR" 8
.IX Item "important, debootstrap, -"
The \fBrequired\fR set plus all packages with Priority:important. This is the
default of debootstrap. It is roughly equivalent to running mmdebstrap with
.Sp
.Vb 1
\&    \-\-variant=essential \-\-include="~prequired|~pimportant"
.Ve
.IP \fBstandard\fR 8
.IX Item "standard"
The \fBimportant\fR set plus all packages with Priority:standard.
It is roughly equivalent to running mmdebstrap with
.Sp
.Vb 1
\&    \-\-variant=essential \-\-include="~prequired|~pimportant|~pstandard"
.Ve
.SH FORMATS
.IX Header "FORMATS"
The output format of \fBmmdebstrap\fR is specified using the \fB\-\-format\fR option.
Without that option the default format is \fIauto\fR. The following formats exist:
.IP \fBauto\fR 8
.IX Item "auto"
When selecting this format (the default), the actual format will be inferred
from the \fITARGET\fR positional argument. If \fITARGET\fR was not specified, then
the \fBtar\fR format will be chosen. If \fITARGET\fR happens to be \fI/dev/null\fR or if
standard output is \fI/dev/null\fR, then the \fBnull\fR format will be chosen. If
\&\fITARGET\fR is an existing directory, and does not equal to \f(CW\*(C`\-\*(C'\fR, then the
\&\fBdirectory\fR format will be chosen. If \fITARGET\fR ends with \f(CW\*(C`.tar\*(C'\fR or with one
of the filename extensions listed in the section \fBCOMPRESSION\fR, or if
\&\fITARGET\fR equals \f(CW\*(C`\-\*(C'\fR, or if \fITARGET\fR is a named pipe (fifo) or if \fITARGET\fR
is a character special file, then the \fBtar\fR format will be chosen. If
\&\fITARGET\fR ends with \f(CW\*(C`.squashfs\*(C'\fR or \f(CW\*(C`.sqfs\*(C'\fR, then the \fBsquashfs\fR format will
be chosen. If \fITARGET\fR ends with \f(CW\*(C`.ext2\*(C'\fR then the \fBext2\fR format will be
chosen. If none of these conditions apply, the \fBdirectory\fR format will be
chosen.
.IP "\fBdirectory\fR, \fBdir\fR" 8
.IX Item "directory, dir"
A chroot directory will be created in \fITARGET\fR.  If the directory already
exists, it must either be empty or only contain an empty \f(CW\*(C`lost+found\*(C'\fR
directory.  The special \fITARGET\fR \f(CW\*(C`\-\*(C'\fR does not work with this format because a
directory cannot be written to standard output. If you need your directory be
named \f(CW\*(C`\-\*(C'\fR, then just explicitly pass the relative path to it like \fI./\-\fR.  If
a directory is chosen as output in any other mode than \fBsudo\fR, then its
contents will have wrong ownership information and special device files will be
missing. Refer to the section \fBMODES\fR for more information.
.IP \fBtar\fR 8
.IX Item "tar"
A temporary chroot directory will be created in \f(CW$TMPDIR\fR or \fI/tmp\fR if
\&\f(CW$TMPDIR\fR is not set. A tarball of that directory will be stored in \fITARGET\fR
or sent to standard output if \fITARGET\fR was omitted or if \fITARGET\fR equals
\&\f(CW\*(C`\-\*(C'\fR.  If \fITARGET\fR ends with one of the filename extensions listed in the
section \fBCOMPRESSION\fR, then a compressed tarball will be created. The tarball
will be in POSIX 1003.1\-2001 (pax) format and will contain extended attributes.
To preserve the extended attributes, you have to pass \fB\-\-xattrs
\&\-\-xattrs\-include='*'\fR to tar when extracting the tarball.
.IP "\fBsquashfs\fR, \fBsqfs\fR" 8
.IX Item "squashfs, sqfs"
A temporary chroot directory will be created in \f(CW$TMPDIR\fR or \fI/tmp\fR if
\&\f(CW$TMPDIR\fR is not set. A tarball of that directory will be piped to the
\&\f(CW\*(C`tar2sqfs\*(C'\fR utility, which will create an xz compressed squashfs image with a
blocksize of 1048576 bytes in \fITARGET\fR.  The special \fITARGET\fR \f(CW\*(C`\-\*(C'\fR does not
work with this format because \f(CW\*(C`tar2sqfs\*(C'\fR can only write to a regular file. If
you need your squashfs image be named \f(CW\*(C`\-\*(C'\fR, then just explicitly pass the
relative path to it like \fI./\-\fR. The \f(CW\*(C`tar2sqfs\*(C'\fR tool only supports a limited
set of extended attribute prefixes. Therefore, extended attributes are disabled
in the resulting image. If you need them, create a tarball first and remove the
extended attributes from its pax headers. Refer to the \fBEXAMPLES\fR section for
how to achieve this.
.IP \fBext2\fR 8
.IX Item "ext2"
A temporary chroot directory will be created in \f(CW$TMPDIR\fR or \fI/tmp\fR if
\&\f(CW$TMPDIR\fR is not set. A tarball of that directory will be piped to the
\&\f(CW\*(C`genext2fs\*(C'\fR utility, which will create an ext2 image that will be
approximately 90% full in \fITARGET\fR.  The special \fITARGET\fR \f(CW\*(C`\-\*(C'\fR does not work
with this format because \f(CW\*(C`genext2fs\*(C'\fR can only write to a regular file. If you
need your ext2 image be named \f(CW\*(C`\-\*(C'\fR, then just explicitly pass the relative path
to it like \fI./\-\fR. To convert the result to an ext3 image, use \f(CW\*(C`tune2fs \-O
has_journal TARGET\*(C'\fR and to convert it to ext4, use \f(CW\*(C`tune2fs \-O
extents,uninit_bg,dir_index,has_journal TARGET\*(C'\fR. Since \f(CW\*(C`genext2fs\*(C'\fR does not
support extended attributes, the resulting image will not contain them.
.IP \fBnull\fR 8
.IX Item "null"
A temporary chroot directory will be created in \f(CW$TMPDIR\fR or \fI/tmp\fR if
\&\f(CW$TMPDIR\fR is not set. After the bootstrap is complete, the temporary chroot
will be deleted without being part of the output. This is most useful when the
desired artifact is generated inside the chroot and it is transferred using
special hooks such as \fBsync-out\fR. It is also useful in situations where only
the exit code or stdout or stderr of a process run in a hook is of interest.
.SH HOOKS
.IX Header "HOOKS"
This section describes properties of the hook options \fB\-\-setup\-hook\fR,
\&\fB\-\-extract\-hook\fR, \fB\-\-essential\-hook\fR and \fB\-\-customize\-hook\fR which are common
to all four of them. Any information specific to each hook is documented under
the specific hook options in the section \fBOPTIONS\fR.
.PP
The options can be specified multiple times and the commands are executed in
the order in which they are given on the command line. There are four different
types of hook option arguments. If the argument passed to the hook option
starts with \f(CW\*(C`copy\-in\*(C'\fR, \f(CW\*(C`copy\-out\*(C'\fR, \f(CW\*(C`tar\-in\*(C'\fR, \f(CW\*(C`tar\-out\*(C'\fR, \f(CW\*(C`upload\*(C'\fR or
\&\f(CW\*(C`download\*(C'\fR followed by a space, then the hook is interpreted as a special
hook. Otherwise, if \fIcommand\fR is an existing executable file from \f(CW$PATH\fR or
if \fIcommand\fR does not contain any shell metacharacters, then \fIcommand\fR is
directly exec-ed with the path to the chroot directory passed as the first
argument. Otherwise, \fIcommand\fR is executed under \fIsh\fR and the chroot
directory can be accessed via \fR\f(CI$1\fR\fI\fR. Most environment variables set by
\&\fBmmdebstrap\fR (like \f(CW\*(C`DEBIAN_FRONTEND\*(C'\fR, \f(CW\*(C`LC_ALL\*(C'\fR and \f(CW\*(C`PATH\*(C'\fR) are preserved.
Most notably, \f(CW\*(C`APT_CONFIG\*(C'\fR is being unset. If you need the path to
\&\f(CW\*(C`APT_CONFIG\*(C'\fR as written by mmdebstrap it can be found in the
\&\f(CW\*(C`MMDEBSTRAP_APT_CONFIG\*(C'\fR environment variable. All environment variables set by
the user are preserved, except for \f(CW\*(C`TMPDIR\*(C'\fR which is cleared. See section
\&\fBTMPDIR\fR. Furthermore, \f(CW\*(C`MMDEBSTRAP_MODE\*(C'\fR will store the mode set by
\&\fB\-\-mode\fR, \f(CW\*(C`MMDEBSTRAP_FORMAT\*(C'\fR stores the format chosen by \fB\-\-format\fR,
\&\f(CW\*(C`MMDEBSTRAP_HOOK\*(C'\fR stores which hook is currently run (setup, extract,
essential, customize), \f(CW\*(C`MMDEBSTRAP_ARGV0\*(C'\fR stores the name of the binary with
which \fBmmdebstrap\fR was executed and \f(CW\*(C`MMDEBSTRAP_VERBOSITY\*(C'\fR stores the
numerical verbosity level (0 for no output, 1 for normal, 2 for verbose and 3
for debug output). The \f(CW\*(C`MMDEBSTRAP_INCLUDE\*(C'\fR variable stores the list of
packages, apt patterns or file paths given by the \fB\-\-include\fR option,
separated by a comma and with commas and percent signs in the option values
urlencoded. If \fISUITE\fR name was supplied, it's stored in \f(CW\*(C`MMDEBSTRAP_SUITE\*(C'\fR.
.PP
In special hooks, the paths inside the chroot are relative to the root
directory of the chroot.  The path on the outside is relative to current
directory of the original \fBmmdebstrap\fR invocation. The path inside the chroot
must already exist. Paths outside the chroot are created as necessary.
.PP
In \fBfakechroot\fR mode, \f(CW\*(C`tar\*(C'\fR, or \f(CW\*(C`sh\*(C'\fR and \f(CW\*(C`cat\*(C'\fR have to be run inside the
chroot or otherwise, symlinks will be wrongly resolved and/or permissions will
be off. This means that the special hooks might fail in \fBfakechroot\fR mode for
the \fBsetup\fR hook or for the \fBextract\fR and \fBcustom\fR variants if no \f(CW\*(C`tar\*(C'\fR or
\&\f(CW\*(C`sh\*(C'\fR and \f(CW\*(C`cat\*(C'\fR is available inside the chroot.
.IP "\fBcopy-out\fR \fIpathinside\fR [\fIpathinside\fR ...] \fIpathoutside\fR" 8
.IX Item "copy-out pathinside [pathinside ...] pathoutside"
Recursively copies one or more files and directories recursively from
\&\fIpathinside\fR inside the chroot to \fIpathoutside\fR outside of the chroot.
.IP "\fBcopy-in\fR \fIpathoutside\fR [\fIpathoutside\fR ...] \fIpathinside\fR" 8
.IX Item "copy-in pathoutside [pathoutside ...] pathinside"
Recursively copies one or more files and directories into the chroot into,
placing them into \fIpathinside\fR inside of the chroot.
.IP "\fBsync-out\fR \fIpathinside\fR \fIpathoutside\fR" 8
.IX Item "sync-out pathinside pathoutside"
Recursively copy everything inside \fIpathinside\fR inside the chroot into
\&\fIpathoutside\fR. In contrast to \fBcopy-out\fR, this command synchronizes the
content of \fIpathinside\fR with the content of \fIpathoutside\fR without deleting
anything from \fIpathoutside\fR but overwriting content as necessary. Use this
command over \fBcopy-out\fR if you don't want to create a new directory outside
the chroot but only update the content of an existing directory.
.IP "\fBsync-in\fR \fIpathoutside\fR \fIpathinside\fR" 8
.IX Item "sync-in pathoutside pathinside"
Recursively copy everything inside \fIpathoutside\fR into \fIpathinside\fR inside the
chroot. In contrast to \fBcopy-in\fR, this command synchronizes the content of
\&\fIpathoutside\fR with the content of \fIpathinside\fR without deleting anything from
\&\fIpathinside\fR but overwriting content as necessary. Use this command over
\&\fBcopy-in\fR if you don't want to create a new directory inside the chroot but
only update the content of an existing directory.
.IP "\fBtar-in\fR \fIoutside.tar\fR \fIpathinside\fR" 8
.IX Item "tar-in outside.tar pathinside"
Unpacks a tarball \fIoutside.tar\fR from outside the chroot into a certain
location \fIpathinside\fR inside the chroot. In \fBunshare\fR mode, device nodes
cannot be created. To ignore device nodes in tarballs, use
\&\fB\-\-skip=tar\-in/mknod\fR.
.IP "\fBtar-out\fR \fIpathinside\fR \fIoutside.tar\fR" 8
.IX Item "tar-out pathinside outside.tar"
Packs the path \fIpathinside\fR from inside the chroot into a tarball, placing it
into a certain location \fIoutside.tar\fR outside the chroot.
.IP "\fBdownload\fR \fIfileinside\fR \fIfileoutside\fR" 8
.IX Item "download fileinside fileoutside"
Copy the file given by \fIfileinside\fR from inside the chroot to outside the
chroot as \fIfileoutside\fR. In contrast to \fBcopy-out\fR, this command only
handles files and not directories. To copy a directory recursively out of the
chroot, use \fBcopy-out\fR or \fBtar-out\fR. Its advantage is, that by being able to
specify the full path on the outside, including the filename, the file on the
outside can have a different name from the file on the inside. In contrast to
\&\fBcopy-out\fR and \fBtar-out\fR, this command follows symlinks.
.IP "\fBupload\fR \fIfileoutside\fR \fIfileinside\fR" 8
.IX Item "upload fileoutside fileinside"
Copy the file given by \fIfileoutside\fR from outside the chroot to inside the
chroot as \fIfileinside\fR. In contrast to \fBcopy-in\fR, this command only
handles files and not directories. To copy a directory recursively into the
chroot, use \fBcopy-in\fR or \fBtar-in\fR. Its advantage is, that by being able to
specify the full path on the inside, including the filename, the file on the
inside can have a different name from the file on the outside. In contrast to
\&\fBcopy-in\fR and \fBtar-in\fR, permission and ownership information will not be
retained.
.SH OPERATION
.IX Header "OPERATION"
This section gives an overview of the different steps to create a chroot. At
its core, what \fBmmdebstrap\fR does can be put into a 14 line shell script:
.PP
.Vb 10
\&    mkdir \-p "$2/etc/apt" "$2/var/cache" "$2/var/lib"
\&    cat << END > "$2/apt.conf"
\&    Apt::Architecture "$(dpkg \-\-print\-architecture)";
\&    Apt::Architectures "$(dpkg \-\-print\-architecture)";
\&    Dir "$(cd "$2" && pwd)";
\&    Dir::Etc::Trusted "$(eval "$(apt\-config shell v Dir::Etc::Trusted/f)"; printf "$v")";
\&    Dir::Etc::TrustedParts "$(eval "$(apt\-config shell v Dir::Etc::TrustedParts/d)"; printf "$v")";
\&    END
\&    echo "deb http://deb.debian.org/debian/ $1 main" > "$2/etc/apt/sources.list"
\&    APT_CONFIG="$2/apt.conf" apt\-get update
\&    APT_CONFIG="$2/apt.conf" apt\-get \-\-yes \-\-download\-only install \*(Aq?essential\*(Aq
\&    for f in "$2"/var/cache/apt/archives/*.deb; do dpkg\-deb \-\-extract "$f" "$2"; done
\&    chroot "$2" sh \-c "dpkg \-\-install \-\-force\-depends /var/cache/apt/archives/*.deb"
.Ve
.PP
The additional complexity of \fBmmdebstrap\fR is to support operation without
superuser privileges, bit-by-bit reproducible output, hooks and foreign
architecture support.
.PP
The remainder of this section explains what \fBmmdebstrap\fR does step-by-step.
.IP \fBcheck\fR 8
.IX Item "check"
Upon startup, several checks are carried out, like:
.RS 8
.IP \(bu 4
whether required utilities (apt, dpkg, tar) are installed
.IP \(bu 4
which mode to use and whether prerequisites are met
.IP \(bu 4
do not allow chrootless mode as root (without fakeroot) unless inside a chroot. This check can be disabled using \fB\-\-skip=check/chrootless\fR
.IP \(bu 4
whether the requested architecture can be executed (requires arch-test) using qemu binfmt_misc support. This requires arch-test and can be disabled using \fB\-\-skip=check/qemu\fR
.IP \(bu 4
how the apt sources can be assembled from \fISUITE\fR, \fIMIRROR\fR and \fB\-\-components\fR and/or from standard input as deb822 or one-line format and whether the required GPG keys exist.
.IP \(bu 4
which output format to pick depending on the \fB\-\-format\fR argument or name of \fITARGET\fR or its type.
.IP \(bu 4
whether the output directory is empty. This check can be disabled using \fB\-\-skip=check/empty\fR
.IP \(bu 4
whether adding a \f(CW\*(C`signed\-by\*(C'\fR to \f(CW\*(C`apt/sources.list\*(C'\fR is necessary. This requires gpg and can be disabled using \fB\-\-skip=check/signed\-by\fR
.RE
.RS 8
.RE
.IP \fBsetup\fR 8
.IX Item "setup"
The following tasks are carried out unless \fB\-\-skip=setup\fR is used:
.RS 8
.IP \(bu 4
create required directories
.IP \(bu 4
write out the temporary apt config file
.IP \(bu 4
populates \fI/etc/apt/apt.conf.d/99mmdebstrap\fR and \fI/etc/dpkg/dpkg.cfg.d/99mmdebstrap\fR with config options from \fB\-\-aptopt\fR and \fB\-\-dpkgopt\fR, respectively
.IP \(bu 4
write out \fI/etc/apt/sources.list\fR
.IP \(bu 4
copy over \fI/etc/resolv.conf\fR and \fI/etc/hostname\fR
.IP \(bu 4
populate \fI/dev\fR if mknod is possible
.RE
.RS 8
.RE
.IP \fBsetup-hook\fR 8
.IX Item "setup-hook"
Run \fB\-\-setup\-hook\fR options and all \fIsetup*\fR scripts in \fB\-\-hook\-dir\fR.
.IP \fBupdate\fR 8
.IX Item "update"
Runs \f(CW\*(C`apt\-get update\*(C'\fR using the temporary apt configuration file created in
the \fBsetup\fR step. This can be disabled using \fB\-\-skip=update\fR.
.IP \fBdownload\fR 8
.IX Item "download"
In the \fBextract\fR and \fBcustom\fR variants, \f(CW\*(C`apt\-get install\*(C'\fR is used to
download all the packages requested via the \fB\-\-include\fR option. The \fBapt\fR
variant uses the fact that libapt treats the \f(CW\*(C`apt\*(C'\fR packages as implicitly
essential to download only all \f(CW\*(C`Essential:yes\*(C'\fR packages plus apt using
\&\f(CW\*(C`apt\-get dist\-upgrade\*(C'\fR. In the remaining variants, all Packages files
downloaded by the \fBupdate\fR step are inspected to find the \f(CW\*(C`Essential:yes\*(C'\fR
package set as well as all packages of the required priority. If \fISUITE\fR is a
non-empty string, then only packages from the archive with suite or codename
matching \fISUITE\fR will be considered for selection of \f(CW\*(C`Essential:yes\*(C'\fR
packages.
.IP \fBmount\fR 8
.IX Item "mount"
Mount relevant device nodes, \fI/proc\fR and \fI/sys\fR into the chroot and unmount
them afterwards. This can be disabled using \fB\-\-skip=chroot/mount\fR or
specifically by \fB\-\-skip=chroot/mount/dev\fR, \fB\-\-skip=chroot/mount/proc\fR and
\&\fB\-\-skip=chroot/mount/sys\fR, respectively. \fBmmdebstrap\fR will disable running
services by temporarily moving \fI/usr/sbin/policy\-rc.d\fR and
\&\fI/usr/sbin/start\-stop\-daemon\fR if they exist. This can be disabled with
\&\fB\-\-skip=chroot/policy\-rc.d\fR and \fB\-\-skip=chroot/start\-stop\-daemon\fR,
respectively.
.IP \fBextract\fR 8
.IX Item "extract"
Extract the downloaded packages into the rootfs.
.IP \fBprepare\fR 8
.IX Item "prepare"
In \fBfakechroot\fR mode, environment variables \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR will be set up
correctly. For foreign \fBfakechroot\fR environments, \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR and
\&\f(CW\*(C`QEMU_LD_PREFIX\*(C'\fR are set up accordingly. This step is not carried out in
\&\fBextract\fR mode and neither for the \fBchrootless\fR variant.
.IP \fBextract-hook\fR 8
.IX Item "extract-hook"
Run \fB\-\-extract\-hook\fR options and all \fIextract*\fR scripts in \fB\-\-hook\-dir\fR.
.IP \fBessential\fR 8
.IX Item "essential"
Uses \f(CW\*(C`dpkg \-\-install\*(C'\fR to properly install all packages that have been
extracted before. Removes all packages downloaded in the \fBdownload\fR step,
except those which were present in \fI/var/cache/apt/archives/\fR before (if any).
This can be disabled using \fB\-\-skip=essential/unlink\fR. This step is not carried
out in \fBextract\fR mode.
.IP \fBessential-hook\fR 8
.IX Item "essential-hook"
Run \fB\-\-essential\-hook\fR options and all \fIessential*\fR scripts in \fB\-\-hook\-dir\fR.
This step is not carried out in \fBextract\fR mode.
.IP \fBinstall\fR 8
.IX Item "install"
Install the apt package into the chroot, if necessary and then run apt from
inside the chroot to install all remaining packages. This step is not carried
out in \fBextract\fR mode.
.IP \fBcustomize-hook\fR 8
.IX Item "customize-hook"
Run \fB\-\-customize\-hook\fR options and all \fIcustomize*\fR scripts in \fB\-\-hook\-dir\fR.
This step is not carried out in \fBextract\fR mode.
.IP \fBunmount\fR 8
.IX Item "unmount"
Unmount everything that was mounted during the \fBmount\fR stage and restores
\&\fI/usr/sbin/policy\-rc.d\fR and \fI/usr/sbin/start\-stop\-daemon\fR if necessary.
.IP \fBcleanup\fR 8
.IX Item "cleanup"
Performs cleanup tasks, unless \fB\-\-skip=cleanup\fR is used:
.RS 8
.IP \(bu 4
Removes the package lists (unless \fB\-\-skip=cleanup/apt/lists\fR) and apt cache (unless \fB\-\-skip=cleanup/apt/cache\fR). Both removals can be disabled by using \fB\-\-skip=cleanup/apt\fR.
.IP \(bu 4
Remove all files that were put into the chroot for setup purposes, like \fI/etc/apt/apt.conf.d/00mmdebstrap\fR and the temporary apt config. This can be disabled using \fB\-\-skip=cleanup/mmdebstrap\fR.
.IP \(bu 4
Remove files that make the result unreproducible and write the empty string to /etc/machine\-id if it exists. This can be disabled using \fB\-\-skip=cleanup/reproducible\fR. Note that this will not remove files that make the result unreproducible on machines with differing \fI/etc/resolv.conf\fR or \fI/etc/hostname\fR. Use a \fB\-\-customize\-hook\fR to make those two files reproducible across multiple hosts. See section \f(CW\*(C`SOURCE_DATE_EPOCH\*(C'\fR for more information. The following files will be removed:
.RS 4
.IP \(bu 4
\&\fI/var/log/dpkg.log\fR
.IP \(bu 4
\&\fI/var/log/apt/history.log\fR
.IP \(bu 4
\&\fI/var/log/apt/term.log\fR
.IP \(bu 4
\&\fI/var/log/alternatives.log\fR
.IP \(bu 4
\&\fI/var/cache/ldconfig/aux\-cache\fR
.IP \(bu 4
\&\fI/var/log/apt/eipp.log.xz\fR
.IP \(bu 4
\&\fI/var/lib/dbus/machine\-id\fR
.RE
.RS 4
.RE
.IP \(bu 4
Remove everything in \fI/run\fR inside the chroot. This can be disabled using \fB\-\-skip=cleanup/run\fR.
.IP \(bu 4
Remove everything in \fI/tmp\fR inside the chroot. This can be disabled using \fB\-\-skip=cleanup/tmp\fR.
.RE
.RS 8
.RE
.IP \fBoutput\fR 8
.IX Item "output"
For formats other than \fBdirectory\fR, pack up the temporary chroot directory
into a tarball, ext2 image or squashfs image and delete the temporary chroot
directory.
.Sp
If \fB\-\-skip=output/dev\fR is added, the resulting chroot will not contain the
device nodes, directories and symlinks that \fBdebootstrap\fR creates but just
an empty /dev as created by \fBbase-files\fR.
.Sp
If \fB\-\-skip=output/mknod\fR is added, the resulting chroot will not contain
device nodes (neither block nor character special devices). This is useful
if the chroot tarball is to be exatracted in environments where mknod does
not function like in unshared user namespaces.
.SH EXAMPLES
.IX Header "EXAMPLES"
Use like debootstrap:
.PP
.Vb 1
\&    $ sudo mmdebstrap unstable ./unstable\-chroot
.Ve
.PP
Without superuser privileges:
.PP
.Vb 1
\&    $ mmdebstrap unstable unstable\-chroot.tar
.Ve
.PP
With no command line arguments at all. The chroot content is entirely defined
by a sources.list file on standard input.
.PP
.Vb 1
\&    $ mmdebstrap < /etc/apt/sources.list > unstable\-chroot.tar
.Ve
.PP
Since the tarball is output on stdout, members of it can be excluded using tar
on-the-fly. For example the /dev directory can be removed from the final
tarbal in cases where it is to be extracted by a non-root user who cannot
create device nodes:
.PP
.Vb 1
\&    $ mmdebstrap unstable | tar \-\-delete ./dev > unstable\-chroot.tar
.Ve
.PP
Create a tarball for use with \f(CW\*(C`sbuild \-\-chroot\-mode=unshare\*(C'\fR:
.PP
.Vb 1
\&    $ mmdebstrap \-\-variant=buildd unstable ~/.cache/sbuild/unstable\-amd64.tar
.Ve
.PP
Instead of a tarball, a squashfs image can be created:
.PP
.Vb 1
\&    $ mmdebstrap unstable unstable\-chroot.squashfs
.Ve
.PP
By default, \fBmmdebstrap\fR runs \fBtar2sqfs\fR with \f(CW\*(C`\-\-no\-skip \-\-exportable
\&\-\-compressor xz \-\-block\-size 1048576\*(C'\fR. To choose a different set of options,
and to filter out all extended attributes not supported by \fBtar2sqfs\fR, pipe
the output of \fBmmdebstrap\fR into \fBtar2sqfs\fR manually like so:
.PP
.Vb 7
\&    $ mmdebstrap unstable \e
\&        | mmtarfilter \-\-pax\-exclude=\*(Aq*\*(Aq \e
\&            \-\-pax\-include=\*(AqSCHILY.xattr.user.*\*(Aq \e
\&            \-\-pax\-include=\*(AqSCHILY.xattr.trusted.*\*(Aq \e
\&            \-\-pax\-include=\*(AqSCHILY.xattr.security.*\*(Aq \e
\&        | tar2sqfs \-\-quiet \-\-no\-skip \-\-force \-\-exportable \-\-compressor xz \e
\&            \-\-block\-size 1048576 unstable\-chroot.squashfs
.Ve
.PP
By default, debootstrapping a stable distribution will add mirrors for security
and updates to the sources.list.
.PP
.Vb 1
\&    $ mmdebstrap stable stable\-chroot.tar
.Ve
.PP
If you don't want this behaviour, you can override it by manually specifying a
mirror in various different ways:
.PP
.Vb 4
\&    $ mmdebstrap stable stable\-chroot.tar http://deb.debian.org/debian
\&    $ mmdebstrap stable stable\-chroot.tar "deb http://deb.debian.org/debian stable main"
\&    $ mmdebstrap stable stable\-chroot.tar /path/to/sources.list
\&    $ mmdebstrap stable stable\-chroot.tar \- < /path/to/sources.list
.Ve
.PP
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).
.PP
.Vb 9
\&    $ mmdebstrap \-\-variant=essential \e
\&        \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/man/*\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-include=/usr/share/man/man[1\-9]/*\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/locale/*\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-include=/usr/share/locale/locale.alias\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-exclude=/usr/share/doc/*\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-include=/usr/share/doc/*/copyright\*(Aq \e
\&        \-\-dpkgopt=\*(Aqpath\-include=/usr/share/doc/*/changelog.Debian.*\*(Aq \e
\&        unstable debian\-unstable.tar
.Ve
.PP
Create a bootable USB Stick that boots into a full Debian desktop:
.PP
.Vb 10
\&    $ mmdebstrap \-\-aptopt=\*(AqApt::Install\-Recommends "true"\*(Aq \-\-customize\-hook \e
\&        \*(Aqchroot "$1" adduser \-\-gecos user \-\-disabled\-password user\*(Aq \e
\&        \-\-customize\-hook=\*(Aqecho \*(Aquser:live\*(Aq | chroot "$1" chpasswd\*(Aq \e
\&        \-\-customize\-hook=\*(Aqecho host > "$1/etc/hostname"\*(Aq \e
\&        \-\-customize\-hook=\*(Aqecho "127.0.0.1 localhost host" > "$1/etc/hosts"\*(Aq \e
\&        \-\-include=linux\-image\-amd64,task\-desktop unstable debian\-unstable.tar
\&    $ cat << END > extlinux.conf
\&    > default linux
\&    > timeout 0
\&    >
\&    > label linux
\&    > kernel /vmlinuz
\&    > append initrd=/initrd.img root=LABEL=rootfs
\&    END
\&    # You can use $(sudo blockdev \-\-getsize64 /dev/sdXXX) to get the right
\&    # image size for the target medium in bytes
\&    $ guestfish \-N debian\-unstable.img=disk:8G \-\- \e
\&        part\-disk /dev/sda mbr : \e
\&        part\-set\-bootable /dev/sda 1 true : \e
\&        mkfs ext4 /dev/sda1 : \e
\&        set\-label /dev/sda1 rootfs : \e
\&        mount /dev/sda1 / : \e
\&        tar\-in debian\-unstable.tar / xattrs:true : \e
\&        upload /usr/lib/EXTLINUX/mbr.bin /boot/mbr.bin : \e
\&        copy\-file\-to\-device /boot/mbr.bin /dev/sda size:440 : \e
\&        extlinux / : copy\-in extlinux.conf / : sync : umount / : shutdown
\&    $ qemu\-system\-x86_64 \-m 1G \-enable\-kvm debian\-unstable.img
\&    $ sudo dd if=debian\-unstable.img of=/dev/sdXXX status=progress
.Ve
.PP
On architectures without extlinux you can also boot using grub2:
.PP
.Vb 12
\&    $ mmdebstrap \-\-include=linux\-image\-amd64,grub2,systemd\-sysv unstable fs.tar
\&    $ guestfish \-N debian\-unstable.img=disk:2G \-\- \e
\&        part\-disk /dev/sda mbr : \e
\&        part\-set\-bootable /dev/sda 1 true : \e
\&        mkfs ext4 /dev/sda1 : \e
\&        set\-label /dev/sda1 rootfs : \e
\&        mount /dev/sda1 / : \e
\&        tar\-in fs.tar / xattrs:true : \e
\&        command "grub\-install /dev/sda" : \e
\&        command update\-grub : \e
\&        sync : umount / : shutdown
\&    $ qemu\-system\-x86_64 \-m 1G \-enable\-kvm debian\-unstable.img
.Ve
.PP
Build libdvdcss2.deb without installing installing anything or changing apt
sources on the current system:
.PP
.Vb 5
\&    $ mmdebstrap \-\-variant=apt \-\-components=main,contrib \-\-include=libdvd\-pkg \e
\&        \-\-customize\-hook=\*(Aqchroot $1 /usr/lib/libdvd\-pkg/b\-i_libdvdcss.sh\*(Aq \e
\&        | tar \-\-extract \-\-verbose \-\-strip\-components=4 \e
\&            \-\-wildcards \*(Aq./usr/src/libdvd\-pkg/libdvdcss2_*_*.deb\*(Aq
\&    $ ls libdvdcss2_*_*.deb
.Ve
.PP
Use as replacement for autopkgtest-build-qemu and vmdb2 for all architectures
supporting EFI booting (amd64, arm64, armhf, i386, riscv64), use a convenience
wrapper around \fBmmdebstrap\fR:
.PP
.Vb 1
\&    $ mmdebstrap\-autopkgtest\-build\-qemu unstable ./autopkgtest.img
.Ve
.PP
Use as replacement for autopkgtest-build-qemu and vmdb2 on architectures
supporting extlinux (amd64 and i386):
.PP
.Vb 10
\&    $ mmdebstrap \-\-variant=important \-\-include=linux\-image\-amd64 \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" passwd \-\-delete root\*(Aq \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" useradd \-\-home\-dir /home/user \-\-create\-home user\*(Aq \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" passwd \-\-delete user\*(Aq \e
\&        \-\-customize\-hook=\*(Aqecho host > "$1/etc/hostname"\*(Aq \e
\&        \-\-customize\-hook=\*(Aqecho "127.0.0.1 localhost host" > "$1/etc/hosts"\*(Aq \e
\&        \-\-customize\-hook=/usr/share/autopkgtest/setup\-commands/setup\-testbed \e
\&        unstable debian\-unstable.tar
\&    $ cat << END > extlinux.conf
\&    > default linux
\&    > timeout 0
\&    >
\&    > label linux
\&    > kernel /vmlinuz
\&    > append initrd=/initrd.img root=/dev/vda1 rw console=ttyS0
\&    END
\&    $ guestfish \-N debian\-unstable.img=disk:8G \-\- \e
\&        part\-disk /dev/sda mbr : \e
\&        part\-set\-bootable /dev/sda 1 true : \e
\&        mkfs ext4 /dev/sda1 : mount /dev/sda1 / : \e
\&        tar\-in debian\-unstable.tar / xattrs:true : \e
\&        upload /usr/lib/EXTLINUX/mbr.bin /boot/mbr.bin : \e
\&        copy\-file\-to\-device /boot/mbr.bin /dev/sda size:440 : \e
\&        extlinux / : copy\-in extlinux.conf / : sync : umount / : shutdown
\&    $ qemu\-img convert \-O qcow2 debian\-unstable.img debian\-unstable.qcow2
.Ve
.PP
As a debootstrap wrapper to run it without superuser privileges but using Linux
user namespaces instead. This fixes Debian bug #829134.
.PP
.Vb 3
\&    $ mmdebstrap \-\-variant=custom \-\-mode=unshare \e
\&        \-\-setup\-hook=\*(Aqdebootstrap unstable "$1"\*(Aq \e
\&        \- debian\-debootstrap.tar
.Ve
.PP
Build a non-Debian chroot like Ubuntu bionic:
.PP
.Vb 2
\&    $ mmdebstrap \-\-aptopt=\*(AqDir::Etc::Trusted
\&       "/usr/share/keyrings/ubuntu\-keyring\-2012\-archive.gpg"\*(Aq bionic bionic.tar
.Ve
.PP
If, for some reason, you cannot use a caching proxy like apt-cacher or
apt-cacher-ng, you can use the \fBsync-in\fR and \fBsync-out\fR special hooks to
synchronize a directory outside the chroot with \fI/var/cache/apt/archives\fR
inside the chroot.
.PP
.Vb 5
\&    $ mmdebstrap \-\-variant=apt \-\-skip=essential/unlink \e
\&        \-\-setup\-hook=\*(Aqmkdir \-p ./cache "$1"/var/cache/apt/archives/\*(Aq \e
\&        \-\-setup\-hook=\*(Aqsync\-in ./cache /var/cache/apt/archives/\*(Aq \e
\&        \-\-customize\-hook=\*(Aqsync\-out /var/cache/apt/archives ./cache\*(Aq \e
\&        unstable /dev/null
.Ve
.PP
Instead of copying potentially large amounts of data with \fBsync-in\fR you can
also use a bind-mount in combination with a \f(CW\*(C`file://\*(C'\fR mirror to make packages
from the outside available inside the chroot:
.PP
.Vb 6
\&    $ mmdebstrap \-\-variant=apt \-\-skip=essential/unlink \e
\&        \-\-setup\-hook=\*(Aqmkdir "$1/tmp/mirror"\*(Aq \e
\&        \-\-setup\-hook=\*(Aqmount \-o ro,bind /tmp/mirror "$1/tmp/mirror"\*(Aq \e
\&        \-\-customize\-hook=\*(Aqsync\-out /var/cache/apt/archives ./cache\*(Aq \e
\&        \-\-customize\-hook=\*(Aqumount "$1/tmp/mirror"; rmdir "$1/tmp/mirror";\*(Aq \e
\&        unstable /dev/null file:///tmp/mirror http://deb.debian.org/debian
.Ve
.PP
To automatically mount all directories referenced by \f(CW\*(C`file://\*(C'\fR mirrors
into the chroot you can use a hook:
.PP
.Vb 3
\&    $ mmdebstrap \-\-variant=apt \e
\&        \-\-hook\-dir=/usr/share/mmdebstrap/hooks/file\-mirror\-automount \e
\&        unstable /dev/null file:///tmp/mirror1 file:///tmp/mirror2
.Ve
.PP
Create a system that can be used with docker:
.PP
.Vb 5
\&    $ mmdebstrap unstable | sudo docker import \- debian
\&    [...]
\&    $ sudo docker run \-it \-\-rm debian whoami
\&    root
\&    $ sudo docker rmi debian
.Ve
.PP
Create and boot a qemu virtual machine for an arbitrary architecture using
the \fBdebvm-create\fR wrapper script around \fBmmdebstrap\fR:
.PP
.Vb 2
\&    $ debvm\-create \-r stable \-\- \-\-architecture=riscv64
\&    $ debvm\-run
.Ve
.PP
Create a system that can be used with podman:
.PP
.Vb 5
\&    $ mmdebstrap unstable | podman import \- debian
\&    [...]
\&    $ podman run \-\-network=none \-it \-\-rm debian whoami
\&    root
\&    $ podman rmi debian
.Ve
.PP
As a docker/podman replacement:
.PP
.Vb 8
\&    $ mmdebstrap unstable chroot.tar
\&    [...]
\&    $ mmdebstrap \-\-variant=custom \-\-skip=update,tar\-in/mknod \e
\&        \-\-setup\-hook=\*(Aqtar\-in chroot.tar /\*(Aq \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" whoami\*(Aq unstable /dev/null
\&    [...]
\&    root
\&    $ rm chroot.tar
.Ve
.PP
You can re-use a chroot tarball created with mmdebstrap for further refinement.
Say you want to create a minimal chroot and a chroot with more packages
installed, then instead of downloading and installing the essential packages
twice you can instead build on top of the already present minimal chroot:
.PP
.Vb 5
\&    $ mmdebstrap \-\-variant=apt unstable chroot.tar
\&    $ mmdebstrap \-\-variant=custom \-\-skip=update,setup,cleanup,tar\-in/mknod \e
\&        \-\-setup\-hook=\*(Aqtar\-in chroot.tar /\*(Aq \e
\&        \-\-customize\-hook=\*(Aqchroot "$1" apt\-get install \-\-yes pkg1 pkg2\*(Aq \e
\&        \*(Aq\*(Aq chroot\-full.tar
.Ve
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """SOURCE_DATE_EPOCH""" 8
.el .IP \f(CWSOURCE_DATE_EPOCH\fR 8
.IX Item "SOURCE_DATE_EPOCH"
By setting \f(CW\*(C`SOURCE_DATE_EPOCH\*(C'\fR the result will be reproducible across multiple
runs with the same options and mirror content. Note that for debootstrap
compatibility, \fBmmdebstrap\fR will copy the host's \fI/etc/resolv.conf\fR and
\&\fI/etc/hostname\fR into the chroot. This means that the \fBmmdebstrap\fR output will
differ if it is run on machines with differing \fI/etc/resolv.conf\fR and
\&\fI/etc/hostname\fR contents. To make the result reproducible across different
hosts, you need to manually either delete both files from the output:
.Sp
.Vb 2
\&    $ mmdebstrap \-\-customize\-hook=\*(Aqrm "$1"/etc/resolv.conf\*(Aq \e
\&                 \-\-customize\-hook=\*(Aqrm "$1"/etc/hostname\*(Aq ...
.Ve
.Sp
or fill them with reproducible content:
.Sp
.Vb 2
\&    $ mmdebstrap \-\-customize\-hook=\*(Aqecho nameserver X > "$1"/etc/resolv.conf\*(Aq \e
\&                 \-\-customize\-hook=\*(Aqecho host > "$1"/etc/hostname\*(Aq ...
.Ve
.ie n .IP """TMPDIR""" 8
.el .IP \f(CWTMPDIR\fR 8
.IX Item "TMPDIR"
When creating a tarball, a temporary directory is populated with the rootfs
before the tarball is packed. The location of that temporary directory will be
in \fI/tmp\fR or the location pointed to by \f(CW\*(C`TMPDIR\*(C'\fR if that environment variable
is set. Setting \f(CW\*(C`TMPDIR\*(C'\fR to a different directory than \fI/tmp\fR is useful if
you have \fI/tmp\fR on a tmpfs that is too small for your rootfs.
.Sp
If you set \f(CW\*(C`TMPDIR\*(C'\fR in \fBunshare\fR mode, then the unshared user must be able to
access the directory. This means that the directory itself must be
world-writable and all its ancestors must be at least world-executable.
.Sp
Since \f(CW\*(C`TMPDIR\*(C'\fR is only valid outside the chroot, the variable is being unset
when running hook scripts. If you need a valid temporary directory in a hook,
consider using \fI/tmp\fR inside your target directory.
.SH DEBOOTSTRAP
.IX Header "DEBOOTSTRAP"
This section lists some differences to debootstrap.
.IP \(bu 8
More than one mirror possible
.IP \(bu 8
Default mirrors for stable releases include updates and security mirror
.IP \(bu 8
Multiple ways to operate as non-root: fakechroot and unshare
.IP \(bu 8
twice as fast
.IP \(bu 8
Can create a chroot with only \f(CW\*(C`Essential:yes\*(C'\fR packages and their deps
.IP \(bu 8
Reproducible output by default if \f(CW$SOURCE_DATE_EPOCH\fR is set
.IP \(bu 8
Can create output on filesystems with nodev set
.IP \(bu 8
apt cache and lists are cleaned at the end
.IP \(bu 8
foreign architecture chroots using qemu-user
.PP
Limitations in comparison to debootstrap:
.IP \(bu 8
Only runs on systems with apt installed (Debian and derivatives)
.IP \(bu 8
No \fISCRIPT\fR argument (use hooks instead)
.IP \(bu 8
Some debootstrap options don't exist, namely:
.Sp
\&\fI\-\-second\-stage\fR, \fI\-\-exclude\fR, \fI\-\-resolve\-deps\fR, \fI\-\-force\-check\-gpg\fR,
\&\fI\-\-merged\-usr\fR and \fI\-\-no\-merged\-usr\fR
.SH MERGED\-/USR
.IX Header "MERGED-/USR"
\&\fBmmdebstrap\fR will create a merged\-/usr chroot or not depending on whether
packages setting up merged\-/usr (i.e. the \fBusrmerge\fR package) are installed or
not. In Debian, the essential package \fBinit-system-helpers\fR depends on the
\&\fBusrmerge\fR package, starting with Debian 12 (Bookworm).
.PP
Before Debian 12 (Bookworm), to force \fBmmdebstrap\fR to create a chroot with
merged\-/usr using symlinks, either explicitly install the \fBusrmerge\fR package:
.PP
.Vb 1
\&    \-\-include=usrmerge
.Ve
.PP
or setup merged\-/usr using the debootstrap-method which takes care of the
architecture specific symlinks and installs the \fBusr-is-merged\fR package.
.PP
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/merged\-usr
.Ve
.PP
To force \fBmmdebstrap\fR to create a chroot without merged\-/usr even after the
Debian 12 (Bookworm) release, you can use the following hook:
.PP
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/no\-merged\-usr
.Ve
.PP
This will write "this system will not be supported in the future" into
\&\fI/etc/unsupported\-skip\-usrmerge\-conversion\fR inside the chroot and install the
\&\fBusr-is-merged\fR package to avoid the installation of the \fBusrmerge\fR package
and its dependencies.
.PP
If you are using \fBmmdebstrap\fR in a setup where you do not know upfront whether
the chroot you are creating should be merged\-/usr or not and you want to avoid
installation of the \fBusrmerge\fR package and it's dependencies, you can use:
.PP
.Vb 1
\&    \-\-hook\-dir=/usr/share/mmdebstrap/hooks/maybe\-merged\-usr
.Ve
.PP
That hook will use the availability of the \fBusr-is-merged\fR package to decide
whether to call the \fBmerged-usr\fR hook or not.
.SH COMPRESSION
.IX Header "COMPRESSION"
\&\fBmmdebstrap\fR will choose a suitable compressor for the output tarball
depending on the filename extension. The following mapping from filename
extension to compressor applies:
.PP
.Vb 10
\& 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
.Ve
.PP
To change compression specific options, either use the respecitve environment
variables like \fBXZ_OPT\fR or send \fBmmdebstrap\fR output to your compressor of
choice with a pipe.
.SH WRAPPERS
.IX Header "WRAPPERS"
.SS debvm
.IX Subsection "debvm"
\&\fBdebvm\fR helps create and run virtual machines for various Debian releases and
architectures.  The tool \fBdebvm-create\fR can be used to create a virtual
machine image and the tool \fBdebvm-run\fR can be used to run such a machine
image. Their purpose primarily is testing software using qemu as a containment
technology.  These are relatively thin wrappers around \fBmmdebstrap\fR and
\&\fBqemu\fR.
.SS bdebstrap
.IX Subsection "bdebstrap"
\&\fBbdebstrap\fR is a YAML config based multi-mirror Debian chroot creation tool.
\&\fBbdebstrap\fR is an alternative to \fBdebootstrap\fR and a wrapper around
\&\fBmmdebstrap\fR to support YAML based configuration files. It inherits all
benefits from \fBmmdebstrap\fR. The support for configuration allows storing all
customization in a YAML file instead of having to use a very long one-liner
call to \fBmmdebstrap\fR. It also layering multiple customizations on top of each
other, e.g. to support flavors of an image.
.SH BUGS
.IX Header "BUGS"
https://gitlab.mister\-muffin.de/josch/mmdebstrap/issues
.PP
https://bugs.debian.org/src:mmdebstrap
.PP
As of version 1.20.9, dpkg does not provide facilities preventing it from
reading the dpkg configuration of the machine running \fBmmdebstrap\fR.
Therefore, until this dpkg limitation is fixed, a default dpkg configuration is
recommended on machines running \fBmmdebstrap\fR. If you are using \fBmmdebstrap\fR
as the non-root user, then as a workaround you could run \f(CW\*(C`chmod 600
/etc/dpkg/dpkg.cfg.d/*\*(C'\fR so that the config files are only accessible by the
root user. See Debian bug #808203.
.PP
With apt versions before 2.1.16, setting \f(CW\*(C`[trusted=yes]\*(C'\fR or
\&\f(CW\*(C`Acquire::AllowInsecureRepositories "1"\*(C'\fR to allow signed archives without a
known public key or unsigned archives will fail because of a gpg warning in the
apt output. Since apt does not communicate its status via any other means than
human readable strings, and because \fBmmdebstrap\fR wants to treat transient
network errors as errors, \fBmmdebstrap\fR treats any warning from "apt-get
update" as an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebootstrap\fR\|(8), \fBdebvm\fR\|(1), \fBbdebstrap\fR\|(1)