Ende September zeigte Immich plötzlich Fehler an. Immich ist meine selbst gehostete Fotoverwaltung, eine Art Google Fotos für zu Hause. Die Bilder sollen nicht auf der virtuellen Platte der VM liegen, sondern auf meinem NAS. Dafür ist ein Verzeichnis des NAS per NFS in die VM eingebunden.

Als ich nachgesehen habe, war genau dieses Verzeichnis nicht eingebunden. Und Immich hatte trotzdem fröhlich weitergeschrieben, und zwar in das leere Verzeichnis auf der lokalen Platte, in dem eigentlich das NAS hätte hängen sollen.

Von Hand ließ sich das NAS problemlos einbinden. Nach dem nächsten Neustart war es wieder weg.

Das Setup

  • VM unter Proxmox mit Debian 13 (trixie). Das Netzwerk verwaltet klassisch ifupdown über /etc/network/interfaces, die Adresse kommt per DHCP.
  • In der VM läuft Docker, unter anderem mit Immich.
  • Das NAS ist ein UniFi UNAS Pro. Es stellt eine Freigabe per NFSv3 bereit, eingebunden über /etc/fstab.

Kurz zu NFS, falls der Begriff neu ist: Mit NFS bindet ein Rechner ein Verzeichnis eines anderen Rechners so ein, als wäre es eine lokale Festplatte. Der Ort, an dem das passiert, heißt Mountpunkt. Bei mir ist das /mnt/nas.

Der Eintrag in der fstab sah zu Beginn so aus:

10.0.99.1:/var/nfs/shared/docker  /mnt/nas  nfs  nofail,x-systemd.automount,x-systemd.device-timeout=10s  0 0

Spurensuche im Journal

systemd macht aus jedem Eintrag in der fstab eine eigene Mount-Unit. Deren Name leitet sich vom Pfad ab: Aus /mnt/nas wird mnt-nas.mount. Sonderzeichen werden dabei umgeschrieben, ein Bindestrich im Pfad zum Beispiel zu \x2d. Den korrekten Namen liefert systemd-escape:

systemd-escape -p --suffix=mount /mnt/nas

Mit dem Namen kommt man an die Meldungen seit dem letzten Start:

journalctl -b -u mnt-nas.mount

Dort standen zwei Dinge:

mount.nfs: Network is unreachable
...
Start request repeated too quickly.

Der Mount wurde also versucht, aber zu einem Zeitpunkt, an dem die VM noch gar kein Netzwerk hatte. Er scheiterte mehrfach innerhalb derselben Sekunde. Daraufhin hat systemd aufgegeben und keine weiteren Versuche mehr zugelassen. Danach war nicht nur der Mount inaktiv, sondern auch die Automount-Unit, die ihn eigentlich beim ersten Zugriff hätte nachholen sollen.

Die Ursache: ein Wort in der Netzwerkkonfiguration

Damit Netzwerk-Mounts nicht zu früh starten, gibt es in systemd das Ziel network-online.target. Ein Ziel ist eine Art Wegmarke beim Booten. Alles, was das Netzwerk braucht, wartet auf diese Marke, und NFS-Mounts tun das automatisch.

Das Problem: Die Marke kann schon erreicht sein, obwohl noch gar keine IP-Adresse da ist. Bei mir trafen zwei Dinge zusammen.

Erstens stand die Netzwerkkarte so in /etc/network/interfaces:

allow-hotplug ens18
iface ens18 inet dhcp

allow-hotplug heißt: Die Karte wird hochgefahren, sobald der Kernel sie meldet, und zwar nebenbei, ohne dass der Bootvorgang darauf wartet. Das ist praktisch für USB-Netzwerkadapter, die mal da sind und mal nicht. Für die einzige Netzwerkkarte einer VM ist es die falsche Wahl. Debian setzt das bei der Installation trotzdem gern so.

Zweitens war der Dienst ifupdown-wait-online.service deaktiviert. Genau der sorgt bei ifupdown dafür, dass network-online.target erst erreicht wird, wenn die Schnittstellen wirklich oben sind. Er wartet aber nur auf Schnittstellen, die mit auto eingetragen sind, nicht auf allow-hotplug.

Ergebnis: systemd meldete „Netzwerk online“, der DHCP-Client wartete noch auf seine Adresse, und der NFS-Mount lief ins Leere.

Die Lösung in vier Schritten

Vorher habe ich beide Dateien gesichert:

sudo cp -a /etc/network/interfaces /etc/network/interfaces.bak
sudo cp -a /etc/fstab /etc/fstab.bak

1. Die Netzwerkkarte beim Booten fest hochfahren. In /etc/network/interfaces habe ich allow-hotplug durch auto ersetzt:

auto ens18
iface ens18 inet dhcp

2. Das Warten auf das Netzwerk einschalten:

sudo systemctl enable ifupdown-wait-online.service

3. Den fstab-Eintrag aufräumen:

10.0.99.1:/var/nfs/shared/docker  /mnt/nas  nfs  defaults,_netdev,nofail,x-systemd.mount-timeout=30s  0 0

Was die Optionen bedeuten:

  • nofail: Wenn das NAS nicht erreichbar ist, bootet die VM trotzdem weiter, statt im Notfallmodus hängen zu bleiben.
  • x-systemd.mount-timeout=30s: So lange darf der Mount dauern, dann gibt systemd auf.
  • _netdev: Markiert den Eintrag als Netzwerk-Dateisystem. Bei NFS erkennt systemd das eigentlich schon am Typ, die Option schadet aber nicht.

Die Automount-Option habe ich rausgenommen. Ehrlich gesagt weiß ich nicht mehr genau, warum. Ich meine, sie hat nicht sauber funktioniert. Mit der reparierten Reihenfolge brauche ich sie ohnehin nicht mehr: Das NAS wird beim Booten direkt eingebunden.

4. Neu laden und neu starten:

sudo systemctl daemon-reload
sudo reboot

Nach dem Neustart zeigt findmnt, ob das NAS wirklich eingebunden ist:

findmnt /mnt/nas

Steht dort nichts, ist das Verzeichnis nur ein leerer Ordner auf der lokalen Platte.

Das eigentliche Problem: Docker schreibt einfach weiter

Der fehlende Mount war ärgerlich. Gefährlich war etwas anderes: Docker hat das gar nicht interessiert.

Für einen Container ist /mnt/nas einfach ein Verzeichnis. Ob dort ein NAS hängt oder nicht, sieht er nicht. Ist der Mount nicht da, schreibt Immich seine Fotos eben auf die lokale Platte der VM. Das hat mehrere unschöne Folgen:

  • Die Fotos liegen nicht dort, wo ich sie vermute, und nicht dort, wo ich sie sichere.
  • Die virtuelle Platte der VM läuft voll. Bei mir ist sie deutlich kleiner als das NAS.
  • Sobald das NAS wieder eingebunden ist, verschwinden die lokal geschriebenen Dateien aus dem Blick. Sie sind noch da, aber versteckt unter dem Mount. Sehen kann man sie erst wieder, wenn man das NAS aushängt.

Deshalb darf Docker bei mir erst starten, wenn der Mount wirklich steht. Dafür gibt es in systemd die Option RequiresMountsFor. Am einfachsten legt man sie mit systemctl edit an:

sudo systemctl edit docker.service

In den Editor kommt:

[Unit]
RequiresMountsFor=/mnt/nas

Das landet in /etc/systemd/system/docker.service.d/override.conf und überlebt damit auch Updates des Docker-Pakets. RequiresMountsFor sorgt für zwei Dinge: Docker startet erst nach dem Mount, und es startet gar nicht, wenn der Mount fehlschlägt.

Lieber gar kein Immich als ein Immich, das heimlich auf die falsche Platte schreibt. Wenn Docker nicht hochkommt, merke ich das sofort. Fotos am falschen Ort merke ich vielleicht erst nach Wochen.

Stolperfallen und Learnings

allow-hotplug ist für Wechsel-Hardware gedacht. Für eine feste Netzwerkkarte, an der Mounts hängen, gehört auto hin.

„Network online“ heißt nicht, dass eine Adresse da ist. Ob network-online.target wirklich wartet, hängt davon ab, welcher Dienst die Wartearbeit übernimmt. Bei ifupdown ist das ifupdown-wait-online.service, bei anderen Netzwerkverwaltungen heißt der Dienst anders.

x-systemd.device-timeout bringt bei NFS nichts. Die Option gilt für Blockgeräte wie Festplatten und USB-Sticks, auf deren Erscheinen systemd wartet. Bei NFS gibt es kein Gerät. Für Netzwerk-Mounts ist x-systemd.mount-timeout die richtige Option.

Den Namen der Mount-Unit nicht raten. systemd-escape liefert ihn zuverlässig, auch bei Bindestrichen und Leerzeichen im Pfad.

Die Abhängigkeit gehört an den Dienst, der Daten schreibt. Den Mount zu reparieren reicht nicht. Irgendwann ist das NAS mal kurz weg, beim Booten oder nach einem Update. Dann muss klar sein, dass niemand ins leere Verzeichnis schreibt.

Nachtrag: inzwischen über eine eigene Netzwerkkarte

Seit Oktober hängt die VM zusätzlich mit einer zweiten Netzwerkkarte direkt im Storage-VLAN des NAS. Der NFS-Verkehr läuft jetzt dort, mit fester Adresse und ohne Umweg über die Firewall. Wie das aussieht und was ich dabei gelernt habe, steht im Artikel Drei Tage ohne Backup. Auch diese Karte steht in /etc/network/interfaces mit auto, aus genau dem Grund von oben.

Fazit

Ein einziges Wort in der Netzwerkkonfiguration hat dafür gesorgt, dass mein NAS nach jedem Neustart fehlte. Gefunden war das schnell, sobald ich ins Journal geschaut habe. Die wichtigere Lehre war aber die zweite: Ein Dienst, der auf ein Netzlaufwerk schreibt, muss wissen, dass er es tut. Sonst schreibt er im Zweifel einfach daneben.

Was als Nächstes kommt

  • Mein Medienserver läuft als Container und bindet das NAS ebenfalls über die fstab ein. Ob dort dasselbe Problem schlummert, will ich mir noch ansehen.
  • Eine zusätzliche Idee, die ich noch nicht umgesetzt habe: den leeren Mountpunkt bei ausgehängtem NAS mit chattr +i schreibgeschützt machen. Dann kann dort gar nichts mehr landen, auch nicht durch ein Programm außerhalb von Docker.