AUTOMOUNT(8)

NAME
automount - automatically mount NFS file systems

SYNOPSIS
automount [ -mnTv ] [ -D name= value ] [ -f master-file ]
[ -M mount-directory ] [ -tl duration ]
[ -tm interval ] [ -tw interval ]
[ directory map [ -mount-options ] ] ...

DESCRIPTION

automount is a daemon that automatically and transparently mounts an NFS file system as needed. It monitors attempts to access directories that are associated with an automount map, along with any directories or files that reside under them. When a file is to be accessed, the daemon mounts the appropriate NFS file system. You can assign a map to a directory using an entry in a direct automount map, or by specifying an indirect map on the command line.

The automount daemon appears to be an NFS server to the kernel. automount uses the map to locate an appropriate NFS file server, exported file system, and mount options. It then mounts the file system in a temporary location, and creates a symbolic link to the temporary location. If the file system is not accessed within an appropriate interval (five minutes by default), the daemon unmounts the file system and removes the symbolic link. If the indicated directory has not already been created, the daemon creates it, and then removes it upon exiting.

Since the name-to-location binding is dynamic, updates to an automount map are transparent to the user. This obviates the need to ``pre-mount'' shared file systems for applications that have ``hard coded'' references to files.

If the directory argument is a pathname, the map argument must be an indirect map. In an indirect map the key for each entry is a simple name that represents a symbolic link within directory to an NFS mount point.

If the directory argument is `/-', the map that follows must be a direct map. A direct map is not associated with a single directory. Instead, the key for each entry is a full pathname that will itself appear to be a symbolic link to an NFS mount point.

A map can be a file or a Network Information Service (NIS) map; if a file, the map argument must be a full pathname.

The -mount-options argument, when supplied, is a comma-separated list of mount(8) options, preceded by a `-'. If these options are supplied, they become the default mount options for all entries in the map. Mount options provided within a map entry override these defaults.

OPTIONS

-m  Suppress initialization of directory-map pairs listed in the auto.master NIS database.

-n  Disable dynamic mounts. With this option, references through the automount daemon only succeed when the target filesystem has been previously mounted. This can be used to prevent NFS servers from cross-mounting each other.

-T  Trace. Expand each NFS call and display it on the standard output.

-v  Verbose. Log status and/or warning messages to the console.

-D envar=value
    Assign value to the indicated automount (environment) variable.

-f master-file
    Read a local file for initialization, ahead of the auto.master NIS map.

-M mount-directory
    Mount temporary file systems in the named directory, instead of /tmp_mnt.

-tl duration
    Specify a duration, in seconds, that a file system is to remain mounted when not in use. The default is 5 minutes.

-tm interval
    Specify an interval, in seconds, between attempts to mount a filesystem. The default is 30 seconds.

-tw interval
    Specify an interval, in seconds, between attempts to unmount filesystems that have exceeded their cached times. The default is 1 minute.

ENVIRONMENT
Environment variables can be used within an automount map. For instance, if $HOME appeared within a map, automount would expand it to its current value for the HOME variable. Environment variables are expanded only for the automounter's environment — not for the environment of a user using the automounter's services.

The special reference to $ARCH expands to the output of arch (1). This can be useful in creating a map entry for mounting executables using a server's export pathname that varies according to the architecture of the client reading the map.

If a reference needs to be protected from affixed characters, you can surround the variable name with curly braces.

USAGE

  Map Entry Format
A simple map entry (mapping) takes the form:

    key [ -mount-options ] location ...

where key is the full pathname of the directory to mount when used in a direct map, or simple name in an indirect map. mount-options is a comma-separated list of mount options, and location specifies a remote filesystem from which the directory may be mounted. In the simple case, location takes the form:

    hostname:pathname

  Replicated Filesystems
Multiple location fields can be specified for replicated read-only filesystems, in which case automount sends multiple mount requests; automount mounts the file system from the first host that replies to the mount request. This request is first made to the local net or subnet. If there is no response, any connected server may respond. Since automount does not monitor the status of the server while the filesystem is mounted it will not use another location in the list if the currently mounted server crashes. This support for replicated filesystems is available only at mount time.

If each location in the list shares the same pathname then a single location may be used with a comma-separated list of hostnames.

    hostname,hostname...:pathname

  Sharing Mounts
If location is specified in the form:

    hostname:pathname:subdir

hostname is the name of the server from which to mount the file system, pathname is the pathname of the directory to mount, and subdir, when supplied, is the name of a subdirectory to which the symbolic link is made. This can be used to prevent duplicate mounts when multiple directories in the same remote file system may be accessed. With a map for /home such as:

    able homeboy:/home/homeboy:able
    baker homeboy:/home/homeboy:baker

and a user attempting to access a file in /home/able, automount mounts homeboy:/home/homeboy, but creates a symbolic link called /home/able to the able subdirectory in the temporarily-mounted filesystem. If a user immediately tries to access a file in /home/baker, automount needs only to create a symbolic link that points to the baker subdirectory; /home/homeboy is already mounted.

With the following map:

    able homeboy:/home/homeboy/able
    baker homeboy:/home/homeboy/baker

automount would have to mount the filesystem twice.

  Comments and Quoting
A mapping can be continued across input lines by escaping the NEWLINE with a backslash. Comments begin with a # and end at the subsequent NEWLINE.

Characters that have special significance to the automount map parser may be protected either with double quotes (") or by escaping with a backslash (\). Pathnames with embedded whitespace, colons (:) or dollar ($) should be protected.

  Directory Pattern Matching
The `&' character is expanded to the value of the key field for the entry in which it occurs. In this case:

    able    homeboy:/home/homeboy:&

the & expands to able.

The `*' character, when supplied as the key field, is recognized as the catch-all entry. Such an entry will be used if any previous entry has not successfully matched the key being searched for. For instance, if the following entry appeared in the indirect map for /home:

    *    &:/home/&

this would allow automatic mounts in /home of any remote file system whose location could be specified as:

    hostname:/home/hostname

  Multiple Mounts

A multiple mount entry takes the form:

    key [ / [mountpoint [ -mount-options ] location ... ] ...

The initial / within the `/[mountpoint]' is required; the optional mountpoint is taken as a pathname relative to the destination of the symbolic link for key. If mountpoint is omitted in the first occurrence, a mountpoint of / is implied.

Given the direct map entry:

/arch/src   \
	/               	-ro,intr		arch:/arch/src      	alt:/arch/src   \
	/1.0           	-ro,intr		alt:/arch/src/1.0   	arch:/arch/src/1.0   \
	/1.0/man	-ro,intr		arch:/arch/src/1.0/man	alt:/arch/src/1.0/man

automount would automatically mount /arch/src, /arch/src/1.0 and /arch/src/1.0/man, as needed, from either arch or alt, whichever host responded first. If the mounts are hierarchically related mounts closer to the root must appear before submounts. All the mounts of a multiple mount entry will occur together and will be unmounted together. This is important if the filesystems reference each other with relative symbolic links. Multiple mount entries can be used both in direct maps and in indirect maps.

  Included Maps
The contents of another map can be included within a map with an entry of the form:

    +mapname

mapname can either be a filename, or the name of an NIS map, or one of the special maps described below. If the key being searched for is not located in an included map, the search continues with the next entry.

  Special Maps

There are two special maps currently available: -hosts, and -null. The -hosts map uses the NIS hosts.byname map to locate a remote host when the hostname is specified. This map specifies mounts of all exported file systems from any host. For instance, if the following automount command is already in effect:

    automount /net -hosts

then a reference to /net/hermes/usr would initiate an automatic mount of all file systems from hermes that automount can mount; references to a directory under /net/hermes will refer to the corresponding directory relative to hermes root.

The -null map, when indicated on the command line, cancels any subsequent map for the directory indicated. It can be used to cancel a map given in auto.master or for a mount point specified as an entry in a direct map.

  Configuration and the auto.master Map
automount normally consults the auto.master NIS configuration map for a list of initial automount maps, and sets up automatic mounts for them in addition to those given on the command line. If there are duplications, the command-line arguments take precedence over a local -f master map and they both take precedence over an NIS auto.master map. This configuration database contains arguments to the automount command, rather than mappings; unless -f is in effect, automount does not look for an auto.master file on the local host.

Maps given on the command line, or those given in a local auto.master file specified with -f override those in the NIS auto.master map. For instance, given the command:

    automount -f /etc/auto.master /home -null /- etc/auto.direct

and a file named /etc/auto.master that contains:

    /home auto.home

automount would ignore /home entry in /etc/auto.master.

FILES
/tmp_mnt
    directory under which filesystems are dynamically mounted

SEE ALSO
df(1V), ls(1V), stat(2V), passwd(5), mount(8)

NOTES

The -hosts map must mount all the exported filesystems from a server. If frequent access to just a single filesystem is required it is more efficient to access the filesystem with a map entry that is tailored to mount just the filesystem of interest.

When it receives signal number 1, SIGHUP, automount rereads the /etc/mtab file to update its internal record of currently-mounted file systems. If a file system mounted with automount is unmounted by a umount command, automount should be forced to reread the file.

An ls(1V) listing of the entries in the directory for an indirect map shows only the symbolic links for currently mounted filesystems. This restriction is intended to avoid unnecessary mounts as a side effect of programs that read the directory and stat(2V) each of the names.

Mount points for a single automounter must not be hierarchically related. automount will not allow an automount mount point to be created within an automounted filesystem.

automount must not be terminated with the SIGKILL signal (kill -9). Without an opportunity to unmount itself, the automount mount points will appear to the kernel to belong to a non-responding NFS server. The recommended way to terminate automount services is to send a SIGTERM (kill -15) signal to the daemon. This allows the automounter to catch the signal and unmount not only its daemon but also any mounts in /tmp_mnt. Mounts in /tmp_mnt that are busy will not be unmounted.

Since each direct map entry results in a separate mount for the mount daemon such maps should be kept short. Entries added to a direct map will have no effect until the automounter is restarted.

Entries in both direct and indirect maps can be modified at any time. The new information will be used when automount next uses the map entry to do a mount. automount does not cache map entries.

The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed.

BUGS

The bg mount option is not recognized by the automounter.

Since automount is single-threaded, any request that is delayed by a slow or non-responding NFS server will delay all subsequent automatic mount requests until it completes.

Programs that read /etc/mtab and then touch files that reside under automatic mount points will introduce further entries to the file.

Automatically-mounted file systems are mounted with type ignore; they do not appear in the output of either mount(8), or df(1V).