Debian Codegraph @

docs/debspawn.1.xml

raw
1 <?xml version='1.0' encoding='ISO-8859-1'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
5 <!-- Please adjust the date whenever revising the manpage. -->
6 <!ENTITY date "<date>18 August, 2018</date>">
7 <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
8 allowed: see man(7), man(1). -->
9 <!ENTITY package "debspawn">
10 ]>
11
12 <refentry>
13 <refentryinfo>
14 <title>debspawn</title>
15 <copyright>
16 <year>2018-2022</year>
17 <holder>Matthias Klumpp</holder>
18 </copyright>
19 <productname>Debspawn</productname>
20 &date;
21 </refentryinfo>
22
23 <refmeta>
24 <refentrytitle>debspawn</refentrytitle>
25 <manvolnum>1</manvolnum>
26 </refmeta>
27 <refnamediv>
28 <refname>&package;</refname>
29 <refpurpose>Build in nspawn containers</refpurpose>
30 </refnamediv>
31
32 <refsynopsisdiv>
33 <cmdsynopsis>
34 <command>&package;</command>
35 @BASE_FLAGS_SYNOPSIS@
36 <group>
37 <option choice="req">COMMAND</option>
38 </group>
39 </cmdsynopsis>
40 </refsynopsisdiv>
41
42 <refsect1>
43 <title>Description</title>
44 <para>
45 This manual page documents the <command>&package;</command> command.
46 </para>
47 <para>
48 <command>&package;</command> is a tool to build Debian packages in an isolated environment, using nspawn containers.
49 By using containers, Debspawn can isolate builds from the host system much better than a regular chroot could.
50 It also allows for more advanced features to manage builds, for example setting resource limits for individual builds.
51 </para>
52 <para>
53 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
54 untrusted code with it. The usual warnings for all technology based on Linux containers apply here.
55 See <command>systemd-nspawn(1)</command> for more information on the container solution Debspawn uses.
56 </para>
57 <para>
58 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
59 make sense to be run in the same environment in which packages are usually built.
60 </para>
61 <para>
62 For more information about the Debspawn project, you can visit its <ulink url="https://github.com/lkorigin/debspawn">project page</ulink>.
63 </para>
64 </refsect1>
65
66 <refsect1>
67 <title>Subcommands</title>
68
69 <para>
70 <command>&package;</command> actions are invoked via subcommands. Refer to their individual manual pages for further details.
71 </para>
72
73 <variablelist>
74
75 <varlistentry>
76 <term><option>create</option></term>
77 <listitem>
78 <para>
79 Create a new container base image for a specific suite, architecture and variant. A custom mirror location can also be
80 provided. For details, see <command>debspawn-create(1)</command>.
81 </para>
82 </listitem>
83 </varlistentry>
84
85 <varlistentry>
86 <term><option>list</option></term>
87 <listitem>
88 <para>
89 List information about all container image that Debspawn knows on the current host.
90 For details, see <command>debspawn-list(1)</command>.
91 </para>
92 </listitem>
93 </varlistentry>
94
95 <varlistentry>
96 <term><option>exists</option></term>
97 <listitem>
98 <para>
99 Check whether a specific container image exists.
100 </para>
101 </listitem>
102 </varlistentry>
103
104 <varlistentry>
105 <term><option>delete</option></term>
106 <listitem>
107 <para>
108 Delete a container base image and all data associated with it.
109 For details, see <command>debspawn-delete(1)</command>.
110 </para>
111 </listitem>
112 </varlistentry>
113
114 <varlistentry>
115 <term><option>update</option></term>
116 <listitem>
117 <para>
118 Update a container base image, ensuring all packages are up to date and the image is set up
119 properly for use with <command>debspawn</command>.
120 For details, see <command>debspawn-update(1)</command>.
121 </para>
122 </listitem>
123 </varlistentry>
124
125 <varlistentry>
126 <term><option>build</option></term>
127 <listitem>
128 <para>
129 Build a Debian package in an isolated environment.
130 For details, see <command>debspawn-build(1)</command>.
131 </para>
132 </listitem>
133 </varlistentry>
134
135 <varlistentry>
136 <term><option>login</option></term>
137 <listitem>
138 <para>
139 Get an interactive shell session in a container.
140 For details, see <command>debspawn-login(1)</command>.
141 </para>
142 </listitem>
143 </varlistentry>
144
145 <varlistentry>
146 <term><option>run</option></term>
147 <listitem>
148 <para>
149 Run arbitrary commands in debspawn container session. This is primarily useful
150 for using <command>&package;</command> to isolate non-package build processes.
151 For details, see <command>debspawn-run(1)</command>.
152 </para>
153 </listitem>
154 </varlistentry>
155
156
157 </variablelist>
158 </refsect1>
159
160 <refsect1>
161 <title>Flags</title>
162
163 <variablelist>
164 @BASE_FLAGS_ENTRIES@
165 </variablelist>
166 </refsect1>
167
168 <refsect1>
169 <title>Configuration</title>
170
171 <para>
172 Configuration is read from an optional TOML file, located at <filename>/etc/debspawn/global.toml</filename> or a location specified
173 with <option>--config</option>. Specifying a config file on the command line will skip loading of the global, system-wide configuration.
174 </para>
175
176 <para>
177 The following keys are valid at the document root level, all are optional:
178 </para>
179
180 <variablelist>
181
182 <varlistentry>
183 <term><option>OSImagesDir</option></term>
184 <listitem>
185 <para>Location for stored container images.</para>
186 </listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term><option>ResultsDir</option></term>
191 <listitem>
192 <para>Default output directory for build artifacts on successful builds.</para>
193 </listitem>
194 </varlistentry>
195
196 <varlistentry>
197 <term><option>APTCacheDir</option></term>
198 <listitem>
199 <para>Location for debspawn's package cache.</para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term><option>InjectedPkgsDir</option></term>
205 <listitem>
206 <para>
207 Package files placed in the root of this directory are available to all containers
208 to satisfy build dependencies, while ones placed in subdirectories with the OS image
209 name (e.g. <literal>sid-arm64</literal>) will only be available to the specified container.
210 </para>
211 </listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>TempDir</option></term>
216 <listitem>
217 <para>Temporary data location (Default: <filename>/var/tmp/debspawn/</filename>).</para>
218 </listitem>
219 </varlistentry>
220
221 <varlistentry>
222 <term><option>DefaultBootstrapVariant</option></term>
223 <listitem>
224 <para>
225 Set a default variant used for bootstrapping with debootstrap that gets
226 used if no variant is explicitly set when creating a new image.
227 Set to <literal>none</literal> to make "no variant" the default.
228 (Default: <literal>buildd</literal>)
229 </para>
230 </listitem>
231 </varlistentry>
232
233 <varlistentry>
234 <term><option>SyscallFilter</option></term>
235 <listitem>
236 <para>
237 Set the system call filter used by <command>&package;</command> containers.
238 This will take a list of system call names or set names as described in the
239 "System Call Filtering" section of <literal>systemd.exec(5)</literal>.
240 </para>
241 <para>
242 It also recognizes the special string-only values <code>compat</code> and
243 <code>nspawn-default</code>, where <code>compat</code> will allow
244 enough system calls to permit many builds and tests that would run in a
245 regular <literal>sbuild(1)</literal> chroot to work with <command>&package;</command>
246 as well. By setting <code>nspawn-default</code>, the more restrictive defaults
247 of <literal>systemd-nspawn(1)</literal> are applied.
248 (Default: <literal>compat</literal>)
249 </para>
250 </listitem>
251 </varlistentry>
252
253 <varlistentry>
254 <term><option>AllowUnsafePermissions</option></term>
255 <listitem>
256 <para>
257 Boolean option. If set to <literal>true</literal>, unsafe options can be used
258 for building software via <command>&package; run</command>, such as making the
259 host's <filename>/dev</filename> and <filename>/proc</filename> filesystems
260 available from within the container. See the <parameter>--allow</parameter> option
261 of <command>&package; run</command> for more details.
262 (Default: <code>false</code>)
263 </para>
264 </listitem>
265 </varlistentry>
266
267 <varlistentry>
268 <term><option>CachePackages</option></term>
269 <listitem>
270 <para>
271 Boolean option. If set to <literal>false</literal>, <command>&package;</command> will not
272 manage its own local cache of APT packages, but will instead always try to download
273 them. It is only recommended to change this option if you are already running a separate APT
274 package repository mirror or a caching proxy such as apt-cacher-ng(8).
275 (Default: <code>true</code>)
276 </para>
277 </listitem>
278 </varlistentry>
279
280 <varlistentry>
281 <term><option>BootstrapTool</option></term>
282 <listitem>
283 <para>
284 Set the bootstrap tool that should be used for bootstrapping new images.
285 The tool should have an interface compatible with debootstrap(8). This option
286 allows one to use alternative tools like mmdebstrap(1) with <command>&package;</command>.
287 (Default: <code>debootstrap</code>)
288 </para>
289 </listitem>
290 </varlistentry>
291
292 </variablelist>
293
294 </refsect1>
295
296 <refsect1>
297 <title>See Also</title>
298 <para>dpkg-buildpackage(1), systemd-nspawn(1), sbuild(1).</para>
299 </refsect1>
300 <refsect1>
301 <title>AUTHOR</title>
302 <para>
303 This manual page was written by Matthias Klumpp <email>[email protected]</email>.
304 </para>
305 </refsect1>
306 </refentry>