upload: Módulo de NGINX para gestionar la carga de archivos

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, entre otras:

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

Habilita el módulo añadiendo lo siguiente al principio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_upload_module.so;

Este documento describe nginx-module-upload v2.4.0 publicado el 03 de febrero de 2026.

---

Un módulo para nginx para gestionar la carga de archivos usando 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
• Configuración de ejemplo
• 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 se eliminan posteriormente del cuerpo y la solicitud modificada se pasa a una ubicación especificada por la directiva upload_pass, lo que permite el manejo arbitrario de los archivos cargados. Cada uno de los campos de archivo se reemplaza por un conjunto de campos especificados por la directiva upload_set_form_field. El contenido de cada archivo cargado puede leerse entonces desde un archivo especificado por la variable $upload_tmp_path o el archivo puede simplemente moverse a su destino final. La eliminación de los archivos de salida se controla mediante la directiva upload_cleanup. Si una solicitud tiene un método distinto de POST, el módulo devuelve el error 405 (Method not allowed). Las solicitudes con dichos métodos pueden procesarse en una ubicación alternativa mediante la directiva error_page.

Directivas

upload_pass

Sintaxis: upload_pass location
Predeterminado: —
Contexto: server,location

Especifica la ubicación a la que se pasa el cuerpo de la solicitud. Los campos de archivo se eliminan y se reemplazan por campos que contienen la información necesaria para gestionar los archivos cargados.

upload_resumable

Sintaxis: upload_resumable on | off
Predeterminado: upload_resumable off
Contexto: main,server,location

Habilita las cargas reanudables.

upload_store

Sintaxis: upload_store directory [level1 [level2]] ...
Predeterminado: —
Contexto: server,location

Especifica un directorio en el que se guardarán los archivos de salida. El directorio puede estar hasheado. En este caso, todos los subdirectorios deben existir antes de iniciar nginx.

upload_state_store

Sintaxis: upload_state_store directory [level1 [level2]] ...
Predeterminado: —
Contexto: server,location

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

upload_store_access

Sintaxis: upload_store_access mode
Predeterminado: upload_store_access user:rw
Contexto: server,location

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

upload_set_form_field

Sintaxis: upload_set_form_field name value
Predeterminado: —
Contexto: server,location

Especifica uno o varios campos de formulario que se generarán para cada archivo cargado en el cuerpo de la solicitud que se pasa al backend. Tanto name como value 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 consta de 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 name value
Predeterminado: —
Contexto: server,location

Especifica uno o varios campos de formulario que contienen atributos agregados que se generarán para cada archivo cargado en el cuerpo de la solicitud que se pasa al backend. Tanto name como value pueden contener variables estándar de nginx, variables de la directiva upload_set_form_field y las siguientes variables especiales adicionales:

• $upload_file_md5: suma de comprobación MD5 del archivo
• $upload_file_md5_uc: suma de comprobación MD5 del archivo en mayúsculas
• $upload_file_sha1: suma de comprobación SHA1 del archivo
• $upload_file_sha1_uc: suma de comprobación SHA1 del archivo en mayúsculas
• $upload_file_sha256: suma de comprobación SHA256 del archivo
• $upload_file_sha256_uc: suma de comprobación SHA256 del archivo en mayúsculas
• $upload_file_sha512: suma de comprobación SHA512 del archivo
• $upload_file_sha512_uc: suma de comprobación SHA512 del archivo en mayúsculas
• $upload_file_crc32: valor hexadecimal del 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 que 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 comprobació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
Predeterminado: —
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 especificarse varias veces por ubicación. El campo se pasará al backend en cuanto coincida el primer patrón. Para entornos sin soporte de PCRE, esta directiva especifica el nombre exacto de un campo que se pasará al backend. Si se omite la directiva, no se pasará ningún campo al backend desde el cliente.

Ejemplo de uso:

upload_pass_form_field "^submit$|^description$";

Para entornos sin soporte de PCRE:

upload_pass_form_field "submit";
upload_pass_form_field "description";

upload_cleanup

Sintaxis: upload_cleanup status/range ...
Predeterminado: —
Contexto: server,location

Especifica los estados HTTP tras cuya generación se eliminarán todos los archivos cargados correctamente en la solicitud actual. Se utiliza para la limpieza después de un fallo del backend o del servidor. El backend también puede señalar explícitamente un estado erróneo si no necesita los archivos cargados por algún motivo. El estado HTTP debe ser un valor numérico en el rango 400-599, no se permiten ceros iniciales. Los rangos de estados pueden especificarse con un guion.

Ejemplo de uso:

upload_cleanup 400 404 499 500-505;

upload_buffer_size

Sintaxis: upload_buffer_size size
Predeterminado: tamaño de la página de memoria en bytes
Contexto: server,location

Tamaño en bytes del búfer de escritura que se utilizará para acumular los datos del archivo y escribirlos en disco. Esta directiva está pensada para usarse 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 size
Predeterminado: 512
Contexto: server,location

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

upload_max_file_size

Sintaxis: upload_max_file_size size
Predeterminado: 0
Contexto: main,server,location

Especifica el tamaño máximo del archivo. Los archivos más largos que el valor de esta directiva se omitirán. Esta directiva especifica un límite "soft", en el sentido de que tras encontrar un archivo más largo que el límite especificado, nginx continuará procesando el cuerpo de la solicitud, intentando recibir los archivos restantes. Para un límite "hard" debe usarse la directiva client_max_body_size. El valor cero para esta directiva especifica que no debe aplicarse ninguna restricción al tamaño del archivo.

upload_limit_rate

Sintaxis: upload_limit_rate rate
Predeterminado: 0
Contexto: main,server,location

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

upload_max_output_body_len

Sintaxis: upload_max_output_body_len size
Predeterminado: 100k
Contexto: main,server,location

Especifica la longitud máxima del cuerpo de salida. Esto evita la acumulación de campos de formulario que no son archivos en memoria. Siempre que el cuerpo de salida supere el límite especificado, se generará el error 413 (Request entity too large). El valor cero para esta directiva especifica que no debe aplicarse ninguna restricción a la longitud del cuerpo de salida.

upload_tame_arrays

Sintaxis: upload_tame_arrays on | off
Predeterminado: off
Contexto: main,server,location

Especifica si los corchetes en los nombres de los campos de archivo deben eliminarse (necesario para los arrays de PHP).

upload_pass_args

Sintaxis: upload_pass_args on | off
Predeterminado: off
Contexto: main,server,location

Habilita el reenvío de los argumentos de consulta a la ubicación especificada por upload_pass. No tiene efecto con ubicaciones con nombre. 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 el URI de solicitud "/upload?id=5". En caso de upload_pass_args off, el backend recibe "/upload".

Configuración de ejemplo

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>