61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
|
---
|
||
|
|
obj: filesystem
|
||
|
|
arch-wiki: https://wiki.archlinux.org/title/Overlay_filesystem
|
||
|
|
source: https://docs.kernel.org/filesystems/overlayfs.html
|
||
|
|
wiki: https://en.wikipedia.org/wiki/OverlayFS
|
||
|
|
rev: 2024-12-19
|
||
|
|
---
|
||
|
|
|
||
|
|
# OverlayFS
|
||
|
|
Overlayfs allows one, usually read-write, directory tree to be overlaid onto another, read-only directory tree. All modifications go to the upper, writable layer. This type of mechanism is most often used for live CDs but there is a wide variety of other uses.
|
||
|
|
|
||
|
|
The implementation differs from other "union filesystem" implementations in that after a file is opened all operations go directly to the underlying, lower or upper, filesystems. This simplifies the implementation and allows native performance in these cases.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
To mount an overlay use the following mount options:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mount -t overlay overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work /merged
|
||
|
|
```
|
||
|
|
|
||
|
|
> **Note**:
|
||
|
|
> - The working directory (`workdir`) needs to be an empty directory on the same filesystem as the upper directory.
|
||
|
|
> - The lower directory can be read-only or could be an overlay itself.
|
||
|
|
> - The upper directory is normally writable.
|
||
|
|
> - The workdir is used to prepare files as they are switched between the layers.
|
||
|
|
|
||
|
|
The lower directory can actually be a list of directories separated by `:`, all changes in the merged directory are still reflected in upper.
|
||
|
|
|
||
|
|
### Read-only overlay
|
||
|
|
Sometimes, it is only desired to create a read-only view of the combination of two or more directories. In that case, it can be created in an easier manner, as the directories `upper` and `work` are not required:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mount -t overlay overlay -o lowerdir=/lower1:/lower2 /merged
|
||
|
|
```
|
||
|
|
|
||
|
|
When `upperdir` is not specified, the overlay is automatically mounted as read-only.
|
||
|
|
|
||
|
|
## Example:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
mount -t overlay overlay -o lowerdir=/lower1:/lower2:/lower3,upperdir=/upper,workdir=/work /merged
|
||
|
|
```
|
||
|
|
|
||
|
|
> **Note**: The order of lower directories is the rightmost is the lowest, thus the upper directory is on top of the first directory in the left-to-right list of lower directories; NOT on top of the last directory in the list, as the order might seem to suggest.
|
||
|
|
|
||
|
|
The above example will have the order:
|
||
|
|
|
||
|
|
- /upper
|
||
|
|
- /lower1
|
||
|
|
- /lower2
|
||
|
|
- /lower3
|
||
|
|
|
||
|
|
To add an overlayfs entry to `/etc/fstab` use the following format:
|
||
|
|
|
||
|
|
```
|
||
|
|
# /etc/fstab
|
||
|
|
overlay /merged overlay noauto,x-systemd.automount,lowerdir=/lower,upperdir=/upper,workdir=/work 0 0
|
||
|
|
```
|
||
|
|
|
||
|
|
The `noauto` and `x-systemd.automount` mount options are necessary to prevent systemd from hanging on boot because it failed to mount the overlay. The overlay is now mounted whenever it is first accessed and requests are buffered until it is ready.
|