usr.sbin/autofs/auto_master.5

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