Docker: overlay2 on btrfs supported?

Hi, quick question: is docker’s overlay2 supposed to work on btrfs host?

Longer version: In order to avoid the known issues with docker’s btrfs driver (notably when it comes to exporting or moving), I thought I’d give overlay2 a try and proceeded like in the official docker documentation, but docker startup fails with level=error msg="failed to mount overlay: invalid argument" storage-driver=overlay2.

The container has been created using the following line:
lxc launch images:ubuntu/22.04 photoview -c security.nesting=true -c security.syscalls.intercept.mknod=true -c security.syscalls.intercept.setxattr=true
Docker version is docker.io/jammy-updates,now 20.10.21-0ubuntu1~22.04.2 from 22.04’s repository.
Host is Ubuntu 20.04 with btrfs everywhere. Kernel is standard ubuntu 5.15.0-67-generic.

My understanding (after searching a bit through the forums) was that overlay2 should work almost universally except on zfs.

I guess I could just go for vfs or use a lxd vm instead of a container, but first I’d like to make sure it’s not some user error on my side :wink:
(Or I’ll go with btrfs after all. If I understand correctly its “failure” mode is similar to what vfs does anyway.)

I’d be grateful for any guidance.

Ok, found the answer myself:

root@photoview:~# dmesg | grep overl
[270044.387623] overlayfs: idmapped layers are currently not supported
[270046.650667] overlayfs: idmapped layers are currently not supported
[270048.896203] overlayfs: idmapped layers are currently not supported
[270242.494895] overlayfs: idmapped layers are currently not supported
[270244.647997] overlayfs: idmapped layers are currently not supported
[270246.901194] overlayfs: idmapped layers are currently not supported
root@photoview:~# mount | grep idmap
/dev/sda4 on / type btrfs (rw,relatime,idmapped,

So maybe sometime in the future, but docker on lxd has quite a few gotchas. Maybe it would work if the host were running 22.04 and its newer kernel? This comment sounds as if it’s a solved issue by now.

Okay, time to upgrade my LXD host; kernel 5.19 should work fine: https://www.phoronix.com/news/OverlayFS-IDMAPPED-Layers

yes, it’s supported, but you need to update to the hwe kernel (5.19+), these kernels are available for Ubuntu 22.04 LTS.

1 Like

@Gilles
mknod doesn’t work with overlay2 though so you’ll have to use btrfs as backend storage driver for docker if that’s something you need (e.g. some docker containers rely on mknod)

you can test this as follows (assuming you have a kernel version > 5.19):

lxc init images:<whatever image you like> docker-ct
lxc config set docker-ct security{.nesting=true,.syscalls.intercept{.mknod=true,.setxattr=true}}
lxc start docker-ct
lxc exec docker-ct -- su -l
# here proceed to install docker then perform these steps
# vim /etc/docker/daemon.json 
# {
#         "storage-driver":"overlay2"
# }
# systemctl restart docker.service
docker run -it --rm busybox
# mknod /root/test c 1 3
# > mknod: /root/test: Operation not permitted

# replace overlay2 above with btrfs and repeat the test 
# and mknod should work now
1 Like

Thanks for pointing this out! Another gotcha to watch out for. I’ll see if the app I intend to run via docker is working fine even without mknod.

I’ve tried it just now with the current kernel (5.19.0-38-generic #39~22.04.1-Ubuntu), but it’s still not working correctly. But given this report on launchpad, I suppose you are aware of it :wink:

Hi @Gilles

This bug was fixed already:
https://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy/commit/fs/overlayfs?h=Ubuntu-hwe-5.19-5.19.0-40.41_22.04.1&id=74dcde33de700484913f474cd21ded0518443d95

AFAIU, you need to use hwe-5.19-5.19.0-40.41_22.04.1 kernel version.

@amikhalitsyn
Great! So I’ll just have to wait a few days(?) till it’s available via the regular repositories? Because right now the latest one I can get is 5.19.0-38.

unfortunately, I have no information about release queue and when this fix will be available in production. I think it’s worth to install -proposed kernel.

2 Likes