NGINX Connection to PHP-FPM Socket Failed: Path Resolution and Configuration Optimization

Problem Phenomenon and Diagnosis

When deploying PHP applications on Ubuntu 16.04 systems, a common issue is NGINX's inability to connect to PHP-FPM. Typical error logs show:

connect() to unix:/var/run/php7.0-fpm.sock failed (2: No such file or directory)

This error indicates that while attempting to connect to the specified Unix domain socket, NGINX cannot locate the corresponding file. However, when users examine the filesystem, they encounter a seemingly contradictory phenomenon:

$ sudo ls -l /var/run/php
total 4
-rw-r--r-- 1 root     root     5 Oct 15 13:00 php7.0-fpm.pid
srw-rw---- 1 www-data www-data 0 Oct 15 13:00 php7.0-fpm.sock
$ sudo ls -l /var/run/php7
ls: cannot access '/var/run/php7': No such file or directory

This discrepancy stems from the peculiarities of path resolution in Unix systems. /var/run/php is a directory, while /var/run/php7 is a non-existent path. When using ls /var/run/php, the command actually lists the contents of the /var/run/php/ directory, which includes the php7.0-fpm.sock file. Understanding these subtle differences in path resolution is crucial for troubleshooting.

PHP Version Evolution and Socket Path Changes

During the transition from PHP 5 to PHP 7, one significant change was the adjustment of the default PHP-FPM socket path. Although minor, this modification had substantial implications for system configuration:

• PHP 5: Socket files typically located at /var/run/php5-fpm.sock
• PHP 7: Socket files default to /var/run/php/php7.0-fpm.sock

This path change reflects modern Linux distributions' efforts to standardize system directory structures. The /var/run/php/ directory serves as a dedicated location for better organization of PHP-related runtime files, including sockets and process ID files for different versions.

NGINX Configuration Correction

The core solution to this problem involves updating NGINX's configuration file to point to the correct socket path. In typical PHP-FPM configurations, the fastcgi_pass directive needs modification:

# Incorrect configuration
fastcgi_pass unix:/var/run/php7.0-fpm.sock;

# Correct configuration
fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;

This correction ensures NGINX can locate the socket file created by PHP-FPM. In practical deployments, precise PHP version matching must also be considered. For instance, Ubuntu 18.04 systems might default to PHP 7.2, requiring the configuration to be adjusted accordingly:

fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;

Practical Recommendations for Ansible Automated Deployment

When using Ansible for automated deployment, properly handling socket path issues is particularly important. Based on the provided Ansible playbook, the following improvement strategies can be implemented:

- name: Configure nginx with correct PHP-FPM socket path
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/sites-available/default
  vars:
    php_socket_path: "/var/run/php/php{{ php_version }}-fpm.sock"
  notify:
    - restart php-fpm
    - restart nginx

This templating approach allows dynamic generation of correct socket paths, adapting to different PHP versions and environment configurations. Simultaneously, ensure proper configuration of related service restart handlers:

handlers:
  - name: restart php-fpm
    service:
      name: "php{{ php_version }}-fpm"
      state: restarted
  
  - name: restart nginx
    service:
      name: nginx
      state: restarted

System Debugging and Verification Steps

When encountering socket connection problems, systematic debugging methods can help quickly identify issues:

1. Verify Socket File Existence: Use sudo ls -la /var/run/php/ to confirm the socket file exists with correct permissions
2. Check PHP-FPM Service Status: Run sudo systemctl status php7.0-fpm to ensure the service is running properly
3. Validate Socket Permissions: Socket files should belong to the www-data user and group, ensuring NGINX processes have access rights
4. Test Socket Connection: Use sudo netstat -lnp | grep php to verify the socket is in listening state
5. Check NGINX Configuration Syntax: Run sudo nginx -t to validate configuration file syntax correctness

Security and Permission Considerations

When configuring PHP-FPM sockets, security aspects cannot be overlooked. Proper permission settings prevent unauthorized access:

• Socket files should be restricted to www-data user and group access, typically with permissions set to 660
• Avoid placing socket files in web-accessible directories
• Regularly check socket file permission settings to prevent security issues from configuration drift

Conclusion and Best Practices

Socket communication between NGINX and PHP-FPM forms the infrastructure of modern PHP application deployment. Properly handling path configuration issues requires understanding:

1. The impact of path changes brought by PHP version upgrades
2. Subtle differences in Unix system path resolution
3. Dynamic configuration strategies in automated deployment tools

By adopting templated configuration management, version-aware path generation, and systematic debugging methods, the reliability and maintainability of PHP application deployment can be significantly improved. These practices not only solve specific connection problems but also provide a solid foundation for building robust web application infrastructure.