1.\" Copyright (c) 2014 The FreeBSD Foundation 2.\" 3.\" This software was developed by Edward Tomasz Napierala under sponsorship 4.\" from the FreeBSD Foundation. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd December 28, 2018 30.Dt AUTO_MASTER 5 31.Os 32.Sh NAME 33.Nm auto_master 34.Nd auto_master and map file format 35.Sh DESCRIPTION 36The automounter configuration consists of the 37.Nm 38configuration file, which assigns filesystem paths to map names, 39and maps, which contain actual mount information. 40The 41.Nm 42configuration file is used by the 43.Xr automount 8 44command. 45Map files are read by the 46.Xr automountd 8 47daemon. 48.Sh AUTO_MASTER SYNTAX 49The 50.Nm 51file consists of lines with two or three entries separated by whitespace 52and terminated by newline character: 53.Bd -literal -offset indent 54.Pa mountpoint Pa map_name Op Ar -options 55.Ed 56.Pp 57.Pa mountpoint 58is either a fully specified path, or 59.Li /- . 60When 61.Pa mountpoint 62is a full path, 63.Pa map_name 64must reference an indirect map. 65Otherwise, 66.Pa map_name 67must reference a direct map. 68See 69.Sx "MAP SYNTAX" below. 70.Pp 71.Pa map_name 72specifies map to use. 73If 74.Pa map_name 75begins with 76.Li - , 77it specifies a special map. 78See 79.Sx "MAP SYNTAX" 80below. 81If 82.Pa map_name 83is not a fully specified path 84.Pq it does not start with Li / , 85.Xr automountd 8 86will search for that name in 87.Li /etc . 88Otherwise it will use the path as given. 89If the file indicated by 90.Pa map_name 91is executable, 92.Xr automountd 8 93will assume it is an executable map. 94See 95.Sx "MAP SYNTAX" 96below. 97Otherwise, the file is opened and the contents parsed. 98.Pp 99.Pa -options 100is an optional field that starts with 101.Li - 102and can contain generic filesystem mount options. 103.Pp 104The following example specifies that the /etc/auto_example indirect map 105will be mounted on /example. 106.Bd -literal -offset indent 107/example auto_example 108.Ed 109.Sh MAP SYNTAX 110Map files consist of lines with a number of entries separated by whitespace 111and terminated by newline character: 112.Bd -literal -offset indent 113.Pa key Oo Ar -options Oc Oo Ar mountpoint Oo -options Oc Oc Ar location Op ... 114.Ed 115.Pp 116In most cases, it can be simplified to: 117.Bd -literal -offset indent 118.Pa key Oo Ar -options Oc Ar location 119.Ed 120.Pp 121.Pa key 122is the path component used by 123.Xr automountd 8 124to find the right map entry to use. 125It is also used to form the final mountpoint. 126A wildcard 127.Pq Ql * 128can be used for the key. 129It matches every directory that does not match other keys. 130Those directories will not be visible to the user 131until accessed. 132.Pp 133The 134.Ar options 135field, if present, must begin with 136.Li - . 137When mounting the filesystem, options supplied to 138.Nm 139and options specified in the map entry are concatenated together. 140The special option 141.Li fstype 142is used to specify filesystem type. 143It is not passed to the mount program as an option. 144Instead, it is passed as an argument to 145.Cm "mount -t". 146The default 147.Li fstype 148is 149.Ql nfs . 150The special option 151.Li nobrowse 152is used to disable creation of top-level directories for special 153and executable maps. 154.Pp 155The optional 156.Pa mountpoint 157field is used to specify multiple mount points 158for a single key. 159.Pp 160The 161.Ar location 162field specifies the filesystem to be mounted. 163Ampersands 164.Pq Ql & 165in the 166.Ar location 167field are replaced with the value of 168.Ar key . 169This is typically used with wildcards, like: 170.Bd -literal -offset indent 171.Li * 192.168.1.1:/share/& 172.Ed 173.Pp 174The 175.Ar location 176field may contain references to variables, like: 177.Bd -literal -offset indent 178.Li sys 192.168.1.1:/sys/${OSNAME} 179.Ed 180.Pp 181Defined variables are: 182.Pp 183.Bl -tag -width "-OSNAME" -compact 184.It Li ARCH 185Expands to the output of 186.Li "uname -p" . 187.It Li CPU 188Same as ARCH. 189.It Li DOLLAR 190A literal $ sign. 191.It Li HOST 192Expands to the output of 193.Li "uname -n" . 194.It Li OSNAME 195Expands to the output of 196.Li "uname -s" . 197.It Li OSREL 198Expands to the output of 199.Li "uname -r" . 200.It Li OSVERS 201Expands to the output of 202.Li "uname -v" . 203.El 204.Pp 205Additional variables can be defined with the 206.Fl D 207option of 208.Xr automount 8 209and 210.Xr automountd 8 . 211.Pp 212To pass a location that begins with 213.Li / , 214prefix it with a colon. 215For example, 216.Li :/dev/cd0 . 217.Pp 218This example, when put into 219.Pa /etc/auto_example , 220and with 221.Nm 222referring to the map as described above, specifies that the NFS share 223.Li 192.168.1.1:/share/example/x 224will be mounted on 225.Pa /example/x/ 226when any process attempts to access that mountpoint, with 227.Li intr 228and 229.Li nfsv4 230mount options, described in 231.Xr mount_nfs 8 : 232.Bd -literal -offset indent 233.Li x -intr,nfsv4 192.168.1.1:/share/example/x 234.Ed 235.Pp 236Automatically mount an SMB share on access, as a guest user, 237without prompting for a password: 238.Bd -literal -offset indent 239.Li share -fstype=smbfs,-N ://@server/share 240.Ed 241.Pp 242Automatically mount the CD drive on access: 243.Bd -literal -offset indent 244.Li cd -fstype=cd9660 :/dev/cd0 245.Ed 246.Sh SPECIAL MAPS 247Special maps have names beginning with 248.Li - . 249Supported special maps are: 250.Pp 251.Bl -tag -width "-hosts" -compact 252.It Li -hosts 253Query the remote NFS server and map exported shares. 254This map is traditionally mounted on 255.Pa /net . 256Access to files on a remote NFS server is provided through the 257.Pf /net/ Ar nfs-server-ip Ns / Ns Ar share-name Ns / 258directory without any additional configuration. 259Directories for individual NFS servers are not present until the first access, 260when they are automatically created. 261.It Li -media 262Query devices that are not yet mounted, but contain valid filesystems. 263Generally used to access files on removable media. 264.It Li -noauto 265Mount filesystems configured in 266.Xr fstab 5 267as "noauto". 268This needs to be set up as a direct map. 269.It Li -null 270Prevent 271.Xr automountd 8 272from mounting anything on the mountpoint. 273.El 274.Pp 275It is possible to add custom special maps by adding them, as executable 276maps named 277.Pa special_foo , 278to the 279.Pa /etc/autofs/ 280directory. 281.Sh EXECUTABLE MAPS 282If the map file specified in 283.Nm 284has the execute bit set, 285.Xr automountd 8 286will execute it and parse the standard output instead of parsing 287the file contents. 288When called without command line arguments, the executable is 289expected to output a list of available map keys separated by 290newline characters. 291Otherwise, the executable will be called with a key name as 292a command line argument. 293Output from the executable is expected to be the entry for that key, 294not including the key itself. 295.Sh INDIRECT VERSUS DIRECT MAPS 296Indirect maps are referred to in 297.Nm 298by entries with a fully qualified path as a mount point, and must contain only 299relative paths as keys. 300Direct maps are referred to in 301.Nm 302by entries with 303.Li /- 304as the mountpoint, and must contain only fully qualified paths as keys. 305For indirect maps, the final mount point is determined by concatenating the 306.Nm 307mountpoint with the map entry key and optional map entry mountpoint. 308For direct maps, the final mount point is determined by concatenating 309the map entry key with the optional map entry mountpoint. 310.Pp 311The example above could be rewritten using direct map, by placing this in 312.Nm : 313.Bd -literal -offset indent 314.Li /- auto_example 315.Ed 316.Pp 317and this in 318.Li /etc/auto_example 319map file: 320.Bd -literal -offset indent 321.Li /example/x -intr,nfsv4 192.168.1.1:/share/example/x 322.Li /example/share -fstype=smbfs,-N ://@server/share 323.Li /example/cd -fstype=cd9660 :/dev/cd0 324.Ed 325.Sh DIRECTORY SERVICES 326Both 327.Nm 328and maps may contain entries consisting of a plus sign and map name: 329.Bd -literal -offset indent 330.Li +auto_master 331.Ed 332.Pp 333Those entries cause 334.Xr automountd 8 335daemon to retrieve the named map from directory services (like LDAP) 336and include it where the entry was. 337.Pp 338If the file containing the map referenced in 339.Nm 340is not found, the map will be retrieved from directory services instead. 341.Pp 342To retrieve entries from directory services, 343.Xr automountd 8 344daemon runs 345.Pa /etc/autofs/include , 346which is usually a shell script, with map name as the only command line 347parameter. 348The script should output entries formatted according to 349.Nm 350or automounter map syntax to standard output. 351An example script to use LDAP is included in 352.Pa /etc/autofs/include_ldap . 353It can be symlinked to 354.Pa /etc/autofs/include . 355.Sh FILES 356.Bl -tag -width ".Pa /etc/auto_master" -compact 357.It Pa /etc/auto_master 358The default location of the 359.Pa auto_master 360file. 361.It Pa /etc/autofs/ 362Directory containing shell scripts to implement special maps and directory 363services. 364.El 365.Sh SEE ALSO 366.Xr autofs 5 , 367.Xr automount 8 , 368.Xr automountd 8 , 369.Xr autounmountd 8 370.Sh AUTHORS 371The 372.Nm 373configuration file functionality was developed by 374.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 375under sponsorship from the FreeBSD Foundation. 376