Home • Explore • Blog • Models • CI
☰



nix
2nd chunk of `src/libstore/local-overlay-store.md`
96277c5c2643c70418d82e5cefa664f4b2e59a711ade157300000001000008d5
    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.

  This is almost but not quite just a [local store].
  That is because taken in isolation, not as part of a local overlay store, by itself, it would appear corrupted.
  But combined with everything else as part of an overlay local store, it is valid.

  - **Upper layer directory**:

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

    This contains additional [store objects][store object]
    (or, strictly speaking, their [file system objects][file system object] that the local overlay store will extend the lower store with).

  - **Upper store directory**:

    > Specified with the [`real`](#store-experimental-local-overlay-store-real) setting.
    > This the same as the base local store setting, and can also be indirectly specified with the [`root`](#store-experimental-local-overlay-store-root) setting.

    This contains all the store objects from each of the two directories.

    The lower store directory and upper layer directory are combined via OverlayFS to create this directory.
    Nix doesn't do this itself, because it typically wouldn't have the permissions to do so, so it is the responsibility of the user to set this up first.
Title: Nix `local-overlay` Store: Lower Metadata and Upper Almost-Store Components
Summary
This section of the Nix `local-overlay` store documentation explains the 'lower metadata source,' an abstract, read-only mechanism for accessing metadata from the lower store, which remains unmodified by the overlay. It then details the 'upper almost-store,' which, while appearing corrupted in isolation, becomes valid when combined with the lower store. The 'upper layer directory' (`upper-layer`) holds new store objects that extend the lower store. Finally, the 'upper store directory' (`real` or `root`) is the final combined directory, created by OverlayFS from the lower store directory and upper layer directory. Users are responsible for setting up this OverlayFS mountpoint as Nix typically lacks the necessary permissions.