Support for including nested mountpoints in overlay?

Support for including nested mountpoints in overlay?

[Nicholas Hubbard]

[-- Attachment #1: Type: text/plain, Size: 1438 bytes --]

Hello everybody,

I have just started working with overlayfs, and ran into a problem. Specifically
I wanted to overlay the root of my filesystem with a command like the following:

# mount -t overlay overlay -o lowerdir=/,upperdir=./tmp-upper,workdir=./tmp-work ./merged

However, I noticed that my nested btrfs subvolumes and boot partition were not
included in ./merged. I quickly learned though that you could have multiple
lowerdirs. So next I tried the following command (I have a nested btrfs subvolume
at /home, and my boot partition mounted at /boot):

# mount -t overlay overlay -o lowerdir=/:/home:/boot,upperdir=./tmp-upper,workdir=./tmp-work ./merged

I was expecting that now I would have (for example) the following directories:

./merged/home/$USER
./merged/boot/grub

However I instead had:

./merged/$USER
./merged/grub

Which shows that all the lowerdirs are placed right at the root of the mergedir.

So I have two questions.

1. Is there a (easy) way say "I want to include all nested mountpoints into the
   overlay in their same directories"?
2. If there is not a (easy) way to do this, do you think it would be both feasible
   and useful to add such a feature?

If the answer to question 2 is "yes", then I would be happy to take a try at this :)

-- 
Nicholas B. Hubbard
Keys: https://github.com/NicholasBHubbard/public-keys
Key ID: 508022AE06C2C446D8072447C700A066BB25F148

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

Re: Support for including nested mountpoints in overlay?

[Amir Goldstein]

On Fri, Sep 12, 2025 at 5:55 PM Nicholas Hubbard
<nicholashubbard@posteo.net> wrote:
>
> Hello everybody,
>
> I have just started working with overlayfs, and ran into a problem. Specifically
> I wanted to overlay the root of my filesystem with a command like the following:
>
> # mount -t overlay overlay -o lowerdir=/,upperdir=./tmp-upper,workdir=./tmp-work ./merged
>
> However, I noticed that my nested btrfs subvolumes and boot partition were not
> included in ./merged. I quickly learned though that you could have multiple
> lowerdirs. So next I tried the following command (I have a nested btrfs subvolume
> at /home, and my boot partition mounted at /boot):
>
> # mount -t overlay overlay -o lowerdir=/:/home:/boot,upperdir=./tmp-upper,workdir=./tmp-work ./merged
>
> I was expecting that now I would have (for example) the following directories:
>
> ./merged/home/$USER
> ./merged/boot/grub
>
> However I instead had:
>
> ./merged/$USER
> ./merged/grub
>
> Which shows that all the lowerdirs are placed right at the root of the mergedir.
>
> So I have two questions.
>
> 1. Is there a (easy) way say "I want to include all nested mountpoints into the
>    overlay in their same directories"?

No. not in general. but maybe specifically for btrfs subvolumes
you can do it because they are all accessible via the btrfs root mount.

If all your lower dirs are on the same btrfs filesystem
and the subvolumes are also accessible via some path is root mount
(e.g. /subvols), then something like may work for you:

mount -t overlay overlay -o
lowerdir=/,upperdir=./tmp-upper,workdir=./tmp-work ./merged

rmdir ./merged/home
rmdir ./merged/boot
mv ./merged/subvols/home ./merged/home
mv ./merged/subvols/boot ./merged/boot

Never tried it with btrfs subvols, so it may not work.

> 2. If there is not a (easy) way to do this, do you think it would be both feasible
>    and useful to add such a feature?

The general case of "include all nested mountpoints" is just way too far off
from the current overlayfs design. Too hard to explain why.

I suggest that you look at FUSE alternatives like
https://github.com/trapexit/mergerfs

Not sure if mergerfs supports this use case, but I think a userspace
union fs is in a better position to add support to this if desired.

Thanks,
Amir.