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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
57 <title>Description</title>
59 <para><command>systemd-nspawn</command> may be used to
60 run a command or OS in a light-weight namespace
61 container. In many ways it is similar to
62 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
63 but more powerful since it fully virtualizes the file
64 system hierarchy, as well as the process tree, the
65 various IPC subsystems and the host and domain
68 <para><command>systemd-nspawn</command> limits access
69 to various kernel interfaces in the container to
70 read-only, such as <filename>/sys</filename>,
71 <filename>/proc/sys</filename> or
72 <filename>/sys/fs/selinux</filename>. Network
73 interfaces and the system clock may not be changed
74 from within the container. Device nodes may not be
75 created. The host system cannot be rebooted and kernel
76 modules may not be loaded from within the
79 <para>Note that even though these security precautions
80 are taken <command>systemd-nspawn</command> is not
81 suitable for secure container setups. Many of the
82 security features may be circumvented and are hence
83 primarily useful to avoid accidental changes to the
84 host system from the container. The intended use of
85 this program is debugging and testing as well as
86 building of packages, distributions and software
87 involved with boot and systems management.</para>
90 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
91 <command>systemd-nspawn</command> may be used to boot
92 full Linux-based operating systems in a
96 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
97 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
99 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
100 to set up an OS directory tree suitable as file system
101 hierarchy for <command>systemd-nspawn</command>
104 <para>Note that <command>systemd-nspawn</command> will
105 mount file systems private to the container to
106 <filename>/dev</filename>,
107 <filename>/run</filename> and similar. These will
108 not be visible outside of the container, and their
109 contents will be lost when the container exits.</para>
111 <para>Note that running two
112 <command>systemd-nspawn</command> containers from the
113 same directory tree will not make processes in them
114 see each other. The PID namespace separation of the
115 two containers is complete and the containers will
116 share very few runtime objects except for the
117 underlying file system.</para>
119 <para><command>systemd-nspawn</command> implements the
121 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
122 Interface</ulink> specification.</para>
126 <title>Options</title>
128 <para>If no arguments are passed the container is set
129 up and a shell started in it, otherwise the passed
130 command and arguments are executed in it. The
131 following options are understood:</para>
135 <term><option>--help</option></term>
136 <term><option>-h</option></term>
138 <listitem><para>Prints a short help
139 text and exits.</para></listitem>
143 <term><option>--version</option></term>
145 <listitem><para>Prints a version string
146 and exits.</para></listitem>
150 <term><option>--directory=</option></term>
151 <term><option>-D</option></term>
153 <listitem><para>Directory to use as
154 file system root for the namespace
155 container. If omitted the current
157 used.</para></listitem>
161 <term><option>--boot</option></term>
162 <term><option>-b</option></term>
164 <listitem><para>Automatically search
165 for an init binary and invoke it
166 instead of a shell or a user supplied
167 program.</para></listitem>
171 <term><option>--user=</option></term>
172 <term><option>-u</option></term>
174 <listitem><para>Run the command
175 under specified user, create home
176 directory and cd into it. As rest
177 of systemd-nspawn, this is not
178 the security feature and limits
179 against accidental changes only.
184 <term><option>--uuid=</option></term>
186 <listitem><para>Set the specified uuid
187 for the container. The init system
189 <filename>/etc/machine-id</filename>
190 from this if this file is not set yet.
195 <term><option>--controllers=</option></term>
196 <term><option>-C</option></term>
198 <listitem><para>Makes the container appear in
199 other hierarchies than the name=systemd:/ one.
200 Takes a comma-separated list of controllers.
205 <term><option>--private-network</option></term>
207 <listitem><para>Turn off networking in
208 the container. This makes all network
209 interfaces unavailable in the
210 container, with the exception of the
211 loopback device.</para></listitem>
215 <term><option>--read-only</option></term>
217 <listitem><para>Mount the root file
218 system read only for the
219 container.</para></listitem>
223 <term><option>--capability=</option></term>
225 <listitem><para>List one or more
226 additional capabilities to grant the
227 container. Takes a comma separated
228 list of capability names, see
229 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
230 for more information. Note that the
231 following capabilities will be granted
232 in any way: CAP_CHOWN,
233 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
234 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
237 CAP_NET_BIND_SERVICE,
238 CAP_NET_BROADCAST, CAP_NET_RAW,
239 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
240 CAP_SETUID, CAP_SYS_ADMIN,
241 CAP_SYS_CHROOT, CAP_SYS_NICE,
242 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
243 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
245 CAP_AUDIT_CONTROL.</para></listitem>
249 <term><option>--link-journal=</option></term>
251 <listitem><para>Control whether the
252 container's journal shall be made
253 visible to the host system. If enabled
254 allows viewing the container's journal
255 files from the host (but not vice
257 <literal>no</literal>,
258 <literal>host</literal>,
259 <literal>guest</literal>,
260 <literal>auto</literal>. If
261 <literal>no</literal>, the journal is
262 not linked. If <literal>host</literal>,
263 the journal files are stored on the
264 host file system (beneath
265 <filename>/var/log/journal/<machine-id></filename>)
266 and the subdirectory is bind-mounted
267 into the container at the same
268 location. If <literal>guest</literal>,
269 the journal files are stored on the
270 guest file system (beneath
271 <filename>/var/log/journal/<machine-id></filename>)
272 and the subdirectory is symlinked into the host
273 at the same location. If
274 <literal>auto</literal> (the default),
275 and the right subdirectory of
276 <filename>/var/log/journal</filename>
277 exists, it will be bind mounted
278 into the container. If the
279 subdirectory doesn't exist, no
280 linking is performed. Effectively,
281 booting a container once with
282 <literal>guest</literal> or
283 <literal>host</literal> will link the
284 journal persistently if further on
285 the default of <literal>auto</literal>
286 is used.</para></listitem>
290 <term><option>-j</option></term>
292 <listitem><para>Equivalent to
293 <option>--link-journal=guest</option>.</para></listitem>
300 <title>Example 1</title>
302 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
303 # systemd-nspawn -bD /srv/mycontainer</programlisting>
305 <para>This installs a minimal Fedora distribution into
306 the directory <filename>/srv/mycontainer/</filename> and
307 then boots an OS in a namespace container in
312 <title>Example 2</title>
314 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
315 # systemd-nspawn -D ~/debian-tree/</programlisting>
317 <para>This installs a minimal Debian unstable
318 distribution into the directory
319 <filename>~/debian-tree/</filename> and then spawns a
320 shell in a namespace container in it.</para>
325 <title>Example 3</title>
327 <programlisting># pacstrap -c -d ~/arch-tree/ base
328 # systemd-nspawn -bD ~/arch-tree/</programlisting>
330 <para>This installs a mimimal Arch Linux distribution into
331 the directory <filename>~/arch-tree/</filename> and then
332 boots an OS in a namespace container in it.</para>
336 <title>Exit status</title>
338 <para>The exit code of the program executed in the
339 container is returned.</para>
343 <title>See Also</title>
345 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
346 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
347 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
348 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
349 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>