<para><command>importctl</command> may be used to download, import, and export disk images via
<citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
- <para><command>importctl</command> operates both on block-level disk images (such as DDIs) as well as
- file-system-level images (tarballs). It supports disk images in one of the four following
- classes:</para>
+ <para><command>importctl</command> operates both on block-level disk images (such as DDIs),
+ file-system-level images (tarballs), as well as OCI images. It supports disk images in one of the four
+ following classes:</para>
<itemizedlist>
<listitem><para>VM images or full OS container images, that may be run via
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>pull-oci</command> <replaceable>REF</replaceable> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Downloads the specified OCI container image, and makes it available under the
+ specified local name in the image directory for the selected <option>--class=</option>. The first
+ argument must be an OCI container reference, such as <literal>library/nginx</literal> If the local
+ name is omitted, it is automatically derived from the last component of the URL, with its suffix
+ removed.</para>
+
+ <para>When downloading images of this type no image verification is done beyond the usual
+ authentication of the HTTPS certificates.</para>
+
+ <para>Note that pressing Control-c during execution of this command will not abort the download. Use
+ <command>cancel-transfer</command>, described below.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><command>import-tar</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
<term><command>import-raw</command> <replaceable>FILE</replaceable> [<replaceable>NAME</replaceable>]</term>
['systemd-modules-load.service', '8', ['systemd-modules-load'], 'HAVE_KMOD'],
['systemd-mount', '1', ['systemd-umount'], ''],
['systemd-mountfsd.service', '8', ['systemd-mountfsd'], 'ENABLE_MOUNTFSD'],
+ ['systemd-mstack', '1', ['mount.mstack'], 'HAVE_BLKID'],
['systemd-mute-console',
'1',
['systemd-mute-console.socket', 'systemd-mute-console@.service'],
['systemd.kill', '5', [], ''],
['systemd.link', '5', [], ''],
['systemd.mount', '5', [], ''],
+ ['systemd.mstack', '7', [], ''],
['systemd.net-naming-scheme', '7', [], ''],
['systemd.netdev', '5', [], 'ENABLE_NETWORKD'],
['systemd.network', '5', [], 'ENABLE_NETWORKD'],
--- /dev/null
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-mstack"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>systemd-mstack</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd-mstack</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd-mstack</refname>
+ <refname>mount.mstack</refname>
+ <refpurpose>Mstack Discoverable Disk Images (DDIs)</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>systemd-mstack</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain"><replaceable>IMAGE</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>systemd-mstack</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>--mount</arg> <arg choice="plain"><replaceable>IMAGE</replaceable></arg> <arg choice="plain"><replaceable>PATH</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>systemd-mstack</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>--umount</arg> <arg choice="plain"><replaceable>PATH</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><command>systemd-mstack</command> is a tool for introspecting and interacting with
+ <filename>.mstack/</filename> mount stack directories, as described in
+ <citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It
+ supports three different operations:</para>
+
+ <orderedlist>
+ <listitem><para>Show general mount stack information, including all described
+ <literal>overlayfs</literal> layers and bind mounts.</para></listitem>
+
+ <listitem><para>Mount a mount stack to a local directory.</para></listitem>
+
+ <listitem><para>Unmount a mount stack from a local directory.</para></listitem>
+ </orderedlist>
+
+ <para>The <command>systemd-mstack</command> command may be invoked as <command>mount.mstack</command> in
+ which case it implements the <citerefentry
+ project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> "external
+ helper" interface. This ensures mount stack directories compatible with <command>systemd-mstack</command>
+ can be mounted directly by <command>mount</command> and <citerefentry
+ project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
+ details see below.</para>
+
+ <xi:include href="vpick.xml" xpointer="image"/>
+ </refsect1>
+
+ <refsect1>
+ <title>Commands</title>
+
+ <para>If neither of the command switches listed below are passed the specified mount stack is opened and
+ general information about it is shown, including a list of all defined layers.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--mount</option></term>
+ <term><option>-m</option></term>
+
+ <listitem><para>Mount the specified mount stack to the specified directory.</para>
+
+ <para>To unmount a mount stack directory mounted like this use the <option>--umount</option> operation.</para>
+
+ <para>Note that this functionality is also available in <citerefentry
+ project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> via a
+ command such as <command>mount -t mstack mystack.mstack targetdir/</command>, as well as in <citerefentry
+ project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
+ details, see below.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-M</option></term>
+
+ <listitem><para>This is a shortcut for <option>--mount --mkdir</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--umount</option></term>
+ <term><option>-u</option></term>
+
+ <listitem><para>Unmount a mount stack from the specified directory. This command expects one argument:
+ a directory where mount stack was mounted.</para>
+
+ <para>All mounted mounts will be recursively unmounted</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-U</option></term>
+
+ <listitem><para>This is a shortcut for <option>--umount --rmdir</option>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--read-only</option></term>
+ <term><option>-r</option></term>
+
+ <listitem><para>Operate in read-only mode. By default, <option>--mount</option> will establish
+ writable mount points. If this option is specified they are established in read-only mode
+ instead.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--mkdir</option></term>
+
+ <listitem><para>If combined with <option>--mount</option> the directory to mount the mount stack to
+ is created if it is missing. Note that the directory is not automatically removed when the mount
+ stack is unmounted again.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--rmdir</option></term>
+
+ <listitem><para>If combined with <option>--umount</option> the specified directory where the mount stack
+ is mounted is removed after unmounting it.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
+ <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+ <xi:include href="standard-options.xml" xpointer="image-filter" />
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
+ <xi:include href="standard-options.xml" xpointer="no-legend" />
+ <xi:include href="standard-options.xml" xpointer="json" />
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Exit status</title>
+
+ <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Invocation as <command>/sbin/mount.mstack</command></title>
+
+ <!-- In case you are wondering why this is spelled out with the /sbin/ prefix, rather than /usr/bin/ or
+ so, or omitting the prefix entirely: it's simply because util-linux mount always uses precisely this
+ spelling in their API docs. For example open mount(8), and grep for '/sbin/mount', and you see a ton
+ of occurences. We just inherit this spelling here, to make clear this is just an instantiation of
+ their plugin mechanism. -->
+
+ <para>The <command>systemd-mstack</command> executable may be symlinked to
+ <filename>/sbin/mount.mstack</filename>. If invoked through that it implements <citerefentry
+ project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
+ "external helper" interface for the (pseudo) file system type <literal>mstack</literal>. This means
+ conformant mount stack directories may be mounted directly via</para>
+
+ <programlisting># mount -t mstack mystack.mstack targetdir/</programlisting>
+
+ <para>in a fashion mostly equivalent to:</para>
+
+ <programlisting># systemd-mstack --mount mystack.mstack targetdir/</programlisting>
+
+ <para>Note that since a single mount stack may contain multiple mount points it should later be unmounted with
+ <command>umount -R targetdir/</command>, for recursive operation.</para>
+
+ <para>This functionality is particularly useful to mount mount stacks automatically at boot via simple
+ <filename>/etc/fstab</filename> entries. For example:</para>
+
+ <programlisting>/path/to/mystack.nspawn /images/mystack/ mstack defaults 0 0</programlisting>
+
+ <para>When invoked this way the mount options <literal>ro</literal>, <literal>rw</literal> map to the
+ corresponding options listed above (i.e. <option>--read-only</option>).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ </simplelist></para>
+ </refsect1>
+
+</refentry>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--mstack=</option></term>
+
+ <listitem><para>Mount stack to mount the root directory for the container from. Takes a path to a
+ directory implementing
+ <citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry>. This
+ may be used to run a container of an <literal>overlayfs</literal> assembled from a number of layers,
+ possibly writable and augmented with additional bind mounts.</para>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--oci-bundle=</option></term>
<member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>RootMStack=</varname></term>
+
+ <listitem><para>Takes a path to a
+ <citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ directory encapsulating a mount stack consisting of layers and bind mounts. Similar to
+ <varname>RootDirectory=</varname> and <varname>RootImage=</varname> this runs the service off a
+ distinct root file system, in this case set up via <literal>overlayfs</literal>.</para>
+
+ <para>Since <filename>.mstack/</filename> directories may reference disk images (DDIs) similar device
+ policy extensions and dependencies are in effect when <varname>RootMStack=</varname> is used as are
+ if <varname>RootImage=</varname> is used.</para>
+
+ <xi:include href="vpick.xml" xpointer="image"/>
+
+ <xi:include href="system-or-user-ns-mountfsd.xml" xpointer="singular"/>
+
+ <xi:include href="version-info.xml" xpointer="v260"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>MountAPIVFS=</varname></term>
--- /dev/null
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd.mstack">
+
+ <refentryinfo>
+ <title>systemd.mstack</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd.mstack</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd.mstack</refname>
+ <refpurpose>Mount stacks in self descriptive directories</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>Directories with the <literal>.mstack/</literal> suffix may encode 'mount stacks' for assembling OS
+ mount hierarchies based on bind and overlay mounts, for use in
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+ <option>--mstack=</option> switch or the service manager's <option>RootMStack=</option> setting for
+ services. <literal>.mstack/</literal> directroies may contain various files and subdirectories, where
+ each will effect one layer of an <literal>overlayfs</literal> mount, or a bind mount. The name of the
+ file or subdirectory indicates how it shall used in the mount hierarchy. Specifically, the following
+ names are defined:</para>
+
+ <orderedlist>
+ <listitem><para>A <filename>layer@<replaceable>id</replaceable>/</filename> directory will be turned into
+ a layer of an overlayfs mount. The <literal>id</literal> identifier is used to define the order of the
+ layers: a version sort is executed, with the first entry being the bottom layer in the
+ <literal>overlayfs</literal> stack, and the last entry becoming the highest layer (precisely:
+ highest "lowerdir") in the <literal>overlayfs</literal> stack.</para></listitem>
+
+ <listitem><para>Similar, a <filename>layer@<replaceable>id</replaceable>.raw</filename> regular file
+ will be mounted as a DDI, and the resulting mount will be turned into an overlayfs layer, following the
+ same sorting rules.</para></listitem>
+
+ <listitem><para>An <filename>rw</filename> directory will be turned into a writable layer at the very top
+ of the <literal>overlayfs</literal> stack. A subdirectory <filename>data</filename> of it will become
+ the "upperdir", a subdirectory <filename>work</filename> will become the "workdir". Note that these two
+ subdirectories do not need to be created explicitly, they are created automatically on first use should
+ they be missing.</para></listitem>
+
+ <listitem><para>A <filename>bind@<replaceable>location</replaceable>/</filename> directory will be bind
+ mounted to the mount point indicated by the <variable>location</variable> identifier, in read-write
+ fashion. The loction is encoded via the same escaping logic used for naming <literal>.mount</literal>
+ units, i.e. slashes become dashes.</para></listitem>
+
+ <listitem><para>Similar, a
+ <filename>bind@<replaceable>location</replaceable>.raw</filename> file will be mounted as a DDI, and the
+ resulting mount bind mounted to the specified location.</para></listitem>
+
+ <listitem><para>A <filename>robind@<replaceable>location</replaceable>/</filename> is treated very
+ similar to <filename>bind@<replaceable>location</replaceable>/</filename>, but the resulting bind mount
+ is read-only.</para></listitem>
+
+ <listitem><para>Similar, <filename>robind@<replaceable>location</replaceable>.raw</filename> creates a
+ read-only bind mount from a DDI.</para></listitem>
+
+ <listitem><para>If a <filename>root/</filename> subdirectory it is used as root of the resulting mount
+ hierarchy, and only the <filename>usr/</filename> subtree of the overlayfs mount will be bound to
+ <filename>usr/</filename> in the hierarchy.</para></listitem>
+ </orderedlist>
+
+ <para>Note that each of the entry types above may be a symbolic link pointing to a directory or image
+ file, instead a directory or image file itself.</para>
+
+ <para>On each listed file or subdirectory type the
+ <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ functionality may be used, for automatic selection of versioned resources.</para>
+
+ <para>Use the
+ <citerefentry><refentrytitle>systemd-mstack</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool
+ to process or mount <filename>.mstack/</filename> directories from the command line.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Examples</title>
+
+ <para>The following <filename>.mstack/</filename> consists of two read-only overlayfs layers as DDI, plus one
+ writable directory one on top. The read-only layers are symlinked:</para>
+
+ <orderedlist>
+ <listitem><para><filename>foobar.mstack/layer@0.raw</filename> → <filename>../base.raw</filename></para></listitem>
+ <listitem><para><filename>foobar.mstack/layer@1.raw</filename> → <filename>../app.raw</filename></para></listitem>
+ <listitem><para><filename>foobar.mstack/rw/</filename></para></listitem>
+ </orderedlist>
+
+ <para>The following <filename>.mstack/</filename> consists of a read-only DDI mounted to <literal>/usr/</literal>
+ and writable root:</para>
+
+ <orderedlist>
+ <listitem><para><filename>waldo.mstack/layer@0.raw</filename> → <filename>../vendor.raw</filename></para></listitem>
+ <listitem><para><filename>waldo.mstack/root/</filename></para></listitem>
+ </orderedlist>
+
+ <para>The following <filename>.mstack/</filename> consists of a read-only DDI mounted as root, but a
+ writable <filename>/var/</filename> mounted on top:</para>
+
+ <orderedlist>
+ <listitem><para><filename>quux.mstack/layer@0.raw</filename> → <filename>../myapp1.raw</filename></para></listitem>
+ <listitem><para><filename>quux.mstack/bind:var</filename> → <filename>../myapp1-var/</filename></para></listitem>
+ </orderedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-mstack</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-vpick</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ </simplelist></para>
+ </refsect1>
+
+</refentry>
projects / thirdparty / systemd.git / commitdiff
