chiark / gitweb /
pager: introduce "jump to end" option
[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>
101                 <command>systemd-nspawn</command> may be used to boot
102                 full Linux-based operating systems in a
103                 container.</para>
104
105                 <para>Use a tool like
106                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
108                 or
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>
112                 containers.</para>
113
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>
120
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.
130                 </para>
131
132                 <para><command>systemd-nspawn</command> implements the
133                 <ulink
134                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
135                 Interface</ulink> specification.</para>
136         </refsect1>
137
138         <refsect1>
139                 <title>Options</title>
140
141                 <para>If option <option>-b</option> is specified, the
142                 arguments are used as arguments for the init
143                 binary. Otherwise, <replaceable>COMMAND</replaceable>
144                 specifies the program to launch in the container, and
145                 the remaining arguments are used as arguments for this
146                 program. If <option>-b</option> is not used and no
147                 arguments are specifed, a shell is launched in the
148                 container.</para>
149
150                 <para>The following options are understood:</para>
151
152                 <variablelist>
153                         <varlistentry>
154                                 <term><option>-h</option></term>
155                                 <term><option>--help</option></term>
156
157                                 <listitem><para>Prints a short help
158                                 text and exits.</para></listitem>
159                         </varlistentry>
160
161                         <varlistentry>
162                                 <term><option>--version</option></term>
163
164                                 <listitem><para>Prints a version string
165                                 and exits.</para></listitem>
166                         </varlistentry>
167
168                         <varlistentry>
169                                 <term><option>-D</option></term>
170                                 <term><option>--directory=</option></term>
171
172                                 <listitem><para>Directory to use as
173                                 file system root for the namespace
174                                 container. If omitted the current
175                                 directory will be
176                                 used.</para></listitem>
177                         </varlistentry>
178
179                         <varlistentry>
180                                 <term><option>-b</option></term>
181                                 <term><option>--boot</option></term>
182
183                                 <listitem><para>Automatically search
184                                 for an init binary and invoke it
185                                 instead of a shell or a user supplied
186                                 program. If this option is used, arguments
187                                 specified on the command line are used
188                                 as arguments for the init binary.
189                                 </para></listitem>
190                         </varlistentry>
191
192                         <varlistentry>
193                                 <term><option>-u</option></term>
194                                 <term><option>--user=</option></term>
195
196                                 <listitem><para>Run the command
197                                 under specified user, create home
198                                 directory and cd into it. As rest
199                                 of systemd-nspawn, this is not
200                                 the security feature and limits
201                                 against accidental changes only.
202                                 </para></listitem>
203                         </varlistentry>
204
205                         <varlistentry>
206                                 <term><option>--uuid=</option></term>
207
208                                 <listitem><para>Set the specified uuid
209                                 for the container. The init system
210                                 will initialize
211                                 <filename>/etc/machine-id</filename>
212                                 from this if this file is not set yet.
213                                 </para></listitem>
214                         </varlistentry>
215
216                         <varlistentry>
217                                 <term><option>-C</option></term>
218                                 <term><option>--controllers=</option></term>
219
220                                 <listitem><para>Makes the container appear in
221                                 other hierarchies than the name=systemd:/ one.
222                                 Takes a comma-separated list of controllers.
223                                 </para></listitem>
224                         </varlistentry>
225
226                         <varlistentry>
227                                 <term><option>--private-network</option></term>
228
229                                 <listitem><para>Turn off networking in
230                                 the container. This makes all network
231                                 interfaces unavailable in the
232                                 container, with the exception of the
233                                 loopback device.</para></listitem>
234                         </varlistentry>
235
236                         <varlistentry>
237                                 <term><option>--read-only</option></term>
238
239                                 <listitem><para>Mount the root file
240                                 system read only for the
241                                 container.</para></listitem>
242                         </varlistentry>
243
244                         <varlistentry>
245                                 <term><option>--capability=</option></term>
246
247                                 <listitem><para>List one or more
248                                 additional capabilities to grant the
249                                 container. Takes a comma separated
250                                 list of capability names, see
251                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
252                                 for more information. Note that the
253                                 following capabilities will be granted
254                                 in any way: CAP_CHOWN,
255                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
256                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
257                                 CAP_KILL, CAP_LEASE,
258                                 CAP_LINUX_IMMUTABLE,
259                                 CAP_NET_BIND_SERVICE,
260                                 CAP_NET_BROADCAST, CAP_NET_RAW,
261                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
262                                 CAP_SETUID, CAP_SYS_ADMIN,
263                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
264                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
265                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
266                                 CAP_AUDIT_WRITE,
267                                 CAP_AUDIT_CONTROL.</para></listitem>
268                         </varlistentry>
269
270                         <varlistentry>
271                                 <term><option>--link-journal=</option></term>
272
273                                 <listitem><para>Control whether the
274                                 container's journal shall be made
275                                 visible to the host system. If enabled
276                                 allows viewing the container's journal
277                                 files from the host (but not vice
278                                 versa). Takes one of
279                                 <literal>no</literal>,
280                                 <literal>host</literal>,
281                                 <literal>guest</literal>,
282                                 <literal>auto</literal>. If
283                                 <literal>no</literal>, the journal is
284                                 not linked. If <literal>host</literal>,
285                                 the journal files are stored on the
286                                 host file system (beneath
287                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
288                                 and the subdirectory is bind-mounted
289                                 into the container at the same
290                                 location. If <literal>guest</literal>,
291                                 the journal files are stored on the
292                                 guest file system (beneath
293                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
294                                 and the subdirectory is symlinked into the host
295                                 at the same location. If
296                                 <literal>auto</literal> (the default),
297                                 and the right subdirectory of
298                                 <filename>/var/log/journal</filename>
299                                 exists, it will be bind mounted
300                                 into the container. If the
301                                 subdirectory doesn't exist, no
302                                 linking is performed. Effectively,
303                                 booting a container once with
304                                 <literal>guest</literal> or
305                                 <literal>host</literal> will link the
306                                 journal persistently if further on
307                                 the default of <literal>auto</literal>
308                                 is used.</para></listitem>
309                         </varlistentry>
310
311                         <varlistentry>
312                                 <term><option>-j</option></term>
313
314                                 <listitem><para>Equivalent to
315                                 <option>--link-journal=guest</option>.</para></listitem>
316                         </varlistentry>
317
318                         <varlistentry>
319                                 <term><option>--bind=</option></term>
320                                 <term><option>--bind-ro=</option></term>
321
322                                 <listitem><para>Bind mount a file or
323                                 directory from the host into the
324                                 container. Either takes a path
325                                 argument -- in which case the
326                                 specified path will be mounted from
327                                 the host to the same path in the
328                                 container --, or a colon-separated
329                                 pair of paths -- in which case the
330                                 first specified path is the source in
331                                 the host, and the second path is the
332                                 destination in the container. The
333                                 <option>--bind-ro=</option> option
334                                 creates read-only bind
335                                 mount.</para></listitem>
336                         </varlistentry>
337                 </variablelist>
338
339         </refsect1>
340
341         <refsect1>
342                 <title>Example 1</title>
343
344                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
345 # systemd-nspawn -bD /srv/mycontainer</programlisting>
346
347                 <para>This installs a minimal Fedora distribution into
348                 the directory <filename>/srv/mycontainer/</filename> and
349                 then boots an OS in a namespace container in
350                 it.</para>
351         </refsect1>
352
353         <refsect1>
354                 <title>Example 2</title>
355
356                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
357 # systemd-nspawn -D ~/debian-tree/</programlisting>
358
359                 <para>This installs a minimal Debian unstable
360                 distribution into the directory
361                 <filename>~/debian-tree/</filename> and then spawns a
362                 shell in a namespace container in it.</para>
363         </refsect1>
364
365         <refsect1>
366                 <title>Example 3</title>
367
368                 <programlisting># pacstrap -c -d ~/arch-tree/ base
369 # systemd-nspawn -bD ~/arch-tree/</programlisting>
370
371                 <para>This installs a mimimal Arch Linux distribution into
372                 the directory <filename>~/arch-tree/</filename> and then
373                 boots an OS in a namespace container in it.</para>
374         </refsect1>
375
376         <refsect1 id='example-nsenter'>
377                 <title>Example 4</title>
378
379                 <para>To enter the container, PID of one of the
380                 processes sharing the new namespaces must be used.
381                 <command>systemd-nspawn</command> prints the PID
382                 (as viewed from the outside) of the launched process,
383                 and it can be used to enter the container.</para>
384
385                 <programlisting># nsenter -muinpt $PID</programlisting>
386
387                 <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
388                 is part of
389                 <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
390                 Kernel support for entering namespaces was added in
391                 Linux 3.8.</para>
392         </refsect1>
393
394         <refsect1>
395                 <title>Exit status</title>
396
397                 <para>The exit code of the program executed in the
398                 container is returned.</para>
399         </refsect1>
400
401         <refsect1>
402                 <title>See Also</title>
403                 <para>
404                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
405                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
406                         <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
407                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
408                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
409                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
410                 </para>
411         </refsect1>
412
413 </refentry>