'\" t
.\"     Title: ostree-state-overlay
.\"    Author: Jonathan Lebon <jonathan@jlebon.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/16/2024
.\"    Manual: ostree-state-overlay
.\"    Source: ostree
.\"  Language: English
.\"
.TH "OSTREE\-STATE\-OVERL" "8" "" "ostree" "ostree-state-overlay"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ostree-state-overlay@.service \- Set up state overlays
.SH "SYNOPSIS"
.PP
ostree\-state\-overlay@\&.service
.SH "EXPERIMENTAL"
.PP
\fBNote this feature is currently considered experimental\&.\fR
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
\m[blue]\fB\%https://github.com/ostreedev/ostree/discussions\fR\m[]\&. If using the feature via rpm\-ostree, feedback may also be provided at
\m[blue]\fB\%https://github.com/coreos/rpm-ostree/issues/233\fR\m[]\&.
.SH "DESCRIPTION"
.PP
In some cases, it\*(Aqs 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\*(Aqs 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\&.
.PP
Since it\*(Aqs 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\&.
.PP
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\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
    $ systemctl enable \-\-now ostree\-state\-overlay@opt\&.service
    
.fi
.if n \{\
.RE
.\}