Fork of Original Code Base: anongit.freedesktop.org/systemd

This is the initial fork of the code base from freedsktop.org.
The code is provided here as a reference of the initial starting
point and for possible future checkouts after a large portion
of this code is removed.

Merge git://anongit.freedesktop.org/systemd/systemd

1 files changed, 331 insertions, 0 deletions

diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
new file mode 100644
index 0000000000..fef5c2c83a
--- /dev/null
+++ b/man/systemd-nspawn.xml
@@ -0,0 +1,331 @@
+<?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 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.</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/&lt;machine-id&gt;</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/&lt;machine-id&gt;</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 --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>