Setting up an iPod MA978 on Linux

by Paul Zarucki, 2008-09-23.


I wanted to set up a friend's iPod on Linux. The iPod was supplied in Mac format and must be re-formatted. This is typically done using a suitable Mac or Windows computer but I don't have either of these, just Linux. There are published instructions for setting up an iPod using Linux but they don't seem to apply to this model as they refer to a firmware file which, as far as I can see, doesn't exist on this iPod. According to the iPod display, it is a model "MA978 version 1.1 Mac" (although the number shown on the case is A1236).

This is my recipe for setting up an MA978 Mac-format iPod on Debian 4.0 GNU/Linux, based on information gleaned from the web (see references at the end of this document).

NOTE: Some of the discussion in this recipe is fairly technical, although you may be able to follow the procedure even if you don't grasp all of the technicalities. It worked for me, but I take no responsibility for any consequences if it doesn't work for you! Some steps, if carried out incorrectly, have the potential to erase your hard disc or iPod.

If you are new to the command line, I highly recommend the beginner's introduction by Rosalyn Hunter.
Software Used
I use the Debian 4.0 GNU/Linux system but the methods described here should work on most GNU/Linux with some modification. The references to copy-and-paste assume you are using an X-windows based graphical desktop system (I use Gnome but the principles apply to almost any of the desktop systems available for GNU/Linux and Unix).

Command Line
This tutorial makes use of the command line. If you are only used to point-and-click methods, don't be afraid! The command line is your friend and, for some tasks, it is quicker and easier than the available graphical software. To start typing commands, open a console or terminal window (if you are using the Gnome desktop look under Applications -> Accessories -> Terminal).
   You can copy-and-paste each command from this page into the console window then edit it to suit your needs before pressing the return key. The left and right arrow keys move the cursor, the delete and backspace keys delete text. Anything you type or paste will be inserted at the cursor position.
   TIP: to copy, select some text with the mouse then, to paste, simply move the mouse to the destination and middle-click (press either the middle button or the scroll wheel on your mouse).

Overview

As supplied, the iPod uses an HFS+ file system with journalling enabled. The Linux kernel has support for HFS+ but it is read-only if the HFS+ file system uses journalling. In order to use the iPod with Linux, we must re-format its data partition with journalling disabled.

In essence the procedure is as follows:
  1. Back up the iPod.
  2. Re-format the iPod's data partition using HFS+ with journalling disabled.
  3. If the iPod contained music that you want to keep then restore the files from the backup.
In reality, I like to include additional steps before and after step 2, as follows:
  1. Back up the iPod.
  2. Erase the iPod's data partition.
  3. Re-format the iPod's data partition using HFS+ with journalling disabled.
  4. Make a compressed backup of the iPod's entire 'disc'.
  5. If the iPod contained music that you want to keep then restore the files from the backup.
The additional steps (2 & 4) create a very compact compressed backup file (4MB for a 4GB iPod) from which the iPod can be restored to a 'clean' state at any time. With this file, I can restore the iPod on any Linux machine without installing additional software or going through a lengthy set up procedure. This might, for example, come in handy if I the iPod's data became corrupted, for example, due to faulty software, a bad connection or an untimely power cut rendering the iPod unusable.

NOTE: the amount of free disc space you will need for this recipe is twice the iPod capacity (e.g. 8GB for a 4GB iPod).

Step 1 - preliminaries

Open a terminal window into which you can type commands. With the following commands we create a directory for this work, change to that directory and become the root user:

mkdir ipod
cd ipod
su root

Step 2 - plug the iPod into the computer

Make sure your graphical desktop system is not set to automatically mount removable storage devices (or log out of the GUI completely and use a text console). Then plug the iPod into the computer (I am using a USB cable but FireWire should work also).

Step 3 - find the iPod's device node and data partition

In order to re-format the iPod, we need to know the device node to which it is attached and which of its partitions holds the data files (music, etc.). The output of the dmesg command reveals the device node and the partition numbers (for clarity, I have indented the lines printed by the computer):

dmesg | tail -n 18
usb 6-1: new high speed USB device using ehci_hcd and address 36
usb 6-1: configuration #1 chosen from 2 choices
scsi39 : SCSI emulation for USB Mass Storage devices
usb-storage: device found at 36
usb-storage: waiting for device to settle before scanning
  Vendor: Apple     Model: iPod              Rev: 1.62
  Type:   Direct-Access                      ANSI SCSI revision: 00
SCSI device sda: 950209 4096-byte hdwr sectors (3892 MB)
sda: Write Protect is off
sda: Mode Sense: 68 00 00 08
sda: assuming drive cache: write through
SCSI device sda: 950209 4096-byte hdwr sectors (3892 MB)
sda: Write Protect is off
sda: Mode Sense: 68 00 00 08
sda: assuming drive cache: write through
 sda: [mac] sda1 sda2
sd 39:0:0:0: Attached scsi removable disk sda
usb-storage: device scan complete

We see that the iPod is attached to device node /dev/sda and that it has two partitions (the line "sda: [mac] sda1 sda2" third from the end where I assume that "[mac]" means a Mac style partition table was found).

The normal way to find the partition sizes would be to use either the fdisk or parted command, but neither of these worked with this iPod, so I resorted to trial-and-error using the mount command:

mkdir ipod_data   # (create a temporary mount point for the iPod)
mount -v -t hfsplus /dev/sda1 ipod_data
mount: wrong fs type, bad option, bad superblock on /dev/sda1,
       missing codepage or other error
       In some cases useful info is found in syslog - try
       dmesg | tail  or so

No luck with /dev/sda1, let's try /dev/sda2:

mount -v -t hfsplus /dev/sda2 ipod_data
/dev/sda2 on /home/paul/ipod/ipod_data type hfsplus (rw)

Success! I'll use the df command to find the size of the file system on /dev/sda2:

df -h | grep sda
/dev/sda2             3.7G  112M  3.6G   4% /home/paul/ipod/ipod_data

That's a 3.7GB file system which corresponds well with the capacity of this iPod (4GB). Just to be sure, lets look at the contents of the iPod's directory:

ls ipod_data
Calendars  Contacts  iPod_Control  Notes  Photos  Recordings

That seems to correspond with the normal directory structure for an iPod's data partition so I think it is safe to assume that the data partition on this iPod is /dev/sda2.

From here on, replace every occurance of /dev/sda and /dev/sda2 with the appropriate choices for your iPod.

Step 4 - unmount the iPod

Unmount the iPod's data partition before continuing:

umount ipod_data

Step 5 - back up the iPod

Before doing anything else to the iPod, I'd like to play safe and make a complete backup of the iPod's 'disc' (actually a flash memory chip). I'd also like to make a separate backup of the iPod's data partition. This will give me two files, each having a size equal to the iPod's capacity.

The following command makes a backup of the iPod's 'disc' (/dev/sda in my case):

dd if=/dev/sda of=ipod.bin
7601672+0 records in
7601672+0 records out
3892056064 bytes (3.9 GB) copied, 385.37 seconds, 10.1 MB/s

As you can see, the backup took 385 seconds, or about 6 minutes, to complete.

Next I back up the iPod's data partition (/dev/sda2 in my case):

dd if=/dev/sda2 of=ipod_data.bin
7601160+0 records in
7601160+0 records out
3891793920 bytes (3.9 GB) copied, 386.295 seconds, 10.1 MB/s

The ls -lh command shows the resulting backup files and their sizes:

ls -lh
total 7.3G
-rw-r--r-- 1 root root 3.7G 2008-08-03 13:09 ipod.bin
drwxr-xr-x 2 root root 4.0K 2008-08-03 13:02 ipod_data
-rw-r--r-- 1 root root 3.7G 2008-08-03 13:23 ipod_data.bin

Each backup file is 3.7GB in size.

Step 6 - install some needed software

Since the Mac-format iPod uses the HFS+ file system, we need to install some new software which will enable us to re-format the data partition with a new HFS+ file system which has journalling disabled. The software must be downloaded as source code and compiled using version 3.4 of the GNU Compiler.

The following command installs version 3.4 of the GNU Compiler, along with libssl-dev which we also need.

apt-get install gcc-3.4 libssl-dev

Temporarily switch from gcc4.1 to gcc3.4:

rm /usr/bin/gcc
rm /usr/bin/gccbug
ln -s /usr/bin/gcc-3.4 /usr/bin/gcc
ln -s /usr/bin/gccbug-3.4 /usr/bin/gccbug

Return to being your normal user:

exit

Download the source code for Apple's HFS+ file system utilities and a patch which makes Apple's code work under Linux:

wget ftp://ftp.fi.debian.org/pub/gentoo/distfiles/diskdev_cmds-332.14.tar.gz
wget ftp://ftp.fi.debian.org/pub/gentoo/distfiles/diskdev_cmds-332.14.patch.bz2

NOTE: Ref. [1] says that this software is not x86_64 compatible but it worked for me on my AMD64 machine, which runs Debian 4.0 for AMD64. This might be because I have the ia32-libs and linux32 packages installed (but I don't really know).

Extract the source code and apply the patch:

tar zxf diskdev_cmds-332.14.tar.gz
bunzip2 -c diskdev_cmds-332.14.patch.bz2 | patch -p0

Compile the source code:

cd diskdev_cmds-332.14
make -f Makefile.lnx

Become the root user and install the software:

su root
cp newfs_hfs.tproj/newfs_hfs /sbin/mkfs.hfsplus
cp fsck_hfs.tproj/fsck_hfs /sbin/fsck.hfsplus
chmod a+x /sbin/*hfsplus
ln -s /sbin/mkfs.hfsplus /sbin/mkfs.hfs
ln -s /sbin/fsck.hfsplus /sbin/fsck.hfs

Restore gcc 4.1 and return to the ipod directory:

rm /usr/bin/gcc
rm /usr/bin/gccbug
ln -s /usr/bin/gcc-4.1 /usr/bin/gcc
ln -s /usr/bin/gccbug-4.1 /usr/bin/gccbug
cd ../

Step 7 - erase the iPod's data partition (optional)

If we now erase the iPod's data partition, we will later be able to create a compressed backup (see below). The compressed backup allows us to quickly re-format the iPod, restoring it to a clean state, complete with its directory structure and SysInfo file (see below), at any time in the future.

First we find the size of the data partition (in units of 1K byte) from the backup file we created earlier:

ls -l --block-size=1024 ipod_data.bin
-rw-r--r-- 1 root root 3800580 2008-08-03 13:23 ipod_data.bin

In this case the size is 3800580K bytes. We can now erase the data partition using following command:

dd if=/dev/zero of=/dev/sda2 bs=1024 count=3800580
3800580+0 records in
3800580+0 records out
3891793920 bytes (3.9 GB) copied, 999.212 seconds, 3.9 MB/s

As you can see, this operation took 999 seconds, or about 17 minutes, to complete.

Step 8 - re-format the iPod's data partition

The following command re-formats the iPod's data partition, creating a new HFS+ file system with journalling disabled:

mkfs.hfs -v iPod /dev/sda2
Initialized /dev/sda2 as a 3712 MB HFS Plus volume

Step 9 - create the iPod directory structure

We now have a blank, re-formatted, iPod and will have to create the iPod's directory structure. Fortunately, the iPod can do this for us!  All we have to do is eject the iPod and wait 30 seconds or so:

eject /dev/sda2

A short time after being ejected, the iPod will create the directory structure and display its menu.

Let's just check that the iPod directories have been created. Unplug the iPod, wait 5 seconds, plug it back into the computer, wait another 5 seconds or so, then type the following commands:

mount -v -t hfsplus /dev/sda2 ipod_data
/dev/sda2 on /home/paul/ipod/ipod_data type hfsplus (rw)
ls ipod_data
Calendars  Contacts  iPod_Control  Notes  Photos  Recordings
umount ipod_data

Those seem to be the correct directories!

ALTERNATIVE METHOD: If your iPod doesn't create the directory structure automatically then try the following procedure using the program gtkpod (both methods worked for me).

NOTE: If you are using the 64-bit version of Debian 4.0, you must first install updated versions of gtkpod and libgpod. See near the end of this document for instructions on how to do this.

Get things ready for gtkpod:

mkdir /media/iPod   # (create a mount point where gtkpod expects to find it)
chmod a+rw /media/iPod   # (make the mount point world-writable)
mount -v -t hfsplus /dev/sda2 /media/iPod   # (mount the iPod)
chmod a+rw /media/iPod   # (make the iPod world-writable)

Start gtkpod as a normal user (Applications -> Sound & Video -> gtkpod if you are using the Gnome desktop). Right-click the iPod in the left panel of gtkpod (assuming it is listed there) and select "Load iPod" from the pop-up menu. A dialogue box appears asking if you want to create new iPod directories. Click Yes. Gtkpod will complain that it can't find the iPod firewire ID, but don't worry, it will create the directories nonetheless!

Close gtkpod then type the following commands:

umount /dev/sda2
rmdir /media/iPod
eject /dev/sda2

Step 10 - create the SysInfo file and make the iPod files world-writable

The software for using the iPod on Linux requires a small text file, called SysInfo, to be installed on the iPod containing the iPod's serial number and model number. The model number is the one found from the iPod's menu, with the leading "M" replaced by "x", giving xA978 in my case.

The iPod's serial number can be obtained with the lsusb command. Unplug the iPod from the computer for 5 seconds then plug it in again. Wait a further 5 seconds then type the following command:

lsusb -v | grep -i serial
  iSerial                 3 000A27001B5A0ECA
  iSerial                 1 0000:00:13.5
  iSerial                 1 0000:00:13.1
  iSerial                 1 0000:00:13.0
  iSerial                 1 0000:00:13.3
  iSerial                 1 0000:00:13.2
  iSerial                 1 0000:00:13.4

The resulting list has quite a few numbers but the one we want is the 16 digit number (000A27001B5A0ECA in my case).

Armed with the model and serial numbers we can now install the SysInfo file on the iPod.

First we mount the iPod's data partition:

mount -v -t hfsplus /dev/sda2 ipod_data

Create the SysInfo file if it doesn't already exist:

touch ipod_data/iPod_Control/Device/SysInfo

Make sure the iPod files are world-writable:

chmod -R a+rw ipod_data

We need to put the following text into the SysInfo file:

ModelNumStr: xA978
FirewireGuid: 0x000A27001B5A0ECA

Note that the 16 digit serial number must be preceded by "0x". You can open the file ipod_data/iPod_Control/Device/SysInfo in a text editor and copy-and-paste the above text (replacing "000A27001B5A0ECA" with the serial number of your iPod). Alternatively, you can type the following commands to add the text to the SysInfo file:

echo "ModelNumStr: xA978" > ipod_data/iPod_Control/Device/SysInfo
echo "FirewireGuid: 0x000A27001B5A0ECA" >> ipod_data/iPod_Control/Device/SysInfo

where "000A27001B5A0ECA" should be replaced by the serial number of your iPod.

Now all we have to do is tidy up:

umount ipod_data
eject /dev/sda2

Step 11 - make a compressed backup of the iPod (optional)

Provided you carried out step 7 (erase the iPod's data partition), you now have the option of making a compressed backup of the iPod. The following command creates the compressed backup:

dd if=/dev/sda | gzip > ipod_clean.bin.gzip
7601672+0 records in
7601672+0 records out
3892056064 bytes (3.9 GB) copied, 384.997 seconds, 10.1 MB/s

The result is a file containing a complete backup of the iPod's 'disc' but occupying about 1/1000 as much space  (3.7MB instead of 3.7GB):

ls -lh ipod_clean*
-rw-r--r-- 1 root root 3.7M 2008-08-03 21:06 ipod_clean.bin.gzip

How to use the Compressed Backup

Any time you want to restore the iPod to its clean state, make sure your graphical desktop system is not set to automatically mount removable storage devices then plug the iPod into the computer and type the following commands (as root user):

umount /dev/sda2   # (make double-sure the iPod is not mounted)
cat ipod_clean.bin.gzip | gunzip > /dev/sda
eject /dev/sda2   # (eject the iPod)

You should now be able to use the iPod normally (remember to restore your desktop settings for removable storage and multimedia devices).

Step 12 - restore the iPod files (optional)

If the iPod contained music files that you wish to keep then you can now restore these from the backup. Type the following commands (as root user) to restore the iPod files:

mkdir ipod_backup   # (create a temporary mount point)
mount -v -t hfsplus -o loop ipod_data.bin ipod_backup
mount -v -t hfsplus /dev/sda2 ipod_data
# (/dev/sda2 is my iPod's data partition - change if your's is different)
cp -a ipod_backup/* ipod_data
chmod -R a+rw ipod_data  # (make the iPod files world-writable)
umount ipod_backup
umount ipod_data

Step 13 - install updates for 64-bit systems

If you are using the 64-bit version of Debian 4.0, you will need to install updated versions of libgpod3 and any programs you want to use, such as gtkpod, that depend upon libgpod (the default version of libgpod doesn't work on 64-bit Linux, at least not for me with this iPod).

Add the following line to your list of package repositories (edit the file /etc/apt/sources.list):

deb http://www.backports.org/ etch-backports main contrib

Then type the following commands:

apt-get update
apt-get -t etch-backports install gtkpod

libgpod3 will be installed automatically because the updated gtkpod depends upon it.

Using the iPod

You should now be able to use the iPod normally. All that remains to make it plug-and-play is to adjust your desktop settings to auto-mount removable media and run gtkpod (or whichever alternative you prefer) when the iPod is detected. If you use the Gnome desktop, look under Desktop -> Preferences -> Removable Drives and Media.

References

  1. http://gentoo-wiki.com/HOWTO_hfsplus - HOWTO hfsplus
  2. http://people.csail.mit.edu/adonovan/hacks/ipod.html - using an iPod with Linux
  3. http://amarok.kde.org/wiki/Media_Device:IPod - using an iPod with Amarok
  4. http://forums.debian.net/viewtopic.php?p=150381&sid=a21aeacfc289ea06ab640cd51bea24bb - using an iPod with Amarok

Change Log

2008-09-23: first version.

Comments welcome! -- read people's comments on this article and add your own comments if you like.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.