Scroll to navigation

MMDEBSTRAP(1) User Contributed Perl Documentation MMDEBSTRAP(1)

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. 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. 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, the path to a squashfs image 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 ends with ".squashfs" or ".sqfs", then TARGET will be interpreted as a path to a squashfs image. If TARGET is the path to a tarball filename or a squashfs image 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. When mmdebstrap creates a tarball it also stores extended attributes. To preserve the extended attributes, you have to pass --xattrs --xattrs-include='*' to tar when extracting the tarball. If TARGET is the path to a squashfs image, mmdebstrap will create an xz compressed image with a blocksize of 1048576 bytes. If TARGET does neither end with ".tar" nor with any of the filename extensions listed in the section COMPRESSION, nor with ".squashfs" or ".sqfs", 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 synopsis and options of this man page and exit.
--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:

    pod2man /usr/bin/mmdebstrap | man -l -
    
--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 debootstrap. 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, proot and chrootless. 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.

Example: This is necessary for allowing old timestamps from snapshot.debian.org

    --aptopt='Acquire::Check-Valid-Until "false"'
    

Example: Settings controlling download of package description translations

    --aptopt='Acquire::Languages { "environment"; "en"; }'
    --aptopt='Acquire::Languages "none"'
    

Example: Enable installing Recommends (by default mmdebstrap doesn't)

    --aptopt='Apt::Install-Recommends "true"'
    

Example: Configure apt-cacher or apt-cacher-ng as an apt proxy

    --aptopt='Acquire::http { Proxy "http://127.0.0.1:3142"; }'
    

Example: For situations in which the apt sandbox user cannot access the chroot

    --aptopt='APT::Sandbox::User "root"'
    

Example: Minimizing the number of packages installed from experimental

    --aptopt='APT::Solver "aspcud"'
    --aptopt='APT::Solver::aspcud::Preferences
       "-count(solution,APT-Release:=/a=experimental/),-removed,-changed,-new"'
    
--keyring=file|directory
Change the default keyring to use by apt. By default, /etc/apt/trusted.gpg and /etc/apt/trusted.gpg.d are used. 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 not use this option to pass multiple files and/or directories. Using the "--keyring" argument in the following way is equal to keeping the default:

    --keyring=/etc/apt/trusted.gpg --keyring=/etc/apt/trusted.gpg.d
    

If you need to pass multiple keyrings, use the "signed-by" option when specifying the mirror like this:

    mmdebstrap mysuite out.tar "deb [signed-by=/path/to/key.gpg] http://..."
    

The "signed-by" option will automatically be added to the final "sources.list" if the keyring required for the selected SUITE is not yet trusted by apt. Automatically adding the "signed-by" option in these cases requires "gpg" to be installed. If "gpg" and "ubuntu-archive-keyring" are installed, then you can create a Ubuntu Bionic chroot on Debian like this:

    mmdebstrap bionic ubuntu-bionic.tar
    

The resulting chroot will have a "source.list" with a "signed-by" option pointing to /usr/share/keyrings/ubuntu-archive-keyring.gpg.

--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: Exclude paths to reduce chroot size

    --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.*'
    

Example: Do not perform safe I/O operations when unpacking for more speed

    --dpkgopt=force-unsafe-io
    
--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 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. Package names are directly passed to apt and thus, you can use apt features like "pkg/suite", "pkg=version", "pkg-" or use a glob or regex for "pkg". See apt(8) for the supported syntax. 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:

    --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-
    
--components=comp1[,comp2,...]
Comma or whitespace separated list of components like main, contrib and non-free which will be used for all URI-only MIRROR 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:

    --components="main contrib non-free"
    --components=main,contrib,non-free
    --comp=main --comp="contrib non-free" --comp="main,non-free"
    
--architectures=native[,foreign1,...]
Comma or whitespace 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. 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:

    --architectures="amd64 armhf mipsel"
    --architectures=amd64,armhf,mipsel
    --arch=amd64 --arch="armhf mipsel" --arch=armhf,mipsel
    
--simulate, --dry-run
Run apt-get with --simulate. 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.
-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 unprivileged 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 ownership information. Choose to create a tarball instead. This mode requires the sysctl "kernel.unprivileged_userns_clone" being set to 1. SETTING THIS OPTION HAS SECURITY IMPLICATIONS. Refer to <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=898446>
fakeroot, fakechroot
This mode will exec mmdebstrap again under "fakechroot fakeroot". A directory chroot created with this mode will end up with wrong permissions. If you need a directory then run mmdebstrap under "fakechroot fakeroot -s fakeroot.env" and use "fakeroot.env" later when entering the chroot with "fakechroot fakeroot -i fakeroot.env chroot ...". This mode will not work if maintainer scripts are unable to handle "LD_PRELOAD" correctly like the package initramfs-tools until version 0.132. This mode will also not work with a different libc inside the chroot than on the outside. Since ldconfig cannot run under fakechroot, the final system will not contain /etc/ld.so.cache. See the section LIMITATIONS in fakechroot(1).
proot
This mode will carry out all calls to chroot with proot instead. Since ownership information is only retained while proot is still running, this will lead to wrong ownership information in the final directory (everything will be owned by the user that executed mmdebstrap) and tarball (everything will be owned by the root user). Extended attributes are not retained. 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. Unless mmdebstrap was run inside fakeroot, the TARGET directory will be owned by the user 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

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:

    $ mmdebstrap unstable | tar --delete ./dev > unstable-chroot.tar

Instead of a tarball, a squashfs image can be created:

    $ mmdebstrap unstable unstable-chroot.squashfs

By default, mmdebstrap runs tar2sqfs with "--no-skip --exportable --compressor xz --block-size 1048576". To choose a different set of options, pipe the output of mmdebstrap into tar2sqfs manually.

By default, debootstrapping a stable distribution will add mirrors for security and updates to the sources.list.

    $ mmdebstrap stable stable-chroot.tar

If you don't want this behaviour, you can override it by manually specifying a mirror in various different ways:

    $ 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

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)

Build a non-Debian chroot like Ubuntu bionic:

    $ mmdebstrap --aptopt='Dir::Etc::Trusted
       "/usr/share/keyrings/ubuntu-keyring-2012-archive.gpg"' bionic bionic.tar

ENVIRONMENT VARIABLES

"SOURCE_DATE_EPOCH"
By setting "SOURCE_DATE_EPOCH" the result will be reproducible over multiple runs with the same options and mirror content.
"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 /tmp or the location pointed to by "TMPDIR" if that environment variable is set.

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 deps
  • 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 (Debian and derivatives)
  • No SCRIPT argument
  • Some debootstrap options don't exist, namely:

    --second-stage, --exclude, <--resolve-deps>, --force-check-gpg, --merged-usr and --no-merged-usr

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 --threads=0
 .txz      xz --threads=0
 .zst      zstd

To change compression specific options, either use the respecitve environment variables like XZ_OPT or send mmdebstrap output to your compressor of choice with a pipe.

BUGS

https://gitlab.mister-muffin.de/josch/mmdebstrap/issues

https://bugs.debian.org/src:mmdebstrap

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.

Setting [trusted=yes] to allow signed archives without a known public key 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, mmdebstrap treats any warning from "apt-get update" as an error. Fixing this will require apt to provide a machine readable status interface. See Debian bugs #778357, #776152, #696335, and #745735.

SEE ALSO

    debootstrap(8)
2020-05-14 perl v5.30.0