| blob | 89100f75faf502109ad575a818da882ffe03a9ff |
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 March 13, 2015
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 HOST
191 Expands to the output of
192 .Li "uname -n" .
193 .It Li OSNAME
194 Expands to the output of
195 .Li "uname -s" .
196 .It Li OSREL
197 Expands to the output of
198 .Li "uname -r" .
199 .It Li OSVERS
200 Expands to the output of
201 .Li "uname -v" .
202 .El
203 .Pp
204 Additional variables can be defined with the
205 .Fl D
206 option of
207 .Xr automount 8
208 and
209 .Xr automountd 8 .
210 .Pp
211 To pass a location that begins with
212 .Li / ,
213 prefix it with a colon.
214 For example,
215 .Li :/dev/cd0 .
216 .Pp
217 This example, when put into
218 .Pa /etc/auto_example ,
219 and with
220 .Nm
221 referring to the map as described above, specifies that the NFS share
222 .Li 192.168.1.1:/share/example/x
223 will be mounted on
224 .Pa /example/x/
225 when any process attempts to access that mountpoint, with
226 .Li intr
227 and
228 .Li nfsv4
229 mount options, described in
230 .Xr mount_nfs 8 :
231 .Bd -literal -offset indent
232 .Li x -intr,nfsv4 192.168.1.1:/share/example/x
233 .Ed
234 .Pp
235 Automatically mount an SMB share on access, as a guest user,
236 without prompting for a password:
237 .Bd -literal -offset indent
238 .Li share -fstype=smbfs,-N ://@server/share
239 .Ed
240 .Pp
241 Automatically mount the CD drive on access:
242 .Bd -literal -offset indent
243 .Li cd -fstype=cd9660 :/dev/cd0
244 .Ed
245 .Sh SPECIAL MAPS
246 Special maps have names beginning with
247 .Li - .
248 Supported special maps are:
249 .Pp
250 .Bl -tag -width "-hosts" -compact
251 .It Li -hosts
252 Query the remote NFS server and map exported shares.
253 This map is traditionally mounted on
254 .Pa /net .
255 Access to files on a remote NFS server is provided through the
256 .Pf /net/ Ar nfs-server-ip Ns / Ns Ar share-name Ns/
257 directory without any additional configuration.
258 Directories for individual NFS servers are not present until the first access,
259 when they are automatically created.
260 .It Li -media
261 Query devices that are not yet mounted, but contain valid filesystems.
262 Generally used to access files on removable media.
263 .It Li -noauto
264 Mount filesystems configured in
265 .Xr fstab 5
266 as "noauto".
267 This needs to be set up as a direct map.
268 .It Li -null
269 Prevent
270 .Xr automountd 8
271 from mounting anything on the mountpoint.
272 .El
273 .Pp
274 It is possible to add custom special maps by adding them, as executable
275 maps named
276 .Pa special_foo ,
277 to the
278 .Pa /etc/autofs/
279 directory.
280 .Sh EXECUTABLE MAPS
281 If the map file specified in
282 .Nm
283 has the execute bit set,
284 .Xr automountd 8
285 will execute it and parse the standard output instead of parsing
286 the file contents.
287 When called without command line arguments, the executable is
288 expected to output a list of available map keys separated by
289 newline characters.
290 Otherwise, the executable will be called with a key name as
291 a command line argument.
292 Output from the executable is expected to be the entry for that key,
293 not including the key itself.
294 .Sh INDIRECT VERSUS DIRECT MAPS
295 Indirect maps are referred to in
296 .Nm
297 by entries with a fully qualified path as a mount point, and must contain only
298 relative paths as keys.
299 Direct maps are referred to in
300 .Nm
301 by entries with
302 .Li /-
303 as the mountpoint, and must contain only fully qualified paths as keys.
304 For indirect maps, the final mount point is determined by concatenating the
305 .Nm
306 mountpoint with the map entry key and optional map entry mountpoint.
307 For direct maps, the final mount point is determined by concatenating
308 the map entry key with the optional map entry mountpoint.
309 .Pp
310 The example above could be rewritten using direct map, by placing this in
311 .Nm :
312 .Bd -literal -offset indent
313 .Li /- auto_example
314 .Ed
315 .Pp
316 and this in
317 .Li /etc/auto_example
318 map file:
319 .Bd -literal -offset indent
320 .Li /example/x -intr,nfsv4 192.168.1.1:/share/example/x
321 .Li /example/share -fstype=smbfs,-N ://@server/share
322 .Li /example/cd -fstype=cd9660 :/dev/cd0
323 .Ed
324 .Sh DIRECTORY SERVICES
325 Both
326 .Nm
327 and maps may contain entries consisting of a plus sign and map name:
328 .Bd -literal -offset indent
329 .Li +auto_master
330 .Ed
331 .Pp
332 Those entries cause
333 .Xr automountd 8
334 daemon to retrieve the named map from directory services (like LDAP)
335 and include it where the entry was.
336 .Pp
337 If the file containing the map referenced in
338 .Nm
339 is not found, the map will be retrieved from directory services instead.
340 .Pp
341 To retrieve entries from directory services,
342 .Xr automountd 8
343 daemon runs
344 .Pa /etc/autofs/include ,
345 which is usually a shell script, with map name as the only command line
346 parameter.
347 The script should output entries formatted according to
348 .Nm
349 or automounter map syntax to standard output.
350 An example script to use LDAP is included in
351 .Pa /etc/autofs/include_ldap .
352 It can be symlinked to
353 .Pa /etc/autofs/include .
354 .Sh FILES
355 .Bl -tag -width ".Pa /etc/auto_master" -compact
356 .It Pa /etc/auto_master
357 The default location of the
358 .Pa auto_master
359 file.
360 .It Pa /etc/autofs/
361 Directory containing shell scripts to implement special maps and directory
362 services.
363 .El
364 .Sh SEE ALSO
365 .Xr autofs 5 ,
366 .Xr automount 8 ,
367 .Xr automountd 8 ,
368 .Xr autounmountd 8
369 .Sh AUTHORS
370 The
371 .Nm
372 configuration file functionality was developed by
373 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
374 under sponsorship from the FreeBSD Foundation.