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