Nginx upload module (v 2.0.3)

rus eng

A module for nginx web server for handling file uploads using multipart/form-data encoding (RFC 1867).


The module parses request body storing all files being uploaded to a directory specified by upload_store directive. The files are then being stripped from body and altered request is then passed to a location specified by upload_pass directive, thus allowing arbitrary handling of uploaded files. Each of file fields are being replaced by a set of fields specified by upload_set_form_field directive. The content of each uploaded file then could be read from a file specified by $upload_tmp_path variable or the file could be simply moved to ultimate destination. Temporary files created by module are being removed only in case of request body parse errors or disk write errors.

NOTE: The module uses blocking file writes, therefore server running it should utilize tens or hundreds of workers depending on the load to prevent network IO starvation.

Configuration directives

syntax: upload_pass <location>
default: none
severity: mandatory
context: server, location

Specifies location to pass request body to. File fields will be stripped and replaced by fields, containig necessary information to handle uploaded files.

syntax: upload_store <directory> [<level 1> [<level 2> ] ... ]
default: none
severity: mandatory
context: server, location

Specifies a directory to which output files will be saved to. The directory could be hashed. In this case all subdirectories should exist before starting nginx.

syntax: upload_store_access <mode>
default: user:rw
severity: optional
context: server, location

Specifies access mode which will be used to create output files.

syntax: upload_set_form_field <name> <value>
default: none
severity: optional
context: server, location

Specifies a form field(s) to generate for each uploaded file in request body passed to backend. Both name and value could contain following special variables:

These variables are valid only during processing of one part of original request body.

upload_set_form_field $ "$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";

syntax: upload_pass_form_field <regex>
default: none
severity: optional
context: location

Specifies a regex pattern for names of fields which will be passed to backend from original request body. This directive could be specified multiple times per location. Field will be passed to backend as soon as first pattern matches. For PCRE-unaware enviroments this directive specifies exact name of a field to pass to backend. If directive is omitted, no fields will be passed to backend from client.

upload_pass_form_field "^submit$|^description$";

For PCRE-unaware environments:

upload_pass_form_field "submit";
upload_pass_form_field "description";

syntax: upload_buffer_size <size>
default: size of memory page in bytes
severity: optional
context: server, location

Size in bytes of write buffer which will be used to accumulate file data and write it to disk. This directive is intended to be used to compromise memory usage vs. syscall rate.

syntax: upload_max_part_header_len <size>
default: 512
severity: optional
context: server, location

Specifies maximal length of part header in bytes. Determines the size of the buffer which will be used to accumulate part headers.

Example configuration

server {
    client_max_body_size 100m;
    listen       80;
    server_name  localhost;

    # 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_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_pass_form_field "^submit$|^description$";

    # Pass altered request body to a backend
    location /test {
        proxy_pass   http://localhost:8080;

Example form

<title>Test upload</title>
<h2>Select files to upload</h2>
<form name="upload" method="POST" enctype="multipart/form-data" action="/upload">
<input type="file" name="file1"><br>
<input type="file" name="file2"><br>
<input type="file" name="file3"><br>
<input type="file" name="file4"><br>
<input type="file" name="file5"><br>
<input type="file" name="file6"><br>
<input type="submit" name="submit" value="Upload">
<input type="hidden" name="test" value="value">


Latest version 2.0.3: tar.gz zip MD5 SHA1
Version 2.0.2: tar.gz zip MD5 SHA1
or go to download area

Browse repository

Browse documentation for earlier versions

Version 2.0.2

How to use

Download sources from one of the links above. Unpack the archive:

tar xvzf nginx_upload_module-2.0.3.tar.gz

Configure nginx with additional module:

cd <path to nginx sources>
./configure --add-module=<path to upload module sources>
make install


nginx -- is a web-server, developed by Igor Sysoev.


The above-described module is an addition to nginx web-server, nevertheless they are independent products. The licence of above-described module is BSD You should have received a copy of licence along with the source code.

Contact author

Valery Kholodkov
Please use address extension while composing an Email to me.

Copyright (C) 2006, 2008 Valery Kholodkov
Module copyright notices see in module sources.