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

[initrd]
v
python2.5 (pid 1)
v
network_setup(), mount usb/sd, etc
v
antitheft client (ATC)
 olpc.atc.run(fqdn of schoolserver, callback)

(sometime later, or immediately if already activated)
v
callback (as pid 2)
v
mount /sysroot, unmount usb/sd
copy /security/lease to /sysroot/security/lease if first boot (activation)
parse chosen/bootpath, swing /versions/current
v
make minimal userland context (mount --move /sysroot /)
 ideally protect PID 1, RTC <- vserver delta time
v
--------------------> (post-FRS) debian w/ developer key:
|                      def run():
|                        os.exec('/sbin/init')
if booting from a backup:
 If unpartitioned:
 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 partitioned:
 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)`
create /versions/running symlink to pristine/<hash>
xo boot:
$current = basename of readlink of /versions/running (a hash)
mnt /home /versions/run/$current/home         (or /home from home partition)
mnt /security /versions/run/$current/security (or /security from boot partition)
mnt /versions /versions/run/$current/versions
chroot /versions/run/$current (mount --move ?)
v
if exists '/sbin/olpc_init.py':
  sys.path = ['/sbin'] + sys.path
  from olpc_init import run
  run(<parameters?>)
else:
  exec '/sbin/init --init'
---------------------> debian w/o developer key (in run)
|
pyinit + rainbow stuff (take over legacy init's job)
 fork run-parts (/etc/inittab stuff)
 listen for shutdown, etc.
 vserver (- CONTEXT)

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 -> /versions/pristine/<hash> (backwards compatibility; don't use)
 /versions/configs/`mkdtemp`/alt     -> /versions/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 -> realpath(/versions/running)
   2. Swap /versions/boot to point to /versions/configs/$c, save old contents in $old
  If partitioned:
   0-2. Make /boot/alt point to ../`basename /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