.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "BDEBSTRAP" "1" "2020-05-26" "bdebstrap" "bdebstrap\[cq]s Manual"
.hy
.SH NAME
.PP
bdebstrap - YAML config based multi-mirror Debian chroot creation tool
.SH SYNOPSIS
.PP
\f[B]bdebstrap\f[R] [\f[B]-h\f[R]|\f[B]--help\f[R]]
[\f[B]-c\f[R]|\f[B]--config\f[R] \f[I]CONFIG\f[R]]
[\f[B]-n\f[R]|\f[B]--name\f[R] \f[I]NAME\f[R]]
[\f[B]-e\f[R]|\f[B]--env\f[R] \f[I]ENV\f[R]]
[\f[B]-s\f[R]|\f[B]--simulate\f[R]|\f[B]--dry-run\f[R]]
[\f[B]-b\f[R]|\f[B]--output-base-dir\f[R] \f[I]OUTPUT_BASE_DIR\f[R]]
[\f[B]-o\f[R]|\f[B]--output\f[R] \f[I]OUTPUT\f[R]]
[\f[B]-q\f[R]|\f[B]--quiet\f[R]|\f[B]--silent\f[R]|\f[B]-v\f[R]|\f[B]--verbose\f[R]|\f[B]--debug\f[R]]
[\f[B]-f\f[R]|\f[B]--force\f[R]] [\f[B]-t\f[R]|\f[B]--tmpdir\f[R]
\f[I]TMPDIR\f[R]] [\f[B]--variant\f[R]
{\f[I]extract\f[R],\f[I]custom\f[R],\f[I]essential\f[R],\f[I]apt\f[R],\f[I]required\f[R],\f[I]minbase\f[R],\f[I]buildd\f[R],\f[I]important\f[R],\f[I]debootstrap\f[R],\f[I]-\f[R],\f[I]standard\f[R]}]
[\f[B]--mode\f[R]
{\f[I]auto\f[R],\f[I]sudo\f[R],\f[I]root\f[R],\f[I]unshare\f[R],\f[I]fakeroot\f[R],\f[I]fakechroot\f[R],\f[I]proot\f[R],\f[I]chrootless\f[R]}]
[\f[B]--aptopt\f[R] \f[I]APTOPT\f[R]] [\f[B]--keyring\f[R]
\f[I]KEYRING\f[R]] [\f[B]--dpkgopt\f[R] \f[I]DPKGOPT\f[R]]
[\f[B]--hostname\f[R] \f[I]HOSTNAME\f[R]]
[\f[B]--install-recommends\f[R]]
[\f[B]--packages\f[R]|\f[B]--include\f[R] \f[I]PACKAGES\f[R]]
[\f[B]--components\f[R] \f[I]COMPONENTS\f[R]] [\f[B]--architectures\f[R]
\f[I]ARCHITECTURES\f[R]] [\f[B]--setup-hook\f[R] \f[I]COMMAND\f[R]]
[\f[B]--essential-hook\f[R] \f[I]COMMAND\f[R]]
[\f[B]--customize-hook\f[R] \f[I]COMMAND\f[R]] [\f[B]--cleanup-hook\f[R]
\f[I]COMMAND\f[R]] [\f[B]--suite\f[R] \f[I]SUITE\f[R]]
[\f[B]--target\f[R] \f[I]TARGET\f[R]] [\f[B]--mirrors\f[R]
\f[I]MIRRORS\f[R]] [\f[I]SUITE\f[R] [\f[I]TARGET\f[R]
[\f[I]MIRROR\f[R]\&...]]]
.SH DESCRIPTION
.PP
\f[B]bdebstrap\f[R] creates a Debian chroot of \f[I]SUITE\f[R] into
\f[I]TARGET\f[R] from one or more \f[I]MIRROR\f[R]s and places meta-data
in the \f[I]OUTPUT\f[R] directory: A \f[I]config.yaml\f[R] containing
the configuration for the build (useful for rebuilds) and a
\f[I]manifest\f[R] listing all installed packages and versions.
If \f[I]TARGET\f[R] is just a filename (and not include the path), it
will be placed in the \f[I]OUTPUT\f[R] directory as well.
\f[B]bdebstrap\f[R] extents mmdebtrap to make it configurable via YAML
configuration files for more complex builds.
.PP
The configuration parameters can be passed to \f[B]bdebstrap\f[R] as
command line arguments or in one or more configuration YAML files.
The content of YAML files will be merged by appending lists and
recursively merging maps.
Arguments specified on the command line will take precedence over values
provided in the YAML configuration file.
The final merged parameters will be stored in the output directory as
\f[I]config.yaml\f[R].
.SH OPTIONS
.TP
\f[B]-h\f[R], \f[B]--help\f[R]
Show a help message and exit
.TP
\f[B]-c\f[R] \f[I]CONFIG\f[R], \f[B]--config\f[R] \f[I]CONFIG\f[R]
Configuration YAML file.
See YAML CONFIGURATION below for the expected structure of this file.
This parameter can be specified multiple times.
The content of YAML files will be merged by appending lists and
recursively merging maps.
.TP
\f[B]-n\f[R] \f[I]NAME\f[R], \f[B]--name\f[R] \f[I]NAME\f[R]
name of the generated golden image.
If no output directory is specified, the golden image will be placed in
\f[I]OUTPUT_BASE_DIR\f[R]/\f[I]NAME\f[R].
.TP
\f[B]-e\f[R] \f[I]ENV\f[R], \f[B]--env\f[R] \f[I]ENV\f[R]
Add an additional environment variable.
These environment variable will be set when calling the hooks.
.TP
\f[B]-s\f[R], \f[B]--simulate\f[R], \f[B]--dry-run\f[R]
Run apt-get with \f[B]--simulate\f[R].
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.
.TP
\f[B]-b\f[R] \f[I]OUTPUT_BASE_DIR\f[R], \f[B]--output-base-dir\f[R] \f[I]OUTPUT_BASE_DIR\f[R]
output base directory.
By default it is the current directory.
.TP
\f[B]-o\f[R] \f[I]OUTPUT\f[R], \f[B]--output\f[R] \f[I]OUTPUT\f[R]
output directory (default: output-base-dir/name)
.TP
\f[B]-q\f[R], \f[B]--quiet\f[R], \f[B]--silent\f[R]
Do not write anything to standard error except errors.
If used together with \f[B]--verbose\f[R] or \f[B]--debug\f[R], only the
last option will take effect.
.TP
\f[B]-v\f[R], \f[B]--verbose\f[R]
Write informational messages (about configuration files, environment
variables, mmdebstrap call, etc.) to standard error.
Instead of progress bars, \f[B]mmdebstrap\f[R] writes the dpkg and apt
output directly to standard error.
If used together with \f[B]--quiet\f[R] or \f[B]--debug\f[R], only the
last option will take effect.
.TP
\f[B]--debug\f[R]
In addition to the output produced by \f[B]--verbose\f[R], write
detailed debugging information to standard error.
Errors of \f[B]mmdebstrap\f[R] will print a backtrace.
If used together with \f[B]--quiet\f[R] or \f[B]--verbose\f[R], only the
last option will take effect.
.TP
\f[B]-f\f[R], \f[B]--force\f[R]
Remove existing output directory before creating a new one
.TP
\f[B]-t\f[R] \f[I]TMPDIR\f[R], \f[B]--tmpdir\f[R] \f[I]TMPDIR\f[R]
Temporary directory for building the image (default: /tmp)
.TP
\f[B]--variant\f[R] {\f[I]extract\f[R],\f[I]custom\f[R],\f[I]essential\f[R],\f[I]apt\f[R],\f[I]required\f[R],\f[I]minbase\f[R],\f[I]buildd\f[R],\f[I]important\f[R],\f[I]debootstrap\f[R],\f[I]-\f[R],\f[I]standard\f[R]}
Choose which package set to install.
.TP
\f[B]--mode\f[R] {\f[I]auto\f[R],\f[I]sudo\f[R],\f[I]root\f[R],\f[I]unshare\f[R],\f[I]fakeroot\f[R],\f[I]fakechroot\f[R],\f[I]proot\f[R],\f[I]chrootless\f[R]}
Choose how to perform the chroot operation and create a filesystem with
ownership information different from the current user.
.TP
\f[B]--aptopt\f[R] \f[I]APTOPT\f[R]
Pass arbitrary options or configuration files to apt.
.TP
\f[B]--keyring\f[R] \f[I]KEYRING\f[R]
Change the default keyring to use by apt.
.TP
\f[B]--dpkgopt\f[R] \f[I]DPKGOPT\f[R]
Pass arbitrary options or configuration files to dpkg.
.TP
\f[B]--hostname\f[R] \f[I]HOSTNAME\f[R]
Write the given \f[I]HOSTNAME\f[R] into \f[I]/etc/hostname\f[R] in the
target chroot.
.TP
\f[B]--install-recommends\f[R]
Consider recommended packages as a dependency for installing.
.TP
\f[B]--packages\f[R] \f[I]PACKAGES\f[R], \f[B]--include\f[R] \f[I]PACKAGES\f[R]
Comma or whitespace separated list of packages which will be installed
in addition to the packages installed by the specified variant.
.TP
\f[B]--components\f[R] \f[I]COMPONENTS\f[R]
Comma or whitespace separated list of components like main, contrib and
non-free which will be used for all URI-only \f[I]MIRROR\f[R] arguments.
.TP
\f[B]--architectures\f[R] \f[I]ARCHITECTURES\f[R]
Comma or whitespace separated list of architectures.
The first architecture is the native architecture inside the chroot.
.TP
\f[B]--setup-hook\f[R] \f[I]COMMAND\f[R]
Execute arbitrary \f[I]COMMAND\f[R] 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.
This option can be specified multiple times.
.TP
\f[B]--essential-hook\f[R] \f[I]COMMAND\f[R]
Execute arbitrary \f[I]COMMAND\f[R] after the Essential:yes packages
have been installed, but before installing the remaining packages.
This option can be specified multiple times.
.TP
\f[B]--customize-hook\f[R] \f[I]COMMAND\f[R]
Execute arbitrary \f[I]COMMAND\f[R] after the chroot is set up and all
packages got installed but before final cleanup actions are carried out.
This option can be specified multiple times.
.TP
\f[B]--cleanup-hook\f[R] \f[I]COMMAND\f[R]
Execute arbitrary \f[I]COMMAND\f[R] after all customize hooks have been
executed.
This option can be specified multiple times.
.TP
\f[B]--suite\f[R] \f[I]SUITE\f[R], \f[I]SUITE\f[R]
The suite may be a valid release code name (eg, sid, stretch, jessie) or
a symbolic name (eg, unstable, testing, stable, oldstable).
.TP
\f[B]--target\f[R] \f[I]TARGET\f[R], \f[I]TARGET\f[R]
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 \f[I]-\f[R].
.TP
\f[B]--mirrors\f[R] \f[I]MIRRORS\f[R], \f[I]MIRRORS\f[R]
Comma separated list of mirrors.
If no mirror option is provided, http://deb.debian.org/debian is used.
.SH YAML CONFIGURATION
.PP
This section describes the expected data-structure hierarchy of the YAML
configuration file(s).
The top-level structure is expected to be a mapping.
The top-level mapping may contain following keys:
.SS env
.PP
mapping of environment variables names to their values.
Environment variables can be overridden by specifying them with
\f[B]--env\f[R] using the same name.
These environment variable are set before calling the hooks.
.SS name
.PP
String.
Name of the generated golden image.
Can be overridden by \f[B]--name\f[R].
.SS mmdebstrap
.PP
mapping.
The values here are passed to mmdebstrap(1).
Following keys might be specified:
.TP
\f[B]aptopts\f[R]
list of arbitrary options or configuration files (string) to apt.
Additional apt options can be specified with \f[B]--aptopt\f[R].
.TP
\f[B]architectures\f[R]
list of architectures (string).
The first architecture is the native architecture inside the chroot.
Additional architectures can be specified with
\f[B]--architectures\f[R].
.TP
\f[B]components\f[R]
list of components (string) like main, contrib and non-free which will
be used for all URI-only \f[I]MIRROR\f[R] arguments.
Additional components can be specified with \f[B]--components\f[R].
.TP
\f[B]dpkgopts\f[R]
list of arbitrary options or configuration files (string) to dpkg.
Additional dpkg options can be specified with \f[B]--dpkgopt\f[R].
.TP
\f[B]hostname\f[R]
String.
If specified, write the given \f[I]hostname\f[R] into
\f[I]/etc/hostname\f[R] in the target chroot.
This parameter does not exist in \f[B]mmdebstrap\f[R] and is implemented
as customize hook for \f[B]mmdebstrap\f[R].
Can be overridden by \f[B]--hostname\f[R].
.TP
\f[B]install-recommends\f[R]
Boolean.
If set to \f[I]True\f[R], the APT option \f[I]Apt::Install-Recommends
\[lq]true\[rq]\f[R] is passed to \f[B]mmdebstrap\f[R] via
\f[B]--aptopt\f[R].
Can be overridden by \f[B]--install-recommends\f[R].
.TP
\f[B]keyrings\f[R]
list of default keyring to use by apt.
Additional keyring files can be specified with \f[B]--keyring\f[R].
.TP
\f[B]mirrors\f[R]
list of mirrors (string).
Additional mirrors can be specified with \f[B]--mirrors\f[R].
.TP
\f[B]mode\f[R]
Choose how to perform the chroot operation and create a filesystem with
ownership information different from the current user.
It needs to be one of \f[I]auto\f[R], \f[I]sudo\f[R], \f[I]root\f[R],
\f[I]unshare\f[R], \f[I]fakeroot\f[R], \f[I]fakechroot\f[R],
\f[I]proot\f[R], or \f[I]chrootless\f[R].
See mmdebstrap(1) for details.
Can be overridden by \f[B]--mode\f[R].
.TP
\f[B]packages\f[R]
list of packages (string) which will be installed in addition to the
packages installed by the specified variant.
Additional packages can be specified with \f[B]--packages\f[R] or
\f[B]--include\f[R].
This setting is passed to \f[B]mmdebstrap\f[R] using the
\f[B]--include\f[R] parameter.
.TP
\f[B]setup-hooks\f[R]
list of setup hooks (string).
Execute arbitrary commands 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 \f[B]HOOKS\f[R] in mmdebstrap(1) for more information and examples.
Additional setup hooks can be specified with \f[B]--setup-hook\f[R].
.TP
\f[B]essential-hooks\f[R]
list of essential hooks (string).
Execute arbitrary commands after the Essential:yes packages have been
installed, but before installing the remaining packages.
See \f[B]HOOKS\f[R] in mmdebstrap(1) for more information and examples.
Additional essential hooks can be specified with
\f[B]--essential-hook\f[R].
.TP
\f[B]customize-hooks\f[R]
list of customize hooks (string).
Execute arbitrary commands after the chroot is set up and all packages
got installed but before final cleanup actions are carried out.
See \f[B]HOOKS\f[R] in mmdebstrap(1) for more information and examples.
Additional customize hooks can be specified with
\f[B]--customize-hook\f[R].
.TP
\f[B]cleanup-hooks\f[R]
list of cleanup hooks (string).
Cleanup hooks are just hooks that are run directly after all other
customize hooks.
See \f[B]customize-hooks\f[R] above.
Additional cleanup hooks can be specified with \f[B]--cleanup-hook\f[R].
.TP
\f[B]suite\f[R]
String.
The suite may be a valid release code name (eg, sid, stretch, jessie) or
a symbolic name (eg, unstable, testing, stable, oldstable).
Can be overridden by \f[B]--suite\f[R].
.TP
\f[B]target\f[R]
String.
The target argument can either be the path to a directory, the path to a
tarball filename, the path to a squashfs image or \f[I]-\f[R].
Can be overridden by \f[B]--target\f[R].
.TP
\f[B]variant\f[R]
Choose which package set to install.
It needs to be one of \f[I]extract\f[R], \f[I]custom\f[R],
\f[I]essential\f[R], \f[I]apt\f[R], \f[I]required\f[R],
\f[I]minbase\f[R], \f[I]buildd\f[R], \f[I]important\f[R],
\f[I]debootstrap\f[R], \f[I]-\f[R], \f[I]standard\f[R].
See mmdebstrap(1) for details.
Can be overridden by \f[B]--variant\f[R].
.SH HOOKS
.PP
\f[B]bdebstrap\f[R] enhances the hooks provided by \f[B]mmdebstrap\f[R].
Hooks can use the environment variables specified via the \f[I]env\f[R]
configuration option or the \f[B]--env\f[R] parameter.
\f[B]bdebstrap\f[R] sets following environment variables by default to
be consumed by the hooks:
.TP
\f[B]BDEBSTRAP_NAME\f[R]
name of the generated golden image which is set via the \f[B]name\f[R]
configuration option of the \f[B]--name\f[R] parameter.
.TP
\f[B]BDEBSTRAP_OUTPUT_DIR\f[R]
Path of a temporary directory inside the chroot.
Files and directories that are placed inside this directory will be
copied out of the image into the output directory.
This temporary directory will be removed in a final cleanup hook.
.SH EXAMPLES
.SS Minimal Debian unstable tarball
.PP
This example shows how to use a small YAML configuration to build a
minimal Debian unstable tarball.
Assume following configuration is stored in \f[I]unstable.yaml\f[R]:
.IP
.nf
\f[C]
mmdebstrap:
  keyrings:
  - /usr/share/keyrings/debian-archive-keyring.gpg
  mode: unshare
  suite: unstable
  target: root.tar.xz
  variant: minbase
\f[R]
.fi
.PP
Then the tarball can be generated by running
.IP
.nf
\f[C]
$ bdebstrap -c unstable.yaml --name example1
$ ls example1/
config.yaml  manifest  root.tar.xz
\f[R]
.fi
.SS Debian live system
.PP
This example shows how to use a YAML configuration to build a Debian 11
(bullseye) live system.
Assume following configuration is stored in \f[I]live.yaml\f[R]:
.IP
.nf
\f[C]
mmdebstrap:
  architectures:
  - amd64
  cleanup-hooks:
  - cp /dev/null \[dq]$1/etc/hostname\[dq]
  - if test -f \[dq]$1/etc/resolv.conf\[dq]; then cp /dev/null \[dq]$1/etc/resolv.conf\[dq]; fi
  customize-hooks:
  - cp --preserve=timestamps -v \[dq]$1\[dq]/boot/vmlinu* \[dq]$1${BDEBSTRAP_OUTPUT_DIR?}/vmlinuz\[dq]
  - cp --preserve=timestamps -v \[dq]$1\[dq]/boot/initrd.img* \[dq]$1${BDEBSTRAP_OUTPUT_DIR?}/initrd.img\[dq]
  - mkdir -p \[dq]$1/root/.ssh\[dq]
  - upload \[ti]/.ssh/id_rsa.pub /root/.ssh/authorized_keys
  keyrings:
  - /usr/share/keyrings/debian-archive-keyring.gpg
  mode: unshare
  packages:
  - init
  - iproute2
  - less
  - libpam-systemd
  - linux-image-cloud-amd64
  - live-boot
  - locales
  - openssh-server
  suite: bullseye
  target: root.squashfs
  variant: minbase
\f[R]
.fi
.PP
This example assumes that \f[I]\[ti]/.ssh/id_rsa.pub\f[R] exists,
because it will be copied into the image to
\f[I]/root/.ssh/authorized_keys\f[R] to allow SSH access using the
user\[cq]s SSH key.
.PP
The squashfs image can be generated by running
.IP
.nf
\f[C]
$ bdebstrap -c live.yaml --name example2
$ ls example2/
config.yaml  initrd.img  manifest  root.squashfs  vmlinuz
\f[R]
.fi
.PP
The kernel and initrd are copied out of the squashfs image using
customize hooks to allow them to be used directly by QEMU.
To launch this image locally with QEMU, the \f[I]root.squashfs\f[R]
image needs to be provided by a HTTP server:
.IP
.nf
\f[C]
$ python3 -m http.server -b localhost --directory example2 8080
\f[R]
.fi
.PP
This command exposes the generated image via HTTP on localhost on port
8080.
QEMU can be started passing the TCP traffic on port 8080 to the
webserver:
.IP
.nf
\f[C]
$ cd example2
$ qemu-system-x86_64 -machine accel=kvm -m 1G -device virtio-net-pci,netdev=net0 -monitor vc \[rs]
    -netdev user,id=net0,hostfwd=tcp::2222-:22,guestfwd=tcp:10.0.2.252:8080-tcp:localhost:8080,hostname=debian-live \[rs]
    -kernel ./vmlinuz -initrd ./initrd.img -append \[dq]boot=live fetch=http://10.0.2.252:8080/root.squashfs quiet\[dq]
\f[R]
.fi
.PP
To print the output on the launching terminal, add \f[I]-nographic
-serial stdio\f[R] to the QEMU command line and \f[I]console=ttyS0\f[R]
to the \f[I]-append\f[R] parameter.
Once the virtual machine is started, it can be accessed via SSH:
.IP
.nf
\f[C]
$ ssh -oUserKnownHostsFile=/dev/null -oStrictHostKeyChecking=no -p 2222 root\[at]localhost
\f[R]
.fi
.SH SEE ALSO
.PP
mmdebstrap(1), debootstrap(8)
.SH AUTHOR
.PP
Benjamin Drung <bdrung@posteo.de>