Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AUTOMOUNTER(8)		  BSD 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 de-
     vices 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 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 at-
	     tached, the media that contains the key will also be listed.

     mlist   List data in a machine readable form as newline separated abso-
	     lute 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, de-
	     faults 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 cre-
     ate 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 de-
     tector 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 discover-
     ies 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	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 discovered
     this time.

   Revisits
     Completing	the removal of stale media, detectors which requested it dur-
     ing 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. Oth-
     erwise the	process	stays around until it has managed to destroy the
     provider or until the key becomes available again.	After successful de-
     struction of the provider the process starts a new	update to ensure that
     keys provided by the destroyed provider are no longer listed as avail-
     able.

     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 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 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 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 lock-
     able 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 ap-
     pear or disappear.	 However, it is	still necessary	to restart devd(8) af-
     ter 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 exe-
     cutable flag is added to ensure that cd'ing into the file system is pos-
     sible.

     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 de-
     vices from	managed	media (such as a USB drive) and	create the necessary
     device nodes to access these images.  Images containing labeled parti-
     tions are detected	like managed media and can even	contain	keys them-
     selves. 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 authentica-
     tion 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 confi-
     dential 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>

BSD			       2 September 2013				   BSD

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://www.freebsd.org/cgi/man.cgi?query=automounter&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help