upload: Módulo de NGINX para manejar cargas de archivos

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 y 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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_upload_module.so;

Este documento describe nginx-module-upload v2.3.0 lanzado el 02 de agosto de 2018.

---

Un módulo para nginx para manejar cargas de archivos utilizando codificación multipart/form-data (RFC 1867) y cargas reanudables de acuerdo con este protocolo.

• Descripción
• Directivas
  • 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
• Ejemplo de configuración
• Licencia

Descripción

El módulo analiza el cuerpo de la solicitud almacenando todos los archivos que se están cargando en un directorio especificado por la directiva upload_store. Los archivos son luego eliminados del cuerpo y la solicitud alterada se pasa a una ubicación especificada por la directiva upload_pass, permitiendo así el manejo arbitrario de los archivos cargados. Cada uno de los campos de archivo es reemplazado por un conjunto de campos especificados por la directiva upload_set_form_field. El contenido de cada archivo cargado puede ser leído desde un archivo especificado por la variable $upload_tmp_path o el archivo puede ser simplemente movido a su destino final. La eliminación de los archivos de salida es controlada por la directiva upload_cleanup. Si una solicitud tiene un método diferente a POST, el módulo devuelve el error 405 (Método no permitido). Las solicitudes con tales métodos pueden ser procesadas en una ubicación alternativa a través de la directiva error_page.

Directivas

upload_pass

Sintaxis: upload_pass location
Por defecto: —
Contexto: server,location

Especifica la ubicación a la que se pasará el cuerpo de la solicitud. Los campos de archivo serán eliminados y reemplazados por campos que contienen la información necesaria para manejar los archivos cargados.

upload_resumable

Sintaxis: upload_resumable on | off
Por defecto: upload_resumable off
Contexto: main,server,location

Habilita cargas reanudables.

upload_store

Sintaxis: upload_store directorio [nivel1 [nivel2]] ...
Por defecto: —
Contexto: server,location

Especifica un directorio al que se guardarán los archivos de salida. El directorio puede ser hashado. En este caso, todos los subdirectorios deben existir antes de iniciar nginx.

upload_state_store

Sintaxis: upload_state_store directorio [nivel1 [nivel2]] ...
Por defecto: —
Contexto: server,location

Especifica un directorio que contendrá archivos de estado para cargas reanudables. El directorio puede ser hashado. En este caso, todos los subdirectorios deben existir antes de iniciar nginx.

upload_store_access

Sintaxis: upload_store_access modo
Por defecto: upload_store_access user:rw
Contexto: server,location

Especifica el modo de acceso que se utilizará para crear archivos de salida.

upload_set_form_field

Sintaxis: upload_set_form_field nombre valor
Por defecto: —
Contexto: server,location

Especifica un campo(s) de formulario a generar para cada archivo cargado en el cuerpo de la solicitud que se pasa al backend. Tanto nombre como valor pueden contener las siguientes variables especiales:

• $upload_field_name: el nombre del campo de archivo original
• $upload_content_type: el tipo de contenido del archivo cargado
• $upload_file_name: el nombre original del archivo que se está cargando con los elementos de ruta iniciales en notación DOS y UNIX eliminados. Es decir, "D:\Documents And Settings\My Dcouments\My Pictures\Picture.jpg" se convertirá en "Picture.jpg" y "/etc/passwd" se convertirá en "passwd".
• $upload_tmp_path: la ruta donde se almacena el contenido del archivo original. El nombre del archivo de salida consiste en 10 dígitos y se genera con el mismo algoritmo que en la directiva proxy_temp_path.

Estas variables son válidas solo durante el procesamiento de una parte del cuerpo de la solicitud original.

Ejemplo de uso:

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

Sintaxis: upload_aggregate_form_field nombre valor
Por defecto: —
Contexto: server,location

Especifica un campo(s) de formulario que contenga atributos agregados a generar para cada archivo cargado en el cuerpo de la solicitud que se pasa al backend. Tanto nombre como valor pueden contener variables estándar de nginx, variables de upload_set_form_field y las siguientes variables especiales adicionales:

• $upload_file_md5: suma de verificación MD5 del archivo
• $upload_file_md5_uc: suma de verificación MD5 del archivo en letras mayúsculas
• $upload_file_sha1: suma de verificación SHA1 del archivo
• $upload_file_sha1_uc: suma de verificación SHA1 del archivo en letras mayúsculas
• $upload_file_crc32: valor hexadecimal de CRC32 del archivo
• $upload_file_size: tamaño del archivo en bytes
• $upload_file_number: número ordinal del archivo en el cuerpo de la solicitud

El valor de un campo especificado por esta directiva se evalúa después de la carga exitosa del archivo, por lo tanto, estas variables son válidas solo al final del procesamiento de una parte del cuerpo de la solicitud original.

Advertencia:: las variables $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1, y $upload_file_sha1_uc utilizan recursos adicionales para calcular las sumas de verificación MD5 y SHA1.

Ejemplo de uso:

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

Sintaxis: upload_pass_form_field regex
Por defecto: —
Contexto: server,location

Especifica un patrón regex para los nombres de los campos que se pasarán al backend desde el cuerpo de la solicitud original. Esta directiva puede ser especificada varias veces por ubicación. El campo se pasará al backend tan pronto como el primer patrón coincida. Para entornos que no conocen PCRE, esta directiva especifica el nombre exacto de un campo para pasar al backend. Si se omite la directiva, no se pasarán campos al backend desde el cliente.

Ejemplo de uso:

upload_pass_form_field "^submit$|^description$";

Para entornos que no conocen PCRE:

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Sintaxis: upload_cleanup status/rango ...
Por defecto: —
Contexto: server,location

Especifica los estados HTTP después de los cuales todos los archivos cargados exitosamente en la solicitud actual serán eliminados. Se utiliza para limpieza después de fallos en el backend o servidor. El backend también puede señalar explícitamente un estado erróneo si no necesita los archivos cargados por alguna razón. El estado HTTP debe ser un valor numérico en el rango de 400-599, no se permiten ceros a la izquierda. Los rangos de estados pueden ser especificados con un guion.

Ejemplo de uso:

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Sintaxis: upload_buffer_size tamaño
Por defecto: tamaño de página de memoria en bytes
Contexto: server,location

Tamaño en bytes del búfer de escritura que se utilizará para acumular datos de archivos y escribirlos en disco. Esta directiva está destinada a ser utilizada para compensar el uso de memoria frente a la tasa de llamadas al sistema.

upload_max_part_header_len

Sintaxis: upload_max_part_header_len tamaño
Por defecto: 512
Contexto: server,location

Especifica la longitud máxima del encabezado de parte en bytes. Determina el tamaño del búfer que se utilizará para acumular encabezados de parte.

upload_max_file_size

Sintaxis: upload_max_file_size tamaño
Por defecto: 0
Contexto: main,server,location

Especifica el tamaño máximo del archivo. Los archivos más largos que el valor de esta directiva serán omitidos. Esta directiva especifica un límite "blando", en el sentido de que después de encontrar un archivo más largo que el límite especificado, nginx continuará procesando el cuerpo de la solicitud, tratando de recibir los archivos restantes. Para un límite "duro", se debe utilizar la directiva client_max_body_size. El valor cero para esta directiva especifica que no se deben aplicar restricciones al tamaño del archivo.

upload_limit_rate

Sintaxis: upload_limit_rate tasa
Por defecto: 0
Contexto: main,server,location

Especifica el límite de tasa de carga en bytes por segundo. Cero significa que la tasa es ilimitada.

upload_max_output_body_len

Sintaxis: upload_max_output_body_len tamaño
Por defecto: 100k
Contexto: main,server,location

Especifica la longitud máxima del cuerpo de salida. Esto previene la acumulación de campos de formulario no relacionados con archivos en memoria. Siempre que el cuerpo de salida supere el límite especificado, se generará el error 413 (Entidad de solicitud demasiado grande). El valor cero para esta directiva especifica que no se deben aplicar restricciones a la longitud del cuerpo de salida.

upload_tame_arrays

Sintaxis: upload_tame_arrays on | off
Por defecto: off
Contexto: main,server,location

Especifica si los corchetes cuadrados en los nombres de los campos de archivo deben ser eliminados (requerido para arreglos de PHP).

upload_pass_args

Sintaxis: upload_pass_args on | off
Por defecto: off
Contexto: main,server,location

Habilita el reenvío de argumentos de consulta a la ubicación especificada por upload_pass. Ineficaz con ubicaciones nombradas. Ejemplo:

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

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

## ...

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

En este ejemplo, el backend recibe la URI de solicitud "/upload?id=5". En caso de upload_pass_args off, el backend recibe "/upload".

Ejemplo de configuración

server {
    client_max_body_size 100m;
    listen 80;

    # El formulario de carga debe ser enviado a esta ubicación
    location /upload/ {
        # Pasar el cuerpo de solicitud alterado a esta ubicación
        upload_pass @test;

        # Almacenar archivos en este directorio
        # El directorio es hashado, los subdirectorios 0 1 2 3 4 5 6 7 8 9 deben existir
        upload_store /tmp 1;

        # Permitir que los archivos cargados sean leídos solo por el usuario
        upload_store_access user:r;

        # Establecer campos especificados en el cuerpo de la solicitud
        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";

        # Informar al backend sobre el hash y el tamaño de un archivo
        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;
    }

    # Pasar el cuerpo de solicitud alterado a 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

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-upload.