acme: Automatisches Zertifikatsmanagement (ACMEv2) Modul für NGINX

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

RedHat Enterprise Linux 7, 8, 9 und 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-acme

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-acme

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_acme_module.so;

Dieses Dokument beschreibt nginx-module-acme v0.3.1, veröffentlicht am 08. Dezember 2025.

nginx-acme

nginx-acme ist ein NGINX Modul mit der Implementierung des automatischen Zertifikatsmanagements (ACMEv2) Protokolls.

Das Modul implementiert folgende Spezifikationen:

RFC8555 (Automatisches Zertifikatsmanagement-Umgebung) mit Einschränkungen:
- Nur der HTTP-01 Challenge-Typ wird unterstützt
RFC8737 (ACME TLS Anwendungsprotokollverhandlungs (ALPN) Challenge Erweiterung)
RFC8738 (ACME IP-Identifikator Validierungserweiterung)
draft-ietf-acme-profiles (ACME Profile Erweiterung, Version 00)

Erste Schritte

checkout, konfigurieren und NGINX in ../nginx bauen

cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release

Das Ergebnis wird sich unter `target/release/libnginx_acme.so` befinden.

Eine andere Möglichkeit ist die Verwendung des bereitgestellten Konfigurationsskripts:

```sh
## im NGINX Quellverzeichnis
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

Das Ergebnis wird sich unter objs/ngx_http_acme_module.so befinden.

Derzeit produziert diese Methode eine leicht größere Bibliothek, da wir den Linker nicht anweisen, LTO durchzuführen und ungenutzten Code zu entfernen.

Testen

Das Repository enthält eine Integrationstest-Suite basierend auf den nginx-tests. Der folgende Befehl wird das Modul bauen und die Tests ausführen:

## Pfad zum NGINX Quell-Checkout, standardmäßig ../nginx, wenn nicht angegeben.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Pfad zum nginx-tests Checkout; standardmäßig ../nginx/tests, wenn nicht angegeben.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

Die meisten Tests erfordern die pebble Testserver-Binärdatei im Pfad oder an einem Ort, der über die Umgebungsvariable TEST_NGINX_PEBBLE_BINARY angegeben ist.

Verwendung

Fügen Sie das Modul zur NGINX-Konfiguration hinzu und konfigurieren Sie es wie unten beschrieben. Beachten Sie, dass dieses Modul eine resolver Konfiguration im http Block erfordert.

Beispielkonfiguration

resolver 127.0.0.1:53;

acme_issuer example {
    uri         https://acme.example.com/directory;
    # contact     [email protected];
    state_path  /var/cache/nginx/acme-example;
    accept_terms_of_service;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    listen 443 ssl;
    server_name  .example.test
                 192.0.2.1      # wird von einigen ACME-Servern nicht unterstützt
                 2001:db8::1    # wird von einigen ACME-Servern nicht unterstützt
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # das Zertifikat nicht bei jeder Anfrage parsen
    ssl_certificate_cache max=2;
}

server {
    # Listener auf Port 80 ist erforderlich, um ACME HTTP-01 Herausforderungen zu verarbeiten
    listen 80;

    location / {
        return 404;
    }
}

Direktiven

[!WICHTIG] Die folgende Referenz spiegelt die aktuelle Entwicklungsversion wider. Siehe ngx_http_acme_module Dokumentation auf nginx.org für die neueste veröffentlichte Version.

acme_issuer

Syntax: acme_issuer name { ... }

Standard: -

Kontext: http

Definiert ein ACME-Zertifikatsausstellerobjekt.

uri

Syntax: uri uri

Standard: -

Kontext: acme_issuer

Die Verzeichnis-URL des ACME-Servers. Diese Direktive ist obligatorisch.

account_key

Syntax: account_key alg[:size] | file

Standard: -

Kontext: acme_issuer

Der private Schlüssel des Kontos, der zur Authentifizierung von Anfragen verwendet wird.

Akzeptierte Werte:

ecdsa:256/384/521 für ES256, ES384 oder ES512 JSON Web Signature Algorithmen
rsa:2048/3072/4096 für RS256.
Dateipfad für einen vorhandenen Schlüssel, unter Verwendung eines der oben genannten Algorithmen.

Die generierten Kontoschlüssel werden über Reloads hinweg beibehalten, gehen jedoch beim Neustart verloren, es sei denn, state_path ist konfiguriert.

challenge

Syntax: challenge type

Standard: http-01

Kontext: acme_issuer

Diese Direktive erschien in Version 0.2.0.

Spezifiziert den ACME-Herausforderungstyp, der für den Aussteller verwendet werden soll.

Akzeptierte Werte:

http-01 (http)
tls-alpn-01 (tls-alpn)

ACME-Herausforderungen sind versioniert. Wenn ein nicht versionierter Name angegeben wird, wählt das Modul automatisch die neueste implementierte Version.

contact

Syntax: contact URL

Standard: -

Kontext: acme_issuer

Setzt ein Array von URLs, die der ACME-Server verwenden kann, um den Client bei Kontoproblemen zu kontaktieren. Das mailto:-Schema wird verwendet, es sei denn, es wird ausdrücklich angegeben.

external_account_key

Syntax: external_account_key kid file

Standard: -

Kontext: acme_issuer

Diese Direktive erschien in Version 0.2.0.

Spezifiziert einen Schlüsselidentifikator kid und eine file mit dem MAC-Schlüssel für externe Kontoberechtigung.

Der Wert data:key kann anstelle der file angegeben werden, was einen Schlüssel direkt aus der Konfiguration lädt, ohne Zwischenablagen zu verwenden.

In beiden Fällen wird erwartet, dass der Schlüssel in base64url kodiert ist.

preferred_chain

Syntax: preferred_chain name

Standard: -

Kontext: acme_issuer

Diese Direktive erschien in Version 0.3.0.

Spezifiziert die bevorzugte Zertifikatskette.

Wenn der ACME-Server mehrere Zertifikatsketten anbietet, bevorzugen Sie die Kette mit dem obersten Zertifikat, das von dem Subject Common Name name ausgestellt wurde. Wenn es keine Übereinstimmungen gibt, wird die Standardkette verwendet.

profile

Syntax: profile name [require]

Standard: -

Kontext: acme_issuer

Diese Direktive erschien in Version 0.3.0.

Fordert das Zertifikatsprofil name vom ACME-Server an.

Der require Parameter führt dazu, dass Zertifikatserneuerungen fehlschlagen, wenn der Server das angegebene Profil nicht unterstützt.

ssl_trusted_certificate

Syntax: ssl_trusted_certificate file

Standard: System CA-Bündel

Kontext: acme_issuer

Spezifiziert eine file mit vertrauenswürdigen CA-Zertifikaten im PEM-Format, die verwendet werden, um das Zertifikat des ACME-Servers zu überprüfen.

ssl_verify

Syntax: ssl_verify on | off

Standard: on

Kontext: acme_issuer

Aktiviert oder deaktiviert die Überprüfung des ACME-Serverzertifikats.

state_path

Syntax: state_path path | off

Standard: acme_<name>

Kontext: acme_issuer

Definiert ein Verzeichnis zum Speichern der Moduldaten, die über Neustarts hinweg beibehalten werden können. Dies kann die Ladezeit verbessern, indem einige Anfragen beim Start übersprungen werden, und vermeiden, die Anfragegrenzwerte des ACME-Servers zu überschreiten.

Das Verzeichnis enthält sensible Inhalte, wie den Kontoschlüssel, ausgestellte Zertifikate und private Schlüssel.

Der off Parameter (0.2.0) deaktiviert das Speichern der Kontoinformationen und ausgestellten Zertifikate auf der Festplatte.

Vor Version 0.2.0 wurde das Zustandsverzeichnis standardmäßig nicht erstellt.

accept_terms_of_service

Syntax: accept_terms_of_service

Standard: -

Kontext: acme_issuer

Stimmt den Nutzungsbedingungen zu, unter denen der ACME-Server verwendet wird. Einige Server verlangen, dass die Nutzungsbedingungen akzeptiert werden, bevor die Kontoanmeldung erfolgt. Die Bedingungen sind normalerweise auf der Website des ACME-Servers verfügbar, und die URL wird bei Bedarf im Fehlerprotokoll ausgegeben.

acme_shared_zone

Syntax: acme_shared_zone zone=name:size

Standard: zone=ngx_acme_shared:256k

Kontext: http

Erlaubt die Erhöhung der Größe des speicherinternen Speichers des Moduls. Die gemeinsame Speicherzone wird verwendet, um die ausgestellten Zertifikate, Schlüssel und Herausforderungsdaten für alle konfigurierten Zertifikatsaussteller zu speichern.

Die Standardzonen-Größe reicht aus, um ungefähr 50 ECDSA prime256v1 Schlüssel oder 35 RSA 2048 Schlüssel zu halten.

acme_certificate

Syntax: acme_certificate issuer [identifier ...] [key=alg[:size]]

Standard: -

Kontext: server

Definiert ein Zertifikat mit der Liste von identifiers, die vom Aussteller issuer angefordert werden.

Die explizite Liste von Identifikatoren kann weggelassen werden. In diesem Fall werden die Identifikatoren aus der server_name Direktive im selben server Block übernommen. Nicht alle Werte, die in der server_name akzeptiert werden, sind gültige Zertifikatsidentifikatoren: Reguläre Ausdrücke und Wildcards werden nicht unterstützt.

Der key Parameter legt den Typ eines generierten privaten Schlüssels fest. Unterstützte Schlüsselalgorithmen und -größen: ecdsa:256 (Standard), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

Eingebettete Variablen

Das ngx_http_acme_module Modul unterstützt eingebettete Variablen, die im server Block mit der acme_certificate Direktive gültig sind:

`$acme_certificate`

SSL-Zertifikat, das an das ssl_certificate übergeben werden kann.

`$acme_certificate_key`

Privater Schlüssel des SSL-Zertifikats, der an das ssl_certificate_key übergeben werden kann.

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub Repository für nginx-module-acme.