upload: module NGINX pour gérer les téléchargements de fichiers

Installation

Vous pouvez installer ce module dans 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 et 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 en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_upload_module.so;

Ce document décrit nginx-module-upload v2.3.0 publié le 02 août 2018.

---

Un module pour nginx pour gérer les téléchargements de fichiers en utilisant l'encodage multipart/form-data (RFC 1867) et les téléchargements récupérables selon ceci 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 téléchargés dans un répertoire spécifié par la directive upload_store. Les fichiers sont ensuite extraits du corps et la requête modifiée est ensuite transmise à un emplacement spécifié par la directive upload_pass, permettant ainsi un traitement arbitraire des fichiers téléchargés. Chacun des champs de fichiers est remplacé par un ensemble de champs spécifiés par la directive upload_set_form_field. Le contenu de chaque fichier téléchargé peut ensuite être lu à partir d'un fichier spécifié par la variable $upload_tmp_path ou le fichier peut simplement être déplacé vers la destination finale. La suppression des fichiers de sortie est contrôlée par la directive upload_cleanup. Si une requête a une méthode autre que POST, le module renvoie l'erreur 405 (Méthode non autorisée). 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
Par défaut : —
Contexte : server,location

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

upload_resumable

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

Active les téléchargements récupérables.

upload_store

Syntaxe : upload_store directory [level1 [level2]] ...
Par 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 de démarrer nginx.

upload_state_store

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

Spécifie un répertoire qui contiendra des fichiers d'état pour les téléchargements récupérables. Le répertoire peut être haché. Dans ce cas, tous les sous-répertoires doivent exister avant de démarrer nginx.

upload_store_access

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

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

upload_set_form_field

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

Spécifie un ou plusieurs champs de formulaire à générer pour chaque fichier téléchargé dans le corps de la requête passé au backend. Les deux name et value peuvent 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échargé
• $upload_file_name : le nom d'origine du fichier téléchargé avec les éléments de chemin précédents en notation DOS et UNIX supprimés. Par exemple, "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 constitué 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
Par défaut : —
Contexte : server,location

Spécifie un ou plusieurs champs de formulaire contenant des attributs agrégés à générer pour chaque fichier téléchargé dans le corps de la requête passé au backend. Les deux name et value peuvent contenir des variables standard de nginx, 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_crc32 : valeur hexadécimale de CRC32 du fichier
• $upload_file_size : taille du fichier en octets
• $upload_file_number : numéro ordinal 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échargement réussi du fichier, ainsi ces variables ne sont 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
Par défaut : —
Contexte : server,location

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

Exemple d'utilisation :

upload_pass_form_field "^submit$|^description$";

Pour les environnements non conscients de PCRE :

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

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

Spécifie les statuts HTTP après la génération desquels tous les fichiers téléchargés avec succès dans la requête actuelle 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 erroné s'il n'a pas besoin des fichiers téléchargés pour une raison quelconque. Le statut HTTP doit être une valeur numérique dans la plage 400-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
Par 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 de fichier et les écrire sur le disque. Cette directive est destinée à être utilisée pour compromettre l'utilisation de la mémoire par rapport au taux d'appels système.

upload_max_part_header_len

Syntaxe : upload_max_part_header_len size
Par 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
Par 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", dans le sens où, après avoir rencontré un fichier plus long que la limite spécifiée, nginx continuera à traiter le corps de la requête, essayant de recevoir les fichiers restants. Pour une limite "stricte", 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
Par défaut : 0
Contexte : main,server,location

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

upload_max_output_body_len

Syntaxe : upload_max_output_body_len size
Par 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-fichier en mémoire. Chaque fois que le corps de sortie dépasse la limite spécifiée, l'erreur 413 (Entité de requête trop grande) sera générée. La valeur de 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
Par défaut : off
Contexte : main,server,location

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

upload_pass_args

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

Active le transfert des arguments de requête à l'emplacement spécifié par upload_pass. Inefficace 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". En cas de upload_pass_args off, le backend obtient "/upload".

Exemple de configuration

server {
    client_max_body_size 100m;
    listen 80;

    # Le formulaire de téléchargement doit être soumis à cet emplacement
    location /upload/ {
        # Passer le corps de 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 les fichiers téléchargés à être lus 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 sur le hachage et 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;
    }

    # Passer le corps de 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>

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-upload.