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>-D</option></term>
 178                                 <term><option>--directory=</option></term>
 179
 180                                 <listitem><para>Directory to use as
 181                                 file system root for the namespace
 182                                 container. If omitted, the current
 183                                 directory will be
 184                                 used.</para></listitem>
 185                         </varlistentry>
 186
 187                         <varlistentry>
 188                                 <term><option>-b</option></term>
 189                                 <term><option>--boot</option></term>
 190
 191                                 <listitem><para>Automatically search
 192                                 for an init binary and invoke it
 193                                 instead of a shell or a user supplied
 194                                 program. If this option is used,
 195                                 arguments specified on the command
 196                                 line are used as arguments for the
 197                                 init binary. This option may not be
 198                                 combined with
 199                                 <option>--share-system</option>.
 200                                 </para></listitem>
 201                         </varlistentry>
 202
 203                         <varlistentry>
 204                                 <term><option>-u</option></term>
 205                                 <term><option>--user=</option></term>
 206
 207                                 <listitem><para>Run the command
 208                                 under specified user, create home
 209                                 directory and cd into it. As rest
 210                                 of systemd-nspawn, this is not
 211                                 the security feature and limits
 212                                 against accidental changes only.
 213                                 </para></listitem>
 214                         </varlistentry>
 215
 216                         <varlistentry>
 217                                 <term><option>-M</option></term>
 218                                 <term><option>--machine=</option></term>
 219
 220                                 <listitem><para>Sets the machine name
 221                                 for this container. This name may be
 222                                 used to identify this container on the
 223                                 host, and is used to initialize the
 224                                 container's hostname (which the
 225                                 container can choose to override,
 226                                 however). If not specified, the last
 227                                 component of the root directory of the
 228                                 container is used.</para></listitem>
 229                         </varlistentry>
 230
 231                         <varlistentry>
 232                                 <term><option>--slice=</option></term>
 233
 234                                 <listitem><para>Make the container
 235                                 part of the specified slice, instead
 236                                 of the
 237                                 <filename>machine.slice</filename>.</para>
 238                                 </listitem>
 239                         </varlistentry>
 240
 241                         <varlistentry>
 242                                 <term><option>-Z</option></term>
 243                                 <term><option>--selinux-context=</option></term>
 244
 245                                 <listitem><para>Sets the SELinux
 246                                 security context to be used to label
 247                                 processes in the container.</para>
 248                                 </listitem>
 249                         </varlistentry>
 250
 251                         <varlistentry>
 252                                 <term><option>-L</option></term>
 253                                 <term><option>--selinux-apifs-context=</option></term>
 254
 255                                 <listitem><para>Sets the SELinux security
 256                                 context to be used to label files in
 257                                 the virtual API file systems in the
 258                                 container.</para>
 259                                 </listitem>
 260                         </varlistentry>
 261
 262                         <varlistentry>
 263                                 <term><option>--uuid=</option></term>
 264
 265                                 <listitem><para>Set the specified UUID
 266                                 for the container. The init system
 267                                 will initialize
 268                                 <filename>/etc/machine-id</filename>
 269                                 from this if this file is not set yet.
 270                                 </para></listitem>
 271                         </varlistentry>
 272
 273                         <varlistentry>
 274                                 <term><option>--private-network</option></term>
 275
 276                                 <listitem><para>Turn off networking in
 277                                 the container. This makes all network
 278                                 interfaces unavailable in the
 279                                 container, with the exception of the
 280                                 loopback device.</para></listitem>
 281                         </varlistentry>
 282
 283                         <varlistentry>
 284                                 <term><option>--read-only</option></term>
 285
 286                                 <listitem><para>Mount the root file
 287                                 system read-only for the
 288                                 container.</para></listitem>
 289                         </varlistentry>
 290
 291                         <varlistentry>
 292                                 <term><option>--capability=</option></term>
 293
 294                                 <listitem><para>List one or more
 295                                 additional capabilities to grant the
 296                                 container. Takes a comma-separated
 297                                 list of capability names, see
 298                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 299                                 for more information. Note that the
 300                                 following capabilities will be granted
 301                                 in any way: CAP_CHOWN,
 302                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 303                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 304                                 CAP_KILL, CAP_LEASE,
 305                                 CAP_LINUX_IMMUTABLE,
 306                                 CAP_NET_BIND_SERVICE,
 307                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 308                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 309                                 CAP_SETUID, CAP_SYS_ADMIN,
 310                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 311                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 312                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 313                                 CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. If
 314                                 the special value
 315                                 <literal>all</literal> is passed all
 316                                 capabilities are
 317                                 retained.</para></listitem>
 318                         </varlistentry>
 319
 320                         <varlistentry>
 321                                 <term><option>--drop-capability=</option></term>
 322
 323                                 <listitem><para>Specify one or more
 324                                 additional capabilities to drop for
 325                                 the container. This allows running the
 326                                 container with fewer capabilities than
 327                                 the default (see above).</para></listitem>
 328                         </varlistentry>
 329
 330                         <varlistentry>
 331                                 <term><option>--link-journal=</option></term>
 332
 333                                 <listitem><para>Control whether the
 334                                 container's journal shall be made
 335                                 visible to the host system. If enabled,
 336                                 allows viewing the container's journal
 337                                 files from the host (but not vice
 338                                 versa). Takes one of
 339                                 <literal>no</literal>,
 340                                 <literal>host</literal>,
 341                                 <literal>guest</literal>,
 342                                 <literal>auto</literal>. If
 343                                 <literal>no</literal>, the journal is
 344                                 not linked. If <literal>host</literal>,
 345                                 the journal files are stored on the
 346                                 host file system (beneath
 347                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 348                                 and the subdirectory is bind-mounted
 349                                 into the container at the same
 350                                 location. If <literal>guest</literal>,
 351                                 the journal files are stored on the
 352                                 guest file system (beneath
 353                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 354                                 and the subdirectory is symlinked into the host
 355                                 at the same location. If
 356                                 <literal>auto</literal> (the default),
 357                                 and the right subdirectory of
 358                                 <filename>/var/log/journal</filename>
 359                                 exists, it will be bind mounted
 360                                 into the container. If the
 361                                 subdirectory does not exist, no
 362                                 linking is performed. Effectively,
 363                                 booting a container once with
 364                                 <literal>guest</literal> or
 365                                 <literal>host</literal> will link the
 366                                 journal persistently if further on
 367                                 the default of <literal>auto</literal>
 368                                 is used.</para></listitem>
 369                         </varlistentry>
 370
 371                         <varlistentry>
 372                                 <term><option>-j</option></term>
 373
 374                                 <listitem><para>Equivalent to
 375                                 <option>--link-journal=guest</option>.</para></listitem>
 376                         </varlistentry>
 377
 378                         <varlistentry>
 379                                 <term><option>--bind=</option></term>
 380                                 <term><option>--bind-ro=</option></term>
 381
 382                                 <listitem><para>Bind mount a file or
 383                                 directory from the host into the
 384                                 container. Either takes a path
 385                                 argument -- in which case the
 386                                 specified path will be mounted from
 387                                 the host to the same path in the
 388                                 container --, or a colon-separated
 389                                 pair of paths -- in which case the
 390                                 first specified path is the source in
 391                                 the host, and the second path is the
 392                                 destination in the container. The
 393                                 <option>--bind-ro=</option> option
 394                                 creates read-only bind
 395                                 mount.</para></listitem>
 396                         </varlistentry>
 397
 398                         <varlistentry>
 399                                 <term><option>--setenv=</option></term>
 400
 401                                 <listitem><para>Specifies an
 402                                 environment variable assignment to
 403                                 pass to the init process in the
 404                                 container, in the format
 405                                 <literal>NAME=VALUE</literal>. This
 406                                 may be used to override the default
 407                                 variables or to set additional
 408                                 variables. This parameter may be used
 409                                 more than once.</para></listitem>
 410                         </varlistentry>
 411
 412                         <varlistentry>
 413                                 <term><option>-q</option></term>
 414                                 <term><option>--quiet</option></term>
 415
 416                                 <listitem><para>Turns off any status
 417                                 output by the tool itself. When this
 418                                 switch is used, then the only output
 419                                 by nspawn will be the console output
 420                                 of the container OS itself.</para></listitem>
 421                         </varlistentry>
 422
 423                         <varlistentry>
 424                                 <term><option>--share-system</option></term>
 425
 426                                 <listitem><para>Allows the container
 427                                 to share certain system facilities
 428                                 with the host. More specifically, this
 429                                 turns off PID namespacing, UTS
 430                                 namespacing and IPC namespacing, and
 431                                 thus allows the guest to see and
 432                                 interact more easily with processes
 433                                 outside of the container. Note that
 434                                 using this option makes it impossible
 435                                 to start up a full Operating System in
 436                                 the container, as an init system
 437                                 cannot operate in this mode. It is
 438                                 only useful to run specific programs
 439                                 or applications this way, without
 440                                 involving an init system in the
 441                                 container. This option implies
 442                                 <option>--register=no</option>. This
 443                                 option may not be combined with
 444                                 <option>--boot</option>.</para></listitem>
 445                         </varlistentry>
 446
 447                         <varlistentry>
 448                                 <term><option>--register=</option></term>
 449
 450                                 <listitem><para>Controls whether the
 451                                 container is registered with
 452                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
 453                                 a boolean argument, defaults to
 454                                 <literal>yes</literal>. This option
 455                                 should be enabled when the container
 456                                 runs a full Operating System (more
 457                                 specifically: an init system), and is
 458                                 useful to ensure that the container is
 459                                 accessible via
 460                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 461                                 and shown by tools such as
 462                                 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
 463                                 the container does not run an init
 464                                 system it is recommended to set this
 465                                 option to <literal>no</literal>. Note
 466                                 that <option>--share-system</option>
 467                                 implies
 468                                 <option>--register=no</option>.
 469                                 </para></listitem>
 470                         </varlistentry>
 471
 472                         <varlistentry>
 473                                 <term><option>--keep-unit</option></term>
 474
 475                                 <listitem><para>Instead of creating a
 476                                 transient scope unit to run the
 477                                 container in, simply register the
 478                                 service or scope unit
 479                                 <command>systemd-nspawn</command> has
 480                                 been invoked in in
 481                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
 482                                 has no effect if
 483                                 <option>--register=no</option> is
 484                                 used. This switch should be used if
 485                                 <command>systemd-nspawn</command> is
 486                                 invoked from within an a service unit,
 487                                 and the service unit's sole purpose
 488                                 is to run a single
 489                                 <command>systemd-nspawn</command>
 490                                 container. This option is not
 491                                 available if run from a user
 492                                 session.</para></listitem>
 493                         </varlistentry>
 494
 495                 </variablelist>
 496
 497         </refsect1>
 498
 499         <refsect1>
 500                 <title>Example 1</title>
 501
 502                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
 503 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 504
 505                 <para>This installs a minimal Fedora distribution into
 506                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
 507                 then boots an OS in a namespace container in
 508                 it.</para>
 509         </refsect1>
 510
 511         <refsect1>
 512                 <title>Example 2</title>
 513
 514                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 515 # systemd-nspawn -D ~/debian-tree/</programlisting>
 516
 517                 <para>This installs a minimal Debian unstable
 518                 distribution into the directory
 519                 <filename>~/debian-tree/</filename> and then spawns a
 520                 shell in a namespace container in it.</para>
 521         </refsect1>
 522
 523         <refsect1>
 524                 <title>Example 3</title>
 525
 526                 <programlisting># pacstrap -c -d ~/arch-tree/ base
 527 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 528
 529                 <para>This installs a mimimal Arch Linux distribution into
 530                 the directory <filename>~/arch-tree/</filename> and then
 531                 boots an OS in a namespace container in it.</para>
 532         </refsect1>
 533
 534         <refsect1>
 535                 <title>Example 4</title>
 536
 537                 <programlisting># mv ~/arch-tree /var/lib/container/arch
 538 # systemctl enable systemd-nspawn@arch.service
 539 # systemctl start systemd-nspawn@arch.service</programlisting>
 540
 541                 <para>This makes the Arch Linux container part of the
 542                 <filename>multi-user.target</filename> on the host.
 543                 </para>
 544         </refsect1>
 545
 546         <refsect1>
 547                 <title>Example 5</title>
 548
 549                 <programlisting># btrfs subvolume snapshot / /.tmp
 550 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
 551
 552                 <para>This runs a copy of the host system in a
 553                 btrfs snapshot.</para>
 554         </refsect1>
 555
 556         <refsect1>
 557                 <title>Example 6</title>
 558
 559                 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 560 # 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>
 561
 562                 <para>This runs a container with SELinux sandbox security contexts.</para>
 563         </refsect1>
 564
 565         <refsect1>
 566                 <title>Exit status</title>
 567
 568                 <para>The exit code of the program executed in the
 569                 container is returned.</para>
 570         </refsect1>
 571
 572         <refsect1>
 573                 <title>See Also</title>
 574                 <para>
 575                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 576                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 577                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 578                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 579                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 580                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 581                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 582                 </para>
 583         </refsect1>
 584
 585 </refentry>