Nginx

This guide provides recommended Nginx configurations for running the VoIPmonitor GUI, especially when Nginx is used as a reverse proxy. These settings are crucial for handling large data requests and preventing timeout errors on long-running operations.

Overview

When using Nginx as a reverse proxy in front of the VoIPmonitor GUI (which is often served by Apache + PHP-FPM), the default Nginx settings for buffers and timeouts may be too low for typical VoIPmonitor usage. This can lead to two common problems:

Errors when viewing large reports, downloading many PCAPs at once, or generating significant charts.
"504 Gateway Timeout" errors when performing actions that take a long time to process on the backend, such as complex database queries or bulk data operations.

The following directives help resolve these issues by increasing Nginx's capacity to handle large responses and by extending its patience for slow backend processes.

Recommended Nginx Configuration

These settings should be placed within the http, server, or location block of your Nginx configuration file (e.g., /etc/nginx/nginx.conf or /etc/nginx/sites-available/default). Applying them within the location block that proxies requests to the GUI is the most common approach.

1. Increasing Buffer Sizes

These directives increase the memory buffers Nginx uses to handle responses from the backend VoIPmonitor server. This is essential for preventing errors when the GUI generates a large amount of data.

Configuration Directives

proxy_buffer_size: Sets the size of the buffer used for reading the first part of the response from the proxied server (typically the headers).
proxy_buffers: Configures the number and size of buffers used for reading the rest of the response.
proxy_busy_buffers_size: Sets the maximum size of buffers that can be "busy" (being sent to the client) before Nginx starts buffering to disk. This should be at least as large as one of the proxy_buffers.

2. Extending Timeouts

These directives increase the time Nginx will wait for the backend to respond before giving up and returning a "504 Gateway Timeout" error. This is critical for long-running GUI operations.

Configuration Directives

proxy_connect_timeout: How long to wait for a connection to the backend server to be established.
proxy_send_timeout: How long to wait for the backend to accept data after a write operation.
proxy_read_timeout: How long to wait for the backend to send data after a read operation.
send_timeout: How long to wait for the client to accept data.

Example Configuration Block

Here is a complete example of a location block for your Nginx server configuration, incorporating all the recommended changes.

location /voipmonitor {
    # Your standard proxy_pass directive to the backend
    proxy_pass http://127.0.0.1:8080; # Adjust to your backend Apache/PHP-FPM address

    # --- Recommended Buffer Settings ---
    # Increase buffers to handle large reports and downloads
    proxy_buffer_size          128k;
    proxy_buffers              4 256k;
    proxy_busy_buffers_size    256k;
    proxy_temp_file_write_size 256k;

    # --- Recommended Timeout Settings ---
    # Extend timeouts to prevent 504 errors on long-running tasks
    proxy_connect_timeout      3600s; # 1 hour
    proxy_send_timeout         3600s;
    proxy_read_timeout         3600s;
    send_timeout               3600s;

    # Standard proxy headers
    proxy_set_header   Host             $host;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;

    # --- CRITICAL for SSO/SSL Termination ---
    # When using a reverse proxy (e.g., AWS ALB) that handles SSL termination
    # and connects to the backend over HTTP, this header tells the GUI that
    # the original client request was HTTPS. Without it, SSO redirects may fail
    # or cause redirect loops because the GUI generates http:// URLs instead of https://
    proxy_set_header   X-Forwarded-Proto $scheme;
}

After adding these settings, test your Nginx configuration and reload the service:

sudo nginx -t
sudo systemctl reload nginx

Troubleshooting

SSO Fails Behind Reverse Proxy

Problem

Google Sign-In or Microsoft Sign-In fails or causes redirect loops when the VoIPmonitor GUI is accessed through a reverse proxy that handles SSL termination.

Cause

The reverse proxy terminates HTTPS and forwards requests to the backend GUI over HTTP. Without the correct headers, the GUI believes it is running on an insecure protocol and generates HTTP URLs, breaking the OAuth callback flow.

Solution

Ensure the X-Forwarded-Proto header is set in your Nginx configuration:

proxy_set_header   X-Forwarded-Proto $scheme;

502 Bad Gateway Errors

Problem

Intermittent 502 errors when accessing the GUI.

Possible Causes

Backend (Apache/PHP-FPM) is not running or crashed
Upstream connection refused

Solution

Check backend service status:

systemctl status apache2
systemctl status php-fpm

External Resources

AI Summary for RAG

Summary: This guide provides recommended Nginx configuration settings for running the VoIPmonitor GUI, particularly when Nginx is used as a reverse proxy. It addresses two common problems: errors with large data requests and "504 Gateway Timeout" errors on long-running operations. To solve issues with large reports or bulk downloads, it recommends increasing buffer sizes with directives like proxy_buffer_size and proxy_buffers. To prevent 504 timeouts, it advises increasing timeout values with directives like proxy_connect_timeout and proxy_read_timeout, typically setting them to a high value like 3600 seconds (1 hour). The article provides a complete, annotated Nginx location block example that incorporates all the recommended settings, ready to be adapted by administrators. Critical for SSO: the X-Forwarded-Proto header must be set to prevent redirect loops when using SSL termination at the proxy level.

Keywords: nginx, reverse proxy, proxy, 504, gateway timeout, timeout, buffer, proxy_buffers, proxy_buffer_size, proxy_read_timeout, performance, gui, web interface, X-Forwarded-Proto, SSO, SSL termination, 502 bad gateway

Key Questions:

How do I fix a "504 Gateway Timeout" error in Nginx with VoIPmonitor?
What are the recommended Nginx settings for VoIPmonitor?
How can I increase the proxy buffer size in Nginx?
Why am I getting errors when downloading large reports or many PCAPs from the GUI?
How to configure Nginx as a reverse proxy for Apache/PHP-FPM?
What do proxy_buffers and proxy_read_timeout do?
Why does SSO fail behind a reverse proxy with SSL termination?
How do I fix redirect loops with Google Sign-In behind Nginx?