GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
AUTOMOUNTER(8) FreeBSD System Manager's Manual AUTOMOUNTER(8)

automounter
Dynamically configure amd for existing devices.

automounter (start | update | list | mlist | monitor | stop)

automounter list [mounted | labels | keys | encrypted]

automounter mlist [mounted | llinks | dlinks]

automounter monitor [interval]

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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"

/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
 

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.

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.

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

amd(8), automounter.conf(5), rc(8), rc.conf(5), devd.conf(5), devfs.rules(5), geli(8), mount(8), umount(8) and service(8)

Dominic Fandrey ⟨kamikaze@bsdforen.de⟩
2 September 2013 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.