NAME

       ostree-state-overlay@.service - Set up state overlays

SYNOPSIS

       ostree-state-overlay@.service

EXPERIMENTAL

       Note this feature is currently considered experimental.  It may not work correctly and some of its
       semantics may be subject to change. Positive or negative feedback are both welcome and may be provided at
       https://github.com/ostreedev/ostree/discussions. If using the feature via rpm-ostree, feedback may also
       be provided at https://github.com/coreos/rpm-ostree/issues/233.

DESCRIPTION

       In some cases, it's useful to be able to have a directory as part of the OSTree commit yet still have
       this directory be writable client-side. One example is software that ships in /opt.  /opt is its own
       vendor-namespaced alternate file hierarchy which may contain both code and state. With state overlays,
       it's possible to have the code part baked in the OSTree, but still allowing the directory to be writable
       so that state can be kept there.

       Since it's writable, nothing prevents sufficiently privileged code to modify or delete content that comes
       from the OSTree commit. This is in sharp contrast with content in /usr, and more closely matches a
       package manager-based distro.

       Crucially, this state is automatically rebased during upgrades (or more generally, anytime a different
       OSTree commit is booted). The semantics of the rebase are as follows: any state file or directory that
       modified OSTree content is deleted, otherwise it is kept and merged onto the new base content (using
       overlayfs). This mostly matches the semantics of a package manager.

       To enable this feature, simply instantiate the unit template, using the target path (in escaped systemd
       path notation) as the instance name. For example, to enable it on /opt:

               $ systemctl enable --now ostree-state-overlay@opt.service

ostree                                                                                     OSTREE-STATE-OVERL(8)