usr.sbin/autofs/auto_master.5

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