Taste the Rainbow:0.7.8

This page is a guided tour of the source code of the rainbow-0.7.8 release.

Source Code Overview

Please start in my rainbow-0.7.8 tree.

 ./
  |--- README : Standard boilerplate about where work gets done; somewhat dated in this release.
  |--- rainbow.spec.in : spec-file template for building RPMS
  |--- Makefile.package : package-specific variables for use in ../Makefile.fedora
  |--- conf : installation-time configuration files
  |     \--- session-olpc.conf : applies some unusual dbus rules to allow many uids
  |                              to use the same session bus and enables OLPC-specific 
  |                              dbus access checks. When /etc/olpc-security exists, 
  |                              session-olpc.conf is loaded by /usr/bin/sugar 
  | 
  |--- docs : explanations & notes
  |     |--- NOTES : various problems I have encountered and thoughts on how to solve them.
  |     *--- rainbow.txt : a sketch & justification of the current design
  |
  \--- rainbow : source code
        |--- util : functions wrapping frequently used idioms or useful syscalls
        |--- inject.py : logic implementing activity launching
        \--- service.py : dbus service entry-point

Rainbow's Spool

Rainbow maintains uid- and gid-reservations, tables relating bundle-ids, uids, gids, and backing storage for data-dirs, instance-dirs, and tmp-dirs in a directory called the 'spool'. The spool is used at boot time by olpc-configure and rainbow-replay-spool:replay_spool() to regenerate the contents of /etc/passwd and /etc/group and is used at run time to keep track of information about activity launches.

In response to #5033, Rainbow's spool is presently located at /home/olpc/isolation/1. As discussed in that ticket, it is important that the rainbow spool persist across invocations of olpc-update (hence its location inside /home, which olpc-update ignores). Since the location, layout, and semantics of the spool directory are part of Rainbow's public interface to the rest of the system (in particular, to Sugar, the Datastore, and to olpc-update), it was also important that this interface be versioned so that future changes can be more easily made.

The top-level layout of a version 1 spool consists of the following directories:

• uid_pool
• gid_pool
• uid_to_home_dir
• uid_to_instance_dir
• gid_to_data_dir
• bundle_id_to_gid

pool directories store resource reservations. Resource reservations are intended to allow Rainbow to service several requests in parallel.

_to_ directories are key-value maps where the keys are file-names and the values are typically directories or strings. Strings are encoded as symlinks. Some extra information is encoded in the owning-uid and owning-gid of the contents of the _to_ directories; for example, during spool replay, we infer the correspondence between uids and gids by examining the ownership information of the home directories in the uid_to_home_dir table.

• I chose to encode key-value maps into a filesystem layout because these maps support the necessary operations at reasonable efficiency and are readily accessible to any program written using libc.

Activity Launching

Activity launching begins when the rainbow D-Bus service receives a CreateActivity message:

• service.py:Rainbow.CreateActivity()

The CreateActivity handler first attempts to reap zombie children, then it clones() the current process and delegates control to

• inject.py:run()

which interleaves calls to the activity-launching primitives:

• inject.py:strace(),
• inject.py:reserve_elt(),
• inject.py:reserve_credentials(),
• inject.py:grab_home(),
• inject.py:configure_home(), and
• inject.py:launch().

and the assumption-checking procedures:

• inject.py:check_bundle_id(),
• inject.py:check_bundle_path(),
• inject.py:check_argv(),
• inject.py:check_cwd(),
• inject.py:check_spool(),
• inject.py:check_owner(),
• inject.py:check_home_dirs(),
• inject.py:check_home(),

Resource Collection

When the rainbow-daemon D-Bus service starts, it performs a garbage collection pass to reclaim resources allocated in its spool. At present, this garbage collection pass simply deallocates any allocated uids and unlinks their instance and home directories.

• gc.py:active_uid(), test for active uids
• gc.py:gc_uid(), unlink the home dirs and instance dirs of uids which are inactive
• gc.py:gc_spool(), iterate over all available uids

This design is consistent with rainbow-0.7.8's simplifying decision to never reuse uids but is inconsistent with the architectural goal of supporting persistent activity instances. This design may be revisited in future releases.

Developing Rainbow

I develop Rainbow in two basic modes, which I call 'snapshot', 'candidate', and 'release' modes:

• By packaging snapshots of a git clone to try out packaging changes.

 make snapshot

• With locally-built or scratch-built packages, when I'm getting ready to tag a release.

 make release

• With an official release, built with Fedora's Koji build system from sources archived in Fedora CVS.
  • Fedora Package Update HOWTO