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">COMMAND</arg>
55 <arg choice="opt" rep="repeat">ARGS</arg>
60 <title>Description</title>
62 <para><command>systemd-nspawn</command> may be used to
63 run a command or OS in a light-weight namespace
64 container. In many ways it is similar to
65 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
66 but more powerful since it fully virtualizes the file
67 system hierarchy, as well as the process tree, the
68 various IPC subsystems and the host and domain
71 <para><command>systemd-nspawn</command> limits access
72 to various kernel interfaces in the container to
73 read-only, such as <filename>/sys</filename>,
74 <filename>/proc/sys</filename> or
75 <filename>/sys/fs/selinux</filename>. Network
76 interfaces and the system clock may not be changed
77 from within the container. Device nodes may not be
78 created. The host system cannot be rebooted and kernel
79 modules may not be loaded from within the
82 <para>Note that even though these security precautions
83 are taken <command>systemd-nspawn</command> is not
84 suitable for secure container setups. Many of the
85 security features may be circumvented and are hence
86 primarily useful to avoid accidental changes to the
87 host system from the container. The intended use of
88 this program is debugging and testing as well as
89 building of packages, distributions and software
90 involved with boot and systems management.</para>
93 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
94 <command>systemd-nspawn</command> may be used to boot
95 full Linux-based operating systems in a
99 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
100 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
102 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
103 to set up an OS directory tree suitable as file system
104 hierarchy for <command>systemd-nspawn</command>
107 <para>Note that <command>systemd-nspawn</command> will
108 mount file systems private to the container to
109 <filename>/dev</filename>,
110 <filename>/run</filename> and similar. These will
111 not be visible outside of the container, and their
112 contents will be lost when the container exits.</para>
114 <para>Note that running two
115 <command>systemd-nspawn</command> containers from the
116 same directory tree will not make processes in them
117 see each other. The PID namespace separation of the
118 two containers is complete and the containers will
119 share very few runtime objects except for the
120 underlying file system. It is however possible to
121 enter an existing container, see
122 <link linkend='example-nsenter'>Example 4</link> below.
125 <para><command>systemd-nspawn</command> implements the
127 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
128 Interface</ulink> specification.</para>
132 <title>Options</title>
134 <para>If no arguments are passed the container is set
135 up and a shell started in it, otherwise the passed
136 command and arguments are executed in it. The
137 following options are understood:</para>
141 <term><option>-h</option></term>
142 <term><option>--help</option></term>
144 <listitem><para>Prints a short help
145 text and exits.</para></listitem>
149 <term><option>--version</option></term>
151 <listitem><para>Prints a version string
152 and exits.</para></listitem>
156 <term><option>-D</option></term>
157 <term><option>--directory=</option></term>
159 <listitem><para>Directory to use as
160 file system root for the namespace
161 container. If omitted the current
163 used.</para></listitem>
167 <term><option>-b</option></term>
168 <term><option>--boot</option></term>
170 <listitem><para>Automatically search
171 for an init binary and invoke it
172 instead of a shell or a user supplied
173 program.</para></listitem>
177 <term><option>-u</option></term>
178 <term><option>--user=</option></term>
180 <listitem><para>Run the command
181 under specified user, create home
182 directory and cd into it. As rest
183 of systemd-nspawn, this is not
184 the security feature and limits
185 against accidental changes only.
190 <term><option>--uuid=</option></term>
192 <listitem><para>Set the specified uuid
193 for the container. The init system
195 <filename>/etc/machine-id</filename>
196 from this if this file is not set yet.
201 <term><option>-C</option></term>
202 <term><option>--controllers=</option></term>
204 <listitem><para>Makes the container appear in
205 other hierarchies than the name=systemd:/ one.
206 Takes a comma-separated list of controllers.
211 <term><option>--private-network</option></term>
213 <listitem><para>Turn off networking in
214 the container. This makes all network
215 interfaces unavailable in the
216 container, with the exception of the
217 loopback device.</para></listitem>
221 <term><option>--read-only</option></term>
223 <listitem><para>Mount the root file
224 system read only for the
225 container.</para></listitem>
229 <term><option>--capability=</option></term>
231 <listitem><para>List one or more
232 additional capabilities to grant the
233 container. Takes a comma separated
234 list of capability names, see
235 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
236 for more information. Note that the
237 following capabilities will be granted
238 in any way: CAP_CHOWN,
239 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
240 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
243 CAP_NET_BIND_SERVICE,
244 CAP_NET_BROADCAST, CAP_NET_RAW,
245 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
246 CAP_SETUID, CAP_SYS_ADMIN,
247 CAP_SYS_CHROOT, CAP_SYS_NICE,
248 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
249 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
251 CAP_AUDIT_CONTROL.</para></listitem>
255 <term><option>--link-journal=</option></term>
257 <listitem><para>Control whether the
258 container's journal shall be made
259 visible to the host system. If enabled
260 allows viewing the container's journal
261 files from the host (but not vice
263 <literal>no</literal>,
264 <literal>host</literal>,
265 <literal>guest</literal>,
266 <literal>auto</literal>. If
267 <literal>no</literal>, the journal is
268 not linked. If <literal>host</literal>,
269 the journal files are stored on the
270 host file system (beneath
271 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
272 and the subdirectory is bind-mounted
273 into the container at the same
274 location. If <literal>guest</literal>,
275 the journal files are stored on the
276 guest file system (beneath
277 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
278 and the subdirectory is symlinked into the host
279 at the same location. If
280 <literal>auto</literal> (the default),
281 and the right subdirectory of
282 <filename>/var/log/journal</filename>
283 exists, it will be bind mounted
284 into the container. If the
285 subdirectory doesn't exist, no
286 linking is performed. Effectively,
287 booting a container once with
288 <literal>guest</literal> or
289 <literal>host</literal> will link the
290 journal persistently if further on
291 the default of <literal>auto</literal>
292 is used.</para></listitem>
296 <term><option>-j</option></term>
298 <listitem><para>Equivalent to
299 <option>--link-journal=guest</option>.</para></listitem>
306 <title>Example 1</title>
308 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
309 # systemd-nspawn -bD /srv/mycontainer</programlisting>
311 <para>This installs a minimal Fedora distribution into
312 the directory <filename>/srv/mycontainer/</filename> and
313 then boots an OS in a namespace container in
318 <title>Example 2</title>
320 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
321 # systemd-nspawn -D ~/debian-tree/</programlisting>
323 <para>This installs a minimal Debian unstable
324 distribution into the directory
325 <filename>~/debian-tree/</filename> and then spawns a
326 shell in a namespace container in it.</para>
330 <title>Example 3</title>
332 <programlisting># pacstrap -c -d ~/arch-tree/ base
333 # systemd-nspawn -bD ~/arch-tree/</programlisting>
335 <para>This installs a mimimal Arch Linux distribution into
336 the directory <filename>~/arch-tree/</filename> and then
337 boots an OS in a namespace container in it.</para>
340 <refsect1 id='example-nsenter'>
341 <title>Example 4</title>
343 <para>To enter the container, PID of one of the
344 processes sharing the new namespaces must be used.
345 <command>systemd-nspawn</command> prints the PID
346 (as viewed from the outside) of the launched process,
347 and it can be used to enter the container.</para>
349 <programlisting># nsenter -muinpt $PID</programlisting>
351 <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
353 <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
354 Kernel support for entering namespaces was added in
359 <title>Exit status</title>
361 <para>The exit code of the program executed in the
362 container is returned.</para>
366 <title>See Also</title>
368 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
369 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
370 <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
371 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
372 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
373 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>