upload: NGINX-Modul zur Verarbeitung von Datei-Uploads

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 and Amazon Linux 2

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

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-upload

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

load_module modules/ngx_http_upload_module.so;

Dieses Dokument beschreibt nginx-module-upload v2.4.0, veröffentlicht am 03. Februar 2026.

---

Ein Modul für nginx zur Verarbeitung von Datei-Uploads mittels multipart/form-data-Kodierung (RFC 1867) und fortsetzbaren Uploads gemäß diesem Protokoll.

• Beschreibung
• Direktiven
  • upload_pass
  • upload_resumable
  • upload_store
  • upload_state_store
  • upload_store_access
  • upload_set_form_field
  • upload_aggregate_form_field
  • upload_pass_form_field
  • upload_cleanup
  • upload_buffer_size
  • upload_max_part_header_len
  • upload_max_file_size
  • upload_limit_rate
  • upload_max_output_body_len
  • upload_tame_arrays
  • upload_pass_args
• Beispielkonfiguration
• Lizenz

Beschreibung

Das Modul parst den Request-Body und speichert alle hochgeladenen Dateien in einem Verzeichnis, das durch die Direktive upload_store angegeben wird. Die Dateien werden anschließend aus dem Body entfernt und die geänderte Anfrage wird an einen Ort weitergeleitet, der durch die Direktive upload_pass angegeben wird, wodurch eine beliebige Verarbeitung der hochgeladenen Dateien ermöglicht wird. Jedes Dateifeld wird durch eine Reihe von Feldern ersetzt, die durch die Direktive upload_set_form_field angegeben werden. Der Inhalt jeder hochgeladenen Datei kann dann aus einer Datei gelesen werden, die durch die Variable $upload_tmp_path angegeben wird, oder die Datei kann einfach an ihren endgültigen Zielort verschoben werden. Das Entfernen der Ausgabedateien wird durch die Direktive upload_cleanup gesteuert. Wenn eine Anfrage eine andere Methode als POST verwendet, gibt das Modul den Fehler 405 (Method not allowed) zurück. Anfragen mit solchen Methoden können an einem alternativen Ort über die error_page-Direktive verarbeitet werden.

Direktiven

upload_pass

Syntax: upload_pass location
Standard: —
Kontext: server,location

Gibt den Ort an, an den der Request-Body weitergeleitet werden soll. Dateifelder werden entfernt und durch Felder ersetzt, die die notwendigen Informationen zur Verarbeitung hochgeladener Dateien enthalten.

upload_resumable

Syntax: upload_resumable on | off
Standard: upload_resumable off
Kontext: main,server,location

Aktiviert fortsetzbare Uploads.

upload_store

Syntax: upload_store directory [level1 [level2]] ...
Standard: —
Kontext: server,location

Gibt ein Verzeichnis an, in dem Ausgabedateien gespeichert werden. Das Verzeichnis kann gehasht werden. In diesem Fall müssen alle Unterverzeichnisse vor dem Start von nginx existieren.

upload_state_store

Syntax: upload_state_store directory [level1 [level2]] ...
Standard: —
Kontext: server,location

Gibt ein Verzeichnis an, das Statusdateien für fortsetzbare Uploads enthält. Das Verzeichnis kann gehasht werden. In diesem Fall müssen alle Unterverzeichnisse vor dem Start von nginx existieren.

upload_store_access

Syntax: upload_store_access mode
Standard: upload_store_access user:rw
Kontext: server,location

Gibt den Zugriffsmodus an, der zum Erstellen von Ausgabedateien verwendet wird.

upload_set_form_field

Syntax: upload_set_form_field name value
Standard: —
Kontext: server,location

Gibt ein oder mehrere Formularfelder an, die für jede hochgeladene Datei im Request-Body generiert werden, der an das Backend weitergeleitet wird. Sowohl name als auch value können die folgenden speziellen Variablen enthalten:

• $upload_field_name: der Name des ursprünglichen Dateifelds
• $upload_content_type: der Inhaltstyp der hochgeladenen Datei
• $upload_file_name: der ursprüngliche Name der hochgeladenen Datei mit führenden Pfadelementen in DOS- und UNIX-Notation entfernt. D.h. "D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg" wird zu "Picture.jpg" konvertiert und "/etc/passwd" wird zu "passwd" konvertiert.
• $upload_tmp_path: der Pfad, in dem der Inhalt der ursprünglichen Datei gespeichert wird. Der Ausgabedateiname besteht aus 10 Ziffern und wird mit demselben Algorithmus generiert wie in der Direktive proxy_temp_path.

Diese Variablen sind nur während der Verarbeitung eines Teils des ursprünglichen Request-Bodys gültig.

Verwendungsbeispiel:

upload_set_form_field $upload_field_name.name "$upload_file_name";
upload_set_form_field $upload_field_name.content_type "$upload_content_type";
upload_set_form_field $upload_field_name.path "$upload_tmp_path";

upload_aggregate_form_field

Syntax: upload_aggregate_form_field name value
Standard: —
Kontext: server,location

Gibt ein oder mehrere Formularfelder an, die aggregierte Attribute enthalten und für jede hochgeladene Datei im Request-Body generiert werden, der an das Backend weitergeleitet wird. Sowohl name als auch value können Standard-nginx-Variablen, Variablen aus der upload_set_form_field-Direktive und die folgenden zusätzlichen speziellen Variablen enthalten:

• $upload_file_md5: MD5-Prüfsumme der Datei
• $upload_file_md5_uc: MD5-Prüfsumme der Datei in Großbuchstaben
• $upload_file_sha1: SHA1-Prüfsumme der Datei
• $upload_file_sha1_uc: SHA1-Prüfsumme der Datei in Großbuchstaben
• $upload_file_sha256: SHA256-Prüfsumme der Datei
• $upload_file_sha256_uc: SHA256-Prüfsumme der Datei in Großbuchstaben
• $upload_file_sha512: SHA512-Prüfsumme der Datei
• $upload_file_sha512_uc: SHA512-Prüfsumme der Datei in Großbuchstaben
• $upload_file_crc32: hexadezimaler Wert der CRC32 der Datei
• $upload_file_size: Größe der Datei in Bytes
• $upload_file_number: Ordnungsnummer der Datei im Request-Body

Der Wert eines durch diese Direktive angegebenen Felds wird nach erfolgreichem Upload der Datei ausgewertet, daher sind diese Variablen nur am Ende der Verarbeitung eines Teils des ursprünglichen Request-Bodys gültig.

Warnung: Die Variablen $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 und $upload_file_sha1_uc verwenden zusätzliche Ressourcen zur Berechnung der MD5- und SHA1-Prüfsummen.

Verwendungsbeispiel:

upload_aggregate_form_field $upload_field_name.md5 "$upload_file_md5";
upload_aggregate_form_field $upload_field_name.size "$upload_file_size";

upload_pass_form_field

Syntax: upload_pass_form_field regex
Standard: —
Kontext: server,location

Gibt ein Regex-Muster für Namen von Feldern an, die aus dem ursprünglichen Request-Body an das Backend weitergeleitet werden. Diese Direktive kann mehrfach pro Location angegeben werden. Ein Feld wird an das Backend weitergeleitet, sobald das erste Muster übereinstimmt. Für PCRE-unfähige Umgebungen gibt diese Direktive den exakten Namen eines Felds an, das an das Backend weitergeleitet werden soll. Wenn die Direktive weggelassen wird, werden keine Felder vom Client an das Backend weitergeleitet.

Verwendungsbeispiel:

upload_pass_form_field "^submit$|^description$";

Für PCRE-unfähige Umgebungen:

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Syntax: upload_cleanup status/range ...
Standard: —
Kontext: server,location

Gibt HTTP-Statuscodes an, nach deren Generierung alle in der aktuellen Anfrage erfolgreich hochgeladenen Dateien entfernt werden. Wird zur Bereinigung nach einem Backend- oder Serverfehler verwendet. Das Backend kann auch explizit einen fehlerhaften Status signalisieren, wenn es die hochgeladenen Dateien aus irgendeinem Grund nicht benötigt. Der HTTP-Status muss ein numerischer Wert im Bereich 400-599 sein, führende Nullen sind nicht erlaubt. Bereiche von Statuscodes können mit einem Bindestrich angegeben werden.

Verwendungsbeispiel:

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Syntax: upload_buffer_size size
Standard: Größe der Speicherseite in Bytes
Kontext: server,location

Größe des Schreibpuffers in Bytes, der zum Ansammeln von Dateidaten und deren Schreiben auf die Festplatte verwendet wird. Diese Direktive ist dafür gedacht, einen Kompromiss zwischen Speicherverbrauch und Syscall-Rate zu finden.

upload_max_part_header_len

Syntax: upload_max_part_header_len size
Standard: 512
Kontext: server,location

Gibt die maximale Länge des Teil-Headers in Bytes an. Bestimmt die Größe des Puffers, der zum Ansammeln von Teil-Headern verwendet wird.

upload_max_file_size

Syntax: upload_max_file_size size
Standard: 0
Kontext: main,server,location

Gibt die maximale Größe der Datei an. Dateien, die länger als der Wert dieser Direktive sind, werden ausgelassen. Diese Direktive gibt ein "weiches" Limit an, in dem Sinne, dass nginx nach dem Auftreten einer Datei, die länger als das angegebene Limit ist, weiterhin den Request-Body verarbeitet und versucht, die verbleibenden Dateien zu empfangen. Für ein "hartes" Limit muss die Direktive client_max_body_size verwendet werden. Der Wert Null für diese Direktive gibt an, dass keine Beschränkungen der Dateigröße angewendet werden sollen.

upload_limit_rate

Syntax: upload_limit_rate rate
Standard: 0
Kontext: main,server,location

Gibt das Upload-Ratenlimit in Bytes pro Sekunde an. Null bedeutet, dass die Rate unbegrenzt ist.

upload_max_output_body_len

Syntax: upload_max_output_body_len size
Standard: 100k
Kontext: main,server,location

Gibt die maximale Länge des Ausgabe-Bodys an. Dies verhindert das Anhäufen von Nicht-Datei-Formularfeldern im Speicher. Wann immer der Ausgabe-Body das angegebene Limit überschreitet, wird der Fehler 413 (Request entity too large) generiert. Der Wert Null für diese Direktive gibt an, dass keine Beschränkungen der Ausgabe-Body-Länge angewendet werden sollen.

upload_tame_arrays

Syntax: upload_tame_arrays on | off
Standard: off
Kontext: main,server,location

Gibt an, ob eckige Klammern in Dateifeldnamen entfernt werden müssen (erforderlich für PHP-Arrays).

upload_pass_args

Syntax: upload_pass_args on | off
Standard: off
Kontext: main,server,location

Aktiviert die Weiterleitung von Query-Argumenten an den Ort, der durch upload_pass angegeben wird. Unwirksam bei benannten Locations. Beispiel:

<form action="/upload/?id=5">
<!-- ... -->

location /upload/ {
    upload_pass /internal_upload/;
    upload_pass_args on;
}

## ...

location /internal_upload/ {
    # ...
    proxy_pass http://backend;
}

In diesem Beispiel erhält das Backend die Request-URI "/upload?id=5". Im Fall von upload_pass_args off erhält das Backend "/upload".

Beispielkonfiguration

server {
    client_max_body_size 100m;
    listen 80;

    # Upload form should be submitted to this location
    location /upload/ {
        # Pass altered request body to this location
        upload_pass @test;

        # Store files to this directory
        # The directory is hashed, subdirectories 0 1 2 3 4 5 6 7 8 9 should exist
        upload_store /tmp 1;

        # Allow uploaded files to be read only by user
        upload_store_access user:r;

        # Set specified fields in request body
        upload_set_form_field $upload_field_name.name "$upload_file_name";
        upload_set_form_field $upload_field_name.content_type "$upload_content_type";
        upload_set_form_field $upload_field_name.path "$upload_tmp_path";

        # Inform backend about hash and size of a file
        upload_aggregate_form_field "$upload_field_name.md5" "$upload_file_md5";
        upload_aggregate_form_field "$upload_field_name.size" "$upload_file_size";

        upload_pass_form_field "^submit$|^description$";

        upload_cleanup 400 404 499 500-505;
    }

    # Pass altered request body to a backend
    location @test {
        proxy_pass http://localhost:8080;
    }
}

<form name="upload" method="POST" enctype="multipart/form-data" action="/upload/">
<input type="file" name="file1">
<input type="file" name="file2">
<input type="hidden" name="test" value="value">
<input type="submit" name="submit" value="Upload">
</form>