unionfs(8)

📦
version 3.4 · 4 versions
, in alpine 3.22, alpine 3.23, alpine 3.24

💅 unionfs(8) — the manual, but make it make sense

okay so bestie, welcome to unionfs(8) — yes that's the page name, that's the vibe, we're doing this. this is unionfs-fuse, and I'm gonna walk you through the whole thing like we're on facetime and I actually want you to pass your exam. 🫶

✨ NAME ✨

unionfs-fuse — a userspace unionfs implementation. that's it, that's the name, she's simple, she's iconic, she does one thing and she does it well 👑

🌸 SYNOPSIS 🌸

unionfs [-o option1 -o option2 ... -o optionN ]
             top_branch:lower_branch:...:lowest_branch
             mount_point

like… you stack a bunch of branches on top of each other, you give her a mount point, and she slays. the options are all optional-ish, the branches and the mount point are the moment. periodt.

🦋 DESCRIPTION 🦋

so unionfs overlays several directories into one single mount point. one mount point, many directories, all merged into one gorgeous little view. it's giving "why choose" energy.

here's the actual mechanics, no cap: she first tries to access the file on the top branch, and if the file isn't there, she just keeps going down, lower and lower level branches, until she finds it. like scrolling until you find the one.

and then — the cute part — if you try to modify a file on a lower level read-only branch while copy-on-write (cow) mode is enabled, the file gets copied up to a higher level read-write branch. she doesn't touch your read-only stuff, she just makes a little copy higher up. respectful. 💖

🎀 OPTIONS 🎀

below is a summary of unionfs options. yes, all of them. I'm not skipping a single one, bestie, we're thorough in this house.

  • -o chroot=path — path to chroot into. by using this option, unionfs may be used for live CDs or live USB sticks, etc. so it can serve "/" as filesystem. ⚠️ heads up: if you do not specify this option and you try to use it for "/", it will deadlock on calling pivot_root — like, full on freeze, not cute. and if you do set this option, you also need to specify the branches relatively to the given chroot directory. see examples/S01a-unionfs-live-cd.sh for an example. iykyk 💅
  • -o cow — enable copy-on-write. that's the whole thing. go off.
  • -o hide_meta_files — okay so in our unionfs root path we have a .unionfs directory that includes metadata, such as hidden (deleted) files. this option makes this directory invisible from readdir(), so for example ls -la /union_root will not show it. 👀 however — and this is the plot twist — this directory is still there and cd .unionfs or ls -l .unionfs still work. also, libfuse will create .fuse_hidden* files if a file is open but will be deleted, and those fuse meta files will be invisible as well. this option is especially useful for package builders. 🍓
  • -d — enable debugging for unionfs and libfuse. useful for developers if the code does not behave as expected. debug information will be written to stderr and a debug file (./unionfs_debug.log by default). two places. overachiever behavior, love that.
  • -o debug_file=file — write unionfs debug information into that file. pick your own destination, main character choice.
  • -o max_files=number — maximum number of open files. most systems have a default limit of 1024 open files per process. for example if unionfs serves "/", applications like KDE or GNOME might have many open files, making the unionfs process reach this limit and become unable to open further files. suggested value for "/" is >16000 or even >32000 files. like she needs room to breathe, okay?? 😭
  • -o noinitgroups — since version 0.23 without any effect, just left over for compatibility. might be removed in future versions. she's retired but still shows up to the group chat 💀
  • -o relaxed_permissions — usually we automatically add the libfuse option -o default_permissions so that libfuse takes over permission checks. however, if running not as root (so as UID != 0 and GID != 0), permissions on the underlying filesystem are already sufficient. and in order to prevent severe security issues, this option is not allowed if running as root. 🚨 read that again. not allowed as root. fr fr.
  • -o statfs_omit_ro — by default, blocks of all branches are counted in statfs() calls (e.g. by df). with this option, read-only branches will be omitted from the summary of blocks. this may sound weird, but it actually fixes "wrong" percentage of free space. she's not being quirky, she's being correct 💅

🌈 Options to libfuse 🌈

there are several further options available which don't directly apply to unionfs, but to libfuse. please run unionfs --help to see these. and btw, we already set -o default_permissions option on our own — we got you, bestie 🫶

🔥 EXAMPLES 🔥

look at her go:

 unionfs -o cow,max_files=32768 \
              -o allow_other,use_ino,suid,dev,nonempty \
              /u/host/etc=RW:/u/group/etc=RO:/u/common/etc=RO \
              /u/union/etc

iconic. ate. no notes. ✨

🧚 Meta data 🧚

like other filesystems, unionfs also needs to store meta data. well, presently only information about deleted files and directories needs to be stored, but in future releases more information might be required, e.g. inode-numbers for persistent inode information.

meta data information are saved and looked for in the .unionfs/ directories of each branch-root. so in the example above, these are:

  • /u/host/etc/.unionfs
  • /u/group/etc/.unionfs
  • /u/common/etc/.unionfs

within these directories a complete directory structure may be found.

example time 🌸: if the admin decides to delete the file /etc/test/testfile, which only exists in /u/unionfs/etc/test/testfile, unionfs can't delete this file, since it is on a read-only branch. so instead the whiteout file /u/host/etc/.unionfs/test/testfile_HIDDEN~ will be created. so on accessing the union filesystem, test/testfile will not be visible. she's not deleting, she's hiding. there's a difference 💅

please also note that whiteout files/directories will only hide the files in lower level branches. so for example whiteouts in the group directory (/u/group/etc/.unionfs of the example above) will only hide files of the common branch (/u/common/etc), but not these of the group and host branches. hierarchy matters, bestie.

and especially for diskless-booted environments it is rather useful for the admin to create whiteout files him/her-self. for example one should blacklist network re-initializations, /etc/mtab, /etc/nologin of the server, and several cron-scripts. this can be easily achieved by creating whiteout files for these scripts in the group meta directory. you're the admin, you're the main character, go hide things responsibly 👑

💀 KNOWN ISSUES 💀

  1. another issue is that presently there is no support for read-only branches when copy-on-write is disabled, thus, -ocow is NOT specified! support for that might be added in later releases.
yes that's genuinely a real limitation, not me being dramatic. if cow is off, read-only branches aren't supported. noted. logged. respect the constraint. 😭

👑 AUTHORS 👑

unionfs-fuse original implementation by Radek Podgorny <radek@podgorny.cz> — founder of the vibe, we stan. 🫶

Radek Podgorny <radek@podgorny.cz>, Bernd Schubert <bernd-schubert@gmx.de>

💜 THANKS 💜

many thanks to the author of the FUSE filesystem Miklos Szeredi. legend behavior, honestly. 🙏

and that's the whole page, bestie!! this was unionfs-fuse version 3.4, dated 2022, and you can find her under unionfs(8) any time you need her. now go mount something. slay 💅✨🎀

📦 where this page comes from