DEBSPAWN(1)

NAME
debspawn - Build in nspawn containers

SYNOPSIS

debspawn [-h|--help] [-c|--config] [--verbose] [--no-unicode] [--version] [--owner] [COMMAND]

DESCRIPTION

This manual page documents the debspawn command.

debspawn is a tool to build Debian packages in an isolated environment, using nspawn containers. By using containers, Debspawn can isolate builds from the host system much better than a regular chroot could. It also allows for more advanced features to manage builds, for example setting resource limits for individual builds.

Please keep in mind that Debspawn is not a security feature! While it provides a lot of isolation from the host system, you should not run arbitrary untrusted code with it. The usual warnings for all technology based on Linux containers apply here. See systemd-nspawn(1) for more information on the container solution Debspawn uses.

Debspawn also allows one to run arbitrary custom commands in its environment. This is useful to execute a variety of non-package build and QA actions that make sense to be run in the same environment in which packages are usually built.

For more information about the Debspawn project, you can visit its project page[1].

SUBCOMMANDS

debspawn actions are invoked via subcommands. Refer to their individual manual pages for further details.

create
    Create a new container base image for a specific suite, architecture and variant. A custom mirror location can also be provided. For details, see debspawn-create(1).

list
    List information about all container image that Debspawn knows on the current host. For details, see debspawn-list(1).

exists
    Check whether a specific container image exists.

delete
    Delete a container base image and all data associated with it. For details, see debspawn-delete(1).

update
    Update a container base image, ensuring all packages are up to date and the image is set up properly for use with debspawn. For details, see debspawn-update(1).

build
    Build a Debian package in an isolated environment. For details, see debspawn-build(1).

login
    Get an interactive shell session in a container. For details, see debspawn-login(1).

run
    Run arbitrary commands in debspawn container session. This is primarily useful for using debspawn to isolate non-package build processes. For details, see debspawn-run(1).

FLAGS

-h|--help
    Print brief help information about available commands.

-c|--config
    Path to the global config file.

--verbose
    Enable debug messages.

--no-unicode
    Disable unicode support.

--version
    Display the version of debspawn itself.

--owner
    Set the user name/uid and group/gid separated by a colon whose behalf we are acting.

CONFIGURATION

Configuration is read from an optional TOML file, located at /etc/debspawn/global.toml or a location specified with --config. Specifying a config file on the command line will skip loading of the global, system-wide configuration.

The following keys are valid at the document root level, all are optional:

OSImagesDir
    Location for stored container images.

ResultsDir
    Default output directory for build artifacts on successful builds.

APTCacheDir
    Location for debspawn's package cache.

InjectedPkgsDir
    Package files placed in the root of this directory are available to all containers to satisfy build dependencies, while ones placed in subdirectories with the OS image name (e.g. sid-arm64) will only be available to the specified container.

TempDir
    Temporary data location (Default: /var/tmp/debspawn/).

DefaultBootstrapVariant
    Set a default variant used for bootstrapping with debootstrap that gets used if no variant is explicitly set when creating a new image. Set to none to make "no variant" the default. (Default: buildd)

SyscallFilter
    Set the system call filter used by debspawn containers. This will take a list of system call names or set names as described in the "System Call Filtering" section of systemd.exec(5).

    It also recognizes the special string-only values compat and nspawn-default, where compat will allow enough system calls to permit many builds and tests that would run in a regular sbuild(1) chroot to work with debspawn as well. By setting nspawn-default, the more restrictive defaults of systemd-nspawn(1) are applied. (Default: compat)

AllowUnsafePermissions
    Boolean option. If set to true, unsafe options can be used for building software via debspawn run, such as making the host's /dev and /proc filesystems available from within the container. See the --allow option of debspawn run for more details. (Default: false)

CachePackages
    Boolean option. If set to false, debspawn will not manage its own local cache of APT packages, but will instead always try to download them. It is only recommended to change this option if you are already running a separate APT package repository mirror or a caching proxy such as apt-cacher-ng(8). (Default: true)

BootstrapTool
    Set the bootstrap tool that should be used for bootstrapping new images. The tool should have an interface compatible with debootstrap(8). This option allows one to use alternative tools like mmdebstrap(1) with debspawn. (Default: debootstrap)

SEE ALSO

dpkg-buildpackage(1), systemd-nspawn(1), sbuild(1).

AUTHOR

This manual page was written by Matthias Klumpp <mak@debian.org>.

COPYRIGHT
Copyright © 2018-2022 Matthias Klumpp

NOTES

1.  project page
    https://github.com/lkorigin/debspawn