R"(

**Store URL format**: `local-overlay`

This store type is a variation of the [local store] designed to leverage Linux's [Overlay Filesystem](https://docs.kernel.org/filesystems/overlayfs.html) (OverlayFS for short).
Just as OverlayFS combines a lower and upper filesystem by treating the upper one as a patch against the lower, the local overlay store combines a lower store with an upper almost-[local store].
("almost" because while the upper filesystems for OverlayFS is valid on its own, the upper almost-store is not a valid local store on its own because some references will dangle.)
To use this store, you will first need to configure an OverlayFS mountpoint [appropriately](#example-filesystem-layout) as Nix will not do this for you (though it will verify the mountpoint is configured correctly).

### Conceptual parts of a local overlay store

*This is a more abstract/conceptual description of the parts of a layered store, an authoritative reference.
For more "practical" instructions, see the worked-out example in the next subsection.*

The parts of a local overlay store are as follows:

- **Lower store**:

  > Specified with the [`lower-store`](#store-experimental-local-overlay-store-lower-store) setting.

  This is any store implementation that includes a store directory as part of the native operating system filesystem.
  For example, this could be a [local store], [local daemon store], or even another local overlay store.

  The local overlay store never tries to modify the lower store in any way.
  Something else could modify the lower store, but there are restrictions on this
  Nix itself requires that this store only grow, and not change in other ways.
  For example, new store objects can be added, but deleting or modifying store objects is not allowed in general, because that will confuse and corrupt any local overlay store using those objects.
  (In addition, the underlying filesystem overlay mechanism may impose additional restrictions, see below.)

  The lower store must not change while it is mounted as part of an overlay store.
  To ensure it does not, you might want to mount the store directory read-only (which then requires the [read-only] parameter to be set to `true`).

  - **Lower store directory**:

    > Specified with `lower-store.real` setting.

    This is the directory used/exposed by the lower store.

    As specified above, Nix requires the local store can only grow not change in other ways.
    Linux's OverlayFS in addition imposes the further requirement that this directory cannot change at all.
    That means that, while any local overlay store exists that is using this store as a lower store, this directory must not change.

  - **Lower metadata source**:

    > Not directly specified.
    > A consequence of the `lower-store` setting, depending on the type of lower store chosen.

    This is abstract, just some way to read the metadata of lower store [store objects][store object].
    For example it could be a SQLite database (for the [local store]), or a socket connection (for the [local daemon store]).

    This need not be writable.
    As stated above a local overlay store never tries to modify its lower store.
    The lower store's metadata is considered part of the lower store, just as the store's [file system objects][file system object] that appear in the store directory are.

- **Upper almost-store**:

  > Not directly specified.
  > Instead the constituent parts are independently specified as described below.