[Sugar-devel] Future of Rainbow + Sugar?

[Michael Stone]

On Tue, Feb 24, 2009 at 08:56:06AM -0800, Carol Farlow Lerche wrote:
>Michael, I think your work on Rainbow is very important, but I think it is a
>bit opaque.  

Carol,

Thanks you for this detailed critique of my documentation efforts to date. One
thing that I've (obviously) struggled with is understanding which audiences
require which sorts of documentation. Your continued assistance untangling this
mess is most appreciated.

>Perhaps you could improve your documentation and as well write
>a tutorial about it that would make it more apparent how much is actually
>implemented and what an activity can do with it.

I'll see what I can cook up.

>So here's an example.  In the Rainbow page on w.l.o you refer to
>http://dev.laptop.org/git?p=security;a=blob;f=rainbow.txt;hb=HEAD for more
>information.  Yet this file has several locutions of the form "This can be
>implemented" and "I believe but have not confirmed" which leave the reader
>unclear as to which services have actually been implemented.  

Do you have an example of documentation which you think really nailed the
divide between "what is needed", "what exists", "how good is it?", and "how do
I use it?"

>Hopping over to Low-Level Activity API the information about security doesn't
>correlate with the permissions referred to in the txt file.

The purpose of the rainbow.txt document was to argue that a design /existed/
which would satisfy enough of the overall goals to be worth pursuing. The
purpose of the Low-Level Activity API documentation is to explain what features
of rainbow exist and can be twiddled by activities.

As it happens, the main feature which exists is primitive filesystem isolation.

>Also you leave ambiguities for the reader by using the passive voice
>throughout these articles.  Changing from passive to active voice answers
>many questions for the reader.  Here is an example:
>
>"All writing to the file system is restricted to subdirectories of the path
>given in the SUGAR_ACTIVITY_ROOT environment variable."
>
>Well, we know that isn't true in all cases, because activities get installed
>by Sugar outside that subtree.  So possibly you mean "Rainbow prevents any
>activity launched by the Sugar shell from writing to any directories except
>those under SUGAR_ACTIVITY_ROOT".   Or do you?  Any exceptions?  What about
>reading files elsewhere in the file system?

For me, these questions are largely answered by the statements, scattered
throughout the system, that rainbow operates by inventing new uids for programs
which it is asked to isolate. However, I can certainly lay things out more
explicitly. Thank you for the reminder about active vs. passive voice.

>I think demystifying Rainbow within a comprehensive document containing a
>section specifically aimed at the concerns of activity developers would go a
>long way toward expanding its use.

What are the concerns of activity developers?

To date, the only one which I have heard clearly articulated is:

   "How do I turn rainbow off for testing?"

which, in fact, is answered in the "For Activity Developers" section.

   http://wiki.laptop.org/go/Rainbow#For_Activity_Developers

Obviously, a couple of people also found it helpful to tweak the isolation
options in detailed ways as discussed in the API docs you cited earlier.

Michael