Nginx upload module (v 2.1.1) |
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. Removal of output files is controlled by directive upload_cleanup.
Specifies location to pass request body to. File fields will be stripped and replaced by fields, containig necessary information to handle uploaded files.
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.
Specifies access mode which will be used to create output files.
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:
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_set_form_field ${upload_field_name}${upload_archive_elm}.name "$upload_file_name";
upload_set_form_field ${upload_field_name}${upload_archive_elm}.content_type "$upload_content_type";
upload_set_form_field ${upload_field_name}${upload_archive_elm}.path "$upload_tmp_path";
upload_set_form_field ${upload_field_name}${upload_archive_elm}.archive_path "$upload_archive_path";
Specifies a form field(s) containing aggregate attributes to generate for each uploaded file in request body passed to backend. Both name and value could contain standard nginx variables, variables from upload_set_form_field directive and following additional special variables:
WARNING: variables $upload_file_md5, $upload_file_md5_uc, $upload_file_sha1 and $upload_file_sha1_uc utilize additional resourses to calculate MD5 and SHA1 checksums.
example:upload_aggregate_form_field $upload_field_name.md5 "$upload_file_md5"; upload_aggregate_form_field $upload_field_name.size "$upload_file_size";
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.
example:upload_pass_form_field "^submit$|^description$";
For PCRE-unaware environments:
upload_pass_form_field "submit"; upload_pass_form_field "description";
Specifies HTTP statuses after generation of which all files successfuly uploaded in current request will be removed. Used for cleanup after backend or server failure. Backend may also explicitly signal errornous status if it doesn't need uploaded files for some reason. HTTP status must be a numerical value in range 400-599, no leading zeroes are allowed. Ranges of statuses could be specified with a dash.
example:upload_cleanup 400 404 499 500-505;
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.
Specifies maximal length of part header in bytes. Determines the size of the buffer which will be used to accumulate part headers.
Specifies maximal size of the file. Files longer than the value of this directive will be omitted. This directive specifies "soft" limit, in the sense, that after encountering file longer than specified limit, nginx will continue to process request body, trying to receive remaining files. For "hard" limit client_max_body_size directive must be used. The value of zero for this directive specifies that no restrictions on file size should be applied.
Specifies maximal length of the output body. This prevents piling up of non-file form fields in memory. Whenever output body overcomes specified limit error 413 (Request entity too large) will be generated. The value of zero for this directive specifies that no restrictions on output body length should be applied.
Enables forwarding of query arguments to backend. Example:
<form action="/upload?id=5">
...
location /upload {
upload_pass /internal_upload;
upload_pass_args on;
}
...
location /internal_upload {
...
proxy_pass http://backend;
}
In this example backend gets request URI "/upload?id=5". In case of upload_pass_args off backend gets "/upload".
Specifies list of mime types, which, whenever received from client, will be considered as undefined, and for which mime type will be determined by file extension, via looking up in table, specified by types {} directive. Multiple instances of this directive are allowed.
example:upload_void_content_type application/octet-stream; upload_void_content_type application/oct-stream;
Specifies a string which will be used as a separator for archive element names. Used to provide unique field names.
Specifies a string which will be used as a separator for archive path elements.
Describes a filter for files with specified mime types. Filters are activated via directives of according modules. Build in filters are activated via directives upload_unzip and upload_discard (see below). Example:
location /upload {
upload_pass /a;
upload_store /tmp/path_a;
# extract files from zip archives and store to specified directory
upload_filter application/zip {
upload_unzip;
upload_store /tmp/path_to_archives;
}
# discard all jpeg and png images
upload_filter image/jpeg image/png {
upload_discard;
}
}
Specifying upload_store directive allows to save files with certain content-type to different location.
Activates a filter for discarding the content of the file being uploaded.
Activates filter for unpacking from uploaded file in PKZIP format. Filter processes the archive while receiving data from client, stores files and generates accroding form fields, as if files in archive were a part of original request. The variable ${upload_archive_elm} must be used to generate unique names for form fields, contaning strings like _1, _2, _3 and so on, or empty string if a file is not an archive element. The variable ${upload_archive_path} specifies path to file within the archive or empty string if file is not a part of archive. mime-type of files extracted from archive is determined via looking up in table specified by types {} directive.
Specifies number and size of buffers used to decompress uploaded file.
Specifies maximal length of a filename within ZIP-archive.
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 {
internal;
proxy_pass http://localhost:8080;
}
}
<html>
<head>
<title>Test upload</title>
</head>
<body>
<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">
</form>
</body>
</html>
Latest version 2.1.1: tar.gz zip MD5 SHA1
Version 2.0.6: tar.gz zip MD5 SHA1
Version 2.0.5: tar.gz zip MD5 SHA1
Version 2.0.4: tar.gz zip MD5 SHA1
Version 2.0.3: tar.gz zip MD5 SHA1
Version 2.0.2: tar.gz zip MD5 SHA1
or go to download area
Version 2.0.6
Version 2.0.5
Version 2.0.4
Version 2.0.3
Version 2.0.2
Download sources from one of the links above. Unpack the archive:
tar xvzf nginx_upload_module-2.1.1.tar.gz
Configure nginx with additional module:
cd <path to nginx sources> ./configure --add-module=<path to upload module sources> make 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.
Valery Kholodkov valery+nginx@grid.net.ru
Please use address extension while composing an Email to me. Should you find a spelling mistake on this page, don't hesitate to contact me.
If you like this module, you can donate to it's development and support, as well as to my work in nginx addons in general.
Thank you!Copyright (C) 2006, 2008 Valery Kholodkov
Module copyright notices see in module sources.