Installation from Linux

From wikiPodLinux

Table of contents

Outdated

This article may be a bit outdated. It is recommended that you start at the Installation page.

Overview

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+ and you are trying to install from Linux (it's recommended to do this from OSX), follow the HOWTO here (http://www.ipodlinux.org/Installation_from_Linux_Hfsplus). Another option is to reformat your iPod as FAT32 (if you can deal with extremely slow FAT32 read/write speeds on OS X).


Note: with Linux it is necessary to have read and write permission on the raw device files for the iPod. This most likely means you need to be root.

Oct 22, 2006: Please note, the below instructions will NOT work for Fedora Core 4 and 5 Linux distros! If you have FC4/5, please use a Linux Live! distro (such as Slax Linux Live) that you can boot from a CD.

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, your iPod would be using device /dev/sdb. The following example commands will use "sdX" as the device for the iPod; please replace this with the correct device for you configuration. If you use the wrong device, you might accidentally write to your computer's hard drive! This actually happened to someone!

Backup

Since we will update the partition information and replace the firmware image, we will now 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. If you make a mistake in partitioning, you can use this to recover. 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 (80MB on the 5G models) and can be compressed once the installation process is complete.

# dd if=/dev/sdX of=ipod_boot_sector_backup bs=512 count=1
# dd if=/dev/sdX1 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/sdX
# sfdisk -R /dev/sdX                      (rereads the partition table)
# dd if=ipod_os_partition_backup of=/dev/sdX1

Note: if you want to upgrade the Apple firmware then you should first 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 WinPods as Linux cannot use a FAT partition for its root file system.

Partitioning instructions differ between 1G/2G/3G/4G/Photo/Mini and Nano/5G (Video). This is because the Nano and Video have a software suspend-to-disk feature that kicks in after 12 hours of inactivity, writing the contents of RAM to the firmware partition. Because this uses practically all the space in the firmware partition, we can't use that space for Linux like we can for the older generations; if we did, we would see filesystem corruption whenever suspend-to-disk kicked in.

The alternative, however, requires us to delete and recreate the music partition with a smaller size, and put the Linux partition after it, at the end of the disk. This is not the best solution, mainly because you lose all the data on that partition, but there's not really any good alternative. If you have a Nano or Video, PLEASE ensure that all data on the music partition of your iPod is backed up! It will be lost!

1G–4G, Mini, and Photo

First, you need to figure out how big to make your Linux partition. Partition sizes are measured in terms of cylinders, whose size is printed when fdisk starts. (You might see something like the following, which would indicate 8MB cylinders.)

Units = cylinders of 16065 * 512 = 8225280 bytes

In general, you want to make your Linux partition as big as you can without making the firmware one too small; generally the best results are achieved by splitting it roughly in half. Guidelines for specific iPods follow:

  • For an iPod with a 33-cylinder firmware partition (most 3Gs and all 2Gs and 1Gs), try shrinking it to 10 cylinders and creating the Linux partition from 11 to 33.
  • For a 4G, Photo, or any other iPod that has a 5-cylinder firmware partition, try keeping the firmware partition as 1–2 and making the Linux one from 3–5.
  • If your firmware partition is neither 33 nor 5 cylinders, try splitting it roughly in half; ask us if you have questions.
  • If your firmware partition is bigger than 100 cylinders, you've got the wrong disk! Leave fdisk without saving changes ("q" command) and take another look at /proc/scsi/scsi. See above.

Note: the output displayed below is correct for a 20GB 3g iPod; some output will be different for different sized iPods and different iPod generations. Your iPod has to be unmounted in order to successfully complete operation number 8, so unmount it before beginning to work on it.

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 format for use with Linux.

Before you start make sure that the ipod partitions are not mounted.

# umount /dev/sdX2

1. Start fdisk.

# fdisk /dev/sdX
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. Recreate the firmware partition with a smaller size.

Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 1
First cylinder (1-19073, default 1): 1
Last cylinder or +size or +sizeM or +sizeK (1-33, default 33): use value you figured out above
(Note, on the iPod Nano this partition ends in cylinder 4 instead of '10'.)

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 to fill the space you just freed up.

Command (m for help): n
Command action
e extended
p primary partition (1-4)
p
Partition number (1-4): 3
First cylinder (1-19073, default 1): value you entered for last cylinder of partition 1, plus 1
Last cylinder or +size or +sizeM or +sizeK (1-19073, default 33): press enter

7. Review the changes. Note: this is for a 20GB 3G iPod; for other iPod versions, cylinder numbers may vary. Ensure that sda1 starts at cylinder 1, that the end cylinder of sda1 is one less than the start cylinder of sda3, that the end cylinder of sda3 is one less than the start cylinder of sda2, and that both sda1 and sda2 are active and all partitions have the listed types.

Command (m for help): p

Disk /dev/sda: 64 heads, 32 sectors, 19073 cylinders
Units = cylinders of 2048 * 512 bytes

  Device Boot    Start       End    Blocks   Id  System
/dev/sda1   *         1        10     10224    0  Empty
/dev/sda2   *        34     19073  19496960    b  Win95 FAT32
/dev/sda3            11        33     23552   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/sdX3

10. Set the maximal mount count to never.

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

Nano, Video, or Big Linux Partition

Remember, these instructions will cause all data on the iPod to be lost!

These instructions are applicable if you have a Nano or a Video (5G), or if you want an unusually large Linux partition on older iPods. In this case, the amount of space to allocate is completely up to you. We will start by deleting the music partition and creating a smaller one in its place; then, we will make a new partition for iPodLinux that uses the now-freed space after the music partition.

An example session is below. Things you should type look like this; placeholders you should replace with an actual value look like this, and output looks like this. If I say [*] or [#] should be entered, it refers to the value above that marked by that mark.

Before you start make sure that the ipod partitions are not mounted.

# umount /dev/sdX2

1. Start fdisk.

# /sbin/fdisk /dev/sdX

The number of cylinders for this disk is set to 7296.
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)

You can ignore this warning.

2. Check the current partition table.

Command (m for help): p

Disk /dev/sdX: 60.0 GB, 60011642880 bytes
255 heads, 63 sectors/track, 7296 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes

   Device Boot      Start         End      Blocks   Id  System
/dev/sdX1   *           1          14      112423+   0  Empty
/dev/sdX2   *          15 [*]    7296    58492665    b  W95 FAT32

This is what your partition table should look like now. The sizes may be different, though; these values are for a 60GB 5g. Remember the value of Start for sdX2!

3. Delete the music partition.

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

4. Create a new, smaller one in its place.

Command (m for help): n
Command action
   e   extended
   p   primary partition (1-4)
p
Partition number (1-4): 2
First cylinder (1-7296, default 1): [*] above
Last cylinder or +size or +sizeM or +sizeK (15-7296, default 7296): see below [#]

The value for "last cylinder" in this case determines the size of your music partition and, thus, the size of your Linux partition as well. On earlier models, each cylinder is about 8MB; do the math. Take the size of your iPod in MB, subtract about 128 MB for Linux, and divide by 8.

For later iPods, it's a good idea to calculate the amount of storage per cylinder. Roughly divide the iPod's total storage, in megabytes (80GB = 80,000MB) over the total number of cylinders. For example, the latest 80GB iPod (3-15-07) has 2,432 cylinders, so the storage per cylinder is 32.89MB, or roughly 32MB. It is more likely that the total storage falls short of 80GB and that 32MB is the accurate measure.

5. Create the Linux partition.

Command (m for help): n
Command action
   e   extended
   p   primary partition (1-4)
p
Partition number (1-4): 3
First cylinder (1-7296, default 1): [#] above, plus 1
Last cylinder or +size or +sizeM or +sizeK (7001-7296, default 7296): press Enter
Using default value 7296    this may vary

6. Mark the new music partition bootable.

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

7. Change its type to the right one.

Command (m for help): t
Partition number (1-4): 2
Hex code (type L to list codes): b
Changed system type of partition 2 to b (W95 FAT32)

8. Print out the partition table to verify that everything is OK.

Command (m for help): p

Disk /dev/sdX: 60.0 GB, 60011642880 bytes
255 heads, 63 sectors/track, 7296 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes

   Device Boot      Start         End      Blocks   Id  System
/dev/sdX1   *           1          14      112423+   0  Empty
/dev/sdX2   *          15        7000    56115045    b  W95 FAT32
/dev/sdX3            7001        7296     2377620   83  Linux

Your partition table will not look exactly like this one. Things you should check at this point:

  • The end cylinder for sdX1 should be one less than the start cylinder for sdX2; the same should be true for the end cylinder of sdX2 and the start of sdX3.
  • Only the first two partitions are marked as bootable.
  • Your music partition (sdX2) is the size you want. (Look at the Blocks field; it's measured in kilobytes.)
  • Each partition has the same ID as the ones in this table. (0, b, and 83 respectively.)

If any of this looks wrong, quit fdisk by typing q at the prompt.

9. Otherwise, write the new partition table; fdisk will exit.

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.
Syncing disks.

If fdisk does not exit with the above message but instead with the below message:

Command (m for help): w
The partition table has been altered!

Calling ioctl() to re-read partition table.

WARNING: Re-reading the partition table failed with error 16: Device or resource busy.
The kernel still uses the old table.
The new table will be used at the next reboot. 

WARNING: If you have created or modified any DOS 6.x
partitions, please see the fdisk manual page for additional
information.
Syncing disks.

then do the following (or skip the following and just reboot your ipod but rebooting might be unsafe:)

# umount /dev/sdX2
# eject /dev/sdX

Then your ipod should reboot itself, if it does not, force the reboot. Reconnect your ipod for the following steps.

10. Create the Linux partition, and recreate the music one. Note: before recreating the music partition, try running your ipod first. Since you didn't move the starting cylinder and if your partition was not full, it probably will contain your old music files intact. In that case don't do mkdosfs or you will lose your music.

# mkdosfs -F 32 /dev/sdX2
mkdosfs 2.10 (22 Sep 2003)
# mke2fs /dev/sdX3
a bunch of output snipped...

11. Set the maximal mount count to never.

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

Kernel Installation

To install the kernel you need the iPod boot loader, a version of the iPod Linux Kernel (https://sourceforge.net/project/showfiles.php?group_id=73079&package_id=73283) and the iPod operating system backup created earlier in the backup process.

You are strongly encouraged to grab a nightly kernel (http://www.ipodlinux.org/builds) (get the latest), since it may contain fixes that haven't made it into a release yet.

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 (note: this means that they're quite outdated because there's a new make_fw as well as a new bootloader) and the iPod Linux kernel version is uclinux-2.4.24-ipod2.bin.

1. Extract the Apple OS from the backup image.

# ./make_fw -o apple_os.bin -e 0 ipod_os_partition_backup

If you cannot extract the Apple OS, you may have a corrupt image, possibly due to a bad hard drive. You can extract the image from the iPod updater supplied by Apple under Windows. This is useful if the hard drive is bad, but still accepts the Apple firmware without problems.

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

If you have a 5G, please see the Loader 2 page.

To make the Apple firmware the default, use

# ./make_fw -g gen -o my_sw.bin -i apple_os.bin -l uclinux-2.4.24-ipod2.bin loader.bin (4g+)

To make Linux the default:

# ./make_fw -g gen -o my_sw.bin -l uclinux-2.4.24-ipod2.bin -i apple_os.bin loader.bin (4g+)

gen can be one of these:

1g, 2g, 3g, 4g (scroll, touch, dock, click), mini, photo, nano, 5g (video)

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

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

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.
(This step is not needed on 4G+ iPods, nor if you downloaded a nightly kernel.)

# mkdir /mnt/ipod
# mount -t ext2 /dev/sdX3 /mnt/ipod
# cp -r lib /mnt/ipod
# umount /mnt/ipod

Userland Installation

The iPodLinux Userland contains the operating system tools and libraries (including podzilla). Download ipod_fs_240206.tar.gz (http://so2.sys-techs.com/ipod/ipod_fs_240206.tar.gz) to get a default userland file tree. 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/sdX3 /mnt/ipod

2. Extract the root filesystem.

# cd /mnt/ipod
# tar zxpf /tmp/ipod_fs_240206.tar.gz

3. Update the root filesystem with the latest kernel modules (for 3Gs and below using release kernels only).

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

4. Leave your iPod root partition.

# cd ..

5. Unmount your iPod root partition.

# umount /mnt/ipod

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 ext3 /dev/sdX3 /mnt/ipod

2. The included podzilla was built on 2006-02-24 from CVS. If this is a bit outdated you may want to update it to newest beta release from here (http://ipodlinux.sourceforge.net/download/beta/), or a nightly release (newer, possibly buggier) from here (http://www.ipodlinux.org/builds/):

# cd /mnt/ipod/bin
# mv podzilla podzilla.old

For a beta:

# wget http://ipodlinux.sourceforge.net/download/beta/podzilla.gz
# gunzip podzilla.gz
# chmod +x podzilla

For a nightly:

# wget http://www.ipodlinux.org/builds/YYYY-MM-DD-podzilla.gz
# gunzip YYYY-MM-DD-podzilla.gz
# mv YYYY-MM-DD-podzilla podzilla
# chmod +x podzilla

3. Unmount your iPod root partition.

# cd /
# umount /mnt/ipod

4. 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 (for a FireWire connected iPod)
# eject /dev/sdX   (for one connected via USB)

5. Reboot your iPod. If your iPod did not automatically reboot, hold down the menu and the play/pause buttons for 3 seconds (if it's a 3g or below) or menu and center (if it's a 4g or above) to reboot it. Your iPod will automatically start the default OS you specified above. You should see the Tux logo and then the default OS should start.

After a reboot, if you want boot into the other OS, hold down the rewind button when the Apple logo appears.

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 ext3 /dev/sdX3 /mnt/ipod
# cp podzilla /mnt/ipod/sbin
# chmod +x /mnt/ipod/sbin/podzilla
# umount /mnt/ipod

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/sdX
# dd if=ipod_os_partition_backup of=/dev/sdX1
Views
Personal tools
Toolbox