upload: NGINX-Modul zur Handhabung 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 und 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 an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_upload_module.so;

Dieses Dokument beschreibt nginx-module-upload v2.3.0 veröffentlicht am 02. August 2018.

Ein Modul für nginx zur Handhabung von Datei-Uploads unter Verwendung von multipart/form-data-Codierung (RFC 1867) und wiederaufnehmbaren Uploads gemäß diesem Protokoll.

Beschreibung
Direktiven
Beispielkonfiguration
Lizenz

Beschreibung

Das Modul analysiert den Anfrageinhalt und speichert alle hochgeladenen Dateien in einem durch die upload_store Direktive angegebenen Verzeichnis. Die Dateien werden dann aus dem Inhalt entfernt und die veränderte Anfrage wird an einen durch die upload_pass Direktive angegebenen Ort weitergeleitet, wodurch eine beliebige Handhabung der hochgeladenen Dateien ermöglicht wird. Jedes der Datei-Felder wird durch eine Menge von Feldern ersetzt, die durch die upload_set_form_field Direktive angegeben sind. Der Inhalt jeder hochgeladenen Datei kann dann aus einer durch die $upload_tmp_path-Variable angegebenen Datei gelesen werden, oder die Datei kann einfach an das endgültige Ziel verschoben werden. Die Entfernung der Ausgabedateien wird durch die Direktive upload_cleanup gesteuert. Wenn eine Anfrage eine andere Methode als POST hat, gibt das Modul den Fehler 405 (Methode nicht erlaubt) 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 Anfrageinhalt weitergeleitet werden soll. Datei-Felder werden entfernt und durch Felder ersetzt, die die notwendigen Informationen zur Handhabung der hochgeladenen Dateien enthalten.

upload_resumable

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

Aktiviert wiederaufnehmbare Uploads.

upload_store

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

Gibt ein Verzeichnis an, in dem die Ausgabedateien gespeichert werden. Das Verzeichnis kann gehasht sein. In diesem Fall sollten alle Unterverzeichnisse existieren, bevor NGINX gestartet wird.

upload_state_store

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

Gibt ein Verzeichnis an, das die Statusdateien für wiederaufnehmbare Uploads enthalten wird. Das Verzeichnis kann gehasht sein. In diesem Fall sollten alle Unterverzeichnisse existieren, bevor NGINX gestartet wird.

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 Anfrageinhalt, die an das Backend weitergeleitet wird, generiert werden sollen. Sowohl name als auch value können folgende spezielle Variablen enthalten:

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

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

Beispiel:

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 für jede hochgeladene Datei im Anfrageinhalt, die an das Backend weitergeleitet wird, generiert werden sollen. Sowohl name als auch value können Standard-NGINX-Variablen, Variablen aus der upload_set_form_field Direktive und folgende zusätzliche spezielle Variablen enthalten:

$upload_file_md5: MD5-Checksumme der Datei
$upload_file_md5_uc: MD5-Checksumme der Datei in Großbuchstaben
$upload_file_sha1: SHA1-Checksumme der Datei
$upload_file_sha1_uc: SHA1-Checksumme der Datei in Großbuchstaben
$upload_file_crc32: hexadezimaler Wert von CRC32 der Datei
$upload_file_size: Größe der Datei in Bytes
$upload_file_number: Ordnungsnummer der Datei im Anfrageinhalt

Der Wert eines durch diese Direktive angegebenen Feldes wird nach erfolgreichem Upload der Datei ausgewertet, sodass diese Variablen nur am Ende der Verarbeitung eines Teils des ursprünglichen Anfrageinhalts gültig sind.

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-Checksummen.

Beispiel:

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 die Namen der Felder an, die aus dem ursprünglichen Anfrageinhalt an das Backend weitergeleitet werden. Diese Direktive kann mehrfach pro Ort angegeben werden. Das Feld wird an das Backend weitergeleitet, sobald das erste Muster übereinstimmt. Für PCRE-unbewusste Umgebungen gibt diese Direktive den genauen Namen eines Feldes an, das an das Backend weitergeleitet werden soll. Wenn die Direktive weggelassen wird, werden keine Felder vom Client an das Backend weitergeleitet.

Beispiel:

upload_pass_form_field "^submit$|^description$";

Für PCRE-unbewusste 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 Erzeugung alle erfolgreich hochgeladenen Dateien in der aktuellen Anfrage 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 von 400-599 sein, führende Nullen sind nicht erlaubt. Bereiche von Statuscodes können mit einem Bindestrich angegeben werden.

Beispiel:

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 in Bytes des Schreibpuffers, der verwendet wird, um Dateidaten zu sammeln und auf die Festplatte zu schreiben. Diese Direktive ist dazu gedacht, einen Kompromiss zwischen Speicherverbrauch und Systemaufrufrate zu erzielen.

upload_max_part_header_len

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

Gibt die maximale Länge des Teile-Headers in Bytes an. Bestimmt die Größe des Puffers, der verwendet wird, um Teile-Header zu sammeln.

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 ignoriert. Diese Direktive gibt ein "weiches" Limit an, in dem Sinne, dass NGINX nach dem Erkennen einer Datei, die länger als das angegebene Limit ist, weiterhin den Anfrageinhalt 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 Einschränkungen für die Dateigröße gelten sollen.

upload_limit_rate

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

Gibt das Upload-Rate-Limit 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 Ausgabekörpers an. Dies verhindert das Ansammeln von nicht-Datei-Formularfeldern im Speicher. Wann immer der Ausgabekörper das angegebene Limit überschreitet, wird der Fehler 413 (Anfrageentität zu groß) erzeugt. Der Wert null für diese Direktive gibt an, dass keine Einschränkungen für die Länge des Ausgabekörpers gelten 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 Abfrageargumenten an den Ort, der durch upload_pass angegeben ist. Wirksam nicht bei benannten Orten. 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 Anfrage-URI "/upload?id=5". Im Falle von upload_pass_args off erhält das Backend "/upload".

Beispielkonfiguration

server {
    client_max_body_size 100m;
    listen 80;

    # Das Upload-Formular sollte an diesen Ort gesendet werden
    location /upload/ {
        # Übergebe den veränderten Anfrageinhalt an diesen Ort
        upload_pass @test;

        # Speichere Dateien in diesem Verzeichnis
        # Das Verzeichnis ist gehasht, Unterverzeichnisse 0 1 2 3 4 5 6 7 8 9 sollten existieren
        upload_store /tmp 1;

        # Erlaube, dass hochgeladene Dateien nur vom Benutzer gelesen werden können
        upload_store_access user:r;

        # Setze die angegebenen Felder im Anfrageinhalt
        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";

        # Informiere das Backend über Hash und Größe einer Datei
        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;
    }

    # Übergebe den veränderten Anfrageinhalt an ein 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>

GitHub

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