Nginx: Difference between revisions

From VoIPmonitor.org
(Add X-Forwarded-Proto header for SSO/SSL termination reverse proxy support)
(Create page: Nginx reverse proxy configuration for VoIPmonitor GUI)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Nginx Configuration for VoIPmonitor GUI}}
{{DISPLAYTITLE:Nginx Reverse Proxy Configuration}}
[[Category:Configuration]]
[[Category:Web GUI]]


'''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.'''
= Nginx Reverse Proxy Configuration =


== Overview ==
This guide covers Nginx configuration as a reverse proxy for the VoIPmonitor GUI, addressing common issues with large data transfers and long-running operations.
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.
== Common Problems ==


== Recommended Nginx Configuration ==
{| class="wikitable"
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.
! Problem !! Symptom !! Solution
|-
| Large data requests || Errors downloading reports/PCAPs || Increase buffer sizes
|-
| Long operations || 504 Gateway Timeout || Increase timeout values
|-
| SSO redirect loops || Google/Microsoft Sign-In fails || Add <code>X-Forwarded-Proto</code> header
|-
| Backend down || 502 Bad Gateway || Check Apache/PHP-FPM status
|}


=== 1. Increasing Buffer Sizes ===
== Recommended Configuration ==
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
Add this configuration to your Nginx <code>location</code> block:
*<code>proxy_buffer_size</code>: Sets the size of the buffer used for reading the first part of the response from the proxied server (typically the headers).
*<code>proxy_buffers</code>: Configures the number and size of buffers used for reading the rest of the response.
*<code>proxy_busy_buffers_size</code>: 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 ===
<syntaxhighlight lang="nginx">
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.
location / {
    proxy_pass http://127.0.0.1:80;


;Configuration Directives
    # Buffer settings for large reports/PCAP downloads
*<code>proxy_connect_timeout</code>: How long to wait for a connection to the backend server to be established.
    proxy_buffer_size 128k;
*<code>proxy_send_timeout</code>: How long to wait for the backend to accept data after a write operation.
    proxy_buffers 4 256k;
*<code>proxy_read_timeout</code>: How long to wait for the backend to send data after a read operation.
    proxy_busy_buffers_size 256k;
*<code>send_timeout</code>: How long to wait for the client to accept data.


=== Example Configuration Block ===
    # Timeout settings (1 hour for long-running operations)
Here is a complete example of a `location` block for your Nginx server configuration, incorporating all the recommended changes.
    proxy_connect_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_read_timeout 3600s;
    send_timeout 3600s;


<pre>
    # Required headers
location /voipmonitor {
    proxy_set_header Host $host;
     # Your standard proxy_pass directive to the backend
     proxy_set_header X-Real-IP $remote_addr;
     proxy_pass http://127.0.0.1:8080; # Adjust to your backend Apache/PHP-FPM address
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


     # --- Recommended Buffer Settings ---
     # CRITICAL for SSO (Google/Microsoft Sign-In)
    # Increase buffers to handle large reports and downloads
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffer_size          128k;
}
    proxy_buffers              4 256k;
</syntaxhighlight>
    proxy_busy_buffers_size    256k;
    proxy_temp_file_write_size 256k;


    # --- Recommended Timeout Settings ---
{{Warning|1=The <code>X-Forwarded-Proto</code> header is '''required''' for SSO (Google/Microsoft Sign-In) when SSL is terminated at Nginx. Without it, you will experience redirect loops.}}
    # 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
=== Apply Changes ===
    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 ---
<syntaxhighlight lang="bash">
    # When using a reverse proxy (e.g., AWS ALB) that handles SSL termination
# Test configuration syntax
    # and connects to the backend over HTTP, this header tells the GUI that
sudo nginx -t
    # 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;
}
</pre>


After adding these settings, be sure to test your Nginx configuration and reload the service:
# Reload configuration
<pre>
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl reload nginx
</pre>
</syntaxhighlight>
 
== Troubleshooting ==
 
=== 504 Gateway Timeout ===
 
Increase all timeout values in the Nginx configuration. The default timeouts are too short for:
* Large CDR exports
* Bulk PCAP downloads
* Complex report generation
 
=== 502 Bad Gateway ===
 
The backend service is not responding. Check:
 
<syntaxhighlight lang="bash">
# Check Apache status
systemctl status apache2


For more in-depth information on this topic, these external resources can be useful:
# Or check PHP-FPM status
* [http://www.nginxtips.com/504-gateway-time-out-using-nginx/ NginxTips: 504 Gateway Time-out using Nginx]
systemctl status php-fpm
* [http://stackoverflow.com/questions/561946/how-do-i-prevent-a-gateway-timeout-with-fastcgi-on-nginx Stack Overflow: How do I prevent a gateway timeout with FastCGI?]
</syntaxhighlight>
 
=== SSO Redirect Loops ===
 
If Google or Microsoft Sign-In fails with redirect loops:
 
1. Verify <code>X-Forwarded-Proto</code> header is set
2. Check that the header value matches the actual protocol (<code>https</code>)
3. Ensure the GUI's configured URL matches the public URL
 
== Apache Alternative (Without Nginx) ==
 
If using Apache with mod_fcgid directly (not behind Nginx), increase these timeouts in Apache configuration:
 
<syntaxhighlight lang="apache">
FcgidIOTimeout 900
FcgidIdleTimeout 900
FcgidConnectTimeout 900
FcgidProcessLifeTime 900
</syntaxhighlight>
 
<syntaxhighlight lang="bash">
# Apply changes
systemctl restart apache2  # Debian/Ubuntu
systemctl restart httpd    # RHEL/CentOS
</syntaxhighlight>
 
{{Tip|These settings fix "server side error - connection to the web server was lost" when loading dashboards or charts.}}
 
== See Also ==
 
* [[GUI_installation|GUI Installation]]
* [[Google_Sign_in_usage|Google Sign-In Configuration]]
* [[Microsoft_Sign_in_usage|Microsoft Sign-In Configuration]]
* [[GUI_troubleshooting|GUI Troubleshooting]]


== AI Summary for RAG ==
== 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.
 
'''Keywords:''' nginx, reverse proxy, proxy, 504, gateway timeout, timeout, buffer, proxy_buffers, proxy_buffer_size, proxy_read_timeout, performance, gui, web interface
'''Summary:''' Nginx reverse proxy configuration guide for VoIPmonitor GUI. Covers buffer settings (<code>proxy_buffer_size</code>, <code>proxy_buffers</code>) for large data downloads and timeout settings (<code>proxy_read_timeout</code>, etc.) set to 3600s to prevent 504 errors on long operations. Critical: <code>X-Forwarded-Proto</code> header must be set for SSO (Google/Microsoft Sign-In) to prevent redirect loops when SSL terminates at Nginx. Also covers Apache mod_fcgid timeout configuration (FcgidIOTimeout, FcgidIdleTimeout) for environments not using Nginx.
 
'''Keywords:''' nginx, reverse proxy, 504 gateway timeout, 502 bad gateway, proxy_buffer_size, proxy_buffers, proxy_read_timeout, X-Forwarded-Proto, SSO, SSL termination, redirect loop, apache, mod_fcgid, FcgidIOTimeout, timeout configuration
 
'''Key Questions:'''
'''Key Questions:'''
* How do I fix a "504 Gateway Timeout" error in Nginx with VoIPmonitor?
* How do I fix 504 Gateway Timeout in Nginx with VoIPmonitor?
* What are the recommended Nginx settings for VoIPmonitor?
* What are the recommended Nginx buffer settings for VoIPmonitor?
* How can I increase the proxy buffer size in Nginx?
* Why does Google/Microsoft Sign-In fail behind Nginx reverse proxy?
* Why am I getting errors when downloading large reports or many PCAPs from the GUI?
* How do I fix SSO redirect loops with SSL termination?
* How to configure Nginx as a reverse proxy for Apache/PHP-FPM?
* What are the recommended timeout values for Nginx with VoIPmonitor?
* What do `proxy_buffers` and `proxy_read_timeout` do?
* How do I fix Apache timeout errors when loading VoIPmonitor dashboards?

Latest revision as of 16:47, 8 January 2026


Nginx Reverse Proxy Configuration

This guide covers Nginx configuration as a reverse proxy for the VoIPmonitor GUI, addressing common issues with large data transfers and long-running operations.

Common Problems

Problem Symptom Solution
Large data requests Errors downloading reports/PCAPs Increase buffer sizes
Long operations 504 Gateway Timeout Increase timeout values
SSO redirect loops Google/Microsoft Sign-In fails Add X-Forwarded-Proto header
Backend down 502 Bad Gateway Check Apache/PHP-FPM status

Recommended Configuration

Add this configuration to your Nginx location block: 

location / {
    proxy_pass http://127.0.0.1:80;

    # Buffer settings for large reports/PCAP downloads
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    # Timeout settings (1 hour for long-running operations)
    proxy_connect_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_read_timeout 3600s;
    send_timeout 3600s;

    # Required 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 (Google/Microsoft Sign-In)
    proxy_set_header X-Forwarded-Proto $scheme;
}

⚠️ Warning: The X-Forwarded-Proto header is required for SSO (Google/Microsoft Sign-In) when SSL is terminated at Nginx. Without it, you will experience redirect loops.

Apply Changes

# Test configuration syntax
sudo nginx -t

# Reload configuration
sudo systemctl reload nginx

Troubleshooting

504 Gateway Timeout

Increase all timeout values in the Nginx configuration. The default timeouts are too short for:

  • Large CDR exports
  • Bulk PCAP downloads
  • Complex report generation

502 Bad Gateway

The backend service is not responding. Check: 

# Check Apache status
systemctl status apache2

# Or check PHP-FPM status
systemctl status php-fpm

SSO Redirect Loops

If Google or Microsoft Sign-In fails with redirect loops:

1. Verify X-Forwarded-Proto header is set 2. Check that the header value matches the actual protocol (https) 3. Ensure the GUI's configured URL matches the public URL

Apache Alternative (Without Nginx)

If using Apache with mod_fcgid directly (not behind Nginx), increase these timeouts in Apache configuration: 

FcgidIOTimeout 900
FcgidIdleTimeout 900
FcgidConnectTimeout 900
FcgidProcessLifeTime 900

# Apply changes
systemctl restart apache2   # Debian/Ubuntu
systemctl restart httpd     # RHEL/CentOS

💡 Tip: These settings fix "server side error - connection to the web server was lost" when loading dashboards or charts.

See Also

AI Summary for RAG

Summary: Nginx reverse proxy configuration guide for VoIPmonitor GUI. Covers buffer settings (proxy_buffer_size, proxy_buffers) for large data downloads and timeout settings (proxy_read_timeout, etc.) set to 3600s to prevent 504 errors on long operations. Critical: X-Forwarded-Proto header must be set for SSO (Google/Microsoft Sign-In) to prevent redirect loops when SSL terminates at Nginx. Also covers Apache mod_fcgid timeout configuration (FcgidIOTimeout, FcgidIdleTimeout) for environments not using Nginx.

Keywords: nginx, reverse proxy, 504 gateway timeout, 502 bad gateway, proxy_buffer_size, proxy_buffers, proxy_read_timeout, X-Forwarded-Proto, SSO, SSL termination, redirect loop, apache, mod_fcgid, FcgidIOTimeout, timeout configuration

Key Questions:

  • How do I fix 504 Gateway Timeout in Nginx with VoIPmonitor?
  • What are the recommended Nginx buffer settings for VoIPmonitor?
  • Why does Google/Microsoft Sign-In fail behind Nginx reverse proxy?
  • How do I fix SSO redirect loops with SSL termination?
  • What are the recommended timeout values for Nginx with VoIPmonitor?
  • How do I fix Apache timeout errors when loading VoIPmonitor dashboards?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Nginx&oldid=10033"