VirtualBox on OS-X Host – howto mount an external USB drive

Ever tried to connect an external USB-drive to your VirtualBox Guest and failed with the drive shown “unavailable” and grayed-out in the List of USB-devices? Well, that’s what happend to me – and I found a solution. You’re welcome to participate.

reworked 2009-11-25

VirtualBox Guest showing unavailable USB disk (Seagate FreeAgent)

Connect your USB drive physically

If you connect an USB-drive to your Mac, it shows up in the Finder – or in case of an unknown filesystem type (like ext3-fs) you’ll get a pop-up asking for action. In first case, “eject” the disk from Finder, in later case, select “ignore“.

The disk will in both cases still be known to OS-X:

me$ diskutil list
...
/dev/disk1
 #:                      TYPE NAME      SIZE       IDENTIFIER
 0:     FDisk_partition_scheme          *931.5 Gi   disk1
 1:                      Linux           931.5 Gi   disk1s1

Essential things, nobody tells you (so far)

This part took me quite some time to figure out. Reading the virtualbox-forum I found the same problem occuring on Linux – but no hint about OS-X. With some experiments and good guessing, I found the following points being essential for a working setup:

1. USB device filter
2. Manufacturer of the drive
3. permissions on host /dev/vboxdrv
4. kernel extensions on host

1. USB device filter – configuring VirtualBox

This point has been essential for every setup I found working.

After starting VirtualBox.app, select the Virtual Machine in which you want to mount the USB-disk. Navigate to Details -> USB -> Ports -> USB. Create a new filter for your USB-drive as shown below or an empty filter, matching every device (the naming of your disk may vary).

There may be a problem with just adding an USB device by klicking the “add”-icon and selecting the drive. Seems as if my Seagate FreeAgent does not match the automatically created filters. When I remove all settings but Name, Vendor ID and Product ID from the device filter, the drive gets available to the guest likewise using an any-filter. To be verified.

2. Manufacturer of the drive

Don’t laugh. The filter settings described above are sufficient for two of my USB drives and are not for two others (both Seagate).

If you have a look at the USB devices known to VirtualBox, and the disk still appears as “Unavailabe”, continue with the next steps.

 me$ VBoxManage list usbhost
 ...
 Manufacturer:       Seagate
 Product:            FreeAgent
 ...
 Current State:      Unavailable

3. permissions on host /dev/vboxdrv

WARNING! If you don’t understand what I am doing in this section – don’t try this at home. In any case it may be a good idea to have a backup before messing around with system settings.

Manipulating the permissions of /dev/vboxdrv worked for me with VirtualBox 3.0.8 – but stopped working after an OS-X update. You may want to continue with the next section.

First of all try starting VirtualBox.app as root and start the guest. If the USB drive is not longer unavailable/grayed-out, continue here.

Open a Terminal, become root (i.e. using ’sudo bash‘).

Have a look in the user-names, group-names and group-IDs on your system:

 dscl . -readall /Users UniqueID RealName
 dscl . -readall /Groups PrimaryGroupID RealName GroupMembership

Create a new group, i.e. named vboxusers with group-ID 11104 (use a group-name and group-ID which is not used on your system!):

 dscl . create /Groups/vboxusers
 dscl . create /Groups/vboxusers name vboxusers
 dscl . create /Groups/vboxusers passwd "*"
 dscl . create /Groups/vboxusers gid 11104

Add the user (i.e. “me”) who starts the Virtual Machine to the newly created group:

 dscl . merge /groups/vboxusers users "me"

Usually a unix-group comes with a dedicated user. That should not be necessary but may help avoiding confusion with UIDs and GIDs

 dscl . create /Users/vboxusers
 dscl . create /Users/vboxusers UniqueID 11104
 dscl . create /Users/vboxusers RealName "VirtualBox pseudouser"
 dscl . merge /Groups/vboxusers users "vboxusers"

The essential step is to make the device file vboxdrv read- and writable for the users using the virtual machine. I do this by adding the user to the group vboxusers (see above) and allowing the group vboxusers to read/write the device file:

 chgrp vboxusers /dev/vboxdrv
 chmod g+rw /dev/vboxdrv

Now logout and login to participate in the new group. Call ‘id’ to verify:

myhost:~ me$ id
uid=501(me) gid=501(me) groups=501(me),...,11104(vboxusers),...

4. kernel extensions on host

That’s the last trick in my bag. This is not deeply tested so far.

First step is to disconnect the USB drive then reboot your OS-X host.
After rebooting, have a look at the loaded kernel extensions:

me$ kextstat
Index Refs Address    Size       Wired      Name (Version) <Linked Against>
 1    1    0x0        0x0        0x0        com.apple.kernel (9.8.0)
 ...

save the result.

Connect your usb drive and repeat the kextstat.
Compare the old output with the new (diff is your friend).

You’ll probably find a new kernel extension loaded. Im my case this is:

com.apple.iokit.IOUSBMassStorageClass (2.0.8)

The trick is to unload this kernel extension:

kextunload -b com.apple.iokit.IOUSBMassStorageClass

Now you should be prepared…

Start your engines…

(Re-)Start VirtualBox.app, start the Virtual Machine you created the filter for. With everything done right, the USB-disk should show up immediately. The view from host side:

 me$ VBoxManage list usbhost
 ...
 Manufacturer:       Seagate
 Product:            FreeAgent
 ...
 Current State:      Captured

Using Linux, Debian Etch as guest:

 me@etch-test:/dev$ find /dev/disk
 ...
 /dev/disk/by-label/FreeAgent_Drive
 ...
 /dev/disk/by-id/usb-Seagate_FreeAgent_2XXXXXXX-part1
 /dev/disk/by-id/usb-Seagate_FreeAgent_2XXXXXXX

Updates

2009-10-21: unfortunately the device files /dev/vbox* are created dynamicaly while booting the host system whereby the new permissions get lost.

2009-10-25: Even worse, after an OS-X system update, setting the permissions as described above, does not help any longer :-((

2009-11-05: Good news!! (Re)Installed the guest-additions for 3.0.10 – et voilà – it works again :-)). Don’t ask. I can’t see any relation to the OS-X update – and I’m not sure if it tomorrow will still be working.

Important points today are:

• Start the Virtual Mashine before plugging in the USB-Drive. If the Drive is connected while the VM is not running, it is taken by OS-X and I found no way to release it (shows up as “Unavailable” in ‘VBoxManage list usbhost’)
• At the moment only an “any” filter catches the USB-Drive.

2009-11-25: After a bunch of tests, the focus rests at OS-X. If OS-X does not release the drive, Virtualbox could not access ist. So unloading the OS-X USB driver seems to be the way to go. Matching USB device filters assumed. Rework of this article.

2010-03-07: Sun confirmed an error in 3.1.4 about two weeks ago:  http://forums.virtualbox.org/viewtopic.php?f=8&t=23701&start=15

Additional notes:

• This HOWTO is based on Mac OS X 10.5.8 as host with Sun VirtualBox 3.0.8 r53138 and 3.0.10 r54097.
• Using an USB-stick, the guest-USB entry will not be grayed-out. The permission problem appears (at least on my Macbook) only with USB-drives.
• Without a) the device filter mentioned above and b) the correct permissions, the USB device will show up grayed-out in the guest.
• If you don’t want to use dscl to edit the user/group settings, try OS-X “server admin tools”, currently located http://www.apple.com/downloads/macosx/apple/application_updates/serveradmintools1057.html (URL changes with every update).
• Unhappily VirtualBox still seems to have problems in managing the usb devices. During my experiments, the USB devices regularly disappeared completely from all settings-menues.  Other strange things happened which I can not reproduce. Restart of VirtualBox helped in these cases.
• This topic is related to http://forums.virtualbox.org/viewtopic.php?t=23701 and http://www.virtualbox.org/ticket/4168