shaba/ostree
1
0
Fork 0
mirror of https://github.com/ostreedev/ostree.git synced 2025-01-02 01:18:23 +03:00
Code Issues Projects Releases Wiki Activity

Merge pull request #3351 from cgwalters/fix-transient-root-doc

Browse Source 
man: Note semantics combining `root.transient` with `composefs.enabled`
This commit is contained in:
Colin Walters 2024-12-19 16:23:48 -05:00 committed by GitHub
commit 45ddf3b798
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 15 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
man/ostree-prepare-root.xml
View File

@ -120,20 +120,25 @@ License along with this library. If not, see <https://www.gnu.org/licenses/>.
<varlistentry>
<term><varname>root.transient</varname></term>
<listitem><para>A boolean value; the default is <literal>false</literal>.
If this is set to <literal>true</literal>, then the <literal>/</literal> filesystem will be a writable <literal>overlayfs</literal>,
with the upper directory being a hidden directory (in the underlying system root filesystem) that will persist across reboots by default.
However, changes will <emphasis>be discarded</emphasis> on OS updates!
Setting this flag to <literal>true</literal> requires composefs (See <literal>composefs.enabled</literal>).
When enabled, the root mount point <literal>/</literal> will be an overlayfs whose contents will be stored
in a tmpfs, and hence discarded on OS upgrade or reboot.
</para>
<para>
Enabling this option can be very useful for cases such as packages (dpkg/rpm/etc) that write content into <literal>/opt</literal>,
particularly where they expect the target to be writable at runtime. To make that work, ensure that your <literal>/opt</literal>
directory is *not* a symlink to <literal>/var/opt</literal>, but is just an empty directory.
</para>
<para>
Note the <literal>/usr</literal> mount point remains read-only by default. This option is independent of <literal>etc.transient</literal> and <literal>sysroot.readonly</literal>;
This option is independent of <literal>etc.transient</literal> and <literal>sysroot.readonly</literal>;
it is supported for example to have <literal>root.transient=true</literal> but <literal>etc.transient=false</literal> in which case changes to <literal>/etc</literal> continue
to persist across updates, with the default OSTree 3-way merge applied.
</para></listitem>
Also related to persistence it is important to emphasize that <literal>/sysroot</literal> (the physical root filesystem) is still persistent
by default; in-place OS upgrades can be applied.
</para>
<para>
Enabling this option can make it significantly easier to adopt an image-based model in some circumstances.
For example, if you have a configuration management system that is inspecting machine-specific state and
e.g. dynamically installing packages or applying configuration, it can more easily be adapted to
run on each boot, while still shifting a portion (or ideally most) image configuration to build time
as part of the base image/commit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>composefs.enabled</varname></term>