Text size:

usb-storage tools

Who needs udev?

Purpose
Prerequisites
Installation
Registering a device
Listing devices
Mounting a filesystem
Unmounting a filesystem
Checking that it works...
Download usb-storage-tools

usb-storage-tools are released under the GNU General Public License, version 2. The full text of the license is supplied in the usb-storage-tools distribution and is also viewable on the site of the Free Software Foundation.

PURPOSE

Users of multiple storage devices that connect to the computer via a USB port often run into problems when it comes to accessing those devices. The usb-storage kernel module emulates a generic SCSI disk and puts the device under the control of the SCSI subsystem. The storage device is then accessible as /dev/sda if it's the first one to be plugged in, /dev/sdb if it's the second, /dev/sdc if it's the third, etc…

I have FIVE such devices: two card readers, an external hard disk in an IDE/USB enclosure, a cellphone and an MP3 player. There are, for example, 4 partitions on the external hard disk. I can't hardwire them as /dev/dsa1, /dev/sda2 etc. in my /etc/fstab, because, if the MP3 player for example was plugged in before the external hard disk, then those partitions will now be /dev/sdb1, /dev/sdb2 etc. and all the entries in my fstab will be incorrect.

This problem can be overcome by using the hotplug/udev tandem and telling the system exactly what "disk" you want your USB storage device to be when it's detected, so if you are using that software combo then this page isn't really what you want − although usb-storage-tools are arguably easier to set up.

usb-storage-tools is a set of shell scripts that allow you to mount your USB storage devices, regardless of what disk they're identified as. You only have to get your hands dirty once in order to obtain information that identifies your USB device, and you use it to create a profile. Thereafter, you simply give the name of the profile and usb-storage-tools use the information in it to identify the SCSI disk emulated by the kernel, thus giving you access to the device.

PREREQUISITES

The kernel must be compiled with support for the sysfs virtual filesystem

The shell these scripts are written for is bash, and they expect it to be in /bin/bash − which is the case of all Linux distributions I've seen so far…

usb-storage support must be available, which in turn requires SCSI-Generic support. Your USB storage devices wouldn't work without these, so if they have been working until now then these kernel elements are already available.

The scripts make use of the following commands: grep, cut, awk, head, cat, sudo and mount. Any self-respecting Linux distribution has all of them but you might want to check, just in case. You'll also have to ensure that you have privileges to use sudo (see visudo(8)).

You'll need root access to your machine for the installation and configuration of usb-storage-tools.

INSTALLATION

Grab the installation tarball and decompress it in one fell swoop (you need to be root for this).
# cd /usr/local
# wget -O - http://linux.sgms-centre.com/misc/usb-storage-tools/usb-storage-tools.tar.gz | tar -xzf -
(don't miss the hyphen at the end of that command line)

Symlink the two commands you'll be using into the /usr/local/bin directory:
# cd usb-storage
# ln -s $PWD/{lsusbstor,usbmount} ../bin
Create the directories that will contain your configuration files:
# mkdir -p /etc/usb-storage/devices
That's it − you're done!

REGISTERING A DEVICE

This is the only time you'll have to get your hands dirty looking for things that will serve to identify your device.

Start by monitoring your system log so that you see what gets displayed when you plug in your USB device. As root, run the following command and watch what happens:
# tail -f /var/log/messages
Plug the USB device in and you should see something like this appear:
Jan 12 17:27:19 dragonfly kernel: usb 1-7.2: new full speed USB device using ehci_hcd and address 33
Jan 12 17:27:19 dragonfly kernel: usb 1-7.2: configuration #1 chosen from 1 choice
Jan 12 17:27:19 dragonfly kernel: scsi26 : SCSI emulation for USB Mass Storage devices
Jan 12 17:27:24 dragonfly kernel: scsi 26:0:0:0: Direct-Access     SanDisk  ImageMate III    2.31 PQ: 0 ANSI: 2
Jan 12 17:27:24 dragonfly kernel: sd 26:0:0:0: Attached scsi removable disk sda
I have inverted the colour of one line because this line contains all the information we're going to need. It tells us that the vendor of the hardware is "SanDisk", that the model is "ImageMate III" and that the revision is "2.31".

Note that the case here is important. If you note down "Sandisk" instead of "SanDisk", your device will never be registered with usb-storage-tools.

Decide now upon a name to give the profile that will represent this USB device. In this instance I named the profile "imagemate". Inside your /etc/usb-storage/devices directory (that you created created earlier, during the installation process) create a file that has the same name as the profile you chose. In it, add this information:
# Identification of the SanDisk ImageMate III CF card reader

VENDOR="SanDisk "
MODEL="ImageMate III   "
REV="2.31"
DEVICE="SanDisk ImageMate III CompactFlash card reader"
Note that the VENDOR string is padded with spaces so that it is precisely 8 characters long, and the MODEL string is space-padded to 16 characters. The REV string (revision) is always 4 characters in length. The DEVICE string is freeform and is what will be displayed by lsusbstor for you to identify the device.

LISTING DEVICES

So, let's run lsusbstor to see what it can tell us (you don't need to be root to run it):
$ lsusbstor
Profile: imagemate
        Device: SanDisk ImageMate III CompactFlash card reader
                SanDisk ImageMate III
        Revision: 2.31
        Device attached to /dev/sda
The card reader was identified and we know that it is attached to device /dev/sda. Now let's plug in the SD-card reader and create a profile for it. This is the relevant information that shows up in the logs as I plug the thing into the PC:
Jan 12 17:35:14 dragonfly kernel: usb 1-7.1: new high speed USB device using ehci_hcd and address 34
Jan 12 17:35:14 dragonfly kernel: usb 1-7.1: configuration #1 chosen from 1 choice
Jan 12 17:35:14 dragonfly kernel: scsi27 : SCSI emulation for USB Mass Storage devices
Jan 12 17:35:19 dragonfly kernel: scsi 27:0:0:0: Direct-Access     Multi    Flash Reader     1.00 PQ: 0 ANSI: 0
Jan 12 17:35:19 dragonfly kernel: sd 27:0:0:0: Attached scsi removable disk sdb
This information enables me to create a profile I'll call "sdcard" and therefore store in /etc/usb-storage/devices/sdcard.
# Identification of my el-cheapo sd/cf/ms card reader

VENDOR="Multi   "
MODEL="Flash Reader    "
REV="1.00"
DEVICE="Generic SD/XD/MS USB2.0 card reader"
Once again, note how VENDOR and MODEL are padded to 8 and 16 characters respectively.
$ lsusbstor
Profile: imagemate
        Device: SanDisk ImageMate III CompactFlash card reader
                SanDisk ImageMate III
        Revision: 2.31
        Device attached to /dev/sda

Profile: sdcard
        Device: Generic SD/XD/MS USB2.0 card reader
                Multi   Flash Reader
        Revision: 1.00
        Device attached to /dev/sdb
Now pull out both card readers and run lsusbstor again:
$ lsusbstor
Profile: imagemate
        Device: SanDisk ImageMate III CompactFlash card reader
                SanDisk ImageMate III
        Revision: 2.31

Profile: sdcard
        Device: Generic SD/XD/MS USB2.0 card reader
                Multi   Flash Reader
        Revision: 1.00
Note how the "Device attached to /dev/sdx" lines have disappeared.

I'm going to plug them back in again, but in the opposite order. First the el-cheapo SD card reader, wait a few seconds, then the SanDisk CF card reader. Then I'm going to run lsusbstor again:
$ lsusbstor
Profile: imagemate
        Device: SanDisk ImageMate III CompactFlash card reader
                SanDisk ImageMate III
        Revision: 2.31
        Device attached to /dev/sdb

Profile: sdcard
        Device: Generic SD/XD/MS USB2.0 card reader
                Multi   Flash Reader
        Revision: 1.00
        Device attached to /dev/sda
The "sdcard" device was plugged in first, which is why it's now attached to /dev/sda with the SanDisk card reader now on /dev/sdb. If I'd entered /dev/sdb1 in my /etc/fstab hoping to be able to access the first partition on the miniSD card I use in my cellphone, I'd be severely disappointed trying to use it now. That's where usbmount comes in useful.

MOUNTING A FILESYSTEM

The traditional /etc/fstab is bypassed here altogether. You can safely remove any references to your USB removeable media in it. Instead, we're going to use a new filesystem table in /etc/usb-storage/fstab. Start by dumping this data into a new /etc/usb-storage/fstab file:
# device,partition      ro/rw   fstype  default mountpoint      extra options
# ----------------      -----   ------  ------------------      -------------
The mount point I use for the first partition on a miniSD card is /sdcard. I mount the partition R/W, the filesystem on these cards is a FAT32 filesystem (vfat). I make sure the files have permissions such that the owner has R/W privileges and everyone else R/O (rw-r--r--, mask=133), directories have rwxr-xr-x privileges (mask=022). Refer to the man pages of chmod and umask if you're unsure about the meaning of these permissions.

The first partition of the card inserted in the card reader identified by the "sdcard" profile is sdcard,1. So, we create a 3rd line in our /etc/usb-storage/fstab file, like this:
# device,partition      ro/rw   fstype  default mountpoint      extra options
# ----------------      -----   ------  ------------------      -------------
sdcard,1                rw      vfat    /sdcard                 fmask=133,dmask=022
The first column identifies the device and the partition you want to mount. There must not be any whitespace or anything else between the beginning of the line and it. The line must start with this information. The second column is either "rw" for read/write, or "ro" for read-only. The third column identifies the type of filesystem on the partition, the fourth is the default mount point, and the fifth (optional) contains extra options to supply to mount.

Note that the information in the 2^nd and subsequent columns is fed directly to mount, so any cock-ups in here are likely to result in mount failing and the filesystem not being mounted.

With this line describing how to mount the partition safely in /etc/usb-storage/fstab (don't forget to make it world-readable), all I have to do now is run this:
$ usbmount -d sdcard,1
Depending on how your sudoers file is set up you might be asked for your user password. This is because the last thing that usbmount does is use sudo in order to run mount with root privileges in order to mount a device that isn't mentioned in /etc/fstab.

Let's check that there is now something mounted on /sdcard:
$ df /sdcard
Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/sda1               997936     23824    974112   3% /sdcard
usb-storage-tools figured out on its own that the device "sdcard" is attached to /dev/sda and therefore mounted /dev/sda1 on /sdcard as a FAT filesystem.

For both "fat" and "vfat" filesystems, neither of which supports user and group ownerships, we need to tell mount who the files on the FAT filesystem are going to belong to once the filesystem is mounted. Absent any such declaration, everything belongs to the root user, thus making the whole thing read-only for a common mortal user.

usbmount ascertains the UID of the user invoking it from the $UID environment variable, and then parses through /etc/passwd in order to figure out that user's main group. It then feeds this infornation to mount so that the filesystem is mounted belonging to the user that invoked usbmount.

This is not done for Unix-native filesystems, which have user and group ownership built into them, nor for ISO9660 or UDF (CD-ROM/DVD) because the media itself is read-only anyway.

It is possible to override the defaults for any given device with an entry in /etc/usb-storage/fstab. The "-r" option overrides the default rw or ro permissions. So, had I wanted to mount the SD card read-only despite the "rw" in my fstab, I would have run:
$ usbmount -d sdcard,1 -r ro
Similarly, the "-t" option overrides the filesystem type, the "-o" option overrides other options passed to mount, and the "-m" option allows the user to specify an alternative mount point.

Other options are:

"-v" causes usbmount to display its version and exit.

"-h" causes a quick help file to be displayed.

"-l" (lowercase L, not the digit "one" or a capital "eye") causes usbmount to display the text of the GNU General Public License and then exit.

UNMOUNTING A FILESYSTEM

Nothing complicated here. Simply use umount (with sudo if you're not root) to unmount the filesystem like you would any other:
$ sudo umount /sdcard
CHECKING THAT IT WORKS

Now that the SD card is unmounted I'm going to pull it out of the USB port. Next, I plug in the SanDisk card reader, I wait a few seconds for the system to register it, and I try and mount sdcard,1 again:
$ usbmount -d sdcard,1
usb-storage: Device "Generic SD/XD/MS USB2.0 card reader" is not attached.
At least it was smart enough to figure that one out…

Okay, so I plug the SD card reader back in (without unplugging the SanDisk reader), wait a few seconds and try again:
$ usbmount -d sdcard,1
No error message this time. Let's use df to see how much room we still have free on the SD card:
$ df /sdcard
Filesystem           1K-blocks      Used Available Use% Mounted on
/dev/sdb1               997936     23824    974112   3% /sdcard
Yep. Still 974,112 blocks. Wait a minute… Look at the first column and compare it with the readout above. I didn't have to do anything special, yet usb-storage-tools "knew" that the SD card reader is now attached to /dev/sdb and it mounted the right partition automagically.

It works :)

NAVIGATION:
>> /misc
>> /

Last update: 12-JAN-2007 22:06:32 UTC
This page has been served 14238 times since 12-JAN-2007