mirror of
https://github.com/systemd/systemd
synced 2024-09-06 08:46:19 +00:00
man/systemd-sysext.xml: document mutable extensions
Signed-off-by: Thilo Fromm <thilofromm@microsoft.com>
This commit is contained in:
parent
bfa2dd7558
commit
ea29a87f23
|
@ -69,8 +69,10 @@
|
||||||
<filename>/var/</filename> included in a system extension image will <emphasis>not</emphasis> appear in
|
<filename>/var/</filename> included in a system extension image will <emphasis>not</emphasis> appear in
|
||||||
the respective hierarchies after activation.</para>
|
the respective hierarchies after activation.</para>
|
||||||
|
|
||||||
<para>System extension images are strictly read-only, and the host <filename>/usr/</filename> and
|
<para>System extension images are strictly read-only by default. On mutable host file systems,
|
||||||
<filename>/opt/</filename> hierarchies become read-only too while they are activated.</para>
|
<filename>/usr/</filename> and <filename>/opt/</filename> hierarchies become read-only while extensions
|
||||||
|
are merged, unless mutability is enabled. Mutability may be enabled via the <option>--mutable=</option>
|
||||||
|
option; see "Mutability" below for more information.</para>
|
||||||
|
|
||||||
<para>System extensions are supposed to be purely additive, i.e. they are supposed to include only files
|
<para>System extensions are supposed to be purely additive, i.e. they are supposed to include only files
|
||||||
that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also
|
that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also
|
||||||
|
@ -158,6 +160,11 @@
|
||||||
same as sysext images. The merged hierarchy will be mounted with <literal>nosuid</literal> and
|
same as sysext images. The merged hierarchy will be mounted with <literal>nosuid</literal> and
|
||||||
(if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</para>
|
(if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</para>
|
||||||
|
|
||||||
|
<para>Just like sysexts, confexts are strictly read-only by default. Merging confexts on mutable host
|
||||||
|
file systems will result in <filename>/etc/</filename> becoming read-only. As with sysexts, mutability
|
||||||
|
can be enabled via the <option>--mutable=</option> option. Refer to "Mutability" below for more
|
||||||
|
information.</para>
|
||||||
|
|
||||||
<para>Confexts are looked for in the directories <filename>/run/confexts/</filename>,
|
<para>Confexts are looked for in the directories <filename>/run/confexts/</filename>,
|
||||||
<filename>/var/lib/confexts/</filename>, <filename>/usr/lib/confexts/</filename> and
|
<filename>/var/lib/confexts/</filename>, <filename>/usr/lib/confexts/</filename> and
|
||||||
<filename>/usr/local/lib/confexts/</filename>. The first listed directory is not suitable for
|
<filename>/usr/local/lib/confexts/</filename>. The first listed directory is not suitable for
|
||||||
|
@ -205,6 +212,55 @@
|
||||||
to tie the most frequently configured options to runtime updateable flags that can be changed without a
|
to tie the most frequently configured options to runtime updateable flags that can be changed without a
|
||||||
system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.</para></refsect1>
|
system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.</para></refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Mutability</title>
|
||||||
|
<para>By default, merging system extensions on mutable host file systems will render <filename>/usr/</filename>
|
||||||
|
and <filename>/opt/</filename> hierarchies read-only. Merging configuration extensions will have the same
|
||||||
|
effect on <filename>/etc/</filename>. Mutable mode allows writes to these locations when extensions are
|
||||||
|
merged.</para>
|
||||||
|
|
||||||
|
<para>The following modes are supported:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para><option>disabled</option>: Force immutable mode even if write routing
|
||||||
|
directories exist below <filename>/var/lib/extensions.mutable/</filename>.
|
||||||
|
This is the default.</para></listitem>
|
||||||
|
<listitem><para><option>auto</option>: Automatic mode. Mutability is disabled by default
|
||||||
|
and only enabled if a corresponding write routing directory exists below
|
||||||
|
<filename>/var/lib/extensions.mutable/</filename>.</para></listitem>
|
||||||
|
<listitem><para><option>enabled</option>: Force mutable mode and automatically create write routing
|
||||||
|
directories below <filename>/var/lib/extensions.mutable/</filename> when required.</para></listitem>
|
||||||
|
<listitem><para><option>import</option>: Force immutable mode like <option>disabled</option> above, but
|
||||||
|
merge the contents of directories below <filename>/var/lib/extensions.mutable/</filename> into the host
|
||||||
|
file system.</para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
See "Options" below on specifying modes using the <option>--mutable=</option> command line option.</para>
|
||||||
|
|
||||||
|
<para>Mutable mode routes writes to subdirectories in <filename>/var/lib/extensions.mutable/</filename>.
|
||||||
|
<simplelist type="horiz">
|
||||||
|
<member>Writes to <filename>/usr/</filename> are directed to <filename>/var/lib/extensions.mutable/usr/</filename></member>,
|
||||||
|
<member>writes to <filename>/opt/</filename> are directed to <filename>/var/lib/extensions.mutable/opt/</filename>, and</member>
|
||||||
|
<member>writes to <filename>/etc/</filename> land in <filename>/var/lib/extensions.mutable/etc/</filename>.</member>
|
||||||
|
</simplelist></para>
|
||||||
|
|
||||||
|
<para>If <filename>usr/</filename>, <filename>opt/</filename>, or <filename>etc/</filename>
|
||||||
|
in <filename>/var/lib/extensions.mutable/</filename> are symlinks, then writes are directed to the
|
||||||
|
symlinks' targets.
|
||||||
|
Consequently, to retain mutability of a host file system, create symlinks
|
||||||
|
<simplelist type="horiz">
|
||||||
|
<member><filename>/var/lib/extensions.mutable/etc/</filename> → <filename>/etc/</filename></member>
|
||||||
|
<member><filename>/var/lib/extensions.mutable/usr/</filename> → <filename>/usr/</filename></member>
|
||||||
|
<member><filename>/var/lib/extensions.mutable/opt/</filename> → <filename>/opt/</filename></member>
|
||||||
|
</simplelist>
|
||||||
|
to route writes back to the original base directory hierarchy.</para>
|
||||||
|
|
||||||
|
<para> Alternatively, a temporary file system may be mounted to
|
||||||
|
<filename>/var/lib/extensions.mutable/</filename>, or symlinks in
|
||||||
|
<filename>/var/lib/extensions.mutable/</filename> may point to sub-directories on a temporary
|
||||||
|
file system (e.g. below <filename>/tmp/</filename>) to only allow ephemeral changes.</para>
|
||||||
|
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Commands</title>
|
<title>Commands</title>
|
||||||
|
|
||||||
|
@ -313,6 +369,45 @@
|
||||||
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>--mutable=</option><replaceable>BOOL</replaceable>|<replaceable>auto</replaceable>|<replaceable>import</replaceable></term>
|
||||||
|
<listitem><para>Set mutable mode.</para>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>no</option></term>
|
||||||
|
<listitem><para>force immutable mode even with write routing directories present.
|
||||||
|
This is the default.</para>
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>auto</option></term>
|
||||||
|
<listitem><para>enable mutable mode individually for <filename>/usr/</filename>,
|
||||||
|
<filename>/opt/</filename>, and <filename>/etc/</filename> if write routing sub-directories
|
||||||
|
or symlinks are present in <filename>/var/lib/extensions.mutable/</filename>; disable otherwise.
|
||||||
|
See "Mutability" above for more information on write routing.</para>
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>yes</option></term>
|
||||||
|
<listitem><para>force mutable mode. Write routing directories will be created in
|
||||||
|
<filename>/var/lib/extensions.mutable/</filename> if not present.</para>
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>import</option></term>
|
||||||
|
<listitem><para>immutable mode, but with contents of write routing directories in
|
||||||
|
<filename>/var/lib/extensions.mutable/</filename> also merged into the host file system.</para>
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
|
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><option>--noexec=</option><replaceable>BOOL</replaceable></term>
|
<term><option>--noexec=</option><replaceable>BOOL</replaceable></term>
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue