Olpc-update: Difference between revisions
(→USB upgrade: various cleanups) |
m (tweak grammar of summary sentence) |
||
(101 intermediate revisions by 31 users not shown) | |||
Line 1: | Line 1: | ||
{{Translations}} |
|||
{{TOCright}} |
{{TOCright}} |
||
[[olpc-update]] is a command-line program to update your system software. It preserves your [[Journal|files (journal)]] and [[activities]] you have installed. |
|||
olpc-update can download the new version from the internet, or from a file on a [[USB drive]]. See [[Updating the XO]] for other update scenarios. |
|||
The old software version is erased the first time the new version is booted, but this can be prevented. |
|||
(Certain really old builds, like 656, can't olpc-update to recent builds. Check the release notes of a recent build to find out if olpc-update can be used from a really old build. If not, then you must install the recent build afresh.) |
|||
== What version do I have now? == |
== What version do I have now? == |
||
Line 6: | Line 14: | ||
To tell what version of the system software you have, follow [[How to check the OS and firmware versions]]. |
To tell what version of the system software you have, follow [[How to check the OS and firmware versions]]. |
||
== |
== Disk space requirements == |
||
The latest stable system software release is |
|||
: {{Latest_Releases/stable}} |
|||
Due to its fail-safe design, olpc-update must store all of the changed files in the release that you are updating to, alongside the existing release that you are running, for a short time. olpc-update cannot complete if there is not enough disk space available. |
|||
There are later "builds" in various stages of development, see [[OS images]]. |
|||
These are likely to be unstable and you will probably need a [[developer key]] to install them. |
|||
If upgrading between minor releases within the same release series or between development releases in the same development stream, the space required will be low. However, if upgrading from one major release to another (e.g. [[10.1.3]] to [[11.2.0]]), you will probably need more than 300mb of disk space available (even though the upgrade process will finish with approximately the same amount of disk space available). |
|||
Before upgrading to any release, read its release notes carefully. |
|||
== |
== How to upgrade == |
||
</noinclude><includeonly>:''Main article: [[olpc-update]]''<p></includeonly>'''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. |
|||
See the [[Releases]] page for the releases that are available. The release notes for each recent release will explain exactly how to use olpc-update to update to that particular version. Be sure to read the release notes before starting the update. |
|||
To manually upgrade your machine when a new version is released: |
|||
The instructions below are generic. |
|||
# Plug the XO into an electrical outlet |
|||
# Connect to the internet. If you are upgrading because you have a WPA [[hotspot]] at home, you might want to go to a [[hotspot#Public Hotpots|Public Hotspot]] to connect to the internet for an online upgrade, such as a [[T-Mobile]] hotspot or a local libary. <br>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. |
|||
# Open the '''[[Terminal Activity]]''' [[Image:Activity-terminal.svg|35px]] or a console and type the following (press the Enter key after it): |
|||
=== Simple online update === |
|||
From build 703 or later use the sudo command as described here. For earlier builds, see the note below. <br> |
|||
Note: You should always back up important files; e.g., to a USB drive or to a school server before updating, just in case. |
|||
</noinclude><includeonly>:''Main article: [[olpc-update]]''<p></includeonly>'''olpc-update''' is designed to work with even the worst internet connections, and will do no harm if it is interrupted during download. It will resume from where it left off, without having to download what it has already downloaded. |
|||
sudo olpc-update ''build-number'' <!-- reboot, verbose --> |
|||
To manually upgrade your machine when a new version is released: |
|||
For example: |
|||
sudo olpc-update 708 |
|||
# Plug the XO into an electrical outlet |
|||
Where |
|||
# [http://www.laptop.org/en/laptop/start/connecting.shtml Connect to the internet]. If you are upgrading because you have a WPA [[hotspot]] at home, you might want to go to a [[hotspot#Public Hotpots|Public Hotspot]] to connect to the internet for an online upgrade, such as a [[T-Mobile]] hotspot or a local libary. <br>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. |
|||
* <tt>build-number</tt> is the number of the build to be updated to. |
|||
# Start the '''[[Terminal Activity]]''' [[Image:Activity-terminal.svg|35px]] (or if you cannot do so, open a [[console]]) and type the following (press the Enter key after it): |
|||
sudo olpc-update ''build-identifier'' |
|||
Note: sudo does not work with some builds which require a password until you become "root". You can become "root" by pressing the "#_" icon at the top of the terminal screen. In builds earlier than 703 you may need to type "[[su -l]]" (note it's lower case "L" not the number "1") and then "olpc-update ''build-number''" instead. |
|||
The ''build-identifier'' is normally identified on the [[Releases|release notes]] of the release you are upgrading to. Historically, build identifiers were simple numbers (e.g. 802), for newer builds prefixes are used to separate between the different laptop models (e.g. 10.1.3_xo1.5-860). |
|||
:* The latest stable build is {{Latest_Releases/stable}} |
|||
If you get an error saying "command not found", type "su -", press enter and then "olpc-update ''build-identifier''" and press enter. For example: |
|||
:* Note that in '''builds 700 and above''', '''you must install activities separately'''. See [[OLPC Update.1 Software Release Notes|Update.1 Software Release Notes]] for details. In 8.2-series builds, you can use the software update control panel to do this. |
|||
su - |
|||
/usr/sbin/olpc-update 802 |
|||
If |
If olpc-update successfully connects to the update server, some messages should display |
||
Downloading contents of build ''build- |
Downloading contents of build ''build-identifier'' |
||
Updating to version hash ''xxxx'' |
Updating to version hash ''xxxx'' |
||
Making clean /versions/updates/... |
Making clean /versions/updates/... |
||
Line 54: | Line 59: | ||
Where ''xxxx'' is a version-specific number. |
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 <code>-r</code> option to <code>olpc-update</code>. |
|||
This process may take more than thirty minutes. |
|||
When the process is complete, you need to [[reboot]], unless you supplied the <code>-r</code> option to <code>olpc-update</code>. |
|||
If the new build includes newer [[firmware]], then your XO will reboot twice. |
|||
When the XO restarts the update will be complete. |
When the XO restarts the update will be complete. |
||
After updating, you should run the Sugar activity updater from the control panel. If not, you may find that various activities are not working. |
|||
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. |
|||
===Simple offline update=== |
|||
Note |
|||
* When upgrading from build number 656 to 703, the upgrade may fail due to random 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, the following command, in place of "olpc-update 703" above, has allowed the upgrade to complete successfully: |
|||
sudo olpc-update -f 703 |
|||
Unless you are running a very old release, you can also download the new release data onto a USB disk from an internet-connected computer, and then use olpc-update on an XO to perform the update, without requiring any internet connection. |
|||
If that doesn't work, try this: |
|||
==== Prepare a USB drive ==== |
|||
su - |
|||
olpc-update -rv xxx |
|||
Your USB drive needs to be writable from the computer on which you'll download the files, and readable from a running XO (as <tt>/media/''YourDriveName</tt>). |
|||
<noinclude> |
|||
*(Note that ''/media'' changes to ''/run/media/olpc'' for Fedora 17 based builds used in 12.1.0 and later). |
|||
==Simple Offline Upgrade== |
|||
==== Download .usb and .toc files onto USB ==== |
|||
Insert a USB drive into a computer connected to the Internet. |
|||
Go to the download.laptop.org site to fetch the [http://download.laptop.org/xo-1/os/official/ latest XO-1 release] or the [http://download.laptop.org/xo-1.5/os/official/ latest XO-1.5 release]. You need to download two files from the build's directory to the top directory of your USB drive: '''<code>os''NNN''.usb</code>''' and '''<code>os''NNN''.toc</code>''', 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 <code>os711.usb</code> and <code>os711.toc</code>; if you are updating to build joyride-1452, the files would be named <code>os1452.usb</code> and <code>os1452.toc</code>. |
|||
===Before you begin=== |
|||
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 drive. Do not open the files. |
|||
This describes how to update the software image on your laptop from a new image on a USB flash drive or disk. <font color=red>You must be using a B3 machine or better, and build 650 or better. NOTE: All G1G1 recipients have received C2 (also known as MP which is the latest model) these laptops have at least build 650</font>. There is also a method of restoring to [[Support_FAQ#How_can_I_restore_my_Give1Get1_XO_to_its_factory_configuration.3F| G1G1 (build 650) shipped defaults]]. If you've got an older machine or an older build, use the old [[Autoreinstallation image]] instructions (does not apply to G1G1). |
|||
==== USB update ==== |
|||
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. |
|||
# Plug the XO into an electrical outlet |
|||
{{Latest Releases | rc = inline | devel = inline}} |
|||
# Insert your USB drive with the <tt>.toc</tt> and <tt>.usb</tt> files on it into your XO. |
|||
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, "703") is what you should update to. <font color="red">If you have a [[Activation and Developer Keys|developer key]] for your machine</font>, 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! |
|||
# Start the [[Terminal activity]] (or if you cannot do so, open the [[console]]), and enter: |
|||
sudo /usr/sbin/olpc-update --usb |
|||
If you get "command not found" errors, enter: |
|||
Now, you'll want to get a root shell on the machine. Open the [[Terminal Activity]] on your XO (or if you cannot do so, open the [[console]]), and type: |
|||
sudo -i |
|||
at the prompt. If you've set a password for the 'olpc' account, you may have to type it in. If you get an error message here, you're using a pre-update.1 build (or pre-joyride-1450); use |
|||
su - |
su - |
||
/usr/sbin/olpc-update --usb |
|||
instead to get your root shell. Either way, you should end up with a prompt with a # character in it. |
|||
If '''olpc-update''' returns 'command not found', then '''olpc-update''' is not in your current working search path. (i.e. Update.1) Instead type '''/usr/sbin/olpc-update''' for the command. |
|||
When olpc-update is finished, [[reboot]] to start using your new build. |
|||
Now you have two choices: [[#Simple online upgrade|update over the network]], or download the build onto a [[#USB upgrade|USB flash drive]] and update from that. |
|||
== Retention of previous versions == |
|||
=== USB upgrade === |
|||
At the terminal prompt in your root shell, type: |
|||
/usr/sbin/olpc-update --version |
|||
As of release [[11.2.0]], olpc-update only keeps 1 software version available by default (i.e. the old version is deleted after booting into the new version for the first time). |
|||
The first line of the response should be something like: |
|||
olpc-update 2.12, Copyright (C) 2007 One Laptop Per Child Association, Inc. |
|||
Older releases maintained two versions ("primary" and "alternate"), so that you could switch between the two (accepting any strange side effects caused by a software downgrade, not really supported by OLPC or the software that it ships). |
|||
If you don't even have the --version option, <font color="red">(this includes all G1G1 laptops shipped before July 2008)</font> or if it does not say that you are using at least version 2.0 of olpc-update, you will need to [[#Workaround: updating olpc-update|update olpc-update]] before continuing. |
|||
== Avoiding purge of previous versions == |
|||
Now follow one of the build links in the "latest releases" box above. You need to download two files to the top directory of your USB flash drive: '''<code>os''NNN''.usb</code>''' and '''<code>os''NNN''.toc</code>''', 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 <code>os711.usb</code> and <code>os711.toc</code>; if you are updating to build joyride-1452, the files would be named <code>os1452.usb</code> and <code>os1452.toc</code>. |
|||
You can avoid olpc-update from deleting old versions in any situation by marking them as sticky, e.g. for build 802: |
|||
Insert your USB flash drive with these files on it into your XO. At the terminal prompt, type: |
|||
sudo olpc-update --usb |
|||
touch /versions/sticky/802 |
|||
When olpc-update is finished, you should [[reboot]] to start using your new build. |
|||
== Restoring a previous OS == |
|||
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. To swap the "primary" and "alternate" images, hold the 'O' gamepad key during boot. |
|||
If you are using an old release where 2 versions are maintained, or if you are running a modern release and have requested olpc-update to not purge one of the versions, you can switch between the 2 versions as follows: |
|||
== Workaround: 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. |
|||
# shutdown the XO |
|||
From a [[su -l|root prompt]] on your XO (see [[su -l]] for information): |
|||
# power-on ''while holding down the'' ' '''O''' ' ''gamepad key''. |
|||
# wget -P /tmp/X -r -np -nd http://dev.laptop.org/~cscott/olpc-update/ |
|||
# release the key when you're instructed to do so |
|||
# rpm -Uvh --force /tmp/X/olpc*.rpm |
|||
# [[How_to_check_the_OS_and_firmware_versions|check the OS version]] |
|||
== Purging a previous OS == |
|||
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/USB_Drive_Name/olpc*.rpm |
|||
If you have marked a version as sticky and now wish to remove it, or if you are running an old release where the old version is maintained and you wish to free up the disk space occupied by it, you can follow the example Terminal session log shown below. |
|||
Now: |
|||
# olpc-update --version |
|||
should tell you that you have version 2.7 or higher of olpc-update. |
|||
=== Identify what is present === |
|||
== 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. |
|||
List the available builds on the system. |
|||
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. |
|||
# '''ls /versions/pristine/*/boot/olpc_build''' |
|||
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. |
|||
/versions/pristine/802/boot/olpc_build |
|||
/versions/pristine/ed3fcf7128610f1f6fe07890f2315742/boot/olpc_build |
|||
# '''cat /versions/pristine/*/boot/olpc_build''' |
|||
802 |
|||
851 |
|||
This shows there are builds 802 and 851 available on the system. |
|||
The current updates server is updates.laptop.org. |
|||
=== |
=== Identify what is running === |
||
# '''cat /boot/olpc_build''' |
|||
851 |
|||
This shows that the build currently running is build 851. |
|||
In summary: |
|||
Do not purge a build if it is the one running now — things break badly. |
|||
=== Measure free space before purge === |
|||
*Be connected to the internet, |
|||
# '''df /''' |
|||
*In a terminal, become root, |
|||
Filesystem 1K-blocks Used Available Use% Mounted on |
|||
*Type <tt>olpc-update ''NNN''</tt> where NNN is the build number or name-number, |
|||
/dev/mtdblock0 1048576 708572 340004 68% / |
|||
*Wait for the update to complete, |
|||
*Reboot. |
|||
This shows roughly 340004 KB available. |
|||
=== Purge the unused build === |
|||
# '''rm -rf /versions/pristine/''802'' /versions/contents/''802'' /versions/run/''802''''' |
|||
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. |
|||
Removes all the files of the unused build. Takes a few seconds. |
|||
==== Run olpc-update ==== |
|||
=== Measure free space after purge === |
|||
Normally you only need to run ''olpc-update'' with a build number, like this: |
|||
# |
# '''df /''' |
||
Filesystem 1K-blocks Used Available Use% Mounted on |
|||
or |
|||
/dev/mtdblock0 1048576 495944 552632 48% / |
|||
# olpc-update joyride-1779 |
|||
There are other options. For example: |
|||
This shows roughly 552632 KB is available, a significant increase. |
|||
# olpc-update --help |
|||
<pre><nowiki> |
|||
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 |
|||
=== Verify builds present === |
|||
For example: |
|||
olpc-update 630 |
|||
olpc-update joyride-2200 |
|||
olpc-update --latest joyride |
|||
# '''ls /versions/pristine/*/boot/olpc_build''' |
|||
For convenience, 'olpc-update joyride-latest' is treated as an alias for |
|||
/versions/pristine/ed3fcf7128610f1f6fe07890f2315742/boot/olpc_build |
|||
'olpc-update --latest joyride'. |
|||
# '''cat /versions/pristine/*/boot/olpc_build''' |
|||
851 |
|||
This shows only the one build is now present. |
|||
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. |
|||
</nowiki></pre> |
|||
There is no need to reboot or restart after purging the alternate build. |
|||
=== Update Targets === |
|||
== More information == |
|||
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: |
|||
The olpc-update script works by transferring only the differences between builds from a USB 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, |
|||
$ rsync rsync://updates.laptop.org | sort |
|||
*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. |
|||
'''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. |
|||
The current updates server is updates.laptop.org. |
|||
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 ==== |
|||
Development version. Rebased on Fedora 9. |
|||
[[Joyride]] |
|||
The latest joyride build number can generally be found at the top of http://dev.laptop.org/~rwh/announcer/joyride-pkgs.html |
|||
==== Debian/Debian-Big ==== |
|||
[Add version and installed packages by default] |
|||
Debian created Apr 10 2008. |
|||
[[Installing Debian as an upgrade]] |
|||
==== Ubuntu/Edubuntu ==== |
|||
Currently Broken to Olpc-update too. [http://dev.laptop.org/ticket/7012] |
|||
Ubuntu version (gutsy?) created May 1 2008. |
|||
Edubuntu version (gutsy?) created May 2 2008. |
|||
[[Edubuntu]] |
|||
=== |
=== Advanced usage === |
||
==== Update using another laptop ==== |
|||
'''Warning: Advanced usage!''' |
|||
Q: How can I re-use the bits for multiple laptops, using a laptop? |
Q: How can I re-use the bits for multiple laptops, using a laptop? |
||
Line 275: | Line 230: | ||
Several laptops can all be updated in the same way from one source with the same 'hints.json' file. |
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 |
|||
==== Setting up a local updates server ==== |
|||
Basic installation instructions can be found at [[Upgrade Server]]. |
|||
The school server integrates with olpc-update. The [[XS-rsync]] component accepts software images and makes them available to olpc-update clients. |
|||
== Source Repository and Specification == |
|||
A dated, alternative solution is described at [[Upgrade Server]]. |
|||
'''Q''': Where are the specifications? |
|||
== For Developers == |
|||
'''A''': See the [[XO updater]] article. |
|||
Original specification: [[XO updater]] |
|||
'''Q''': Where is the source? |
|||
Source: |
|||
'''A''': The source repository for olpc-update is |
|||
* git://dev.laptop.org/projects/olpc-update |
|||
* http://dev.laptop.org/git/projects/olpc-update |
|||
It also uses code from the olpc-contents package: |
|||
* http://dev.laptop.org/pub/source/olpc-update/ |
|||
Maintainer: [[User:DanielDrake]] |
|||
olpc-update uses [[olpc-contents]] for most of the heavy lifting. |
|||
[[category:software]] |
[[category:software]] |
||
[[Category:Package management]] |
[[Category:Package management]] |
||
[[Category:Procedures]] |
|||
[[Category:Update paths]] |
[[Category:Update paths]] |
||
</noinclude> |
Latest revision as of 23:53, 17 December 2013
olpc-update is a command-line program to update your system software. It preserves your files (journal) and activities you have installed.
olpc-update can download the new version from the internet, or from a file on a USB drive. See Updating the XO for other update scenarios.
The old software version is erased the first time the new version is booted, but this can be prevented.
(Certain really old builds, like 656, can't olpc-update to recent builds. Check the release notes of a recent build to find out if olpc-update can be used from a really old build. If not, then you must install the recent build afresh.)
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.
Disk space requirements
Due to its fail-safe design, olpc-update must store all of the changed files in the release that you are updating to, alongside the existing release that you are running, for a short time. olpc-update cannot complete if there is not enough disk space available.
If upgrading between minor releases within the same release series or between development releases in the same development stream, the space required will be low. However, if upgrading from one major release to another (e.g. 10.1.3 to 11.2.0), you will probably need more than 300mb of disk space available (even though the upgrade process will finish with approximately the same amount of disk space available).
How to upgrade
See the Releases page for the releases that are available. The release notes for each recent release will explain exactly how to use olpc-update to update to that particular version. Be sure to read the release notes before starting the update.
The instructions below are generic.
Simple online update
Note: You should always back up important files; e.g., to a USB 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. It will resume from where it left off, without having to download what it has already downloaded.
To manually upgrade your machine when a new version is released:
- Plug the XO into an electrical outlet
- 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. - 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-identifier
The build-identifier is normally identified on the release notes of the release you are upgrading to. Historically, build identifiers were simple numbers (e.g. 802), for newer builds prefixes are used to separate between the different laptop models (e.g. 10.1.3_xo1.5-860).
If you get an error saying "command not found", type "su -", press enter and then "olpc-update build-identifier" and press enter. For example:
su - /usr/sbin/olpc-update 802
If olpc-update successfully connects to the update server, some messages should display
Downloading contents of build build-identifier 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.
After updating, you should run the Sugar activity updater from the control panel. If not, you may find that various activities are not working.
Simple offline update
Unless you are running a very old release, you can also download the new release data onto a USB disk from an internet-connected computer, and then use olpc-update on an XO to perform the update, without requiring any internet connection.
Prepare a USB drive
Your USB drive needs to be writable from the computer on which you'll download the files, and readable from a running XO (as /media/YourDriveName).
- (Note that /media changes to /run/media/olpc for Fedora 17 based builds used in 12.1.0 and later).
Download .usb and .toc files onto USB
Insert a USB drive into a computer connected to the Internet.
Go to the download.laptop.org site to fetch the latest XO-1 release or the latest XO-1.5 release. You need to download two files from the build's directory to the top directory of your USB 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 drive. Do not open the files.
USB update
- Plug the XO into an electrical outlet
- Insert your USB drive with the .toc and .usb files on it into your XO.
- Start the Terminal activity (or if you cannot do so, open the console), and enter:
sudo /usr/sbin/olpc-update --usb
If you get "command not found" errors, enter:
su - /usr/sbin/olpc-update --usb
When olpc-update is finished, reboot to start using your new build.
Retention of previous versions
As of release 11.2.0, olpc-update only keeps 1 software version available by default (i.e. the old version is deleted after booting into the new version for the first time).
Older releases maintained two versions ("primary" and "alternate"), so that you could switch between the two (accepting any strange side effects caused by a software downgrade, not really supported by OLPC or the software that it ships).
Avoiding purge of previous versions
You can avoid olpc-update from deleting old versions in any situation by marking them as sticky, e.g. for build 802:
touch /versions/sticky/802
Restoring a previous OS
If you are using an old release where 2 versions are maintained, or if you are running a modern release and have requested olpc-update to not purge one of the versions, you can switch between the 2 versions as follows:
- 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
Purging a previous OS
If you have marked a version as sticky and now wish to remove it, or if you are running an old release where the old version is maintained and you wish to free up the disk space occupied by it, you can follow the example Terminal session log shown below.
Identify what is present
List the available builds on the system.
# ls /versions/pristine/*/boot/olpc_build /versions/pristine/802/boot/olpc_build /versions/pristine/ed3fcf7128610f1f6fe07890f2315742/boot/olpc_build # cat /versions/pristine/*/boot/olpc_build 802 851
This shows there are builds 802 and 851 available on the system.
Identify what is running
# cat /boot/olpc_build 851
This shows that the build currently running is build 851. Do not purge a build if it is the one running now — things break badly.
Measure free space before purge
# df / Filesystem 1K-blocks Used Available Use% Mounted on /dev/mtdblock0 1048576 708572 340004 68% /
This shows roughly 340004 KB available.
Purge the unused build
# rm -rf /versions/pristine/802 /versions/contents/802 /versions/run/802
Removes all the files of the unused build. Takes a few seconds.
Measure free space after purge
# df / Filesystem 1K-blocks Used Available Use% Mounted on /dev/mtdblock0 1048576 495944 552632 48% /
This shows roughly 552632 KB is available, a significant increase.
Verify builds present
# ls /versions/pristine/*/boot/olpc_build /versions/pristine/ed3fcf7128610f1f6fe07890f2315742/boot/olpc_build # cat /versions/pristine/*/boot/olpc_build 851
This shows only the one build is now present.
There is no need to reboot or restart after purging the alternate build.
More information
The olpc-update script works by transferring only the differences between builds from a USB 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.
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
The school server integrates with olpc-update. The XS-rsync component accepts software images and makes them available to olpc-update clients.
A dated, alternative solution is described at Upgrade Server.
For Developers
Original specification: XO updater
Source:
- git://dev.laptop.org/projects/olpc-update
- http://dev.laptop.org/git/projects/olpc-update
- http://dev.laptop.org/pub/source/olpc-update/
Maintainer: User:DanielDrake
olpc-update uses olpc-contents for most of the heavy lifting.