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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="systemd-nspawn">
27 <title>systemd-nspawn</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd-nspawn</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>systemd-nspawn</refname>
47 <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
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>
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>
67 <title>Description</title>
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
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
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>
100 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
101 <command>systemd-nspawn</command> may be used to boot
102 full Linux-based operating systems in a
105 <para>Use a tool like
106 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
109 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
110 to set up an OS directory tree suitable as file system
111 hierarchy for <command>systemd-nspawn</command>
114 <para>Note that <command>systemd-nspawn</command> will
115 mount file systems private to the container to
116 <filename>/dev</filename>,
117 <filename>/run</filename> and similar. These will
118 not be visible outside of the container, and their
119 contents will be lost when the container exits.</para>
121 <para>Note that running two
122 <command>systemd-nspawn</command> containers from the
123 same directory tree will not make processes in them
124 see each other. The PID namespace separation of the
125 two containers is complete and the containers will
126 share very few runtime objects except for the
127 underlying file system. It is however possible to
128 enter an existing container, see
129 <link linkend='example-nsenter'>Example 4</link> below.
132 <para><command>systemd-nspawn</command> implements the
134 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
135 Interface</ulink> specification.</para>
137 <para>As a safety check
138 <command>systemd-nspawn</command> will verify the
139 existance of <filename>/etc/os-release</filename> in
140 the container tree before starting the container (see
141 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
142 might be necessary to add this file to the container
143 tree manually if the OS of the container is too old to
144 contain this file out-of-the-box.</para>
146 <para>Note that the kernel auditing subsystem is
147 currently broken when used together with
148 containers. We hence recommend turning it off entirely
149 when using <command>systemd-nspawn</command> by
150 booting with <literal>audit=0</literal> on the kernel
151 command line, or by turning it off at kernel build
152 time. If auditing is enabled in the kernel operating
153 systems booted in an nspawn container might refuse
154 log-in attempts.</para>
158 <title>Options</title>
160 <para>If option <option>-b</option> is specified, the
161 arguments are used as arguments for the init
162 binary. Otherwise, <replaceable>COMMAND</replaceable>
163 specifies the program to launch in the container, and
164 the remaining arguments are used as arguments for this
165 program. If <option>-b</option> is not used and no
166 arguments are specifed, a shell is launched in the
169 <para>The following options are understood:</para>
173 <term><option>-h</option></term>
174 <term><option>--help</option></term>
176 <listitem><para>Prints a short help
177 text and exits.</para></listitem>
181 <term><option>--version</option></term>
183 <listitem><para>Prints a version string
184 and exits.</para></listitem>
188 <term><option>-D</option></term>
189 <term><option>--directory=</option></term>
191 <listitem><para>Directory to use as
192 file system root for the namespace
193 container. If omitted the current
195 used.</para></listitem>
199 <term><option>-b</option></term>
200 <term><option>--boot</option></term>
202 <listitem><para>Automatically search
203 for an init binary and invoke it
204 instead of a shell or a user supplied
205 program. If this option is used, arguments
206 specified on the command line are used
207 as arguments for the init binary.
212 <term><option>-u</option></term>
213 <term><option>--user=</option></term>
215 <listitem><para>Run the command
216 under specified user, create home
217 directory and cd into it. As rest
218 of systemd-nspawn, this is not
219 the security feature and limits
220 against accidental changes only.
225 <term><option>-M</option></term>
226 <term><option>--machine=</option></term>
228 <listitem><para>Sets the machine name
229 for this container. This name may be
230 used to identify this container on the
231 host, and is used to initialize the
232 container's hostname (which the
233 container can choose to override,
234 however). If not specified the last
235 component of the root directory of the
236 container is used.</para></listitem>
240 <term><option>--uuid=</option></term>
242 <listitem><para>Set the specified uuid
243 for the container. The init system
245 <filename>/etc/machine-id</filename>
246 from this if this file is not set yet.
251 <term><option>-C</option></term>
252 <term><option>--controllers=</option></term>
254 <listitem><para>Makes the container appear in
255 other hierarchies than the name=systemd:/ one.
256 Takes a comma-separated list of controllers.
261 <term><option>--private-network</option></term>
263 <listitem><para>Turn off networking in
264 the container. This makes all network
265 interfaces unavailable in the
266 container, with the exception of the
267 loopback device.</para></listitem>
271 <term><option>--read-only</option></term>
273 <listitem><para>Mount the root file
274 system read only for the
275 container.</para></listitem>
279 <term><option>--capability=</option></term>
281 <listitem><para>List one or more
282 additional capabilities to grant the
283 container. Takes a comma separated
284 list of capability names, see
285 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
286 for more information. Note that the
287 following capabilities will be granted
288 in any way: CAP_CHOWN,
289 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
290 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
293 CAP_NET_BIND_SERVICE,
294 CAP_NET_BROADCAST, CAP_NET_RAW,
295 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
296 CAP_SETUID, CAP_SYS_ADMIN,
297 CAP_SYS_CHROOT, CAP_SYS_NICE,
298 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
299 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
301 CAP_AUDIT_CONTROL.</para></listitem>
305 <term><option>--link-journal=</option></term>
307 <listitem><para>Control whether the
308 container's journal shall be made
309 visible to the host system. If enabled
310 allows viewing the container's journal
311 files from the host (but not vice
313 <literal>no</literal>,
314 <literal>host</literal>,
315 <literal>guest</literal>,
316 <literal>auto</literal>. If
317 <literal>no</literal>, the journal is
318 not linked. If <literal>host</literal>,
319 the journal files are stored on the
320 host file system (beneath
321 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
322 and the subdirectory is bind-mounted
323 into the container at the same
324 location. If <literal>guest</literal>,
325 the journal files are stored on the
326 guest file system (beneath
327 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
328 and the subdirectory is symlinked into the host
329 at the same location. If
330 <literal>auto</literal> (the default),
331 and the right subdirectory of
332 <filename>/var/log/journal</filename>
333 exists, it will be bind mounted
334 into the container. If the
335 subdirectory doesn't exist, no
336 linking is performed. Effectively,
337 booting a container once with
338 <literal>guest</literal> or
339 <literal>host</literal> will link the
340 journal persistently if further on
341 the default of <literal>auto</literal>
342 is used.</para></listitem>
346 <term><option>-j</option></term>
348 <listitem><para>Equivalent to
349 <option>--link-journal=guest</option>.</para></listitem>
353 <term><option>--bind=</option></term>
354 <term><option>--bind-ro=</option></term>
356 <listitem><para>Bind mount a file or
357 directory from the host into the
358 container. Either takes a path
359 argument -- in which case the
360 specified path will be mounted from
361 the host to the same path in the
362 container --, or a colon-separated
363 pair of paths -- in which case the
364 first specified path is the source in
365 the host, and the second path is the
366 destination in the container. The
367 <option>--bind-ro=</option> option
368 creates read-only bind
369 mount.</para></listitem>
376 <title>Example 1</title>
378 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
379 # systemd-nspawn -bD /srv/mycontainer</programlisting>
381 <para>This installs a minimal Fedora distribution into
382 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
383 then boots an OS in a namespace container in
388 <title>Example 2</title>
390 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
391 # systemd-nspawn -D ~/debian-tree/</programlisting>
393 <para>This installs a minimal Debian unstable
394 distribution into the directory
395 <filename>~/debian-tree/</filename> and then spawns a
396 shell in a namespace container in it.</para>
400 <title>Example 3</title>
402 <programlisting># pacstrap -c -d ~/arch-tree/ base
403 # systemd-nspawn -bD ~/arch-tree/</programlisting>
405 <para>This installs a mimimal Arch Linux distribution into
406 the directory <filename>~/arch-tree/</filename> and then
407 boots an OS in a namespace container in it.</para>
410 <refsect1 id='example-nsenter'>
411 <title>Example 4</title>
413 <para>To enter the container, PID of one of the
414 processes sharing the new namespaces must be used.
415 <command>systemd-nspawn</command> prints the PID
416 (as viewed from the outside) of the launched process,
417 and it can be used to enter the container.</para>
419 <programlisting># nsenter -m -u -i -n -p -t $PID</programlisting>
421 <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
423 <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
424 Kernel support for entering namespaces was added in
429 <title>Exit status</title>
431 <para>The exit code of the program executed in the
432 container is returned.</para>
436 <title>See Also</title>
438 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
439 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
440 <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
441 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
442 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
443 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>