Proxmox NFS «stale file handle»: чому це трапляється і як запобігти

Що насправді означає «stale file handle» (у термінах Proxmox)

Proxmox тут не особливий — це «просто Linux». Коли Proxmox монтує NFS-сховище, він покладається на NFS-клієнт Linux для співставлення шляхів (наприклад, /mnt/pve/nfs-prod) з об’єктами файлової системи на сервері. NFS-клієнт кешує невеликий непрозорий ідентифікатор для кожного файлу/каталогу, з яким він працює: файл-хендл (file handle).

Цей хендл видає NFS-сервер. Він кодує «цей об’єкт, в цій файловій системі, в тій уяві про світ у сервера». Хендл призначений переживати звичайні операції, як-от перезавантаження або мерехтіння мережі. Але він не переживає певні події на боці сервера: переключення експорту на іншу файлову систему, заміну файлової системи, відновлення таблиць інодів, промоцію снапшотів або «допомогу» від людини з root-доступом і вірою в найкраще.

Коли Proxmox робить буденну операцію — відкриває qcow2, перераховує каталог, блокує диск ВМ — і сервер відповідає «я більше не знаю цей хендл», клієнт повертає ESTALE. Proxmox відображає це як «stale file handle» і далі виникає каскад помилок: помилки запуску ВМ, збої резервного копіювання, проблеми з міграцією або маркування сховища як офлайн.

Важлива відмінність: stale file handle — це не «NFS впав». Це «NFS працює, але змінилася ідентичність об’єкта». Ця різниця має значення для діагностики й запобігання.

Ось рамка надійності, яку я б хотів, аби всі використовували: stale file handle — це проблема узгодженості ідентичності, а не проблема підключення.

Цитата, яка має бути в кожному каналi інцидентів NFS (парафраз): ідея Джона Оллспо: умови для відмови закладаються в систему задовго до інциденту. Stale хендли — саме так: латентні умови плюс тригер.

Короткий жарт №1: NFS означає «No, File’s Somewhere»… аж поки не стає «Now File’s Stale».

Факти та контекст: чому це постійно підводить людей

Трохи історії й «чому» допомагають, бо в NFS є особливості, які неочевидні, якщо ви звикли до локальних дисків, об’єктного сховища або розподілених файлових систем, спроектованих у цьому столітті.

1. NFS був спроектований для безстатевих серверів (особливо v2/v3). Така безстатевість зсунула складність на клієнти: кешування, повторні спроби і дивні крайові випадки на кшталт stale handles.
2. Файл-хендли навмисно непрозорі. Сервер може змінювати їхню внутрішню структуру між версіями або конфігураціями; клієнт має ставитись до них як до «магічних печив».
3. NFSv3 часто пов’язує ідентичність із деталями файлової системи/інодами. Замініть файлову систему або перемішайте іноди — і старі хендли стануть недійсними.
4. NFSv4 ввів «псевдо-файлову систему» та іншу модель монтування. Це поліпшило деякі речі, але додало нові підводні камені навколо шляхів експорту, переадресацій і відповідності ідентифікаторів користувачів.
5. Деякі NAS-пристрої віртуалізують файлові системи під капотом. Під час фейловеру, оновлення або ребалансування бекенд може змінити ідентичність, навіть якщо шлях експорту залишається тим самим.
6. Hard-монти — це дефолт Linux з причини. «Soft» монтування може перетворити тимчасову проблему сервера на приховану корупцію даних, що значно гірше за завислий процес.
7. «Stale file handle» старший за ваш стек віртуалізації. Його можна знайти ще в епосі UNIX; сучасні гіпервізори лише збільшили радіус ураження.
8. Семантика блокувань має довгу й заплутану історію. NLM для v3 і інтегровані блокування у v4 можуть взаємодіяти з фейловерами та реекспортами так, що виглядає як «випадкові» проблеми з дисками ВМ.

Висновок: NFS може бути надійним, але лише якщо ви розглядаєте ідентичність файлів як частину контракту зберігання. Якщо ваш NFS-сервер може тихо замінити бекенд файлової системи — у вас немає контракту, а є лише відчуття.

Кореневі причини, що породжують stale file handles

1) Експорт тепер вказує на іншу файлову систему

Класика. Рядок шляху експорту незмінний, але базова файлова система змінилася: змонтовано новий ZFS-датасет, новий ext4-том, промотовано репліковану файлову систему або інший NAS-том змонтовано в ту саму директорію.

NFS файл-хендли зазвичай містять ідентифікатор файлової системи. Якщо цей ідентифікатор змінюється — старі хендли стають застарілими. Часто відбувається після «обслуговування сховища», коли хтось відмонтовує і знову монтує шлях експорту, або після фейловеру, коли стендбай-вузол експортує не тотожну метаданам файлової системи копію.

2) Повторне використання інодів або регенерація таблиці інодів (рідше, але реально)

Деякі файлові системи та операції відновлення можуть змінити ідентичність іноду для «того самого шляху». Якщо сервер вирішив, що об’єкт за шляхом тепер інший інод, хендли, які посилалися на старий інод, стануть stale. Ви побачите це після відбудов файлової системи, агресивних відкатів снапшотів або певних робочих процесів «відновлення з бекапу» у той самий шлях.

3) Зміна опцій експорту або конфігурації NFS-сервера під час роботи

Зміни експорту і перезавантаження сервера можуть інвалідизувати уявлення сервера про те, що експортується і з яким ідентифікатором файлової системи. В NFSv3 fsid важить більше, ніж багато хто розуміє. В NFSv4 мають значення псевдо-root і дерево експорту.

4) NAS-фейловер, коли клієнт говорить «той самий IP», але з іншим образом сервера

Високодоступний NFS часто використовує плаваючу IP-адресу. Добре. Але якщо під час фейловеру змінюється «особистість» сервера так, що ідентичність файлової системи не зберігається точно (або з’являється із запізненням), клієнти можуть зберігати старі хендли і потім вибухнути. Деякі пристрої мають «grace period» або ремапінг хендлів; деякі — ні. Декотрі — тільки після ввімкнення певної опції. Питаєте, як я це знаю.

5) Відкат снапшота / промоція клонів на сервері

Відкат привабливий: «просто відкотимо датасет». Якщо відкат змінює ідентичність інодів або покоління файлової системи, хендли виходять зі строю. Диски ВМ особливо чутливі, бо вони довго живуть і часто відкриті.

6) Поведінка вузла Proxmox: кешовані записи каталогу і зайняті процеси

Навіть якщо сервер вже «коректний», клієнти можуть зберігати застарілі посилання, якщо процеси мають відкриті дескриптори файлів, робочі директорії або кешовані dentries, що вказують на старі хендли. Саме тому «umount і remount» іноді виправляє, а іноді видає «device is busy» — це ввічливе повідомлення Linux, що процес все ще там.

7) «Оптимізаційні» опції монтування, що змінюють семантику

Тюнінг NFS для продуктивності — нормально. Тюнінг для відчуттів — ні. Опції як actimeo, lookupcache і агресивне кешування атрибутів можуть збільшити вікно, коли клієнти працюють із застарілою уявою про ідентичність. Зазвичай кешування не дає прямого stale handle, але воно збільшує частоту дивної поведінки навколо перейменувань/видалень і швидких відкатів.

Короткий жарт №2: Найшвидший спосіб згенерувати stale file handles — сказати вголос «не хвилюйтеся, це просто NFS». NFS вас почує.

Швидкий план діагностики (перевірити перше/друге/третє)

Мета — швидко відповісти на три питання:

• Це проблема ідентичності (ESTALE) чи проблема підключення/продуктивності (таймаути)?
• Помилка локалізована на одному вузлі Proxmox чи в межах усього кластера?
• Чи сервер змінив те, що експортує, або клієнт закешував щось зламане?

Перше: підтвердити помилку та область впливу

1. Перевірте логи завдань Proxmox на наявність ESTALE / stale file handle.
2. На кількох вузлах спробуйте перерахувати той самий шлях. Якщо лише один вузол бачить stale — зазвичай це кеш/стан процесів на клієнті. Якщо всі вузли бачать stale — змінився сервер/експорт.
3. Подивіться в журнали ядра на клієнті для повідомлень NFS. Вони часто містять IP сервера і точку монтування.

Друге: перевірити, що монтування — те, що ви думаєте

1. Перевірте findmnt, щоб підтвердити версію NFS, сервер, шлях експорту і опції монтування.
2. Перевірте /proc/fs/nfsfs/volumes, щоб побачити уявлення клієнта про томи та їхні ID.
3. На сервері підтвердьте, що експорти не змінилися і що файлову систему за експортом — та сама dataset/volume.

Третє: вирішіть, чи виправляти на клієнті, сервері чи обох

• Якщо експорт сервера вказує кудись нове: спочатку виправте ідентичність сервера/експорту, потім перемонтуйте клієнти.
• Якщо сервер стабільний, але один вузол зламався: завершіть процеси, що тримають stale fd, а потім перемонтуйте.
• Якщо спрацював HA фейловер: потрібно виправити збереження ідентичності при фейловері, а не лише перемонтовувати. Перемонтування — це пластир.

Практичні завдання: команди, очікуваний висновок і рішення

Нижче — реальні команди, які можна виконати на вузлах Proxmox і типовому Linux NFS-сервері. Кожне завдання включає, що означає вивід і яке рішення прийняти далі.

Завдання 1: Підтвердити монтування і версію NFS

cr0x@pve1:~$ findmnt -t nfs,nfs4 /mnt/pve/nfs-prod
TARGET           SOURCE                   FSTYPE OPTIONS
/mnt/pve/nfs-prod nfs01:/exports/prod     nfs4   rw,relatime,vers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,proto=tcp

Значення: Ви змонтовані з nfs01:/exports/prod використовуючи NFSv4.1 з hard-монтом.

Рішення: Якщо SOURCE не відповідає очікуваному (не той хост/експорт), зупиніться. Виправте визначення сховища Proxmox або DNS, перш ніж шукати stale handles.

Завдання 2: Відтворити помилку stale мінімально

cr0x@pve1:~$ ls -la /mnt/pve/nfs-prod/images
ls: cannot access '/mnt/pve/nfs-prod/images': Stale file handle

Значення: Це справжній симптом ESTALE при зверненні до каталогу.

Рішення: Перевірте, чи інші вузли бачать те ж саме. Якщо так — підозрюйте зміну експорту/ідентичності на сервері.

Завдання 3: Перевірити повідомлення ядра про скарги NFS-клієнта

cr0x@pve1:~$ dmesg -T | tail -n 20
[Thu Dec 26 01:58:41 2025] NFS: stale file handle
[Thu Dec 26 01:58:41 2025] NFS: server nfs01 not responding, still trying
[Thu Dec 26 01:58:57 2025] NFS: server nfs01 OK

Значення: Можуть співіснувати і проблеми ідентичності (stale handle), і короткочасна недоступність сервера. Вони можуть співпадати під час фейловеру/перезапуску.

Рішення: Якщо «not responding» повторюється, також дослідіть мережу/навантаження сервера. Але не ігноруйте stale handle: воно не пройде само по собі.

Завдання 4: Визначити, хто «коштує» в монті (блокуює демонтування)

cr0x@pve1:~$ fuser -vm /mnt/pve/nfs-prod
                     USER        PID ACCESS COMMAND
/mnt/pve/nfs-prod:   root      21940 ..c.. pvedaemon
                     root      31211 ..c.. pve-backup
                     root      1402  ..c.. systemd

Значення: Ці PID мають поточну директорію або відкриті файли під монтом.

Рішення: Якщо потрібно перемонтувати — зупиніть відповідні сервіси/завдання Proxmox коректно, інакше доведеться вдаватися до «lazy unmount».

Завдання 5: Подивитися внутрішній список томів NFS-клієнта

cr0x@pve1:~$ cat /proc/fs/nfsfs/volumes
NV SERVER   PORT DEV     FSID              FSC
v4 nfs01    2049 0:50    0:0               yes

Значення: Клієнт бачить NFSv4 том від nfs01. FSID тут менш описовий, ніж у v3, але підтверджує уявлення клієнта.

Рішення: Якщо ви очікували кілька монтувань або різні сервери, а бачите лише один — можливо, монтування через HA VIP і ви не помітили фейловери.

Завдання 6: Перевірити конфіг Proxmox на наявність запису NFS

cr0x@pve1:~$ cat /etc/pve/storage.cfg
nfs: nfs-prod
        server nfs01
        export /exports/prod
        path /mnt/pve/nfs-prod
        content images,iso,vztmpl,backup
        options vers=4.1,proto=tcp,hard,timeo=600,retrans=2

Значення: Proxmox налаштований монтувати цей експорт з певними опціями.

Рішення: Якщо у вас відсутній явний vers і середовище змішане, зафіксуйте версії навмисно. Нечіткі різниці v3/v4 часто спричиняють проблеми.

Завдання 7: Валідовати експорти з боку клієнта (вид NFSv3; все ще корисно)

cr0x@pve1:~$ showmount -e nfs01
Export list for nfs01:
/exports/prod 10.10.20.0/24
/exports/dev  10.10.20.0/24

Значення: Сервер рекламує ці експортшляхи. Для NFSv4 це може не показати всієї картини (псевдо-root), але спіймає базове розходження.

Рішення: Якщо експорт зник або змінилися дозволи — виправте це першочергово. Stale handle іноді йде слідом за переконфігурацією експорту.

Завдання 8: На NFS-сервері — підтвердити конфіг експорту і fsid

cr0x@nfs01:~$ sudo exportfs -v
/exports/prod   10.10.20.0/24(rw,sync,wdelay,hide,no_subtree_check,sec=sys,fsid=100)
/exports/dev    10.10.20.0/24(rw,sync,wdelay,hide,no_subtree_check,sec=sys,fsid=101)

Значення: Сервер експортує з явними значеннями fsid. Це добра гігієна для стабільності, особливо з NFSv3 і в деяких HA-сценаріях.

Рішення: Якщо fsid відсутній і ви робите щось складне (bind mounts, ZFS datasets, фейловери) — додайте явні fsid і протестуйте. Якщо fsid змінився нещодавно — очікуйте stale handles до перемонтування клієнтів.

Завдання 9: Підтвердити, що файлова система за експортом не змінилася

cr0x@nfs01:~$ mount | grep ' /exports/prod '
tank/prod on /exports/prod type zfs (rw,xattr,noacl)

Значення: Шлях експорту відповідає ZFS-датасету tank/prod.

Рішення: Порівняйте з відомою базою. Якщо хтось замінив його (наприклад тепер tank/prod-new) — це ваш тригер stale handles.

Завдання 10: Виявити «каталог був замінений» (зміни номера іноду з часом)

cr0x@nfs01:~$ stat -c '%n inode=%i dev=%d' /exports/prod /exports/prod/images
/exports/prod inode=48 dev=46
/exports/prod/images inode=1024 dev=46

Значення: Ви збираєте ідентифікатори, що допомагають вловити інциденти «ми перемонтували щось інше тут». Якщо dev змінився — змінено монтування.

Рішення: Якщо dev/inode відрізняються від попередніх записів — розглядайте це як зміну ідентичності на сервері і плануйте скоординоване перемонтування клієнтів (і виправлення робочого процесу, що це спричинив).

Завдання 11: Спробувати чистий перемонт на вузлі Proxmox (після зупинки залежних задач)

cr0x@pve1:~$ sudo systemctl stop pvedaemon pveproxy
cr0x@pve1:~$ sudo umount /mnt/pve/nfs-prod
umount: /mnt/pve/nfs-prod: target is busy.

Значення: Щось ще тримає його зайнятим (часто backup, qemu або shell з cwd всередині).

Рішення: Використайте fuser/lsof, щоб знайти і зупинити конкретні процеси. Не поспішайте до lazy unmount, доки не зрозумієте наслідків.

Завдання 12: Знайти відкриті файли під монтом (точніше, ніж fuser)

cr0x@pve1:~$ sudo lsof +f -- /mnt/pve/nfs-prod | head
COMMAND     PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
pve-backup 31211 root  cwd    DIR  0,50     4096    2 /mnt/pve/nfs-prod/backup
qemu-system 9982 root   27u   REG  0,50 2147483648  7 /mnt/pve/nfs-prod/images/101/vm-101-disk-0.qcow2

Значення: Відкриті дескриптори мають процес резервного копіювання і qemu. Якщо ці дескриптори stale — вони і надалі даватимуть помилки, поки не будуть перезапущені й монтування оновлене.

Рішення: Зупиніть/перемістіть ВМ, що працюють з цим сховищем перед перемонтуванням. Інакше ви ризикуєте цілісністю і часу відновлення.

Завдання 13: Використовувати lazy unmount тільки як контрольований останній захід

cr0x@pve1:~$ sudo umount -l /mnt/pve/nfs-prod
cr0x@pve1:~$ sudo mount /mnt/pve/nfs-prod
cr0x@pve1:~$ ls /mnt/pve/nfs-prod
backup  images  iso  vztmpl

Значення: Монтування повернулося і перелік директорій працює. Lazy unmount від’єднав монтування від namespace, поки старі посилання поступово закінчуються.

Рішення: Негайно перевірте, що процеси qemu не все ще посилаються на старий монтування. Якщо так — перезапустіть їх коректно. Lazy unmount не безкоштовний вихід.

Завдання 14: Підтвердити, що Proxmox бачить сховище як доступне

cr0x@pve1:~$ pvesm status
Name       Type  Status     Total     Used    Available  %
local      dir   active   19660800  8214528    11446272  41.79%
nfs-prod   nfs   active  104857600 20971520    83886080  20.00%

Значення: Сховище активне з погляду Proxmox.

Рішення: Якщо воно все ще «inactive», але Linux-монтування працює — перевірте дозволи, типи контенту й сервіси Proxmox. Якщо Linux-монтування зламане — не виніть Proxmox.

Завдання 15: Якщо підозрюєте фейловер, підтвердити, з яким сервером ви спілкуєтесь

cr0x@pve1:~$ rpcinfo -t nfs01 nfs 4
program 100003 version 4 ready and waiting

Значення: RPC-з’єднання до цілі nfs01 є. У HA VIP-настройках це не доводить, який фізичний вузол активний, але підтверджує доступність сервісу.

Рішення: Якщо задіяне HA, перевірте збереження ідентичності під час фейловеру. Stale handles, що виникають одночасно з VIP-фейловером, — це архітектурна проблема.

Завдання 16: Санітарна перевірка на сервері: хтось не «ре-лодив» експорти недавно?

cr0x@nfs01:~$ sudo journalctl -u nfs-server -u nfs-mountd --since "2 hours ago" | tail -n 30
Dec 26 01:54:02 nfs01 exportfs[18842]: exporting 10.10.20.0/24:/exports/prod
Dec 26 01:54:02 nfs01 systemd[1]: Reloaded NFS server and services.

Значення: Експорти перезавантажувалися в інтервалі інциденту. Це не обов’язково погано, але сильна кореляційна підказка.

Рішення: Якщо перезавантаження експорту збіглося зі stale handles — перегляньте, що змінилося (експорти, точки монтування, fsid, bind mounts). Додайте правило: «зміни експорту вимагають контролю змін».

Типові помилки: симптом → корінь → виправлення

1) Диски ВМ періодично не стартують після обслуговування NAS

Симптом: qm start не вдається через помилки введення/виведення; логи Proxmox показують stale file handle на шляху диска ВМ.

Корінь: Шлях експорту залишився тим самим, але NAS під час обслуговування або фейловеру підмінив/відкатав базовий том або змінив ідентичність файлової системи.

Виправлення: Зробіть експорти стабільними: явний fsid (де застосовно), послідовна ідентичність файлової системи на HA-вузлах, уникати «замінити те, що змонтовано під шляхом експорту». Після виправлення на сервері — перемонтуйте клієнти і перезапустіть уражені процеси qemu.

2) Лише один вузол Proxmox бачить stale handles; інші в порядку

Симптом: Сховище «active» на вузлі A, але при переліку директорій виникає stale handle; вузол B може переглядати нормально.

Корінь: Вузол A має процеси з відкритими застарілими дескрипторами або кешовані dentries; вузол B перемонтувався або ніколи не торкався змінених об’єктів.

Виправлення: Знайдіть процеси через lsof/fuser, зупиніть/перемістіть навантаження, що використовує монтування, і потім чисто перемонтуйте уражений вузол.

3) Резервні копії падають зі stale handle одразу після «відновлення на місці»

Симптом: Робота бекапу падає під час сканування директорій; помилки вказують на папку, нещодавно відновлену.

Корінь: Процес відновлення замінив каталоги/файли таким чином, що змінилася ідентичність інодів, тоді як клієнти все ще мали кешовані хендли до старих об’єктів.

Виправлення: Не відновлюйте шлях шлях-заміною під активним експортом. Відновлюйте в новий шлях, перевіряйте цілісність, потім робіть контрольований cutover (і перемонтування клієнтів при потребі).

4) Хтось «вирішив» це soft-монтами і тепер має ризик корупції

Симптом: Помилки stale зникли, але пізніше з’являються рандомні помилки застосунків і обрізані файли.

Корінь: soft може спричинити ранні відмови NFS-операцій; багато додатків не вміють безпечно це обробляти для образів ВМ чи баз даних.

Виправлення: Для дисків ВМ використовуйте hard. Вирішіть базову проблему ідентичності/фейловеру. Якщо потрібен контрольований відмовостійкий сценарій — використовуйте коректні таймаути та моніторинг, а не soft.

5) Stale handle після зміни опцій експорту (особливо з bind mounts)

Симптом: Після «прибирання» деякі каталоги дають stale file handle, інші працюють.

Корінь: Змінено дерево експорту; bind mounts або піддиректорії експортувалися по-іншому; змінилося присвоєння fsid.

Виправлення: Тримайте стабільну структуру експорту. Краще експортувати окрему файлову систему/датасет під кожне сховище Proxmox. Уникайте експорту глибоких піддиректорій з рухомими батьками.

6) «Ми використовуємо HA VIP, тож усе гаразд» (насправді ні, за замовчуванням)

Симптом: Кластерні stale handles під час тестів фейловеру; все повертається після перемонтування/перезавантаження.

Корінь: Станбі вузол не зберігає ідентичність file handle або представляє інший FSID за тією самою IP-адресою.

Виправлення: Налаштуйте HA NFS правильно: спільний бекенд з послідовною ідентичністю або HA-рішення для NFS, що гарантує стабільні file handles при фейловері. Тестуйте з живими завданнями, а не лише з ls.

Три корпоративні історії з польових боїв

Міні-історія 1: Інцидент через хибне припущення

У них був акуратний Proxmox-кластер і акуратний NAS. Шлях експорту був /exports/prod і таким залишався роками. Під час оновлення сховища хтось створив новий том і змонтував його на /exports/prod у вікні техобслуговування. Та ж директорія, ті самі права, та сама IP. Вони вирішили, що «той самий шлях» = «те саме сховище».

Спочатку все працювало. Нові міграції ВМ потрапляли на новий том і виконувались. Наступного дня почали падати бекапи, потім кілька ВМ перезавантажилися під час патчів і не піднялися. Stale file handle всюди. On-call команда вважала це за відмову NFS і робила звичні ритуали: перезапустити сервіси, перезавантажити вузол Proxmox, перезавантажити контролер NAS. Помилка змінювала форму, але не зникала.

Поворотним моментом стало порівняння джерела монтування на сервері і імені ZFS-датасету за експортом. Він був новим. Старий том все ще існував і був змонтований в іншому місці. Клієнти закешували хендли до об’єктів на старій файловій системі; експорт тепер вказував на нову. NFS-сервер не «впав», він ввічливо відмовився визнавати минуле життя.

Вони виправили це нудною роботою: створили новий шлях експорту для нового тому, додали його як нове сховище Proxmox, мігрували диски явно, потім вивели старий. Постмортем вимога була пряма: «Не замінювати файлову систему під існуючим шляхом експорту». Ніхто не був щасливий із цим правилом, поки наступне оновлення не пройшло без pager-ів.

Міні-історія 2: Оптимізація, що зіграла зле

Інша команда мала проблеми з продуктивністю: бекапи були повільними, I/O дисків ВМ скакали, і хтось вирішив, що причина — «NFS metadata chatter». Вони агресивно налаштували опції монтування — кешування атрибутів, поведінку lookup cache, збільшені rsize/wsize, зменшені retrans і кілька опцій зі статті для іншого робочого навантаження.

У щасливому шляху продуктивність покращилась. Потім вони запустили запланований тест фейловеру на HA NAS. Сам фейловер пройшов чисто, але вузли Proxmox почали повідомляти про stale handles і дивні невідповідності у списках директорій. Лише деякі вузли. Лише деякі піддиректорії. Це виглядало як інцидент від космічних променів.

Справжня проблема: тюнінг збільшив вікно, коли клієнти вірили своєму кешованому вигляду, у той час як дерево експорту на сервері коротко було в транзитному стані під час фейловеру. Клієнти не були неправі, що кешували; вони були неправі, що кешували настільки довго, враховуючи поведінку сервера. І оскільки «оптимізацію» впроваджували поступово, різні вузли поводилися по-різному. Удачі у дебагу о 03:00.

Вони відкотилися до консервативного профілю і виправили послідовність HA так, щоб експорт ставав доступним тільки після того, як файлову систему змонтовано й вона повністю консистентна. Урок: якщо ви налаштовуєте — налаштовуйте проти моделі відмов. Інакше ви просто зробите відмову цікавішою.

Міні-історія 3: Нудна, але правильна практика, що врятувала день

Одна команда підприємства трактувала NFS-експорти як API-контракти. Кожне Proxmox-сховище мало свій виділений файловий ресурс/датасет. Експорти декларувалися з явними ідентифікаторами, зміни проходили рев’ю, і «поміняти те, що змонтоване тут» просто не дозволялося. Політика була не популярна, бо прибирала клас «швидких фіксів». І в цьому була суть.

Вони все ще мали інциденти — мережеві збої, баги в прошивці мережевих карт, комутатор, який вирішив скидати пакети як частину очищення аури. Але stale file handles були рідкісні, і коли виникали — зона ураження була малою. Один експорт, один датасет, один ідентифікатор сховища. Діагностика була швидкою, бо сумнівів було менше.

Потім оновлення сервера перезавантажило NFS-вузол у невдалий момент. Клієнти застопорилися (hard-mount виконав свою роль), моніторинг засвітився, on-call слідував runbook: підтвердити NFS, перевірити ідентичність експорту, перемонтувати тільки при потребі, перезапустити тільки уражені завдання. Жодних перезавантажень вузлів. Жодних випадкових «спробати ще раз». Інцидент був короткий, нудний і не став подією у кар’єрі.

Це найвища похвала в опраці: інцидент поводився саме так, як написано в runbook.

Запобігання: що стандартизувати і що заборонити

Стандартизувати: стабільні експорти, які не рухаються

Якщо хочете менше stale handles — припиніть робити те, що їх створює: змінювати ідентичність файлової системи під час, коли клієнти змонтовані.

• Одне Proxmox-сховище ↔ одна серверна файлова система/датасет. Уникайте експорту глибоких піддиректорій спільного тому для різних цілей. Це підвищує шанс, що хтось «почистить» батьківську директорію.
• Ніколи не замінюйте те, що змонтовано під шляхом експорту. Створіть новий шлях експорту, зробіть cutover явно, потім виведіть старий.
• Використовуйте явні ідентифікатори експорту там, де потрібно. На багатьох Linux NFS-серверах встановлення fsid для експорту — це профілактика стабільності, особливо для NFSv3 і в мульті-експортних сценаріях.
• Фіксуйте версії NFS навмисно. Змішування v3/v4 між вузлами — запрошення до непослідовної поведінки при відмовах.

Стандартизувати: консервативні опції монтування для VM-сховища

Для образів ВМ пріоритет — коректність і передбачувана поведінка при відмові, а не бенчмаркові виграші.

• Використовуйте hard монти. Якщо сервер зависне — ваше I/O зависне. Це чесно. Це дозволяє виконувати фейловер, виправлення або fencing без корупції дисків.
• Використовуйте TCP. Так, UDP існував історично. Ні, вам не треба його для дисків ВМ у 2025 році.
• Встановлюйте розумні таймаути. Поширена практика — довший timeo з обмеженими retrans і гарним оповіщенням, щоб виявляти завислі стани без перетворення їх у приховані відмови.
• Тримайте кешування атрибутів у межах здорового глузду. Не перегинайте, якщо не можете відтворити тести відмов під цими налаштуваннями.

Заборонити: «відкат датасету, що містить працюючі диски ВМ»

Якщо ваш NFS-сервер хостить активні диски ВМ і ви робите відкат снапшота під ними — ви граєте у файлову рулетку. Навіть якщо сервер витримає, клієнти не зможуть узгодити «минуле» з кешованими хендлами. Замість цього:

• Відновлюйте в новий датасет/шлях.
• Перевіряйте цілісність.
• Плануйте контрольовану міграцію/cutover.

Заборонити: експортувати шляхи, що залежать від bind mounts без контролю змін

Bind mounts зручні. Вони — відмінний спосіб непомітно змінити ідентичність файлової системи. Якщо мусите їх використовувати, трактуйте зміни bind mount як продакшн-зміну з maintenance window, координацією клієнтів і планом відкату.

Проєктувати HA: стабільна ідентичність при фейловері або не прикидатися HA

HA NFS — це складно, бо «та сама IP» ≠ «та сама ідентичність файлової системи». Якщо під час фейловеру бекенд не зберігає хендли, ви отримаєте stale handles по всьому кластеру. Рішення включають:

• Спільна бекенд-файлова система з послідовною ідентичністю та коректною підтримкою HA для NFS.
• Оркестрація фейловеру, що гарантує, що експорти з’являються лише після того, як файлова система змонтована і готова.
• Уникнення NFS для дисків ВМ, якщо ваша HA-модель не гарантує ідентичність (використовуйте блочне сховище або кластерну файлову систему, розроблену для цього).

Чеклісти / покроковий план

Покроково: коли stale file handle вражає продакшен

1. Підтвердіть область впливу: один вузол чи всі. Запустіть ls на тому самому шляху з двох вузлів.
2. Зберіть докази перед «фіксом»: журнали ядра (dmesg), логи завдань Proxmox, вивід findmnt.
3. Визначте постраждалі навантаження: які ВМ/CT використовують це сховище. Плануйте паузу/міграцію при потребі.
4. Перевірте ідентичність експорту на сервері: підтвердіть, що експорт вказує на очікуваний файловий ресурс/датасет; перевірте недавні перезавантаження експорту і зміни монтування.
5. Виправте дрейф на стороні сервера спочатку: якщо експорт перемістився — поверніть або створіть новий експорт і переконфігуруйте Proxmox.
6. Зупиніть процеси з stale fd на клієнті: lsof/fuser, потім зупиніть або перемістіть ВМ, що використовують монтування.
7. Перемонтуйте чисто: unmount, mount, перевірте список директорій, перевірте доступ до файлів.
8. Перезапустіть тільки те, що треба: qemu-процеси для уражених ВМ, завдання бекапу тощо.
9. Після інциденту: визначте тригер на стороні сервера і напишіть політику, яка запобігатиме повторенню.

Чекліст: вимоги стабільності експорту для Proxmox NFS датасторів

• Виділена файлова система/датасет для кожного датастору
• Заборонено «замінювати монтування під шляхом»
• Явні ідентифікатори експорту (де застосовно)
• Контроль змін для редагування експорту
• Документовані опції монтування, зафіксовані в Proxmox storage.cfg
• Тестування HA-фейловеру з відкритими файлами, а не лише з ls

Чекліст: «перед обслуговуванням» на NFS-сервері, що хостить Proxmox

• Підтвердьте, які Proxmox-сховища прив’язані до яких експортів
• Заглушіть або перемістіть високоризикові навантаження (ВМ з інтенсивним записом, бекапи)
• Якщо фейловер/апґрейд змінює ідентичність експорту — заплануйте вікно для перемонтування клієнтів
• Повідомте очікувану поведінку: hard-монти можуть зависнути під час перезавантаження
• Після обслуговування: перевірте експорти, точки монтування і ідентичність датасетів перед «зеленим» статусом

Поширені запитання (FAQ)

1) Чи є «stale file handle» багом Proxmox?

Ні. Proxmox показує помилку клієнта NFS у Linux (ESTALE). Звичайний тригер — зміна ідентичності на боці сервера або поведінка HA при фейловері.

2) Чому перезавантаження вузла Proxmox іноді «виправляє» проблему?

Перезавантаження скидає кешований стан і відкриті дескриптори файлів, змушуючи зробити свіжі хендли після перемонтування. Це грубий інструмент, що ховає справжню причину і коштує більше часу простою, ніж потрібно.

3) Який вибрати: NFSv3 чи NFSv4.x для Proxmox?

Обидва варіанти можуть працювати, але обирайте свідомо і стандартизуйте. NFSv4.x спрощує певні аспекти (єдиний порт, інтегроване блокування), тоді як v3 має простішу семантику в деяких середовищах. Змішування версій між вузлами — запрошення до непослідовної поведінки.

4) Чи допоможе «soft» монтування уникнути завислих ВМ?

Ні для дисків ВМ. Soft-монти можуть викликати відмови операцій посеред запису, що додатки не вміють безпечно обробити. Hard-монти плюс якісний моніторинг — це правильний підхід.

5) Чи може stale file handle трапитися, якщо сервер ніколи не перезавантажувався?

Так. Будь-яка зміна, яка фактично замінює ідентичність об’єкта файлової системи — відкат снапшота, перемонтування датасету, switch bind mount, переконфігурація експорту — може це спричинити.

6) Чому іноді це зачіпає лише один каталог під монтом?

Тому що хендли прив’язані до об’єкта. Якщо була замінена лише одна піддерева (відновлена, відкотана, перемонтована через bind mount), то тільки хендли, що посилалися на ту піддерево, стануть stale.

7) Яке найбезпечніше виправлення, коли диски ВМ лежать на ураженому NFS?

Зупиніть або перемістіть ВМ, які використовують це сховище, перемонтуйте датастор, потім перезапустіть ВМ. Якщо зупинити неможливо — ви ризикуєте цілісністю даних і часом відновлення.

8) Чи завжди явний fsid запобігає stale handles?

Ні. Він зменшує певний клас проблем (особливо навколо ідентифікації експорту та змін), але не врятує від заміни базової файлової системи/датасету або від руйнівних відкатів.

9) Як відрізнити проблему ідентичності від простого затримки/таймауту?

Затримки/таймаути проявляються як «сервер не відповідає» і зависле I/O; stale handle проявляється як негайна помилка Stale file handle при lookup/open. Вони можуть траплятися разом під час фейловеру.

10) Якщо я змушений робити відкат на сервері, який варіант найменш поганий?

Відновлюйте в новий шлях/датасет і робіть cutover через зміну сховища в Proxmox (і перемонтування). Не відкатуйте in-place під активними клієнтами.

Практичні наступні кроки

Якщо хочете менше інцидентів зі stale file handle, виконайте це в порядку:

1. Аудит стабільності експорту: підтвердіть, що кожне Proxmox NFS-сховище мапиться на виділену серверну файлову систему/датасет, який ніколи не замінюється на місці.
2. Стандартизувати монти: зафіксуйте версію NFS і опції в /etc/pve/storage.cfg. Усуньте ад-хок відмінності між вузлами.
3. Виправте HA чесно: або гарантуйте стабільну ідентичність при фейловері, або перестаньте вдавати, що VIP робить його безпечним.
4. Напишіть runbook: швидкі перевірки діагностики, кроки «хто тримає монтування», і процедура контрольованого перемонтування.
5. Змініть культуру: «просто перемонтуй» — не рішення; це симптом відсутності контрактів між зберіганням і обчисленням.

Stale file handles — це система, що говорить вам правду: під вами щось змінилося. Зробіть ці зміни явними, контрольованими і тестованими — і правда перестане бути надто драматичною.