Buffer sizes optimization in Nginx - Commands & Configuration

Introduction

When a web server handles many requests, it uses memory buffers to temporarily store data. Optimizing these buffer sizes helps the server work faster and avoid errors like slow responses or dropped connections.

When your nginx server handles large client requests and you want to avoid 'upstream sent too big header' errors.

When you notice slow response times due to insufficient buffer sizes for headers or body data.

When running nginx as a reverse proxy and backend responses have large headers or cookies.

When tuning nginx for high traffic websites to improve memory usage and performance.

When you want to reduce the chance of 502 or 504 errors caused by buffer overflows.

Config File - nginx.conf

nginx.conf

worker_processes auto;
events {
    worker_connections 1024;
}
http {
    server {
        listen 80;
        server_name example.com;

        # Buffer size for reading client request headers
        client_header_buffer_size 1k;

        # Number and size of buffers for large headers
        large_client_header_buffers 4 8k;

        # Buffer size for reading client request body
        client_body_buffer_size 8k;

        location / {
            proxy_pass http://backend_server;
            # Buffer sizes for proxy responses
            proxy_buffer_size 4k;
            proxy_buffers 8 16k;
            proxy_busy_buffers_size 16k;
        }
    }
}

client_header_buffer_size: Sets buffer size for reading client request headers.

large_client_header_buffers: Defines number and size of buffers for large headers like cookies.

client_body_buffer_size: Buffer size for reading client request body data.

proxy_buffer_size: Buffer size for reading the first part of the response from the proxied server.

proxy_buffers: Number and size of buffers for the rest of the response.

proxy_busy_buffers_size: Maximum size of buffers that can be busy sending a response to the client.

Commands

Check the nginx configuration file syntax to ensure no errors before reloading.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new buffer size settings without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a simple HTTP HEAD request to verify the server responds correctly after changes.

Terminal

curl -I http://example.com

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: properly sized buffers prevent errors and improve nginx performance by handling headers and body data efficiently.

Common Mistakes

Setting buffer sizes too small

This causes nginx to return errors like 'upstream sent too big header' or slow down processing.

Increase buffer sizes gradually and test to find the right balance for your traffic.

Setting buffer sizes too large without need

This wastes server memory and can reduce overall performance under high load.

Only increase buffers as needed based on actual request and response sizes.

Changing config but forgetting to test syntax or reload nginx

Nginx will not apply changes or may fail to start, causing downtime.

Always run 'nginx -t' to check config and then reload nginx safely.

Summary

Edit nginx.conf to set buffer sizes like client_header_buffer_size and proxy_buffers.

Test the configuration syntax with 'nginx -t' before applying changes.

Reload nginx to apply new buffer settings without downtime.

Verify server response with a simple HTTP request to ensure stability.

Practice

1. What is the main purpose of adjusting proxy_buffer_size in nginx?

easy

A. To limit the total size of all proxy buffers combined

B. To set the maximum number of simultaneous connections nginx can handle

C. To control the size of the buffer used for reading the first part of the response from the proxied server

D. To configure the timeout for proxy connections

Solution

1. Step 1: Understand the role of proxy_buffer_size

   This directive sets the size of the buffer used to read the first part of the response from the proxied server, usually the response headers.

2. Step 2: Differentiate from other buffer settings

   Other directives like proxy_buffers control the number and size of buffers for the rest of the response, not just the first part.

3. Final Answer:

   To control the size of the buffer used for reading the first part of the response from the proxied server -> Option C

4. Quick Check:

   proxy_buffer_size controls first response buffer size [OK]

Hint: First buffer size is controlled by proxy_buffer_size [OK]

Common Mistakes:

• Confusing proxy_buffer_size with proxy_buffers
• Thinking it controls total buffer memory
• Mixing it with timeout settings

2. Which of the following is the correct syntax to set 4 buffers of 8k size each for proxying in nginx?

easy

A. proxy_buffers 4 8k;

B. proxy_buffers 8k 4;

C. proxy_buffers 4k 8;

D. proxy_buffers 8 4k;

Solution

1. Step 1: Recall nginx proxy_buffers syntax

   The correct syntax is proxy_buffers <number> <size>; where number is how many buffers and size is the size of each buffer.

2. Step 2: Match the correct order and units

   proxy_buffers 4 8k; correctly uses 4 buffers of 8k size each: proxy_buffers 4 8k;. Other options have reversed order or wrong units.

3. Final Answer:

   proxy_buffers 4 8k; -> Option A

4. Quick Check:

   proxy_buffers syntax = number size [OK]

Hint: Syntax is number first, then size with units [OK]

Common Mistakes:

• Swapping number and size order
• Using wrong units like 'k' instead of 'kB'
• Missing semicolon at end

3. Given this nginx config snippet:

proxy_buffer_size 4k;
proxy_buffers 2 8k;
proxy_busy_buffers_size 12k;

What will happen if the response size is 20k?

medium

A. nginx will buffer the entire response in memory without errors

B. nginx will buffer 12k and send the rest directly to the client

C. nginx will ignore proxy_busy_buffers_size and use default values

D. nginx will return an error because buffers are too small

Solution

1. Step 1: Calculate total buffer capacity

   proxy_buffers = 2 buffers * 8k = 16k plus proxy_buffer_size = 4k, total 20k buffer space. proxy_busy_buffers_size is 12k, which limits busy buffers.

2. Step 2: Understand buffering behavior for 20k response

   Since response is 20k, nginx uses buffers up to proxy_busy_buffers_size (12k) for busy buffers, then sends remaining data directly to client without buffering fully in memory.

3. Final Answer:

   nginx will buffer 12k and send the rest directly to the client -> Option B

4. Quick Check:

   proxy_busy_buffers_size limits busy buffer memory [OK]

Hint: proxy_busy_buffers_size limits busy buffer memory [OK]

Common Mistakes:

• Assuming all response fits in buffers
• Ignoring proxy_busy_buffers_size effect
• Thinking nginx errors on large responses

4. You set proxy_buffers 4 16k; but nginx logs show 'upstream sent too big header'. What is the likely cause?

medium

A. proxy_buffer_size is too small to hold the response header

B. proxy_busy_buffers_size is larger than proxy_buffers total size

C. proxy_buffers size is too large for the server memory

D. proxy_buffers number is set too high

Solution

1. Step 1: Understand error meaning

   'upstream sent too big header' means nginx cannot buffer the response header fully.

2. Step 2: Identify relevant buffer directive

   The response header is buffered by proxy_buffer_size, not proxy_buffers. If proxy_buffer_size is too small, this error occurs.

3. Final Answer:

   proxy_buffer_size is too small to hold the response header -> Option A

4. Quick Check:

   Response headers need proxy_buffer_size large enough [OK]

Hint: Check proxy_buffer_size for header errors [OK]

Common Mistakes:

• Changing proxy_buffers instead of proxy_buffer_size
• Ignoring header size requirements
• Assuming proxy_busy_buffers_size causes header errors

5. You want to optimize nginx proxy buffers for a backend that sends large JSON responses (~100k). Which configuration best balances memory use and performance?

hard

A. proxy_buffer_size 4k; proxy_buffers 2 8k; proxy_busy_buffers_size 12k;

B. proxy_buffer_size 8k; proxy_buffers 4 8k; proxy_busy_buffers_size 16k;

C. proxy_buffer_size 64k; proxy_buffers 16 64k; proxy_busy_buffers_size 128k;

D. proxy_buffer_size 16k; proxy_buffers 8 16k; proxy_busy_buffers_size 32k;

Solution

1. Step 1: Analyze response size and buffer needs

   Large JSON (~100k) requires enough buffer space to avoid slow disk writes but not excessive memory use.

2. Step 2: Evaluate options for balance

   proxy_buffer_size 16k; proxy_buffers 8 16k; proxy_busy_buffers_size 32k; uses moderate buffer sizes (16k) and enough buffers (8) with a reasonable busy buffer size (32k), balancing memory and performance well. proxy_buffer_size 64k; proxy_buffers 16 64k; proxy_busy_buffers_size 128k; is too large, A and D are too small for 100k responses.

3. Final Answer:

   proxy_buffer_size 16k; proxy_buffers 8 16k; proxy_busy_buffers_size 32k; -> Option D

4. Quick Check:

   Moderate buffers and sizes fit large responses efficiently [OK]

Hint: Match buffer sizes to typical response size for best results [OK]

Common Mistakes:

• Using too small buffers causing slow proxying
• Allocating too much memory wasting resources
• Ignoring proxy_busy_buffers_size limits