upload : module NGINX pour la gestion des téléversements de fichiers

Installation

Vous pouvez installer ce module sur n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

• RedHat Enterprise Linux 7, 8, 9 et 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 et 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

Activez le module en ajoutant ce qui suit au début de /etc/nginx/nginx.conf :

load_module modules/ngx_http_upload_module.so;

Ce document décrit nginx-module-upload v2.4.0 publié le 03 février 2026.

---

Un module pour nginx permettant de gérer les téléversements de fichiers à l'aide de l'encodage multipart/form-data (RFC 1867) et des téléversements reprenables selon ce protocole.

• Description
• Directives
  • 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
• Exemple de configuration
• Licence

Description

Le module analyse le corps de la requête en stockant tous les fichiers en cours de téléversement dans un répertoire spécifié par la directive upload_store. Les fichiers sont ensuite retirés du corps et la requête modifiée est alors transmise à un emplacement spécifié par la directive upload_pass, ce qui permet une gestion arbitraire des fichiers téléversés. Chacun des champs de fichier est remplacé par un ensemble de champs spécifiés par la directive upload_set_form_field. Le contenu de chaque fichier téléversé peut ensuite être lu depuis un fichier spécifié par la variable $upload_tmp_path ou le fichier peut être simplement déplacé vers sa destination finale. La suppression des fichiers de sortie est contrôlée par la directive upload_cleanup. Si une requête utilise une méthode autre que POST, le module renvoie l'erreur 405 (Method not allowed). Les requêtes avec de telles méthodes peuvent être traitées dans un emplacement alternatif via la directive error_page.

Directives

upload_pass

Syntaxe : upload_pass location
Défaut : —
Contexte : server,location

Spécifie l'emplacement auquel transmettre le corps de la requête. Les champs de fichier seront retirés et remplacés par des champs contenant les informations nécessaires pour gérer les fichiers téléversés.

upload_resumable

Syntaxe : upload_resumable on | off
Défaut : upload_resumable off
Contexte : main,server,location

Active les téléversements reprenables.

upload_store

Syntaxe : upload_store directory [level1 [level2]] ...
Défaut : —
Contexte : server,location

Spécifie un répertoire dans lequel les fichiers de sortie seront enregistrés. Le répertoire peut être haché. Dans ce cas, tous les sous-répertoires doivent exister avant le démarrage de nginx.

upload_state_store

Syntaxe : upload_state_store directory [level1 [level2]] ...
Défaut : —
Contexte : server,location

Spécifie un répertoire qui contiendra les fichiers d'état pour les téléversements reprenables. Le répertoire peut être haché. Dans ce cas, tous les sous-répertoires doivent exister avant le démarrage de nginx.

upload_store_access

Syntaxe : upload_store_access mode
Défaut : upload_store_access user:rw
Contexte : server,location

Spécifie le mode d'accès qui sera utilisé pour créer les fichiers de sortie.

upload_set_form_field

Syntaxe : upload_set_form_field name value
Défaut : —
Contexte : server,location

Spécifie un ou des champs de formulaire à générer pour chaque fichier téléversé dans le corps de la requête transmis au backend. name et value peuvent tous deux contenir les variables spéciales suivantes :

• $upload_field_name : le nom du champ de fichier d'origine
• $upload_content_type : le type de contenu du fichier téléversé
• $upload_file_name : le nom d'origine du fichier en cours de téléversement avec les éléments de chemin de tête en notation DOS et UNIX supprimés. C'est-à-dire que "D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg" sera converti en "Picture.jpg" et "/etc/passwd" sera converti en "passwd".
• $upload_tmp_path : le chemin où le contenu du fichier d'origine est stocké. Le nom du fichier de sortie est composé de 10 chiffres et généré avec le même algorithme que dans la directive proxy_temp_path.

Ces variables ne sont valides que pendant le traitement d'une partie du corps de la requête d'origine.

Exemple d'utilisation :

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

Syntaxe : upload_aggregate_form_field name value
Défaut : —
Contexte : server,location

Spécifie un ou des champs de formulaire contenant des attributs agrégés à générer pour chaque fichier téléversé dans le corps de la requête transmis au backend. Le nom et la valeur peuvent contenir des variables nginx standard, des variables de la directive upload_set_form_field et les variables spéciales supplémentaires suivantes :

• $upload_file_md5 : somme de contrôle MD5 du fichier
• $upload_file_md5_uc : somme de contrôle MD5 du fichier en lettres majuscules
• $upload_file_sha1 : somme de contrôle SHA1 du fichier
• $upload_file_sha1_uc : somme de contrôle SHA1 du fichier en lettres majuscules
• $upload_file_sha256 : somme de contrôle SHA256 du fichier
• $upload_file_sha256_uc : somme de contrôle SHA256 du fichier en lettres majuscules
• $upload_file_sha512 : somme de contrôle SHA512 du fichier
• $upload_file_sha512_uc : somme de contrôle SHA512 du fichier en lettres majuscules
• $upload_file_crc32 : valeur hexadécimale du CRC32 du fichier
• $upload_file_size : taille du fichier en octets
• $upload_file_number : numéro d'ordre du fichier dans le corps de la requête

La valeur d'un champ spécifié par cette directive est évaluée après le téléversement réussi du fichier, ces variables ne sont donc valides qu'à la fin du traitement d'une partie du corps de la requête d'origine.

Avertissement : les variables $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 et $upload_file_sha1_uc utilisent des ressources supplémentaires pour calculer les sommes de contrôle MD5 et SHA1.

Exemple d'utilisation :

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

Syntaxe : upload_pass_form_field regex
Défaut : —
Contexte : server,location

Spécifie un motif regex pour les noms des champs qui seront transmis au backend depuis le corps de la requête d'origine. Cette directive peut être spécifiée plusieurs fois par emplacement. Le champ sera transmis au backend dès que le premier motif correspond. Pour les environnements sans PCRE, cette directive spécifie le nom exact d'un champ à transmettre au backend. Si la directive est omise, aucun champ ne sera transmis au backend depuis le client.

Exemple d'utilisation :

upload_pass_form_field "^submit$|^description$";

Pour les environnements sans PCRE :

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Syntaxe : upload_cleanup status/range ...
Défaut : —
Contexte : server,location

Spécifie les statuts HTTP après la génération desquels tous les fichiers téléversés avec succès dans la requête courante seront supprimés. Utilisé pour le nettoyage après une défaillance du backend ou du serveur. Le backend peut également signaler explicitement un statut d'erreur s'il n'a pas besoin des fichiers téléversés pour une raison quelconque. Le statut HTTP doit être une valeur numérique comprise entre 400 et 599, aucun zéro initial n'est autorisé. Des plages de statuts peuvent être spécifiées avec un tiret.

Exemple d'utilisation :

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Syntaxe : upload_buffer_size size
Défaut : taille de la page mémoire en octets
Contexte : server,location

Taille en octets du tampon d'écriture qui sera utilisé pour accumuler les données du fichier et les écrire sur le disque. Cette directive est destinée à être utilisée pour faire un compromis entre l'utilisation de la mémoire et le taux d'appels système.

upload_max_part_header_len

Syntaxe : upload_max_part_header_len size
Défaut : 512
Contexte : server,location

Spécifie la longueur maximale de l'en-tête de partie en octets. Détermine la taille du tampon qui sera utilisé pour accumuler les en-têtes de partie.

upload_max_file_size

Syntaxe : upload_max_file_size size
Défaut : 0
Contexte : main,server,location

Spécifie la taille maximale du fichier. Les fichiers plus longs que la valeur de cette directive seront omis. Cette directive spécifie une limite "souple", en ce sens qu'après avoir rencontré un fichier plus long que la limite spécifiée, nginx continuera à traiter le corps de la requête, en essayant de recevoir les fichiers restants. Pour une limite "dure", la directive client_max_body_size doit être utilisée. La valeur zéro pour cette directive spécifie qu'aucune restriction sur la taille des fichiers ne doit être appliquée.

upload_limit_rate

Syntaxe : upload_limit_rate rate
Défaut : 0
Contexte : main,server,location

Spécifie la limite de débit de téléversement en octets par seconde. Zéro signifie que le débit est illimité.

upload_max_output_body_len

Syntaxe : upload_max_output_body_len size
Défaut : 100k
Contexte : main,server,location

Spécifie la longueur maximale du corps de sortie. Cela empêche l'accumulation de champs de formulaire non-fichiers en mémoire. Chaque fois que le corps de sortie dépasse la limite spécifiée, l'erreur 413 (Request entity too large) sera générée. La valeur zéro pour cette directive spécifie qu'aucune restriction sur la longueur du corps de sortie ne doit être appliquée.

upload_tame_arrays

Syntaxe : upload_tame_arrays on | off
Défaut : off
Contexte : main,server,location

Spécifie si les crochets dans les noms de champs de fichier doivent être supprimés (nécessaire pour les tableaux PHP).

upload_pass_args

Syntaxe : upload_pass_args on | off
Défaut : off
Contexte : main,server,location

Active la transmission des arguments de requête vers l'emplacement spécifié par upload_pass. Sans effet avec les emplacements nommés. Exemple :

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

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

## ...

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

Dans cet exemple, le backend reçoit l'URI de requête "/upload?id=5". Dans le cas de upload_pass_args off, le backend reçoit "/upload".

Exemple de configuration

server {
    client_max_body_size 100m;
    listen 80;

    # Le formulaire de téléversement doit être soumis à cet emplacement
    location /upload/ {
        # Transmettre le corps de la requête modifié à cet emplacement
        upload_pass @test;

        # Stocker les fichiers dans ce répertoire
        # Le répertoire est haché, les sous-répertoires 0 1 2 3 4 5 6 7 8 9 doivent exister
        upload_store /tmp 1;

        # Autoriser la lecture des fichiers téléversés uniquement par l'utilisateur
        upload_store_access user:r;

        # Définir les champs spécifiés dans le corps de la requête
        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";

        # Informer le backend du hachage et de la taille d'un fichier
        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;
    }

    # Transmettre le corps de la requête modifié à un 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>