1.\" $NetBSD: auto_master.5,v 1.6 2018/01/25 19:15:10 uwe 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 25, 2017 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 HOST 199Expands to the output of 200.Li "uname -n" . 201.It Dv OSNAME 202Expands to the output of 203.Li "uname -s" . 204.It Dv OSREL 205Expands to the output of 206.Li "uname -r" . 207.It Dv OSVERS 208Expands to the output of 209.Li "uname -v" . 210.El 211.Pp 212Additional variables can be defined with the 213.Fl D 214option of 215.Xr automount 8 216and 217.Xr automountd 8 . 218.Pp 219To pass a location that begins with 220.Pa / , 221prefix it with a colon. 222For example, 223.Li :/dev/cd0 . 224.Pp 225This example, when put into 226.Pa /etc/auto_example , 227and with 228.Nm 229referring to the map as described above, specifies that the NFS share 230.Li 192.168.1.1:/share/example/x 231will be mounted on 232.Pa /example/x/ 233when any process attempts to access that mountpoint, with 234.Ic intr 235and 236.Ic nfsv4 237mount options, described in 238.Xr mount_nfs 8 : 239.Bd -literal -offset indent 240x -intr,nfsv4 192.168.1.1:/share/example/x 241.Ed 242.Pp 243Automatically mount an SMB share on access, as a guest user, 244without prompting for a password: 245.Bd -literal -offset indent 246share -fstype=smbfs,-N ://@server/share 247.Ed 248.Pp 249Automatically mount the CD drive on access: 250.Bd -literal -offset indent 251cd -fstype=cd9660 :/dev/cd0 252.Ed 253.Sh SPECIAL MAPS 254Special maps have names beginning with 255.Li - . 256Supported special maps are: 257.Pp 258.Bl -tag -width ".Ic -noauto" -compact 259.It Ic -hosts 260Query the remote NFS server and map exported shares. 261This map is traditionally mounted on 262.Pa /net . 263Access to files on a remote NFS server is provided through the 264.Pa /net/ Ns Ar nfs-server-ip Ns / Ns Ar share-name Ns / 265directory without any additional configuration. 266Directories for individual NFS servers are not present until the first access, 267when they are automatically created. 268.It Ic -media 269Query devices that are not yet mounted, but contain valid file systems. 270Generally used to access files on removable media. 271.It Ic -noauto 272Mount file systems configured in 273.Xr fstab 5 274as "noauto". 275This needs to be set up as a direct map. 276.It Ic -null 277Prevent 278.Xr automountd 8 279from mounting anything on the mountpoint. 280.El 281.Pp 282It is possible to add custom special maps by adding them, as executable 283maps named 284.Pa special_foo , 285to the 286.Pa /etc/autofs/ 287directory. 288.Sh EXECUTABLE MAPS 289If the map file specified in 290.Nm 291has the execute bit set, 292.Xr automountd 8 293will execute it and parse the standard output instead of parsing 294the file contents. 295When called without command line arguments, the executable is 296expected to output a list of available map keys separated by 297newline characters. 298Otherwise, the executable will be called with a key name as 299a command line argument. 300Output from the executable is expected to be the entry for that key, 301not including the key itself. 302.Sh INDIRECT VERSUS DIRECT MAPS 303Indirect maps are referred to in 304.Nm 305by entries with a fully qualified path as a mount point, and must contain only 306relative paths as keys. 307Direct maps are referred to in 308.Nm 309by entries with 310.Li /- 311as the mountpoint, and must contain only fully qualified paths as keys. 312For indirect maps, the final mount point is determined by concatenating the 313.Nm 314mountpoint with the map entry key and optional map entry mountpoint. 315For direct maps, the final mount point is determined by concatenating 316the map entry key with the optional map entry mountpoint. 317.Pp 318The example above could be rewritten using direct map, by placing this in 319.Nm : 320.Bd -literal -offset indent 321/- auto_example 322.Ed 323.Pp 324and this in the 325.Pa /etc/auto_example 326map file: 327.Bd -literal -offset indent 328/example/x -intr,nfsv4 192.168.1.1:/share/example/x 329/example/share -fstype=smbfs,-N ://@server/share 330/example/cd -fstype=cd9660 :/dev/cd0 331.Ed 332.Sh DIRECTORY SERVICES 333Both 334.Nm 335and maps may contain entries consisting of a plus sign and map name: 336.Bd -literal -offset indent 337+auto_master 338.Ed 339.Pp 340Those entries cause 341.Xr automountd 8 342daemon to retrieve the named map from directory services (like LDAP) 343and include it where the entry was. 344.Pp 345If the file containing the map referenced in 346.Nm 347is not found, the map will be retrieved from directory services instead. 348.Pp 349To retrieve entries from directory services, 350.Xr automountd 8 351daemon runs 352.Pa /etc/autofs/include , 353which is usually a shell script, with map name as the only command line 354parameter. 355The script should output entries formatted according to 356.Nm 357or automounter map syntax to standard output. 358An example script to use LDAP is included in 359.Pa /etc/autofs/include_ldap . 360It can be symlinked to 361.Pa /etc/autofs/include . 362.Sh FILES 363.Bl -tag -width ".Pa /etc/auto_master" -compact 364.It Pa /etc/auto_master 365The default location of the 366.Nm 367file. 368.It Pa /etc/autofs/ 369Directory containing shell scripts to implement special maps and directory 370services. 371.El 372.Sh SEE ALSO 373.Xr autofs 5 , 374.Xr automount 8 , 375.Xr automountd 8 , 376.Xr autounmountd 8 377.Sh AUTHORS 378.An -nosplit 379The 380.Nm 381configuration file functionality was developed by 382.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 383under sponsorship from the 384.Fx 385Foundation. 386.Pp 387The 388.Nm 389configuration file functionality was ported to 390.Dx 391and 392.Nx 393by 394.An Tomohiro Kusumi Aq Mt kusumi.tomohiro@gmail.com . 395.Sh BUGS 396The 397.Li -media 398special map is currently unsupported on 399.Nx . 400