[thirdparty/systemd.git] / man / systemd-nspawn.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd-nspawn">

        <refentryinfo>
                <title>systemd-nspawn</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd-nspawn</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd-nspawn</refname>
                <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <cmdsynopsis>
                        <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
                </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><command>systemd-nspawn</command> may be used to
                run a command or OS in a light-weight namespace
                container. In many ways it is similar to
                <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                but more powerful since it fully virtualizes the file
                system hierarchy, as well as the process tree, the
                various IPC subsystems and the host and domain
                name.</para>

                <para><command>systemd-nspawn</command> limits access
                to various kernel interfaces in the container to
                read-only, such as <filename>/sys</filename>,
                <filename>/proc/sys</filename> or
                <filename>/sys/fs/selinux</filename>. Network
                interfaces and the system clock may not be changed
                from within the container. Device nodes may not be
                created. The host system cannot be rebooted and kernel
                modules may not be loaded from within the
                container.</para>

                <para>Note that even though these security precautions
                are taken <command>systemd-nspawn</command> is not
                suitable for secure container setups. Many of the
                security features may be circumvented and are hence
                primarily useful to avoid accidental changes to the
                host system from the container. The intended use of
                this program is debugging and testing as well as
                building of packages, distributions and software
                involved with boot and systems management.</para>

                <para>In contrast to
                <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                <command>systemd-nspawn</command> may be used to boot
                full Linux-based operating systems in a
                container.</para>

                <para>Use a tool like
                <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                or
                <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                to set up an OS directory tree suitable as file system
                hierarchy for <command>systemd-nspawn</command>
                containers.</para>

                <para>Note that <command>systemd-nspawn</command> will
                mount file systems private to the container to
                <filename>/dev</filename>,
                <filename>/run</filename> and similar. These will
                not be visible outside of the container, and their
                contents will be lost when the container exits.</para>

                <para>Note that running two
                <command>systemd-nspawn</command> containers from the
                same directory tree will not make processes in them
                see each other. The PID namespace separation of the
                two containers is complete and the containers will
                share very few runtime objects except for the
                underlying file system.</para>

                <para><command>systemd-nspawn</command> implements the
                <ulink
                url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
                Interface</ulink> specification.</para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>If no arguments are passed the container is set
                up and a shell started in it, otherwise the passed
                command and arguments are executed in it. The
                following options are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><option>--help</option></term>
                                <term><option>-h</option></term>

                                <listitem><para>Prints a short help
                                text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--directory=</option></term>
                                <term><option>-D</option></term>

                                <listitem><para>Directory to use as
                                file system root for the namespace
                                container. If omitted the current
                                directory will be
                                used.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--boot</option></term>
                                <term><option>-b</option></term>

                                <listitem><para>Automatically search
                                for an init binary and invoke it
                                instead of a shell or a user supplied
                                program.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--user=</option></term>
                                <term><option>-u</option></term>

                                <listitem><para>Run the command
                                under specified user, create home
                                directory and cd into it. As rest
                                of systemd-nspawn, this is not
                                the security feature and limits
                                against accidental changes only.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--uuid=</option></term>

                                <listitem><para>Set the specified uuid
                                for the container. The init system
                                will initialize
                                <filename>/etc/machine-id</filename>
                                from this if this file is not set yet.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--controllers=</option></term>
                                <term><option>-C</option></term>

                                <listitem><para>Makes the container appear in
                                other hierarchies that the name=systemd:/ one.
                                Takes a comma-separated list of controllers.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--private-network</option></term>

                                <listitem><para>Turn off networking in
                                the container. This makes all network
                                interfaces unavailable in the
                                container, with the exception of the
                                loopback device.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--read-only</option></term>

                                <listitem><para>Mount the root file
                                system read only for the
                                container.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--capability=</option></term>

                                <listitem><para>List one or more
                                additional capabilities to grant the
                                container. Takes a comma separated
                                list of capability names, see
                                <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                for more information. Note that the
                                the following capabilities will be
                                granted in any way: CAP_CHOWN,
                                CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
                                CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
                                CAP_KILL, CAP_LEASE,
                                CAP_LINUX_IMMUTABLE,
                                CAP_NET_BIND_SERVICE,
                                CAP_NET_BROADCAST, CAP_NET_RAW,
                                CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
                                CAP_SETUID, CAP_SYS_ADMIN,
                                CAP_SYS_CHROOT, CAP_SYS_NICE,
                                CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
                                CAP_SYS_RESOURCE.</para></listitem>
                        </varlistentry>

                </variablelist>

        </refsect1>

        <refsect1>
                <title>Example 1</title>

                <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>

                <para>This installs a minimal Fedora distribution into
                the directory <filename>~/fedora-tree/</filename>
                and then boots an OS in a namespace container in it,
                with systemd as init system.</para>
        </refsect1>

        <refsect1>
                <title>Example 2</title>

                <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
# systemd-nspawn -D ~/debian-tree/</programlisting>

                <para>This installs a minimal Debian unstable
                distribution into the directory
                <filename>~/debian-tree/</filename> and then spawns a
                shell in a namespace container in it.</para>

        </refsect1>

        <refsect1>
                <title>Exit status</title>

                <para>The exit code of the program executed in the
                container is returned.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
8f7a3c14 LP	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
5430f7f2 LP	11	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	12	the Free Software Foundation; either version 2.1 of the License, or
8f7a3c14 LP	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
5430f7f2	18	Lesser General Public License for more details.
8f7a3c14	19
5430f7f2	20	You should have received a copy of the GNU Lesser General Public License
8f7a3c14 LP	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
9f7dad77	64	system hierarchy, as well as the process tree, the
8f7a3c14 LP	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
4f755fc6 LP	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>
8f7a3c14 LP	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
25f5971b LP	96	<citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	97	or
	98	<citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c14	99	to set up an OS directory tree suitable as file system
25f5971b LP	100	hierarchy for <command>systemd-nspawn</command>
25f5971b LP	101	containers.</para>
8f7a3c14 LP	102
	103	<para>Note that <command>systemd-nspawn</command> will
	104	mount file systems private to the container to
	105	<filename>/dev</filename>,
2b583ce6	106	<filename>/run</filename> and similar. These will
8f7a3c14 LP	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
9f7dad77	113	see each other. The PID namespace separation of the
8f7a3c14 LP	114	two containers is complete and the containers will
	115	share very few runtime objects except for the
	116	underlying file system.</para>
99800333 LP	117
	118	<para><command>systemd-nspawn</command> implements the
	119	<ulink
	120	url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
	121	Interface</ulink> specification.</para>
8f7a3c14 LP	122	</refsect1>
	123
	124	<refsect1>
	125	<title>Options</title>
	126
	127	<para>If no arguments are passed the container is set
	128	up and a shell started in it, otherwise the passed
	129	command and arguments are executed in it. The
	130	following options are understood:</para>
	131
	132	<variablelist>
	133	<varlistentry>
	134	<term><option>--help</option></term>
a41fe3a2	135	<term><option>-h</option></term>
8f7a3c14 LP	136
	137	<listitem><para>Prints a short help
	138	text and exits.</para></listitem>
	139	</varlistentry>
	140
	141	<varlistentry>
	142	<term><option>--directory=</option></term>
ab1f0633	143	<term><option>-D</option></term>
8f7a3c14 LP	144
	145	<listitem><para>Directory to use as
	146	file system root for the namespace
	147	container. If omitted the current
	148	directory will be
	149	used.</para></listitem>
	150	</varlistentry>
	151
0f0dbc46 LP	152	<varlistentry>
	153	<term><option>--boot</option></term>
	154	<term><option>-b</option></term>
	155
	156	<listitem><para>Automatically search
	157	for an init binary and invoke it
	158	instead of a shell or a user supplied
	159	program.</para></listitem>
	160	</varlistentry>
	161
687d0825 MV	162	<varlistentry>
687d0825 MV	163	<term><option>--user=</option></term>
4f755fc6	164	<term><option>-u</option></term>
687d0825 MV	165
	166	<listitem><para>Run the command
	167	under specified user, create home
	168	directory and cd into it. As rest
	169	of systemd-nspawn, this is not
	170	the security feature and limits
	171	against accidental changes only.
	172	</para></listitem>
	173	</varlistentry>
	174
144f0fc0 LP	175	<varlistentry>
	176	<term><option>--uuid=</option></term>
	177
	178	<listitem><para>Set the specified uuid
	179	for the container. The init system
	180	will initialize
	181	<filename>/etc/machine-id</filename>
	182	from this if this file is not set yet.
	183	</para></listitem>
	184	</varlistentry>
	185
40c32a4a LGL	186	<varlistentry>
	187	<term><option>--controllers=</option></term>
	188	<term><option>-C</option></term>
	189
	190	<listitem><para>Makes the container appear in
	191	other hierarchies that the name=systemd:/ one.
	192	Takes a comma-separated list of controllers.
	193	</para></listitem>
	194	</varlistentry>
	195
a41fe3a2	196	<varlistentry>
ff01d048	197	<term><option>--private-network</option></term>
a41fe3a2 LP	198
	199	<listitem><para>Turn off networking in
	200	the container. This makes all network
	201	interfaces unavailable in the
	202	container, with the exception of the
	203	loopback device.</para></listitem>
	204	</varlistentry>
	205
bc2f673e LP	206	<varlistentry>
	207	<term><option>--read-only</option></term>
	208
	209	<listitem><para>Mount the root file
	210	system read only for the
	211	container.</para></listitem>
	212	</varlistentry>
	213
5076f0cc LP	214	<varlistentry>
	215	<term><option>--capability=</option></term>
	216
	217	<listitem><para>List one or more
	218	additional capabilities to grant the
	219	container. Takes a comma separated
	220	list of capability names, see
	221	<citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
	222	for more information. Note that the
	223	the following capabilities will be
	224	granted in any way: CAP_CHOWN,
	225	CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
	226	CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
	227	CAP_KILL, CAP_LEASE,
	228	CAP_LINUX_IMMUTABLE,
	229	CAP_NET_BIND_SERVICE,
	230	CAP_NET_BROADCAST, CAP_NET_RAW,
	231	CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
	232	CAP_SETUID, CAP_SYS_ADMIN,
	233	CAP_SYS_CHROOT, CAP_SYS_NICE,
	234	CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
	235	CAP_SYS_RESOURCE.</para></listitem>
	236	</varlistentry>
	237
8f7a3c14 LP	238	</variablelist>
	239
	240	</refsect1>
	241
	242	<refsect1>
	243	<title>Example 1</title>
	244
25f5971b LP	245	<programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
25f5971b LP	246	# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>
8f7a3c14	247
25f5971b LP	248	<para>This installs a minimal Fedora distribution into
	249	the directory <filename>~/fedora-tree/</filename>
	250	and then boots an OS in a namespace container in it,
	251	with systemd as init system.</para>
8f7a3c14 LP	252	</refsect1>
	253
	254	<refsect1>
	255	<title>Example 2</title>
	256
25f5971b LP	257	<programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
25f5971b LP	258	# systemd-nspawn -D ~/debian-tree/</programlisting>
8f7a3c14	259
25f5971b LP	260	<para>This installs a minimal Debian unstable
	261	distribution into the directory
	262	<filename>~/debian-tree/</filename> and then spawns a
	263	shell in a namespace container in it.</para>
8f7a3c14 LP	264
	265	</refsect1>
	266
	267	<refsect1>
	268	<title>Exit status</title>
	269
	270	<para>The exit code of the program executed in the
	271	container is returned.</para>
	272	</refsect1>
	273
	274	<refsect1>
	275	<title>See Also</title>
	276	<para>
	277	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	278	<citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
25f5971b LP	279	<citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
25f5971b LP	280	<citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c14 LP	281	</para>
	282	</refsect1>
	283
	284	</refentry>