# debspawn

debspawn

1

&package;

Build in nspawn containers

    		       &package;
    		       @BASE_FLAGS_SYNOPSIS@

    			       COMMAND

## Description

This manual page documents the `&package;` command.

`&package;` 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.

## Subcommands

`&package;` 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)`.

`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 `&package;` to isolate non-package build processes. For details, see `debspawn-run(1)`.

## Flags

@BASE_FLAGS_ENTRIES@

## 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 `&package;` 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 `&package;` 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 `&package; run`, such as making the host's `/dev` and `/proc` filesystems available from within the container. See the `--allow` option of `&package; run` for more details. (Default: `false`)

`CachePackages`

- Boolean option. If set to `false`, `&package;` 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 `&package;`. (Default: `debootstrap`)

## See Also

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

## AUTHOR

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