Nginx

From VoIPmonitor.org
Revision as of 20:49, 7 January 2026 by Admin (talk | contribs) (Add Apache/mod_fcgid timeout configuration section for users not using Nginx reverse proxy)


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

Apache/mod_fcgid Timeout Errors (Without Nginx)

If you are not using Nginx as a reverse proxy and are experiencing timeout errors with Apache directly, the solution involves adjusting Apache's mod_fcgid (FastCGI) timeout settings instead.

Problem

The GUI intermittently shows "server side error - check your http server error log. - connection to the web server was lost / interrupted," especially when loading dashboards with large data sets or generating complex reports.

Cause

The Apache mod_fcgid module has default timeout limits that are too short for VoIPmonitor's long-running database queries related to dashboard chart generation and report processing.

Solution

Increase the mod_fcgid timeout values in your Apache configuration file (httpd.conf, apache2.conf, or a virtual host configuration block): 

<IfModule mod_fcgid.c>
    # Time to wait for a connection to the FastCGI process
    FcgidConnectTimeout 900

    # Time to wait for FastCGI responses (15 minutes)
    FcgidIOTimeout 900

    # Maximum lifetime of any FastCGI process (15 minutes)
    FcgidProcessLifeTime 900

    # Maximum idle time for a FastCGI process before it's terminated
    FcgidIdleTimeout 900

    # Maximum time waiting for output from FastCGI application
    FcgidOutputBufferSize 65536
</IfModule>

After making these changes, restart Apache: 

# CentOS/RHEL/AlmaLinux
sudo systemctl restart httpd

# Debian/Ubuntu
sudo systemctl restart apache2

For more comprehensive Apache troubleshooting, see GUI_troubleshooting.

External Resources

See Also

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. For users not using Nginx, the guide also includes Apache/mod_fcgid timeout configuration (FcgidIOTimeout, FcgidIdleTimeout, FcgidConnectTimeout, FcgidProcessLifeTime) for fixing "server side error - connection to the web server was lost" errors when experiencing timeouts with Apache directly.

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, apache, httpd, mod_fcgid, fcgid, FcgidIOTimeout, FcgidIdleTimeout, FcgidConnectTimeout, FcgidProcessLifeTime, server side error, connection lost interrupted, web server error log, dashboard timeout, chart timeout

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?
  • How do I fix Apache timeout errors when VoIPmonitor GUI charts fail to load?
  • What mod_fcgid settings should I adjust for dashboard timeout errors?
  • How to increase httpd timeout for VoIPmonitor GUI?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Nginx&oldid=9907"