# Error in Preinit documentation regarding overlays

**URL:** <https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188>\
**Category:** Talk about Documentation\
**Created:** [April 10, 2020, 7:39pm UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188 "2020-04-10T19:39:21Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![seanmiller](https://forum.openwrt.org/letter_avatar/seanmiller/32/6_449c533f586939b6e5f246632a46421f.png) [@seanmiller](https://forum.openwrt.org/u/seanmiller)\
**Post date:** [April 10, 2020, 7:39pm UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/1 "2020-04-10T19:39:21Z")

</div>

From the [preinit\_mount](https://openwrt.org/docs/techref/preinit_mount) documentation under the **Mount Root Filesystem** section:

```
3. If mtd device rootfs_data has not already been formatted, mounts a tmpfs (ramdisk) as root filesystem, and indicates that further steps should be skipped.
4. Mounts previously formatted jffs2 partition on /overlay and indicates successful mount.
5. Makes successfully mounted /overlay (if it exists) the new root filesystem and moves previous root filesystem to /rom, and indicates to skip further steps.

```

This is only true if a config (sysupgrade.tgz) is NOT preserved across the update. If a config is preserved, step 3 is skipped entirely, and the jffs2 overlay is immediately mounted even if rootfs\_data has not been formatted, instead of being deferred till later in the boot sequence. This is a bug, since it ends up hanging the preinit\_main script while the rootfs\_data partition is being cleaned and formatted for the mounting of the jffs2 overlay (this is why the intended behavior is to first mount the tmp overlay). Machines with large rootfs\_data partitions can lock up and crash because of this.

This bug has been around since 2008, and its a messy one to patch. For now, the official documentation should make note of this to help developers who may see inconsistent behavior across "first boots".

---

<div class="post-metadata">

**Author:** ![seanmiller](https://forum.openwrt.org/letter_avatar/seanmiller/32/6_449c533f586939b6e5f246632a46421f.png) [@seanmiller](https://forum.openwrt.org/u/seanmiller)\
**Post date:** [April 21, 2020, 10:40pm UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/3 "2020-04-21T22:40:55Z")

</div>

I have posted a more detailed description of this bug (and my custom patch for it) in the README for [this github repo](https://github.com/sean-m-miller/OpenWrt-LEDE-patches/tree/master/sysupgrade_ram_overlay_when_preserving_config). The official documentation for overlays and preinit sequences should explain this bug to prevent other developers from going down the same rabbit hole I did. Any feedback would be appreciated.

---

<div class="post-metadata">

**Author:** ![seanmiller](https://forum.openwrt.org/letter_avatar/seanmiller/32/6_449c533f586939b6e5f246632a46421f.png) [@seanmiller](https://forum.openwrt.org/u/seanmiller)\
**Post date:** [May 16, 2020, 10:47pm UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/4 "2020-05-16T22:47:13Z")

</div>

I took the liberty of making additions to the wiki for the Sysupgrade and Preinit and Root Mount and Firstboot Scripts technical references.

Here's another more detailed but still abridged explanation of this bug for any non-believers:

Sysupgrades that preserve volatile files ('sysupgrade -c ...') replace the 0xDEADCODE marker at the rootfs/rootfs\_data boundary with the tar bundle of preserved files. The 0xDEADCODE marker is moved to the start of the next erase block.

Upon the subsequent first boot, the mount\_root utility reads a valid jffs2 file in the first block of rootfs\_data, concludes that the partition has already been formatted, and summons the jffs2 driver. The jffs2 driver finds the 0xDEADCODE marker after the tar file and assumes that now is a safe time to format the rootfs\_data partition and launch the jffs2 overlay.

This is a bug, since preinit\_main hangs while the jffs2 driver formats the partition, which can cause fatal soft lockups on systems with weak cpu and large rootfs\_data partitions. The intended behavior for a first boot is to have mount\_root kick off an intermediate tmpfs overlay, deferring the jffs2 switch until the /etc/init.d/done call.

---

<div class="post-metadata">

**Author:** ![anon50098793](https://forum.openwrt.org/letter_avatar/anon50098793/32/6_449c533f586939b6e5f246632a46421f.png) [@anon50098793](https://forum.openwrt.org/u/anon50098793)\
**Post date:** [May 17, 2020, 2:57am UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/5 "2020-05-17T02:57:17Z")

</div>

> [@seanmiller](#):
>
> preinit\_main hangs while the jffs2 driver formats the partition

interesting...

> keep the 0xdeadc0de marker at the rootfs/rootfs\_data boundary, and writes the file to raw flash in the following erase blocks. Since the 0xdeadc0de is kept where it belongs, upon reboot after the upgrade, mount\_root falls into the FS\_DEADCODE case and launches the /tmp RAM overlay.

Always good to learn more about the boot process... especially the lower level procd-init/preinit mount\_root side of things... and thanks for adding to the wiki + spending the time to dissect all of this!

---

<div class="post-metadata">

**Author:** ![erdoukki](https://forum.openwrt.org/user_avatar/forum.openwrt.org/erdoukki/32/52960_2.png) [@erdoukki](https://forum.openwrt.org/u/erdoukki)\
**Post date:** [September 2, 2021, 9:01am UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/6 "2021-09-02T09:01:45Z")

</div>

Sorry to revive this old topic, is this PreInit problem with Overlay still actual with latest 21.02 ?

---

<div class="post-metadata">

**Author:** ![anon50098793](https://forum.openwrt.org/letter_avatar/anon50098793/32/6_449c533f586939b6e5f246632a46421f.png) [@anon50098793](https://forum.openwrt.org/u/anon50098793)\
**Post date:** [September 2, 2021, 9:12am UTC](https://forum.openwrt.org/t/error-in-preinit-documentation-regarding-overlays/60188/7 "2021-09-02T09:12:47Z")

</div>

ref: [http://lists.openwrt.org/pipermail/openwrt-devel/2020-May/029225.html](http://lists.openwrt.org/pipermail/openwrt-devel/2020-May/029225.html)
