Reference

Parts of this document were written by the author of the original Nginx Upload Progress module, Brice Figureau.

This is a reference of all configuration options that this module adds to Nginx. You should be familiar with Nginx configuration to read it and not feel confused.

upload_progress

syntax: upload_progress zone_name zone_size
default: n/a
context: server

This directive enables the upload progress module and reserve zone_size bytes to the zone_name which will be used to store the per-connection tracking information.

track_uploads

syntax: track_uploads zone_name timeout
default: n/a
context: location

This directive enables tracking uploads for the current location. Each POST landing in this location will register the request in the zone_name upload progress tracker.
Since Nginx doesn’t support yet RFC 1867 upload, the location must be a proxy_pass or fastcgi location.
The POST _must_ have a query parameter called X-Progress-ID (or an HTTP header of the same name) whose value is the unique identifier used to get progress information. If the POST has no such information, the upload will not be tracked.
The timeout parameter controls the time upload information are kept after the upload request has finished. This allows the upload progress probe to be able to get the “upload done” information or when an error as occurred. Usual value is 30 seconds.
Warning: since version 0.4, the track_uploads must be the last directive of the location (i.e. it should be placed after any proxy_pass or fasctgi_pass).

report_uploads

syntax: report_uploads zone_name
default: n/a
context: location

This directive allows a location to report the upload progress that is tracked by track_uploads for zone_name. The returned document is a JSON text with the possible 4 results:

- the upload request hasn’t been registered yet or is unknown:

{ ’state’ : ’starting’ }

- the upload request has ended:

{ ’state’ : ‘done’ }

- the upload request generated an HTTP error:

{ ’state’ : ‘error’, ’status’ : <error code> }

One error code that is interesting to track for clients is HTTP error 413 (Request entity too large)

- the upload request is in progress:

{ ’state’ : ‘uploading’, ‘received’ : <size_received>, ’size’ : <total_size>}

The HTTP request to this location must have either an X-Progress-ID parameter or X-Progress-ID HTTP header containing the unique identifier as specified in your upload/POST request to the relevant tracked zone. If you are using the X-Progress-ID as a query-string parameter, ensure it is the LAST argument in the URL.

sell_tickets

syntax: sell_uploads zone_name
default: n/a
context: location

Placing this directive will make the server to serve JSON responses with the ticket and the server_id to all clients connecting to the location. Name of the zone specified in the upload_progress directive has to be passed as the argument.

ticket_format

syntax: ticket_format format
default: n/a
context: location

Format of the ticket served within the location. It is a text string, which may contain special symbols called here ‘non-terminals’ that are later replaced with specific values. A non-terminal starts with a ‘%’ character and ends with a ‘.’ character. Non-terminals that can be used at the moment are:

* %timestamp. – UNIX timestamp
* %random. – random sequence of bytes with a configurable length
* %user_agent. – user-agent header from the request
* %server_id. – id of the server

The list of non-terminals probably will be extended in future versions.

ticket_base64_encode

syntax: ticket_base64_encode on|off
default: off
context: location

Most probably, the ticket will contain some non-printable characters. Thus it might be a good idea to encode the tickets with base64. That’s what this directive is for.

ticket_timeout

syntax: ticket_timeout time
default: None, something must be specified (we’ll think about some default value in future versions)
context: location

The tickets will be marked as invalid after this period of time (and later they will be removed from the memory).

ticket_server_id

syntax: ticket_server_id server_id
default: None, you must specify something.
context: location

This value will be added to the JSON object that will contain the ticket. It’s useful if you’re using the module for distributed sites (probably you’ll put the server’s external address here).

ticket_random_len

syntax: ticket_random_len length
default: 10
context: location

Length (in bytes) of the randomly generated piece of data.

ticket_md5

syntax: ticket_md5 salt
default: none
context: location

If used, md5 sum of the ticket will be added at it’s end. If you specify the salt parameter, you’ll have a simple ticket signatures solution.