linux troubleshooting guide

Linux Permissions Troubleshooting Before chmod

Permission failures are usually path problems, ownership problems, service-user problems, or mode problems. Inspect all four before changing anything.

Problem

An application cannot read a file, Nginx returns 403, SSH rejects a key, or a script says permission denied. Someone suggests `chmod -R 777`. That is almost never the right first move.

First rule

Inspect the full path and service user before changing file modes.

Audience

beginners, web developers, junior admins, and defensive security learners

Cert context

Strong unofficial practice for file permissions, ownership, groups, and safe administration objectives.

quick start

Safe first commands

namei -l /var/www/example/index.html
stat -c '%A %U:%G %n' /var/www/example/index.html
ls -ld /var /var/www /var/www/example

Check every directory in the path

A readable file is still unreachable if the service user cannot traverse one directory above it. `namei -l` shows each path component.

namei -l /var/www/example/index.html

Read owner, group, and mode together

Mode bits only make sense alongside owner and group. `stat` gives the compact view you need before deciding whether ownership or mode is wrong.

stat -c '%A %U:%G %n' /var/www/example/index.html

Match the fix to the service user

Web servers, app processes, cron jobs, and SSH have different users and strictness rules. Fixing the wrong user or broadening permissions can hide the real issue while increasing exposure.

ps -eo user,comm,args | grep -E 'nginx|apache|node|python' | grep -v grep

Avoid recursive permission changes under pressure

`chmod -R` and `chown -R` can break applications, expose secrets, and make later forensic review harder. Change the smallest path component that explains the failure.

find /var/www/example -maxdepth 2 -type f -perm -o+r -print | head

triage logic

How to read the result

a parent directory lacks execute permission for the needed user path

The process cannot traverse the directory even if the final file is readable.

Next: Adjust the narrow directory permission or group membership instead of changing the whole tree.

the file is owned by an unexpected user

A deploy, upload, or restore may have changed ownership.

Next: Confirm the intended service user and fix ownership narrowly.

secrets are world-readable

The current permissions may expose credentials.

Next: Restrict access and check whether any process depends on the loose mode.

safety notes

Slow down here

Do not use `chmod 777` as a diagnostic shortcut on real systems.
Capture current owner and mode before changing them.
Treat SSH keys, environment files, and database credentials as sensitive.

related lessons