chiark / gitweb /
man: document $MAINPID
[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> <command>systemd-nspawn</command>
101                 may be used to boot full Linux-based operating systems
102                 in a container.</para>
103
104                 <para>Use a tool like
105                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
106                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107                 or
108                 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
109                 to set up an OS directory tree suitable as file system
110                 hierarchy for <command>systemd-nspawn</command>
111                 containers.</para>
112
113                 <para>Note that <command>systemd-nspawn</command> will
114                 mount file systems private to the container to
115                 <filename>/dev</filename>,
116                 <filename>/run</filename> and similar. These will
117                 not be visible outside of the container, and their
118                 contents will be lost when the container exits.</para>
119
120                 <para>Note that running two
121                 <command>systemd-nspawn</command> containers from the
122                 same directory tree will not make processes in them
123                 see each other. The PID namespace separation of the
124                 two containers is complete and the containers will
125                 share very few runtime objects except for the
126                 underlying file system. Use
127                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
128                 <command>login</command> command to request an
129                 additional login prompt in a running container.</para>
130
131                 <para><command>systemd-nspawn</command> implements the
132                 <ulink
133                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
134                 Interface</ulink> specification.</para>
135
136                 <para>As a safety check
137                 <command>systemd-nspawn</command> will verify the
138                 existence of <filename>/etc/os-release</filename> in
139                 the container tree before starting the container (see
140                 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
141                 might be necessary to add this file to the container
142                 tree manually if the OS of the container is too old to
143                 contain this file out-of-the-box.</para>
144         </refsect1>
145
146         <refsect1>
147                 <title>Options</title>
148
149                 <para>If option <option>-b</option> is specified, the
150                 arguments are used as arguments for the init
151                 binary. Otherwise, <replaceable>COMMAND</replaceable>
152                 specifies the program to launch in the container, and
153                 the remaining arguments are used as arguments for this
154                 program. If <option>-b</option> is not used and no
155                 arguments are specifed, a shell is launched in the
156                 container.</para>
157
158                 <para>The following options are understood:</para>
159
160                 <variablelist>
161                         <varlistentry>
162                                 <term><option>-h</option></term>
163                                 <term><option>--help</option></term>
164
165                                 <listitem><para>Prints a short help
166                                 text and exits.</para></listitem>
167                         </varlistentry>
168
169                         <varlistentry>
170                                 <term><option>--version</option></term>
171
172                                 <listitem><para>Prints a version string
173                                 and exits.</para></listitem>
174                         </varlistentry>
175
176                         <varlistentry>
177                                 <term><option>-q</option></term>
178                                 <term><option>--quiet</option></term>
179
180                                 <listitem><para>Turns off any status
181                                 output by the tool itself. When this
182                                 switch is used, the only output
183                                 from nspawn will be the console output
184                                 of the container OS itself.</para></listitem>
185                         </varlistentry>
186
187                         <varlistentry>
188                                 <term><option>-D</option></term>
189                                 <term><option>--directory=</option></term>
190
191                                 <listitem><para>Directory to use as
192                                 file system root for the namespace
193                                 container. If omitted, the current
194                                 directory will be
195                                 used.</para></listitem>
196                         </varlistentry>
197
198                         <varlistentry>
199                                 <term><option>-b</option></term>
200                                 <term><option>--boot</option></term>
201
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,
206                                 arguments specified on the command
207                                 line are used as arguments for the
208                                 init binary. This option may not be
209                                 combined with
210                                 <option>--share-system</option>.
211                                 </para></listitem>
212                         </varlistentry>
213
214                         <varlistentry>
215                                 <term><option>-u</option></term>
216                                 <term><option>--user=</option></term>
217
218                                 <listitem><para>Run the command
219                                 under specified user, create home
220                                 directory and cd into it. As rest
221                                 of systemd-nspawn, this is not
222                                 the security feature and limits
223                                 against accidental changes only.
224                                 </para></listitem>
225                         </varlistentry>
226
227                         <varlistentry>
228                                 <term><option>-M</option></term>
229                                 <term><option>--machine=</option></term>
230
231                                 <listitem><para>Sets the machine name
232                                 for this container. This name may be
233                                 used to identify this container on the
234                                 host, and is used to initialize the
235                                 container's hostname (which the
236                                 container can choose to override,
237                                 however). If not specified, the last
238                                 component of the root directory of the
239                                 container is used.</para></listitem>
240                         </varlistentry>
241
242                         <varlistentry>
243                                 <term><option>--uuid=</option></term>
244
245                                 <listitem><para>Set the specified UUID
246                                 for the container. The init system
247                                 will initialize
248                                 <filename>/etc/machine-id</filename>
249                                 from this if this file is not set yet.
250                                 </para></listitem>
251                         </varlistentry>
252
253                         <varlistentry>
254                                 <term><option>--slice=</option></term>
255
256                                 <listitem><para>Make the container
257                                 part of the specified slice, instead
258                                 of the default
259                                 <filename>machine.slice</filename>.</para>
260                                 </listitem>
261                         </varlistentry>
262
263                         <varlistentry>
264                                 <term><option>--private-network</option></term>
265
266                                 <listitem><para>Disconnect networking
267                                 of the container from the host. This
268                                 makes all network interfaces
269                                 unavailable in the container, with the
270                                 exception of the loopback device and
271                                 those specified with
272                                 <option>--network-interface=</option>
273                                 and configured with
274                                 <option>--network-veth</option>. If
275                                 this option is specified, the
276                                 CAP_NET_ADMIN capability will be added
277                                 to the set of capabilities the
278                                 container retains. The latter may be
279                                 disabled by using
280                                 <option>--drop-capability=</option>.</para></listitem>
281                         </varlistentry>
282
283                         <varlistentry>
284                                 <term><option>--network-interface=</option></term>
285
286                                 <listitem><para>Assign the specified
287                                 network interface to the
288                                 container. This will move the
289                                 specified interface from the calling
290                                 namespace and place it in the
291                                 container. When the container
292                                 terminates, it is moved back to the
293                                 host namespace. Note that
294                                 <option>--network-interface=</option>
295                                 implies
296                                 <option>--private-network</option>. This
297                                 option may be used more than once to
298                                 add multiple network interfaces to the
299                                 container.</para></listitem>
300                         </varlistentry>
301
302                         <varlistentry>
303                                 <term><option>--network-veth</option></term>
304
305                                 <listitem><para>Create a virtual
306                                 Ethernet link between host and
307                                 container. The host side of the
308                                 Ethernet link will be available as a
309                                 network interface named after the
310                                 container's name (as specified with
311                                 <option>--machine=</option>), prefixed
312                                 with <literal>ve-</literal>. The
313                                 container side of the the Ethernet
314                                 link will be named
315                                 <literal>host0</literal>. Note that
316                                 <option>--network-veth</option>
317                                 implies
318                                 <option>--private-network</option>.</para></listitem>
319                         </varlistentry>
320
321                         <varlistentry>
322                                 <term><option>--network-bridge=</option></term>
323
324                                 <listitem><para>Adds the host side of the
325                                 Ethernet link created with
326                                 <option>--network-veth</option>
327                                 to the specified bridge. Note that
328                                 <option>--network-bridge</option>
329                                 implies
330                                 <option>--network-veth</option>.</para></listitem>
331                         </varlistentry>
332
333                         <varlistentry>
334                                 <term><option>-Z</option></term>
335                                 <term><option>--selinux-context=</option></term>
336
337                                 <listitem><para>Sets the SELinux
338                                 security context to be used to label
339                                 processes in the container.</para>
340                                 </listitem>
341                         </varlistentry>
342
343                         <varlistentry>
344                                 <term><option>-L</option></term>
345                                 <term><option>--selinux-apifs-context=</option></term>
346
347                                 <listitem><para>Sets the SELinux security
348                                 context to be used to label files in
349                                 the virtual API file systems in the
350                                 container.</para>
351                                 </listitem>
352                         </varlistentry>
353
354                         <varlistentry>
355                                 <term><option>--capability=</option></term>
356
357                                 <listitem><para>List one or more
358                                 additional capabilities to grant the
359                                 container. Takes a comma-separated
360                                 list of capability names, see
361                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
362                                 for more information. Note that the
363                                 following capabilities will be granted
364                                 in any way: CAP_CHOWN,
365                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
366                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
367                                 CAP_KILL, CAP_LEASE,
368                                 CAP_LINUX_IMMUTABLE,
369                                 CAP_NET_BIND_SERVICE,
370                                 CAP_NET_BROADCAST, CAP_NET_RAW,
371                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
372                                 CAP_SETUID, CAP_SYS_ADMIN,
373                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
374                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
375                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
376                                 CAP_AUDIT_WRITE,
377                                 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
378                                 is retained if
379                                 <option>--private-network</option> is
380                                 specified. If the special value
381                                 <literal>all</literal> is passed, all
382                                 capabilities are
383                                 retained.</para></listitem>
384                         </varlistentry>
385
386                         <varlistentry>
387                                 <term><option>--drop-capability=</option></term>
388
389                                 <listitem><para>Specify one or more
390                                 additional capabilities to drop for
391                                 the container. This allows running the
392                                 container with fewer capabilities than
393                                 the default (see above).</para></listitem>
394                         </varlistentry>
395
396                         <varlistentry>
397                                 <term><option>--link-journal=</option></term>
398
399                                 <listitem><para>Control whether the
400                                 container's journal shall be made
401                                 visible to the host system. If enabled,
402                                 allows viewing the container's journal
403                                 files from the host (but not vice
404                                 versa). Takes one of
405                                 <literal>no</literal>,
406                                 <literal>host</literal>,
407                                 <literal>guest</literal>,
408                                 <literal>auto</literal>. If
409                                 <literal>no</literal>, the journal is
410                                 not linked. If <literal>host</literal>,
411                                 the journal files are stored on the
412                                 host file system (beneath
413                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
414                                 and the subdirectory is bind-mounted
415                                 into the container at the same
416                                 location. If <literal>guest</literal>,
417                                 the journal files are stored on the
418                                 guest file system (beneath
419                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
420                                 and the subdirectory is symlinked into the host
421                                 at the same location. If
422                                 <literal>auto</literal> (the default),
423                                 and the right subdirectory of
424                                 <filename>/var/log/journal</filename>
425                                 exists, it will be bind mounted
426                                 into the container. If the
427                                 subdirectory does not exist, no
428                                 linking is performed. Effectively,
429                                 booting a container once with
430                                 <literal>guest</literal> or
431                                 <literal>host</literal> will link the
432                                 journal persistently if further on
433                                 the default of <literal>auto</literal>
434                                 is used.</para></listitem>
435                         </varlistentry>
436
437                         <varlistentry>
438                                 <term><option>-j</option></term>
439
440                                 <listitem><para>Equivalent to
441                                 <option>--link-journal=guest</option>.</para></listitem>
442                         </varlistentry>
443
444                         <varlistentry>
445                                 <term><option>--read-only</option></term>
446
447                                 <listitem><para>Mount the root file
448                                 system read-only for the
449                                 container.</para></listitem>
450                         </varlistentry>
451
452                         <varlistentry>
453                                 <term><option>--bind=</option></term>
454                                 <term><option>--bind-ro=</option></term>
455
456                                 <listitem><para>Bind mount a file or
457                                 directory from the host into the
458                                 container. Either takes a path
459                                 argument -- in which case the
460                                 specified path will be mounted from
461                                 the host to the same path in the
462                                 container --, or a colon-separated
463                                 pair of paths -- in which case the
464                                 first specified path is the source in
465                                 the host, and the second path is the
466                                 destination in the container. The
467                                 <option>--bind-ro=</option> option
468                                 creates read-only bind
469                                 mount.</para></listitem>
470                         </varlistentry>
471
472                         <varlistentry>
473                                 <term><option>--setenv=</option></term>
474
475                                 <listitem><para>Specifies an
476                                 environment variable assignment to
477                                 pass to the init process in the
478                                 container, in the format
479                                 <literal>NAME=VALUE</literal>. This
480                                 may be used to override the default
481                                 variables or to set additional
482                                 variables. This parameter may be used
483                                 more than once.</para></listitem>
484                         </varlistentry>
485
486                         <varlistentry>
487                                 <term><option>--share-system</option></term>
488
489                                 <listitem><para>Allows the container
490                                 to share certain system facilities
491                                 with the host. More specifically, this
492                                 turns off PID namespacing, UTS
493                                 namespacing and IPC namespacing, and
494                                 thus allows the guest to see and
495                                 interact more easily with processes
496                                 outside of the container. Note that
497                                 using this option makes it impossible
498                                 to start up a full Operating System in
499                                 the container, as an init system
500                                 cannot operate in this mode. It is
501                                 only useful to run specific programs
502                                 or applications this way, without
503                                 involving an init system in the
504                                 container. This option implies
505                                 <option>--register=no</option>. This
506                                 option may not be combined with
507                                 <option>--boot</option>.</para></listitem>
508                         </varlistentry>
509
510                         <varlistentry>
511                                 <term><option>--register=</option></term>
512
513                                 <listitem><para>Controls whether the
514                                 container is registered with
515                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
516                                 a boolean argument, defaults to
517                                 <literal>yes</literal>. This option
518                                 should be enabled when the container
519                                 runs a full Operating System (more
520                                 specifically: an init system), and is
521                                 useful to ensure that the container is
522                                 accessible via
523                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
524                                 and shown by tools such as
525                                 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
526                                 the container does not run an init
527                                 system, it is recommended to set this
528                                 option to <literal>no</literal>. Note
529                                 that <option>--share-system</option>
530                                 implies
531                                 <option>--register=no</option>.
532                                 </para></listitem>
533                         </varlistentry>
534
535                         <varlistentry>
536                                 <term><option>--keep-unit</option></term>
537
538                                 <listitem><para>Instead of creating a
539                                 transient scope unit to run the
540                                 container in, simply register the
541                                 service or scope unit
542                                 <command>systemd-nspawn</command> has
543                                 been invoked in with
544                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
545                                 has no effect if
546                                 <option>--register=no</option> is
547                                 used. This switch should be used if
548                                 <command>systemd-nspawn</command> is
549                                 invoked from within a service unit,
550                                 and the service unit's sole purpose
551                                 is to run a single
552                                 <command>systemd-nspawn</command>
553                                 container. This option is not
554                                 available if run from a user
555                                 session.</para></listitem>
556                         </varlistentry>
557
558                         <varlistentry>
559                                 <term><option>--personality=</option></term>
560
561                                 <listitem><para>Control the
562                                 architecture ("personality") reported
563                                 by
564                                 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
565                                 in the container. Currently, only
566                                 <literal>x86</literal> and
567                                 <literal>x86-64</literal> are
568                                 supported. This is useful when running
569                                 a 32bit container on a 64bit
570                                 host. If this setting is not used
571                                 the personality reported in the
572                                 container is the same as the one
573                                 reported on the
574                                 host.</para></listitem>
575                         </varlistentry>
576                 </variablelist>
577
578         </refsect1>
579
580         <refsect1>
581                 <title>Example 1</title>
582
583                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
584 # systemd-nspawn -bD /srv/mycontainer</programlisting>
585
586                 <para>This installs a minimal Fedora distribution into
587                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
588                 then boots an OS in a namespace container in
589                 it.</para>
590         </refsect1>
591
592         <refsect1>
593                 <title>Example 2</title>
594
595                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
596 # systemd-nspawn -D ~/debian-tree/</programlisting>
597
598                 <para>This installs a minimal Debian unstable
599                 distribution into the directory
600                 <filename>~/debian-tree/</filename> and then spawns a
601                 shell in a namespace container in it.</para>
602         </refsect1>
603
604         <refsect1>
605                 <title>Example 3</title>
606
607                 <programlisting># pacstrap -c -d ~/arch-tree/ base
608 # systemd-nspawn -bD ~/arch-tree/</programlisting>
609
610                 <para>This installs a mimimal Arch Linux distribution into
611                 the directory <filename>~/arch-tree/</filename> and then
612                 boots an OS in a namespace container in it.</para>
613         </refsect1>
614
615         <refsect1>
616                 <title>Example 4</title>
617
618                 <programlisting># mv ~/arch-tree /var/lib/container/arch
619 # systemctl enable systemd-nspawn@arch.service
620 # systemctl start systemd-nspawn@arch.service</programlisting>
621
622                 <para>This makes the Arch Linux container part of the
623                 <filename>multi-user.target</filename> on the host.
624                 </para>
625         </refsect1>
626
627         <refsect1>
628                 <title>Example 5</title>
629
630                 <programlisting># btrfs subvolume snapshot / /.tmp
631 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
632
633                 <para>This runs a copy of the host system in a
634                 btrfs snapshot.</para>
635         </refsect1>
636
637         <refsect1>
638                 <title>Example 6</title>
639
640                 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
641 # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting>
642
643                 <para>This runs a container with SELinux sandbox security contexts.</para>
644         </refsect1>
645
646         <refsect1>
647                 <title>Exit status</title>
648
649                 <para>The exit code of the program executed in the
650                 container is returned.</para>
651         </refsect1>
652
653         <refsect1>
654                 <title>See Also</title>
655                 <para>
656                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
657                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
658                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
659                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
660                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
661                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
662                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
663                 </para>
664         </refsect1>
665
666 </refentry>