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