X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd-nspawn.xml;h=8adcd946b0438e6da634576eefc780a99ada068a;hb=5b7d4c1c164d91b8c28c3dcd3921ad9863953ffa;hp=2939951a886a775427cc59d74430e580dcc8dfb8;hpb=88d04e31ce0837ebf937ab46c3c39a0d93ab4c7c;p=elogind.git

diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index 2939951a8..8adcd946b 100644
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -49,7 +49,17 @@
 
         <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>
+                        <command>systemd-nspawn</command>
+                        <arg choice="opt" rep="repeat">OPTIONS</arg>
+                        <arg choice="opt"><replaceable>COMMAND</replaceable>
+                        <arg choice="opt" rep="repeat">ARGS</arg>
+                        </arg>
+                </cmdsynopsis>
+                <cmdsynopsis>
+                        <command>systemd-nspawn</command>
+                        <arg choice="plain">-b</arg>
+                        <arg choice="opt" rep="repeat">OPTIONS</arg>
+                        <arg choice="opt" rep="repeat">ARGS</arg>
                 </cmdsynopsis>
         </refsynopsisdiv>
 
@@ -93,9 +103,10 @@
                 container.</para>
 
                 <para>Use a tool like
-                <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-                or
+                <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>
@@ -113,7 +124,10 @@
                 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>
+                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
@@ -124,15 +138,21 @@
         <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>
+                <para>If option <option>-b</option> is specified, the
+                arguments are used as arguments for the init
+                binary. Otherwise, <replaceable>COMMAND</replaceable>
+                specifies the program to launch in the container, and
+                the remaining arguments are used as arguments for this
+                program. If <option>-b</option> is not used and no
+                arguments are specifed, a shell is launched in the
+                container.</para>
+
+                <para>The following options are understood:</para>
 
                 <variablelist>
                         <varlistentry>
-                                <term><option>--help</option></term>
                                 <term><option>-h</option></term>
+                                <term><option>--help</option></term>
 
                                 <listitem><para>Prints a short help
                                 text and exits.</para></listitem>
@@ -146,8 +166,8 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>--directory=</option></term>
                                 <term><option>-D</option></term>
+                                <term><option>--directory=</option></term>
 
                                 <listitem><para>Directory to use as
                                 file system root for the namespace
@@ -157,18 +177,21 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>--boot</option></term>
                                 <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>
+                                program. If this option is used, arguments
+                                specified on the command line are used
+                                as arguments for the init binary.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>--user=</option></term>
                                 <term><option>-u</option></term>
+                                <term><option>--user=</option></term>
 
                                 <listitem><para>Run the command
                                 under specified user, create home
@@ -191,8 +214,8 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>--controllers=</option></term>
                                 <term><option>-C</option></term>
+                                <term><option>--controllers=</option></term>
 
                                 <listitem><para>Makes the container appear in
                                 other hierarchies than the name=systemd:/ one.
@@ -261,13 +284,13 @@
                                 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>)
+                                <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/&lt;machine-id&gt;</filename>)
+                                <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),
@@ -291,6 +314,26 @@
                                 <listitem><para>Equivalent to
                                 <option>--link-journal=guest</option>.</para></listitem>
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--bind=</option></term>
+                                <term><option>--bind-ro=</option></term>
+
+                                <listitem><para>Bind mount a file or
+                                directory from the host into the
+                                container. Either takes a path
+                                argument -- in which case the
+                                specified path will be mounted from
+                                the host to the same path in the
+                                container --, or a colon-separated
+                                pair of paths -- in which case the
+                                first specified path is the source in
+                                the host, and the second path is the
+                                destination in the container. The
+                                <option>--bind-ro=</option> option
+                                creates read-only bind
+                                mount.</para></listitem>
+                        </varlistentry>
                 </variablelist>
 
         </refsect1>
@@ -298,13 +341,13 @@
         <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>
+                <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>~/fedora-tree/</filename>
-                and then boots an OS in a namespace container in it,
-                with systemd as init system.</para>
+                the directory <filename>/srv/mycontainer/</filename> and
+                then boots an OS in a namespace container in
+                it.</para>
         </refsect1>
 
         <refsect1>
@@ -317,7 +360,35 @@
                 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>
@@ -332,8 +403,10 @@
                 <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>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                 </para>
         </refsect1>