Early boot

  This page is monitored by the OLPC team.

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 initramfsen.

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).
7. Run the userland init program.

Stage 3: Userland

Perhaps, we're booting a custom userland. In that case, /sbin/olpc_init.py will contain something like:

def run():  
    os.exec('/sbin/init')

and will be imported and run by PID 1.

Perhaps we're booting from a backup OS. Assuming that we've only got one partition to deal with:

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. mount /home /versions/run/$current/home (or /home from home partition)
4. mount /security /versions/run/$current/security (or /security from boot partition)
5. mount /versions /versions/run/$current/versions
6. chroot /versions/run/$current (mount --move ?)

Finally, as suggested above:

if exists '/sbin/olpc_init.py':
  sys.path = ['/sbin'] + sys.path
  from olpc_init import run
  run(<parameters?>)
else:
  exec '/sbin/init --init'

Notes on P_SF_RUN

P_SF_RUN:
 off = allow mod = run from /versions/run/X
 on  = pristine  = run from /versions/run/X

switch on->off: set the unlink flags on /versions/run
      off->on:  create immutably-tagged /versions/run/a,b from /versions/a,b

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>
 /security

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}
 /security
 /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

Upgrade procedure, creating new b from a (w.l.o.g)
 Rainbow: (ATC gives <version> <hash> <priority>)
 -1: Check that /versions/pristine/<hash> doesn't already exist.
  If unpartitioned:
   0. Create new /versions/configs/$c <- where $c = mkdtemp
   1. Create /versions/configs/$c/current -> ../../pristine/`basename(readlink /versions/running)`
   2. Swap /versions/boot to point to configs/$c, save old contents in $old
  If partitioned:
   0-2. Make /boot/alt point to ../`basename(readlink /versions/running)`
  3a. Delete the tree(s) pointed to from /versions/configs/$old which are not pointed to by
     /versions/running (revisit when multiple trees)
  3b. Delete corresponding members of /boot-versions if using a boot partition
  4. Delete /versions/configs/$old.
  4b. Delete corresponding member of /boot-versions if using a boot partition.
  5. Invoke 'olpc-updater <version>'
     in new container:
[MICHAEL WILL REWRITE STARTING FROM HERE]
  NOTE THAT /upgrade must live in same bind-mount as /current if we're to be able to clone it.
  MORE LIKELY THAT RAINBOW WILL CREATE /upgrade FOR US AS CLONE OF /current
           /current (ro-bind mount from /versions/a)
           /upgrade (initially empty)
 OLPC updater:
  6. clone /current to /upgrade
  7. upgrade /upgrade by hook or crook
[END MICHAEL REWRITES]
  8. exit
 Rainbow:
  9. Verify /versions/updates/<hash> matches <hash>
 10. Move /versions/updates/<hash> to /versions/pristine/<hash>
 10b. Create /versions/run/<hash> from /versions/pristine/<hash> according to P_SF_RUN setting
 If unpartitioned:
  11. Make a new config /versions/configs/$d (d = mkdtemp)
  12. Create 'current' symlink to /versions/pristine/<hash>
  13. Create 'alt' symlink to *realpath of* /versions/running
  14. Swing /versions/boot to /versions/configs/$d
       (atomic!  iff we do file move of new symlink)
  15. Delete /versions/configs/$c
 If partitioned:
  11. Copy /versions/pristine/<hash>/boot to boot:/boot-versions/<hash>
  12. Make boot:/boot-versions/<hash>/alt point to what boot:/boot currently points to
  13. Atomically swing boot:/boot to point to /boot-versions/<hash>
 16. If <priority> reboot. (Ask Eben & sugar folks)

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