networkd: netdev - add ipvlan support

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

diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index b3a2d328559273a6feccc01114ca7e562e419e98..0c6fb002891d63e2cdbaed074d46915deff07e0f 100644 (file)
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -165,14 +165,80 @@
                                 <term><option>--directory=</option></term>
 
                                 <listitem><para>Directory to use as
                                 <term><option>--directory=</option></term>
 
                                 <listitem><para>Directory to use as

-                                file system root for the container. If
-                                neither <option>--directory=</option>
-                                nor <option>--image=</option> are
+                                file system root for the container.</para>
+
+                                <para>If neither
+                                <option>--directory=</option>, nor
+                                <option>--image=</option> is specified
+                                the directory is determined as
+                                <filename>/var/lib/machines/</filename>
+                                suffixed by the machine name as
+                                specified with
+                                <option>--machine=</option>. If
+                                neither <option>--directory=</option>,
+                                <option>--image=</option>, nor
+                                <option>--machine=</option> are

                                 specified, the current directory will
                                 specified, the current directory will

-                                be used. May not be specified together with
+                                be used. May not be specified together
+                                with

                                 <option>--image=</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>--image=</option>.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>--template=</option></term>
+
+                                <listitem><para>Directory or
+                                <literal>btrfs</literal> subvolume to
+                                use as template for the container's
+                                root directory. If this is specified
+                                and the container's root directory (as
+                                configured by
+                                <option>--directory=</option>) does
+                                not yet exist it is created as
+                                <literal>btrfs</literal> subvolume and
+                                populated from this template
+                                tree. Ideally, the specified template
+                                path refers to the root of a
+                                <literal>btrfs</literal> subvolume, in
+                                which case a simple copy-on-write
+                                snapshot is taken, and populating the
+                                root directory is instant. If the
+                                specified template path does not refer
+                                to the root of a
+                                <literal>btrfs</literal> subvolume (or
+                                not even to a <literal>btrfs</literal>
+                                file system at all), the tree is
+                                copied, which can be substantially
+                                more time-consuming. Note that if this
+                                option is used the container's root
+                                directory (in contrast to the template
+                                directory!) must be located on a
+                                <literal>btrfs</literal> file system,
+                                so that the <literal>btrfs</literal>
+                                subvolume may be created. May not be
+                                specified together with
+                                <option>--image=</option> or
+                                <option>--ephemeral</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>-x</option></term>
+                                <term><option>--ephemeral</option></term>
+
+                                <listitem><para>If specified, the
+                                container is run with a temporary
+                                <literal>btrfs</literal> snapshot of
+                                its root directory (as configured with
+                                <option>--directory=</option>), that
+                                is removed immediately when the
+                                container terminates. This option is
+                                only supported if the root file system
+                                is <literal>btrfs</literal>. May not
+                                be specified together with
+                                <option>--image=</option> or
+                                <option>--template=</option>.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>-i</option></term>
                                 <term><option>--image=</option></term>
                         <varlistentry>
                                 <term><option>-i</option></term>
                                 <term><option>--image=</option></term>


@@ -181,10 +247,13 @@
                                 the root directory for the container
                                 from. Takes a path to a regular file
                                 or to a block device node. The file or
                                 the root directory for the container
                                 from. Takes a path to a regular file
                                 or to a block device node. The file or

-                                block device must contain a GUID
-                                Partition Table with a root partition
-                                which is mounted as the root directory
-                                of the container. Optionally, it may
+                                block device must contain either an
+                                MBR partition table with a single
+                                partition of type 0x83 that is marked
+                                bootable, or a GUID partition table
+                                with a root partition which is mounted
+                                as the root directory of the
+                                container. Optionally, GPT images may

                                 contain a home and/or a server data
                                 partition which are mounted to the
                                 appropriate places in the
                                 contain a home and/or a server data
                                 partition which are mounted to the
                                 appropriate places in the


@@ -197,7 +266,9 @@
                                 partitions, swap partitions or EFI
                                 system partitions are not mounted. May
                                 not be specified together with
                                 partitions, swap partitions or EFI
                                 system partitions are not mounted. May
                                 not be specified together with

-                                <option>--directory=</option>.</para></listitem>
+                                <option>--directory=</option>,
+                                <option>--template=</option> or
+                                <option>--ephemeral</option>.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -237,13 +308,22 @@
 
                                 <listitem><para>Sets the machine name
                                 for this container. This name may be
 
                                 <listitem><para>Sets the machine name
                                 for this container. This name may be

-                                used to identify this container on the
-                                host, and is used to initialize the
-                                container's hostname (which the
-                                container can choose to override,
-                                however). If not specified, the last
-                                component of the root directory of the
-                                container is used.</para></listitem>
+                                used to identify this container during
+                                its runtime (for example in tools like
+                                <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                                and similar), and is used to
+                                initialize the container's hostname
+                                (which the container can choose to
+                                override, however). If not specified,
+                                the last component of the root
+                                directory path of the container is
+                                used, possibly suffixed with a random
+                                identifier in case
+                                <option>--ephemeral</option> mode is
+                                selected. If the root directory
+                                selected is the host's root directory
+                                the host's hostname is used as default
+                                instead.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -330,6 +410,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

+                                <term><option>-n</option></term>

                                 <term><option>--network-veth</option></term>
 
                                 <listitem><para>Create a virtual
                                 <term><option>--network-veth</option></term>
 
                                 <listitem><para>Create a virtual


@@ -365,6 +446,32 @@
                                 of <literal>ve-</literal>.</para></listitem>
                         </varlistentry>
 
                                 of <literal>ve-</literal>.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>-p</option></term>
+                                <term><option>--port=</option></term>
+
+                                <listitem><para>If private networking
+                                is enabled, maps an IP port on the
+                                host onto an IP port on the
+                                container. Takes a protocol specifier
+                                (either <literal>tcp</literal> or
+                                <literal>udp</literal>), separated by
+                                a colon from a host port number in the
+                                range 1 to 65535, separated by a colon
+                                from a container port number in the
+                                range from 1 to 65535. The protocol
+                                specifier and its separating colon may
+                                be omitted, in which case
+                                <literal>tcp</literal> is assumed.
+                                The container port number and its
+                                colon may be ommitted, in which case
+                                the same port as the host port is
+                                implied. This option is only supported
+                                if private networking is used, such as
+                                <option>--network-veth</option> or
+                                <option>--network-bridge=</option>.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>-Z</option></term>
                                 <term><option>--selinux-context=</option></term>
                         <varlistentry>
                                 <term><option>-Z</option></term>
                                 <term><option>--selinux-context=</option></term>


@@ -439,7 +546,9 @@
                                 versa). Takes one of
                                 <literal>no</literal>,
                                 <literal>host</literal>,
                                 versa). Takes one of
                                 <literal>no</literal>,
                                 <literal>host</literal>,

+                                <literal>try-host</literal>,

                                 <literal>guest</literal>,
                                 <literal>guest</literal>,

+                                <literal>try-guest</literal>,

                                 <literal>auto</literal>. If
                                 <literal>no</literal>, the journal is
                                 not linked. If <literal>host</literal>,
                                 <literal>auto</literal>. If
                                 <literal>no</literal>, the journal is
                                 not linked. If <literal>host</literal>,


@@ -453,8 +562,11 @@
                                 guest file system (beneath
                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
                                 and the subdirectory is symlinked into the host
                                 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),
+                                at the same location. <literal>try-host</literal>
+                                and <literal>try-guest</literal> do the same
+                                but do not fail if the host does not have
+                                persistent journalling enabled.
+                                If <literal>auto</literal> (the default),

                                 and the right subdirectory of
                                 <filename>/var/log/journal</filename>
                                 exists, it will be bind mounted
                                 and the right subdirectory of
                                 <filename>/var/log/journal</filename>
                                 exists, it will be bind mounted


@@ -473,7 +585,7 @@
                                 <term><option>-j</option></term>
 
                                 <listitem><para>Equivalent to
                                 <term><option>-j</option></term>
 
                                 <listitem><para>Equivalent to

-                                <option>--link-journal=guest</option>.</para></listitem>
+                                <option>--link-journal=try-guest</option>.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -648,13 +760,13 @@
                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 
                                 <listitem><para>Boots the container in
                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 
                                 <listitem><para>Boots the container in

-                                volatile (ephemeral) mode. When no
-                                mode parameter is passed or when mode
-                                is specified as <literal>yes</literal>
-                                full volatile mode is enabled. This
-                                means the root directory is mounted as
-                                mostly unpopulated
-                                <literal>tmpfs</literal> instance, and
+                                volatile mode. When no mode parameter
+                                is passed or when mode is specified as
+                                <literal>yes</literal> full volatile
+                                mode is enabled. This means the root
+                                directory is mounted as mostly
+                                unpopulated <literal>tmpfs</literal>
+                                instance, and

                                 <filename>/usr</filename> from the OS
                                 tree is mounted into it, read-only
                                 (the system thus starts up with
                                 <filename>/usr</filename> from the OS
                                 tree is mounted into it, read-only
                                 (the system thus starts up with


@@ -672,8 +784,8 @@
                                 changes to the latter are lost on
                                 shutdown). When the mode parameter is
                                 specified as <literal>no</literal>
                                 changes to the latter are lost on
                                 shutdown). When the mode parameter is
                                 specified as <literal>no</literal>

-                                (the default) the whole OS tree is made
-                                available writable.</para>
+                                (the default) the whole OS tree is
+                                made available writable.</para>

 
                                 <para>Note that setting this to
                                 <literal>yes</literal> or
 
                                 <para>Note that setting this to
                                 <literal>yes</literal> or


@@ -698,7 +810,7 @@
                 <example>
                         <title>Boot a minimal Fedora distribution in a container</title>
 
                 <example>
                         <title>Boot a minimal Fedora distribution in a container</title>
 

-                        <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
+                        <programlisting># yum -y --releasever=21 --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
 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 
                         <para>This installs a minimal Fedora distribution into


@@ -733,7 +845,7 @@
                 <example>
                         <title>Enable Arch Linux container on boot</title>
 
                 <example>
                         <title>Enable Arch Linux container on boot</title>
 

-                        <programlisting># mv ~/arch-tree /var/lib/container/arch
+                        <programlisting># mv ~/arch-tree /var/lib/machines/arch

 # systemctl enable systemd-nspawn@arch.service
 # systemctl start systemd-nspawn@arch.service</programlisting>
 
 # systemctl enable systemd-nspawn@arch.service
 # systemctl start systemd-nspawn@arch.service</programlisting>
 


@@ -743,13 +855,16 @@
                 </example>
 
                 <example>
                 </example>
 
                 <example>

-                        <title>Boot into a btrfs snapshot of the host system</title>
+                        <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>

 
 

-                        <programlisting># btrfs subvolume snapshot / /.tmp
-# systemd-nspawn --private-network -D /.tmp -b</programlisting>
+                        <programlisting># systemd-nspawn -D / -xb</programlisting>

 
                         <para>This runs a copy of the host system in a
 
                         <para>This runs a copy of the host system in a

-                        btrfs snapshot.</para>
+                        <literal>btrfs</literal> snapshot which is
+                        removed immediately when the container
+                        exits. All file system changes made during
+                        runtime will be lost on shutdown,
+                        hence.</para>

                 </example>
 
                 <example>
                 </example>
 
                 <example>


@@ -776,7 +891,8 @@
                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>

                 </para>
         </refsect1>
 
                 </para>
         </refsect1>