Linux & macOS Filesystem Explained: Important Folders, Config Files, Logs, and Troubleshooting

Published on September 19, 2026 by Muhammad Raza Bangi · 27 min read

A developer deploys a website through a hosting dashboard. Everything works — until it doesn't. The site starts returning a 502 error, disk usage hits 100%, a domain resolves to the wrong server, or a background job silently stops running. The dashboard that made deployment easy now hides exactly the information needed to fix the problem: where the configuration lives, where the logs are written, which process is actually running, and who owns which file.

Modern hosting platforms — cPanel, Plesk, Vercel, managed WordPress hosts — are good at making deployment fast. They're not designed to teach you what's happening underneath. The moment something breaks in a way the dashboard can't explain, or you move to a VPS where there is no dashboard, you need to know the filesystem: what each important directory is for, where logs and configuration actually live, and how to inspect a running server safely without guessing.

This guide covers that filesystem in practical depth, for both Linux (with an emphasis on Ubuntu/Debian, the most common choice in web hosting) and macOS, which is Unix-based but meaningfully different in several places. Every section is labeled by platform, and every command is marked as either safe to run or state-changing, so you can follow along on a real machine without breaking anything.

What You Will Learn

1. What Is a Filesystem?

A filesystem is the way an operating system organizes and finds data on disk. Every piece of stored data — a program, a photo, a configuration file — lives inside a file, and files are organized into directories (folders), which can contain other directories. The location of a file, written out from the top of that structure, is its path.

On Linux and macOS there is exactly one directory tree, and it starts at a single root, written as a forward slash: /. Windows assigns a separate letter to each disk (C:, D:); Unix-like systems instead mountevery additional disk, partition, or network share onto some folder inside that one tree. A second hard drive doesn't become a new root — it becomes, say, /mnt/backup, and once mounted, files under it are addressed exactly like any other path. The folder a filesystem is attached to is called its mount point (more in section 13).

A path is absolute when it starts from the root, like /etc/nginx/nginx.conf — it means the same thing no matter where you currently are. A path is relativewhen it doesn't start with a slash, like logs/error.log— it's resolved against your current directory, so the same relative path can point to different files depending on where you run it from.

Don't confuse the root directory (/, the top of the tree) with the root user— the administrative account, sometimes called the superuser, that can read and write anything on the system. They share a name by convention, not because they're the same thing; every regular user's files still live somewhere under / too.

Both Linux and macOS filesystems are, by default, case-sensitive: Report.txt and report.txtare different files. macOS is a partial exception — its default APFS volumes are usually formatted case-insensitive but case-preserving, so two files differing only in case can't normally coexist, which occasionally surprises developers moving a project from Linux. Any file or directory whose name starts with a dot, like .env or .gitignore, is a hidden file— the shell and file managers skip it by default, but it's an ordinary file in every other respect.

The tilde, ~, is shorthand for the current user's home directory — /home/alex on Linux or /Users/alex on macOS. You'll see it constantly in documentation and shell prompts.

You'll often hear "everything is a file" used to describe Unix-like systems. It's a useful simplification — a running process's state, a hardware device, and a network socket can all be represented and interacted with through something that looks like a file — but it isn't perfectly literal. Some of these (covered in section 12) are virtual: they don't hold bytes on disk, they're a live window the kernel generates on demand when you read them.

pwd          # print the absolute path of your current directory
ls           # list files in the current directory
ls -la       # list all files, including hidden ones, with permissions/owner/size
cd /etc      # change into an absolute path
cd ~         # change into your home directory

pwd("print working directory") confirms exactly where you are before you run anything else — useful before trusting a relative path. ls -la adds two things to a plain listing: -a reveals dotfiles, and -l switches to the "long" format, which is where you'll read permissions and ownership (see section 14).

2. A Visual Tour of the Filesystem

This is the shape of a typical Linux root directory. macOS shares most of these names (it's Unix-based) but reserves several for its own use — see the caveats after the table.

/
├── bin      → essential command binaries
├── boot     → boot loader files, kernel images
├── dev      → device files (virtual)
├── etc      → system-wide configuration
├── home     → regular users' personal files
├── opt      → optional third-party software
├── proc     → live process/kernel info (virtual)
├── root     → the root user's home directory
├── run      → runtime state since last boot (virtual)
├── sbin     → essential admin binaries
├── srv      → data served by this system (less common)
├── tmp      → temporary files, cleared periodically
├── usr      → installed programs and shared resources
└── var      → logs, caches, and other changing data

3. /etc: System Configuration

/etcis where a Unix-like system traditionally keeps machine-wide configuration — the closest thing to a government office holding the rules everyone on the machine follows. That's a convention, not a hard rule: plenty of applications (databases, language runtimes, containerized services) keep their own configuration somewhere else entirely, often inside their own installation directory or a project folder. Treat /etc as the first place to look for system-level settings, not the only place.

Not every file below exists on every machine — presence depends on your distribution and what's installed.

4. Deep Dive: /etc/hosts

First, the correction that matters most for searchability: the file is /etc/hosts, plural — never /etc/host. It stores mappings for potentially many hosts, hence the name.

The hosts file is a plain-text table your operating system checks to translate a hostname into an IP address, before it ever asks a DNS server. Each meaningful line pairs an IP address with one or more hostnames:

127.0.0.1  92nodes.test

That single line tells your machine — and only your machine — that requests for 92nodes.test should go to 127.0.0.1, the loopback address that always means "this computer." Open a browser afterward and 92nodes.test resolves to whatever is running locally, without touching the public internet at all.

This is different from DNS in one crucial way: DNS is a distributed, public system that answers the same question for anyone in the world; the hosts file is a private override that exists only on the machine where it was edited. Developers use it to point a friendly local domain at a project running on localhost, to test a staging environment under its real production hostname before DNS is switched over, or to temporarily redirect a domain during a server migration without touching public records. None of that creates, changes, or previews a real DNS record — anyone else visiting that domain still gets whatever the actual DNS records say.

Because both the operating system and the browser cache DNS lookups, a hosts-file edit can appear not to work immediately even though it's correct — the old answer is just still cached somewhere. Restarting the browser or flushing the OS DNS cache usually resolves the apparent delay.

Inspecting and editing safely

cat /etc/hosts                                  # view current contents (Linux & macOS)
sudo cp /etc/hosts /etc/hosts.bak.$(date +%F)   # back up before editing (Linux & macOS)
sudo nano /etc/hosts                            # open in an editor and add one line at a time

Add a new line under the existing entries rather than replacing the file's contents — the file typically already contains required entries such as a loopback line for localhost, and removing those can break local tools that depend on them.

To verify resolution after editing:

ping 92nodes.test                        # both — confirms an IP was resolved
getent hosts 92nodes.test                # Linux — shows exactly what the resolver returned
dscacheutil -q host -a name 92nodes.test # macOS — queries the local Directory Service cache

pingonly proves that a hostname resolved to an IP address and that address replied to an ICMP packet — it says nothing about whether a web server is actually listening, whether it's returning errors, or whether TLS is configured correctly. Treat a successful ping as one data point, not a website health check.

5. DNS and /etc/resolv.conf

When a hostname isn't found locally, the system asks a nameserver — a DNS server responsible for translating names into IP addresses. On Linux, /etc/resolv.conf traditionally lists which nameservers to use and any search domains (suffixes automatically appended to short, unqualified hostnames).

On most current Linux distributions, this file is no longer meant to be hand-edited: it is generated and rewritten automatically by systemd-resolved, NetworkManager, or a DHCP client hook, often ending up as a symlink. A manual edit can appear to work for a moment and then silently revert on the next network event or reboot. If you need a persistent change, configure it through the resolver service itself.

Safe diagnostic commands:

dig example.com                # both (if installed) — detailed DNS query and response
nslookup example.com           # both — simpler DNS query tool
resolvectl status              # Linux (systemd-resolved) — shows active DNS config per interface
scutil --dns                   # macOS — shows the effective resolver configuration

On macOS, don't try to manage DNS long-term by editing /etc/resolv.conf directly — macOS builds its resolver configuration dynamically and expects DNS changes through System Settings → Network, or networksetup on the command line, not a hand edit that the system will overwrite.

6. /var: Changing Application Data

/var stands for variable data — anything the system expects to keep growing or changing while the machine runs, as opposed to /etc's mostly-static configuration.

/var/wwwis a packaging convention on Debian/Ubuntu-based Nginx and Apache installs, not a filesystem requirement — plenty of real servers don't have it. Laravel, Node.js, Docker, databases, and web servers each decide their own default locations for logs and state, and any of them can be reconfigured to write elsewhere; the safest way to find the real path is to check the relevant configuration file rather than assume a convention holds.

7. Logs: Where Errors Actually Live

Linux logging generally comes in two forms today: traditional plain-text files under /var/log, and the systemd journal, a structured, indexed log store read with journalctl. Many services write to both; some, especially ones that log only via systemd, only exist in the journal. macOS uses its own unified logging system instead, read with log show and log stream.

Useful commands:

tail -f /var/log/nginx/error.log          # follow a file live as new lines are written
journalctl -u nginx                       # all journal entries for the nginx service
journalctl -u nginx --since "30 minutes ago"
sudo systemctl status nginx               # quick health snapshot + recent log lines

log show --predicate 'process == "sshd"' --last 30m
log stream --predicate 'process == "nginx"'

A few tools you'll lean on constantly: tail prints the end of a file (add -f to keep watching it live); less opens a file for scrollable, searchable reading without loading it all into your terminal history; grep filters lines matching a pattern, e.g. grep "500" access.log. journalctl's -u flag filters by service, and --since filters by time — both make a large journal actually searchable.

Scenario: a website returns 502 Bad Gateway

A 502 means the web server (Nginx or Apache) is up and reachable, but the application it forwards requests to — the upstream — didn't answer correctly. Work through it in order:

1. Confirm the response with a direct request rather than trusting the browser cache.
2. Check the web server's error log for the specific upstream failure reason.
3. Check whether the application process (PHP-FPM, Node.js, a queue worker) is actually running.
4. Check the upstream service's own logs — PHP-FPM, Node.js, or whatever sits behind the proxy.
5. Check that the port or Unix socket the web server expects to reach is the one the app is actually listening on.
6. Check file and socket permissions between the web server user and the application user.
7. Check disk space and memory — an OOM-killed process or a full disk can cause exactly this.
8. Review whatever configuration changed most recently — a deploy, a config reload, a certificate renewal.

8. /home, /root, and macOS /Users

Every regular user gets a personal directory — /home/alex on Linux, /Users/alex on macOS — holding their files and personal configuration. The root user is the one exception: its home directory is /root, a separate, dedicated location rather than a folder inside /home.

User-specific configuration usually lives as dotfiles directly in the home directory: ~/.ssh for SSH keys and known hosts, ~/.config for many modern applications' settings, and shell startup files like .bashrc, .profile, or .zshrc (macOS has used zsh as its default shell since Catalina).

Inside ~/.ssh you'll typically find:

9. /usr, /bin, /sbin, and PATH

/usrholds the bulk of a system's installed programs, libraries, and shared resources — /usr/bin for user commands, /usr/sbin for administrative commands, and /usr/local (with its own bin subfolder) reserved for software installed manually or outside the distribution's package manager. That separation is exactly why manually built scripts and tools are conventionally placed in /usr/local/bin — the package manager will never overwrite anything there.

On many current Linux distributions, /bin and /sbin are symbolic links into their /usr equivalents — a "merged /usr" layout that simplifies having a separate /usr partition. You can usually still use either path; they resolve to the same files.

Which actual program runs when you type a command name is decided by PATH, an environment variable listing directories to search, in order, for a matching executable. When two installs of PHP or Node.js exist on the same machine — a system package and a manually installed version, for example — whichever directory appears first in PATHwins, which is a common source of "it works in my terminal but the wrong version runs in production."

which php        # path to the php binary that would actually run
which node
command -v nginx # POSIX-portable equivalent of which
type php         # shows whether it's a binary, alias, or shell built-in
echo "$PATH"     # the ordered list of directories being searched

10. /opt: Optional Third-Party Software

/optis conventionally used for self-contained, optional third-party applications that don't integrate into the distribution's normal package layout — for example, a vendor-supplied database engine or a commercial application often installs under /opt/vendor-name. The practical difference from /usr/local is mostly about self-containment: /usr/local expects software to slot into the standard bin/lib/share layout, while /opt packages usually bundle their own internal directory structure. Not every third-party application uses /opt — plenty install through the normal package manager into /usr instead.

11. /tmp and Temporary Files

/tmp is shared scratch space that any user or process can write to. Many systems clear it automatically on reboot or on a schedule, and permissions are commonly world-writable with the sticky bit set — a special permission flag (shown as a tat the end of the permission string) meaning that even though everyone can create files here, only a file's owner (or root) can delete or rename it. That's what stops one user from deleting another user's temporary files out from under them.

/var/tmp serves a similar purpose but is conventionally expected to survive across a reboot, whereas /tmpoften does not — check your specific distribution's configuration rather than assuming either behavior.

Because it's world-writable and routinely cleared, never treat /tmpas durable storage for anything that matters — a generated report a user needs to download later, an upload awaiting processing, or any file your application can't afford to lose. On a live server, don't manually clear /tmp either; another process may currently depend on a file sitting there.

12. /proc, /sys, /dev, and /run

These aren't ordinary folders holding bytes on disk — they're virtual filesystemsthe kernel generates on the fly. Reading a "file" here doesn't read stored data; it asks the kernel a live question and gets back a live answer.

cat /proc/cpuinfo
cat /proc/meminfo
ls /proc

13. Mount Points: /mnt, /media, and Drives

Mounting is the act of attaching a filesystem — a disk partition, a USB drive, a network share — onto a folder in the tree, so its files become reachable at that path. /mnt is the conventional location for manually mounted filesystems; /media is typically used for removable media mounted automatically by the desktop environment. A disk can be physically connected and fully functional but invisible in the place you expect, simply because nothing has mounted it yet.

mount             # list currently mounted filesystems
findmnt           # a more readable, tree-formatted view of mounts
lsblk             # list block devices and their mount points
df -h             # disk usage per mounted filesystem, human-readable

/etc/fstabdefines which filesystems should be mounted automatically at boot and where. It's read very early in the boot process, so a malformed entry can prevent the system from booting normally.

macOS mounts external and network volumes under /Volumes, each appearing as its own named folder there rather than under /mnt.

14. File Ownership and Permissions

Every file and directory has an owner (a user) and a group, and grants three kinds of access — read, write, and execute— separately to three parties: the owning user, the owning group, and everyone else ("others"). On a directory, execute means something slightly different than on a file: it controls whether you can enter or look inside that directory at all, not whether you can "run" it.

ls -l
# -rw-r--r-- 1 alex developers  1240 Sep 12 10:03 example.txt
# drwxr-xr-x 2 alex developers  4096 Sep 12 10:03 scripts

Reading the ten-character string from the left: the first character is - for a regular file or d for a directory. The remaining nine come in three groups of three — owner, group, others — each showing r, w, x, or - for "not granted." -rw-r--r-- means the owner can read and write, and the group and everyone else can only read.

The same permissions are also written as a three-digit numeric mode, adding 4 (read), 2 (write), and 1 (execute) for each of owner/group/others:

chmod 644 example.txt          # set permissions by numeric mode
chmod 755 scripts               # directories generally need the execute bit to be enterable
chown user:group example.txt    # change owner and group (usually requires sudo on files you don't own)

777grants read, write, and execute to everyone — owner, group, and others alike. It's rarely the right fix: a "permission denied" error almost always means the wrong user or group owns the file, or the process is running as the wrong user, not that the permission bits need to be maxed out. On a shared or internet-facing server, 777also means any user or compromised process on that machine can modify the file. Diagnose the actual owner and the actual running user first, and grant only what's needed — the principle of least privilege.

A common real example: a Laravel application needs its web-server process to be able to write inside the storage and bootstrap/cache directories, because that's where it writes logs, compiled views, and framework cache. The concept is: the user your web server actually runs as (commonly something like www-dataon Debian/Ubuntu, but this varies by distribution and hosting setup) needs write access there, through ownership or group membership — not through opening the directory to every user on the system. There's no single universal user/group to prescribe here because server setups differ; check what user your web server and PHP-FPM pool are actually configured to run as before deciding on ownership.

15. Services: systemd vs launchd

A service(or daemon) is a program meant to run continuously in the background, independent of any logged-in user — a web server, a database, an SSH daemon. That's distinct from just having the application's files on disk: files are static until something starts a process from them, and a service manager is what starts, stops, restarts, and supervises that process automatically, including across reboots.

Most current major distributions (Ubuntu, Debian, Fedora, RHEL-family, and others) use systemd as their service manager, controlled with systemctl, driven by unit files that describe how to start a service, what it depends on, and how to restart it if it fails. Arch Linux also uses systemd by default. Editing a vendor-shipped unit file directly is usually a bad idea — package updates can overwrite it — so systemd provides an override mechanism (systemctl edit) instead.

systemctl status nginx     # safe, read-only — current state and recent log lines
systemctl restart nginx    # state-changing — restarts the service, needs sudo
systemctl enable nginx     # state-changing — makes it start automatically on boot, needs sudo
journalctl -u nginx        # safe, read-only — this service's journal entries

macOS does not use systemd — systemctl simply doesn't exist there. Instead it uses launchd, configured through XML property-list files: LaunchAgents run on behalf of a logged-in user, while LaunchDaemons run system-wide, independent of any user session — the closest macOS equivalent to a Linux system service.

16. Processes, Ports, and Sockets

Every running program is a process, identified by a numeric process ID (PID). A port is a numbered endpoint a network service listens on (Nginx commonly listens on 80 and 443); a process bound to a port is said to be listening there. A socket is the underlying communication endpoint — most commonly a TCP socket over the network, or a Unix socket, a file-based communication channel used for fast local-only connections, which is exactly how Nginx often talks to PHP-FPM on the same machine.

This connects directly back to the 502 scenario in section 7: Nginx returns 502 specifically when it can reach the upstream address it's configured with, but nothing is listening there — the application process crashed, hasn't started yet, or is listening on a different port or socket path than Nginx expects.

ps aux                       # both — list running processes
top                          # both — live, updating process view
lsof -i :3000                # both, if installed — which process owns port 3000
ss -ltnp                     # Linux only — listening TCP sockets with owning process
curl -I http://localhost:3000 # both — just the response headers, quick liveness check

ss is a Linux-specific tool (the modern replacement for the older netstat). lsofis useful on both Linux and macOS wherever it's installed, and is the standard choice on macOS specifically since ssisn't available there.

17. Where Web-Development Files Live

Nginx

The main configuration file is typically /etc/nginx/nginx.conf, with individual site configs conventionally split into /etc/nginx/sites-available/ and symlinked into /etc/nginx/sites-enabled/ on Debian/Ubuntu, though not every install uses that split. Access and error logs default to /var/log/nginx/. Always test a configuration before reloading it:

sudo nginx -t          # validates syntax without applying anything
sudo systemctl reload nginx   # state-changing — applies a valid config with no dropped connections

Apache

On Debian/Ubuntu, configuration lives under /etc/apache2/, with virtual hosts in sites-available/ and logs in /var/log/apache2/. RHEL-family distributions instead use /etc/httpd/ and /var/log/httpd/. Enabled modules are configured separately from virtual hosts in both layouts.

PHP and PHP-FPM

PHP's CLI and FPM (FastCGI Process Manager) modes commonly load different php.ini files, and FPM adds its own pool configuration controlling how many worker processes run and what user they run as. Find exactly which configuration is actually loaded rather than assuming:

php --ini    # shows which php.ini (and any scanned additional .ini files) is loaded
php -i       # full, detailed PHP configuration dump

Laravel

Within a Laravel project:

Node.js and Next.js

Source files are just files until a process runs them — the code on disk and the currently running Node.js process are two different things, and editing the source doesn't change the running process until it's restarted or a watcher reloads it. Common conventions: .env, .env.local, and other .env.* variants for environment configuration; a build output directory (Next.js uses .next); and logs that depend entirely on how the process is run — captured by a process manager (like PM2), by the container runtime, or by whatever system service wraps it, rather than a single fixed path.

Docker

Docker manages its own internal storage for images, containers, and volumes — don't reach into Docker's internal data directory by hand. Use Docker's own commands instead:

docker ps                   # running containers
docker logs <container>     # a container's stdout/stderr logs
docker volume ls            # named volumes Docker manages

Editing files under Docker's internal storage location directly can corrupt image and container state in ways that are hard to diagnose — everything you need is reachable through the Docker CLI.

Databases

A database engine's data directory is not meant to be browsed or edited by hand — its internal file format is specific to that engine and version, and manual changes can corrupt it beyond recovery. Use the database's own client tools, proper dumps, and tested backup/restore procedures for anything beyond read-only curiosity about where the files live.

18. Linux vs macOS Quick Comparison

Exact defaults vary by distribution and by macOS version — verify on the specific machine rather than assuming any single row applies everywhere.

19. Five Real-World Troubleshooting Exercises

20. Safe Server-Inspection Checklist

A read-only walkthrough to run on an unfamiliar or misbehaving server before changing anything.

pwd                              # where you are
whoami                           # which user you're running as
uname -a                         # kernel and architecture info
ls -la                           # what's in this directory, including hidden files
df -h                            # disk space per filesystem
df -i                            # inode usage per filesystem
free -h                          # memory usage
ps aux                           # running processes
ss -ltnp                         # listening ports and owning processes (may need sudo)
systemctl --failed               # any services currently in a failed state
journalctl -p err --since today  # today's error-level journal entries

ss -ltnp, systemctl --failed, and full process ownership detail may need sudo to show complete information. free, ss, systemctl, and /proc are not standard macOS tools — use the macOS checklist below instead on a Mac.

pwd
whoami
uname -a
ls -la
df -h
top -l 1 | head -n 15            # one-shot process/resource snapshot
ps aux
lsof -i -P -n | grep LISTEN      # listening ports and owning processes
log show --last 1h --predicate 'eventMessage contains "error"'

21. Dangerous Shortcuts to Avoid

None of the commands below are shown as copyable code blocks on purpose — they're listed here as things to recognize and avoid, not to run.

• Running a sudo command copied from a forum or chat without reading exactly what it does first.
• Reaching for a recursive world-writable permission change (the pattern often written as chmod -R 777) as a generic fix for any "permission denied" error.
• Deleting unfamiliar files or folders under /var, /etc, /usr, /Library, or /System just because you don't recognize them.
• Overwriting the entire /etc/hosts file instead of adding a line to it.
• Hand-editing an automatically generated DNS configuration file and expecting the change to persist.
• Publishing a .env file, a private key, or a raw production log anywhere public.
• Running an application process as the root user "to make a permissions error go away."
• Killing a process by PID without first confirming what it actually is and what depends on it.
• Directly modifying files inside Docker's internal storage or a database engine's data directory.
• Recursively changing ownership starting from / or another very broad path.
• Testing a destructive command for the first time directly on a production server instead of a disposable environment.

22. Quick-Reference Cheat Sheet

For authoritative detail beyond this guide: the Filesystem Hierarchy Standard defines the Linux directory conventions covered above, systemd's own documentation covers service units in full, and Apple's launchd documentation covers LaunchAgents and LaunchDaemons.

23. Frequently Asked Questions

Conclusion

A hosting dashboard is genuinely useful, but it's an interface on top of the same filesystem covered here — the same /etc for configuration, the same /var/log for logs, the same ownership and permission rules underneath. Knowing where those things live, and which commands are safe to run versus which ones change system state, is what turns "the dashboard says something's wrong" into an actual diagnosis: a specific log line, a specific process, a specific permission mismatch.

If you need help deploying, securing, or troubleshooting a production website, the 92 Nodes engineering team can help — from a one-off server issue to ongoing support and maintenance. If you're building or hardening a Linux server, our chmod permission generator and cron expression builder are free tools built around exactly the topics in this guide.