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