Apple iPod, iPad, iPhone

This is a placeholder for a more comprehensive article on how to manage an Apple device on a Gentoo system. The goal is to mount the iPod/iPhone/iPad somewhere so that it can be interfaced with by other tools, such as or  or others. It also shows how to copy files to the iDevice using a file manager, without the need of syncing via iTunes.

The idevice Software Stack
This is the idevice software stack. The dependencies will be pulled in automatically, but this is useful as a reference when trying to figure out which layers are or are not working.



USB Device Access
must be explicity emerged since no other stack package will pull it in. Run the daemon to make the device available to higher layers:

The flags are optional but make managing the daemon easy and transparent.

Pairing
Pairing functionality is provided by. Emerge it, then test it by running:

This should print the device serial number which appeared in your dmesg log.

If this has been successful, run:

to verify that communications with the device are functioning correctly.

Now run:

to pair with the device. Check this with:

Mounting
is supported by, so if you use GNOME, it's easy for you. If not, you will need. Both of these will mount from the idevice to a target directory. If your device is 'jailbroken', you may use the --root flag to gain access to the root of the device.

Note that media files must be in to be accessible by applications running on the device. More on this later.

Simply emerge gvfs with USE="ios", and it should auto-mount it for you. You can also mount the device manually using a frontend to GIO/GVfs such as, (>=1.6.x) or.

First, emerge ifuse, then try running it:

Users wishing to access the idevice must be members of the plugdev group, and must have write-access to the mount point.

Remember, you need to start a new user session after doing this for it to take effect. Most users quit their window manager and re-enter it to do this.

Also you need to change fusermount permissions:

Create a mount-point for the Media folder on the device.

Create some App-specific mount points (I use the AppIDs as directory names, more on finding them later)

Set appropriate permissions.

Now mount the device as a user. First, the Media "partition":

Now an App's Documents folder:

If you get error "bad mount point", try this command instead previous:

Finally, the device root (jailbroken devices only): (UNTESTED)

If the preceding steps worked, this should be enough to mount the device. This can be automated using udev rules.

You should note that the author's experience is that throughput is slow, and is seriously affected by multiple copies in parallel - iotop reports transfer rates of approximately 1200 KiB/s for a single transfer, but a total of 600 KiB/s for two in parallel.

For transferring audio files to the idevice, mount the Media partition, make sure that your user can read and write files there and point gtkpod at it.

Frontends to
Once you've "connected" to the 'Documents on My iPad' device using Gigolo, you can access the device via a file manager such as Thunar (>=1.6.x) or Nautilus and access the 'Documents' folder of the apps that support the iTunes Document Sharing feature (also called the "House Arrest" protocol). Copying files to this 'Documents' folder will make some apps pick up the files and allow you to view/edit/delete them on the iPad.

Following is a non-exhaustive list of free apps that support file transfers as described above:
 * Videos: 'OPlayerHD Lite', 'HD Player'
 * Audio: 'OPlayerHD Lite'
 * Photos: 'Another Photo Viewer'
 * PDFs or E-books: 'Documents 2', 'ciando Reader'

Sometimes it may be necessary to restart the app to make it aware of the transferred file, or possibly even reboot the iPad.

ifuse can also mount areas of the ipad by AppID, which allows the user to transfer files, which may then be used by the particular application. The AppID is a kind of namespace, particular to each application.

To find these AppIDs, you must install.

List the AppIDs of the Apps currently installed on your device.

Mount by AppID:

If you get error "bad mount point", try this command instead previous:

Now you are free to copy files to the mounted folder, which will be accessible to that App (iBooks in this example).

QueryType failed, error code -256
This error either appears on its own or followed by failed XML parsing, such as:

In 2011-11, this was due to an Apple update, and git versions of and  were needed

error opening socket
If your device was connected before installing imobiledevice, you might get

Unplug and replug your device, and try again.

GnuTLS Error: A TLS packet with unexpected length was received
In 2010, this could be solved by re-merging and. See this forum thread for more informations.

Permissions
Make sure that you are mounting as a normal user.

Unhandled Apple File Control error
If you're getting a: "Failed to open directory "ggImageViewer". Unhandled Apple File Control error (7).", then it is possible that the relevant app doesn't properly support the Apple file sharing protocol. Sometimes though it helps if you simply disconnect the 'Documents on My iPad' device, unplug the iPad, then plug it back and reconnect the device. Then you might be able to normally access an app's sandboxed 'Documents' folder.

External resources

 * Marcan's Blog
 * unl0cker's Hackintosh Post