Skip to main content
OpenWrt’s filesystem is designed around the constraints of embedded devices: small flash storage, no hard disk, and the need to survive power loss without data corruption.

​
OverlayFS: Read-Only Base + Writable Overlay

OpenWrt uses OverlayFS to combine two layers into a single coherent filesystem:
1

Read-only base (/rom)

A squashfs partition containing the base system — the kernel, core binaries, default configuration, and baked-in packages. This layer is compressed and cannot be modified at runtime. It survives a factory reset.
2

Writable overlay (/overlay)

A jffs2 (on NOR flash) or ext4 (on NAND/eMMC/USB) partition that stores all changes made after boot: installed packages, modified config files, new files. This is what opkg writes to.
3

Merged view (/)

The Linux kernel merges the two layers transparently. When you read a file, the overlay is checked first; if absent, the base is used. When you write a file, it goes to the overlay — even if the original lives in /rom.
This design means:
  • A factory reset simply wipes the overlay, restoring the pristine base system
  • The base system takes up minimal flash space due to squashfs compression
  • Write operations are absorbed by the overlay without touching the compressed base

​
Directory Layout

/
├── bin/          # Core user binaries (sh, cat, ls, uci, ...)
├── sbin/         # System binaries (init, procd, sysupgrade, hotplug-call, ...)
├── etc/          # Configuration files
│   ├── config/   # UCI configuration files (network, wireless, firewall, ...)
│   ├── init.d/   # Service init scripts
│   ├── hotplug.d/# Hotplug event handler scripts
│   ├── rc.d/     # Boot order symlinks (S##name, K##name)
│   └── sysupgrade.conf  # Files to preserve across firmware upgrades
├── lib/          # Shared libraries and kernel modules
│   ├── modules/  # Kernel modules (.ko files)
│   ├── functions.sh     # Shell function library
│   └── functions/# Additional shell function modules
├── usr/          # User-space programs and libraries
│   ├── bin/      # Non-essential user binaries
│   ├── sbin/     # Non-essential system binaries
│   └── lib/      # Shared libraries for user-space programs
├── tmp/          # Volatile tmpfs — cleared on every reboot
├── var/          # Runtime state (symlink into /tmp on most builds)
├── www/          # LuCI web interface files
├── overlay/      # The raw writable overlay partition (mounted directly)
└── rom/          # The raw read-only squashfs base (mounted directly)

​
Key Directories

/etc/config/

UCI configuration files. One file per subsystem. Edit these via uci or directly. See UCI System.

/tmp/

tmpfs — lives in RAM, not flash. Used for runtime state (/tmp/resolv.conf, /tmp/.uci/, lock files). Lost on reboot.

/overlay/

The raw writable overlay. Do not write here directly — access it through the merged / view.

/rom/

The read-only squashfs base. You can read default config files from here (e.g., /rom/etc/config/network) to compare against your current settings.

​
Flash Storage Constraints

Most consumer routers ship with 4–16 MB of flash. After the base system, available overlay space is often only 1–4 MB. Check available space before installing packages:
df -h
Devices with 4 MB or less of flash may have limited or no room for additional packages.
Key implications:
  • /tmp (RAM-backed tmpfs) is the correct place for large temporary files
  • Avoid storing logs on flash — use a remote syslog server or log to /tmp
  • Consider extroot (booting from a USB drive or SD card) to expand available space on flash-constrained devices

​
Firmware Upgrades with sysupgrade

sysupgrade is the standard tool for updating OpenWrt firmware. It replaces the base squashfs image while selectively preserving your configuration from the overlay.

​
Basic Usage

# Upgrade from a local firmware file
sysupgrade -v /tmp/openwrt-ath79-generic-mydevice-squashfs-sysupgrade.bin

# Perform an upgrade without preserving any config (factory reset behavior)
sysupgrade -n /tmp/firmware.bin
Always transfer the firmware image to /tmp/ first — sysupgrade will wipe all mounted filesystems including the overlay during the upgrade process.

​
What Gets Preserved

By default, sysupgrade preserves:
  • /etc/ — all configuration files (including UCI configs)
  • Files explicitly listed in /etc/sysupgrade.conf

​
Customizing Preserved Files

Edit /etc/sysupgrade.conf to add files or directories you want to keep across upgrades: 
## Files and directories to preserve during an upgrade.
# /etc/example.conf
# /etc/openvpn/

/etc/openvpn/
/etc/wireguard/
/root/.ssh/authorized_keys
Packages installed at runtime via opkg are not automatically reinstalled after a sysupgrade. Keep a list of your installed packages with opkg list-installed and reinstall them after upgrading.