overlayfs: upper fs does not support file handles (nfs_export) Linux / DevOps

overlayfs: upper fs does not support file handles — Ошибка OverlayFS

Обновлено: 18.08.2026 · Официальная база знаний

Архитектура ошибки и симптомы сбоя

Сообщение «overlayfs: upper fs does not support file handles (nfs_export)» регистрируется драйвером ядра OverlayFS. Ошибка возникает при попытке смонтировать многослойную файловую систему с включенной опцией экспорта по NFS (nfs_export=on) или уникальной адресацией inode, когда вышележащая файловая система (Upper Layer FS) не поддерживает генерацию постоянных 64/128-битных файловых дескрипторов (File Handles / exportfs API). Это часто проявляется в Docker, containerd и Live-образах на нестандартных базовых ФС.

Диагностическая таблица параметров сбоя

Параметр	Значение	Инженерный смысл сбоя
nfs_export	OverlayFS Mount Option	Механизм кодирования file handle для экспорта OverlayFS по сети NFS.
Upper FS	Read-Write Layer	Слой записи (обычно ext4, XFS, tmpfs или btrfs).
File Handle Missing	NFS VFS Limitation	Базовая ФС не реализует методы `encode_fh() / fh_to_dentry()` в ядре.

Пошаговое дерево решений и сценарии траблшутинга

Сценарий 1: Отключение опции nfs_export при монтировании

Если экспорт слоя OverlayFS по сети NFS не требуется, принудительно отключите этот функционал:

# Ручное монтирование OverlayFS с отключением nfs_export и xino:
sudo mount -t overlay overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work,nfs_export=off /merged

# В /etc/fstab добавьте:
overlay /merged overlay noauto,x-systemd.automount,lowerdir=/lower,upperdir=/upper,workdir=/work,nfs_export=off 0 0

Сценарий 2: Отключение nfs_export в параметрах модуля overlay

Для контейнерных сред Docker / Podman отключите глобальный дефолт в параметрах ядра:

# Добавьте в /etc/modprobe.d/overlay.conf:
options overlay nfs_export=off xino=off

# Обновите initramfs:
sudo update-initramfs -u

Сценарий 3: Настройка поддерживаемой базовой файловой системы (XFS / ext4)

Если nfs_export=on критически необходим для работы NFS-сервера поверх Docker-контейнеров:

Убедитесь, что базовая ФС отформатирована с поддержкой file handles: mkfs.ext4 -O dir_index /dev/sdX.
Для XFS убедитесь, что включена опция ftype=1: mkfs.xfs -n ftype=1 /dev/sdX.
Исключите использование tmpfs в качестве upperdir при включенном nfs_export.

Контейнерный рантайм Docker / containerd не стартует из-за сбоев драйвера overlay2?
ITSTM выполнит аудит блочных уровней гипервизоров, миграцию на совместимые структуры XFS/ext4 и оптимизацию storage driver.

Практический опыт инженера: При развертывании Docker/Kubernetes на RHEL/CentOS всегда проверяйте, чтобы базовый раздел /var/lib/docker был отформатирован в XFS с параметром ftype=1, иначе драйвер overlay2 полностью откажется функционировать.

Частые вопросы (FAQ)

Для чего вообще нужен параметр nfs_export в OverlayFS?

Параметр nfs_export позволяет повторно экспортировать смонтированную структуру OverlayFS клиентам по протоколу NFS (v3/v4), транслируя постоянные файловые дескрипторы между всеми слоями (lower/upper).

Почему tmpfs не работает с nfs_export=on?

tmpfs — это память виртуальной ФС, которая не сохраняет постоянные структуры NFS file handles в ядре. При попытке назначить tmpfs в качестве upperdir модуль overlayfs выдает ошибку совместимости.

Что такое параметр xino в OverlayFS?

Параметр xino (eXtended Inode Numbers) транслирует и маппит номера inode из нижележащих слоев в единое 64-битное адресное пространство, предотвращая дублирование номеров inode в объединенном дереве файлов.

Как проверить текущие опции смонтированного контейнерного слоя?

Выполните команду: mount | grep overlay или просмотрите файл /proc/mounts.