Home

Screen Shots

Documentation

Download

Forums

Support & Help

Project Sponsors

FAQ's

Legal

Linux on iPod at SourceForge.

Linux iPod Installation Guide

Auf Deutsch

Introduction

The Linux on iPod project offers a development platform for building applications that run on the iPod hardware. Currently we have also developed a basic application that mimics some of the functionality of the existing Apple firmware, over time we hope to add to this application to provide similar functionality to that as the Apple firmware as well as innovations not available with the standard software.

Installation of Linux on your iPod is a non-destructive process and will leave all your existing configuration and music on your iPod. The included bootloader will also allow you to choose either the Apple or the Linux software to start at reset.

This document describes how to install Linux on your iPod using a Unix-like system (for example Linux or Mac OSX). The process is based on the 2.4.24-ipod0 release of the Linux kernel and the 040403 release of the root filesystem.

Any feedback on this documentation is greatly appreciated.

Overview

This document covers the following sections.

• Firewire/Connection Setup
• Linux Installation
  1. Locating your iPod
  2. Backup
  3. Partitioning
  4. Kernel Installation
  5. Userland installation
  6. Finishing up
  7. Upgrading
  8. Uninstalling iPod Linux
• Mac OSX Installation
  1. Backup
  2. Kernel Installation
  3. Userland installation
  4. Finishing up
  5. Upgrading
  6. Uninstalling iPod Linux
• Windows Installation

In order to install Linux on your iPod you firstly need to have your system configured for your iPod. If you are using Mac OSX then there is probably nothing further to do, however if you are using Linux (especially if this the first time!) you need to ensure that you have either Firewire or USB correctly configured for your iPod.

To configure Firewire or USB for your system please consult the documentation provided with your operating system.

Once the operating system is configured you need to determine how your operating system identifies your iPod.

To do this you should plug in your iPod to your PC and ensure that it switches to Disk-Mode. Normally it should do so automatically when the appropriate connection is established by your operating system, however, you can enter forced disk mode by resetting your iPod (hold down menu and play/pause for 3 seconds) and then when the Apple icon appears hold down fast-forward and rewind.

Once in disk mode you should see the message "Do not disconnect." on your iPod. You should then check your operating system configuration to see how your iPod is configured.

To continue with the installation please go to the operating system specific section of the manual.

Linux Installation

This section of the guide details how to install Linux on your iPod using a Linux based PC. It assumes that you are using a Windows formatted iPod (e.g. FAT32) - if your iPod is HFS+ formatted it is generally easier to reformat as FAT32.

Note, with Linux it is necessary to have root permissions to install Linux on your iPod.

Locating your iPod

Under Linux you should check the file "/proc/scsi/scsi" for an entry where the Vendor is "Apple" and the model is "iPod". For example:

# cat /proc/scsi/scsi
Attached devices:
Host: scsi0 Channel: 00 Id: 00 Lun: 00
Vendor: Apple Model: iPod Rev: 1.50
Type: Direct-Access ANSI SCSI revision: 02


The scsi0 portion indicates the iPod is the first SCSI device and so will be visible as /dev/sda, if on your system you see scsi1 then your iPod would be using device /dev/sdb. The following example commands will use sda as the device for the iPod, please replace this with the correct device for you configuration.

Backup

Since we will update the partition information and replace the hard-drive firmware image we will firstly make a backup of this data. The first backup file is simply a copy of the MBR (master boot record) which contains the partition table for the disk. The second backup file is a complete backup of the operating system partition on the iPod and includes the Apple iPod operating system (this file is 40MB and can be compressed once the installation process is complete).

# dd if=/dev/sda of=ipod_boot_sector_backup count=1
# dd if=/dev/sda1 of=ipod_os_partition_backup


Should you need to restore these backups for any reason simply use the following commands.

# dd if=ipod_boot_sector_backup of=/dev/sda
# dd if=ipod_os_partition_backup of=/dev/sda1


Note, if you want to upgrade the Apple firmware then you should firstly restore the iPod operating system backup.

It is also possible to completely restore your iPod to its factory state by using the restore program from Apple. This will restore the original operating system and standard partitioning to your iPod. Unfortunately this will mean any settings or music will have to be copied back to your iPod.

Partitioning

Now that the backups are done we will add a new partition to the iPod to hold the root file system for Linux. This is required on Win-iPods as Linux cannot use a FAT partition for its root file system.

The following commands describe a session with fdisk that deletes the existing firmware partition and then creates a new, smaller, partition to hold the firmware. The additional space is then used to create a new partition which we then format for use with Linux.

Note, the output displayed below is correct for a 20GB iPod, some output will be different for different sized iPods however the values entered by the user remain the same.

1. Start fdisk.

   # fdisk /dev/sda
The number of cylinders for this disk is set to 2431.
There is nothing wrong with that, but this is larger than 1024,
and could in certain setups cause problems with:
1) software that runs at boot time (e.g., old versions of LILO)
2) booting and partitioning software from other OSs
(e.g., DOS FDISK, OS/2 FDISK)

Command (m for help):

2. Delete the firmware partition.

   Command (m for help): d
Partition number (1-4): 1

3. Create a new primary partition with a length of 1 cylinder.

   Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-2431, default 1): 1
Last cylinder or +size or +sizeM or +sizeK (1-5, default 5): 1

4. Activate the first partition.

   Command (m for help): a
Partition number (1-4): 1

5. Set partition type to 'Empty'.

   Command (m for help): t
Partition number (1-4): 1
Hex code (type L to list codes): 0

6. Create the 3rd primary partition from 2nd to 5th Cylinder.

   Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 3
First cylinder (1-2431, default 1): 2
Last cylinder or +size or +sizeM or +sizeK (1-5, default 5): 5

7. Review the changes. Note, this is for a 20GB iPod, for other iPod versions the sda2 partition size will vary.

   Command (m for help): p
   

   Disk /dev/sda: 20.0 GB, 20000268288 bytes
   255 heads, 63 sectors/track, 2431 cylinders
   Units = cylinders of 16065 * 512 = 8225280 bytes
   
      Device Boot    Start       End    Blocks   Id  System
   /dev/sda1   *         1         1      8001    0  Empty
   /dev/sda2   *         6      2431  19486845    b  Win95 FAT32
   /dev/sda3             2         5     32130   83  Linux
   
   Partition table entries are not in disk order
   

8. If everything looks OK, write out the partition table.

   Command (m for help): w

9. fdisk will now exit and we can create the new filesystem.

   # mke2fs -j /dev/sda3

10. Set the maximal mount count to never.

    # tune2fs -c 0 /dev/sda3
tune2fs 1.34 (25-Jul-2003)
Setting maximal mount count to -1

To install the kernel you need the iPod Boot Loader, a version of the iPod Linux Kernel and the iPod operating system backup created earlier in the backup process.

Firstly extract the ipodloader and iPod Linux kernel archives into a working directory and check for any last minute release notes. In the examples below the make_fw tool and loader.bin file are from the ipodloader distribution and the iPod Linux kernel version is uclinux-2.4.24-ipod0.bin.

1. Extract the Apple OS from the backup image.

   # make_fw -o apple_os.bin -e 0 ipod_os_partition_backup

2. Create a new image including the Linux and the Apple OS.

   # make_fw -o my_sw.bin -l uclinux-2.4.24-ipod0.bin -i apple_os.bin loader.bin

3. Copy the new image (which is about 4-5 MB in size) back to your iPod.

   # dd if=my_sw.bin of=/dev/sda1

4. Copy the kernel modules onto the iPod (note the directory /mnt/ipod must exist and should not be in use). The lib directory below refers to the directory from the kernel release and contains the modules directory.

   # mount -t ext2 /dev/sda3 /mnt/tmp
# cp -r lib /mnt/tmp # umount /mnt/tmp

The iPod Linux Userland contains the operating system tools and libraries (including the podzilla and mp3 applications). This archive should be installed on the root partition of your iPod as created during the partition step above.

1. Mount your iPod root partition.

   # mount -t ext2 /dev/sda3 /mnt/tmp


2. Extract the root filesystem.

   # cd /mnt/tmp
# tar zxf /tmp/ipod_fs_040403.tar.gz


3. Update the root filesystem with the latest kernel modules.

   # tar zxf /tmp/uclinux-2.4.24-ipod0.tar.gz lib


4. Unmount your iPod root partition.

   # umount /mnt/tmp


Finishing up

The current release contains a number of usability bugs that can be resolved by executing the following commands.

1. Mount your iPod root partition.

   # mount -t ext2 /dev/sda3 /mnt/tmp


2. Fixes for /etc/rc. Replace /mnt/tmp/etc/rc with the following:

   hostname ipod
mount -t proc proc /proc
ln -s /dev/pty/m0 /dev/ptyp0
ln -s /dev/pty/m1 /dev/ptyp1
ln -s /dev/ide/host0/bus0/target0/lun0/disc /dev/hda
ln -s /dev/ide/host0/bus0/target0/lun0/part2 /dev/hda2
ln -s /dev/ide/host0/bus0/target0/lun0/part3 /dev/hda3
ln -s /dev/tts/1 /dev/ttyS1
mknod /dev/ttyp0 c 3 0
mknod /dev/ttyp1 c 3 0
modprobe tsb43aa82
modprobe eth1394
ifconfig eth0 192.168.222.2 mtu 170
mount -t vfat -o ro /dev/hda2 /mnt
mount -o remount,rw /dev/hda3 /
hdparm -S 3 /dev/hda

3. Fixes for /etc/inittab. Replace /mnt/tmp/etc/inittab with the following:

   inet:unknown:/bin/inetd
pz:unknown:/bin/podzilla

4. Unmount your iPod root partition.

   # umount /mnt/tmp


5. Eject your iPod. The following command will unload the firewire driver for your iPod. Once unloaded your iPod will either reboot automatically or display the "OK to disconnect." message.

   # modprobe -r sbp2


6. Reboot your iPod. If the iPod did not automatically reboot hold down the menu and the play/pause buttons for 3 seconds to reboot it.

Using the configuration above on reboot your iPod will automatically start Linux. You should see the Tux logo and then the normal Linux boot console messages will scroll by. Once the operating system is booted the Podzilla application will start. This work-in-progress interface mimics the Apple interface.

When you are finished with Linux you can reboot the iPod by holding down the menu and play/pause buttons for 3 seconds. When the Apple logo appears hold down the rewind button to start the Apple firmware.

Upgrading

To upgrade to a new version of the kernel simply repeat the process in the Kernel Installation section.

To upgrade to a new version of the user tools simply repeat the process in the Userland Installation section.

To install a new version of podzilla simply copy the new podzilla binary to your iPod:

# mount -t ext2 /dev/sda3 /mnt/tmp
# cp podzilla /mnt/tmp/sbin
# umount /mnt/tmp


Uninstalling iPod Linux

To completely remove Linux from your iPod you should restore the original firmware partition and MBR from your backup files.

# dd if=ipod_boot_sector_backup of=/dev/sda
# dd if=ipod_os_partition_backup of=/dev/sda1


This section of the guide details how to install Linux on your iPod using a Mac OSX based PC. To use this portion of the guide your iPod must be formatted with the HFS+ filesystem (this is the default for Mac-iPods).

Locating your iPod

With OSX your iPod should be automatically mounted when you plug it into your Mac. To determine the device name:

Start the Terminal application, and run the mount command.

# mount
/dev/disk1s3 on /Volumes/iPod (nodev, nosuid, mounted by leachbj)

The /dev/disk1s3 portion indicates the iPod is the first SCSI device and so will be visible as /dev/disk1, if on your system you see /dev/disk2s3 then your iPod would be using device /dev/disk2. In the above example the volume is mounted as /Volumes/iPod. The iPod portion will be the name of your iPod.

The following example commands will use disk1 as the device for the iPod and /Volumes/iPod for the mount point, please replace these with the corrects values for you configuration.

Backup

The backup file is a complete backup of the operating system partition on the iPod and includes the Apple iPod operating system (this file is 40MB and can be compressed once the installation process is complete).

# dd if=/dev/disk1s2 of=ipod_os_partition_backup


Should you need to restore the backup for any reason simply use the following commands.

# dd if=ipod_os_partition_backup of=/dev/disk1s2


Note, if you want to upgrade the Apple firmware then you should firstly restore the iPod operating system backup.

It is also possible to completely restore your iPod to its factory state by using the restore program from Apple. This will restore the original operating system to your iPod. Unfortunately this will mean any settings or music will have to be copied back to your iPod.

Kernel Installation

To install the kernel you need the iPod Boot Loader, a version of the iPod Linux Kernel and the iPod operating system backup created earlier in the backup process.

Firstly extract the ipodloader and iPod Linux kernel archives into a working directory and check for any last minute release notes. In the examples below the make_fw tool and loader.bin file are from the ipodloader distribution and the iPod Linux kernel version is uclinux-2.4.24-ipod0.bin.

1. Extract the Apple OS from the backup image.

   # make_fw -o apple_os.bin -e 0 ipod_os_partition_backup

2. Create a new image including the Linux and the Apple OS.

   # make_fw -o my_sw.bin -l uclinux-2.4.24-ipod0.bin -i apple_os.bin loader.bin

3. Copy the new image (which is about 4-5 MB in size) back to your iPod.

   # dd if=my_sw.bin of=/dev/disk1s2

4. Copy the kernel modules onto the iPod. The lib directory below refers to the directory from the kernel release and contains the modules directory.

   # cp -r lib /Volumes/iPod

The iPod Linux Userland contains the operating system tools and libraries (including the podzilla and mp3 applications). This archive should be installed on your normal iPod filesystem.

Extract the root filesystem onto the iPod.

# cd /Volumes/iPod
# tar zxf /tmp/ipod_fs_040403.tar.gz