udev-based automounter (uam)
(c) 2008-2010 Michał Górny
Released under the terms of the 3-clause BSD license


Introduction
============

What is it all about? This is just simple tool for mounting pendrives and alikes
when inserted -- something like ivman or functionality integrated in KDE/GNOME.

So what's the difference? Unlike those tools uam doesn't use HAL. Unlike
traditional automounters it doesn't require you to sacrifice memory for three
additional daemons -- HAL, dbus & the mounter itself. Instead you just have to
have udev running (which you'd like to have anyway) and uam will be called by it
everytime an USB stick is inserted.


Using
=====

It should 'just work'. If it doesn't, take a look at syslog and/or configuration
file. If you're sure everything is set right, contact me and I'll see what I can
do for you.


Mounting ejectable media (CD/DVD disks)
=======================================

With kernel 2.6.38 or newer, uam should be able to mount CD/DVD disks and other
ejectable media as well. In order to do that, you have to enable in-kernel
polling and set a suitable poll interval through sysfs:

	echo 5000 > /sys/module/block/parameters/events_dfl_poll_msecs

This will cause all ejectable drives to be polled every 5 seconds. You can set
a poll interval per-device too, e.g.:

	echo 5000 > /sys/block/sr0/events_poll_msecs

If you'd like to make this setting permanent, you can add that option
to the kernel command-line like:

	block.events_dfl_poll_msecs=5000

For lilo, that would be:

	append = "block.events_dfl_poll_msecs=5000"

Please note that most likely the polling won't work with the old ATA drivers
(the ones marked `DEPRECATED`). If you're still using them, you need to migrate
to the new ones from under the `Serial ATA and Parallel ATA drivers` menu entry.
Please note that you have to enable `SCSI CDROM support` as well.


Use of pmount
=============

Due to non-daemonic and non-interactive nature of uam, there is a fair amount
of features which can't be implemented in it. As there's no real reason
to duplicate well-developed and working solutions, it is officially suggested
to use pmount along with uam.

The pmount utility can be used to manually unmount removable devices mounted
by uam (thus making sure all I/O is synced) and mount ejectable media (like CDs
or floppies) which can't be done by uam due to its reliance on udev triggers.


Hook support
============

As of version 0.0.5, uam supports 'hooks' -- user-provided scripts which are
sourced when specific conditions occur. These can be used to alter the device
information, support additional notification methods, etc.

The hook scripts are to be contained in ${HOOKDIR} subdirectories (defaulting
to /etc/udev/uam-hooks/) and are sourced using the dot operator (called 'source'
in bash too). This means they have full access to the environment of uam
(and thus they can alter its' variables) but they should avoid calling builtins
like 'exit', 'exec', 'return' and similar in the outer scope (as that would
cause exiting uam).

The following hook types (which are subdirectory names too) are supported:

1. pre-mount -- called after getting the basic device information but before
the mounting procedure starts. They can be used to alter both device information
and uam configuration for specific devices.
2. post-mount -- called after device is successfully mounted. These can be used
to notify the user or update the environment.
3. mount-failed -- called whenever uam has tried all possible mountpoints and
was unable to mount a particular device.
4. pre-umount -- called after getting the mountpoint for a particular device
but before starting the unmount procedure. These scripts could alter
the mountpoint but is it useful at all?
5. post-umount -- called after successful or unsuccessful umount. The SUMMARY
environment variable can be used to get the umount result-message.


Bug reports
===========

It is preferred to use Gentoo Bugzilla [1] for that (with `sys-apps/uam`
in the summary). If you don't have an account there and prefer to use github
bugtracker [2], feel free to.

Please attach (or paste) the debug trace (obtained through setting `TRACE`
in `uam.conf`) if possible. It helps me a lot. Otherwise, please try to obtain
and attach (using root account):

- `blkid -o udev`,
- `udevadm monitor --property` output while plugging in the device,
- the program version and your `uam.conf`.

[1]:http://bugs.gentoo.org/enter_bug.cgi?product=Gentoo%20Linux&component=Applications&short_desc=sys-apps/uam:%20
[2]:http://github.com/mgorny/uam/issues

<!-- vim:se syn=markdown : -->