Olpc-update

  This page is monitored by the OLPC team.

olpc-update is a command-line program to update your system software. It only copies the differences between your current version and a new OS image, preserving your files (journal) and activities you have installed.

/* WARNING: While technically true, the files are still on the system, the update (using the USB instructions) is not an update in the commonly understood sense. It installs a new copy of the OS minus activities. To get to your activities you must hold the 'O' game pad key during power-on and boot to the previous installation. */

It can access the new version from the internet, or from files you place on a USB drive.

See Updating the XO for other update scenarios, such as the step-by-step (but destructive) no-fail update.

WARNING

Do not update your OLPC when your battery is not fully charged. The firmware update will only complete if your battery is detected with a charge. Otherwise you will get a "battery" not detected error and the laptop will not finish powering up after the update. If your battery does not recharge you can not use the battery recovery tools, and you will need to purchase a new battery to boot your XO again.

Before you begin

Second year G1G1 (Nov 17 to Dec 31 2008 donations) recipients received Build 656 or Release 8.2.0 release. First year G1G1 (Nov 12 to Dec 31 2007 donations) recipients received C2 (also known as MP) hardware running Builds 650, 653 or 656. For pre-production (prior to November 2007) equipment : You must be using a B3 machine or better, and build 650 or better of the system software

If you have problems, you can try booting a previous configuration before attempting an update; see #Restoring a previous OS image.

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 Clean-install procedure. That works even if you have an older machine or older build.

What version do I have now?

To tell what version of the system software you have, follow How to check the OS and firmware versions.

What version is available?

You need to identify the "build" to which you want to update your system. The latest stable system software release is

13.2.11 || 2020-01-29

Most users should update to that build.

All releases currently available are listed on the Release notes page. Before upgrading to any release, read its release notes carefully.

Other builds

+	Software
XO
	13.2.11	2020-01-29
XS
	xs-0.7	2012-02-20

There are later builds in various stages of development, see OS images for more background. These are likely to be unstable and you will probably need to request a developer key to install them.

To the right is a list of our latest releases. If you have a developer key for your machine, and feel adventurous, you can try the candidate or a developer build. For the latest developer build, click on the 'jffs2' link beside 'devel' in the box, and use the name at the top of the page; it will be something like "joyride-2452".

Performing an update

Simple online update

Your XO Journal will remain intact with this update method. Note: You should always back up important files; e.g., to a USB flash drive or to a school server before updating, just in case.

olpc-update is designed to work with even the worst internet connections, and will do no harm if it is interrupted during download. If you don't like your new software update, you can revert to the older version by holding down the O key on the game pad (between the right speaker and the power button) when you next turn the laptop on.

To manually upgrade your machine when a new version is released:

1. Plug the XO into an electrical outlet
2. Connect to the internet. If you are upgrading because you have a WPA hotspot at home, you might want to go to a Public Hotspot to connect to the internet for an online upgrade, such as a T-Mobile hotspot or a local libary.
   Firewall note: olpc-upgrade requires outgoing TCP PORT:873 to be unfiltered by the hotspot's firewall. In otherwords if the laptop has functional-access to the internet but olpc-upgrade returns the message "I don't think you're connected to the internet." check the hotspot's firewall is not blocking the outgoing TCP Port 873.
3. Start the Terminal Activity (or if you cannot do so, open a console) and type the following (press the Enter key after it):

sudo olpc-update build-number 

For example:

sudo olpc-update 802

Where

• build-number is the number of the build to be updated to. Released versions are simple numbers; development versions are prefixed numbers like 'joyride-2310' or '8.2-765'. The latest stable build is 13.2.11 || 2020-01-29.

If you get an error saying "sudo: command not found", type "su -", press enter and then "olpc-update build-number" and press enter. For example:

su -
olpc-update 802

If you get an error saying "olpc-update: command not found", try adding the /usr/sbin path to the command. For example:

/usr/sbin/olpc-update 802

If olpc-update successfully connects to the update server, some messages should display

Downloading contents of build build-number
Updating to version hash xxxx
Making clean /versions/updates/...
Trying irsync_pristine update from rsync://updates.laptop.org/build-build-number
- Cleaning tree.
- Fetching contents.
- Performing incremental rsync.
Verifying update.
Installing update in /versions/{pristine,run}/xxxx

Where xxxx is a version-specific number.

The olpc-update program uses several methods to update. If "irsync_pristine" fails, it will try "irsync dirty update", and then try "Performing full rsync". As long as the last method completes without errors, you're fine. This process may take more than thirty minutes.

When the process is complete, you need to reboot, unless you supplied the -r option to olpc-update. If the new build includes newer firmware, then your XO will reboot twice. When the XO restarts the update will be complete.

If you want to revert to the previous build, see Restoring a previous OS image.

Note

• When upgrading from build number 656 to 703, the upgrade may fail due to transient rsync errors, for example "rsync error: error in rsync protocol data stream (code 12) at io.c(824) [receive r=2.6.9]" and "rsync error: some files could not be transferred (code 23) at main.c(1385) [receiver=2.6.9]". In that case, retrying the command often allows the upgrade to complete successfully.
• When upgrading from build 650, 653, or 656, you must install activities separately. See Update.1 Software Release Notes for details. In 8.2-series builds (765 and higher), the software update control panel will allow you to update your activities after you upgrade.

Simple offline update

for new users
illustrated guide to updating using a USB stick

You copy special files for the new build to a USB flash drive, and then tell olpc-update to update the system image from USB.

Prepare a USB flash drive

Your USB flash drive needs to be writable from the computer on which you'll download the files, and readable from a running XO (as /media/YourDriveName). That probably means your USB flash drive should be formatted as FAT or FAT32, and only contains one partition. Most ordinary USB flash drives are set up this way, except "U3" flash drives which may not work. Remove U3 with uninstall software from http://www.u3.com/uninstall

Download .usb and .toc files onto USB

Insert a USB flash drive into a computer connected to the Internet.

Follow one of the build links in the "latest releases" box above. You need to download two files from the build's directory to the top directory of your USB flash drive: osNNN.usb and osNNN.toc, where NNN is the numeric part of the build you are updating to. For example, if you are updating to build 711, the files would be named os711.usb and os711.toc; if you are updating to build joyride-1452, the files would be named os1452.usb and os1452.toc. Right-click (Ctrl-click for Mac) on each of the two names and choose "Save Target As" ("Save Link As" for Firefox). Save both files to the USB flash drive. Do not open the files.

USB update

1. Plug the XO into an electrical outlet
2. Insert your USB flash drive with the .toc and .usb files on it into your XO.
3. Start the Terminal activity (or if you cannot do so, open the console), and enter:

/usr/sbin/olpc-update --version

The first line of the response should be something like:

olpc-update 2.12, Copyright (C) 2007 One Laptop Per Child Association, Inc.

If you don't even have the --version option, (this includes all G1G1 laptops shipped before July 2008) or if it does not say that you are using at least version 2.0 of olpc-update, you will need to update olpc-update before continuing.

At the terminal prompt, type:

sudo /usr/sbin/olpc-update --usb

and press enter.

If you get "sudo: command not found" errors, enter

su -
/usr/sbin/olpc-update --usb

When olpc-update is finished, reboot to start using your new build.

As with other update sources, the update mechanism preserves the build from which you ran the updater as an "alternate" image from which you can boot, see #Restoring a previous OS image.

Restoring a previous OS image

The update mechanism preserves the build from which you ran the updater as an "alternate" image from which you can boot. This means you can restore to a previous version of your OS if, after your update, your image isn't working properly.

To swap the "primary" and "alternate" images:

• shutdown the XO
• power-on while holding down the ' O ' gamepad key.
• release the key when you're instructed to do so
• check the OS version

More information

The olpc-update script works by transferring only the differences between builds from a USB flash drive or 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,

• A full reinstallation from OS build 602 to 603 would normally take about 279Mb of download data, whereas olpc-update takes 16Mb of download data,
• A full reinstallation 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 characterize. It depends on the speed of the internet link, the speed of the updates server, and whether the update was able to use its server-friendly efficiency mode. An olpc-update from 602 to 603 took under 17 minutes.

The current updates server is updates.laptop.org.

Root access

To actually update your XO, you must run the olpc-update command as the root user (you can check its version and get usage help without being root).

Entering sudo olpc-update options is the preferred way to run it as the root user. However, sudo is not available in some builds, and in sudo does not work in some builds which require a password until you become "root". Here are some ways to become the root user:

• In later versions of the Terminal Activity you can become "root" by pressing the "#_" icon at the top of the terminal screen.
• In builds earlier than 703 you may need to instead enter su -l.
• In the console you can login as root.

The root prompt ends with #. Then you can just enter olpc-update options.

Updating olpc-update

If you are using an old build, olpc-update might not be recent enough to let you update via USB, or update to a build containing a library. Here's how to upgrade olpc-update to allow you to use the processes described above.

From a root prompt on your XO:

# wget -P /tmp/X -r -np -nd http://dev.laptop.org/~cscott/olpc-update/
# rpm -Uvh --force /tmp/X/olpc*.rpm

Or, if you are working without a internet connection on the XO-1, go to http://dev.laptop.org/~cscott/olpc-update/ and download both files to your USB drive. Then with the USB drive inserted into the XO-1:

# rpm -Uvh --force /media/your_USB_Drive_Name/olpc*.rpm

Now:

# olpc-update --version

should tell you that you have version 2.7 or higher of olpc-update. Note that the minor version number should not be interpreted as a decimal fraction; for instance, 2.17 is a later version than 2.7.

Usage

In summary:

• Be connected to the internet.
• In a terminal, become root, or type sudo before "olpc-update"
• Type olpc-update NNN where NNN is the build number or name-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.

Run olpc-update

Normally you only need to run olpc-update with a build number, like this:

# olpc-update 703

or

# olpc-update joyride-1779

There are other options. For example:

# olpc-update --help

Usage: 
 olpc-update [options] --hints hints-file
 olpc-update [options] --latest stream-name
 olpc-update [options] [-rf] build-number
 olpc-update [options] [-rf] --usb
 olpc-update --version
 olpc-update --help

For example:
 olpc-update 630
 olpc-update joyride-2200
 olpc-update --latest joyride

For convenience, 'olpc-update joyride-latest' is treated as an alias for
'olpc-update --latest joyride'.

Options:
  -h, --help     show this help message and exit
  -f, --full     skip incremental update attempt.
  --force        force update to an unsigned build.
  -r, --reboot   reboot after a successful update.
  -p, --poweroff poweroff after a successful update.
  --hints=FILE   name of json-encoded hints dictionary identifying the desired
                 new version.
  --latest=STREAM update to the version named by the given update stream.
  -u, --usb      update to new build on inserted USB stick.
  -v             display verbose progress information; repeat for more verbose
                 output.
  -q, --quiet    don't output anything; use exit status to indicate success.
  --version      display version and license information.

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 partial list of the available builds, use the command:

$ rsync rsync://updates.laptop.org | sort

Note that this does not list all the builds available. Instead, this just lists the builds which have been requested recently; the server loads new builds on demand and garbage collects old builds.

You can use the --latest option to olpc-update with one of the build streams listed at https://activation.laptop.org/streams/ -- for example:

$ sudo olpc-update --latest unstable

(But first <trac>7676</trac> needs to be fixed.)

You will need a developer key to install any of the builds below:

• Joyride: the latest joyride build number can generally be found at the top of the build announcer page.
• Debian: Installing Debian as an upgrade (unmaintained)
• Ubuntu/Edubuntu: (unmaintained, currently broken: <trac>7012</trac>)

Advanced usage

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, create an appropriate 'hints' file:

export SOURCE=10.0.0.1
export BUILD=dd44...597f
python2.5
>>> import os, bitfrost.util.json as json
>>> hints = ('%(BUILD)s' % os.environ, 'normal', [('rsync','rsync://%(SOURCE)s/pristine/%(BUILD)s' % os.environ)])
>>> open('hints.json','w').write(json.write(hints))
>>> exit()

Now on the TARGET laptop, use olpc-update to upgrade or downgrade to that build:

sudo olpc-update --hints hints.json

Several laptops can all be updated in the same way from one source with the same 'hints.json' file.

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.

The source code for the updates server is available at:

http://dev.laptop.org/git/users/cscott/upgrade-server

Basic installation instructions can be found at Upgrade Server.

Source Repository and Specification

Q: Where are the specifications?

A: See the XO updater article.

Q: Where is the source?

A: The source repository for olpc-update is

http://dev.laptop.org/git/users/cscott/olpc-update

It also uses code from the olpc-contents package:

http://dev.laptop.org/git/users/cscott/olpc-contents