Debian/Ubuntu: как исправить overlayfs invalid argument и operation not permitted в rootless Docker

Rootless Docker на Debian и Ubuntu обычно выбирают ради более безопасного запуска контейнеров без постоянной работы демона от root. Но именно в rootless-режиме чаще всего всплывают две неприятные ошибки: overlayfs: invalid argument и operation not permitted. На практике это почти всегда означает не «Docker сломан», а несовпадение между storage driver, возможностями ядра, типом файловой системы и ограничениями user namespaces.

Проблема особенно заметна после свежей установки rootless Docker, миграции на новый сервер, обновления ядра или переноса каталога данных в нестандартный раздел. Частый сценарий такой: обычный Docker от root работает, а rootless Docker не стартует или падает при первом же запуске контейнера.

Ниже разберём, как быстро локализовать источник ошибки, когда виноват именно overlayfs, когда проблема в subordinate UID/GID или sysctl, и почему в большинстве случаев самым практичным решением оказывается fuse-overlayfs.

Сразу важный ориентир: rootless Docker не обязан вести себя точно так же, как rootful-режим. Rootless зависит от того, какие функции ядра доступны непривилегированному пользователю, а это уже комбинация версии ядра, настроек дистрибутива, поддержки FUSE и типа файловой системы под домашним каталогом.

Именно поэтому одна и та же инструкция может сработать на Ubuntu 24.04 и не сработать на Debian 11 со старым ядром или на сервере, где домашний каталог лежит на сетевой ФС. Ошибка одна, причин несколько. Лучше идти по короткой диагностической схеме, чем переустанавливать Docker вслепую.

Что на самом деле означают эти ошибки

Когда rootless Docker пытается использовать overlayfs как storage driver, он рассчитывает, что ядро разрешит непривилегированному процессу создать нужный тип overlay-монтажа внутри user namespace. Если эта возможность недоступна, появляются сообщения вроде:

overlayfs: invalid argument

operation not permitted

Иногда они видны прямо в логах пользовательского демона Docker, иногда всплывают при старте контейнера, а иногда Docker не поднимается вовсе из-за ошибки инициализации драйвера хранения.

На практике чаще всего срабатывает один из четырёх сценариев:

• ядро не поддерживает нужный режим работы overlayfs для rootless;
• mount-операции внутри user namespaces ограничены политикой системы или виртуализации;
• каталог данных Docker расположен на неподходящей файловой системе;
• не установлен или не используется fuse-overlayfs, который в rootless-режиме должен заменить обычный overlay.

Если коротко: такая ошибка редко лечится переустановкой Docker. Обычно помогает либо корректная настройка rootless-окружения, либо явный переход на fuse-overlayfs.

С чего начать диагностику на Debian и Ubuntu

Первое правило — не ограничиваться одной командой docker info. В rootless-режиме важнее проверить, стартует ли пользовательский systemd-сервис и что именно пишет журнал при инициализации storage driver.

Сначала посмотрите статус и последние логи rootless daemon:

systemctl --user status docker

journalctl --user -u docker -n 200 --no-pager

Если в журнале есть строки с overlay2, fuse-overlayfs, failed to mount overlay, operation not permitted или backing filesystem, это уже сильно сужает круг поиска.

Затем проверьте, какой storage driver Docker пытается использовать сейчас:

docker info | sed -n '/Storage Driver/,+8p'

Если демон не поднимается, команда может не ответить. В таком случае опирайтесь на журнал и конфигурацию. В рабочем режиме вы обычно увидите overlay2, fuse-overlayfs или, как временный аварийный вариант, vfs.

Следующий шаг — проверить subordinate UID и GID. Без них rootless Docker либо не работает нормально, либо ведёт себя нестабильно:

grep ^$(whoami): /etc/subuid /etc/subgid

Ожидаемый результат выглядит примерно так:

/etc/subuid:alice:100000:65536
/etc/subgid:alice:100000:65536

Если записей нет, rootless-окружение настроено не до конца, и ошибки storage driver могут быть лишь следствием.

Облачный VDS-сервер в России

Аренда виртуальных серверов с моментальным развертыванием инфраструктуры от 195₽ / мес

Подробнее

Почему overlayfs ломается именно в rootless Docker

Самая частая ошибка в ожиданиях — считать, что overlay2 в rootless Docker обязан работать так же, как в обычном Docker. Это неверно. В rootful-режиме демон имеет root-привилегии и использует возможности ядра напрямую. В rootless всё упирается в то, что разрешено обычному пользователю внутри user namespace.

На Debian и Ubuntu поведение зависит и от версии ядра, и от того, как именно собран kernel package. Даже если модуль overlay загружен, это ещё не гарантирует, что rootless-монтаж будет разрешён.

Отдельная история — файловая система. Если каталог данных rootless Docker лежит на NFS, CIFS или другой сетевой файловой системе, ошибки invalid argument и operation not permitted встречаются заметно чаще. Похожие симптомы бывают и при нестандартных mount options, недоступном FUSE или nested-окружении вроде LXC.

Проверить, где именно расположен каталог данных Docker, лучше до любых изменений:

docker info | sed -n '/Docker Root Dir/p'

findmnt -T ~/.local/share/docker

Вторая команда особенно полезна, если демон не стартует. Она покажет тип файловой системы и параметры монтирования. Если там сетевой storage или экзотическая ФС, это уже серьёзная зацепка.

Бывает и так, что rootless Docker на одном и том же сервере работает у одного пользователя и ломается у другого. Причина обычно в разном расположении домашних каталогов, разных subordinate ID, лимитах или окружении пользовательской systemd-сессии.

Если вы строите контейнерную инфраструктуру на отдельном сервере, где можно контролировать ядро, FUSE и файловую систему, это проще и предсказуемее делать на VDS, чем в окружении с непрозрачными ограничениями хоста.

Когда нужен fuse-overlayfs и почему это штатный вариант

fuse-overlayfs — не обходной трюк, а нормальный и часто рекомендуемый способ организовать union filesystem в rootless-режиме там, где обычный overlay недоступен или нестабилен. Для Debian и Ubuntu это очень часто самый предсказуемый путь.

Смысл простой: вместо попытки использовать kernel overlay напрямую Docker обращается к FUSE-реализации, которая лучше совместима с непривилегированным запуском. Да, в некоторых сценариях это может быть чуть медленнее, чем rootful overlay2, но зато убирает целый класс ошибок с mount-операциями.

Проверить наличие пакета можно так:

which fuse-overlayfs

dpkg -l | grep fuse-overlayfs

Если пакета нет, обычно достаточно установить его вместе с зависимостями rootless-режима:

sudo apt update

sudo apt install -y fuse-overlayfs uidmap dbus-user-session

Пакеты uidmap и dbus-user-session тоже важны: без них rootless Docker нередко запускается частично или нестабильно, особенно если установка делалась вручную.

Как проверить, что Docker действительно использует fuse-overlayfs

После установки перезапустите пользовательский демон и проверьте, какой driver активен:

systemctl --user restart docker

docker info

В зависимости от версии Docker вы увидите либо явный storage driver fuse-overlayfs, либо косвенные признаки его использования в статусе драйвера. Если после этого контейнеры начали запускаться, то корень проблемы почти наверняка был именно в несовместимости обычного overlayfs с rootless-режимом.

Если у вас уже есть важные контейнеры и образы, не меняйте storage driver без резервной копии. Для Docker это смена базового механизма хранения, а не косметическая настройка.

Проверка user namespaces без лишней магии

Rootless Docker критически зависит от рабочих user namespaces. Если они выключены, урезаны политикой безопасности или пользователю не выделены subordinate ID, ошибки storage driver будут только верхушкой айсберга.

Проверьте базовые параметры ядра:

sysctl kernel.unprivileged_userns_clone

sysctl user.max_user_namespaces

Для Debian и Ubuntu обычно ожидается, что kernel.unprivileged_userns_clone разрешён, а user.max_user_namespaces больше нуля. Если видите запрет, rootless Docker не сможет нормально работать в принципе.

При необходимости значения можно задать явно:

echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/99-rootless.conf

echo 'user.max_user_namespaces=28633' | sudo tee -a /etc/sysctl.d/99-rootless.conf

sudo sysctl --system

Конкретное число для user.max_user_namespaces может быть и другим. Важен сам факт ненулевого лимита и понимание того, что такая настройка допустима в вашей политике безопасности.

Если параллельно вы разбираетесь с сетевыми проблемами контейнеров, полезно отдельно свериться с материалом про настройку Docker с iptables и nftables: storage и сетевой стек часто ломаются одновременно, но причины у них разные.

Типовые сценарии, где ошибка повторяется снова и снова

На реальных серверах чаще всего встречаются несколько повторяющихся кейсов. Их стоит проверить до переустановки Docker и до очистки каталога данных.

Домашний каталог на сетевой файловой системе

Если ~/.local/share/docker лежит на NFS или CIFS, rootless Docker часто конфликтует и с overlay, и с семантикой файловых атрибутов. В таком случае правильнее перенести данные на локальную файловую систему, например ext4 или XFS с совместимыми параметрами.

Rootless Docker внутри контейнера

Если вы запускаете rootless Docker внутри LXC, systemd-nspawn или другого контейнера, ошибка operation not permitted может означать, что внешний слой виртуализации просто запрещает нужные mount-операции или работу FUSE. Тогда проблема не в Debian или Ubuntu как таковых, а в ограничениях хоста.

Старое ядро или нестандартная сборка

На старых ветках Debian и Ubuntu, особенно с кастомным kernel, поведение overlayfs внутри user namespaces может отличаться от того, что ожидают современные версии Docker. Если Docker сравнительно новый, а ядро старое, совместимость может оказаться неполной.

FUSE установлен, но фактически недоступен

Иногда пакет fuse-overlayfs есть, но само устройство FUSE недоступно или заблокировано политикой хоста. В этом случае переход на FUSE не помогает, и в логах снова появляются ошибки доступа. Тогда проверять нужно уже не пакет, а возможность работы FUSE в конкретной виртуализации.

Виртуальный хостинг для сайтов

Универсальное решение для создания и размещения сайтов любой сложности в Интернете от 95₽ / мес

Подробнее

Как безопасно переключить storage driver в rootless Docker

На рабочем сервере нельзя менять storage driver наугад. Для Docker это означает смену способа хранения образов и слоёв, поэтому старые данные автоматически не «переедут» в новый драйвер без последствий.

Если rootless Docker только что установлен и в нём ещё нет полезных данных, проще добиться корректного старта с fuse-overlayfs и начать с чистого состояния. Если контейнеры уже используются, сначала сделайте экспорт образов, резервные копии томов и проверьте сценарий отката.

Посмотреть пользовательский конфиг демона можно так:

cat ~/.config/docker/daemon.json

Если нужно явно задать storage driver, минимальный конфиг будет таким:

{
  "storage-driver": "fuse-overlayfs"
}

После изменения конфигурации перезапустите пользовательский сервис и снова проверьте статус драйвера:

systemctl --user daemon-reload

systemctl --user restart docker

docker info | sed -n '/Storage Driver/,+8p'

Если демон не стартует и после этого, не меняйте несколько параметров сразу. Вернитесь к логам через journalctl --user -u docker и проверьте, не упирается ли проблема в FUSE, ФС или ограничения виртуализации.

Что делать, если даже fuse-overlayfs не помогает

Если после установки fuse-overlayfs и проверки user namespaces ошибка остаётся, идите по короткому чек-листу:

1. Проверьте, что FUSE реально доступен и не запрещён хостом.
2. Уточните тип файловой системы под ~/.local/share/docker.
3. Смотрите журнал user service, а не только вывод клиента.
4. Проверьте, не запускается ли rootless Docker внутри ограниченного контейнера.
5. Сверьте версию ядра и версию Docker.
6. На короткое время протестируйте vfs только как диагностический шаг.

Переход на vfs полезен не как постоянное решение, а как способ доказать, что ломается именно overlay-слой. Если на vfs демон стартует и контейнеры запускаются, значит сеть, namespaces и базовая логика Docker в порядке, а проблема локализуется в storage backend.

Минимальный временный конфиг выглядит так:

{
  "storage-driver": "vfs"
}

Если с ним всё заработало, почти наверняка нужно возвращаться к вопросу поддержки fuse-overlayfs, типа файловой системы или ограничений хоста. Оставлять vfs в продакшене обычно не хочется из-за потерь производительности и расхода диска.

Практический алгоритм восстановления за 10–15 минут

Если нужен короткий рабочий сценарий без лишней теории, используйте такой порядок:

1. Проверьте статус rootless daemon и последние логи.
2. Убедитесь, что у пользователя есть записи в /etc/subuid и /etc/subgid.
3. Проверьте sysctl для kernel.unprivileged_userns_clone и лимит user.max_user_namespaces.
4. Посмотрите тип файловой системы для ~/.local/share/docker.
5. Установите fuse-overlayfs, uidmap и dbus-user-session.
6. Явно задайте storage-driver как fuse-overlayfs.
7. Перезапустите systemctl --user restart docker.
8. Проверьте docker info и тестовый запуск контейнера.

Для быстрой проверки после исправления подойдёт простой тест:

docker run --rm hello-world

Если контейнер стартует, а в docker info отображается корректный storage driver, значит основной барьер снят. Дальше можно возвращать рабочие образы и compose-проекты.

Когда разумнее отказаться от rootless на конкретном узле

Rootless Docker полезен по модели безопасности, но не обязан быть лучшим выбором на каждом сервере. Если у вас тяжёлые CI-нагрузки, nested-контейнеризация, нестандартные storage-сценарии или сильно ограниченная виртуализация, цена совместимости может оказаться слишком высокой.

В таких случаях честнее оценить архитектуру: либо использовать rootless там, где он реально стабилен, либо запускать обычный Docker на изолированном узле с внятным hardening и ограничением доступа. Пытаться любой ценой заставить rootless overlay работать в заведомо неподходящем окружении — плохая инвестиция времени.

Если нужен предсказуемый сервер под контейнеры, где можно контролировать ядро, FUSE, файловую систему и параметры namespaces, заранее подбирайте подходящую платформу. Для небольших проектов это может быть и виртуальный хостинг, но для Docker и отладки низкоуровневых ограничений обычно логичнее отдельный серверный контур.

Итог

Ошибки overlayfs invalid argument и operation not permitted в rootless Docker на Debian и Ubuntu обычно связаны не с самим Docker, а с несовместимостью между overlayfs, user namespaces, FUSE и конкретной файловой системой. Самая практичная стратегия — не гадать, а проверить логи, driver, subordinate ID, sysctl и тип backing filesystem.

В большинстве случаев рабочее решение одно и то же: установить и задействовать fuse-overlayfs. Если не помогает даже он, ищите ограничения хоста, nested-виртуализацию или неподходящую файловую систему для каталога данных. Такой подход быстро отделяет проблему настройки от архитектурного ограничения.

Главное — не менять storage driver вслепую на рабочем окружении. Для rootless Docker это не второстепенная опция, а базовая часть архитектуры хранения.