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>Incompatibility with Auditing</title>
 148
 149                 <para>Note that the kernel auditing subsystem is
 150                 currently broken when used together with
 151                 containers. We hence recommend turning it off entirely
 152                 by booting with <literal>audit=0</literal> on the
 153                 kernel command line, or by turning it off at kernel
 154                 build time. If auditing is enabled in the kernel,
 155                 operating systems booted in an nspawn container might
 156                 refuse log-in attempts.</para>
 157         </refsect1>
 158
 159         <refsect1>
 160                 <title>Options</title>
 161
 162                 <para>If option <option>-b</option> is specified, the
 163                 arguments are used as arguments for the init
 164                 binary. Otherwise, <replaceable>COMMAND</replaceable>
 165                 specifies the program to launch in the container, and
 166                 the remaining arguments are used as arguments for this
 167                 program. If <option>-b</option> is not used and no
 168                 arguments are specifed, a shell is launched in the
 169                 container.</para>
 170
 171                 <para>The following options are understood:</para>
 172
 173                 <variablelist>
 174                         <varlistentry>
 175                                 <term><option>-h</option></term>
 176                                 <term><option>--help</option></term>
 177
 178                                 <listitem><para>Prints a short help
 179                                 text and exits.</para></listitem>
 180                         </varlistentry>
 181
 182                         <varlistentry>
 183                                 <term><option>--version</option></term>
 184
 185                                 <listitem><para>Prints a version string
 186                                 and exits.</para></listitem>
 187                         </varlistentry>
 188
 189                         <varlistentry>
 190                                 <term><option>-D</option></term>
 191                                 <term><option>--directory=</option></term>
 192
 193                                 <listitem><para>Directory to use as
 194                                 file system root for the namespace
 195                                 container. If omitted, the current
 196                                 directory will be
 197                                 used.</para></listitem>
 198                         </varlistentry>
 199
 200                         <varlistentry>
 201                                 <term><option>-b</option></term>
 202                                 <term><option>--boot</option></term>
 203
 204                                 <listitem><para>Automatically search
 205                                 for an init binary and invoke it
 206                                 instead of a shell or a user supplied
 207                                 program. If this option is used, arguments
 208                                 specified on the command line are used
 209                                 as arguments for the init binary.
 210                                 </para></listitem>
 211                         </varlistentry>
 212
 213                         <varlistentry>
 214                                 <term><option>-u</option></term>
 215                                 <term><option>--user=</option></term>
 216
 217                                 <listitem><para>Run the command
 218                                 under specified user, create home
 219                                 directory and cd into it. As rest
 220                                 of systemd-nspawn, this is not
 221                                 the security feature and limits
 222                                 against accidental changes only.
 223                                 </para></listitem>
 224                         </varlistentry>
 225
 226                         <varlistentry>
 227                                 <term><option>-M</option></term>
 228                                 <term><option>--machine=</option></term>
 229
 230                                 <listitem><para>Sets the machine name
 231                                 for this container. This name may be
 232                                 used to identify this container on the
 233                                 host, and is used to initialize the
 234                                 container's hostname (which the
 235                                 container can choose to override,
 236                                 however). If not specified, the last
 237                                 component of the root directory of the
 238                                 container is used.</para></listitem>
 239                         </varlistentry>
 240
 241                         <varlistentry>
 242                                 <term><option>--slice=</option></term>
 243
 244                                 <listitem><para>Make the container
 245                                 part of the specified slice, instead
 246                                 of the
 247                                 <filename>machine.slice</filename>.</para>
 248                                 </listitem>
 249                         </varlistentry>
 250
 251                         <varlistentry>
 252                                 <term><option>-L</option></term>
 253                                 <term><option>--file-label=</option></term>
 254
 255                                 <listitem><para>Sets the mandatory
 256                                 access control (MAC/SELinux) file
 257                                 label to be used by virtual API file
 258                                 systems in the container.</para>
 259                                 </listitem>
 260                         </varlistentry>
 261
 262                         <varlistentry>
 263                                 <term><option>-Z</option></term>
 264                                 <term><option>--process-label=</option></term>
 265
 266                                 <listitem><para>Sets the mandatory
 267                                 access control (MAC/SELinux) label to be used by
 268                                 processes in the container.</para>
 269                                 </listitem>
 270                         </varlistentry>
 271
 272                         <varlistentry>
 273                                 <term><option>--uuid=</option></term>
 274
 275                                 <listitem><para>Set the specified UUID
 276                                 for the container. The init system
 277                                 will initialize
 278                                 <filename>/etc/machine-id</filename>
 279                                 from this if this file is not set yet.
 280                                 </para></listitem>
 281                         </varlistentry>
 282
 283                         <varlistentry>
 284                                 <term><option>--private-network</option></term>
 285
 286                                 <listitem><para>Turn off networking in
 287                                 the container. This makes all network
 288                                 interfaces unavailable in the
 289                                 container, with the exception of the
 290                                 loopback device.</para></listitem>
 291                         </varlistentry>
 292
 293                         <varlistentry>
 294                                 <term><option>--read-only</option></term>
 295
 296                                 <listitem><para>Mount the root file
 297                                 system read-only for the
 298                                 container.</para></listitem>
 299                         </varlistentry>
 300
 301                         <varlistentry>
 302                                 <term><option>--capability=</option></term>
 303
 304                                 <listitem><para>List one or more
 305                                 additional capabilities to grant the
 306                                 container. Takes a comma-separated
 307                                 list of capability names, see
 308                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 309                                 for more information. Note that the
 310                                 following capabilities will be granted
 311                                 in any way: CAP_CHOWN,
 312                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 313                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 314                                 CAP_KILL, CAP_LEASE,
 315                                 CAP_LINUX_IMMUTABLE,
 316                                 CAP_NET_BIND_SERVICE,
 317                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 318                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 319                                 CAP_SETUID, CAP_SYS_ADMIN,
 320                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 321                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 322                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 323                                 CAP_AUDIT_WRITE,
 324                                 CAP_AUDIT_CONTROL.</para></listitem>
 325                         </varlistentry>
 326
 327                         <varlistentry>
 328                                 <term><option>--drop-capability=</option></term>
 329
 330                                 <listitem><para>Specify one or more
 331                                 additional capabilities to drop for
 332                                 the container. This allows running the
 333                                 container with fewer capabilities than
 334                                 the default (see above).</para></listitem>
 335                         </varlistentry>
 336
 337                         <varlistentry>
 338                                 <term><option>--link-journal=</option></term>
 339
 340                                 <listitem><para>Control whether the
 341                                 container's journal shall be made
 342                                 visible to the host system. If enabled,
 343                                 allows viewing the container's journal
 344                                 files from the host (but not vice
 345                                 versa). Takes one of
 346                                 <literal>no</literal>,
 347                                 <literal>host</literal>,
 348                                 <literal>guest</literal>,
 349                                 <literal>auto</literal>. If
 350                                 <literal>no</literal>, the journal is
 351                                 not linked. If <literal>host</literal>,
 352                                 the journal files are stored on the
 353                                 host file system (beneath
 354                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 355                                 and the subdirectory is bind-mounted
 356                                 into the container at the same
 357                                 location. If <literal>guest</literal>,
 358                                 the journal files are stored on the
 359                                 guest file system (beneath
 360                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 361                                 and the subdirectory is symlinked into the host
 362                                 at the same location. If
 363                                 <literal>auto</literal> (the default),
 364                                 and the right subdirectory of
 365                                 <filename>/var/log/journal</filename>
 366                                 exists, it will be bind mounted
 367                                 into the container. If the
 368                                 subdirectory does not exist, no
 369                                 linking is performed. Effectively,
 370                                 booting a container once with
 371                                 <literal>guest</literal> or
 372                                 <literal>host</literal> will link the
 373                                 journal persistently if further on
 374                                 the default of <literal>auto</literal>
 375                                 is used.</para></listitem>
 376                         </varlistentry>
 377
 378                         <varlistentry>
 379                                 <term><option>-j</option></term>
 380
 381                                 <listitem><para>Equivalent to
 382                                 <option>--link-journal=guest</option>.</para></listitem>
 383                         </varlistentry>
 384
 385                         <varlistentry>
 386                                 <term><option>--bind=</option></term>
 387                                 <term><option>--bind-ro=</option></term>
 388
 389                                 <listitem><para>Bind mount a file or
 390                                 directory from the host into the
 391                                 container. Either takes a path
 392                                 argument -- in which case the
 393                                 specified path will be mounted from
 394                                 the host to the same path in the
 395                                 container --, or a colon-separated
 396                                 pair of paths -- in which case the
 397                                 first specified path is the source in
 398                                 the host, and the second path is the
 399                                 destination in the container. The
 400                                 <option>--bind-ro=</option> option
 401                                 creates read-only bind
 402                                 mount.</para></listitem>
 403                         </varlistentry>
 404
 405                         <varlistentry>
 406                                 <term><option>--setenv=</option></term>
 407
 408                                 <listitem><para>Specifies an
 409                                 environment variable assignment to
 410                                 pass to the init process in the
 411                                 container, in the format
 412                                 <literal>NAME=VALUE</literal>. This
 413                                 may be used to override the default
 414                                 variables or to set additional
 415                                 variables. This parameter may be used
 416                                 more than once.</para></listitem>
 417                         </varlistentry>
 418
 419                 </variablelist>
 420
 421         </refsect1>
 422
 423         <refsect1>
 424                 <title>Example 1</title>
 425
 426                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
 427 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 428
 429                 <para>This installs a minimal Fedora distribution into
 430                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
 431                 then boots an OS in a namespace container in
 432                 it.</para>
 433         </refsect1>
 434
 435         <refsect1>
 436                 <title>Example 2</title>
 437
 438                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 439 # systemd-nspawn -D ~/debian-tree/</programlisting>
 440
 441                 <para>This installs a minimal Debian unstable
 442                 distribution into the directory
 443                 <filename>~/debian-tree/</filename> and then spawns a
 444                 shell in a namespace container in it.</para>
 445         </refsect1>
 446
 447         <refsect1>
 448                 <title>Example 3</title>
 449
 450                 <programlisting># pacstrap -c -d ~/arch-tree/ base
 451 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 452
 453                 <para>This installs a mimimal Arch Linux distribution into
 454                 the directory <filename>~/arch-tree/</filename> and then
 455                 boots an OS in a namespace container in it.</para>
 456         </refsect1>
 457
 458         <refsect1>
 459                 <title>Example 4</title>
 460
 461                 <programlisting># mv ~/arch-tree /var/lib/container/arch
 462 # systemctl enable systemd-nspawn@arch.service
 463 # systemctl start systemd-nspawn@arch.service</programlisting>
 464
 465                 <para>This makes the Arch Linux container part of the
 466                 <filename>multi-user.target</filename> on the host.
 467                 </para>
 468         </refsect1>
 469
 470         <refsect1>
 471                 <title>Example 5</title>
 472
 473                 <programlisting># btrfs subvolume snapshot / /.tmp
 474 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
 475
 476                 <para>This runs a copy of the host system in a
 477                 btrfs snapshot.</para>
 478         </refsect1>
 479
 480         <refsect1>
 481                 <title>Example 6</title>
 482
 483                 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 484 # 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>
 485
 486                 <para>This runs a container with SELinux sandbox labels.</para>
 487         </refsect1>
 488
 489         <refsect1>
 490                 <title>Exit status</title>
 491
 492                 <para>The exit code of the program executed in the
 493                 container is returned.</para>
 494         </refsect1>
 495
 496         <refsect1>
 497                 <title>See Also</title>
 498                 <para>
 499                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 500                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 501                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 502                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 503                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 504                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 505                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 506                 </para>
 507         </refsect1>
 508
 509 </refentry>