1.\" Copyright (c) 2014 The FreeBSD Foundation 2.\" All rights reserved. 3.\" 4.\" This software was developed by Edward Tomasz Napierala under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd November 17, 2014 31.Dt AUTO_MASTER 5 32.Os 33.Sh NAME 34.Nm auto_master 35.Nd auto_master and map file format 36.Sh DESCRIPTION 37The 38.Nm 39configuration file is used by the 40.Xr automount 8 41command. 42Map files are read by the 43.Xr automountd 8 44daemon. 45.Sh AUTO_MASTER SYNTAX 46The 47.Nm 48file consists of lines with two or three entries separated by whitespace 49and terminated by newline character: 50.Bd -literal -offset indent 51.Pa mountpoint Pa map_name Op Ar -options 52.Ed 53.Pp 54.Pa mountpoint 55is either a fully specified path, or 56.Li /- . 57When 58.Pa mountpoint 59is a full path, 60.Pa map_name 61must reference an indirect map. 62Otherwise, 63.Pa map_name 64must reference a direct map. 65See 66.Sx "MAP SYNTAX" below. 67.Pp 68.Pa map_name 69specifies map to use. 70If 71.Pa map_name 72begins with 73.Li - , 74it specifies a special map. 75See 76.Sx "MAP SYNTAX" 77below. 78If 79.Pa map_name 80is not a fully specified path 81.Pq it does not start with Li / , 82.Xr automountd 8 83will search for that name in 84.Li /etc . 85Otherwise it will use the path as given. 86If the file indicated by 87.Pa map_name 88is executable, 89.Xr automountd 8 90will assume it is an executable map. 91See 92.Sx "MAP SYNTAX" 93below. 94Otherwise, the file is opened and the contents parsed. 95.Pp 96.Pa -options 97is an optional field that starts with 98.Li - 99and can contain generic filesystem mount options. 100.Pp 101The following example specifies that the /etc/auto_example indirect map 102will be mounted on /example. 103.Bd -literal -offset indent 104/example auto_example 105.Ed 106.Sh MAP SYNTAX 107Map files consist of lines with a number of entries separated by whitespace 108and terminated by newline character: 109.Bd -literal -offset indent 110.Pa key Oo Ar -options Oc Oo Ar mountpoint Oo -options Oc Oc Ar location Op ... 111.Ed 112.Pp 113In most cases, it can be simplified to: 114.Bd -literal -offset indent 115.Pa key Oo Ar -options Oc Ar location 116.Ed 117.Pp 118.Pa key 119is the path component used by 120.Xr automountd 8 121to find the right map entry to use. 122It is also used to form the final mountpoint. 123.Pp 124The 125.Ar options 126field, if present, must begin with 127.Li - . 128When mounting the filesystem, options supplied to 129.Nm 130and options specified in the map entry are concatenated together. 131The special option 132.Li fstype 133is used to specify filesystem type. 134It is not passed to the mount program as an option. 135Instead, it is passed as argument to 136.Cm "mount -t". 137The special option 138.Li nobrowse 139is used to disable creation of top-level directories for special 140and executable maps. 141.Pp 142The optional 143.Pa mountpoint 144field is used to specify multiple mount points 145for a single key. 146.Pp 147The 148.Ar location 149field specifies the filesystem to be mounted. 150To pass location that begins with 151.Li / , 152prefix it with colon. 153For example, 154.Li :/dev/cd0 . 155.Pp 156This example, when used with the 157.Nm 158example above, specifies that the NFS share 159.Li 192.168.1.1:/share/example/x 160will be mounted on 161.Pa /example/x/ 162when any process attempts to access that mountpoint, with 163.Li intr 164and 165.Li nfsv4 166mount options: 167.Bd -literal -offset indent 168.Li x -intr,nfsv4 192.168.1.1:/share/example/x 169.Ed 170.Pp 171Automatically mount the CD drive on access: 172.Bd -literal -offset indent 173.Li cd -fstype=cd9660 :/dev/cd0 174.Ed 175.Sh SPECIAL MAPS 176Special maps have names beginning with 177.Li - . 178Supported special maps are: 179.Pp 180.Bl -tag -width "-hosts" -compact 181.It Li -hosts 182This map queries the remote NFS server and maps exported volumes. 183It is traditionally mounted on 184.Pa /net . 185It enables access to files on a remote NFS server by accessing 186.Pa /net/nfs-server-ip/share-name/ 187directory, without the need for any further configuration. 188.It Li -null 189This map prevents the 190.Xr automountd 8 191from mounting anything on the mountpoint. 192.El 193.Sh EXECUTABLE MAPS 194If the map file specified in 195.Nm 196has execute bit set, the 197.Xr automountd 8 198will execute it and parse the standard output instead of parsing 199the file contents. 200.Sh INDIRECT VERSUS DIRECT MAPS 201Indirect maps are referred to in 202.Nm 203by entries with a fully qualified path as a mount point, and must contain only 204relative paths as keys. 205Direct maps are referred to in 206.Nm 207by entries with 208.Li /- 209as the mountpoint, and must contain only fully qualified paths as keys. 210For indirect maps, the final mount point is determined by concatenating the 211.Nm 212mountpoint with the map entry key and optional map entry mountpoint. 213For direct maps, the final mount point is determined by concatenating 214the map entry key with the optional map entry mountpoint. 215.Pp 216The example above could be rewritten using direct map, by placing this in 217.Nm : 218.Bd -literal -offset indent 219.Li /- auto_example 220.Ed 221.Pp 222and this in 223.Li /etc/auto_example 224map file: 225.Bd -literal -offset indent 226.Li /example/x -intr,nfsv4 192.168.1.1:/share/example/x 227.Li /example/cd -fstype=cd9660 :/dev/cd0 228.Ed 229.Sh DIRECTORY SERVICES 230Both 231.Nm 232and maps may contain entries consisting of a plus sign and map name: 233.Bd -literal -offset indent 234.Li +auto_master 235.Ed 236.Pp 237Those entries cause 238.Xr automountd 8 239daemon to retrieve the named map from directory services (like LDAP) 240and include it where the entry was. 241.Pp 242If the file containing the map referenced in 243.Nm 244is not found, the map will be retrieved from directory services instead. 245.Pp 246To retrieve entries from directory services, 247.Xr automountd 8 248daemon runs 249.Pa /etc/autofs/include , 250which is usually a shell script, with map name as the only command line 251parameter. 252The script should output entries formatted according to 253.Nm 254or automounter map syntax to standard output. 255An example script to use LDAP is included in 256.Pa /etc/autofs/include_ldap . 257It can be symlinked to 258.Pa /etc/autofs/include . 259.Sh FILES 260.Bl -tag -width ".Pa /etc/auto_master" -compact 261.It Pa /etc/auto_master 262The default location of the 263.Pa auto_master 264file. 265.El 266.Sh SEE ALSO 267.Xr autofs 5 , 268.Xr automount 8 , 269.Xr automountd 8 , 270.Xr autounmountd 8 271.Sh AUTHORS 272The 273.Nm 274configuration file functionality was developed by 275.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 276under sponsorship from the FreeBSD Foundation. 277