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