HOWTO hfsplus
From Gentoo Linux Wiki
| Installation • Kernel & Hardware • Networks • Portage • Software • System • X Server • Gaming • Non-x86 • Emulators • Misc |
HFS+, HFS Plus, or Mac OS Extended are names for a file system developed by Apple Computer to replace their Hierarchical File System (HFS). In addition to being the default file system on modern Apple computers, HFS+ is one of two formats that are supported by the iPod hard-disk based music player. HFS+ supports UNIX style file permissions, and has support in the kernel. The following series of steps adds support for HFS+ capability and tools.
This HOWTO shows how to patch Apple's utilities to work under Linux. These utilities include mkfs.hfsplus and fsck.hfsplus. These Darwin utilities allow creating and repairing of HFS+ partitions in Linux.
The Darwin tools are not to be confused with the Penquin PPC tools (i.e. hpmount, hpfsck) contained in the Gentoo package sys-fs/hfsplusutils. They do not operate or mount newer hfsplus partitions, but are the only hfsplus tools included on a Gentoo PPC LiveCD. A number of Linux distributions omit HFSplus kernel support.
The Linux kernel driver at this time does not support writing to HFS+ journaled drives and partitions. Writing to a hfsplus partition is only possible after journaling has been disabled. While the Linux HFS+ driver is technically stable, it is not recommended for production environments.
[edit] Adding HFS+ Kernel Support
In order for Linux to read the HFS+ partition maps and partitions, kernel support is required. In Linux kernel 2.6 and newer, HFS+ support is included but may not be enabled; however, in Linux kernel 2.4 support can be added by patching the kernel. This patch can be obtained from an SourceForge project called linux-hfsplus. The following steps assume use of a 2.6 kernel or a HFS+ patched 2.4 kernel. Type the following commands at a terminal to launch the kernel configuration program.
cd /usr/src/linux make xconfig
After the qconf program opens, expand Device Drivers, File Systems, and Miscellaneous filesystems then enable Apple Extended HFS file system support and Apple Macintosh file system support. Then under Partition Types enable Macintosh partition map support. Save changes by pressing Ctrl-S and close the qconf program. Recompile and install your new kernel.
[edit] Testing Kernel Support
Once the HFS+ support has been added to the kernel the filesystem can be mounted and manipulated by the operating system. The following command will query kernel for HFS+ support; it should return hfs and hfsplus.
grep hfs /proc/filesystems hfs hfsplus
Note that you might need to modprobe the hfs and hfsplus modules if you compiled them as modules.
[edit] Listing of Partitions
The /proc/partitions file contains a listing of all partitions currently connected on the system. For example, the fourth generation Apple formatted iPods have three partitions. The first partition is a partition map, the second is a firmware partition, and the third is a HFS+ partition. The sdx prefix, where x is a letter in the alphabet, is used for SCSI emulation for Firewire and USB. In the following case, the iPod is located at sda.
cat /proc/partitions major minor #blocks name 3 0 48122708 hda 3 1 47070418 hda1 3 2 1052257 hda2 8 48 39063023 sda 8 49 31 sda1 8 50 32768 sda2 8 51 39030224 sda3
This shows how Macintosh Partition maps are treated as separate partitions under Linux, by counting blocks contained within partitions.
Macintosh disk PC/MSDOS disk
31 sda1 33 (hidden partition map)
+ 32768 sda2 47070418 hda1
+ 39030224 sda3 1052257 hda2
-------------------------------------------------------------
= 39063023 sda 48122708 hda
[edit] Using GNU Parted to View Partitions
Many Linux distributions do not include the partitioning tool parted; instead, despite its inability to interpret Macintosh partition maps, most use fdisk. In Gentoo, parted can be installed using the emerge command, or similar command in other distributions.
emerge parted parted /dev/sda
GNU Parted 1.6.23 Copyright (C) 1998 - 2005 Free Software Foundation, Inc. This program is free software, covered by the GNU General Public License. Using /dev/sda (parted) print Disk geometry for /dev/sdd: 0kB - 40GB Disk label type: mac Number Start End Size Filesystem Name Flags 1 1kB 32kB 32kB partition map 2 32kB 34MB 34MB firmware 3 34MB 40GB 40GB disk
While parted does allow viewing of the Macintosh partition maps, it does not support modification, identification, or creation of these partitions.
[edit] Compiling Apple's Filesystem Tools
The following commands run as root will download, compile, and install Apple's open source HFS+ tools.
The diskdev package, including most Darwin kernel code, is under the APSL (Apple Public Source License). The patches themselves are licensed under the GPL; however, their use may fall under restrictions from the APSL.
[edit] Port the Darwin Disk Utilites
The OS X 10.4.[4-7] / Darwin 8.[4-7](x86) tools can be ported to x86/PPC Linux.
[edit] Gentoo
Gentoo users can use Portage
emerge diskdev_cmds
[edit] Manual Installs
If wget doesn't work for you, you can download the source with a web browser at the Apple repositories but you will need to sign up for an ADC login. When using these instructions on systems other than Gentoo, you need to use GCC 3.4 and libssl-dev to compile. With these installed you should either symlink gcc-3.4 --> gcc temporarily or edit Makefile.lnx to use gcc-3.4 specifically. Works on Ubuntu 7.10 Gutsy 4.18.2008. Download the Apple Source Code
wget http://www.mythic-beasts.com/resources/appletv/mb_boot_tv/diskdev_cmds-332.14.patch.bz2 tar zxf diskdev_cmds-332.14.tar.gz bunzip2 -c diskdev_cmds-332.14.patch.bz2 | patch -p0 cd diskdev_cmds-332.14 make -f Makefile.lnx cp newfs_hfs.tproj/newfs_hfs /sbin/mkfs.hfsplus cp fsck_hfs.tproj/fsck_hfs /sbin/fsck.hfsplus cd /sbin ln -s mkfs.hfsplus mkfs.hfs ln -s fsck.hfsplus fsck.hfs
[edit] Other Versions
Also experimental x86/PPC OS X 10.4.[4-7] / Darwin 8.[4-7](PPC) is available using the above instructions below files.
http://www.ecl.udel.edu/~mcgee/diskdev_cmds/hfs-tools-332.11.1.ebuild http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-332.14.tar.gz http://www.ecl.udel.edu/~mcgee/diskdev_cmds/diskdev_cmds-332.11.1.patch.bz2
Josejx's current x86/PPC Linux port from OS X 10.4.3 / Darwin 8.3
http://www.ecl.udel.edu/~mcgee/diskdev_cmds/hfs-tools-332.11.ebuild http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-332.11.tar.gz http://dev.gentoo.org/~josejx/diskdev_cmds-332.11.patch.bz2
The original, now outdated, x86 Linux port from OS X 10.2.[5-6] / Darwin 6.[5-6] is available below.
http://www.opensource.apple.com/darwinsource/tarballs/apsl/diskdev_cmds-208.11.tar.gz http://www.ardistech.com/hfsplus/diskdev_cmds.diff.gz
[edit] Creating HFS+ Filesystems with mkfs.hfsplus
| Code: Output of mkfs.hfsplus |
|
mkfs.hfsplus
usage: mkfs.hfsplus [-h | -w] [-N] [hfsplus-options] special-device
options:
-h create an HFS format filesystem (HFS Plus is the default)
-N do not create file system, just print out parameters
-s use case-sensitive filenames (default is case-insensitive)
-w add a HFS wrapper (i.e. Native Mac OS 9 bootable)
where hfsplus-options are:
-J [journal-size] make this HFS+ volume journaled
-G group-id (for root directory)
-U user-id (for root directory)
-M access-mask (for root directory)
-b allocation block size (4096 optimal)
-c clump size list (comma separated)
e=blocks (extents file)
c=blocks (catalog file)
a=blocks (attributes file)
b=blocks (bitmap file)
d=blocks (user data fork)
r=blocks (user resource fork)
-i starting catalog node id
-n b-tree node size list (comma separated)
e=size (extents b-tree)
c=size (catalog b-tree)
a=size (attributes b-tree)
-v volume name (in ascii or UTF-8)
examples:
mkfs.hfsplus -v Untitled /dev/rdisk0s7
mkfs.hfsplus -v Untitled -n c=4096,e=1024 /dev/rdisk0s7
mkfs.hfsplus -w -v Untitled -c b=64,c=1024 /dev/rdisk0s7
|
mkfs.hfsplus can be used to initialize/format/create the filesystem.
mkfs.hfsplus -v iPod /dev/sda3 Initialized /dev/sdd3 as a 37 GB HFS Plus volume
Use gtkpod or some other program to create iPod folder structure and add music.
[edit] Disable Journaling
If you plan to work with a HFS+ partition under Linux and OS-X make sure journaling is disabled. Kernels older than 2.6.15 will mount journalized partitions read-write by default. When these older kernels will make changes to the filesystem without updating the journal the inconsistencies created which could lead to data loss.
To disable journaling on a parition under Apple OS-X terminal (non-destructive)
diskutil disableJournal volumeName
You can also use the "Disk Utility" GUI
have the iPod mounted select the iPod hold the option key and click file->disable journaling
Or you could reformat the partition under Linux
mkfs.hfsplus -v "iPod" /dev/sdXn
[edit] Mounting HFS+ partitions
Some HFS+ filesystems are wrapped inside of an HFS file system in order to display an error message on a Macintosh that does not support HFS+ and provide boot support. If the partition is wrapped inside of HFS partition, a special filesystem type option will be required to mount the drive. This command will show a common way to mount both wrapped and unwrapped hfsplus partitions.
mount -t hfsplus /dev/sda3 /mnt/ipod
Hfsplus partitions which are journalized (read-only)
mount -t hfsplus -o ro /dev/sda3 /mnt/ipod
[edit] Common HFS+ kernel error messages
dmesg | tail -n 1 HFS+-fs: write access to a journaled filesystem is not supported, use the force option at your own risk, mounting read-only.
Recommended solution: disable journaling on the partiton.
dmesg | tail -n 1 HFS+-fs: unable to find HFS+ superblock.
Recommended solution: Update to 2.6.16 kernel which supports HFSX, but remember the partition may still be journaled; see above.
To check for errors after mounting the drive or at any other time, run the following command.
dmesg | tail -n 1 HFS+-fs warning: Filesystem was not cleanly unmounted, running fsck.hfsplus is recommended. mounting read-only.
[edit] Repairing a HFS+ Filesystem using Fsck.hfsplus
The error message, shown at the end of section above, recommends running fsck.hfsplus. This particular tool is not available in any standard PC Linux distribution; however, fsck.hfsplus was installed above. Should the volume be damaged, fsck.hfsplus's output could be similar to the below.
| Code: fsck.hfsplus Usage |
|
fsck.hfsplus fsck.hfsplus: missing special-device usage: fsck.hfsplus [-dfl m [mode] npqruy] special-device d = output debugging info f = force fsck even if clean (preen only) l = live fsck (lock down and test-only) m arg = octal mode used when creating lost+found directory n = assume a no response p = just fix normal inconsistencies q = quick check returns clean, dirty, or failure r = rebuild catalog btree u = usage y = assume a yes response |
| Code: Example of a Damaged Volume |
|
fsck.hfsplus /dev/sda3 ** /dev/sda3 ** Checking HFS Plus volume. ** Checking Extents Overflow file. ** Checking Catalog file. Keys out of order (4, 1) ** Rebuilding Catalog B-tree. ** Checking HFS Plus volume. ** Checking Extents Overflow file. ** Checking Catalog file. ** Checking Catalog hierarchy. Invalid directory item count (It should be 0 instead of 1) ** Checking volume bitmap. Volume Bit Map needs minor repair ** Checking volume information. Invalid volume free block count (It should be 7809542 not 7809541) ** Repairing volume. |
| Code: Example of a Clean Volume |
|
fsck.hfsplus /dev/sda3 ** /dev/sda3 ** Checking HFS Plus volume. ** Checking Extents Overflow file. ** Checking Catalog file. ** Checking Catalog hierarchy. ** Checking volume bitmap. ** Checking volume information. ** The volume iPod appears to be OK. |
[edit] Additional Information Links
- HOWTO Update iPod Firmware
- Related HOWTO: Using an iPod With Gentoo Linux
- http://ipodlinux.org/Installation_from_Linux_Hfsplus
- http://developer.apple.com/technotes/tn/tn1150.html
- http://sourceforge.net/projects/linux-hfsplus
- http://www.ardistech.com/hfsplus
- http://bugs.gentoo.org/show_bug.cgi?id=46342
- http://ubuntuforums.org/showthread.php?p=4591297#post4591297
