========
USBmount
========

The USBmount package automatically mounts USB mass storage devices
(typically USB pen drives) when they are plugged in, and unmounts them
when they are removed. The mountpoints (/media/usb[0-7] by default),
filesystem types to consider, and mount options are configurable. When
multiple devices are plugged in, the first available mountpoint is
automatically selected. If the device provides a model name, a symbolic
link /var/run/usbmount/MODELNAME pointing to the mountpoint is auto-
matically created.

The script that does the (un)mounting is called by the udev daemon.
Therefore, USBmount requires a 2.6 (or newer) kernel.

USBmount is intended as a lightweight solution which is independent of a
desktop environment. Users which would like an icon to appear when an
USB device is plugged in should use the pmount and hal packages instead.

The comments in the configuration file /etc/usbmount/usbmount.conf
describe how to configure the package.

Generic Comments about Flash Drives
===================================

Users should be aware that, independently of the filesystem used by the
mass storage device, *ANY* filesystem that resides in flash memory will
become unreadable after some time. This unfortunate situation is
intrinsic to the storage medium and better quality flash drives perform
a "wear levelling" operation, distributing the load of operations across
the whole device. [*]

Filesystems using flash memory and mounted with the "sync" option can
degrade earlier due to the fact that the sync mount option forces the
operating system to write data more frequently to the device than if it
were mounted without the sync option.

So, why mount filesystems with the sync option then? The reason is to
keep the written data on the drive reflecting what the user thinks is on
the flash drive, and, more importantly, to avoid the problem of the user
unplugging the device before it is finished receiving data that the
kernel has on the memory of the computer and that is meant to be written
to the device.

If you don't like the sync option with your filesystems, then you can
remove it from the configuration file of usbmount and use your devices
with better performance and longer life time. *BUT* you should always
make sure that you use the "sync" command (on a shell) to ensure that
there is no writes pending for the device in question, so that you don't
loose any data when you unplug the device from the computer.

[*] You can see if your flash drives support wear levelling by seeing
    the technical specifications of your specific drives in the
    manufacturer's site (e.g., the manufacturer Kingston provides such
    information regarding its drives and others quite probably do that
    too).

Of course, usbmount doesn't only work with flash drives. Common hard
drives put into enclosures are perfectly used with usbmount and
usbmount, despite its name, can mount drives connected via Firewire
ports, provided that the kernel has support for it (most distribution
kernels, including the ones shipped with Debian and Ubuntu do).


Technical Recommendations
=========================

Control of Filesystems Mounted by USBmount
------------------------------------------

You can choose which filesystems you want usbmount to automatically
handle by listing the filesystem types provided by the operating system
in the configuration variable FILESYSTEMS.

Recommendations for vfat Filesystems
------------------------------------

The vfat filesystem is one of the most commonly used filesystems in pen
drives. Unfortunately, due to its age, it is very poor regarding
features and, in particular, it doesn't feature the most basic access
control present in Unix systems, namely: permissions on files.

Linux works around this by creating "virtual" permissions and
restrictions based on who mounted the filesystem. As usbmount is used,
the user assigned to the vfat filesystem is, by default, root.

For a more flexible configuration, some useful options for vfat
filesystems are to specify explicitly who the user and permissions are.
Please, read the manpage of the mount command to get details.

An example is to specify "-fstype=vfat,gid=floppy,dmask=0007,fmask=0117"
in the FS_MOUNTOPTIONS variable of the configuration file. The
particular options specified in the example mean that members of the
floppy group can read from and write to the medium, but nobody else can
access it.

Troubleshooting USBmount
------------------------

No software is free of problems and the situation isn't different with
USBmount. To ease the troubleshooting of problems, you may try to check
the following:

* Do you have HAL running? Any GNOME or KDE daemon automounting devices?

* Let's suppose that the partition containing the filesystem that you
  want USBmount to automatically handle is /dev/sda1 (your case may,
  quite possibly, vary). Then, check the result of the following
  command:

  udevadm test --action=add /sys/class/block/sda1

  The command above just gives diagnostics of what USBmount would do
  with the device, but it doesn't actually mount or interfere with the
  device. It is intended for debugging purposes. Be careful that it
  generates *a lot* of output. Many screens, depending on the device.

* Under the same assumptions as the above, another good diagnostic tool
  is the following:

  udevadm info -a -p $(udevadm info -q path -n /dev/sdb1)


Hook Scripts
------------

After a device or partition has been mounted, the command 'run-parts
/etc/usbmount/mount.d' is executed. This runs all scripts in
/etc/usbmount/mount.d which adhere to a certain naming convention; see
the run-parts manual page for details.

The following environment variables are available to the scripts (in
addition to those set in /etc/usbmount/usbmount.conf and by the hotplug
and udev systems):

UM_DEVICE       - filename of the device node
UM_MOUNTPOINT   - mointpoint
UM_FILESYSTEM   - filesystem type
UM_MOUNTOPTIONS - mount options that have been passed to the mount command
UM_VENDOR       - vendor of the device (empty if unknown)
UM_MODEL        - model name of the device (empty if unknown)

Likewise, the command 'run-parts /etc/usbmount/umount.d' is executed
after a device or partition has been unmounted. The scripts can make use
of the environment variables UM_DEVICE, UM_MOUNTPOINT and UM_FILESYSTEM.
Note that vendor and model name are no longer easily available when the
device has been removed. If you need this information in an unmount hook
script, write it to a file in a mount hook script and read it back in
the unmount hook script.
