'\" t
.\"     Title: debspawn
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 18 August, 2018
.\"    Manual: debspawn
.\"    Source: Debspawn
.\"  Language: English
.\"
.TH "DEBSPAWN" "1" "" "Debspawn" "debspawn"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
debspawn \- Build in nspawn containers
.SH "SYNOPSIS"
.HP \w'\fBdebspawn\fR\ 'u
\fBdebspawn\fR [\-h|\-\-help] [\-c|\-\-config] [\-\-verbose] [\-\-no\-unicode] [\-\-version] [\-\-owner] [\fBCOMMAND\fR]
.SH "DESCRIPTION"
.PP
This manual page documents the
\fBdebspawn\fR
command\&.
.PP
\fBdebspawn\fR
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\&.
.PP
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
\fBsystemd\-nspawn(1)\fR
for more information on the container solution Debspawn uses\&.
.PP
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\&.
.PP
For more information about the Debspawn project, you can visit its
\m[blue]\fBproject page\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "SUBCOMMANDS"
.PP
\fBdebspawn\fR
actions are invoked via subcommands\&. Refer to their individual manual pages for further details\&.
.PP
\fBcreate\fR
.RS 4
Create a new container base image for a specific suite, architecture and variant\&. A custom mirror location can also be provided\&. For details, see
\fBdebspawn\-create(1)\fR\&.
.RE
.PP
\fBlist\fR
.RS 4
List information about all container image that Debspawn knows on the current host\&. For details, see
\fBdebspawn\-list(1)\fR\&.
.RE
.PP
\fBdelete\fR
.RS 4
Delete a container base image and all data associated with it\&. For details, see
\fBdebspawn\-delete(1)\fR\&.
.RE
.PP
\fBupdate\fR
.RS 4
Update a container base image, ensuring all packages are up to date and the image is set up properly for use with
\fBdebspawn\fR\&. For details, see
\fBdebspawn\-update(1)\fR\&.
.RE
.PP
\fBbuild\fR
.RS 4
Build a Debian package in an isolated environment\&. For details, see
\fBdebspawn\-build(1)\fR\&.
.RE
.PP
\fBlogin\fR
.RS 4
Get an interactive shell session in a container\&. For details, see
\fBdebspawn\-login(1)\fR\&.
.RE
.PP
\fBrun\fR
.RS 4
Run arbitrary commands in debspawn container session\&. This is primarily useful for using
\fBdebspawn\fR
to isolate non\-package build processes\&. For details, see
\fBdebspawn\-run(1)\fR\&.
.RE
.SH "FLAGS"
.PP
\-h|\-\-help
.RS 4
Print brief help information about available commands\&.
.RE
.PP
\-c|\-\-config
.RS 4
Path to the global config file\&.
.RE
.PP
\-\-verbose
.RS 4
Enable debug messages\&.
.RE
.PP
\-\-no\-unicode
.RS 4
Disable unicode support\&.
.RE
.PP
\-\-version
.RS 4
Display the version of debspawn itself\&.
.RE
.PP
\-\-owner
.RS 4
Set the user name/uid and group/gid separated by a colon whose behalf we are acting\&.
.RE
.SH "CONFIGURATION"
.PP
Configuration is read from an optional TOML file, located at
/etc/debspawn/global\&.toml
or a location specified with
\fB\-\-config\fR\&. Specifying a config file on the command line will skip loading of the global, system\-wide configuration\&.
.PP
The following keys are valid at the document root level, all are optional:
.PP
\fBOSImagesDir\fR
.RS 4
Location for stored container images\&.
.RE
.PP
\fBResultsDir\fR
.RS 4
Default output directory for build artifacts on successful builds\&.
.RE
.PP
\fBAPTCacheDir\fR
.RS 4
Location for debspawn\*(Aqs package cache\&.
.RE
.PP
\fBInjectedPkgsDir\fR
.RS 4
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\&.
.RE
.PP
\fBTempDir\fR
.RS 4
Temporary data location (Default:
/var/tmp/debspawn/)\&.
.RE
.PP
\fBDefaultBootstrapVariant\fR
.RS 4
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)
.RE
.PP
\fBSyscallFilter\fR
.RS 4
Set the system call filter used by
\fBdebspawn\fR
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)\&.
.sp
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
\fBdebspawn\fR
as well\&. By setting
nspawn\-default, the more restrictive defaults of
systemd\-nspawn(1)
are applied\&. (Default:
compat)
.RE
.PP
\fBAllowUnsafePermissions\fR
.RS 4
Boolean option\&. If set to
true, unsafe options can be used for building software via
\fBdebspawn run\fR, such as making the host\*(Aqs
/dev
and
/proc
filesystems available from within the container\&. See the
\fI\-\-allow\fR
option of
\fBdebspawn run\fR
for more details\&. (Default:
false)
.RE
.PP
\fBCachePackages\fR
.RS 4
Boolean option\&. If set to
false,
\fBdebspawn\fR
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)
.RE
.PP
\fBBootstrapTool\fR
.RS 4
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
\fBdebspawn\fR\&. (Default:
debootstrap)
.RE
.SH "SEE ALSO"
.PP
dpkg\-buildpackage(1), systemd\-nspawn(1), sbuild(1)\&.
.SH "AUTHOR"
.PP
This manual page was written by Matthias Klumpp
<mak@debian\&.org>\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2018-2022 Matthias Klumpp
.br
.SH "NOTES"
.IP " 1." 4
project page
.RS 4
\%https://github.com/lkorigin/debspawn
.RE