Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Filesystem doc #951

Merged
merged 4 commits into from
Dec 10, 2024
Merged

Filesystem doc #951

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aebb4ad
filesystem: Doc usr/etc
cgwalters Dec 9, 2024
6696eb3
filesystem: Doc etc.transient
cgwalters Dec 9, 2024
936e832
doc: Expand on prepare-root
cgwalters Dec 9, 2024
be346bc
docs: Fix "implmentation" typo
cgwalters Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions docs/src/filesystem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ in derived builds.
## `/etc`

The `/etc` directory contains mutable persistent state by default; however,
it is suppported to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html).
it is suppported to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html),
see below as well.

When in persistent mode, it inherits the OSTree semantics of [performing a 3-way merge](https://ostreedev.github.io/ostree/atomic-upgrades/#assembling-a-new-deployment-directory)
across upgrades. In a nutshell:
Expand All @@ -95,6 +96,13 @@ would require external intervention to apply.

For more on configuration file best practices, see [Building](building/guidance.md).

### `/usr/etc`

The `/usr/etc` tree is generated client side and contains the default container image's
view of `/etc`. This should generally be considered an internal implmentation detail
cgwalters marked this conversation as resolved.
Show resolved Hide resolved
of bootc/ostree. Do *not* explicitly put files into this location, it can create
undefined behavior. There is a check for this in `bootc container lint`.

## `/var`

Content in `/var` persists by default; it is however supported to make it or subdirectories
Expand Down Expand Up @@ -178,11 +186,33 @@ To do this, set the
transient = true
```

option in `prepare-root.conf`. In particular this will allow software to
option in `/usr/lib/ostree/prepare-root.conf`. In particular this will allow software to
write (transiently, i.e. until the next reboot) to all top-level directories,
including `/usr` and `/opt`, with symlinks to `/var` for content that should
persist.

This can be combined with `etc.transient` as well (below).

More on prepare-root: <https://ostreedev.github.io/ostree/man/ostree-prepare-root.html>

## Enabling transient etc

The default (per above) is to have `/etc` persist. If however you do
not need to use it for any per-machine state, then enabling a transient
`/etc` is a great way to reduce the amount of possible state drift. Set
the

```toml
[etc]
transient = true
```

option in `/usr/lib/ostree/prepare-root.conf`.

This can be combined with `root.transient` as well (above).

More on prepare-root: <https://ostreedev.github.io/ostree/man/ostree-prepare-root.html>

## Enabling state overlays

This feature enables a writable overlay on top of `/opt` (or really, any
Expand Down
Loading