OS images for USB disks

Notes before beginning...

• This page presumes that you'll be using the disks you create on OLPC's "XO" hardware. While you could try to boot a normal PC with them (making sure you select the OLPC Simulator option), there are other ways to run the OLPC's Sugar user interface on a PC, see Emulating the XO.
• By default, the images boot with the GRUB boot option OLPC USB. This is what you want if you're booting from a USB disk connected to OLPC hardware.

Background

The OS images that OLPC creates for each release contain the computer instructions of the OLPC software. If you present those to an XO, it will run them. But the XO has to boot, read these machine instructions from the file system on the USB, and then use that file system. The OLPC operating system's layout is incompatible with the "FAT" filesystem set up on most USB drives, it requires permissions and symbolic links that FAT does not provide. ("Live" CDs and USBs for Linux get around this limitation by packing a UNIX file system into simple files on the CD or USB drive which the computer unpacks during boot.)

So you must

1. create a file system on the USB drive with the necessary characteristics
2. put the OLPC release's files in this file system
3. modify the boot instructions in the file system

before you can attempt to boot an XO from the USB drive

USB disk with existing partitions

If you don't want to completely wipe the USB stick or hard drive, you can also try transferring the partition within the image file into an existing partition on your storage device. Using dd to transfer the image directly onto the device completely replaces the existing data and partition table. Instead, you can use loopback mounts to copy the partition across and then set-up grub on the device.

Partitioning

Don't follow this set of instructions if you don't know how to partition your disk or create filesystems. There are some things you need to know that the OS images assume:

ext3 root filesystem

Make sure the root partition is the ext3 filesystem, not ext2.

OLPCRoot volume label

The OS images look for the volume label OLPCRoot to determine the root FS. You can set this for an ext3 filesystem with:

# tune2fs -L OLPCRoot /dev/sdX1

Where /dev/sdX1 is the partition containing your root FS.

Extracting a build's files

Since 2010 or so the OLPC Build system does not produce a generic Linux filesystem image, it produces images specific to the built-in flash memory of different XO models. However, many builds contain the file system contents in a file named osNN.tree.tar.lzma

After downloading the .tree.tar.lzma file appropriate for your XO, you need to extract these files to the partition on your device, preserving their attributes and ownership. One way to extract these files to your partition.

• Insert the SD card or USB drive and allow your operating system to mount it.
• Change to its root directory, e.g.

 % cd /media/OLPCRoot

• "Untar" the files, e.g.

 % sudo tar --lzma --numeric-owner -xvf /path/to/downloaded/osNN.tree.tar.lzma

• You need to create a symbolic link from the boot directory to /boot, e.g.

 % sudo ln -s versions/pristine/NN/boot boot'

• ?? You need to make additional changes to the boot path in olpc.fth and initrd ?? See <trac>11233</trac>.
• Safely remove the SD card or USB drive
• % sync

Booting

Now you try booting. Insert the USB drive, power on the XO holding down the check game key to see details, and then press [Esc] to disable the normal boot process. Then enter something like (see Custom bootloader):

ok boot U:\boot\vmlinuz

Mounting an image to extract files

JFFS2 XO-1 images

In theory you can mount a JFFS2 .img of the XO-1 file system under Linux and get the files from that. The JFFS2 FAQ mentions some issues.

Old ext3 images

Retrieve and unzip the appropriate OLPC image file as described above. This file contains a partition table, which describes exactly one partition. What we want to do is to mount that partition (using a loopback device) and copy the contents to the USB hard disk, then make that hard disk bootable.

First, we need to setup the image file on a loopback device so we can inspect that partition table:

# losetup /dev/loop0 olpc-stream-development-59-20060808_1153-rpm-ext3.img 

Now, use fdisk to look at the contents:

# fdisk -l -u /dev/loop0

 Disk /dev/loop0: 504 MB, 504626688 bytes
 16 heads, 32 sectors/track, 1924 cylinders, total 985599 sectors
 Units = sectors of 1 * 512 = 512 bytes
 Device Boot      Start         End      Blocks   Id  System
 /dev/loop0p1        32      985599      492784   83  Linux

In this case, the partition we want starts at sector 32, and each sector is 512 bytes = 16384 bytes into the image file. Now, we can set up a second loopback device to load this partition and mount it:

# losetup /dev/loop1 -o 16384 olpc-stream-development-59-20060808_1153-rpm-ext3.img
# mount -text3 /dev/loop1 /media/tmp/

Copying files to the new disk

Now, copy the files to your USB hard disk:

# cd /media/tmp
# find | cpio -p --unconditional --preserve-modification-time --dot /media/OLPCRoot

Bootloader setup

Since LinuxBIOS is no longer on olpc , GRUB is useless. Just reboot your olpc and it will start on USB key . To verify type "df" or "mount" in a terminal

And finally, we need to set up grub on the disk to boot from the first partition. We do this using the GRUB shell. Note that in this example, we're installing on (hd1), because the external disk is the 2nd disk connected to the system. When it boots on the OLPC board, it will be the primary disk and grub will treat it as (hd0)

# grub
Probing devices to guess BIOS drives. This may take a long time.
# grub> root (hd1)
root (hd1)
Filesystem type unknown, using whole disk
# grub> root (hd1,0)
root (hd1,0)
Filesystem type is ext2fs, partition type 0x83
grub> setup (hd1)
setup (hd1)
Checking if "/boot/grub/stage1" exists... yes
Checking if "/boot/grub/stage2" exists... yes
Checking if "/boot/grub/e2fs_stage1_5" exists... yes
Running "embed /boot/grub/e2fs_stage1_5 (hd1)"...  15 sectors are embedded.
succeeded
Running "install /boot/grub/stage1 (hd1) (hd1)1+15 p (hd1,0)/boot/grub/stage2 /boot/grub/menu.lst"... succeeded
Done.
# grub> ^C
#

• When I tried booting from this drive on the OLPC, GRUB started but didn't load its configuration correctly - just dropping me into the grub shell instead. I needed to run 'root' and 'setup' again on the actual board to get GRUB to set itself up right. If anyone knows how to avoid this step, please fix the instructions.

To solve the Problem you have to insert two lines in each sector of /media/OLPCRoot/boot/grub/menu.lst (possibly grub.conf, whatever is printed out above):

map (hd0) (hd1)
map (hd1) (hd0)

Dedicated USB disk

The #Dedicated USB disk method described here combines step 1 (create a file system on the USB drive with the necessary characteristics) and 2 (put the OLPC release's files in this file system) by dumping an XO image complete with a partition table and ext3 filesystem onto the USB drive.

However, as of 2010 OLPC's Build system no longer creates such images. The XO-1 osNNN.img file is the raw JFFS2 contents and does not work copied to a USB flash drive.

CAUTION: ** See How_to_Damage_a_FLASH_Storage_Device before proceeding. **

**A tar-based copy would use the existing file system and partitions. New instructions needed.** --FGrose 15:18, 4 February 2009 (UTC)

Consider the cpio-based method described in #USB disk with existing partitions.

Linux

If you can devote an entire USB flash drive or hard disk for trying images out and there is a suitable ext3 partition image, then using the OS images is easy.

To try out an image, simply download the appropriate .img.bz2 file, e.g.,

olpc-stream-development-42-20060714_1709-rpm-ext3.img.bz2

unzip it, and transfer it to a USB storage device via dd, e.g.,

% bunzip2 olpc-stream-development-42-20060714_1709-rpm-ext3.img.bz2
% sudo dd if=olpc-stream-development-42-20060714_1709-rpm-ext3.img of=/dev/sdX bs=1M
% sync

Remember to:

• Make sure any old partitions from the storage device are unmounted.
• Do this as the super user / root
• Replace /dev/sdX with the device file of the USB storage device. The images contain a partition table and boot loader, so make sure to write to the device and not a partition on the device (e.g. not /dev/sdb1).
  • If you pick the wrong device you can easily overwrite the contents of your computer's hard drive!
• The USB storage device must be 1024 MB or larger. All existing data will be lost.

Now you should be able to boot the OLPC operating system off the USB storage device.

Windows

In situations where you have only a Windows machine with Internet connection available, you can also use WinImage to copy the image to the USB storage device.

• First, unpack the .bz2 file (e.g., using 7zip or WinRAR)
• Second, launch WinImage and write the image to the USB storage device

http://img520.imageshack.us/img520/5421/image1jv9.gif

• A window will pop up and ask you which disk to write to - make sure that you select the correct disk - all its contents will be overwritten!

http://img114.imageshack.us/img114/5276/image3it5.gif

Mac OS X

Due to its BSD roots the instructions for Linux apply almost verbatim. Be sure to read them, in particular the All existing data will be lost part.

(these images are all quite old) First, download the devel_ext3.img.bz2 file from http://olpc.download.redhat.com/olpc/streams/development/ without unpacking it (to save disk space).

When you plug in a flash drive it will most likely be formatted as FAT, it will be automatically mounted and pop open in the Finder. You need to unmount it first (do not press the eject button in the Finder because this removes the entire device).

So open up a Terminal. Use "mount" to find out which device (/dev/diskX) the flash drive is. /dev/disk0 is your main hard drive, you will not want to accidentally overwrite that! My flash was "NO NAME" on /dev/disk1s1:

machine:~ user$ mount
...
/dev/disk1s1 on /Volumes/NO NAME (local, nodev, nosuid)
machine:~ user$

In the following, you need to use /dev/diskX not /dev/diskXsY which is only one partition, we need to use the entire drive. You need to be super user to unmount:

machine:~ user$ sudo umount /dev/diskX

If unmounting fails, it means something is accessing the disk. Generally, this works in more cases:

machine:~ user$ sudo hdiutil eject /dev/diskX

If this still doesn't work, you can use lsof to find out what is accessing the disk

 machine:~ user$ sudo lsof "/Volumes/NO NAME"

This should return a listing of processes that are using the disk. It is most likely to be spotlight (process name mds). This can be tricky to resolve. I did this by going into spotlight preferences and adding the disk to the Privacy section to stop it indexing the disk. You may need to eject and re-insert the USB drive, or even reboot.

You can also use Disk Utility to unmount the volume without ejecting the disk itself.

Once the drive has been unmounted, we can unpack and copy the file in one go. Make very sure you use the right /dev/diskX!

machine:~ user$ bunzip2 -c olpc-redhat-stream-development-build-466-20070626_0502-devel_ext3.img.bz2 | dd of=/dev/diskX bs=1m

Once the copying is finished, the Finder might pop up a warning dialog because it does not recognize the ext3 file system. Just eject the drive.

USB Boot images

See also

• Slackware
• DebXO for boot of a clean install of Debian via USB image.
• Fedora 10 bootable on USB card, was/may be available via Amazon for purchase.
• Creating a custom Ubuntu image for booting off USB device.
• Using Gentoo_on_XO via USB-stick.
• See Booting from USB Device for instructions on how to boot xo-1 images from a USB device.