FreeBSD 14 PHP-FPM Cannot Access Unix Socket Due to Permission Drift

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Nginx returns 502 because it cannot connect to php-fpm socket.

Environment & Reproduction

After package updates or pool config edits.

service php_fpm status && sockstat -4 -6 -l | grep php-fpm

Root Cause Analysis

Socket owner/group or mode no longer matches web server runtime user.

Quick Triage

Check socket path in both nginx and php-fpm configs.

grep -R "fastcgi_pass|listen =" /usr/local/etc

Step-by-Step Diagnosis

Inspect pool-level listen.owner, listen.group, and listen.mode.

grep -nE 'listen.|user *=|group *=' /usr/local/etc/php-fpm.d/*.conf

Solution – Primary Fix

Set matching user/group and secure socket mode, then restart services.

sudo service php_fpm restart && sudo service nginx reload

Solution – Alternative Approaches

Switch to localhost TCP upstream if socket ownership churn persists.

Verification & Acceptance Criteria

Dynamic PHP requests succeed and error log no longer shows connect() denied.

Rollback Plan

Restore prior pool config and service definitions.

Prevention & Hardening

Lock php-fpm pool templates and validate on deployment.

Related Errors & Cross-Refs

Can align with chroot path or jail mount permission issues.

Related tutorial: View the step-by-step tutorial for freebsd-14.

View all freebsd-14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

PHP-FPM pool security and Nginx upstream integration docs.