Wiederherstellung nach einem fehlgeschlagenen NGINX Plus-Upgrade: „Modul ‚M‘ hat Version X statt Y“

Liam CrillySenior Director, Produktmanagement

Wenn Sie dynamische Module verwenden, wird beim Upgrade auf eine neue Version von NGINX oder NGINX Plus möglicherweise eine Fehlermeldung wie diese angezeigt:

Setting up nginx-plus (1.11.10-1~xenial) ...
nginx: [emerg] module "/etc/nginx/modules/ngx_http_geoip_module.so" version 1011005 instead of 1011006 in /etc/nginx/nginx.conf:7

nginx: configuration file /etc/nginx/nginx.conf test failed

invoke-rc.d: initscript nginx, action "upgrade" failed.

Der wahrscheinlichste Grund ist, dass Sie das angegebene dynamische Modul (.so-Datei) nicht aktualisiert haben:

• Wenn Sie NGINX Open Source verwenden, müssen dynamische Module für die Version kompiliert werden, auf die Sie aktualisieren.
• Wenn Sie NGINX Plus verwenden, müssen dynamische Module für die NGINX Open Source-Version kompiliert werden, die dem NGINX Plus-Release entspricht, auf das Sie ein Upgrade durchführen.

Der Kürze halber sprechen wir im Folgenden nur noch von NGINX Plus.

Keine Panik!

Sie können beruhigt sein: Diese Fehlermeldung bedeutet nicht, dass Ihr NGINX Plus-Server ausgefallen ist. Upgrades von NGINX Plus erfolgen ohne Unterbrechung, sodass bei einem fehlgeschlagenen Upgrade die alte Version weiterläuft. Das Upgrade ist jedoch unvollständig und Ihr System befindet sich in einem inkonsistenten Zustand:

• Die im Arbeitsspeicher ausgeführten NGINX Plus-Prozesse verwenden die alte Version
• Alle Dateien auf dem Datenträger, die zu NGINX Plus gehören, entsprechen der neuen Version
• Das in der Fehlermeldung erwähnte dynamische Modul wurde für die alte Version kompiliert

Starten Sie nginx nicht manuell neu und führen Sie auch keinen Neustart des Systems durch. Andernfalls kommt es zu Ausfallzeiten, da neue NGINX Plus-Prozesse nicht gestartet werden können, solange dynamische Module nicht mit der neuen NGINX Plus-Version synchronisiert sind.

Beachten Sie, dass sich die Fehlermeldung nur auf das erste inkompatible Modul bezieht, das während des Upgradevorgangs gefunden wurde. Daher ist es wichtig, alle load_module-Direktiven in Ihrer Konfiguration zu finden und sicherzustellen, dass jedes Modul für die entsprechende NGINX-Version kompiliert wurde. Für jede NGINX Plus-Version werden die korrekten Versionen aller von NGINX entwickelten und zertifizierten dynamischen Module von Drittanbietern bereitgestellt, sodass Sie nur nicht zertifizierte Module neu kompilieren müssen.In diesem Artikel wird beschrieben, wie Sie den Upgradevorgang sicher abschließen.

Was ist schiefgelaufen?

Mit NGINX 1.11.5 und NGINX Plus R11 wurde die Möglichkeit eingeführt, dynamische Module für NGINX Open Source zu kompilieren und in NGINX Plus zu laden. Diese Binärkompatibilität setzt voraus, dass das Modul und NGINX Plus auf derselben Open-Source-Basisversion beruhen. Ein Upgrade von NGINX Plus schlägt aufgrund dieser Versionsabweichung fehl, wenn nicht zuvor dynamische Module installiert wurden, die für die entsprechende Version von NGINX Open Source erstellt wurden.

Wenn Ihr dynamisches Modul von einem Drittanbieter bereitgestellt wurde, müssen Sie sich an den Anbieter wenden, um eine neue Version zu erhalten, die auf die NGINX-Version der NGINX Plus-Version abgestimmt ist, auf die Sie aktualisieren möchten. Wenn Ihr dynamisches Modul aus dem Quellcode kompiliert wurde (und Sie Zugriff auf den Quellcode haben), lesen Sie weiter.

Der Weg zur Wiederherstellung

Schritt 0: Build-Umgebung vorbereiten

Wir empfehlen dringend, dynamische Module auf einem separaten System zu kompilieren, das wir hier als „Build-Umgebung“ bezeichnen. Dadurch werden das Risiko und die Komplexität des Systems minimiert, auf dem Sie NGINX Plus mit dem dynamischen Modul ausführen (dieses bezeichnen wir als „Produktionsumgebung“). Die Build-Umgebung muss dasselbe Betriebssystem und dieselbe Version wie die Produktionsumgebung aufweisen; außerdem müssen die folgenden Komponenten installiert sein:

• UnZip-Dienstprogramm
• Compiler und Make-Dienstprogramm
• Bibliothek für Perl-kompatible reguläre Ausdrücke (Entwicklungsdateien)
• Zlib-Komprimierungsbibliotheken (Entwicklungsdateien)

Führen Sie den folgenden Befehl aus, um sicherzustellen, dass diese Voraussetzungen in Ihrer Build-Umgebung installiert sind.

• Für Ubuntu/Debian:

buildenv$ sudo apt-get install unzip gcc make libpcre3-dev zlib1g-dev

• Für CentOS/RHEL/Oracle Linux:

buildenv$ sudo yum install unzip gcc make pcre-devel zlib-devel

Schritt 1: NGINX Open Source beziehen

1. Führen Sie in der Produktionsumgebung den folgenden Befehl aus, um die Version von NGINX Open Source zu ermitteln, die der ausgeführten NGINX Plus-Version entspricht. In dieser Ausgabe ist sie orange hervorgehoben: NGINX 1.11.10, was NGINX Plus R12 entspricht.

production$ nginx -vnginx version: nginx/1.11.10 (nginx-plus-r12)

1. Laden Sie in der Build-Umgebung die Quelldateien für die entsprechende Version von NGINX Open Source herunter.

build-env$ wget -qO - http://nginx.org/download/nginx-1.11.10.tar.gz | tar zxfv -

Schritt 2: Quellen des dynamischen Moduls herunterladen

Kopieren Sie den Quellcode des dynamischen Moduls in das gewünschte Build-Verzeichnis. In diesem Beispiel kopieren wir ein NGINX-Beispielmodul namens „Hello World“ aus seinem GitHub-Repository.

buildenv$ git clone https://github.com/perusio/nginx-hello-world-module.git
Cloning into 'nginx-hello-world-module'...

Schritt 3: Kompilieren Sie das dynamische Modul

1. Kompilieren Sie das dynamische Modul, indem Sie zunächst das NGINX-Skript configure mit dem Argument --with-compat ausführen, um das dynamische Modul binärkompatibel mit NGINX Plus zu machen. Führen Sie anschließend make modules aus, um nur das Modul zu kompilieren.

buildenv$ cd nginx-1.11.10/buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
buildenv$ make modules

1. Überprüfen Sie, ob der Build-Prozess das dynamische Modul als .so-Datei im Unterverzeichnis objs erstellt hat.

buildenv$ ls objs/*.soobjs/ngx_http_hello_world.so

1. Erstellen Sie eine Kopie der Moduldatei, deren Dateiname die Version von NGINX Open Source enthält. Dies erleichtert die Verwaltung mehrerer Versionen des dynamischen Moduls in der Produktionsumgebung.

buildenv$ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.11.10.so

Schritt 4: Kopieren Sie das dynamische Modul in die Produktionsumgebung

Da wir das dynamische Modul mit der NGINX Open Source-Version im Dateinamen erstellt haben, können wir es bedenkenlos in die Produktionsumgebung kopieren, ohne den Betrieb zu beeinträchtigen.

buildenv$ scp ./ngx_http_hello_world_1.11.10.so production:/etc/nginx/modules

Schritt 5: Dynamisches Modul austauschen

Ersetzen Sie in der Produktionsumgebung die aktuelle .so-Datei durch die neue. Dies kann zu diesem Zeitpunkt gefahrlos durchgeführt werden, da dynamische Module erst in den Arbeitsspeicher geladen werden, wenn nginx neu gestartet oder die Konfiguration neu geladen wird.

production$ cd /etc/nginx/modulesproduction$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so
production$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so
production$ ls -gG
-rw-r--r-- 1 243576 Jan 31 16:18 ngx_http_hello_world_1.11.10.so
-rw-r--r-- 1 243576 Oct 20 10:40 ngx_http_hello_world_ROLLBACK.so
lrwxrwxrwx 1     24 Jan 31 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

Schritt 6: Upgrade von NGINX Plus abschließen

1. Führen Sie den folgenden Befehl aus, um zu überprüfen, ob die Modulversion korrekt und NGINX Plus bereit ist, den Upgradevorgang abzuschließen.

production$ nginx -tnginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

1. Schließen Sie den Upgrade-Vorgang ab, damit NGINX Plus die neue Version und die dynamischen Module verwendet.

production$ service nginx upgradeStarting new master nginx:                                 [  OK  ]
Graceful shutdown of old nginx:                            [  OK  ]

Verhindern des Upgrade-Fehlers

Wenn Sie NGINX Plus das nächste Mal aktualisieren, können Sie Zeit sparen und Fehler vermeiden, indem Sie vor dem Upgrade diese Anweisungen befolgen. So sind die aktualisierten dynamischen Module bereits verfügbar, wenn Sie den Upgrade-Vorgang starten.

Über den Autor

Liam CrillySenior Director, Produktmanagement

Weitere Blogbeiträge von Liam Crilly