chiark / gitweb /
man: add DOI for refereed article on Forward Secure Sealing to journald.conf(5)
[elogind.git] / man / systemd-nspawn.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd-nspawn">
25
26         <refentryinfo>
27                 <title>systemd-nspawn</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemd-nspawn</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd-nspawn</refname>
47                 <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>systemd-nspawn</command>
53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
54                         <arg choice="opt"><replaceable>COMMAND</replaceable>
55                         <arg choice="opt" rep="repeat">ARGS</arg>
56                         </arg>
57                 </cmdsynopsis>
58                 <cmdsynopsis>
59                         <command>systemd-nspawn</command>
60                         <arg choice="plain">-b</arg>
61                         <arg choice="opt" rep="repeat">OPTIONS</arg>
62                         <arg choice="opt" rep="repeat">ARGS</arg>
63                 </cmdsynopsis>
64         </refsynopsisdiv>
65
66         <refsect1>
67                 <title>Description</title>
68
69                 <para><command>systemd-nspawn</command> may be used to
70                 run a command or OS in a light-weight namespace
71                 container. In many ways it is similar to
72                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
73                 but more powerful since it fully virtualizes the file
74                 system hierarchy, as well as the process tree, the
75                 various IPC subsystems and the host and domain
76                 name.</para>
77
78                 <para><command>systemd-nspawn</command> limits access
79                 to various kernel interfaces in the container to
80                 read-only, such as <filename>/sys</filename>,
81                 <filename>/proc/sys</filename> or
82                 <filename>/sys/fs/selinux</filename>. Network
83                 interfaces and the system clock may not be changed
84                 from within the container. Device nodes may not be
85                 created. The host system cannot be rebooted and kernel
86                 modules may not be loaded from within the
87                 container.</para>
88
89                 <para>Note that even though these security precautions
90                 are taken <command>systemd-nspawn</command> is not
91                 suitable for secure container setups. Many of the
92                 security features may be circumvented and are hence
93                 primarily useful to avoid accidental changes to the
94                 host system from the container. The intended use of
95                 this program is debugging and testing as well as
96                 building of packages, distributions and software
97                 involved with boot and systems management.</para>
98
99                 <para>In contrast to
100                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
101                 may be used to boot full Linux-based operating systems
102                 in a container.</para>
103
104                 <para>Use a tool like
105                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
106                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107                 or
108                 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
109                 to set up an OS directory tree suitable as file system
110                 hierarchy for <command>systemd-nspawn</command>
111                 containers.</para>
112
113                 <para>Note that <command>systemd-nspawn</command> will
114                 mount file systems private to the container to
115                 <filename>/dev</filename>,
116                 <filename>/run</filename> and similar. These will
117                 not be visible outside of the container, and their
118                 contents will be lost when the container exits.</para>
119
120                 <para>Note that running two
121                 <command>systemd-nspawn</command> containers from the
122                 same directory tree will not make processes in them
123                 see each other. The PID namespace separation of the
124                 two containers is complete and the containers will
125                 share very few runtime objects except for the
126                 underlying file system. Use
127                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
128                 <command>login</command> command to request an
129                 additional login prompt in a running container.</para>
130
131                 <para><command>systemd-nspawn</command> implements the
132                 <ulink
133                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
134                 Interface</ulink> specification.</para>
135
136                 <para>As a safety check
137                 <command>systemd-nspawn</command> will verify the
138                 existence of <filename>/etc/os-release</filename> in
139                 the container tree before starting the container (see
140                 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
141                 might be necessary to add this file to the container
142                 tree manually if the OS of the container is too old to
143                 contain this file out-of-the-box.</para>
144         </refsect1>
145
146         <refsect1>
147                 <title>Incompatibility with Auditing</title>
148
149                 <para>Note that the kernel auditing subsystem is
150                 currently broken when used together with
151                 containers. We hence recommend turning it off entirely
152                 by booting with <literal>audit=0</literal> on the
153                 kernel command line, or by turning it off at kernel
154                 build time. If auditing is enabled in the kernel,
155                 operating systems booted in an nspawn container might
156                 refuse log-in attempts.</para>
157         </refsect1>
158
159         <refsect1>
160                 <title>Options</title>
161
162                 <para>If option <option>-b</option> is specified, the
163                 arguments are used as arguments for the init
164                 binary. Otherwise, <replaceable>COMMAND</replaceable>
165                 specifies the program to launch in the container, and
166                 the remaining arguments are used as arguments for this
167                 program. If <option>-b</option> is not used and no
168                 arguments are specifed, a shell is launched in the
169                 container.</para>
170
171                 <para>The following options are understood:</para>
172
173                 <variablelist>
174                         <varlistentry>
175                                 <term><option>-h</option></term>
176                                 <term><option>--help</option></term>
177
178                                 <listitem><para>Prints a short help
179                                 text and exits.</para></listitem>
180                         </varlistentry>
181
182                         <varlistentry>
183                                 <term><option>--version</option></term>
184
185                                 <listitem><para>Prints a version string
186                                 and exits.</para></listitem>
187                         </varlistentry>
188
189                         <varlistentry>
190                                 <term><option>-D</option></term>
191                                 <term><option>--directory=</option></term>
192
193                                 <listitem><para>Directory to use as
194                                 file system root for the namespace
195                                 container. If omitted, the current
196                                 directory will be
197                                 used.</para></listitem>
198                         </varlistentry>
199
200                         <varlistentry>
201                                 <term><option>-b</option></term>
202                                 <term><option>--boot</option></term>
203
204                                 <listitem><para>Automatically search
205                                 for an init binary and invoke it
206                                 instead of a shell or a user supplied
207                                 program. If this option is used, arguments
208                                 specified on the command line are used
209                                 as arguments for the init binary.
210                                 </para></listitem>
211                         </varlistentry>
212
213                         <varlistentry>
214                                 <term><option>-u</option></term>
215                                 <term><option>--user=</option></term>
216
217                                 <listitem><para>Run the command
218                                 under specified user, create home
219                                 directory and cd into it. As rest
220                                 of systemd-nspawn, this is not
221                                 the security feature and limits
222                                 against accidental changes only.
223                                 </para></listitem>
224                         </varlistentry>
225
226                         <varlistentry>
227                                 <term><option>-M</option></term>
228                                 <term><option>--machine=</option></term>
229
230                                 <listitem><para>Sets the machine name
231                                 for this container. This name may be
232                                 used to identify this container on the
233                                 host, and is used to initialize the
234                                 container's hostname (which the
235                                 container can choose to override,
236                                 however). If not specified, the last
237                                 component of the root directory of the
238                                 container is used.</para></listitem>
239                         </varlistentry>
240
241                         <varlistentry>
242                                 <term><option>--slice=</option></term>
243
244                                 <listitem><para>Make the container
245                                 part of the specified slice, instead
246                                 of the
247                                 <filename>machine.slice</filename>.</para>
248                                 </listitem>
249                         </varlistentry>
250
251                         <varlistentry>
252                                 <term><option>--uuid=</option></term>
253
254                                 <listitem><para>Set the specified UUID
255                                 for the container. The init system
256                                 will initialize
257                                 <filename>/etc/machine-id</filename>
258                                 from this if this file is not set yet.
259                                 </para></listitem>
260                         </varlistentry>
261
262                         <varlistentry>
263                                 <term><option>--private-network</option></term>
264
265                                 <listitem><para>Turn off networking in
266                                 the container. This makes all network
267                                 interfaces unavailable in the
268                                 container, with the exception of the
269                                 loopback device.</para></listitem>
270                         </varlistentry>
271
272                         <varlistentry>
273                                 <term><option>--read-only</option></term>
274
275                                 <listitem><para>Mount the root file
276                                 system read-only for the
277                                 container.</para></listitem>
278                         </varlistentry>
279
280                         <varlistentry>
281                                 <term><option>--capability=</option></term>
282
283                                 <listitem><para>List one or more
284                                 additional capabilities to grant the
285                                 container. Takes a comma-separated
286                                 list of capability names, see
287                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
288                                 for more information. Note that the
289                                 following capabilities will be granted
290                                 in any way: CAP_CHOWN,
291                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
292                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
293                                 CAP_KILL, CAP_LEASE,
294                                 CAP_LINUX_IMMUTABLE,
295                                 CAP_NET_BIND_SERVICE,
296                                 CAP_NET_BROADCAST, CAP_NET_RAW,
297                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
298                                 CAP_SETUID, CAP_SYS_ADMIN,
299                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
300                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
301                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
302                                 CAP_AUDIT_WRITE,
303                                 CAP_AUDIT_CONTROL.</para></listitem>
304                         </varlistentry>
305
306                         <varlistentry>
307                                 <term><option>--drop-capability=</option></term>
308
309                                 <listitem><para>Specify one or more
310                                 additional capabilities to drop for
311                                 the container. This allows running the
312                                 container with fewer capabilities than
313                                 the default (see above).</para></listitem>
314                         </varlistentry>
315
316                         <varlistentry>
317                                 <term><option>--link-journal=</option></term>
318
319                                 <listitem><para>Control whether the
320                                 container's journal shall be made
321                                 visible to the host system. If enabled,
322                                 allows viewing the container's journal
323                                 files from the host (but not vice
324                                 versa). Takes one of
325                                 <literal>no</literal>,
326                                 <literal>host</literal>,
327                                 <literal>guest</literal>,
328                                 <literal>auto</literal>. If
329                                 <literal>no</literal>, the journal is
330                                 not linked. If <literal>host</literal>,
331                                 the journal files are stored on the
332                                 host file system (beneath
333                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
334                                 and the subdirectory is bind-mounted
335                                 into the container at the same
336                                 location. If <literal>guest</literal>,
337                                 the journal files are stored on the
338                                 guest file system (beneath
339                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
340                                 and the subdirectory is symlinked into the host
341                                 at the same location. If
342                                 <literal>auto</literal> (the default),
343                                 and the right subdirectory of
344                                 <filename>/var/log/journal</filename>
345                                 exists, it will be bind mounted
346                                 into the container. If the
347                                 subdirectory does not exist, no
348                                 linking is performed. Effectively,
349                                 booting a container once with
350                                 <literal>guest</literal> or
351                                 <literal>host</literal> will link the
352                                 journal persistently if further on
353                                 the default of <literal>auto</literal>
354                                 is used.</para></listitem>
355                         </varlistentry>
356
357                         <varlistentry>
358                                 <term><option>-j</option></term>
359
360                                 <listitem><para>Equivalent to
361                                 <option>--link-journal=guest</option>.</para></listitem>
362                         </varlistentry>
363
364                         <varlistentry>
365                                 <term><option>--bind=</option></term>
366                                 <term><option>--bind-ro=</option></term>
367
368                                 <listitem><para>Bind mount a file or
369                                 directory from the host into the
370                                 container. Either takes a path
371                                 argument -- in which case the
372                                 specified path will be mounted from
373                                 the host to the same path in the
374                                 container --, or a colon-separated
375                                 pair of paths -- in which case the
376                                 first specified path is the source in
377                                 the host, and the second path is the
378                                 destination in the container. The
379                                 <option>--bind-ro=</option> option
380                                 creates read-only bind
381                                 mount.</para></listitem>
382                         </varlistentry>
383
384                         <varlistentry>
385                                 <term><option>--setenv=</option></term>
386
387                                 <listitem><para>Specifies an
388                                 environment variable assignment to
389                                 pass to the init process in the
390                                 container, in the format
391                                 <literal>NAME=VALUE</literal>. This
392                                 may be used to override the default
393                                 variables or to set additional
394                                 variables. This parameter may be used
395                                 more than once.</para></listitem>
396                         </varlistentry>
397
398                 </variablelist>
399
400         </refsect1>
401
402         <refsect1>
403                 <title>Example 1</title>
404
405                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
406 # systemd-nspawn -bD /srv/mycontainer</programlisting>
407
408                 <para>This installs a minimal Fedora distribution into
409                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
410                 then boots an OS in a namespace container in
411                 it.</para>
412         </refsect1>
413
414         <refsect1>
415                 <title>Example 2</title>
416
417                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
418 # systemd-nspawn -D ~/debian-tree/</programlisting>
419
420                 <para>This installs a minimal Debian unstable
421                 distribution into the directory
422                 <filename>~/debian-tree/</filename> and then spawns a
423                 shell in a namespace container in it.</para>
424         </refsect1>
425
426         <refsect1>
427                 <title>Example 3</title>
428
429                 <programlisting># pacstrap -c -d ~/arch-tree/ base
430 # systemd-nspawn -bD ~/arch-tree/</programlisting>
431
432                 <para>This installs a mimimal Arch Linux distribution into
433                 the directory <filename>~/arch-tree/</filename> and then
434                 boots an OS in a namespace container in it.</para>
435         </refsect1>
436
437         <refsect1>
438                 <title>Example 4</title>
439
440                 <programlisting># mv ~/arch-tree /var/lib/container/arch
441 # systemctl enable systemd-nspawn@arch.service
442 # systemctl start systemd-nspawn@arch.service</programlisting>
443
444                 <para>This makes the Arch Linux container part of the
445                 <filename>multi-user.target</filename> on the host.
446                 </para>
447         </refsect1>
448
449         <refsect1>
450                 <title>Example 5</title>
451
452                 <programlisting># btrfs subvolume snapshot / /.tmp
453 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
454
455                 <para>This runs a copy of the host system in a
456                 btrfs snapshot.</para>
457         </refsect1>
458
459
460         <refsect1>
461                 <title>Exit status</title>
462
463                 <para>The exit code of the program executed in the
464                 container is returned.</para>
465         </refsect1>
466
467         <refsect1>
468                 <title>See Also</title>
469                 <para>
470                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
471                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
472                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
473                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
474                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
475                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
476                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
477                 </para>
478         </refsect1>
479
480 </refentry>