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