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