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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
  53                 </cmdsynopsis>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>systemd-nspawn</command> may be used to
  60                 run a command or OS in a light-weight namespace
  61                 container. In many ways it is similar to
  62                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  63                 but more powerful since it fully virtualizes the file
  64                 system hierarchy, as well as the process tree, the
  65                 various IPC subsystems and the host and domain
  66                 name.</para>
  67
  68                 <para><command>systemd-nspawn</command> limits access
  69                 to various kernel interfaces in the container to
  70                 read-only, such as <filename>/sys</filename>,
  71                 <filename>/proc/sys</filename> or
  72                 <filename>/sys/fs/selinux</filename>. Network
  73                 interfaces and the system clock may not be changed
  74                 from within the container. Device nodes may not be
  75                 created. The host system cannot be rebooted and kernel
  76                 modules may not be loaded from within the
  77                 container.</para>
  78
  79                 <para>Note that even though these security precautions
  80                 are taken <command>systemd-nspawn</command> is not
  81                 suitable for secure container setups. Many of the
  82                 security features may be circumvented and are hence
  83                 primarily useful to avoid accidental changes to the
  84                 host system from the container. The intended use of
  85                 this program is debugging and testing as well as
  86                 building of packages, distributions and software
  87                 involved with boot and systems management.</para>
  88
  89                 <para>In contrast to
  90                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  91                 <command>systemd-nspawn</command> may be used to boot
  92                 full Linux-based operating systems in a
  93                 container.</para>
  94
  95                 <para>Use a tool like
  96                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  97                 or
  98                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  99                 to set up an OS directory tree suitable as file system
 100                 hierarchy for <command>systemd-nspawn</command>
 101                 containers.</para>
 102
 103                 <para>Note that <command>systemd-nspawn</command> will
 104                 mount file systems private to the container to
 105                 <filename>/dev</filename>,
 106                 <filename>/run</filename> and similar. These will
 107                 not be visible outside of the container, and their
 108                 contents will be lost when the container exits.</para>
 109
 110                 <para>Note that running two
 111                 <command>systemd-nspawn</command> containers from the
 112                 same directory tree will not make processes in them
 113                 see each other. The PID namespace separation of the
 114                 two containers is complete and the containers will
 115                 share very few runtime objects except for the
 116                 underlying file system.</para>
 117         </refsect1>
 118
 119         <refsect1>
 120                 <title>Options</title>
 121
 122                 <para>If no arguments are passed the container is set
 123                 up and a shell started in it, otherwise the passed
 124                 command and arguments are executed in it. The
 125                 following options are understood:</para>
 126
 127                 <variablelist>
 128                         <varlistentry>
 129                                 <term><option>--help</option></term>
 130                                 <term><option>-h</option></term>
 131
 132                                 <listitem><para>Prints a short help
 133                                 text and exits.</para></listitem>
 134                         </varlistentry>
 135
 136                         <varlistentry>
 137                                 <term><option>--directory=</option></term>
 138                                 <term><option>-D</option></term>
 139
 140                                 <listitem><para>Directory to use as
 141                                 file system root for the namespace
 142                                 container. If omitted the current
 143                                 directory will be
 144                                 used.</para></listitem>
 145                         </varlistentry>
 146
 147                         <varlistentry>
 148                                 <term><option>--boot</option></term>
 149                                 <term><option>-b</option></term>
 150
 151                                 <listitem><para>Automatically search
 152                                 for an init binary and invoke it
 153                                 instead of a shell or a user supplied
 154                                 program.</para></listitem>
 155                         </varlistentry>
 156
 157                         <varlistentry>
 158                                 <term><option>--user=</option></term>
 159                                 <term><option>-u</option></term>
 160
 161                                 <listitem><para>Run the command
 162                                 under specified user, create home
 163                                 directory and cd into it. As rest
 164                                 of systemd-nspawn, this is not
 165                                 the security feature and limits
 166                                 against accidental changes only.
 167                                 </para></listitem>
 168                         </varlistentry>
 169
 170                         <varlistentry>
 171                                 <term><option>--uuid=</option></term>
 172
 173                                 <listitem><para>Set the specified uuid
 174                                 for the container. The init system
 175                                 will initialize
 176                                 <filename>/etc/machine-id</filename>
 177                                 from this if this file is not set yet.
 178                                 </para></listitem>
 179                         </varlistentry>
 180
 181                         <varlistentry>
 182                                 <term><option>--controllers=</option></term>
 183                                 <term><option>-C</option></term>
 184
 185                                 <listitem><para>Makes the container appear in
 186                                 other hierarchies that the name=systemd:/ one.
 187                                 Takes a comma-separated list of controllers.
 188                                 </para></listitem>
 189                         </varlistentry>
 190
 191                         <varlistentry>
 192                                 <term><option>--private-network</option></term>
 193
 194                                 <listitem><para>Turn off networking in
 195                                 the container. This makes all network
 196                                 interfaces unavailable in the
 197                                 container, with the exception of the
 198                                 loopback device.</para></listitem>
 199                         </varlistentry>
 200
 201                         <varlistentry>
 202                                 <term><option>--read-only</option></term>
 203
 204                                 <listitem><para>Mount the root file
 205                                 system read only for the
 206                                 container.</para></listitem>
 207                         </varlistentry>
 208
 209                         <varlistentry>
 210                                 <term><option>--capability=</option></term>
 211
 212                                 <listitem><para>List one or more
 213                                 additional capabilities to grant the
 214                                 container. Takes a comma separated
 215                                 list of capability names, see
 216                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 217                                 for more information. Note that the
 218                                 the following capabilities will be
 219                                 granted in any way: CAP_CHOWN,
 220                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 221                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 222                                 CAP_KILL, CAP_LEASE,
 223                                 CAP_LINUX_IMMUTABLE,
 224                                 CAP_NET_BIND_SERVICE,
 225                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 226                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 227                                 CAP_SETUID, CAP_SYS_ADMIN,
 228                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 229                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 230                                 CAP_SYS_RESOURCE.</para></listitem>
 231                         </varlistentry>
 232
 233                 </variablelist>
 234
 235         </refsect1>
 236
 237         <refsect1>
 238                 <title>Example 1</title>
 239
 240                 <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
 241 # systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>
 242
 243                 <para>This installs a minimal Fedora distribution into
 244                 the directory <filename>~/fedora-tree/</filename>
 245                 and then boots an OS in a namespace container in it,
 246                 with systemd as init system.</para>
 247         </refsect1>
 248
 249         <refsect1>
 250                 <title>Example 2</title>
 251
 252                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 253 # systemd-nspawn -D ~/debian-tree/</programlisting>
 254
 255                 <para>This installs a minimal Debian unstable
 256                 distribution into the directory
 257                 <filename>~/debian-tree/</filename> and then spawns a
 258                 shell in a namespace container in it.</para>
 259
 260         </refsect1>
 261
 262         <refsect1>
 263                 <title>Exit status</title>
 264
 265                 <para>The exit code of the program executed in the
 266                 container is returned.</para>
 267         </refsect1>
 268
 269         <refsect1>
 270                 <title>See Also</title>
 271                 <para>
 272                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 273                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 274                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 275                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 276                 </para>
 277         </refsect1>
 278
 279 </refentry>