root@ubuntu:/home/ubuntu/overlay# ls -al /var/lib/docker/overlay2/l total 60 drwx------ 2 root root 4096 Oct 13 09:59 . drwx------ 16 root root 4096 Oct 13 09:59 .. lrwxrwxrwx 1 root root 72 Oct 10 16:40 DV6GEXARCBVAEZUJFL6KW3HSBJ -> ../71d1c02e60dfef29316cba9191b04c367381028e0518080f808b25087919ac41/diff lrwxrwxrwx 1 root root 72 Oct 10 16:16 GBVTARSEMDEDMBRBE7CECORBH6 -> ../0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df/diff lrwxrwxrwx 1 root root 77 Oct 10 16:16 I2CALNKEYKBOZMIZ67WXTUJ43D -> ../0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df-init/diff lrwxrwxrwx 1 root root 72 Oct 13 09:59 IYTF5KWSAFXCPURRBAMP22ACS3 -> ../5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 MN4IC4KQI4FAGG4ZIPEYHSPJGW -> ../5b5ae62b54531106bccfad465de30780c4f133693c74b804d87c3c2546541108/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 OHD7XJ4JW7PEYZRGBIBJZYTLYY -> ../6510d1f15249d407e43e6fa1246679929c8ddad57da56dc10b83f4cbaa17c705/diff lrwxrwxrwx 1 root root 72 Oct 9 20:00 P2FHY5TVXEA2IYWG37CHNM3MTE -> ../a09755a54062a2fb04311aa8630e9b97ce51209411c858165b5f681d562c5e9c/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 PWRZKLZFFPTNF76EUWJQWMXDXN -> ../3788a1d89b1bc944ba327ca0324eb9443031789e763601ee9750fa7d95437abd/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 QYAY6NY35IL5RIM4PE5ZLY7C44 -> ../7476c0bf71a728df117c608552402720681f87a8d4229d3e6550a3b00124df2e/diff lrwxrwxrwx 1 root root 72 Oct 10 16:40 R6NXNIP3FZ7H4ZJ5V3BSSUET3Y -> ../c38cdc062d10e73519af50b85880eee7848a5eee8c196a3e01378befa427b875/diff lrwxrwxrwx 1 root root 72 Oct 10 16:40 SASKARTZ26LG5BYUKMI5WXE6MR -> ../164f8b5ab975c5eceb93e5c9fdd4b38bbea82b9be02c174744803bddea4a11aa/diff lrwxrwxrwx 1 root root 77 Oct 13 09:59 SRXNCERMAR3GVIRILHRJYBDOLK -> ../5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987-init/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 XKGKOR5GBTIGTO6EHG22MIZ7NE -> ../7ba2254bf85fb157f24f026a04150bf5aa6b4d772454f5c6511a8993055e1c2e/diff root@ubuntu:/home/ubuntu/overlay#
root@ubuntu:/home/ubuntu/overlay# mount | grep overlay overlay on /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/merged type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /home/ubuntu/overlay/merged type overlay (rw,relatime,lowerdir=/home/ubuntu/overlay/lower,upperdir=/home/ubuntu/overlay/upper,workdir=/home/ubuntu/overlay/work,xino=off) root@ubuntu:/home/ubuntu/overlay#
root@ubuntu:/home/ubuntu# ls -i /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff/etc/nginx 8781915 conf.d root@ubuntu:/home/ubuntu# ls -i /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/merged/usr/sbin/nginx 8528334 /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/merged/usr/sbin/nginx root@ubuntu:/home/ubuntu#
root@ubuntu:/home/ubuntu# ls -i /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs/usr/sbin/nginx 8528334 /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs/usr/sbin/nginx
root@ubuntu:/home/ubuntu# lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT loop0 7:0 0 85.8M 1 loop /snap/core/9994 loop1 7:1 0 50M 0 loop /tmp/my-rootfs sda 8:0 0 3.7T 0 disk sdb 8:16 0 3.7T 0 disk sdc 8:32 0 222.6G 0 disk ├─sdc1 8:33 0 243M 0 part /boot/efi ├─sdc2 8:34 0 488M 0 part /boot └─sdc3 8:35 0 221.9G 0 part / root@ubuntu:/home/ubuntu# mount | grep sdc /dev/sdc3 on / type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc2 on /boot type ext4 (rw,relatime,stripe=256) /dev/sdc1 on /boot/efi type vfat (rw,relatime,fmask=0077,dmask=0077,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-4f91659c8b805cc0-resolv.conf type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-4f91659c8b805cc0-resolv.conf type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-2103ec8fc7ffd25a-hostname type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-2103ec8fc7ffd25a-hostname type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-c9ac2c282536032f-hosts type ext4 (rw,relatime,errors=remount-ro,stripe=64) /dev/sdc3 on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47-c9ac2c282536032f-hosts type ext4 (rw,relatime,errors=remount-ro,stripe=64) root@ubuntu:/home/ubuntu#
root@ubuntu:/home/ubuntu# ls -l /var/lib/docker/overlay2 total 48 drwx------ 4 root root 4096 Oct 10 16:16 0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df drwx------ 4 root root 4096 Oct 10 16:16 0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df-init drwx------ 3 root root 4096 Oct 10 16:40 164f8b5ab975c5eceb93e5c9fdd4b38bbea82b9be02c174744803bddea4a11aa drwx------ 4 root root 4096 Oct 9 20:03 3788a1d89b1bc944ba327ca0324eb9443031789e763601ee9750fa7d95437abd drwx------ 4 root root 4096 Oct 9 20:03 5b5ae62b54531106bccfad465de30780c4f133693c74b804d87c3c2546541108 drwx------ 4 root root 4096 Oct 9 20:03 6510d1f15249d407e43e6fa1246679929c8ddad57da56dc10b83f4cbaa17c705 drwx------ 4 root root 4096 Oct 10 16:40 71d1c02e60dfef29316cba9191b04c367381028e0518080f808b25087919ac41 drwx------ 4 root root 4096 Oct 9 20:03 7476c0bf71a728df117c608552402720681f87a8d4229d3e6550a3b00124df2e drwx------ 3 root root 4096 Oct 9 20:03 7ba2254bf85fb157f24f026a04150bf5aa6b4d772454f5c6511a8993055e1c2e drwx------ 3 root root 4096 Oct 9 20:00 a09755a54062a2fb04311aa8630e9b97ce51209411c858165b5f681d562c5e9c drwx------ 4 root root 4096 Oct 10 16:40 c38cdc062d10e73519af50b85880eee7848a5eee8c196a3e01378befa427b875 drwx------ 2 root root 4096 Oct 12 20:55 l root@ubuntu:/home/ubuntu# ls -l /var/lib/docker/overlay2/l total 44 lrwxrwxrwx 1 root root 72 Oct 10 16:40 DV6GEXARCBVAEZUJFL6KW3HSBJ -> ../71d1c02e60dfef29316cba9191b04c367381028e0518080f808b25087919ac41/diff lrwxrwxrwx 1 root root 72 Oct 10 16:16 GBVTARSEMDEDMBRBE7CECORBH6 -> ../0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df/diff lrwxrwxrwx 1 root root 77 Oct 10 16:16 I2CALNKEYKBOZMIZ67WXTUJ43D -> ../0c8fd8ebc4beeb02f1efb2ce0891c60bdc3ab39a557a3f28e8bdf4760156e5df-init/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 MN4IC4KQI4FAGG4ZIPEYHSPJGW -> ../5b5ae62b54531106bccfad465de30780c4f133693c74b804d87c3c2546541108/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 OHD7XJ4JW7PEYZRGBIBJZYTLYY -> ../6510d1f15249d407e43e6fa1246679929c8ddad57da56dc10b83f4cbaa17c705/diff lrwxrwxrwx 1 root root 72 Oct 9 20:00 P2FHY5TVXEA2IYWG37CHNM3MTE -> ../a09755a54062a2fb04311aa8630e9b97ce51209411c858165b5f681d562c5e9c/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 PWRZKLZFFPTNF76EUWJQWMXDXN -> ../3788a1d89b1bc944ba327ca0324eb9443031789e763601ee9750fa7d95437abd/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 QYAY6NY35IL5RIM4PE5ZLY7C44 -> ../7476c0bf71a728df117c608552402720681f87a8d4229d3e6550a3b00124df2e/diff lrwxrwxrwx 1 root root 72 Oct 10 16:40 R6NXNIP3FZ7H4ZJ5V3BSSUET3Y -> ../c38cdc062d10e73519af50b85880eee7848a5eee8c196a3e01378befa427b875/diff lrwxrwxrwx 1 root root 72 Oct 10 16:40 SASKARTZ26LG5BYUKMI5WXE6MR -> ../164f8b5ab975c5eceb93e5c9fdd4b38bbea82b9be02c174744803bddea4a11aa/diff lrwxrwxrwx 1 root root 72 Oct 9 20:03 XKGKOR5GBTIGTO6EHG22MIZ7NE -> ../7ba2254bf85fb157f24f026a04150bf5aa6b4d772454f5c6511a8993055e1c2e/diff root@ubuntu:/home/ubuntu#
root@ubuntu:/home/ubuntu# mount | grep overlay overlay on /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/merged type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off)
root@ubuntu:/home/ubuntu/overlay# mount | grep '/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK' overlay on /var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/merged type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/mounts/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) overlay on /run/kata-containers/shared/sandboxes/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/shared/419c8d922542e6c8edecfb5160345c76af47e56909d77a4034781e32d3d78f47/rootfs type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/SRXNCERMAR3GVIRILHRJYBDOLK:/var/lib/docker/overlay2/l/QYAY6NY35IL5RIM4PE5ZLY7C44:/var/lib/docker/overlay2/l/MN4IC4KQI4FAGG4ZIPEYHSPJGW:/var/lib/docker/overlay2/l/PWRZKLZFFPTNF76EUWJQWMXDXN:/var/lib/docker/overlay2/l/OHD7XJ4JW7PEYZRGBIBJZYTLYY:/var/lib/docker/overlay2/l/XKGKOR5GBTIGTO6EHG22MIZ7NE,upperdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/diff,workdir=/var/lib/docker/overlay2/5038d54a4f37f20842df884bf78087d42af5a01d1b054fa6446ea8597e4e1987/work,xino=off) root@ubuntu:/home/ubuntu/overlay#
OverlayFS is a modern union filesystem that is similar to AUFS, but faster and with a simpler implementation. Docker provides two storage drivers for OverlayFS: the original overlay
, and the newer and more stable overlay2
.
This topic refers to the Linux kernel driver as OverlayFS
and to the Docker storage driver as overlay
or overlay2
.
Note: If you use OverlayFS, use the
overlay2
driver rather than theoverlay
driver, because it is more efficient in terms of inode utilization. To use the new driver, you need version 4.0 or higher of the Linux kernel, or RHEL or CentOS using version 3.10.0-514 and above.For more information about differences between
overlay
vsoverlay2
, check Docker storage drivers.
Prerequisites
OverlayFS is supported if you meet the following prerequisites:
- The
overlay2
driver is supported on Docker Engine - Community, and Docker EE 17.06.02-ee5 and up, and is the recommended storage driver. - Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using version 3.10.0-514 of the kernel or higher. If you use an older kernel, you need to use the
overlay
driver, which is not recommended. -
The
overlay
andoverlay2
drivers are supported onxfs
backing filesystems, but only withd_type=true
enabled.Use
xfs_info
to verify that theftype
option is set to1
. To format anxfs
filesystem correctly, use the flag-n ftype=1
.Warning: Running on XFS without d_type support now causes Docker to skip the attempt to use the
overlay
oroverlay2
driver. Existing installs will continue to run, but produce an error. This is to allow users to migrate their data. In a future version, this will be a fatal error, which will prevent Docker from starting. - Changing the storage driver makes existing containers and images inaccessible on the local system. Use
docker save
to save any images you have built or push them to Docker Hub or a private registry before changing the storage driver, so that you do not need to re-create them later.
Configure Docker with the overlay
or overlay2
storage driver
It is highly recommended that you use the overlay2
driver if possible, rather than the overlay
driver. The overlay
driver is not supported for Docker EE.
To configure Docker to use the overlay
storage driver your Docker host must be running version 3.18 of the Linux kernel (preferably newer) with the overlay kernel module loaded. For the overlay2
driver, the version of your kernel must be 4.0 or newer.
Before following this procedure, you must first meet all the prerequisites.
The steps below outline how to configure the overlay2
storage driver. If you need to use the legacy overlay
driver, specify it instead.
-
Stop Docker.
$ sudo systemctl stop docker
-
Copy the contents of
/var/lib/docker
to a temporary location.$ cp -au /var/lib/docker /var/lib/docker.bk
-
If you want to use a separate backing filesystem from the one used by
/var/lib/
, format the filesystem and mount it into/var/lib/docker
. Make sure add this mount to/etc/fstab
to make it permanent. -
Edit
/etc/docker/daemon.json
. If it does not yet exist, create it. Assuming that the file was empty, add the following contents.{ "storage-driver": "overlay2" }
Docker does not start if the
daemon.json
file contains badly-formed JSON. -
Start Docker.
$ sudo systemctl start docker
-
Verify that the daemon is using the
overlay2
storage driver. Use thedocker info
command and look forStorage Driver
andBacking filesystem
.$ docker info Containers: 0 Images: 0 Storage Driver: overlay2 Backing Filesystem: xfs Supports d_type: true Native Overlay Diff: true <output truncated>
Docker is now using the overlay2
storage driver and has automatically created the overlay mount with the required lowerdir
, upperdir
, merged
, and workdir
constructs.
Continue reading for details about how OverlayFS works within your Docker containers, as well as performance advice and information about limitations of its compatibility with different backing filesystems.
How the overlay2
driver works
If you are still using the overlay
driver rather than overlay2
, see How the overlay driver works instead.
OverlayFS layers two directories on a single Linux host and presents them as a single directory. These directories are called layers and the unification process is referred to as a union mount. OverlayFS refers to the lower directory as lowerdir
and the upper directory a upperdir
. The unified view is exposed through its own directory called merged
.
The overlay2
driver natively supports up to 128 lower OverlayFS layers. This capability provides better performance for layer-related Docker commands such as docker build
and docker commit
, and consumes fewer inodes on the backing filesystem.
Image and container layers on-disk
After downloading a five-layer image using docker pull ubuntu
, you can see six directories under /var/lib/docker/overlay2
.
Warning: Do not directly manipulate any files or directories within
/var/lib/docker/
. These files and directories are managed by Docker.
$ ls -l /var/lib/docker/overlay2
total 24
drwx------ 5 root root 4096 Jun 20 07:36 223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7
drwx------ 3 root root 4096 Jun 20 07:36 3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b
drwx------ 5 root root 4096 Jun 20 07:36 4e9fa83caff3e8f4cc83693fa407a4a9fac9573deaf481506c102d484dd1e6a1
drwx------ 5 root root 4096 Jun 20 07:36 e8876a226237217ec61c4baf238a32992291d059fdac95ed6303bdff3f59cff5
drwx------ 5 root root 4096 Jun 20 07:36 eca1e4e1694283e001f200a667bb3cb40853cf2d1b12c29feda7422fed78afed
drwx------ 2 root root 4096 Jun 20 07:36 l
The new l
(lowercase L
) directory contains shortened layer identifiers as symbolic links. These identifiers are used to avoid hitting the page size limitation on arguments to the mount
command.
$ ls -l /var/lib/docker/overlay2/l
total 20
lrwxrwxrwx 1 root root 72 Jun 20 07:36 6Y5IM2XC7TSNIJZZFLJCS6I4I4 -> ../3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 B3WWEFKBG3PLLV737KZFIASSW7 -> ../4e9fa83caff3e8f4cc83693fa407a4a9fac9573deaf481506c102d484dd1e6a1/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 JEYMODZYFCZFYSDABYXD5MF6YO -> ../eca1e4e1694283e001f200a667bb3cb40853cf2d1b12c29feda7422fed78afed/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 NFYKDW6APBCCUCTOUSYDH4DXAT -> ../223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 UL2MW33MSE3Q5VYIKBRN4ZAGQP -> ../e8876a226237217ec61c4baf238a32992291d059fdac95ed6303bdff3f59cff5/diff
The lowest layer contains a file called link
, which contains the name of the shortened identifier, and a directory called diff
which contains the layer’s contents.
$ ls /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/
diff link
$ cat /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/link
6Y5IM2XC7TSNIJZZFLJCS6I4I4
$ ls /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/diff
bin boot dev etc home lib lib64 media mnt opt proc root run sbin srv sys tmp usr var
The second-lowest layer, and each higher layer, contain a file called lower
, which denotes its parent, and a directory called diff
which contains its contents. It also contains a merged
directory, which contains the unified contents of its parent layer and itself, and a work
directory which is used internally by OverlayFS.
$ ls /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7
diff link lower merged work
$ cat /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/lower
l/6Y5IM2XC7TSNIJZZFLJCS6I4I4
$ ls /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/diff/
etc sbin usr var
To view the mounts which exist when you use the overlay
storage driver with Docker, use the mount
command. The output below is truncated for readability.
$ mount | grep overlay
overlay on /var/lib/docker/overlay2/9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/merged
type overlay (rw,relatime,
lowerdir=l/DJA75GUWHWG7EWICFYX54FIOVT:l/B3WWEFKBG3PLLV737KZFIASSW7:l/JEYMODZYFCZFYSDABYXD5MF6YO:l/UL2MW33MSE3Q5VYIKBRN4ZAGQP:l/NFYKDW6APBCCUCTOUSYDH4DXAT:l/6Y5IM2XC7TSNIJZZFLJCS6I4I4,
upperdir=9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/diff,
workdir=9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/work)
The rw
on the second line shows that the overlay
mount is read-write.
How the overlay
driver works
This content applies to the overlay
driver only. Docker recommends using the overlay2
driver, which works differently. See How the overlay2 driver works for overlay2
.
OverlayFS layers two directories on a single Linux host and presents them as a single directory. These directories are called layers and the unification process is referred to as a union mount. OverlayFS refers to the lower directory as lowerdir
and the upper directory a upperdir
. The unified view is exposed through its own directory called merged
.
The diagram below shows how a Docker image and a Docker container are layered. The image layer is the lowerdir
and the container layer is the upperdir
. The unified view is exposed through a directory called merged
which is effectively the containers mount point. The diagram shows how Docker constructs map to OverlayFS constructs.
Where the image layer and the container layer contain the same files, the container layer “wins” and obscures the existence of the same files in the image layer.
The overlay
driver only works with two layers. This means that multi-layered images cannot be implemented as multiple OverlayFS layers. Instead, each image layer is implemented as its own directory under /var/lib/docker/overlay
. Hard links are then used as a space-efficient way to reference data shared with lower layers. The use of hardlinks causes an excessive use of inodes, which is a known limitation of the legacy overlay
storage driver, and may require additional configuration of the backing filesystem. Refer to the overlayFS and Docker performance for details.
To create a container, the overlay
driver combines the directory representing the image’s top layer plus a new directory for the container. The image’s top layer is the lowerdir
in the overlay and is read-only. The new directory for the container is the upperdir
and is writable.
Image and container layers on-disk
The following docker pull
command shows a Docker host downloading a Docker image comprising five layers.
$ docker pull ubuntu
Using default tag: latest
latest: Pulling from library/ubuntu
5ba4f30e5bea: Pull complete
9d7d19c9dc56: Pull complete
ac6ad7efd0f9: Pull complete
e7491a747824: Pull complete
a3ed95caeb02: Pull complete
Digest: sha256:46fb5d001b88ad904c5c732b086b596b92cfb4a4840a3abd0e35dbb6870585e4
Status: Downloaded newer image for ubuntu:latest
THE IMAGE LAYERS
Each image layer has its own directory within /var/lib/docker/overlay/
, which contains its contents, as shown below. The image layer IDs do not correspond to the directory IDs.
Warning: Do not directly manipulate any files or directories within
/var/lib/docker/
. These files and directories are managed by Docker.
$ ls -l /var/lib/docker/overlay/
total 20
drwx------ 3 root root 4096 Jun 20 16:11 38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8
drwx------ 3 root root 4096 Jun 20 16:11 55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358
drwx------ 3 root root 4096 Jun 20 16:11 824c8a961a4f5e8fe4f4243dab57c5be798e7fd195f6d88ab06aea92ba931654
drwx------ 3 root root 4096 Jun 20 16:11 ad0fe55125ebf599da124da175174a4b8c1878afe6907bf7c78570341f308461
drwx------ 3 root root 4096 Jun 20 16:11 edab9b5e5bf73f2997524eebeac1de4cf9c8b904fa8ad3ec43b3504196aa3801
The image layer directories contain the files unique to that layer as well as hard links to the data that is shared with lower layers. This allows for efficient use of disk space.
$ ls -i /var/lib/docker/overlay/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls
19793696 /var/lib/docker/overlay/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls
$ ls -i /var/lib/docker/overlay/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls
19793696 /var/lib/docker/overlay/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls
THE CONTAINER LAYER
Containers also exist on-disk in the Docker host’s filesystem under /var/lib/docker/overlay/
. If you list a running container’s subdirectory using the ls -l
command, three directories and one file exist:
$ ls -l /var/lib/docker/overlay/<directory-of-running-container>
total 16
-rw-r--r-- 1 root root 64 Jun 20 16:39 lower-id
drwxr-xr-x 1 root root 4096 Jun 20 16:39 merged
drwxr-xr-x 4 root root 4096 Jun 20 16:39 upper
drwx------ 3 root root 4096 Jun 20 16:39 work
The lower-id
file contains the ID of the top layer of the image the container is based on, which is the OverlayFS lowerdir
.
$ cat /var/lib/docker/overlay/ec444863a55a9f1ca2df72223d459c5d940a721b2288ff86a3f27be28b53be6c/lower-id
55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358
The upper
directory contains the contents of the container’s read-write layer, which corresponds to the OverlayFS upperdir
.
The merged
directory is the union mount of the lowerdir
and upperdir
, which comprises the view of the filesystem from within the running container.
The work
directory is internal to OverlayFS.
To view the mounts which exist when you use the overlay
storage driver with Docker, use the mount
command. The output below is truncated for readability.
$ mount | grep overlay
overlay on /var/lib/docker/overlay/ec444863a55a.../merged
type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay/55f1e14c361b.../root,
upperdir=/var/lib/docker/overlay/ec444863a55a.../upper,
workdir=/var/lib/docker/overlay/ec444863a55a.../work)
The rw
on the second line shows that the overlay
mount is read-write.
How container reads and writes work with overlay
or overlay2
Reading files
Consider three scenarios where a container opens a file for read access with overlay.
-
The file does not exist in the container layer: If a container opens a file for read access and the file does not already exist in the container (
upperdir
) it is read from the image (lowerdir)
. This incurs very little performance overhead. -
The file only exists in the container layer: If a container opens a file for read access and the file exists in the container (
upperdir
) and not in the image (lowerdir
), it is read directly from the container. -
The file exists in both the container layer and the image layer: If a container opens a file for read access and the file exists in the image layer and the container layer, the file’s version in the container layer is read. Files in the container layer (
upperdir
) obscure files with the same name in the image layer (lowerdir
).
Modifying files or directories
Consider some scenarios where files in a container are modified.
-
Writing to a file for the first time: The first time a container writes to an existing file, that file does not exist in the container (
upperdir
). Theoverlay
/overlay2
driver performs a copy_up operation to copy the file from the image (lowerdir
) to the container (upperdir
). The container then writes the changes to the new copy of the file in the container layer.However, OverlayFS works at the file level rather than the block level. This means that all OverlayFS copy_up operations copy the entire file, even if the file is very large and only a small part of it is being modified. This can have a noticeable impact on container write performance. However, two things are worth noting:
-
The copy_up operation only occurs the first time a given file is written to. Subsequent writes to the same file operate against the copy of the file already copied up to the container.
-
OverlayFS only works with two layers. This means that performance should be better than AUFS, which can suffer noticeable latencies when searching for files in images with many layers. This advantage applies to both
overlay
andoverlay2
drivers.overlayfs2
is slightly less performant thanoverlayfs
on initial read, because it must look through more layers, but it caches the results so this is only a small penalty.
-
-
Deleting files and directories:
-
When a file is deleted within a container, a whiteout file is created in the container (
upperdir
). The version of the file in the image layer (lowerdir
) is not deleted (because thelowerdir
is read-only). However, the whiteout file prevents it from being available to the container. -
When a directory is deleted within a container, an opaque directory is created within the container (
upperdir
). This works in the same way as a whiteout file and effectively prevents the directory from being accessed, even though it still exists in the image (lowerdir
).
-
-
Renaming directories: Calling
rename(2)
for a directory is allowed only when both the source and the destination path are on the top layer. Otherwise, it returnsEXDEV
error (“cross-device link not permitted”). Your application needs to be designed to handleEXDEV
and fall back to a “copy and unlink” strategy.
OverlayFS and Docker Performance
Both overlay2
and overlay
drivers are more performant than aufs
and devicemapper
. In certain circumstances, overlay2
may perform better than btrfs
as well. However, be aware of the following details.
-
Page Caching. OverlayFS supports page cache sharing. Multiple containers accessing the same file share a single page cache entry for that file. This makes the
overlay
andoverlay2
drivers efficient with memory and a good option for high-density use cases such as PaaS. -
copy_up. As with AUFS, OverlayFS performs copy-up operations whenever a container writes to a file for the first time. This can add latency into the write operation, especially for large files. However, once the file has been copied up, all subsequent writes to that file occur in the upper layer, without the need for further copy-up operations.
The OverlayFS
copy_up
operation is faster than the same operation with AUFS, because AUFS supports more layers than OverlayFS and it is possible to incur far larger latencies if searching through many AUFS layers.overlay2
supports multiple layers as well, but mitigates any performance hit with caching. -
Inode limits. Use of the legacy
overlay
storage driver can cause excessive inode consumption. This is especially true in the presence of a large number of images and containers on the Docker host. The only way to increase the number of inodes available to a filesystem is to reformat it. To avoid running into this issue, it is highly recommended that you useoverlay2
if at all possible.
Performance best practices
The following generic performance best practices also apply to OverlayFS.
-
Use fast storage: Solid-state drives (SSDs) provide faster reads and writes than spinning disks.
-
Use volumes for write-heavy workloads: Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and do not incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting your data even if no running container is using them.