3.1.2 Checking the Storage Driver

The Docker Engine uses overlay2 as the default storage driver to manage Docker containers. The overlay2 storage driver can run into issues on systems using an XFS formatted file system that is not created with the -n ftype=1 option enabled. This is because overlay file systems depend on dtype support to handle metadata such as white outs for file deletion.

The root partition on Oracle Linux 7 is automatically formatted with -n ftype=0 where XFS is selected as the file system, disabling dtype support. On new installations of Docker, the package installer checks the file system format options to ensure that dtype support is available. If dtype support is not enabled, the installer overrides the default storage driver to use devicemapper to ensure that Docker is ready-to-use on newly installed systems. However, upgraded versions of Docker continue to use the storage driver that was configured in the previous release. This means that if you have configured Docker to use overlay2 on an underlying XFS-formatted file system, you may need to migrate the data to dedicated storage that has been formatted correctly.

Oracle recommends using Btrfs as a more stable and mature technology than overlayfs.

To check which storage driver and backing file system are configured on a running Docker Engine and to determine the path to the root Docker storage, run:

# docker info |grep 'Storage\|Filesystem\|Root'

If the storage driver is set to overlay2 and the backing file system is set to xfs, check that the XFS file system is formatted correctly:

# xfs_info /var/lib/docker |grep ftype

If necessary, replace /var/lib/docker with the path to the root Docker storage returned in the previous command. If the information returned by this command includes ftype=0, you must migrate the data held in this directory to storage that is formatted with support for overlay filesystems.

To migrate the storage:

  1. Attach a block storage device to the system where you are running Docker. Use the lsblk command to identify the device name and UUID. For example:

    # lsblk -o 'NAME,TYPE,UUID,MOUNTPOINT'

    If necessary, you may need to partition the device using a partitioning tool such as fdisk or parted.

  2. Format the block device with the XFS file system, for example to format a partition /dev/sdb1:

    # mkfs -t xfs -n ftype=1 /dev/sdb1

    It is essential that you use the -n ftype=1 option when you create the file system or you will not be able to use overlayfs.

  3. Temporarily mount the new file system, so that you can copy the contents from the existing Docker root directory:

    # mount -t xfs /dev/sdb1 /mnt
  4. Stop the Docker Engine, if it is running:

    # systemctl stop docker
  5. Move the existing Docker data to the new file system:

    # mv /var/lib/docker/* /mnt
  6. Unmount the new file system and remount it onto the Docker root directory:

    # umount /mnt
    # mount -t xfs /dev/sdb1 /var/lib/docker
  7. Create an entry in your fstab to ensure that the file system is mounted at boot. Open /etc/fstab in an editor and add a line similar to the following:

    UUID=UUID_value /var/lib/docker   xfs     defaults        0 0

    Replace UUID_value with the UUID value for the partition that you created. Use the lsblk or blkid command if you need to check the value.

Tip

If you do not have additional storage available for this purpose, it is possible to create an XFS file system image and loopback mount this. For example, to create a 25 GB image file in the root directory, you could use the following command:

# mkfs.xfs -d file=1,name=/DockerStorage,size=25g -n ftype=1

To temporarily mount this file, you can enter:

# mount -o loop -t xfs /DockerStorage /mnt

An entry in /etc/fstab, to make a permanent mount for Docker storage, may look similar to the following:

/DockerStorage    /var/lib/docker        xfs     loop            0 0 

This configuration can help as a temporary solution to solve upgrade issues. However, using a loopback mounted file system image as a form of permanent storage for Docker is not recommended for production environments.

See Section 2.7, “Configuring Docker Storage” for more information on setting up and configuring storage for Docker.