Olpc-update
Before you begin
This page describes how to update the software image on your laptop. You can either update over the network, or from a USB flash key or disk. You must be using a B3 machine or better, and an update.1 build or better.. If you've got an older machine, use the old Autoreinstallation image instructions. If you're running build 650 or better, you can use these instructions to upgrade over the network, but not from a USB key.
If you want to wipe out your journal and all content you've generated and restore your machine to a pristine state, please use the Activated Upgrade instructions.
Quick Start
First, identify the build to which you want to update your system. To the right is a list of our latest releases. For most people, the numbered build after "Stable" (for example, "650") is what you should update to. If you have a developer key for your machine, and feel adventurous, you can try the latest developer build. Click on the 'devel_jffs2' link beside 'devel' in the box, and use the name at the top of the page, something like "joyride-1452". Ignore all this if you already know what you want to update to!
Now, you'll want to get a root shell on the machine. Open the 'Terminal' activity on your XO, and type:
sudo -s
at the prompt. You may have to type in the password you've set for the 'olpc' account, if you've set one. If you get an error message here, you're using a pre-update.1 build; use
su
instead to get your root shell. Either way, you should end up with a prompt with a # character in it.
Now you have two choices: update over the network, or download the build onto a USB key and update from that.
Network upgrade
At your root prompt, type:
olpc-update <build-no>
where <build-no> is the name of the build you would like. For example:
olpc-update 653
for a stable build, or (if you've got a developer key)
olpc-update joyride-1453
When olpc-update is finished, you should reboot to start using your new build.
The update mechanism preserves the build from which you ran the updater as an "alternate" image from which you can boot. To swap the "primary" and "alternate" images, hold the 'O' gamepad key during boot.
USB upgrade
At your root prompt, type:
olpc-update --version
The first line of the response should be something like:
olpc-update 2.0, Copyright (C) 2007 One Laptop Per Child Association, Inc.
If it does not say that you are using at least version 2.0 of olpc-update, you will need to upgrade olpc-update before continuing.
Now use the links in the "latest releases" box above to download two files to the top directory of your USB key: osXYZ.usb and osXYZ.toc, where XYZ is the numeric part of the build you are updating to. For example, if you are updating to build 650, the files would be named os650.usb and os650.toc. If you are updating to build joyride-1452, the files would be named os1452.usb and os1452.toc.
Insert your USB key with these files on it into your XO. At your root prompt, type:
olpc-update --usb
When olpc-update is finished, you should reboot to start using your new build.
The update mechanism preserves the build from which you ran the updater as an "alternate" image from which you can boot. To swap the "primary" and "alternate" images, hold the 'O' gamepad key during boot.
More information
This method of updating from one operating system (OS) build to another is experimental. It works by transferring only the differences across the internet link from an updates server. This makes updating easier, mostly quicker, and almost always with less data transfer.
As an example of the data efficiency gain,
- An autoreinstallation from OS build 602 to 603 would normally take about 279Mb of download data, whereas olpc-update takes 16Mb of download data,
- An autoreinstallation from OS build 603 to 608 would normally take 262Mb of download data, whereas olpc-update takes 6.5Mb of download data,
- An olpc-update from OS build 602 to 625 takes 33Mb of download data.
The time efficiency gain is less easy to characterise. It depends on the speed of the internet link, the speed of the updates server, and whether the autoreinstallation image needs to be downloaded. An olpc-update from 602 to 603 cost under 17 minutes.
The current updates server is updates.laptop.org.
Usage
In summary:
- Be connected to the internet,
- Log in as root,
- Type olpc-update NNN where NNN is the build number,
- Wait for the update to complete,
- Reboot.
Be Connected
Ensure the laptop or the emulator is able to access the internet, by being connected an an access point, or via the mesh, or using an ethernet connection.
Be Root, with correct Environment Variables
From the Sugar Developer's Console:
$ su - # whoami root
From SSH or the Virtual Terminal:
# whoami root
Run olpc-update
Normally you only need to run olpc-update with a build number, like this:
# olpc-update 613
There are other options. For example:
# olpc-update --help
Usage:
Update to build-<id>: olpc-update [-r] [-s SERVER] <id>
Update to <url>: olpc-update [-r] -u <toc url> <tree url>
Find a target: olpc-update [-s SERVER] -l
Get a changelog: olpc-update [-s SERVER] -c <id>
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-l, --list-targets show available update targets
-c, --changelog show changelog for build NUM
-s SERVER, --server=SERVER
override the rsync base url (e.g. rsync://my.server)
-u, --urls give raw contents-file and tree urls(e.g.
rsync://my.server)
-r, --reboot reboot after update
Update Targets
There are several update targets available. There is usually one for each operating system build, and there are others for test builds and for Debian. To get a list of the available builds, use the command:
# rsync rsync://updates.laptop.org | sort
Latest Version
Q: What is the latest version of the updater?
A: the most-recent released version of the updater is at:
# wget http://dev.laptop.org/~mstone/olpccontents-latest.rpm # wget http://dev.laptop.org/~mstone/rainbow-latest.rpm
Use this on build 602 for example before attempting an update to 625.
A: the most-recent unstable version of the updater is at:
# wget http://dev.laptop.org/~mstone/pyvserver.rpm # wget http://dev.laptop.org/~mstone/rainbow.rpm
These packages can be installed with something like:
# rpm --upgrade --force *.rpm
You can do this on any build.
Update Using Another Laptop
Q: How can I re-use the bits for multiple laptops, using a laptop?
A: Imagine that you have two laptops, one is called SOURCE and the other TARGET.
On the SOURCE laptop, add an rsyncd.conf file to /etc:
[contents]
path = /versions/contents
uid = root
gid = root
[pristine]
path = /versions/pristine
uid = root
gid = root
Then start rsync --daemon there.
On the TARGET laptop, use rsync to check access and identify the build that is available:
SOURCE=10.0.0.1
rsync rsync://${SOURCE}/contents
Where 10.0.0.1 is the IP address or domain name of the SOURCE laptop.
Take note of the build identifier. It will be a hexadecimal hash, 64 characters long.
On the TARGET laptop, use olpc-update to upgrade or downgrade to that build:
SOURCE=10.0.0.1
BUILD=dd44...597f
olpc-update -u rsync://${SOURCE}/contents/${BUILD} rsync://${SOURCE}/pristine/${BUILD}/
Note that the extra slash on the end of the second argument is needed.
Several laptops can all be updated in the same way from one source.
Setting Up A Local Updates Server
Q: How can I re-use the bits for multiple laptops, using a server?
A: This feature is available for testing but is not yet released. Also, no one that I know of is yet publishing their own builds.
In any case, in very recent versions of the updater, one may specify something like
# olpc-update -s rsync://teach.laptop.org -l
to see a list of builds available from teach.laptop.org.
Note: In the future, it may be possible to use this feature to perform incremental updates from a USB stick or SD card, e.g. by giving something like
# olpc-update -s /mnt/mmcblk0p1 613
Please give feedback on whether you would use such an update target.
- manifest was an old name for contents, and was present for builds 602 603 605 607 608 and omitted from builds 609 610 611 612,
- updates.laptop.org generates an AUTH request, so an ident server on the system running rsync may be helpful, Debian package oidentd is sufficient,
Source Repository
Q: Where is the source?
A: The source repo is http://dev.laptop.org/git/users/mstone/security
The branch you want is currently called updater, though this will likely change in the future. There are five important files in the repository. They are:
rainbow/sbin/olpc-update rainbow/sbin/olpc-update-rsync rainbow/rainbow/update.py rainbow/rainbow/launch/targets/update.py rainbow/rainbow/launch/stages/update.py
A: More recent work is being done on the master branch.
