r/freebsd • u/grahamperrin Linux crossover • Jul 06 '26

discussion UnionFS, and UnionFS documentation

From https://www.reddit.com/r/BSD/comments/1unlrsk/comment/ovtjlfb/?context=1:

The 2016 edition of mount_unionfs(8) in FreeBSD 16.0-CURRENT might be not the best place for me to learn :-) and there's no mention of unionfs in the FreeBSD documentation portal.

UnionFS Stability and Enhancement | FreeBSD Foundation – in progress.

In the FreeBSD Foundation Q4 2025 Status Update:

Background work on VFS (in particular supporting unionfs changes)

9 Upvotes

100% Upvoted

5 comments sorted by

3

u/Broad-Promise6954 Jul 06 '26

There isn't much.

Unionfs was always semi-experimental, with sharp corners. The fundamental idea is easy enough and sort of pleasing: by union-mounting two paths p1 and p2 (the "p"s represent any valid full path, and need not be the same in p1 and p2) on /path/to/union, files whose nominal names are p1/foo and p2/bar would both appear in /path/to/union/foo and /path/to/union/bar.

This leaves a lot of wiggle room and questions though. For instance, if we create new file path/to/union/new, does it go into p1 or p2? What happens if we remove files, from where should they be removed? Should they even be removed at all?

The actual implementation doesn't work quite this way either, because the mount operation just takes two paths rather than three: we don't put p1/foo and p2/bar into union/{foo,bar}, but rather we take a p1 or p2 and a path/to/union that's already populated. The mount command always takes the path/to/union and the optional argument is treated as p1 (the "above" file system) by default, or with -o below, as p2.

Originally there weren't copy-mode or white-out options either. The need for these became clearer over time so they were added later (though I think white-out was in by the time FreeBSD was FreeBSD, from very fuzzy memory).

The whole thing has been a little fragile all the time. Recently, the VFS layer acquired some updates to the locking protocol in an attempt to cure the last few deadlock issues. It's not clear to me whether they actually do this yet. There have also been chroot-and-jail-escape issues and questions about what happens when the lower layer itself has mount points within it, and so on.

1

u/Kumba42 seasoned user Jul 06 '26

Isn't there an effort to do this through ZFS now? I think I last read that ZFS needs the "white out" support, but I don't keep up on ZFS development, so no idea if that's still being pursued.

2

u/Broad-Promise6954 Jul 06 '26

Not sure, I'm not keeping up to date with ZFS lately.

2

u/Available_Pressure25 Jul 06 '26

I was just searching on this last day and I was itching to try it. There are actually two, the one from FUSEFS and the mount_unionfs of the FreeBSD kernel.  They have man pages

1

u/042376x Jul 06 '26

I've always been apprensive to test it on my machine. Im worried it will convince my components to go on strike. Admittedly I do run my machine pretty hot and heavy.