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