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