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
 137                 <para>As a safety check
 138                 <command>systemd-nspawn</command> will verify the
 139                 existance of <filename>/etc/os-release</filename> in
 140                 the container tree before starting the container (see
 141                 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
 142                 might be necessary to add this file to the container
 143                 tree manually if the OS of the container is too old to
 144                 contain this file out-of-the-box.</para>
 145
 146                 <para>Note that the kernel auditing subsystem is
 147                 currently broken when used together with
 148                 containers. We hence recommend turning it off entirely
 149                 when using <command>systemd-nspawn</command> by
 150                 booting with <literal>audit=0</literal> on the kernel
 151                 command line, or by turning it off at kernel build
 152                 time. If auditing is enabled in the kernel operating
 153                 systems booted in an nspawn container might refuse
 154                 log-in attempts.</para>
 155         </refsect1>
 156
 157         <refsect1>
 158                 <title>Options</title>
 159
 160                 <para>If option <option>-b</option> is specified, the
 161                 arguments are used as arguments for the init
 162                 binary. Otherwise, <replaceable>COMMAND</replaceable>
 163                 specifies the program to launch in the container, and
 164                 the remaining arguments are used as arguments for this
 165                 program. If <option>-b</option> is not used and no
 166                 arguments are specifed, a shell is launched in the
 167                 container.</para>
 168
 169                 <para>The following options are understood:</para>
 170
 171                 <variablelist>
 172                         <varlistentry>
 173                                 <term><option>-h</option></term>
 174                                 <term><option>--help</option></term>
 175
 176                                 <listitem><para>Prints a short help
 177                                 text and exits.</para></listitem>
 178                         </varlistentry>
 179
 180                         <varlistentry>
 181                                 <term><option>--version</option></term>
 182
 183                                 <listitem><para>Prints a version string
 184                                 and exits.</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, arguments
 206                                 specified on the command line are used
 207                                 as arguments for the init binary.
 208                                 </para></listitem>
 209                         </varlistentry>
 210
 211                         <varlistentry>
 212                                 <term><option>-u</option></term>
 213                                 <term><option>--user=</option></term>
 214
 215                                 <listitem><para>Run the command
 216                                 under specified user, create home
 217                                 directory and cd into it. As rest
 218                                 of systemd-nspawn, this is not
 219                                 the security feature and limits
 220                                 against accidental changes only.
 221                                 </para></listitem>
 222                         </varlistentry>
 223
 224                         <varlistentry>
 225                                 <term><option>-M</option></term>
 226                                 <term><option>--machine=</option></term>
 227
 228                                 <listitem><para>Sets the machine name
 229                                 for this container. This name may be
 230                                 used to identify this container on the
 231                                 host, and is used to initialize the
 232                                 container's hostname (which the
 233                                 container can choose to override,
 234                                 however). If not specified the last
 235                                 component of the root directory of the
 236                                 container is used.</para></listitem>
 237                         </varlistentry>
 238
 239                         <varlistentry>
 240                                 <term><option>--uuid=</option></term>
 241
 242                                 <listitem><para>Set the specified uuid
 243                                 for the container. The init system
 244                                 will initialize
 245                                 <filename>/etc/machine-id</filename>
 246                                 from this if this file is not set yet.
 247                                 </para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><option>-C</option></term>
 252                                 <term><option>--controllers=</option></term>
 253
 254                                 <listitem><para>Makes the container appear in
 255                                 other hierarchies than the name=systemd:/ one.
 256                                 Takes a comma-separated list of controllers.
 257                                 </para></listitem>
 258                         </varlistentry>
 259
 260                         <varlistentry>
 261                                 <term><option>--private-network</option></term>
 262
 263                                 <listitem><para>Turn off networking in
 264                                 the container. This makes all network
 265                                 interfaces unavailable in the
 266                                 container, with the exception of the
 267                                 loopback device.</para></listitem>
 268                         </varlistentry>
 269
 270                         <varlistentry>
 271                                 <term><option>--read-only</option></term>
 272
 273                                 <listitem><para>Mount the root file
 274                                 system read only for the
 275                                 container.</para></listitem>
 276                         </varlistentry>
 277
 278                         <varlistentry>
 279                                 <term><option>--capability=</option></term>
 280
 281                                 <listitem><para>List one or more
 282                                 additional capabilities to grant the
 283                                 container. Takes a comma separated
 284                                 list of capability names, see
 285                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 286                                 for more information. Note that the
 287                                 following capabilities will be granted
 288                                 in any way: CAP_CHOWN,
 289                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 290                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 291                                 CAP_KILL, CAP_LEASE,
 292                                 CAP_LINUX_IMMUTABLE,
 293                                 CAP_NET_BIND_SERVICE,
 294                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 295                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 296                                 CAP_SETUID, CAP_SYS_ADMIN,
 297                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 298                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 299                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 300                                 CAP_AUDIT_WRITE,
 301                                 CAP_AUDIT_CONTROL.</para></listitem>
 302                         </varlistentry>
 303
 304                         <varlistentry>
 305                                 <term><option>--link-journal=</option></term>
 306
 307                                 <listitem><para>Control whether the
 308                                 container's journal shall be made
 309                                 visible to the host system. If enabled
 310                                 allows viewing the container's journal
 311                                 files from the host (but not vice
 312                                 versa). Takes one of
 313                                 <literal>no</literal>,
 314                                 <literal>host</literal>,
 315                                 <literal>guest</literal>,
 316                                 <literal>auto</literal>. If
 317                                 <literal>no</literal>, the journal is
 318                                 not linked. If <literal>host</literal>,
 319                                 the journal files are stored on the
 320                                 host file system (beneath
 321                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 322                                 and the subdirectory is bind-mounted
 323                                 into the container at the same
 324                                 location. If <literal>guest</literal>,
 325                                 the journal files are stored on the
 326                                 guest file system (beneath
 327                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 328                                 and the subdirectory is symlinked into the host
 329                                 at the same location. If
 330                                 <literal>auto</literal> (the default),
 331                                 and the right subdirectory of
 332                                 <filename>/var/log/journal</filename>
 333                                 exists, it will be bind mounted
 334                                 into the container. If the
 335                                 subdirectory doesn't exist, no
 336                                 linking is performed. Effectively,
 337                                 booting a container once with
 338                                 <literal>guest</literal> or
 339                                 <literal>host</literal> will link the
 340                                 journal persistently if further on
 341                                 the default of <literal>auto</literal>
 342                                 is used.</para></listitem>
 343                         </varlistentry>
 344
 345                         <varlistentry>
 346                                 <term><option>-j</option></term>
 347
 348                                 <listitem><para>Equivalent to
 349                                 <option>--link-journal=guest</option>.</para></listitem>
 350                         </varlistentry>
 351
 352                         <varlistentry>
 353                                 <term><option>--bind=</option></term>
 354                                 <term><option>--bind-ro=</option></term>
 355
 356                                 <listitem><para>Bind mount a file or
 357                                 directory from the host into the
 358                                 container. Either takes a path
 359                                 argument -- in which case the
 360                                 specified path will be mounted from
 361                                 the host to the same path in the
 362                                 container --, or a colon-separated
 363                                 pair of paths -- in which case the
 364                                 first specified path is the source in
 365                                 the host, and the second path is the
 366                                 destination in the container. The
 367                                 <option>--bind-ro=</option> option
 368                                 creates read-only bind
 369                                 mount.</para></listitem>
 370                         </varlistentry>
 371                 </variablelist>
 372
 373         </refsect1>
 374
 375         <refsect1>
 376                 <title>Example 1</title>
 377
 378                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
 379 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 380
 381                 <para>This installs a minimal Fedora distribution into
 382                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
 383                 then boots an OS in a namespace container in
 384                 it.</para>
 385         </refsect1>
 386
 387         <refsect1>
 388                 <title>Example 2</title>
 389
 390                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 391 # systemd-nspawn -D ~/debian-tree/</programlisting>
 392
 393                 <para>This installs a minimal Debian unstable
 394                 distribution into the directory
 395                 <filename>~/debian-tree/</filename> and then spawns a
 396                 shell in a namespace container in it.</para>
 397         </refsect1>
 398
 399         <refsect1>
 400                 <title>Example 3</title>
 401
 402                 <programlisting># pacstrap -c -d ~/arch-tree/ base
 403 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 404
 405                 <para>This installs a mimimal Arch Linux distribution into
 406                 the directory <filename>~/arch-tree/</filename> and then
 407                 boots an OS in a namespace container in it.</para>
 408         </refsect1>
 409
 410         <refsect1 id='example-nsenter'>
 411                 <title>Example 4</title>
 412
 413                 <para>To enter the container, PID of one of the
 414                 processes sharing the new namespaces must be used.
 415                 <command>systemd-nspawn</command> prints the PID
 416                 (as viewed from the outside) of the launched process,
 417                 and it can be used to enter the container.</para>
 418
 419                 <programlisting># nsenter -m -u -i -n -p -t $PID</programlisting>
 420
 421                 <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 422                 is part of
 423                 <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
 424                 Kernel support for entering namespaces was added in
 425                 Linux 3.8.</para>
 426         </refsect1>
 427
 428         <refsect1>
 429                 <title>Exit status</title>
 430
 431                 <para>The exit code of the program executed in the
 432                 container is returned.</para>
 433         </refsect1>
 434
 435         <refsect1>
 436                 <title>See Also</title>
 437                 <para>
 438                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 439                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 440                         <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 441                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 442                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 443                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 444                 </para>
 445         </refsect1>
 446
 447 </refentry>