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