FreeBSD Manual Pages
AUTOMOUNTER(8) System Manager's Manual AUTOMOUNTER(8) NAME automounter -- Dynamically configure amd for existing devices. SYNOPSIS automounter (start | update | list | mlist | monitor | stop) 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 con- figuration 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 parti- tions 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 neces- sary 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 ab- solute 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 start- ing. 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 en- tire 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 detec- tion 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 sys- tem 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 oc- cured after the first run and prevented detection through the other de- tectors. 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 discov- ered 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 de- stroy the provider or until the key becomes available again. After suc- cessful 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 avail- able. 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 de- vices are available. Locking Because the sequential order of events is critical to retain consis- tency most of the operation of automounter is locked. I.e. start, up- date, 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 lock- ing ensures that too many updates at once (e.g. lots of diconnect/con- nect 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 previ- ous updates. Mounting and Unmounting The amd(8) map file is created so that file systems are mounted and un- mounted 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 inter- prets 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 al- lows 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 recom- mended 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 manage- ment 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 neces- sary 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 authenti- cation 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 im- ages 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 con- fidential 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 can- not 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 up- date. 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. SEE ALSO 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) AUTHOR Dominic Fandrey <kamikaze@bsdforen.de> FreeBSD ports 15.0 2 September 2013 AUTOMOUNTER(8)
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | NOTES | IMPLEMENTATION NOTES | STARTUP | DEVICE DISCOVERY | ACCESS RIGHTS | GELI | FILES | EXIT CODES | BUGS/UNEXPECTED BEHAVIOUR | COMPATIBILITY | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=automounter&sektion=8&manpath=FreeBSD+Ports+15.0>