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>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  97                 to set up an OS directory tree suitable as file system
  98                 hierarchy for <command>systemd-nspawn</command> containers.</para>
  99
 100                 <para>Note that <command>systemd-nspawn</command> will
 101                 mount file systems private to the container to
 102                 <filename>/dev</filename>,
 103                 <filename>/run</filename> and similar. These will
 104                 not be visible outside of the container, and their
 105                 contents will be lost when the container exits.</para>
 106
 107                 <para>Note that running two
 108                 <command>systemd-nspawn</command> containers from the
 109                 same directory tree will not make processes in them
 110                 see each other. The PID namespace separation of the
 111                 two containers is complete and the containers will
 112                 share very few runtime objects except for the
 113                 underlying file system.</para>
 114         </refsect1>
 115
 116         <refsect1>
 117                 <title>Options</title>
 118
 119                 <para>If no arguments are passed the container is set
 120                 up and a shell started in it, otherwise the passed
 121                 command and arguments are executed in it. The
 122                 following options are understood:</para>
 123
 124                 <variablelist>
 125                         <varlistentry>
 126                                 <term><option>--help</option></term>
 127                                 <term><option>-h</option></term>
 128
 129                                 <listitem><para>Prints a short help
 130                                 text and exits.</para></listitem>
 131                         </varlistentry>
 132
 133                         <varlistentry>
 134                                 <term><option>--directory=</option></term>
 135                                 <term><option>-D</option></term>
 136
 137                                 <listitem><para>Directory to use as
 138                                 file system root for the namespace
 139                                 container. If omitted the current
 140                                 directory will be
 141                                 used.</para></listitem>
 142                         </varlistentry>
 143
 144                         <varlistentry>
 145                                 <term><option>--boot</option></term>
 146                                 <term><option>-b</option></term>
 147
 148                                 <listitem><para>Automatically search
 149                                 for an init binary and invoke it
 150                                 instead of a shell or a user supplied
 151                                 program.</para></listitem>
 152                         </varlistentry>
 153
 154                         <varlistentry>
 155                                 <term><option>--user=</option></term>
 156                                 <term><option>-u</option></term>
 157
 158                                 <listitem><para>Run the command
 159                                 under specified user, create home
 160                                 directory and cd into it. As rest
 161                                 of systemd-nspawn, this is not
 162                                 the security feature and limits
 163                                 against accidental changes only.
 164                                 </para></listitem>
 165                         </varlistentry>
 166
 167                         <varlistentry>
 168                                 <term><option>--uuid=</option></term>
 169
 170                                 <listitem><para>Set the specified uuid
 171                                 for the container. The init system
 172                                 will initialize
 173                                 <filename>/etc/machine-id</filename>
 174                                 from this if this file is not set yet.
 175                                 </para></listitem>
 176                         </varlistentry>
 177
 178                         <varlistentry>
 179                                 <term><option>--controllers=</option></term>
 180                                 <term><option>-C</option></term>
 181
 182                                 <listitem><para>Makes the container appear in
 183                                 other hierarchies that the name=systemd:/ one.
 184                                 Takes a comma-separated list of controllers.
 185                                 </para></listitem>
 186                         </varlistentry>
 187
 188                         <varlistentry>
 189                                 <term><option>--private-network</option></term>
 190
 191                                 <listitem><para>Turn off networking in
 192                                 the container. This makes all network
 193                                 interfaces unavailable in the
 194                                 container, with the exception of the
 195                                 loopback device.</para></listitem>
 196                         </varlistentry>
 197
 198                 </variablelist>
 199
 200         </refsect1>
 201
 202         <refsect1>
 203                 <title>Example 1</title>
 204
 205                 <programlisting># debootstrap --arch=amd64 unstable debian-tree/
 206 # systemd-nspawn -D debian-tree/</programlisting>
 207
 208                 <para>This installs a minimal Debian unstable
 209                 distribution into the directory
 210                 <filename>debian-tree/</filename> and then spawns a
 211                 shell in a namespace container in it.</para>
 212
 213         </refsect1>
 214
 215         <refsect1>
 216                 <title>Example 2</title>
 217
 218                 <programlisting># mock --init
 219 # systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /sbin/init systemd.log_level=debug</programlisting>
 220
 221                 <para>This installs a minimal Fedora distribution into
 222                 a subdirectory of <filename>/var/lib/mock/</filename>
 223                 and then boots an OS in a namespace container in it,
 224                 with systemd as init system, configured for debug
 225                 logging.</para>
 226
 227         </refsect1>
 228
 229         <refsect1>
 230                 <title>Exit status</title>
 231
 232                 <para>The exit code of the program executed in the
 233                 container is returned.</para>
 234         </refsect1>
 235
 236         <refsect1>
 237                 <title>See Also</title>
 238                 <para>
 239                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 240                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 241                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 242                         <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 243                 </para>
 244         </refsect1>
 245
 246 </refentry>