[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</command>
                        <arg choice="opt" rep="repeat">OPTIONS</arg>
                        <arg choice="opt">COMMAND</arg>
                        <arg choice="opt" rep="repeat">ARGS</arg>
                </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>,
                <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                or
                <citerefentry><refentrytitle>pacman</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. It is however possible to
                enter an existing container, see
                <link linkend='example-nsenter'>Example 4</link> below.
                </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>-h</option></term>
                                <term><option>--help</option></term>

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

                        <varlistentry>
                                <term><option>--version</option></term>

                                <listitem><para>Prints a version string
                                and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-D</option></term>
                                <term><option>--directory=</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>-b</option></term>
                                <term><option>--boot</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>-u</option></term>
                                <term><option>--user=</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>-C</option></term>
                                <term><option>--controllers=</option></term>

                                <listitem><para>Makes the container appear in
                                other hierarchies than 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
                                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, CAP_SYS_BOOT,
                                CAP_AUDIT_WRITE,
                                CAP_AUDIT_CONTROL.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--link-journal=</option></term>

                                <listitem><para>Control whether the
                                container's journal shall be made
                                visible to the host system. If enabled
                                allows viewing the container's journal
                                files from the host (but not vice
                                versa). Takes one of
                                <literal>no</literal>,
                                <literal>host</literal>,
                                <literal>guest</literal>,
                                <literal>auto</literal>. If
                                <literal>no</literal>, the journal is
                                not linked. If <literal>host</literal>,
                                the journal files are stored on the
                                host file system (beneath
                                <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
                                and the subdirectory is bind-mounted
                                into the container at the same
                                location. If <literal>guest</literal>,
                                the journal files are stored on the
                                guest file system (beneath
                                <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
                                and the subdirectory is symlinked into the host
                                at the same location. If
                                <literal>auto</literal> (the default),
                                and the right subdirectory of
                                <filename>/var/log/journal</filename>
                                exists, it will be bind mounted
                                into the container. If the
                                subdirectory doesn't exist, no
                                linking is performed. Effectively,
                                booting a container once with
                                <literal>guest</literal> or
                                <literal>host</literal> will link the
                                journal persistently if further on
                                the default of <literal>auto</literal>
                                is used.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-j</option></term>

                                <listitem><para>Equivalent to
                                <option>--link-journal=guest</option>.</para></listitem>
                        </varlistentry>
                </variablelist>

        </refsect1>

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

                <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
# systemd-nspawn -bD /srv/mycontainer</programlisting>

                <para>This installs a minimal Fedora distribution into
                the directory <filename>/srv/mycontainer/</filename> and
                then boots an OS in a namespace container in
                it.</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>Example 3</title>

                <programlisting># pacstrap -c -d ~/arch-tree/ base
# systemd-nspawn -bD ~/arch-tree/</programlisting>

                <para>This installs a mimimal Arch Linux distribution into
                the directory <filename>~/arch-tree/</filename> and then
                boots an OS in a namespace container in it.</para>
        </refsect1>

        <refsect1 id='example-nsenter'>
                <title>Example 4</title>

                <para>To enter the container, PID of one of the
                processes sharing the new namespaces must be used.
                <command>systemd-nspawn</command> prints the PID
                (as viewed from the outside) of the launched process,
                and it can be used to enter the container.</para>

                <programlisting># nsenter -muinpt $PID</programlisting>

                <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                is part of
                <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
                Kernel support for entering namespaces was added in
                Linux 3.8.</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>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>pacman</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>
1fd96121 ZJS	52	<command>systemd-nspawn</command>
	53	<arg choice="opt" rep="repeat">OPTIONS</arg>
	54	<arg choice="opt">COMMAND</arg>
	55	<arg choice="opt" rep="repeat">ARGS</arg>
8f7a3c14 LP	56	</cmdsynopsis>
	57	</refsynopsisdiv>
	58
	59	<refsect1>
	60	<title>Description</title>
	61
	62	<para><command>systemd-nspawn</command> may be used to
	63	run a command or OS in a light-weight namespace
	64	container. In many ways it is similar to
	65	<citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	66	but more powerful since it fully virtualizes the file
9f7dad77	67	system hierarchy, as well as the process tree, the
8f7a3c14 LP	68	various IPC subsystems and the host and domain
	69	name.</para>
	70
	71	<para><command>systemd-nspawn</command> limits access
	72	to various kernel interfaces in the container to
	73	read-only, such as <filename>/sys</filename>,
	74	<filename>/proc/sys</filename> or
4f755fc6 LP	75	<filename>/sys/fs/selinux</filename>. Network
	76	interfaces and the system clock may not be changed
	77	from within the container. Device nodes may not be
	78	created. The host system cannot be rebooted and kernel
	79	modules may not be loaded from within the
	80	container.</para>
8f7a3c14 LP	81
	82	<para>Note that even though these security precautions
	83	are taken <command>systemd-nspawn</command> is not
	84	suitable for secure container setups. Many of the
	85	security features may be circumvented and are hence
	86	primarily useful to avoid accidental changes to the
	87	host system from the container. The intended use of
	88	this program is debugging and testing as well as
	89	building of packages, distributions and software
	90	involved with boot and systems management.</para>
	91
	92	<para>In contrast to
	93	<citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	94	<command>systemd-nspawn</command> may be used to boot
	95	full Linux-based operating systems in a
	96	container.</para>
	97
	98	<para>Use a tool like
4d62fb42	99	<citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
25f5971b	100	<citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
4d62fb42 LP	101	or
4d62fb42 LP	102	<citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c14	103	to set up an OS directory tree suitable as file system
25f5971b LP	104	hierarchy for <command>systemd-nspawn</command>
25f5971b LP	105	containers.</para>
8f7a3c14 LP	106
	107	<para>Note that <command>systemd-nspawn</command> will
	108	mount file systems private to the container to
	109	<filename>/dev</filename>,
2b583ce6	110	<filename>/run</filename> and similar. These will
8f7a3c14 LP	111	not be visible outside of the container, and their
	112	contents will be lost when the container exits.</para>
	113
	114	<para>Note that running two
	115	<command>systemd-nspawn</command> containers from the
	116	same directory tree will not make processes in them
9f7dad77	117	see each other. The PID namespace separation of the
8f7a3c14 LP	118	two containers is complete and the containers will
8f7a3c14 LP	119	share very few runtime objects except for the
1fd96121 ZJS	120	underlying file system. It is however possible to
	121	enter an existing container, see
	122	<link linkend='example-nsenter'>Example 4</link> below.
	123	</para>
99800333 LP	124
	125	<para><command>systemd-nspawn</command> implements the
	126	<ulink
	127	url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
	128	Interface</ulink> specification.</para>
8f7a3c14 LP	129	</refsect1>
	130
	131	<refsect1>
	132	<title>Options</title>
	133
	134	<para>If no arguments are passed the container is set
	135	up and a shell started in it, otherwise the passed
	136	command and arguments are executed in it. The
	137	following options are understood:</para>
	138
	139	<variablelist>
	140	<varlistentry>
a41fe3a2	141	<term><option>-h</option></term>
a7f5bb1e	142	<term><option>--help</option></term>
8f7a3c14 LP	143
	144	<listitem><para>Prints a short help
	145	text and exits.</para></listitem>
	146	</varlistentry>
	147
acbeb427 ZJS	148	<varlistentry>
	149	<term><option>--version</option></term>
	150
	151	<listitem><para>Prints a version string
	152	and exits.</para></listitem>
	153	</varlistentry>
	154
8f7a3c14	155	<varlistentry>
ab1f0633	156	<term><option>-D</option></term>
a7f5bb1e	157	<term><option>--directory=</option></term>
8f7a3c14 LP	158
	159	<listitem><para>Directory to use as
	160	file system root for the namespace
	161	container. If omitted the current
	162	directory will be
	163	used.</para></listitem>
	164	</varlistentry>
	165
0f0dbc46	166	<varlistentry>
0f0dbc46	167	<term><option>-b</option></term>
a7f5bb1e	168	<term><option>--boot</option></term>
0f0dbc46 LP	169
	170	<listitem><para>Automatically search
	171	for an init binary and invoke it
	172	instead of a shell or a user supplied
	173	program.</para></listitem>
	174	</varlistentry>
	175
687d0825	176	<varlistentry>
4f755fc6	177	<term><option>-u</option></term>
a7f5bb1e	178	<term><option>--user=</option></term>
687d0825 MV	179
	180	<listitem><para>Run the command
	181	under specified user, create home
	182	directory and cd into it. As rest
	183	of systemd-nspawn, this is not
	184	the security feature and limits
	185	against accidental changes only.
	186	</para></listitem>
	187	</varlistentry>
	188
144f0fc0 LP	189	<varlistentry>
	190	<term><option>--uuid=</option></term>
	191
	192	<listitem><para>Set the specified uuid
	193	for the container. The init system
	194	will initialize
	195	<filename>/etc/machine-id</filename>
	196	from this if this file is not set yet.
	197	</para></listitem>
	198	</varlistentry>
	199
40c32a4a	200	<varlistentry>
40c32a4a	201	<term><option>-C</option></term>
a7f5bb1e	202	<term><option>--controllers=</option></term>
40c32a4a LGL	203
40c32a4a LGL	204	<listitem><para>Makes the container appear in
0cd1fd43	205	other hierarchies than the name=systemd:/ one.
40c32a4a LGL	206	Takes a comma-separated list of controllers.
	207	</para></listitem>
	208	</varlistentry>
	209
a41fe3a2	210	<varlistentry>
ff01d048	211	<term><option>--private-network</option></term>
a41fe3a2 LP	212
	213	<listitem><para>Turn off networking in
	214	the container. This makes all network
	215	interfaces unavailable in the
	216	container, with the exception of the
	217	loopback device.</para></listitem>
	218	</varlistentry>
	219
bc2f673e LP	220	<varlistentry>
	221	<term><option>--read-only</option></term>
	222
	223	<listitem><para>Mount the root file
	224	system read only for the
	225	container.</para></listitem>
	226	</varlistentry>
	227
5076f0cc LP	228	<varlistentry>
	229	<term><option>--capability=</option></term>
	230
	231	<listitem><para>List one or more
	232	additional capabilities to grant the
	233	container. Takes a comma separated
	234	list of capability names, see
	235	<citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
	236	for more information. Note that the
88d04e31 LP	237	following capabilities will be granted
88d04e31 LP	238	in any way: CAP_CHOWN,
5076f0cc LP	239	CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
	240	CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
	241	CAP_KILL, CAP_LEASE,
	242	CAP_LINUX_IMMUTABLE,
	243	CAP_NET_BIND_SERVICE,
	244	CAP_NET_BROADCAST, CAP_NET_RAW,
	245	CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
	246	CAP_SETUID, CAP_SYS_ADMIN,
	247	CAP_SYS_CHROOT, CAP_SYS_NICE,
	248	CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
88d04e31 LP	249	CAP_SYS_RESOURCE, CAP_SYS_BOOT,
	250	CAP_AUDIT_WRITE,
	251	CAP_AUDIT_CONTROL.</para></listitem>
5076f0cc LP	252	</varlistentry>
5076f0cc LP	253
57fb9fb5 LP	254	<varlistentry>
	255	<term><option>--link-journal=</option></term>
	256
	257	<listitem><para>Control whether the
	258	container's journal shall be made
	259	visible to the host system. If enabled
	260	allows viewing the container's journal
	261	files from the host (but not vice
	262	versa). Takes one of
	263	<literal>no</literal>,
	264	<literal>host</literal>,
	265	<literal>guest</literal>,
	266	<literal>auto</literal>. If
27407a01 ZJS	267	<literal>no</literal>, the journal is
27407a01 ZJS	268	not linked. If <literal>host</literal>,
57fb9fb5	269	the journal files are stored on the
27407a01	270	host file system (beneath
e670b166	271	<filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
27407a01	272	and the subdirectory is bind-mounted
57fb9fb5	273	into the container at the same
27407a01	274	location. If <literal>guest</literal>,
57fb9fb5	275	the journal files are stored on the
27407a01	276	guest file system (beneath
e670b166	277	<filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
27407a01	278	and the subdirectory is symlinked into the host
57fb9fb5	279	at the same location. If
27407a01 ZJS	280	<literal>auto</literal> (the default),
27407a01 ZJS	281	and the right subdirectory of
57fb9fb5	282	<filename>/var/log/journal</filename>
27407a01 ZJS	283	exists, it will be bind mounted
	284	into the container. If the
	285	subdirectory doesn't exist, no
	286	linking is performed. Effectively,
	287	booting a container once with
57fb9fb5 LP	288	<literal>guest</literal> or
57fb9fb5 LP	289	<literal>host</literal> will link the
27407a01	290	journal persistently if further on
57fb9fb5 LP	291	the default of <literal>auto</literal>
	292	is used.</para></listitem>
	293	</varlistentry>
	294
	295	<varlistentry>
	296	<term><option>-j</option></term>
	297
	298	<listitem><para>Equivalent to
	299	<option>--link-journal=guest</option>.</para></listitem>
	300	</varlistentry>
8f7a3c14 LP	301	</variablelist>
	302
	303	</refsect1>
	304
	305	<refsect1>
	306	<title>Example 1</title>
	307
2b3987a8 LP	308	<programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
2b3987a8 LP	309	# systemd-nspawn -bD /srv/mycontainer</programlisting>
8f7a3c14	310
25f5971b	311	<para>This installs a minimal Fedora distribution into
2b3987a8 LP	312	the directory <filename>/srv/mycontainer/</filename> and
	313	then boots an OS in a namespace container in
	314	it.</para>
8f7a3c14 LP	315	</refsect1>
	316
	317	<refsect1>
	318	<title>Example 2</title>
	319
25f5971b LP	320	<programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
25f5971b LP	321	# systemd-nspawn -D ~/debian-tree/</programlisting>
8f7a3c14	322
25f5971b LP	323	<para>This installs a minimal Debian unstable
	324	distribution into the directory
	325	<filename>~/debian-tree/</filename> and then spawns a
	326	shell in a namespace container in it.</para>
8f7a3c14 LP	327	</refsect1>
8f7a3c14 LP	328
68562936 WG	329	<refsect1>
	330	<title>Example 3</title>
	331
	332	<programlisting># pacstrap -c -d ~/arch-tree/ base
	333	# systemd-nspawn -bD ~/arch-tree/</programlisting>
	334
	335	<para>This installs a mimimal Arch Linux distribution into
	336	the directory <filename>~/arch-tree/</filename> and then
	337	boots an OS in a namespace container in it.</para>
	338	</refsect1>
	339
1fd96121 ZJS	340	<refsect1 id='example-nsenter'>
	341	<title>Example 4</title>
	342
	343	<para>To enter the container, PID of one of the
	344	processes sharing the new namespaces must be used.
	345	<command>systemd-nspawn</command> prints the PID
	346	(as viewed from the outside) of the launched process,
	347	and it can be used to enter the container.</para>
	348
	349	<programlisting># nsenter -muinpt $PID</programlisting>
	350
	351	<para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	352	is part of
	353	<ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
	354	Kernel support for entering namespaces was added in
	355	Linux 3.8.</para>
	356	</refsect1>
	357
8f7a3c14 LP	358	<refsect1>
	359	<title>Exit status</title>
	360
	361	<para>The exit code of the program executed in the
	362	container is returned.</para>
	363	</refsect1>
	364
	365	<refsect1>
	366	<title>See Also</title>
	367	<para>
	368	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	369	<citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1fd96121	370	<citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
25f5971b	371	<citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
4d62fb42	372	<citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
68562936	373	<citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c14 LP	374	</para>
	375	</refsect1>
	376
	377	</refentry>