1.\" Copyright (c) 2016 The DragonFly Project 2.\" Copyright (c) 2014 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" This software was developed by Edward Tomasz Napierala under sponsorship 6.\" from the FreeBSD Foundation. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd April 14, 2016 32.Dt AUTO_MASTER 5 33.Os 34.Sh NAME 35.Nm auto_master 36.Nd auto_master and map file format 37.Sh DESCRIPTION 38The automounter configuration consists of the 39.Nm 40configuration file, which assigns filesystem paths to map names, 41and maps, which contain actual mount information. 42The 43.Nm 44configuration file is used by the 45.Xr automount 8 46command. 47Map files are read by the 48.Xr automountd 8 49daemon. 50.Sh AUTO_MASTER SYNTAX 51The 52.Nm 53file consists of lines with two or three entries separated by whitespace 54and terminated by newline character: 55.Bd -literal -offset indent 56.Pa mountpoint Pa map_name Op Ar -options 57.Ed 58.Pp 59.Pa mountpoint 60is either a fully specified path, or 61.Li /- . 62When 63.Pa mountpoint 64is a full path, 65.Pa map_name 66must reference an indirect map. 67Otherwise, 68.Pa map_name 69must reference a direct map. 70See 71.Sx "MAP SYNTAX" below. 72.Pp 73.Pa map_name 74specifies map to use. 75If 76.Pa map_name 77begins with 78.Li - , 79it specifies a special map. 80See 81.Sx "MAP SYNTAX" 82below. 83If 84.Pa map_name 85is not a fully specified path 86.Pq it does not start with Li / , 87.Xr automountd 8 88will search for that name in 89.Li /etc . 90Otherwise it will use the path as given. 91If the file indicated by 92.Pa map_name 93is executable, 94.Xr automountd 8 95will assume it is an executable map. 96See 97.Sx "MAP SYNTAX" 98below. 99Otherwise, the file is opened and the contents parsed. 100.Pp 101.Pa -options 102is an optional field that starts with 103.Li - 104and can contain generic filesystem mount options. 105.Pp 106The following example specifies that the /etc/auto_example indirect map 107will be mounted on /example. 108.Bd -literal -offset indent 109/example auto_example 110.Ed 111.Sh MAP SYNTAX 112Map files consist of lines with a number of entries separated by whitespace 113and terminated by newline character: 114.Bd -literal -offset indent 115.Pa key Oo Ar -options Oc Oo Ar mountpoint Oo -options Oc Oc Ar location Op ... 116.Ed 117.Pp 118In most cases, it can be simplified to: 119.Bd -literal -offset indent 120.Pa key Oo Ar -options Oc Ar location 121.Ed 122.Pp 123.Pa key 124is the path component used by 125.Xr automountd 8 126to find the right map entry to use. 127It is also used to form the final mountpoint. 128A wildcard 129.Pq Ql * 130can be used for the key. 131It matches every directory that does not match other keys. 132Those directories will not be visible to the user 133until accessed. 134.Pp 135The 136.Ar options 137field, if present, must begin with 138.Li - . 139When mounting the filesystem, options supplied to 140.Nm 141and options specified in the map entry are concatenated together. 142The special option 143.Li fstype 144is used to specify filesystem type. 145It is not passed to the mount program as an option. 146Instead, it is passed as an argument to 147.Cm "mount -t". 148The default 149.Li fstype 150is 151.Ql nfs . 152The special option 153.Li nobrowse 154is used to disable creation of top-level directories for special 155and executable maps. 156.Pp 157The optional 158.Pa mountpoint 159field is used to specify multiple mount points 160for a single key. 161.Pp 162The 163.Ar location 164field specifies the filesystem to be mounted. 165Ampersands 166.Pq Ql & 167in the 168.Ar location 169field are replaced with the value of 170.Ar key . 171This is typically used with wildcards, like: 172.Bd -literal -offset indent 173.Li * 192.168.1.1:/share/& 174.Ed 175.Pp 176The 177.Ar location 178field may contain references to variables, like: 179.Bd -literal -offset indent 180.Li sys 192.168.1.1:/sys/${OSNAME} 181.Ed 182.Pp 183Defined variables are: 184.Pp 185.Bl -tag -width "-OSNAME" -compact 186.It Li ARCH 187Expands to the output of 188.Li "uname -p" . 189.It Li CPU 190Same as ARCH. 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.Pp 377The 378.Nm 379configuration file functionality was ported to 380.Dx 381by 382.An Tomohiro Kusumi Aq Mt kusumi.tomohiro@gmail.com . 383.Sh BUGS 384.Pa /etc/autofs/special_media 385on 386.Dx 387currently can't detect HAMMER filesystem consists of more than one volumes. 388.Pp 389.Pa /etc/autofs/special_media 390on 391.Dx 392currently ignores md(4) devices by default. 393