usr.sbin/autofs/auto_master.5

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