Keywords: Nginx | PHP-FPM | 502 Error | Connection Refused | FastCGI
Abstract: This technical article addresses the common 502 Gateway Timeout error in Nginx deployments, providing a comprehensive analysis of the 'connect() failed (111: Connection refused) while connecting to upstream' error. Through detailed examination of PHP-FPM configuration and Nginx upstream settings, it presents complete solutions including modifying listen.allowed_clients parameters in php5-fpm configuration, adjusting listening methods, and proper service restart procedures. The article systematically explains technical details of permission configuration, network connectivity, and service coordination using concrete error log examples, offering developers actionable troubleshooting guidance.
Problem Background and Error Analysis
In web application deployment, the coordination between Nginx as a reverse proxy server and backend FastCGI process managers (such as PHP-FPM) is crucial. When 502 Gateway Timeout errors occur, it typically indicates that Nginx cannot establish effective connections with upstream services. From the provided error log, the core issue is: connect() failed (111: Connection refused) while connecting to upstream, specifically pointing to fastcgi://127.0.0.1:9000.
Root Cause Analysis
This error indicates that Nginx's attempt to connect to local address 127.0.0.1 on port 9000 was refused. This is typically not a permission issue but rather PHP-FPM service configuration restricting connection sources. PHP-FPM default configurations may only allow specific client connections, or improper listening configuration prevents Nginx from establishing connections.
Solution Implementation
First, modify the PHP-FPM configuration file. On Debian/Ubuntu-based systems, use the following command to edit the configuration file:
sudo nano /etc/php5/fpm/pool.d/www.confIn the configuration file, locate the listen.allowed_clients line and ensure it's uncommented and set to 127.0.0.1:
listen.allowed_clients = 127.0.0.1Simultaneously, adjust the listening configuration. Comment out the Unix socket listening method:
;listen = /var/run/php5-fpm.sockAnd enable TCP port listening:
listen = 9000Service Restart and Verification
After completing configuration modifications, reload or restart the relevant services. First restart the PHP-FPM service:
sudo service php5-fpm restartOr use the reload command to maintain existing connections:
sudo service php5-fpm reloadThen restart the Nginx service:
sudo service nginx restartOr use the reload command:
sudo service nginx reloadConfiguration Principles Deep Dive
The listen.allowed_clients parameter defines the client IP addresses permitted to connect to PHP-FPM. When set to 127.0.0.1, it only allows connections from the local loopback address, providing basic security assurance. Switching the listening method from Unix socket to TCP port 9000 ensures Nginx can communicate with PHP-FPM through standard network protocols.
In Nginx's virtual host configuration, the corresponding upstream configuration should be set as:
fastcgi_pass 127.0.0.1:9000;This configuration combination ensures Nginx can successfully forward FastCGI requests to local PHP-FPM processes.
Extended Troubleshooting Recommendations
If the above solution doesn't resolve the issue, further checks are recommended: whether PHP-FPM processes are running normally, if firewall settings are blocking port 9000 connections, and configurations of security modules like SELinux or AppArmor. More detailed diagnostic information can be obtained through system logs and PHP-FPM error logs.