View source for 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.
([[wikipedia:Live CD|"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
# create a file system on the USB drive with the necessary characteristics
# put the OLPC release's files in this file system
# 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/sd''X1''

Where <tt>/dev/sd''X1''</tt> is the partition containing your root FS.

=== Extracting a build's files ===
Since 2010 or so the OLPC [[Build system]] does not retain a generic Linux filesystem image, it produces images specific to the built-in flash memory of different XO models.
However, many builds contain the filesystem contents in a file named <tt>os''NN''.tree.tar.lzma</tt>

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''
:*(Note that ''/media'' changes to ''/run/media/olpc'' for Fedora 17 based builds used in 12.1.0 and later).
* "Untar" the files, e.g.
  % '''sudo tar --lzma --numeric-owner -xvf /'''''path/to/downloaded'''''/os'''''NN'''''.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 [http://www.linux-mtd.infradead.org/faq/jffs2.html 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 <tt>os''NNN''.img</tt> file is the raw JFFS2 contents and does not work copied to a USB flash drive.

<div style="border:1px solid #b0ffb0; padding:1px; margin:1px; background-color:#fab15c">
'''''CAUTION''''': ** See [[How_to_Damage_a_FLASH_Storage_Device]] before proceeding. **
</div>
: **A tar-based copy would use the existing file system and partitions. New instructions needed.**  --[[User:FGrose|FGrose]] 15:18, 4 February 2009 (UTC)
:Consider the cpio-based method described in [[#USB disk with existing partitions]].  
<div style="border:4px solid #fab15c; padding:1px; margin:1px; background-color:#ffffff">
=== 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 <tt>.img.bz2</tt> file, e.g.,

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

unzip it, and transfer it to a USB storage device via <tt>dd</tt>, 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/sd''X'' bs=1M
 % sync

Remember to:

* Make sure any old partitions from the storage device are unmounted.
* Do this as the super user / root
* Replace <tt>/dev/sd''X''</tt> 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'' <tt>/dev/sdb1</tt>).
** '''''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 <tt>devel_ext3.img.bz2</tt> 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.
</div>

== 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 [http://amazon.com/dp/B001L7EGA6  Amazon] for purchase.
* [[Ubuntu]]
* Using [[Gentoo_on_XO]] via USB-stick.
* See [[User:Donaldaudric/Booting from USB Device|Booting from USB Device]] for instructions on how to boot xo-1 images from a USB device.

[[Category:OS]]
[[Category:Developers]]