Early boot

This page describes things that happen early in the boot process. Basically this is the startup of the first process that runs. This is the documentation for the peculiarities that allows for this process to run without things that most processes expect when they start running.

  For Developers

NOTE: The contents of this page are not set in stone, and are subject to change! This page is a draft in active flux ... Please leave suggestions on the talk page.

Draft of early boot upgrade/init procedures designed by Michael Stone and C. Scott Ananian.

Early userland startup steps

Stage 1: Initramfs

See the source code for more details. Instructions are available for building initramfs.

1. Control is passed to the initramfs' /init program.
   • This program runs python2.5 as PID 1.
2. /init executes the theft deterrence protocol, checking its 'am I stolen?' flag and looking for a valid activation lease.
3. /init will decide whether to fail the boot.
   • If the boot should stop, then a graphical error message will be displayed.
   • If the boot should continue, then /init will fork and will prepare to execute the userland init program.

Stage 2: NAND

Since /init forked, we are now running as PID NNN rather than PID 1.

1. Mount /sysroot and unmount our USB or SD devices so that our userland can make its own decisions about how to handle them.
2. Fail the boot if we think we're stolen.
3. If requested, swing /versions/current to point at the backup OS tree.
   • If necessary, make the filesystem upgradable.
4. Start the boot animation.
5. Make a minimal userland context (e.g. mount --move /sysroot /).
6. Take any measures that might help protect PID 1 and the real-time clock (RTC).

Stage 3: Userland

1. make new config w/ swapped current and alt
   • (ie. create a /versions/configs/XXX w/ new current, alt)
2. then swing /versions/boot symlink

If multiple partitions are present:

1. Make boot:/boot/alt/alt point to ../`basename(readlink boot:/boot)`
2. Make boot:/boot point to boot-versions/`basename(readlinke boot:/boot/alt)`

In either case:

1. Make the /versions/running symlink point to pristine/<hash>
2. Set $current equal to the basename of readlink of /versions/running (which should be a hash)
3. Make appropriate bind-mounts:
   • mount /home /versions/run/$current/home (or /home from home partition)
   • mount /security /versions/run/$current/security (or /security from boot partition)
   • mount /versions /versions/run/$current/versions
4. chroot or mount --move into /versions/run/$current

Finally, run the userland init program.

1. Import and run the run() function from /sbin/olpc_init.py if it exists; otherwise,
2. Exec /sbin/init.

Notes on P_SF_RUN

P_SF_RUN is a Bitfrost protection intended to control when running programs may modify the 'run' image of the current OS tree. (P_SF_CORE controls modifications to the pristine versions of OS trees.)

Suppose we're going to boot an OS tree named X.

• When P_SF_RUN is switched off, we should make /versions/run/X copy-on-write.
• When P_SF_RUN is switched on, we should boot from an immutable copy of the pristine version of X.

These rules mean that:

• If P_SF_RUN is off then we should allow modifications.
• If P_SF_RUN is on then we should prohibit modifications.

List of directories in security partition

 /security

List of directories in boot partition

 /boot -> boot-versions/<hash>
 /boot-alt -> boot/alt
 /boot-versions/<version>/{runos.zip,runrd.zip,etc}
 /boot-versions/<version>/alt -> ../<alternate version>

List of directories in root partition

 /sys, /proc, /ofw   vfs
 /versions/pristine/{hashes}
 /versions/contents/{hashes}  (contents files for the corresponding pristine tree)
 /versions/configs/`mkdtemp`/current -> ../../pristine/<hash> (backwards compatibility; don't use)
 /versions/configs/`mkdtemp`/alt     -> ../../pristine/<hash> (backwards compatibility; don't use)
 /versions/boot -> configs/<something> (backwards compatibility; don't use)
 /versions/running -> pristine/<hash>  (version we booted from; hash matches /boot symlink from boot partition)
 /versions/updates/<hash>   (temporary space for updates, preserved in case update
                             net connection drops & updater is restarted)
 /versions/run/{hashes}
 /boot -> versions/boot/current/boot (backwards compatibility; don't use)
 /boot-alt -> versions/boot/alt/boot (backwards compatibility; don't use)

List of directories in home partition

 /home

Upgrade procedure

Suppose that we want to create a new OS tree named $b where $b cryptographically identifies the contents of the desired OS tree.)

1. Check that /versions/pristine/<hash> doesn't already exist.
2. Let $a = `basename(readlink /versions/running)`.

Create a "safety" boot configuration

If we are unpartitioned, then we may:

1. Create new /versions/configs/$c <- where $c = mkdtemp
2. Create /versions/configs/$c/current -> ../../pristine/$a
3. Swing /versions/boot to point to configs/$c, save old contents in $old

(If partitioned: Make /boot/alt point to ../$a.)

Afterward, we should:

Make Space

1. Delete the tree(s) pointed to from /versions/configs/$old which are:
   • not pointed to by /versions/running
   • not pointed to by a symlink in /versions/sticky

(If partitioned and if using a boot partition: delete corresponding members of /boot-versions.)

1. Delete /versions/configs/$old.

(If partitioned and if using a boot partition: delete corresponding member of /boot-versions.)

Acquire the Bits

1. Shallow-copy /versions/pristine/$a into a tmpdir $d on the same file system. (To shallow-copy a tree is to copy its directory structure, then to hardlink all its inodes into the new empty tree.)
2. Modify the contents of $d by any means that breaks hardlinks before writing through them. When finished,
3. Cryptographically verify that $b identifies the contents of the tmpdir $d.

Clean Up

If verification fails, destroy $d and return failure. Otherwise:

1. Move $d to /versions/pristine/$b.
2. Create /versions/run/$b from /versions/pristine/$b according to the current P_SF_RUN setting.

Then, if unpartitioned:

1. Make a new config in /versions/configs/$e with mkdtemp.
2. Point its 'current' symlink to /versions/pristine/$b.
3. Point its 'alt' symlink to (realpath /versions/running).
4. ATOMICALLY swing /versions/boot to /versions/configs/$e.
   • (To atomically swing a symlink $s, make a new symlink $t on the same filesystem pointing to the desired location and then rename $t on top of $s.)
5. Delete /versions/configs/$c

If partitioned:

1. Copy /versions/pristine/$b/boot to boot:/boot-versions/$b
2. Make boot:/boot-versions/$b/alt point to (realpath boot:/boot).
3. Atomically swing boot:/boot to point to boot:/boot-versions/%b

Finally, execute any post-update instructions.

Open Questions

1. Are thawed trees persistent?
   1. when I use a frozen tree?
   2. when I upgrade
2. Is "thawness" global? Or per-OS-version?
3. Can thawed trees be frozen for temporary read-only use?
4. Space limits for upgrader?
5. UI for:
   1. P_SF_RUN
   2. which image you boot (esp if more than two)
   3. Rest of security UI
6. Configuration versioning / globalness
   1. do security settings persist across updates
   2. do we inherit a security configuration from the 'old' version when upgrading?
7. Loadable kernel modules
   1. Bind-mount /lib/modules read-only? (Doesn't fix the problem, really)

Related pages

• Installing Debian as an upgrade
• Manual in-place upgrade