A    Writing Automount and AutoFS Maps

This appendix explains how to write AutoFS and Automount maps, which you can use to specify the file systems you intend to mount with the automount daemon or autofsd daemon  (see Section 4.1.2 and Section 4.6.3).

It also describes some fundamental differences between Automount and AutoFS, particularly in how these services interpret and execute the specified mounts.

Note

The Automount daemon will be retired in a future release of the operating system. For information about migrating from Automount to AutoFS, see Section 4.6.3.5.

With a few restrictions, as documented in this appendix and in the Restrictions section of autofsmount(8), Automount and AutoFS maps can be used interchangeably.

A.1    Map Conventions and Basic Syntax

Automount and AutoFS maps are configuration files that indicate which remote file systems to auto-mount, where to mount them, and which mount options to use. They can also contain entries that point to other map files in a hierarchical manner.

Conventionally, these map files are named with the prefix auto and they are located in the /etc directory on the local system. However, you can also distribute maps via NIS. Any system running Automount or AutoFS can use local maps, NIS maps, or a combination of both. See Section 4.6.3.4 for more information.

There are four types of maps:

The following sections explain the purpose and syntax for each type of map.

A.1.1    Master Map

The master map is the top-level map file for Automount or AutoFS. It contains only entries that point to other maps (direct, indirect, or special); it does not describe any mounts. However, it can contain mount options that apply to all of the mounts listed in the specified maps.

Each line in the master map has the following syntax: 


key  map [mount-options]

key

Names the directory for which the specified map applies. If the map argument is the name of an indirect map or the name of a special map, enter the full pathname of a local directory. If the map argument is a direct map, use the predefined dummy directory, /-. See Section A.1.2 and Section A.1.3 for more information.

map

Names the map that the automount or autofsmount command uses to find the mount points and locations. This can be a file name, an NIS map name, or a special map name.

mount-options

Lists the options used to regulate the mounting of entries listed in map.

The following map is an example of a master map: 

/-           auto.tools    -nosuid,hard,intr  [1]
/home        auto.home     -nosuid,hard,intr  [2]
/net         -hosts        -nosuid,hard,intr  [3]
 
 

In this master map, the entries have the following purpose:

  1. Points to a direct map called auto.tools, which describes mounts for shared applications. [Return to example]

  2. Points to an indirect map called auto.home, which describes mounts for users' home directories. [Return to example]

  3. Points to a special map called -hosts, which is described in Section A.1.4. [Return to example]

All of the entries include a string of mount options that apply to all mounts described within the respective map files. For a description of these mount options, see mount(8).

A.1.2    Direct Map

Direct maps specify the remote file systems to mount locally, the remote hosts that are serving those file systems, and the local directories on which those file systems are to be mounted. You can also use direct maps to specify the mount options for each file system.

Direct maps are so named because each mount they describe is associated with a fully qualfied mount point. (In contrast, the entries in indirect maps are associated with a parent directory that is specified in the master map.)

Direct maps have the following syntax: 


key [mount-options] location

key

Specifies the full pathname of the mount point.

mount-options

Lists the options for this specific mount. When present, these options override any mount options specified on the command line or in the master map.

location

Specifies the location of the resource being mounted and uses the format server:pathname. (For the mount to be successful, the file system must be exported from the specified server to the local host as described in Section 4.5.2.) Multiple location fields can be specified; see Section A.2.5 for more information.

The following map, auto.tools, is an example of an direct map: 

/tools/bin   apollo:/usr/opt/bin 
/tools/lib   apollo:/usr/opt/lib
/tools/man   apollo:/usr/opt/man

It describes the mounts for shared applications that are exported from the apollo production server. On that server, the file systems are located in the /usr/opt directory; however, on the client system, they are mounted in the /tools directory.

A.1.3    Indirect Map

Indirect maps have the same purpose and format as direct maps. However, unlike the key in a direct map, the key in an indirect map is a simple directory name that does not begin with a slash.

An indirect map as a whole is associated with a parent directory that is specified in the master map (as in Section A.1.1) or on the command line. The entries in an indirect map list subdirectories that are individually mounted within that parent directory.

The following map, auto.home, is an example of an indirect map: 

strauss   apollo:/usr/staff/strauss
cameron   apollo:/usr/staff/cameron
smith     zeus:/usr/staff/smith
samler    apollo:/usr/staff/samler
campbell  zeus:/usr/staff/campbell
larson    apollo:/usr/staff/larson

This map describes the mounts for users' home directories, which are exported from two production servers, zeus and apollo.

Because all of the user's directories listed in this map are mounted in the same parent directory, /home, there is no need to specify it in each entry. Instead, the indirect map as a whole is associated with the /home directory.

For example, the first entry in this file would be logically equivalent to the following direct map entry: 

/home/strauss   apollo:/usr/staff/strauss

A.1.4    Special Maps

The -hosts map and the -null map are special maps that are built into the automatic mounting daemons.

You can use the -hosts map to simultaneously mount all of the file systems that are exported from an NFS server listed in the local system's hosts database. (The hosts database that your system uses is determined by the services running on your system and the order in which those services are specified in the /etc/svc.conf file.)

You can use the -hosts map with the automount command as follows: 

# automount /net -hosts

Similarly, you can use the -hosts map with the autofsmount command, as follows: 

# autofsmount /net -hosts

Or, you can use the -hosts map in a map file, as shown in Section A.1.1.

If a user on the local system subsequently switches into the /net/hostname directory, where hostname is a server listed in the hosts database, all of the exported file systems from hostname are automatically mounted on the local system under the /net/hostname directory.

For example, suppose that hera and sheba are both hosts on a local area network that is running NIS. If superuser on hera enters the automount /net -hosts command, users on hera can access any directories that sheba exports to hera. All of the exported directories are mounted under /net/sheba on hera.

The -null map cancels the map associated with the directory indicated. You can use it to cancel a map specified in the master map. For example, invoking the automount command in the following manner causes the /net entry in auto.master to be ignored: 

# automount /net -null

The -null map works similarly with the autofsmount command, except if you intend to cancel an entry in an indirect map. In this special case, you need to use the -null option with the autofsd command. For example: 

# autofsd /works/dorado -null

When this command is executed, AutoFS cancels the mount associated with the /works/dorado mount point, which is specified in an indirect map.

A.2    Advanced Map Syntax

Automount and AutoFS provide additional syntax that allows you to write less redundant maps, and, in some cases, provides more control over how and when file systems are mounted. This syntax includes:

The following sections describe this syntax in more detail.

A.2.1    Substitution and Pattern Matching

Both the automount command and the autofsmount command recognize the ampersand (&) and asterisk (*) characters, which allow you to eliminate redundancy within maps.

You can use an ampersand as a substitute for the key name of a map entry whenever that key is repeated in the same map entry.

Ampersands are allowed in both direct and indirect maps; however, they are most efficient and easily understood in the context of indirect maps. The following example is an indirect map that does not use ampersands: 

#key               mount-options      location
#
host1              -rw,nosuid        host1:/home/host1
host2              -rw,nosuid        host2:/home/host2

Using the ampersand (&) as a substitution character, the entries read as follows: 

#key               mount-options     location
#
host1              -rw,nosuid        &:/home/&
host2              -rw,nosuid        &:/home/&

You can use the asterisk (*) to substitute for lines that are all formatted similarly. Both daemons use the asterisk to match any host not listed as a key in an entry before the asterisk.

The asterisk is allowed only in indirect maps. The following example shows how the asterisk (*) is typically used: 

#key               mount-options     location
#
host1              -rw,nosuid        &:/home/&
host2              -rw,nosuid        &:/home/&
*                  -rw,nosuid        &:/home/&

Suppose a user enters the following command: 

% ls /home/host5

Either daemon recognizes the host name, host5, as the key and substitutes host5 for each of the ampersands in the location field. The map is interpreted as follows for host5: 

#key               mount-options     location
#
host5              -rw,nosuid        host5:/home/host5

Note

The automount and autofsmount commands ignore any entry that follows an asterisk in a local map file.

A.2.2    Environment Variables

You can use the value of an environment variable in a map by adding a dollar sign ($) prefix to its name. You also can use braces ({ }) to delimit the name of the variable from appended letters or digits.

Environment variables can be inherited from the environment or can be defined explicitly with the -D option on the command line. For example, you can invoke the automount daemon with the HOST variable by entering the following command: 

# automount -D HOST=hostname

To define a variable with AutoFS, you must pass it to both the autofsd daemon and the autofsmount command, as follows: 

# autofsd -D HOST=hostname
# autofsmount -D HOST=hostname

Although you can define new variables while either service is running, you typically define them when you start Automount or AutoFS on your system.

The following is an example of a direct map entry that uses the standard environment variable HOST to specify a particular directory for the local host to mount: 

/mydir     -rw        apollo:/export/$HOST
 

The following is an example of a direct map entry that uses the explicitly defined environment variables MACH and OS to specify the correct tools directory for the local host's architecture and operating system: 

/tools     -rw     zeus:/tools/${MACH}.${OS}
 

The following is an example of a direct map entry that uses the explicitly defined environment variable NET to specify the appropriate host name for a server: 

/share/orchard/build/set5     -rw    {$NET}orchard:/share/orchard/build/set5
 

This is useful if the server is connected to several subnetworks, each referring to the server by a different host name.

A.2.3    Multiple Mounts

When you write direct and indirect maps, you can specify that different directories within a file system hierarchy be mounted from different servers. For example, if you mount the /usr/local file system on your machine, you can mount the various subdirectories within /usr/local from different servers.

The following example shows an entry in a direct map in which the directories /usr/local/bin, /usr/local/src, and /usr/local/man are mounted from the machines host1, host2, and host3, respectively: 

/usr/local\
                /bin    -ro        host1:/usr/local/bin \
                /src    -ro        host2:/usr/local/src \
                /man  -ro          host3:/usr/local/man

This entry, which is displayed over four lines with continuation marks (\) and indentation for readability, is an example of multiple, nonhierarchical mounts. These mounts are nonhierarchical because they are triggered on an individual basis as users switch into the respective directories, despite the fact that all of the mount points are located in the same /usr/local directory.

In contrast, when file systems are mounted hierarchically, the entire hierarchy is treated as one object. When a subdirectory within the hierarchy is referenced, the daemon mounts the entire hierarchy. The entire hierarchy is also unmounted as one object.

The following example shows a true hierarchical entry: 

/usr/local \
             /            -ro        host0:/usr/local \
             /bin         -ro        host1:/usr/local/bin \
             /src         -ro        host2:/usr/local/src \
             /tools       -ro        host3:/usr/local/tools

Here, the administrator adds the mount point / to mount /usr/local from host0, which completes the hierarchy. As a result, when a user switches into any subdirectory within /usr/local, such as /usr/local/bin, the daemon simultaneously mounts the entire /usr/local hierarchy.

The only exception with respect to hierarchical mounts is specific to AutoFS.

Like the automount daemon, the autofsd daemon creates symbolic links for file systems that are served locally. But if the autofsd daemon encounters an entry in a list of hierarchical file systems that is served locally and would result in a circular symbolic link on the local system (for example, a link from the /usr/local/bin directory back to itself), the group semantic is lost. AutoFS will mount and unmount the file systems on an individual basis.

This happens because AutoFS is designed to mount a remote file system on (or create a symbolic link to) the designated mount point itself. It does not, as Automount does, create an additional symbolic link back to a special temporary directory from which the remote file system is actually served. See Section A.4 for more information.

A.2.4    Shared Mounts

Shared mounts prevent duplicate mounts of the same remote file system when multiple subdirectories within it are accessed. Instead of creating a duplicate mount for each subdirectory, the daemon creates a symbolic link to the file system that is already mounted.

You can specify shared mounts by formatting the location field for each subdirectory entry as follows: 

host:path:subdir

Note

AutoFS does not support this syntax. If the autofsmount command encounters this syntax, it converts the final colon (:) to a slash (/) and treats the entry as a typical AutoFS mount.

The host field is the remote host from which to mount the file system. The path field is the pathname of the directory to mount, and the subdir field, if specified, is the name of the subdirectory to which the symbolic link is made.

Suppose an indirect map called /auto.myindirect is specified in a master file as follows: 

/mydir          /auto.myindirect
 

And the /auto.myindirect map consists of the following entries: 

mybin           host1:/usr/staff/diane:bin
mystuff         host1:/usr/staff/diane:stuff

When a user accesses a file in /mydir/mybin, the automount daemon mounts host1:/usr/staff/diane, but creates a symbolic link called /mydir/mybin to the bin subdirectory in the temporarily mounted file system. If a user immediately tries to access a file in /mydir/mystuff, the automount daemon needs only to create a symbolic link that points to the stuff subdirectory because the /usr/staff/diane directory is already mounted. With the following map, the daemon would perform two separate mount operations: 

mybin           host1:/usr/staff/diane/bin
mystuff         host1:/usr/staff/diane/stuff

A.2.5    Replicated File Systems

You can specify multiple locations for a single mount. If a file system is located on several servers and one of the servers is disabled, the file system can be mounted from one of the other servers. (This makes sense only when mounting a read-only file system, where there are no file changes to be synchronized.)

In the following example, the reference pages can be mounted from host1, machine2, or system3: 

/usr/man\
                -ro,soft        host1:/usr/man \
                                machine2:/usr/man \
                                system3:/usr/man

The preceding example can also be expressed as a list of servers, separated by commas and followed by a colon and the pathname, for example: 

/usr/man  -ro,soft  host1,machine2,system3:/usr/man

This syntax is valid only if the pathname is the same on each server.

When you access the reference pages, the automount daemon issues a ping request (NFS v2 loop request) to each of the specified servers concurrently and selects the first server that responds to serve the file system.

In contrast, the autofsd daemon first classifies each of the specified servers based on the proximity of its network address to the current system (Local, Same Subnet, Same Network, or Other Network). The daemon then attempts to serve the file system from the closest resource, starting with Local addresses.

If the file system can be served locally, the daemon uses a symbolic link to access it. If the file system cannot be served locally, the daemon resorts to trying all Same Subnet, Same Network, and Other Network addresses, in that order. Except when checking Local addresses, the system issues a ping request to each server concurrently and selects the first server that responds to serve the file system.

A.3    Map Examples

The examples in this section illustrate how the same maps can be rewritten in a number of ways.

Figure A-1 illustrates an auto.master map that points to the /etc/auto.direct direct map, the built-in -hosts map, and the /etc/auto.home indirect map. Each map to which the auto.master map points is expanded to show its sample contents.

Figure A-1:  Sample automount Maps

The following examples show how the /etc/auto.direct map in Figure A-1 can be rewritten using multiple mounts (Example A-1); multiple mounts and shared mounts (Example A-2); and multiple mounts, shared mounts, and replicated file systems (Example A-3).

Example A-1:  Multiple Mounts in a Direct Map

/mnt/mytmp                          june:/usr/staff/jones/tmp
/mnt/mynotes                        june:/usr/staff/jones/notes
/usr/arch       /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

Example A-2:  Multiple Mounts and Shared Mounts in a Direct Map

/mnt/mytmp                          june:/usr/staff/jones:tmp
/mnt/mynotes                        june:/usr/staff/jones:notes
/usr/arch       /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

Example A-3:  Multiple Mounts, Shared Mounts, and Replicated File Systems in a Direct Map

/mnt/mytmp                          june:/usr/staff/jones:tmp
/mnt/mynotes                        june:/usr/staff/jones:notes
/usr/arch       /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                                    bazel:/src/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                                    fiesta:/archive/uws\
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

The /etc/auto.direct maps in the preceding examples could be rewritten as indirect maps. If the /etc/auto.direct map is rewritten to be an indirect map, the entry pointing to it in the auto.master map would look like the following: 

/mnt     /etc/auto.indirect

Rewritten as a simple indirect map (/etc/auto.indirect), the /etc/auto.direct map in Figure A-1 would read as shown in Example A-4.

Example A-4:  Simple Indirect Map

mytmp           june:/usr/staff/jones/tmp
mynotes         june:/usr/staff/jones/notes
arch    -ro     chester:/usr/arch

The following examples illustrate that indirect maps can also be rewritten using multiple mounts (Example A-5); multiple mounts and shared mounts (Example A-6); and multiple mounts, shared mounts, and replicated file systems (Example A-7).

Example A-5:  Multiple Mounts in an Indirect Map

mytmp                               june:/usr/staff/jones/tmp
mynotes                             june:/usr/staff/jones/notes
arch            /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

Example A-6:  Multiple Mounts and Shared Mounts in an Indirect Map

mytmp                               june:/usr/staff/jones:tmp
mynotes                             june:/usr/staff/jones:notes
arch            /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

Example A-7:  Multiple Mounts, Shared Mounts, and Replicated File Systems in an Indirect Map

mytmp                               june:/usr/staff/jones:tmp
mynotes                             june:/usr/staff/jones:notes
arch            /             -ro   chester:/usr/arch \
                /bsd          -ro   chester:/usr/arch/bsd \
                                    bazel:/src/bsd \
                /standards    -ro   chester:/usr/arch/standards \
                /dec/uws      -ro   chester:/usr/arch/dec/uws \
                                    fiesta:/archive/uws\
                /dec/ultrix   -ro   chester:/usr/arch/dec/ultrix

As previously described, the -hosts map shown in Figure A-1 is a built-in map supplied by Automount and AutoFS. In this case, if a user switches into a directory called /net/hosts1 on the system running Automount or AutoFS , the system checks for references to host1 in the hosts database and attempts to mount all of the file systems exported by host1 on the local system.

The /etc/auto.home map shown in Figure A-1 is an indirect map that allows users to remotely mount their home directories. If necessary, it can be rewritten using substitution characters, as follows: 

user1  host1:/usr/staff/&
user2  host2:/usr/staff/&
user3  host2:/usr/staff/&
user4  host2:/usr/staff/&
user5  host3:/usr/staff/&

A.4    Understanding Automount and AutoFS Behavior

Automount and AutoFS are fundamentally the same in that both services allow you to automatically mount file systems on an as-needed basis. However, each service performs its function in a different manner that is mostly invisible to the end user.

The following sections describe:

A.4.1    Mounting Remote File Systems

The primary difference between Automount and AutoFS is that Automount serves remote file systems by mounting them in a temporary directory on the local system (/tmp_mount, by default) and creating symbolic links from that directory to the intended mount point. In contrast, AutoFS mounts remote file systems directly on their intended mount points on the local system (unless the file system exists on the local system itself, in which case, AutoFS creates a symbolic link).

Consider the following direct map example: 

/tools/bin   apollo:/usr/opt/bin 
/tools/lib   apollo:/usr/opt/lib
/tools/man   apollo:/usr/opt/man

If this map is served by Automount, and a user switches into /tools/bin on the local system, Automount responds by mounting the remote file system, /usr/opt/bin, in the local /tmp_mnt/apollo/tools/bin directory, then it creates a symbolic link from that directory to the intended target, /tools/bin.

If the same map is served by AutoFS, and a user switches into /tools/bin on the local system, AutoFS responds by mounting the remote file system, /usr/opt/bin, directly on the intended local target directory, /tools/bin. (AutoFS creates a symbolic link, from /usr/opt/bin to /tools/bin, only if the local system is the apollo server itself.)

Each behavior has its benefits. For example, because Automount mounts remote file systems in a temporary directory, you can use it to take advantage of shared mounts to prevent duplicate mounts of the same remote file system. AutoFS must mount these remote file systems on an individual basis.

On the other hand, AutoFS is more efficient because it does not deal with the overhead of a temporary directory and symbolic links. It also provides higher availability than Automount. Although the autofsd daemon must be running for mounts or unmounts to be performed, if it is killed or becomes unavailable, exisiting auto-mounted NFS file systems continue to be available. If the automount daemon fails, all of its auto-mounted file systems become unavailable because the automount daemon is required for lookups.

A.4.2    Inducing Automatic Mounts

Because the underlying mechanics of Automount and AutoFS are different, invoking file processing commands on a directory that contains intercept points (the key objects that trigger auto-mounts) can have vastly different results for each service.

For example, because many file processing commands do not follow symbolic links by default, these commands will not follow the symbolic links from an intercept point to Automount's temporary directory. Therefore, these file processing commands are not likely to process the contents of file systems that are served by Automount, even if those file systems were auto-mounted prior to the commands' execution.

For AutoFS, if the file processing command is designed to induce an auto-mount by AutoFS, the command will always process the contents of the auto-mounted file system, because AutoFS mounts file systems directly on their intercept points. As previously mentioned, AutoFS creates a symbolic link only if the local host is serving the requested file system. This type of symbolic link is recognized by many file processing commands, and, for consistency, is treated the same as any other file system served by AutoFS.

The following examples describe Automount and AutoFS behavior for the same command invoked in each environment. Except where noted, when a command's behavior differs for the AutoFS environment, the intention is to conform to Open Network Computing (ONC+) standards for AutoFS.

In all cases, directory is a directory that contains direct intercept points (the key objects named in direct maps).

Note

Indirect intercept points do not induce auto-mounts unless specifically named via a command.

Invoking a command on a directory that is a direct or indirect intercept point itself always induces an auto-mount and the subsequent processing of the auto-mounted file system's contents by the command that triggers the auto-mount.