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 August 23, 2014
  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
  38 .Nm
  39 configuration file is used by the
  40 .Xr automount 8
  41 command.
  42 Map files are read by the
  43 .Xr automountd 8
  44 daemon.
  45 .Sh AUTO_MASTER SYNTAX
  46 The
  47 .Nm
  48 file consists of lines with two or three entries separated by whitespace
  49 and terminated by newline character:
  50 .Bd -literal -offset indent
  51 .Pa mountpoint Pa map_name Op Ar -options
  52 .Ed
  53 .Pp
  54 .Pa mountpoint
  55 is either a fully specified path, or
  56 .Li /- .
  57 When
  58 .Pa mountpoint
  59 is a full path,
  60 .Pa map_name
  61 must reference an indirect map.
  62 Otherwise,
  63 .Pa map_name
  64 must reference a direct map.
  65 See
  66 .Sx "MAP SYNTAX" below.
  67 .Pp
  68 .Pa map_name
  69 specifies map to use.
  70 If
  71 .Pa map_name
  72 begins with
  73 .Li - ,
  74 it specifies a special map.
  75 See
  76 .Sx "MAP SYNTAX"
  77 below.
  78 If
  79 .Pa map_name
  80 is not a fully specified path
  81 .Pq it does not start with Li / ,
  82 .Xr automountd 8
  83 will search for that name in
  84 .Li /etc .
  85 Otherwise it will use the path as given.
  86 If the file indicated by
  87 .Pa map_name
  88 is executable,
  89 .Xr automountd 8
  90 will assume it is an executable map.
  91 See
  92 .Sx "MAP SYNTAX"
  93 below.
  94 Otherwise, the file is opened and the contents parsed.
  95 .Pp
  96 .Pa -options
  97 is an optional field that starts with
  98 .Li -
  99 and can contain generic filesystem mount options.
 100 .Pp
 101 The following example specifies that the /etc/auto_example indirect map
 102 will be mounted on /example.
 103 .Bd -literal -offset indent
 104 /example auto_example
 105 .Ed
 106 .Sh MAP SYNTAX
 107 Map files consist of lines with a number of entries separated by whitespace
 108 and terminated by newline character:
 109 .Bd -literal -offset indent
 110 .Pa key Oo Ar -options Oc Oo Ar mountpoint Oo -options Oc Oc Ar location Op ...
 111 .Ed
 112 .Pp
 113 In most cases, it can be simplified to:
 114 .Bd -literal -offset indent
 115 .Pa key Oo Ar -options Oc Ar location
 116 .Ed
 117 .Pp
 118 .Pa key
 119 is the path component used by
 120 .Xr automountd 8
 121 to find the right map entry to use.
 122 It is also used to form the final mountpoint.
 123 .Pp
 124 The
 125 .Ar options
 126 field, if present, must begin with
 127 .Li - .
 128 When mounting the filesystem, options supplied to
 129 .Nm
 130 and options specified in the map entry are concatenated together.
 131 The special option
 132 .Li fstype
 133 is used to specify filesystem type.
 134 It is not passed to the mount program as an option.
 135 Instead, it is passed as argument to
 136 .Cm "mount -t".
 137 The special option
 138 .Li nobrowse
 139 is used to disable creation of top-level directories for special
 140 and executable maps.
 141 .Pp
 142 The optional
 143 .Pa mountpoint
 144 field is used to specify multiple mount points
 145 for a single key.
 146 .Pp
 147 The
 148 .Ar location
 149 field specifies the filesystem to be mounted.
 150 To pass location that begins with
 151 .Li / ,
 152 prefix it with colon.
 153 For example,
 154 .Li :/dev/cd0 .
 155 .Pp
 156 This example, when used with the
 157 .Nm
 158 example above, specifies that the NFS share
 159 .Li 192.168.1.1:/share/example/x
 160 will be mounted on
 161 .Pa /example/x/
 162 when any process attempts to access that mountpoint, with
 163 .Li intr
 164 and
 165 .Li nfsv4
 166 mount options:
 167 .Bd -literal -offset indent
 168 .Li x -intr,nfsv4 192.168.1.1:/share/example/x
 169 .Ed
 170 .Pp
 171 Automatically mount the CD drive on access:
 172 .Bd -literal -offset indent
 173 .Li cd -intr,fstype=cd9660 :/dev/cd0
 174 .Ed
 175 .Sh SPECIAL MAPS
 176 Special maps have names beginning with
 177 .Li - .
 178 Supported special maps are:
 179 .Pp
 180 .Bl -tag -width "-hosts" -compact
 181 .It Li -hosts
 182 This map queries the remote NFS server and maps exported volumes.
 183 It is traditionally mounted on
 184 .Pa /net .
 185 It enables access to files on a remote NFS server by accessing
 186 .Pa /net/nfs-server-ip/share-name/
 187 directory, without the need for any further configuration.
 188 .It Li -null
 189 This map prevents the
 190 .Xr automountd 8
 191 from mounting anything on the mountpoint.
 192 .El
 193 .Sh EXECUTABLE MAPS
 194 If the map file specified in
 195 .Nm
 196 has execute bit set, the
 197 .Xr automountd 8
 198 will execute it and parse the standard output instead of parsing
 199 the file contents.
 200 .Sh INDIRECT VERSUS DIRECT MAPS
 201 Indirect maps are referred to in
 202 .Nm
 203 by entries with a fully qualified path as a mount point, and must contain only
 204 relative paths as keys.
 205 Direct maps are referred to in
 206 .Nm
 207 by entries with
 208 .Li /-
 209 as the mountpoint, and must contain only fully qualified paths as keys.
 210 For indirect maps, the final mount point is determined by concatenating the
 211 .Nm
 212 mountpoint with the map entry key and optional map entry mountpoint.
 213 For direct maps, the final mount point is determined by concatenating
 214 the map entry key with the optional map entry mountpoint.
 215 .Pp
 216 The example above could be rewritten using direct map, by placing this in
 217 .Nm :
 218 .Bd -literal -offset indent
 219 .Li /- auto_example
 220 .Ed
 221 .Pp
 222 and this in
 223 .Li /etc/auto_example
 224 map file:
 225 .Bd -literal -offset indent
 226 .Li /example/x -intr,nfsv4 192.168.1.1:/share/example/x
 227 .Li /example/cd -intr,fstype=cd9660 :/dev/cd0
 228 .Ed
 229 .Sh DIRECTORY SERVICES
 230 Both
 231 .Nm
 232 and maps may contain entries consisting of a plus sign and map name:
 233 .Bd -literal -offset indent
 234 .Li +auto_master
 235 .Ed
 236 .Pp
 237 Those entries cause
 238 .Xr automountd 8
 239 daemon to retrieve the named map from directory services (like LDAP)
 240 and include it where the entry was.
 241 .Pp
 242 If the file containing the map referenced in
 243 .Nm
 244 is not found, the map will be retrieved from directory services instead.
 245 .Pp
 246 To retrieve entries from directory services,
 247 .Xr automountd 8
 248 daemon runs
 249 .Pa /etc/autofs/include ,
 250 which is usually a shell script, with map name as the only command line
 251 parameter.
 252 The script should output entries formatted according to
 253 .Nm
 254 or automounter map syntax to standard output.
 255 An example script to use LDAP is included in
 256 .Pa /etc/autofs/include_ldap .
 257 It can be symlinked to
 258 .Pa /etc/autofs/include .
 259 .Sh FILES
 260 .Bl -tag -width ".Pa /etc/auto_master" -compact
 261 .It Pa /etc/auto_master
 262 The default location of the
 263 .Pa auto_master
 264 file.
 265 .El
 266 .Sh SEE ALSO
 267 .Xr autofs 5 ,
 268 .Xr automount 8 ,
 269 .Xr automountd 8 ,
 270 .Xr autounmountd 8
 271 .Sh AUTHORS
 272 The
 273 .Nm
 274 configuration file functionality was developed by
 275 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 276 under sponsorship from the FreeBSD Foundation.