Skip to content

OverlayFS and root filesystem replacement

Mount sequence

S02datamount.sh mounts the UBI volume named data at /data. S04overlaymount.sh then calls do_overlay_mount /data/overlay.

The stock helper in /etc/overlaymount does three things:

  1. Creates /data/overlay/upper and /data/overlay/work if absent.
  2. Mounts an overlay with lowerdir=/, upperdir=/data/overlay/upper, and workdir=/data/overlay/work at /mnt.
  3. Runs pivot_root, moving /proc, /dev, /tmp, /sys, /run, and /data into the new root.

The previous root remains available at /rom. This is why a modified S89usbgadget.sh can finish by sourcing /rom/etc/init.d/S89usbgadget.sh instead of duplicating it.

Upper-layer semantics

A file at /data/overlay/upper/<path> appears at /<path> in the running system. For example:

  • /data/overlay/upper/usr/bin/adbd → /usr/bin/adbd
  • /data/overlay/upper/etc/init.d/S89usbgadget.sh → /etc/init.d/S89usbgadget.sh
  • /data/overlay/upper/etc/shadow → /etc/shadow

Only the upper layer is writable in the normal stock flow. The lower UBIFS rootfs remains stock until an OTA or a separate image write changes it.

Timing constraints

Files in the upper layer are unavailable until S04 completes. Therefore:

  • S02 and S03 cannot be replaced by an overlay file.
  • S04 itself cannot be replaced by an overlay file.
  • S89 and later scripts can be replaced by an overlay file.

This ordering explains why a data-only jailbreak cannot safely change early UBI recovery or the initial factory-reset hook without modifying the lower rootfs.

Rollback

Removing an upper file reveals the lower stock file. The third-party SSH package narrows this further: its rollback removes owned payload files and leaves unrelated user files in place. By contrast, stock factory reset removes almost the entire data tree, not just overlay customizations.