Linux File System Hierarchy
debt(d7/e5/b7/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints list lynis, namei, and ls-la — these are specialist audit/inspection tools that a developer must deliberately invoke; they won't catch wrong file placements during development or CI automatically. Wrong paths typically surface at runtime (session not writable, uploads lost on reboot, log rotation broken) rather than at compile or lint time, placing this firmly at d7 rather than d9 (which would be silent in production until users hit it — here, symptoms do appear relatively quickly in staging/testing).
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix notes ownership/permission corrections for PHP-FPM, but the common_mistakes reveal that misplaced files span multiple concerns: upload directories, log paths, temp file usage, and hardcoded home paths. Correcting these requires updating configuration files (php.ini, FPM pool configs), application code that references paths, deployment scripts, and potentially log rotation configs — well beyond a one-liner but not a full architectural rework.
Closest to 'strong gravitational pull' (b7). The misconception confirms that non-standard file locations break package managers, backup scripts, log rotation configs, and security policies. The applies_to covers both web and CLI contexts, meaning every deployment decision, every sysadmin script, and every tool integration is shaped by whether FHS conventions are followed. Violations create persistent cross-cutting debt where every new feature (logging, uploads, sessions) must work around the wrong baseline.
Closest to 'serious trap — contradicts how a similar concept works elsewhere' (t7). The misconception is explicit: 'Files can go anywhere as long as they work.' This is a deeply intuitive belief for developers coming from Windows or containerised environments where paths are more flexible. The trap is that code works perfectly in development (local machine, single user, no log rotation, no backup scripts) but breaks in production in multiple subtle ways. This contradicts the developer's reasonable mental model that 'if it runs, it's fine,' making it a t7 rather than t9 (the obvious path isn't always wrong — it just fails in specific production contexts).
Also Known As
TL;DR
Explanation
FHS (Filesystem Hierarchy Standard) defines where things go: /etc (config files), /var (variable data — logs, spool, databases), /var/log (logs), /var/www (web content), /tmp (temp files, cleared on reboot), /usr/local (locally installed software), /home (user home dirs), /root (root home), /proc (virtual — kernel and process info), /sys (virtual — hardware info), /run (runtime data, cleared on reboot), /opt (optional/third-party software). PHP apps live in /var/www; logs go to /var/log; runtime files (PID, sockets) go to /run.
Common Misconception
Why It Matters
Common Mistakes
- Writing temporary files to the app directory — use sys_get_temp_dir() or /tmp; app directory may not be writable.
- Storing uploaded files in /tmp — /tmp is cleared on reboot; use /var/www/uploads or object storage.
- Log files in the application root — they should go to /var/log/appname/ for log rotation and access control.
- Hardcoding /home/username paths — breaks when deployed as a different user or on a different server.
Code Examples
// Files in wrong locations:
define('LOG_FILE', '/tmp/app.log'); // Cleared on reboot!
define('UPLOAD_DIR', '/tmp/uploads/'); // Cleared on reboot!
define('CONFIG_FILE', '/home/paul/app.conf'); // User-specific path
define('PID_FILE', '/var/www/html/app.pid'); // Wrong — should be /run/// Correct FHS locations:
define('LOG_FILE', '/var/log/myapp/app.log');
define('UPLOAD_DIR', '/var/www/myapp/uploads/'); // Persistent
define('CONFIG_FILE', '/etc/myapp/config.php'); // Standard config location
define('PID_FILE', '/run/myapp/app.pid'); // Standard runtime location
define('CACHE_DIR', sys_get_temp_dir() . '/myapp_cache/'); // Portable temp