1.Dd April 20, 2007 2.Dt AUTO_MASTER 5 3.Os Darwin 4.Sh NAME 5.Nm auto_master 6.Nd 7automounter master map 8.Sh DESCRIPTION 9The 10.Nm 11file contains a list of the directories that are to be automounted. 12Associated with each directory is the name of a map that lists the 13locations of the filesystems to be automounted there. 14The default map looks like this: 15.Bd -literal -offset indent 16# 17# Automounter master map 18# 19+auto_master # Use directory service 20/net -hosts -nobrowse,hidefromfinder,nosuid 21/home auto_home -nobrowse,hidefromfinder 22/Network/Servers -fstab 23/- -static 24.Ed 25.Pp 26A 27.Dq # 28is the comment character. All characters from it to the end of 29line are ignored. 30A line beginning with 31.Dq + 32and followed by a name, indicates the name of a file or map accessible 33from a Directory Service source such as NIS or LDAP; 34the master map entries in that file or map are included at this point 35in the master map. 36A line that specifies a map to be mounted has the format: 37.Pp 38.Dl Va mountpoint map -options 39.Pp 40where 41.Va mountpoint 42is the directory on which the map is to be mounted, 43.Va map 44is the name of the map to be mounted, and 45.Va options 46is an optional, comma-separated list of default 47mount options to be used by any entries in the map 48that do not have their own mount options. 49The 50.Cm nobrowse 51option is used on maps that have the potential to 52produce entries too numerous for browsing to 53be practical. This option as used in the master 54map is distinct from nobrowse used as a Mac OS X 55mount option, which affects the visibility of the 56mount to the Finder. 57The 58.Cm hidefromfinder 59option is used on maps that shouldn't show up as folders in the Finder; 60it causes the 61.Dv UF_HIDDEN 62flag to be set on the root directory of the map. 63.Pp 64A 65.Va map 66name beginning with / is 67the pathname of a file containing the map, otherwise 68the name represents a map to be found as a file in 69.Pa /etc 70or to be read from Directory Service (and thus from whatever sources 71Directory Service uses, such as NIS or LDAP servers). 72.Pp 73Note that, in order to get automounter maps from NIS, the "BSD Flat File 74and NIS" plugin must, in the Directory Utility application, be enabled 75and configured to "Use NIS domain for authentication". 76.Pp 77If more than one entry in the master map has the same 78.Va mountpoint 79then all but the first are ignored. 80For instance, in the following master map: 81.Bd -literal -offset indent 82/shared my_auto_shared 83+auto_master 84.Ed 85.Pp 86The 87.Pa /shared 88entry overrides any 89.Pa /shared 90specification imported from the network 91.Nm . 92.Sh AUTOMOUNTER MAPS 93Automounter maps associate directories with the locations of 94filesystems that are to be mounted when the directory is accessed. 95Map entries have the general form: 96.Pp 97.Dl Va key location 98.Pp 99These map entries may be represented by lines in a file, 100NIS or LDAP tables indexed by the key, or from output of 101an executable map. 102Most commonly, the 103.Va location 104is simply the name of an NFS 105server and the path to an exported file system, e.g. 106.Bd -literal -offset indent 107local mynfs:/export/local 108.Ed 109.Pp 110A 111.Va location 112can also represent multiple mounts, where each 113is associated with a relative path, for example: 114.Bd -literal -offset indent 115pkg \\ 116 /data mynfs:/export/pkg/data \\ 117 /bin mynfs:/export/pkg/bin \\ 118 /man mynfs:/export/pkg/man 119.Ed 120.Pp 121Reference to this entry will provide access to any 122of three exported file systems from the server, each via 123its own subdirectory. 124Each of these sub-mounts will be done only when referenced. 125Note the use of a backslash to escape the newline so that 126the automounter will read these lines as a single map entry. 127.Pp 128The 129.Va location 130can be preceded by a comma-separated list of mount options 131with a prepended 132.Dq - . 133For example: 134.Bd -literal -offset indent 135bin -ro,nosuid mynfs:/export/bin 136.Ed 137.Pp 138For file system types other than NFS, the mount option 139.Cm -fstype Ns = Ns Aq Ar type 140can be used to specify the file system type. The 141.Va location 142would be in the form expected by the mount command for that file system 143type. 144For example: 145.Bd -literal -offset indent 146smb -fstype=smb //guest@smbserver/share 147afp -fstype=afp afp://;AUTH=NO%20USER%20AUTHENT@afpserver/share 148.Ed 149.Pp 150If the 151.Va location 152is a URL, with a scheme specifying AFP, NFS, or SMB, then, 153if no file system type is specified, 154the directory referred to by that URL will be mounted using 155.Xr mount_url 8 . 156For example: 157.Bd -literal -offset indent 158nfsurl nfs://nfsserver/path/to/mount 159smburl smb://guest@smbserver/share 160afpurl afp://;AUTH=NO%20USER%20AUTHENT@afpserver/share 161.Ed 162.Sh Replicated mounts 163More than one 164.Va location 165can be specified in a map entry. At the time the mount is done, the 166automounter will choose one of those 167.Va locations 168to mount. Locations not responding to an NFS null request at that time 169will not be considered, so that servers that are unavailable will not be 170chosen. Servers that are on the same subnet as the client will be 171chosen in preference to servers on different subnets. 172.Pp 173By default, in each of those sets of servers, the server with the 174shortest response time to the aforementioned NFS null request will be 175chosen. A 176.Va location 177can be given a weighting factor; the higher the weighting factor, the 178lower the preference for that server. For example, with an entry such 179as 180.Bd -literal -offset indent 181data net1a:/data net1b:/data net1c(1):/otherdata 182.Ed 183.Pp 184if either host net1a or net1b is available, the one with the shortest 185response time will be chosen; host net1c will be chosen only if it is 186available and neither hosts net1a nor net1b are available. 187.Pp 188If all 189.Va locations 190have the same path, a comma-separated list of hosts followed by the path 191can be used: 192.Bd -literal -offset indent 193data net1a,net1b,net1c(1):/data 194.Ed 195.Pp 196If a server that has been mounted becomes unavailable, the NFS client 197will not automatically fail over to another server; the mount must be 198unmounted and remounted in order for failover to occur. 199.Sh Direct Map 200A 201.Em direct 202map associates filesystem locations directly with directories. 203The entry key is the full path name of a directory. 204For example: 205.Bd -literal -offset indent 206/usr/local eng4:/export/local 207/src eng4:/export/src 208.Ed 209.Pp 210Since the direct map as a whole isn't associated with a single 211directory, it is specified in the master map with a dummy 212directory name of 213.Pa /- . 214.Sh Indirect Map 215An 216.Em indirect 217map is used where a large number of entries are to be associated 218with a single directory. Each map entry key is the simple name of a 219directory entry. A good example of this is the 220.Pa auto_home 221map which determines the entries under the 222.Pa /home 223directory. 224For example: 225.Bd -literal -offset indent 226bill argon:/export/home/bill 227brent depot:/export/home/brent 228guy depot:/export/home/guy 229.Ed 230.Pp 231.Sh Executable Map 232An 233.Em executable 234map is an indirect map represented by a file that has its execute bit set. 235Instead of reading entries from the file directly, the automounter 236executes the program or script passing the 237.Va key 238as an argument and receiving the 239.Va location 240string on stdout. 241If the automounter needs to enumerate map keys for a directory listing, 242it invokes the map with no arguments and expects a newline-separated 243list of keys on stdout. 244.Pp 245If an error occurs, the executable map must return a non-zero 246exit status and no output. 247.Pp 248For example, a map that, when bound to an Open 249Directory server, has one entry for every user, with the key being the 250user's login name and the entry being the URL of the user's home 251directory, could be implemented as 252.Bd -literal -offset indent 253#!/bin/sh 254if [ $# = 0 ]; then # List keys 255 dscl /Search -list Users 256 exit 257fi 258# Return location 259homedirloc=`dscl /Search -read Users/$1 HomeDirectory` 260case "$homedirloc" in 261 262"No such key: HomeDirectory"*) 263 homedirloc=`dscl /Search -read Users/$1 NFSHomeDirectory` 264 case "$homedirloc" in 265 266 "NFSHomeDirectory: /Network/Servers/"*) 267 # 268 # NFS home directory 269 # 270 echo "$homedirloc" | sed 's;NFSHomeDirectory: /Network/Servers/\([^/]*\)/\(.*\);\1:/\2;' 271 ;; 272 273 *) 274 # 275 # Unknown 276 # 277 exit 1 278 ;; 279 esac 280 ;; 281 282"HomeDirectory: <home_dir><url>smb://"*) 283 # 284 # SMB home directory 285 # 286 echo "$homedirloc" | sed -e 's;HomeDirectory: <home_dir><url>;;' -e 's;</url><path>;/;' -e 's;</path></home_dir>;;' 287 ;; 288 289*) 290 # 291 # Unknown 292 # 293 exit 1 294 ;; 295esac 296.Ed 297.Pp 298(this is a simplified example; it does not handle users who do not have 299a network home directory, but includes them in the directory listing). 300.Sh Substituting the map key entry 301If a 302.Va location 303in a map entry contains an ampersand (&), the ampersand will be replaced 304by the value of the key for the map entry. For example, a map entry of 305.Bd -literal -offset indent 306bill argon:/export/home/& 307.Ed 308.Pp 309is equivalent to a map entry of 310.Bd -literal -offset indent 311bill argon:/export/home/bill 312.Ed 313.Sh Wildcards 314If the key in an indirect map entry is an asterisk (*), that entry will 315match any name that isn't matched by any other entry. For example, a 316map with 317.Bd -literal -offset indent 318bill argon:/export/home/bill 319* depot:/export/home/& 320.Ed 321.Pp 322as entries will mount 323.Pa argon:/export/home/bill 324on 325.Pa bill 326and will mount 327.Pa depot:/export/home/{user} 328on 329.Pa {user} 330for all other values of 331.Pa {user} . 332.Sh Variables 333A 334.Va location 335string in a map can contain references to variables. A reference to a 336variable consists of dollar sign ($) followed by the name of the 337variable. A variable name is a sequence of alphanumeric characters and 338underscores; the name of the variable can be contained in 339curly braces to separate the variable reference from any alphanumeric 340characters or underscores following it. 341There are some predefined variables: 342.Bl -tag -width "OSNAME" -offset indent 343.It Sy ARCH 344System architecture ("macintosh" on Macintoshes). 345.It Sy CPU 346Processor type, as reported by 347.Ic "uname -p" 348("powerpc" on PowerPC Macintoshes, "i386" on Intel Macintoshes). 349.It Sy HOST 350This machine's host name. 351.It Sy OSNAME 352Operating system name, as reported by 353.Ic "uname -s" 354("Darwin" in OS X). 355.It Sy OSREL 356Operating system release, as reported by 357.Ic "uname -r" 358(for example, 9.3.0 in Mac OS X 10.5.3). 359.It Sy OSVERS 360Operating system version, as reported by 361.Ic "uname -v" 362(this string is a long string with spaces in Mac OS X, and is not very 363useful in automounter maps). 364.El 365.Pp 366For example, a direct map entry such as 367.Bd -literal -offset indent 368/usr/local/bin -ro server:/export/bin/$OSNAME/$CPU 369.Ed 370.Pp 371would mount on 372.Pa /usr/local/bin 373a directory from the specified server containing executable images 374appropriate to the operating system and CPU type of the machine. 375.Pp 376In addition, any environment variable set in the environment of 377.Xr automountd 8 378can be used as a variable name; those variables can be set 379with the 380.Dv AUTOMOUNTD_ENV 381parameter in the 382.Xr autofs.conf 5 383file. 384.Sh Quoting 385Special characters, such as white space characters, a dollar sign, or an 386ampersand can be quoted by escaping them with a backslash (\e); this 387prevents white space from being interpreted as a field separator, 388prevents a dollar sign from being interpreted as the beginning of a 389variable name, and prevents an ampersand from being interpreted as the 390key field for the entry in which it occurs. A sequence of characters 391can also be quoted by enclosing it in double-quotes ("). 392.Sh Special Maps 393The special maps have reserved names and are built into the automounter. 394.Bl -tag 395.It Dv -fstab 396This map would normally be mounted on 397.Pa /Network/Servers . 398The key is the host name of a server; the contents of the map entry are 399generated from corresponding entries in 400.Xr fstab 5 401data (as provided by 402.Xr getfsent 3 Ns ) 403that have the 404.Li net 405option and that specify mounts from that server. An entry of the form 406.Bd -literal -offset indent 407server:/path mountpoint fstype options 0 0 408.Ed 409.Pp 410will be mounted in 411.Va server Ns / Ns Va path 412under the mount point of the 413.Dv -fstab 414map, using the specified 415.Va fstype 416file system type and the specified 417.Va options . 418The 419.Va mountpoint 420is ignored. 421.It Dv -hosts 422This map would normally be mounted on 423.Pa /net . 424The key is the host name of an NFS server; the contents of the map are 425generated from the list of file systems exported by that server. 426For example, a server that exports three NFS filesystems might have 427an equivalent map entry of: 428.Bd -literal -offset indent 429myserv \\ 430 /export/home myserv:/export/home \\ 431 /export/local myserv:/export/local \\ 432 /export/pkg myserv:/export/pkg 433.Ed 434.Pp 435To access the first mount, the path would be 436.Pa /net/myserv/export/home 437if the map was associated with 438.Pa /net . 439.It Dv -null 440This map has no entries. 441It is used to disable entries that occur later in the 442.Nm 443file. 444For example: 445.Bd -literal -offset indent 446/shared -null 447+auto_master 448.Ed 449.Pp 450The -null entry disables any 451.Pa /shared 452entry in +auto_master. 453.It Dv -static 454This map is a direct map, so the mount point must be specified as 455.Pa /- Ns . 456The contents are generated from all entries in 457.Xr fstab 5 458data (as provided by 459.Xr getfsent 3 Ns ) 460that do not have the 461.Li net 462option. An 463.Xr fstab 5 464entry of the form 465.Bd -literal -offset indent 466server:/path mountpoint fstype options rw 0 0 467.Ed 468.Pp 469will generate a direct map entry of the form 470.Bd -literal -offset indent 471mountpoint options server:/path 472.Ed 473.Pp 474.El 475.Sh FILES 476.Bl -tag -width /etc/auto_master -compact 477.It Pa /etc/auto_master 478The master map file. 479.El 480.Sh SEE ALSO 481.Xr automount 8 , 482.Xr automountd 8 , 483.Xr autofsd 8 , 484.Xr autofs.conf 5 , 485.Xr fstab 5 , 486.Xr getfsent 3 , 487.Xr DirectoryService 8 488