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