chiark / gitweb /
build-sys: make PolicyKit support compile-time optional (was runtime-optional already)
[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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
53                 </cmdsynopsis>
54         </refsynopsisdiv>
55
56         <refsect1>
57                 <title>Description</title>
58
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
66                 name.</para>
67
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
77                 container.</para>
78
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>
88
89                 <para>In contrast to
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
93                 container.</para>
94
95                 <para>Use a tool like
96                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
97                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
98                 or
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>
102                 containers.</para>
103
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>
110
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>
118
119                 <para><command>systemd-nspawn</command> implements the
120                 <ulink
121                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
122                 Interface</ulink> specification.</para>
123         </refsect1>
124
125         <refsect1>
126                 <title>Options</title>
127
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>
132
133                 <variablelist>
134                         <varlistentry>
135                                 <term><option>-h</option></term>
136                                 <term><option>--help</option></term>
137
138                                 <listitem><para>Prints a short help
139                                 text and exits.</para></listitem>
140                         </varlistentry>
141
142                         <varlistentry>
143                                 <term><option>--version</option></term>
144
145                                 <listitem><para>Prints a version string
146                                 and exits.</para></listitem>
147                         </varlistentry>
148
149                         <varlistentry>
150                                 <term><option>-D</option></term>
151                                 <term><option>--directory=</option></term>
152
153                                 <listitem><para>Directory to use as
154                                 file system root for the namespace
155                                 container. If omitted the current
156                                 directory will be
157                                 used.</para></listitem>
158                         </varlistentry>
159
160                         <varlistentry>
161                                 <term><option>-b</option></term>
162                                 <term><option>--boot</option></term>
163
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>
168                         </varlistentry>
169
170                         <varlistentry>
171                                 <term><option>-u</option></term>
172                                 <term><option>--user=</option></term>
173
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.
180                                 </para></listitem>
181                         </varlistentry>
182
183                         <varlistentry>
184                                 <term><option>--uuid=</option></term>
185
186                                 <listitem><para>Set the specified uuid
187                                 for the container. The init system
188                                 will initialize
189                                 <filename>/etc/machine-id</filename>
190                                 from this if this file is not set yet.
191                                 </para></listitem>
192                         </varlistentry>
193
194                         <varlistentry>
195                                 <term><option>-C</option></term>
196                                 <term><option>--controllers=</option></term>
197
198                                 <listitem><para>Makes the container appear in
199                                 other hierarchies than the name=systemd:/ one.
200                                 Takes a comma-separated list of controllers.
201                                 </para></listitem>
202                         </varlistentry>
203
204                         <varlistentry>
205                                 <term><option>--private-network</option></term>
206
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>
212                         </varlistentry>
213
214                         <varlistentry>
215                                 <term><option>--read-only</option></term>
216
217                                 <listitem><para>Mount the root file
218                                 system read only for the
219                                 container.</para></listitem>
220                         </varlistentry>
221
222                         <varlistentry>
223                                 <term><option>--capability=</option></term>
224
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,
235                                 CAP_KILL, CAP_LEASE,
236                                 CAP_LINUX_IMMUTABLE,
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,
244                                 CAP_AUDIT_WRITE,
245                                 CAP_AUDIT_CONTROL.</para></listitem>
246                         </varlistentry>
247
248                         <varlistentry>
249                                 <term><option>--link-journal=</option></term>
250
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
256                                 versa). Takes one of
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/&lt;machine-id&gt;</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/&lt;machine-id&gt;</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>
287                         </varlistentry>
288
289                         <varlistentry>
290                                 <term><option>-j</option></term>
291
292                                 <listitem><para>Equivalent to
293                                 <option>--link-journal=guest</option>.</para></listitem>
294                         </varlistentry>
295                 </variablelist>
296
297         </refsect1>
298
299         <refsect1>
300                 <title>Example 1</title>
301
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>
304
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
308                 it.</para>
309         </refsect1>
310
311         <refsect1>
312                 <title>Example 2</title>
313
314                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
315 # systemd-nspawn -D ~/debian-tree/</programlisting>
316
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>
321
322         </refsect1>
323
324         <refsect1>
325                 <title>Example 3</title>
326
327                 <programlisting># pacstrap -c -d ~/arch-tree/ base
328 # systemd-nspawn -bD ~/arch-tree/</programlisting>
329
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>
333         </refsect1>
334
335         <refsect1>
336                 <title>Exit status</title>
337
338                 <para>The exit code of the program executed in the
339                 container is returned.</para>
340         </refsect1>
341
342         <refsect1>
343                 <title>See Also</title>
344                 <para>
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>
350                 </para>
351         </refsect1>
352
353 </refentry>