DragonFly On-Line Manual Pages
AUTOMOUNTER(8) DragonFly 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
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.
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>
DragonFly 6.5-DEVELOPMENT 2 September 2013 DragonFly 6.5-DEVELOPMENT