Confused? Type help

> blog post Customizing the XO image

Customizing the XO image
Wed, 31 Dec 2008 02:32:35

Bryan asked to write something about the XO-customization build process for OLE Nepal. See this post as the second installment of the OLE Nepal deployment series.

So here we go:

First: why do we need to customize a standard XO build? What's wrong with the one supplied by OLPC. Isn't that one tested through and through, and shaved to perfection?

Absolutely. To perfection... Well, almost... But that's besides the point. In a software package as big as a total XO install, it's just about inconceivable that the local requirements overlap a hundred percent with OLPC's. General stuff, like proper support for Unicode keyboard layouts, is... general enough for OLPC to integrate in the standard software. But between us wanting it, and them integrating it in a stable build lies a time-gap to great to wait for. And since we are progressing with local stuff over time, we will have new requirements, when the old ones are integrated. Also we have, or might have requirements that OLPC just isn't interested in or for which it just doesn't have the manpower. And then then we have local configurations like our own update server for Activities or System software, which are scattered around the filesystem.

It's easiest to keep track of all these changes in one place, and we made our own version-controlled Pilgrim build to do take on that burden. For the uninitiated: Pilgrim is the XO filesystem- and image-builder that the folks at OLPC use themselves to build their images.

The biggest benefits of Pilgrim over for example cloning (which we did before) are:

  • All the customizations are contained in scripts, so you don't have to document them, so you can't forget certain steps
  • It forces you to structure the files needed for customization, and while you're at it, you might just as well version-control them
  • You get a customization factory which builds lots of different useful files, like image files, with which you can flash XO's, the .usb files which you can use for machine-local olpc-update-s, and an fs tree which you can use for olpc-update over the network. (note btw that olpc-update preserves user-data).

A rival of Pilgrim is Puritan by the way, written in Python, mostly by Michael Stone, which tries to be more elegant about things like caching, debugging and aborting the build process, and building and customizing the image (and has a cool way to use Git for changes). The need for something like Puritan is there, because Pilgrim IS a big daisy-chain of hacks.

Pilgrim nitty-gritty

So what kind of stuff did we change at OLE Nepal? Perhaps a bit more overview first. Say one would want to get a clean 8.2 image. One checks out Pilgrim, sets it to the right build (be it 8.2 or 703 or whatever), installs some dependencies, make-installs it and enters an incantation on the command-line to let it poop out the .img file and its brothers and sisters. And voila!

But one wants and needs to hack pilgrim a bit. The relevant big ones are the 'pilgrim' file in the root and the one in the streams.d dir, with some auxillery config files sourced in. A few thousand lines of bash scripting, so it's a little dynamically scoped monster.

The first step was to cache all the rpms needed for building the XO local, since downloading them from outside Nepal takes hours and out of the box Pilgrim deletes them. We put them in a local Yum repo, and edit the yum directives  in olpc-development-yum-install.conf accordingly.

Also we revived the automatic installation of activities. Which needed a little bit of love, since last it was used it still put all of them in /usr/share/sugar. Also the installer expects an html file with links to the activities you might want to install, which it wgets to a local directory, after which it takes the latest version of the ones you specified in So you might want to have a script to generate that file from the contents of your activities directory, much like what one needs for the software-updater, but a bit less sophisticated.

Related to the last paragraph, you'll find that the fake mounted image in your build-system will fill up pretty quickly with all that activity content. A bit to quick actually, since the XO uses jffs2 which will compress your fs pretty tight, while pilgrim configures the image on your build system to only one gig. So you might want to set PILGRIM_FS_SIZE_jffs2 and/or PILGRIM_FS_SIZE_devel_jffs2 in to double that amount, which is about right I believe.

Then some customizations on what output would be created was necessary. First of all we want to use olpc-update for updating the XO's from time to time. olpc-update expects a filesystem tree, and a contents file pooped out by pilgrim. With the standard build, pulled from the interwebs, the files aren't put in the right order and place (or, at all really) to be consumed by the olpc-update script present on the XO's.

Also be ware if you want to olpc-update from your own server with a 703 build. Its on-board olpc-update version doesn't have the option to specify another server than the standard. And the development version of olpc-update doesn't contain all the bitfrost files needed by 703, since it doesn't have them itself yet. You can just supplant the bitfrost dir in the development version with the bitfrost dir from a recent XO build ( /usr/lib/python2.5/site-packages/bitfrost works with the one from 8.2 in any case. Should still send a patch). AANNDDDDD, olpc-update pulls in files from the server through rsync://..., so set up a correct rsync daemon conf file in /etc, and start the rsync daemon at startup.

And also the standard pilgrim will make tars out of the fs that you'll rarely need but will take forever to build and take up useless space. So we commented them out.

XO customizations

Then we have to deal with the customizations to the XO itself. The whole reason for this operation.

  1. We had issues with xkb and the traditional Nepali keyboard layout. SCIM solves these issues, so that's what we installed. Everything, except for Write, seems to work for us. Since we're expecting to work that kink out of the cable, we're switching to SCIM. Adding extra packages in Pilgrim is just a matter of adding them to the yum list in and making sure you point to a repo that holds them and their dependencies.

  2. The same holds true for auxillery packages needed by certain activities. We want flash and gnuchess for example, and xpdf, which comes with its own set of dependencies.

  3. Then we have config files that we want to hardwire. So the xo's should update from our schoolservers, not from the wiki or from a location specified by the activities themselves. So we put a file in /etc/olpc-update. Of course you can do that through the gui, but you don't want to do that for every XO that goes through your hands.

The correct way for incorporating these configurations is perhaps making rpm packages, but to me that seems like to much of a hassle for no real gain, so we've got our own for that. Makes it sound nice and official.

Other victims are the scim config dir, the list of default activity favorites, Nepali espeak data and the wpa2 password for the schoolserver if utilized (connecting to aps with wpa2 set is very flaky atm).

Right now we can't just put our images on non-unlocked (so locked) XO's, because we can't sign them (olpc-updating locked XOs to unsigned builds should perhaps not be that hard though, if all one needs to do is tweak the olcp-update script), but apparently OLPC is working on a solution for deployments.

Of course we tested the builds, and they work as expected. So now we've got a nice updater and a nice custom image generator. Pretty sweet!

Oh! And happy New Year, to the ones who celebrate! And also for the ones who don't. No need to be cheap.


on Wed, 31 Dec 2008 02:33:56 Deployment preparation « Tales from the underbelly said:

[...] software infrastructure - a well functioning, customized XO image - a good plan to set up networks for these schools - money - people to go to these schools and have [...]

on Wed, 31 Dec 2008 13:30:44 BryanWB said:

thanks dude, great writeup

Want to comment? Type comment. Type something else to randomy chat a bit. I won't bite.