NAME

automounter —

Dynamically configure amd for existing devices.

SYNOPSIS

automounter list [mounted | labels | keys | encrypted]

automounter mlist [mounted | llinks | dlinks]

automounter monitor [interval]

DESCRIPTION

The automounter script dynamically builds a map file for amd(8). It is meant to be started by the rc(8) system and triggered by devd(8) when devices appear or disappear.

By default automounter copies the file /etc/amd.map and builds its configuration on top of that. This means it inherits everything defined there and amd_enable="YES" should not be set in rc.conf(5).

The script also supports polling the keys of geli(8) encrypted partitions and images from managed media. More information is available in the GELI section of this manual page.

This manual page describes how to set up automounter. How to adjust its behaviour is described in the automounter.conf(5) manual page.

COMMANDS

The following commands are available:

start: Starts amd(8) and calls update.
update: Updates the dynamic map file for amd(8) and creates the necessary mount points and links. It also removes stale mount points and links.
list: Lists the labels of currently managed mounts, the keys found on the media and the encrypted providers that are available.
list mounted: Lists the currently mounted labels.
list labels: List currently available labels.
list keys: Lists the keys that were found on the managed media.
list encrypted: Lists the encrypted images and devices that are available. If attached, the media that contains the key will also be listed.
mlist: List data in a machine readable form as newline separated absolute path names.
mlist mounted: List the paths of mounted file systems.
mlist llinks: List label named links to file systems.
mlist dlinks: List device named links to file systems.
monitor: Provides a top(1) like display of the available labels, keys and encrypted images and devices.
monitor interval: Refresh the monitor display at the given interval in seconds, defaults to two seconds if omitted.
stop: Unmount everything, stop amd(8) and clean everything up.

Unsupported parameters will cause printing of supported parameters.

NOTES

Automounter is made for the sake of comfort. Even though it reduces the probability of panics, the user is still obliged to run mount(8) to make sure a device is not mounted, before unplugging it.

FreeBSD 7.1 and higher normally do no longer panic when a mounted device disappears and automounter handles this case gracefully, however it still remains “bad style” to unplug mounted media and might leave your file system in an inconsistent state.

IMPLEMENTATION NOTES

This manual section is for the technically interested, to setup automounter skip ahead to STARTUP.

automounter is not a daemon, instead it relies on amd(8) to perform the daemonic task of dynamically mounting file systems.

The purpose of automounter is to discover mountable file systems and create an amd(8) map file. This also entails recording discoveries, creating a link structure in /media and not loosing any devices during operation, which is the most difficult task of all.

States Of Operation

automounter knows two states of operation, stopped and started. This is necessary to ensure that the system has been initialized before starting. The start call is performed by the rc(8) system, which causes automounter to start amd(8), perform the first update and discover available file systems.

If properly configured premature update calls might be issued by devd(8) during boot. These will be ignored.

Device Discovery

The first activity during an update call is device discovery. The entire configuration is rebuilt every time an update is called. To this end detector functions are called. The current detector functions are named mountedDetect(), iso9660Detect(), glabelDetect() and probeDetect(). Each of these functions calls the writeNode() function to record its discoveries and set up the necessary directory and link structure. The writeNode() function also performs the blacklisting checks. The detectors keep a list of already probed devices, to avoid redundant work.

The mounted detector discovers the currently mounted devices. This is necessary, because mounting a glabel consumer destroys the glabel providers and thus prevents discovery by the glabel detector. The probe detector needs to be able to mount file systems, which does not work with already mounted geom providers, so it depends on this, too.

The iso9660 detector simply assumes that devices conforming to certain name patterns are optical disk drives. This behaviour prevents detection failure if a drive does not hold a disk. The device pattern can be changed in the automounter.conf(5) file.

The glabel detector uses the geom(8) label class to identify file system types through labels. This is the traditional way of discovery for automounter.

The probe detector takes the remaining geom providers reported by the gstat(8) tool and simply tries to mount them as different file system types until it succeeds or runs out of file system types. Successfully mounted devices are unmounted and setup with writeNode().

Afterwards the mount detector is called again to catch mounts that occured after the first run and prevented detection through the other detectors. This is a very unlikely case, but not entirely impossible.

Stale Mounts

The next step is to compare the list of previously discovered devices and destroy the /media link structure for each one that was not discovered this time.

Revisits

Completing the removal of stale media, detectors which requested it during the first run are revisited. This allows them to follow label changes of a device after the old media links have been removed.

Encrypted Providers

Afterwards, if activated, the geli(8) managing function is started.

The geliUpdate() function checks whether it is currently managing keys residing on no longer present file systems. The keys are removed from the list of available keys.

The next step is to search newly discovered file systems for keys.

Afterwards a process for each encrypted file system whose key is no longer available is forked off. This process tries to destroy the geli(8) provider, which is only possible if the file system is not mounted. Otherwise the process stays around until it has managed to destroy the provider or until the key becomes available again. After successful destruction of the provider the process starts a new update to ensure that keys provided by the destroyed provider are no longer listed as available.

The last step is to decrypt the providers for which new keys are available. This results in the creation of new geoms, which are picked up by devd(8), resulting in a new update call.

Reconfiguring AMD

Now that the device discovery is completed, amd(8) is sent SIGHUP to reload the newly built map file. From this moment on the discovered devices are available.

Locking

Because the sequential order of events is critical to retain consistency most of the operation of automounter is locked. I.e. start, update, stop, mount and umount are synchronous operations.

Mounts and umounts, because they may not occur during device discovery, the others, because update runs may only occur one at a time. The locking ensures that too many updates at once (e.g. lots of diconnect/connect events reported by devd(8) or the removal of several encrypted providers) will be called sequentially or time out at a time when it can be assumed safely, that the discoveries were already made by previous updates.

Mounting and Unmounting

The amd(8) map file is created so that file systems are mounted and unmounted through automounter. This has several advantages, the first of which is that amd(8) cannot deal with spaces in mount(8) and umount(8) parameters. To permit human readable mount directories, the mount and umount commands are called with a hash, which automounter than interprets as one of its managed file systems.

The second advantage is that automounter can thus intercept mounts and umounts. This is used to enforce locked mounts and umounts as well as preventing unmount attempts to file systems in use, especially with the fuse hack in place. But it is also used to force unmount file systems whose devices are no longer present and issue an update call, because the disappearing of the device was previously missed, due to mounted file systems being protected from disappearing.

Finally it is used to silently fall back to read-only mode, which allows mounting of devices with hardware write protection like SD cards or lockable USB drives.

STARTUP

In order for the dynamic creation and destruction of mount points to work, it is necessary that automounter is started first. The recommended way to achieve this is by setting the following line in rc.conf(5):

automounter_enable="YES"

To start it without rebooting run the following command:

service automounter start

DEVICE DISCOVERY

As of automounter 1.4.1 it is no longer necessary to add an entry to the devd.conf(5) file to automatically update available devices when they appear or disappear. However, it is still necessary to restart devd(8) after installation:

service devd restart

ACCESS RIGHTS

The mount point inherits the access rights of the label device node. This is useful for file systems that don't support proper user management like msdosfs. If any right is present for the owner, group or others the executable flag is added to ensure that cd'ing into the file system is possible.

If the label device node is not found, e.g. because the label is empty, the regular device node will be used instead.

To find out how to change the access rights to a device node and hence of the resulting mount point read the devfs.rules(5) manual page.

GELI

The automounter script is able to poll keys for encrypted images and devices from managed media (such as a USB drive) and create the necessary device nodes to access these images. Images containing labeled partitions are detected like managed media and can even contain keys themselves. Keys and labels will simply be updated whenever new ones show up.

If a used key disappears the encrypted device will be detached when no longer in use.

To activate and configure this feature please refer to the GELI section of the automounter.conf(5) manual page.

How to create images that can be mounted with a key (password authentication is not supported) is described in the geli(8) manual page. Keys are expected to reside in .geli/keys on a labeled partition and the images are expected to be stored in /var/geli/images.

Devices have to be unresolvable symlinks from /var/geli/images. E.g. if you wish to enable auto attaching for /dev/da0s1 with a key named confidential you have to create a link in the following fashion:

ln -s da0s1 "/var/geli/images/confidential"

FILES

/usr/local/sbin/automounter
/usr/local/etc/automounter.conf
/usr/local/etc/automounter.conf.sample
/usr/local/etc/devd/automounter.conf
/usr/local/etc/rc.d/automounter

EXIT CODES

Additionally to the error codes listed here, automounter can return all the errors listed in the lockf(1) manual.

ERR_CMD_UNKNOWN 1: Returned if started with an unknown command parameter.
ERR_NOT_STARTED 2: Returned if automounter has not yet been started.
ERR_MOUNT_FS_MISSING 3: Returned by the mount command if the requested file system cannot be found.
ERR_UMOUNT_ACTIVE 4: Returned by the umount command if the file system to unmount is active.
ERR_LIST_LOCKED 5: Returned if the list command is issued during an ongoing update.
ERR_RPC_FAIL 6: Returned if the RPC daemon is not available and could not be started.
ERR_AMD_FAIL 7: Returned if the AMD daemon could not be started.

BUGS/UNEXPECTED BEHAVIOUR

Fuse based file systems like ntfs-3g close all opened files when amd tries to unmount them. This is a bug in fuse and neither automounter nor amd are to blame. A workaround for this bug is described in the automounter.conf(5) manual page.

COMPATIBILITY

The script has been tested on FreeBSD stable/9-r254957.

AUTHOR

Dominic Fandrey ⟨kamikaze@bsdforen.de⟩