Early boot: Difference between revisions

From OLPC
Jump to navigation Jump to search
(→‎Upgrade procedure: Whoops! Bug fixes.)
 
(40 intermediate revisions by 5 users not shown)
Line 1: Line 1:
;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.
{{OLPC}}

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


== Early userland startup steps ==
== Early userland startup steps ==

[initrd]
=== Stage 1: Initramfs ===
v

python2.5 (pid 1)
''See the [http://dev.laptop.org/git?p=users/cscott/olpcrd-rootskel;a=tree;f=src-olpc;hb=HEAD source code] for more details. Instructions are available for [[building initramfs]].''
v

network_setup(), mount usb/sd, etc
# Control is passed to the initramfs' [http://dev.laptop.org/git?p=users/cscott/olpcrd-rootskel;a=blob;f=src-olpc/init;hb=HEAD /init] program.
v
#* This program runs python2.5 as PID 1.
antitheft client (ATC)
# /init executes the [[Theft deterrence protocol|theft deterrence protocol]], checking its 'am I stolen?' flag and looking for a valid [[Firmware Key and Signature Formats#Antitheft/Activation Lease|activation lease]].
olpc.atc.run(fqdn of schoolserver, callback)
# /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.

# Mount /sysroot and unmount our USB or SD devices so that our userland can make its own decisions about how to handle them.
# Fail the boot if we think we're stolen.
# If requested, swing /versions/current to point at the backup OS tree.
#* If necessary, make the filesystem [http://dev.laptop.org/git?p=users/cscott/olpcrd-rootskel;a=blob;f=src-olpc/upfs.py;hb=HEAD upgradable].
# Start the boot animation.
# Make a minimal userland context (e.g. <tt>mount --move /sysroot /</tt>).
# Take any measures that might help protect PID 1 and the real-time clock (RTC).

=== Stage 3: Userland ===

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

If multiple partitions are present:
# Make boot:/boot/alt/alt point to ../`basename(readlink boot:/boot)`
# Make boot:/boot point to boot-versions/`basename(readlinke boot:/boot/alt)`

In either case:

# Make the ''/versions/running'' symlink point to ''pristine/<hash>''
# Set $current equal to the basename of readlink of ''/versions/running'' (which should be a hash)
# 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
# ''chroot'' or ''mount --move'' into /versions/run/$current

Finally, run the userland init program.
# Import and run the ''run()'' function from /sbin/olpc_init.py if it exists; otherwise,
(sometime later, or immediately if already activated)
# Exec /sbin/init.
v
callback (as pid 2)
v
mount /sysroot, unmount usb/sd
copy /security/lease to /sysroot/security/lease if first boot
parse chosen/bootpath, swing /pristine/current
v
make minimal userland context (mount --move /sysroot /)
vserver (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:
1. make new config w/ swapped current and alt
(ie. create a /pristine/configs/XXX w/ new current, alt)
2. then swing /pristine/boot symlink
create /pristine/running
xo boot:
$current = basename of realpath of /pristine/boot/current (a hash)
mnt /home /run/$current/home
mnt /security /run/$current/security
mnt /pristine /run/$current/pristine
chroot /run/$current (mount --move ?) [ actually vserver container here ]
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 ==
== Notes on P_SF_RUN ==
P_SF_RUN:
off = allow mod = run from /run/X
on = pristine = run from /run/X
switch on->off: set the unlink flags on /run
off->on: create immutably-tagged /run/a,b from /pristine/a,b


[[OLPC Bitfrost#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. ([[OLPC Bitfrost#P_SF_CORE|P_SF_CORE]] controls modifications to the pristine versions of OS trees.)
== List of directories in root ==

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

== List of directories in home partition ==
/home
/home
/boot -> /pristine/boot/current
/boot-alt -> /pristine/boot/alt


== Upgrade procedure ==
== Upgrade procedure ==
Upgrade procedure, creating new b from a (w.l.o.g)
Rainbow: (ATC gives <version> <hash> <priority>)
-1: Check that /pristine/tree/<hash> doesn't already exist.
0. Create new /pristine/config/$c <- where $c = mkdtemp
1. Create /pristine/config/$c/current -> realpath(/pristine/running)
2. Swap /pristine/boot to point to /pristine/config/$c, save old contents in $old
3. Delete the tree(s) pointed to from /pristine/config/$old which are not pointed to by
/pristine/running (revisit when multiple trees)
4. Delete /pristine/config/$old.
5. Invoke 'olpc-updater <version>'
in new container:
[MICHAEL WILL REWRITE STARTING FROM HERE]
/current (ro-bind mount from /pristine/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 /pristine/updates/<hash> matches <hash>
10. Move /pristine/updates/<hash> to /pristine/trees/<hash>
11. Make a new config /pristine/configs/$d (d = mkdtemp)
12. Create 'current' symlink to /pristine/trees/<hash>
13. Create 'alt' symlink to *realpath of* /pristine/running
14. Swing /pristine/boot to /pristine/configs/$d
(atomic! iff we do file move of new symlink)
12. Delete /pristine/configs/$c
13. If <priority> reboot. (Ask Eben & sugar folks)


Suppose that we want to create a new OS tree named ''$b'' where ''$b'' cryptographically identifies the [[contents manifest specification|contents]] of the desired OS tree.)
[[Category:software]]

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

=== Create a "safety" boot configuration ===
If we are unpartitioned, then we may:

# Create new /versions/configs/$c <- where $c = mkdtemp
# Create /versions/configs/$c/current -> ../../pristine/$a
# 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 ===

# 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.)''

# Delete /versions/configs/$old.
''(If partitioned and if using a boot partition: delete corresponding member of /boot-versions.)''

=== Acquire the Bits ===

# 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.)
# Modify the contents of ''$d'' by any means that breaks hardlinks before writing through them. When finished,
# Cryptographically [[Olpc-contents|verify]] that ''$b'' identifies the contents of the tmpdir ''$d''.

=== Clean Up ===

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

# Move ''$d'' to ''/versions/pristine/$b''.
# Create ''/versions/run/$b'' from ''/versions/pristine/$b'' according to the current [[OLPC Bitfrost:P_SF_RUN|P_SF_RUN]] setting.

Then, if unpartitioned:

# Make a new config in ''/versions/configs/$e'' with ''mkdtemp''.
# Point its 'current' symlink to ''/versions/pristine/$b''.
# Point its 'alt' symlink to ''(realpath /versions/running)''.
# 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''.)
# Delete /versions/configs/$c
If partitioned:

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

Finally, execute any post-update instructions.

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

==Related pages==
* [[Boot process]] describes what the [[firmware]] does ''before'' the Linux boot sequence.
* [[Installing Debian as an upgrade]]
* [[Manual in-place upgrade]]

[[Category:software]] [[Category:XO startup]]

Latest revision as of 22:31, 27 August 2009

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.



Pencil.png 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.

Pencil.png

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