mmdebstrap/README.md

179 lines
6.6 KiB
Markdown
Raw Normal View History

2018-09-18 09:20:24 +00:00
mmdebstrap
==========
An alternative to debootstrap which uses apt internally and is thus able to use
more than one mirror and resolve more complex dependencies.
Usage
-----
Use like debootstrap:
sudo mmdebstrap unstable ./unstable-chroot
Without superuser privileges:
mmdebstrap unstable unstable-chroot.tar
With complex apt options:
cat /etc/apt/sources.list | mmdebstrap > unstable-chroot.tar
2020-01-19 21:20:25 +00:00
For the full documentation use:
pod2man ./mmdebstrap | man -l -
Or read a HTML version of the man page in either of these locations:
- https://gitlab.mister-muffin.de/josch/mmdebstrap/wiki
- https://manpages.debian.org/unstable/mmdebstrap/mmdebstrap.1.en.html
2018-09-18 09:20:24 +00:00
The sales pitch in comparison to debootstrap
--------------------------------------------
Summary:
- more than one mirror possible
- security and updates mirror included for Debian stable chroots
- twice as fast
2018-09-18 09:20:24 +00:00
- chroot with apt in 11 seconds
- gzipped tarball with apt is 27M small
- bit-by-bit reproducible output
- unprivileged operation using Linux user namespaces or fakechroot
2018-09-18 09:20:24 +00:00
- can operate on filesystems mounted with nodev
- foreign architecture chroots with qemu-user
- variant installing only Essential:yes packages and dependencies
- temporary chroots by redirecting to /dev/null
- chroots without apt inside (for chroot from buildinfo file with debootsnap)
2018-09-18 09:20:24 +00:00
The author believes that a chroot of a Debian stable release should include the
latest packages including security fixes by default. This has been a wontfix
with debootstrap since 2009 (See #543819 and #762222). Since mmdebstrap uses
apt internally, support for multiple mirrors comes for free and stable or
oldstable **chroots will include security and updates mirrors**.
A side-effect of using apt is being twice as fast as debootstrap. The
timings were carried out on a laptop with an Intel Core i5-5200U, using a
mirror on localhost and a tmpfs.
| variant | mmdebstrap | debootstrap |
| --------- | ---------- | ------------ |
| essential | 9.52 s | n.a |
| apt | 10.98 s | n.a |
| minbase | 13.54 s | 26.37 s |
| buildd | 21.31 s | 34.85 s |
| - | 23.01 s | 48.83 s |
2018-09-18 09:20:24 +00:00
Apt considers itself an `Essential: yes` package. This feature allows one to
create a chroot containing just the `Essential: yes` packages and apt (and
their hard dependencies) in **just 11 seconds**.
If desired, a most minimal chroot with just the `Essential: yes` packages and
their hard dependencies can be created with a gzipped tarball size of just 34M.
By using dpkg's `--path-exclude` option to exclude documentation, even smaller
gzipped tarballs of 21M in size are possible. If apt is included, the result is
a **gzipped tarball of only 27M**.
These small sizes are also achieved because apt caches and other cruft is
stripped from the chroot. This also makes the result **bit-by-bit
reproducible** if the `$SOURCE_DATE_EPOCH` environment variable is set.
The author believes, that it should not be necessary to have superuser
2018-09-18 11:11:15 +00:00
privileges to create a file (the chroot tarball) in one's home directory.
Thus, mmdebstrap provides multiple options to create a chroot tarball with the
2021-08-17 09:07:48 +00:00
right permissions **without superuser privileges**. This avoids a whole class
of bugs like #921815. Depending on what is available, it uses either Linux user
namespaces or fakechroot. Debootstrap supports fakechroot but will not
2021-08-17 09:07:48 +00:00
create a tarball with the right permissions by itself. Support for Linux user
namespaces is missing (see #829134).
2018-09-18 09:20:24 +00:00
When creating a chroot tarball with debootstrap, the temporary chroot directory
cannot be on a filesystem that has been mounted with nodev. In unprivileged
2018-09-18 11:11:15 +00:00
mode, **mknod is never used**, which means that /tmp can be used as a temporary
2018-09-18 09:20:24 +00:00
directory location even if if it's mounted with nodev as a security measure.
If the chroot architecture cannot be executed by the current machine, qemu-user
2018-09-18 11:11:15 +00:00
is used to allow one to create a **foreign architecture chroot**.
2018-09-18 09:20:24 +00:00
Limitations in comparison to debootstrap
----------------------------------------
Debootstrap supports creating a Debian chroot on non-Debian systems but
2021-08-17 09:07:48 +00:00
mmdebstrap requires apt and is thus limited to Debian and derivatives. This
means that mmdebstrap can never fully replace debootstrap and debootstrap will
continue to be relevant in situations where you want to create a Debian chroot
from a platform without apt and dpkg.
2018-09-18 09:20:24 +00:00
There is no `SCRIPT` argument.
2020-01-19 21:20:25 +00:00
The following options, don't exist: `--second-stage`, `--exclude`,
`--resolve-deps`, `--force-check-gpg`, `--merged-usr` and `--no-merged-usr`.
The quirks from debootstrap are needed to create chroots of Debian unstable
from snapshot.d.o before timestamp 20141107T220431Z or Debian 8 (Jessie) or
later.
2018-09-18 09:20:24 +00:00
Tests
=====
2018-10-22 18:37:31 +00:00
The script `coverage.sh` runs mmdebstrap in all kind of scenarios to execute
all code paths of the script. It verifies its output in each scenario and
2018-11-23 16:26:50 +00:00
displays the results gathered with Devel::Cover. It also compares the output of
2020-01-19 21:20:25 +00:00
mmdebstrap with debootstrap in several scenarios. To run the testsuite, run:
./make_mirror.sh
CMD=./mmdebstrap ./coverage.sh
To also generate perl Devel::Cover data, omit the `CMD` environment variable.
But that will also take a lot longer.
The `make_mirror.sh` script will be a no-op if nothing changed in Debian
unstable. You don't need to run `make_mirror.sh` before every invocation of
`coverage.sh`. When you make changes to `make_mirror.sh` and want to regenerate
the cache, run:
2020-01-19 21:20:25 +00:00
touch -d yesterday shared/cache/debian/dists/unstable/Release
2018-10-22 18:37:31 +00:00
The script `coverage.sh` does not need an active internet connection by
default. An online connection is only needed by the `make_mirror.sh` script
which fills a local cache with a few minimal Debian mirror copies.
By default, `coverage.sh` will skip running a single test which tries creating
a Ubuntu Focal chroot. To not skip that test, run `coverage.sh` with the
environment variable `ONLINE=yes`.
If a test fails you can run individual tests by executing `coverage.py` with
the test name and optionally limit it to a specific distribution like so:
CMD=./mmdebstrap ./coverage.py --dist unstable check-against-debootstrap-dist
2018-09-18 09:20:24 +00:00
Bugs
====
mmdebstrap has bugs. Report them here:
https://gitlab.mister-muffin.de/josch/mmdebstrap/issues
2020-01-19 21:20:25 +00:00
Contributors
============
2021-08-16 11:12:55 +00:00
- Johannes Schauer Marin Rodrigues (main author)
2020-01-19 21:20:25 +00:00
- Helmut Grohne
2024-06-26 05:36:40 +00:00
- Jochen Sprickerhof
2023-03-17 07:03:19 +00:00
- Gioele Barabucci
2020-01-19 21:20:25 +00:00
- Benjamin Drung
2021-08-17 09:06:55 +00:00
- Josh Triplett
- Konstantin Demin
2024-06-26 05:36:40 +00:00
- Chris Hofstaedtler
- Colin Watson
2022-11-18 08:48:07 +00:00
- David Kalnischkies
- Emilio Pozuelo Monfort
2024-01-29 10:39:53 +00:00
- Francesco Poli
2023-03-17 07:03:19 +00:00
- Jakub Wilk
2022-11-18 08:48:07 +00:00
- Joe Groocock
2024-06-26 05:36:40 +00:00
- Max-Julian Pogner
2022-11-18 08:48:07 +00:00
- Nicolas Vigier
- Raul Tambre
- Steve Dodd
2021-08-17 09:06:55 +00:00
- Trent W. Buck
- Vagrant Cascadian