Installing Fedora Core

Overview

This page describes how to install Fedora Core on the One Laptop per Child hardware. As of the writing of this document, the A-Test boards have been built and distributed to several hundred people. Fedora Core does run on the hardware, with some minor changes. We'll walk you through how to make those changes.

Requirements

Hardware

You will need a few pieces of hardware to install the software on the A-Test board.

• 1 A-Test (or pre-A-Test) OLPC board
• 1 USB flash drive (aka: thumb drive, pen drive, flash key)
• 1 USB hard drive
• 1 USB ethernet adapter
• 1 external VGA-compatible monitor for display
• 1 USB keyboard
• 1 USB mouse
• 1 powered USB hub

Why you need the powered USB hub

• The board only has 3 USB ports, and there are 5 USB peripherals involved.
• But even if you are only using 3 USB peripherals, you still might need a powered hub, because the board's internal power converters are wimpy (to reduce cost and prolong battery life).

Software

Right now, you need to use Rawhide—the Fedora development branch—(or unstable) version of Fedora Core to install on the laptop. We will be putting our kernel changes, dependency, and software changes into FC Rawhide. Our current requirements for the software include:

• A recent Rawhide snapshot; not all builds may work, even if they're recent—we provide some known good snapshots.
• A place to host that snapshot on your network; there are a couple of sources listed below, if absolutely needed.
• The serenity to accept that sometimes Rawhide is broken.
• A strong will to live.

Download

You will want to use one of our Rawhide snapshots. The reason is that Rawhide is fast-moving and you will want to use snapshots that we have tested.

A Rawhide snapshot from May 27th, 2006 that works with these instructions is available from these mirrors:

• http://olpc.download.redhat.com/olpc/rawhide-snapshots/2006-05-27-0237/
• http://www-crca.ucsd.edu/~msp/olpc/rawhide-snapshots/2006-05-27-0237/

(the second mirror hasn't yet been tested; use the first if it's available).

Getting Ready to Install

To ease readability, lines where you enter commands will be shown in green, and text printed by the computer will be shown in black. Other important text will be shown as bold.

Mounting

If you want to mount the images on a Linux, try this:

  losetup -o $((32 * 512)) /dev/loop/0 olpc-stream-development-7-20060609_1600-ext3.img
  mount -t ext2 /dev/loop/0 /mnt/

Setting up a bootable image

Insert your USB key into another Fedora machine and run the command dmesg. The output should look something like this:

[username@computername images]$ dmesg
.
.
.
usb-storage: waiting for device to settle before scanning
  Vendor: Kingston  Model: DataTraveler 2.0  Rev: 6.16
  Type:   Direct-Access                      ANSI SCSI revision: 00
SCSI device sda: 2004991 512-byte hdwr sectors (1027 MB)
sda: Write Protect is off
sda: Mode Sense: 45 00 00 08
sda: assuming drive cache: write through
SCSI device sda: 2004991 512-byte hdwr sectors (1027 MB)
sda: Write Protect is off
sda: Mode Sense: 45 00 00 08
sda: assuming drive cache: write through
sda: sda1
sd 3:0:0:0: Attached scsi removable disk sda
sd 3:0:0:0: Attached scsi generic sg0 type 0
usb-storage: device scan complete
.
.
.
[username@computername images]$

Note the fact that this USB key has shown up as sda. You will need this in a moment.

Make sure the device is not mounted. You can do this with a simple mount command. If /dev/sda1 shows up in the output, it's mounted. You can unmonut it by running umount /dev/sda1. Like so:

[username@computername images]$ mount
/dev/hda2 on / type ext3 (rw)
none on /proc type proc (rw)
none on /sys type sysfs (rw)
none on /dev/pts type devpts (rw,gid=5,mode=620)
/dev/hda1 on /boot type ext3 (rw)
/dev/sda1 on /media/Kingston type vfat (rw,noexec,nosuid,nodev,shortname=winnt,uid=500)
[username@computername images]$  sudo umount /dev/sda1 
[username@computername images]$

Go to the Fedora Rawhide tree here. Get the file

images/diskboot.img

This is the file that contains a bootable image that you can use to boot on the board and run the installer. You will need to copy it in a raw format to the USB key. You do this using the dd command to the raw device. Note that this is /dev/sda not /dev/sda1. Make sure that you use the 'dd' command with the correct drive, as this will destroy or replace any filesystems or data on this drive.

[root@mobile2 2006-06-08-0245]#  dd if=images/diskboot.img of=/dev/sda
16384+0 records in
16384+0 records out
8388608 bytes (8.4 MB) copied, 1.88433 seconds, 4.5 MB/s
[root@computername 2006-06-08-0245]#

Boot on the laptop

Insert the USB flash drive into one of the USB ports on the A-Test board itself. Do not connect it through the USB hub.

Power on the board. If the BIOS detects the flash drive, you will see a message in the upper left-hand corner of the screen that says something like:

Press F1 for Setup INITIALIZING BOOT USB DEVICE - DataTraveler 2.0  
USB Storage Class Device [xxxxxxxx/xxxx/xxxx]

or

Press F1 for Setup INITIALIZING BOOT USB DEVICE - WD1600BB-00RDA0
USB BOOTABLE HDD DEVICE [xxxxxxxx/xxxx/xxxx]

You should see the Linux kernel being loaded and then the installer being loaded. If you don't, try the USB key in a different port or try disconnecting the hub. The BIOS and USB are very flaky right now because we are using a temporary (partially debugged) BIOS until LinuxBIOS comes up on the boards. In fact, you might have to disconnect the USB hub while the kernel and initrd are loaded off the USB key and then connect it quickly once the kernel has started booting.

Installing

Congratulations! Now you've made it to the Linux installer boot screen. From here you should type:

linux selinux=0 text

and hit return to enter the text-mode installer. The graphical installer will not run on this machine because it does not have enough memory. We disable selinux during this install because for some reason it turns a 40-minute install into a 4-hour ordeal. We aren't sure why at this point. Please note the above instructions that say that you might have to plug the USB hub in after the initrd has been loaded and the kernel starts up due to problems with the USB stack and the BIOS.

You may also have to remove the USB plug for the keyboard and plug it back in again once the kernel has started. Once again, USB and BIOS bugs. Just don't be alarmed if your keyboard suddenly doesn't work.

From here you need to pick your install type. We've been using HTTP installs and we have D-Link USB ethernet devices that require that we pick the asix driver. We're going to assume you know how to set up a web server or NFS server to install from and you know how to set your network settings so that it can find it.

When you're setting up a partition table, we suggest that you use the smallest configuration possible. This means no logical volume groups. Just three partitions:

  Drive       file system    Mount point   Size
/dev/sda1   ext3           /boot         (about 128MB)
/dev/sda2   swap           N/A           (about 1GB)
/dev/sda3   ext3           /             (everything else)

This makes it very easy to fix things later—because we are going to have to fix things later. And, yes, we really do need a gig of swap. We've run out of memory with only 512MB.

Once you've partitioned, you might have to restart to get the new partition table. Make sure you do restart instead of just trying to forge ahead.

Follow the installer prompts until you get to package selection. You should be able to install the packages you want, but be warned that picking a lot of packages will take a long time on this machine. We usually install a minimal system (unselect all of the high-level packages) and then install just the packages we need. If you really want to install packages now, don't be surprosed if it takes a couple of hours.

Fixing post-install

Assuming that your install was successful and you've rebooted the machine you probably see an error like this:

switchroot: mount failed: No such file or directory
Kernel panic - not syncing: Attempting to kill init!
  <c0416e96> panic+0x46/0x188 <x04194cd> do_exit+0x75/0x72c
  <c04121ab> do_page_fault+0x22a/0x5a9  <c0419bf1> sys_exit_group+0x0/0xd
  <c0402cc7> syscall_call+0x7/0xb

This is good news. This means that you've got an install that's completed and tried to boot. The panic is a symptom of the fact that your kernel doesn't have the usb modules loaded and can't find the disk. Lucky for you this is pretty easy to fix.

Fixing the initrd

First, you have to pull your USB hard drive out of the laptop board and plug it into another machine. You should mount the /boot and the / (root) partitions on your drive. In the following examples, our root partition is mounted in /media/disk and our /boot partition is mounted in /media/disk-1. Depending on what machine you're using, 'disk' and 'disk-1' may be switched, or may be called something else, like 'usbdisk' and 'usbdisk-1'.

Note: Make sure that you're changing the files on the hard drive you want to fix, not on the hard drive that already works!

Once you've done that, cd into the /boot partition on your USB hard drive. You should see a set of files like this:

config-2.6.16-1.2221_FC6      lost+found
grub                          System.map-2.6.16-1.2221_FC6
initrd-2.6.16-1.2221_FC6.img  vmlinuz-2.6.16-1.2221_FC6

initrd-2.6.16-1.2221_FC6.img is the file we're interested in fixing. initrd is a file that contains extra modules the kernel needs in order to find extra hardware devices, as well as the initial startup script that mounts your root partition and kicks off the rest of the boot process.

There are two things we will be fixing:

• First, the modules for the usb drives are missing. We will have to pull them out of the kernel directory and add them to the initrd.

• Second, we need to add a delay during the boot process so that once the usb modules are loaded, the devices are given a chance to settle and the hard drives show up, before attempting to mount root.

initrd is a file that's compressed and stored as a cpio archive. In order to extract the files we'll need to decompress it and explode the archive; you may want to 'sudo -s' into your root account so you don't have to type 'sudo' every line:

[root@computername ~]# cd /media/disk-1/ 
[root@computername disk-1]# ls
config-2.6.16-1.2221_FC6      lost+found
grub                          System.map-2.6.16-1.2221_FC6
initrd-2.6.16-1.2221_FC6.img  vmlinuz-2.6.16-1.2221_FC6
[root@computername disk-1]# ls -l 
total 3533
-rw-r--r-- 1 root root   59376 May 26 13:27 config-2.6.16-1.2221_FC6
drwxr-xr-x 2 root root    1024 Jun  8 09:13 grub
-rw-r--r-- 1 root root 1101550 Jun  8 09:08 initrd-2.6.16-1.2221_FC6.img
drwx------ 2 root root   12288 Jun  8 04:51 lost+found
-rw-r--r-- 1 root root  796900 May 26 13:27 System.map-2.6.16-1.2221_FC6
-rw-r--r-- 1 root root 1625946 May 26 13:27 vmlinuz-2.6.16-1.2221_FC6
[root@computername disk-1]# mkdir work 
[root@computername disk-1]# cd work 
[root@computername work]# gzip -cd ../initrd-2.6.16-1.2221_FC6.img | cpio -i 
4765 blocks
[root@computername work]# ls 
bin  dev  etc  init  lib  proc  sbin  sys  sysroot
[root@computername work]#

What we want to do is to add two files to the lib/ directory that are missing. The missing files are the drives for USB1 and USB2 devices. Those files are:

ehci-hcd.ko
ohci-hcd.ko

They are located in the kernel modules directory on the root partition that you mounted earlier. In my case they would be at:

/media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ehci-hcd.ko
/media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ohci-hcd.ko

Keeping in mind that on any particular machine, it 'disk' may be 'usbdisk' or 'disk-1' or 'usbdisk-1' or something like that. Copy them into the lib/ directory that you just extracted.

[root@computername work]# cd lib
[root@computername lib]# cp -v \
 /media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ohci-hcd.ko \
 /media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ehci-hcd.ko .
`/media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ohci-hcd.ko' -> `./ohci-hcd.ko'
`/media/disk/lib/modules/2.6.16-1.2221_FC6/kernel/drivers/usb/host/ehci-hcd.ko' -> `./ehci-hcd.ko'
[root@computername lib]# ls 
dm-mirror.ko    dm-zero.ko   jbd.ko       sd_mod.ko
dm-mod.ko       ehci-hcd.ko  ohci-hcd.ko  usb-storage.ko
dm-snapshot.ko  ext3.ko      scsi_mod.ko
[root@computername lib]#

Now that you've put the modules in the right place you have to tell the init program to load them during startup. At the same time, we will have to add a delay to the startup so that once those modules are loaded the devices will be detected once they have spun up.

cd up to the work/ directory and edit the init file using vi:

[root@computername lib]# pwd /media/disk-1/work/lib  
[root@mobile2 lib]# cd .. 
[root@computername work]# ls 
bin  dev  etc  init  lib  proc  sbin  sys  sysroot
[root@mobile2 work]# vi init 

In that file, look for the following section and add what we've added. The lines that we've added show up in bold:

echo Setting up hotplug.
hotplug
echo Creating block device nodes.
mkblkdevs
mount -t usbfs /proc/bus/usb /proc/bus/usb
echo "Loading ehci-hcd.ko module"
insmod /lib/ehci-hcd.ko
echo "Loading ohci-hcd.ko module"
insmod /lib/ohci-hcd.ko 
echo "Loading scsi_mod.ko module"
insmod /lib/scsi_mod.ko
echo "Loading sd_mod.ko module"
insmod /lib/sd_mod.ko
echo "Loading usb-storage.ko module"
insmod /lib/usb-storage.ko
echo Waiting for driver initialization.
stabilized /proc/bus/usb/devices
echo Waiting for driver initialization in case stabilize does not work
sleep 12 
echo "Loading jbd.ko module"
insmod /lib/jbd.ko

Now that you've added the right lines to the init and you've also added the required modules, it's time to put the initrd back together again. To do that you need to make a backup of the current initrd, make a file list of the files to be included in the new initrd (remember, you've added some times), and then reassemble the initrd into an archive. The commands should look like this:

[root@computername work]# mv ../initrd-2.6.16-1.2221_FC6.img ../initrd-2.6.16-1.2221_FC6.img.backup 
[root@computername work]# find . > ../initrd-file-list 
[root@computername work]# cat ../initrd-file-list  | cpio -o -c > ../initrd-2.6.16-1.2221_FC6.img 
4892 blocks
[root@computername work]# ls -l ..
total 4646
-rw-r--r-- 1 root root   59376 May 26 13:27 config-2.6.16-1.2221_FC6
drwxr-xr-x 2 root root    1024 Jun  8 09:13 grub
-rw-r--r-- 1 root root 1130820 Jun 15 10:43 initrd-2.6.16-1.2221_FC6.img
-rw-r--r-- 1 root root 1101550 Jun  8 09:08 initrd-2.6.16-1.2221_FC6.img.backup
-rw-r--r-- 1 root root     620 Jun 15 10:42 initrd-file-list
drwx------ 2 root root   12288 Jun  8 04:51 lost+found
-rw-r--r-- 1 root root  796900 May 26 13:27 System.map-2.6.16-1.2221_FC6
-rw-r--r-- 1 root root 1625946 May 26 13:27 vmlinuz-2.6.16-1.2221_FC6
drwxr-xr-x 9 root root    1024 Jun 15 10:38 work
[root@computername work]#

At this point you should have a working initrd and the right modules in place. You should be able to unmount the drives, reconnect the drive directly into the laptop motherboard—don't connect through the hub or the BIOS might not find the drive—and reboot. But since you're here, we suggest that you fix up the grub options for the board first.

Grub Options

We suggest that you add some options to grub that will make using X on the laptop easier, assuming you decide to install it. To do that, edit the file /boot/grub/grub.conf and add the options on bold to the boot options:

[root@computername work]#   vi /boot/grub/grub.conf 

title Fedora Core (2.6.16-1.2221_FC6)
        root (hd0,0)
        kernel /vmlinuz-2.6.16-1.2221_FC6 ro root=LABEL=/  selinux=0 vga=0x311 video=fbdev:ypan  

To install X, once you are logged in, type in "yum install xfree86" to retrieve and install the package.

Common Errors

• "invalid file system" on boot
• kernel panic on boot

Invalid initrd

You may still encounter a kernel panic even after fixing the initrd. This is caused when we recompress the archive. This may or may not be an issue. We're not sure what causes it quite yet.

RAMDISK: Compressed image found at block 0
No filesystem could mount root, tried: ext2 iso9660
Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)
<c0416e96> panic+0x46/0x188 <c06e6a7f> mount_block_root+0x214/0x223
<c0463261> sys_mknod+0x27/0x2b  <c06e8d90> initrd_load+0xc7/0x372
<c06e6b75> prepare_namespace+0x8d/0x100 <c0453c7e> sys_acces+0x1f/0x23
<c04003d5> init+0x159/0x22b  <c0402ba6> ret_from_fork+0x6/0x20
<c040027c> init+0x0/0x22b <c040027c> init+0x0/0x22b
<c0401005> kernel_thread_helper+0x5/0xb

If this happens to you, don't compress the archive.