--- name: "auto_master" section: "5" platform: "macos" package: "autofs" version: "322" release: "macOS 26.5" platforms: ["freebsd", "macos"] url: "https://new.carta.tech/auto_master" --- # auto\_master(5) automounter master map ## NAME **auto\_master** – automounter master map ## DESCRIPTION The **auto\_master** file contains a list of the directories that are to be automounted. Associated with each directory is the name of a map that lists the locations of the filesystems to be automounted there. The default map looks like this: ``` # # Automounter master map # +auto_master # Use directory service #/net -hosts -nobrowse,hidefromfinder,nosuid /home auto_home -nobrowse,hidefromfinder /Network/Servers -fstab /- -static ``` A “#” is the comment character. All characters from it to the end of line are ignored. A line beginning with “+” and followed by a name, indicates the name of a file or map accessible from a Directory Service source such as NIS or LDAP; the master map entries in that file or map are included at this point in the master map. A line that specifies a map to be mounted has the format: ``` mountpoint map -options ``` where *mountpoint* is the directory on which the map is to be mounted, *map* is the name of the map to be mounted, and *options* is an optional, comma-separated list of default mount options to be used by any entries in the map that do not have their own mount options. The **nobrowse** option is used on maps that have the potential to produce entries too numerous for browsing to be practical. This option as used in the master map is distinct from nobrowse used as a Mac OS X mount option, which affects the visibility of the mount to the Finder. The **hidefromfinder** option is used on maps that shouldn't show up as folders in the Finder; it causes the UF\_HIDDEN flag to be set on the root directory of the map. A *map* name beginning with / is the pathname of a file containing the map, otherwise the name represents a map to be found as a file in */etc* or to be read from Directory Service (and thus from whatever sources Directory Service uses, such as NIS or LDAP servers). Note that, in order to get automounter maps from NIS, the "BSD Flat File and NIS" plugin must, in the Directory Utility application, be enabled and configured to "Use NIS domain for authentication". If more than one entry in the master map has the same *mountpoint* then all but the first are ignored. For instance, in the following master map: ``` /shared my_auto_shared +auto_master ``` The */shared* entry overrides any */shared* specification imported from the network **auto\_master**. ## AUTOMOUNTER MAPS Automounter maps associate directories with the locations of filesystems that are to be mounted when the directory is accessed. Map entries have the general form: ``` key location ``` These map entries may be represented by lines in a file, NIS or LDAP tables indexed by the key, or from output of an executable map. Most commonly, the *location* is simply the name of an NFS server and the path to an exported file system, e.g. ``` local mynfs:/export/local ``` A *location* can also represent multiple mounts, where each is associated with a relative path, for example: ``` pkg \ /data mynfs:/export/pkg/data \ /bin mynfs:/export/pkg/bin \ /man mynfs:/export/pkg/man ``` Reference to this entry will provide access to any of three exported file systems from the server, each via its own subdirectory. Each of these sub-mounts will be done only when referenced. Note the use of a backslash to escape the newline so that the automounter will read these lines as a single map entry. The *location* can be preceded by a comma-separated list of mount options with a prepended “-”. For example: ``` bin -ro,nosuid mynfs:/export/bin ``` For file system types other than NFS, the mount option **-fstype**=⟨*type*⟩ can be used to specify the file system type. The *location* would be in the form expected by the mount command for that file system type. For example: ``` smb -fstype=smb //guest@smbserver/share afp -fstype=afp afp://;AUTH=NO%20USER%20AUTHENT@afpserver/share ``` If the *location* is a URL, with a scheme specifying AFP, NFS, or SMB, then, if no file system type is specified, the directory referred to by that URL will be mounted using [mount\_url(8)](/mount_url/8.md). For example: ``` nfsurl nfs://nfsserver/path/to/mount smburl smb://guest@smbserver/share afpurl afp://;AUTH=NO%20USER%20AUTHENT@afpserver/share ``` ## Replicated mounts More than one *location* can be specified in a map entry. At the time the mount is done, the automounter will choose one of those *locations* to mount. Locations not responding to an NFS null request at that time will not be considered, so that servers that are unavailable will not be chosen. Servers that are on the same subnet as the client will be chosen in preference to servers on different subnets. By default, in each of those sets of servers, the server with the shortest response time to the aforementioned NFS null request will be chosen. A *location* can be given a weighting factor; the higher the weighting factor, the lower the preference for that server. For example, with an entry such as ``` data net1a:/data net1b:/data net1c(1):/otherdata ``` if either host net1a or net1b is available, the one with the shortest response time will be chosen; host net1c will be chosen only if it is available and neither hosts net1a nor net1b are available. If all *locations* have the same path, a comma-separated list of hosts followed by the path can be used: ``` data net1a,net1b,net1c(1):/data ``` If a server that has been mounted becomes unavailable, the NFS client will not automatically fail over to another server; the mount must be unmounted and remounted in order for failover to occur. ## Direct Map A *direct* map associates filesystem locations directly with directories. The entry key is the full path name of a directory. For example: ``` /usr/local eng4:/export/local /src eng4:/export/src ``` Since the direct map as a whole isn't associated with a single directory, it is specified in the master map with a dummy directory name of */-*. ## Indirect Map An *indirect* map is used where a large number of entries are to be associated with a single directory. Each map entry key is the simple name of a directory entry. A good example of this is the *auto\_home* map which determines the entries under the */home* directory. For example: ``` bill argon:/export/home/bill brent depot:/export/home/brent guy depot:/export/home/guy ``` ## Executable Map An *executable* map is an indirect map represented by a file that has its execute bit set. Instead of reading entries from the file directly, the automounter executes the program or script passing the *key* as an argument and receiving the *location* string on stdout. If the automounter needs to enumerate map keys for a directory listing, it invokes the map with no arguments and expects a newline-separated list of keys on stdout. If an error occurs, the executable map must return a non-zero exit status and no output. For example, a map that, when bound to an Open Directory server, has one entry for every user, with the key being the user's login name and the entry being the URL of the user's home directory, could be implemented as ``` #!/bin/sh if [ $# = 0 ]; then # List keys dscl /Search -list Users exit fi # Return location homedirloc=`dscl /Search -read Users/$1 HomeDirectory` case "$homedirloc" in "No such key: HomeDirectory"*) homedirloc=`dscl /Search -read Users/$1 NFSHomeDirectory` case "$homedirloc" in "NFSHomeDirectory: /Network/Servers/"*) # # NFS home directory # echo "$homedirloc" | sed 's;NFSHomeDirectory: /Network/Servers//]*/;1:/2;' ;; *) # # Unknown # exit 1 ;; esac ;; "HomeDirectory: smb://"*) # # SMB home directory # echo "$homedirloc" | sed -e 's;HomeDirectory: ;;' -e 's;;/;' -e 's;;;' ;; *) # # Unknown # exit 1 ;; esac ``` (this is a simplified example; it does not handle users who do not have a network home directory, but includes them in the directory listing). ## Substituting the map key entry If a *location* in a map entry contains an ampersand (&), the ampersand will be replaced by the value of the key for the map entry. For example, a map entry of ``` bill argon:/export/home/& ``` is equivalent to a map entry of ``` bill argon:/export/home/bill ``` ## Wildcards If the key in an indirect map entry is an asterisk (\*), that entry will match any name that isn't matched by any other entry. For example, a map with ``` bill argon:/export/home/bill * depot:/export/home/& ``` as entries will mount *argon:/export/home/bill* on *bill* and will mount *depot:/export/home/{user}* on *{user}* for all other values of *{user}*. ## Variables A *location* string in a map can contain references to variables. A reference to a variable consists of dollar sign ($) followed by the name of the variable. A variable name is a sequence of alphanumeric characters and underscores; the name of the variable can be contained in curly braces to separate the variable reference from any alphanumeric characters or underscores following it. There are some predefined variables: - **ARCH** System architecture ("macintosh" on Macintoshes). - **CPU** Processor type, as reported by **uname -p** ("powerpc" on PowerPC Macintoshes, "i386" on Intel Macintoshes). - **HOST** This machine's host name. - **OSNAME** Operating system name, as reported by **uname -s** ("Darwin" in OS X). - **OSREL** Operating system release, as reported by **uname -r** (for example, 9.3.0 in Mac OS X 10.5.3). - **OSVERS** Operating system version, as reported by **uname -v** (this string is a long string with spaces in Mac OS X, and is not very useful in automounter maps). For example, a direct map entry such as ``` /usr/local/bin -ro server:/export/bin/$OSNAME/$CPU ``` would mount on */usr/local/bin* a directory from the specified server containing executable images appropriate to the operating system and CPU type of the machine. In addition, any environment variable set in the environment of [automountd(8)](/automountd/8.md) can be used as a variable name; those variables can be set with the AUTOMOUNTD\_ENV parameter in the [autofs.conf(5)](/autofs.conf/5.md) file. ## Quoting Special characters, such as white space characters, a dollar sign, or an ampersand can be quoted by escaping them with a backslash (\\); this prevents white space from being interpreted as a field separator, prevents a dollar sign from being interpreted as the beginning of a variable name, and prevents an ampersand from being interpreted as the key field for the entry in which it occurs. A sequence of characters can also be quoted by enclosing it in double-quotes ("). ## Special Maps The special maps have reserved names and are built into the automounter. - \-fstab This map would normally be mounted on */Network/Servers*. The key is the host name of a server; the contents of the map entry are generated from corresponding entries in [fstab(5)](/fstab/5.md) data (as provided by [getfsent(3)](/getfsent/3.md)) that have the net option and that specify mounts from that server. An entry of the form ``` server:/path mountpoint fstype options 0 0 ``` will be mounted in *server*/*path* under the mount point of the -fstab map, using the specified *fstype* file system type and the specified *options*. The *mountpoint* is ignored. - \-hosts This map would normally be mounted on */net*. The key is the host name of an NFS server; the contents of the map are generated from the list of file systems exported by that server. For example, a server that exports three NFS filesystems might have an equivalent map entry of: ``` myserv \ /export/home myserv:/export/home \ /export/local myserv:/export/local \ /export/pkg myserv:/export/pkg ``` To access the first mount, the path would be */net/myserv/export/home* if the map was associated with */net*. - \-null This map has no entries. It is used to disable entries that occur later in the **auto\_master** file. For example: ``` /shared -null +auto_master ``` The -null entry disables any */shared* entry in +auto\_master. - \-static This map is a direct map, so the mount point must be specified as */-*. The contents are generated from all entries in [fstab(5)](/fstab/5.md) data (as provided by [getfsent(3)](/getfsent/3.md)) that do not have the net option. An [fstab(5)](/fstab/5.md) entry of the form ``` server:/path mountpoint fstype options rw 0 0 ``` will generate a direct map entry of the form ``` mountpoint options server:/path ``` ## FILES - */etc/auto\_master* The master map file. ## SEE ALSO [automount(8)](/automount/8.md), [automountd(8)](/automountd/8.md), [autofsd(8)](/autofsd/8.md), [autofs.conf(5)](/autofs.conf/5.md), [fstab(5)](/fstab/5.md), [getfsent(3)](/getfsent/3.md), DirectoryService(8)