NGINX: How to Increase the Upload File Size Limit

Introduction

NGINX is a popular open-source web server that is also used as a reverse proxy, HTTP cache, and load balancer. Some applications that run behind NGINX require the capability to upload large files. However, by default, NGINX has a limit set on the maximum file size that can be uploaded. This tutorial will guide you through the steps needed to increase this file size limit according to your needs.

Understanding the Directive

Before diving into the configuration, it’s crucial to understand the directive responsible for limiting file size in NGINX: client_max_body_size. This directive dictates the maximum size of the body of a HTTP request. The default value is relatively small, commonly 1MB, which is insufficient for uploading large files. By modifying this value, you can allow uploads that exceed the default limitation.

Simple Configuration Change

For a basic setup, where all you need is to change the file size limit, open your NGINX configuration file (usually located at /etc/nginx/nginx.conf) and find the http block.

http {
    ...
    client_max_body_size 100M;
    ...
}

This code snippet sets the maximum allowed file size for uploads to 100 megabytes. After adding or updating the directive, save the file and reload NGINX:

sudo nginx -s reload

Applying to Specific Server Block or Location

If you only want to increase the limit for a particular website or within a specific location on your website, you can set client_max_body_size within server block or location block in your NGINX configuration file. For server block, add the directive inside the corresponding server block:

server {
    listen 80;
    server_name example.com;
    ...
    client_max_body_size 100M;
    ...
}

For location block:

server {
    ...
    location /upload {
        client_max_body_size 200M;
    }
}

This sets the file size limit to 200MB for requests going to example.com/upload. Don’t forget to reload NGINX after making these changes.

Configuration for Large File Uploads with Buffering

When dealing with very large file uploads, it’s important to configure both NGINX and the underlying operating system to handle large file transfers efficiently. This could involve tweaking buffer sizes, timeouts, and the temporary storage location used by NGINX when buffering incoming data.

Here’s a comprehensive configuration example that increases timeouts and buffer sizes for large file uploads:

http {
    ...
    client_body_buffer_size 128k;
    client_max_body_size 0;
    client_body_timeout 300;
    client_header_timeout 300;
    send_timeout 300;
    ...
}

Setting client_max_body_size to 0 removes the file size limit which is useful for unrestricted uploads. This is not recommended for all servers due to security implications. Careful monitoring and controlling the upload endpoints can mitigate some risks.

Error Handling

In case of errors due to large file uploads, NGINX will return a response code 413 (Request Entity Too Large). Handling this response inside your application is important to provide feedback to users attempting to upload files that exceed your configured limits. Additionally, consider customizing the error page:

http {
    ...
    error_page 413 /custom_413.html;
    ...
}

Conclusion

Increasing the limit for file uploads in NGINX is a straightforward task that enables users to upload larger files to your application. Always reload the configuration after changes, and carefully plan file size limits considering security and resource usage.