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