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