contrib/amd/amd/amd.8

   1 .\"
   2 .\" Copyright (c) 1997-2006 Erez Zadok
   3 .\" Copyright (c) 1989 Jan-Simon Pendry
   4 .\" Copyright (c) 1989 Imperial College of Science, Technology & Medicine
   5 .\" Copyright (c) 1989 The Regents of the University of California.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This code is derived from software contributed to Berkeley by
   9 .\" Jan-Simon Pendry at Imperial College, London.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\" 3. All advertising materials mentioning features or use of this software
  20 .\"    must display the following acknowledgment:
  21 .\"      This product includes software developed by the University of
  22 .\"      California, Berkeley and its contributors.
  23 .\" 4. Neither the name of the University nor the names of its contributors
  24 .\"    may be used to endorse or promote products derived from this software
  25 .\"    without specific prior written permission.
  26 .\"
  27 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  28 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  29 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  30 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  31 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  32 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  33 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  34 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  35 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  36 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  37 .\" SUCH DAMAGE.
  38 .\"
  39 .\"     %W% (Berkeley) %G%
  40 .\"
  41 .\" $Id: amd.8,v 1.14.2.1 2006/01/02 18:48:23 ezk Exp $
  42 .\" $FreeBSD$
  43 .\"
  44 .Dd January 2, 2006
  45 .Dt AMD 8
  46 .Os
  47 .Sh NAME
  48 .Nm amd
  49 .Nd automatically mount file systems
  50 .Sh SYNOPSIS
  51 .Nm
  52 .Fl H
  53 .Nm
  54 .Op Fl F Ar conf_file
  55 .Nm
  56 .Op Fl nprvHS
  57 .Op Fl a Ar mount_point
  58 .Op Fl c Ar duration
  59 .Op Fl d Ar domain
  60 .Op Fl k Ar kernel-arch
  61 .Op Fl l Ar logfile
  62 .Op Fl o Ar op_sys_ver
  63 .Op Fl t Ar timeout.retransmit
  64 .Op Fl w Ar interval
  65 .Op Fl x Ar log-option
  66 .Op Fl y Ar YP-domain
  67 .Op Fl A Ar arch
  68 .Op Fl C Ar cluster-name
  69 .Op Fl D Ar option
  70 .Op Fl F Ar conf_file
  71 .Op Fl O Ar op_sys_name
  72 .Op Fl T Ar tag
  73 .Oo
  74 .Ar directory mapname
  75 .Op Fl map-options
  76 .Oc
  77 .Ar ...
  78 .Sh DESCRIPTION
  79 The
  80 .Nm
  81 utility
  82 is a daemon that automatically mounts file systems
  83 whenever a file or directory
  84 within that file system is accessed.
  85 File systems are automatically unmounted when they
  86 appear to be quiescent.
  87 .Pp
  88 The
  89 .Nm
  90 utility
  91 operates by attaching itself as an
  92 .Tn NFS
  93 server to each of the specified
  94 .Ar directories .
  95 Lookups within the specified directories
  96 are handled by
  97 .Nm ,
  98 which uses the map defined by
  99 .Ar mapname
 100 to determine how to resolve the lookup.
 101 Generally, this will be a host name, some file system information
 102 and some mount options for the given file system.
 103 .Pp
 104 In the first form depicted above,
 105 .Nm
 106 will print a short help string.
 107 In the second form, if no options are
 108 specified, or if the
 109 .Fl F
 110 is used,
 111 .Nm
 112 will read configuration parameters from the file
 113 .Ar conf_file
 114 which defaults to
 115 .Pa /etc/amd.conf .
 116 The last form is described below.
 117 .Sh OPTIONS
 118 .Bl -tag -width indent
 119 .It Fl a Ar temporary-directory
 120 Specify an alternative location for the real mount points.
 121 The default is
 122 .Pa /.amd_mnt .
 123 .It Fl c Ar duration
 124 Specify a
 125 .Ar duration ,
 126 in seconds, that a looked up name remains
 127 cached when not in use.
 128 The default is 5 minutes.
 129 .It Fl d Ar domain
 130 Specify the local domain name.
 131 If this option is not
 132 given the domain name is determined from the hostname.
 133 .It Fl k Ar kernel-arch
 134 Specifies the kernel architecture.
 135 This is used solely
 136 to set the ${karch} selector.
 137 .It Fl l Ar logfile
 138 Specify a logfile in which to record mount and unmount events.
 139 If
 140 .Ar logfile
 141 is the string
 142 .Dq Li syslog ,
 143 then the log messages will be sent to the system log daemon by
 144 .Xr syslog 3 .
 145 The default syslog facility used is
 146 .Dv LOG_DAEMON .
 147 If you
 148 wish to change it, append its name to the log file name, delimited by a
 149 single colon.
 150 For example, if
 151 .Ar logfile
 152 is the string
 153 .Dq Li syslog:local7
 154 then
 155 .Nm
 156 will log messages via
 157 .Xr syslog 3
 158 using the
 159 .Dv LOG_LOCAL7
 160 facility (if it exists on the system).
 161 .It Fl n
 162 Normalize hostnames.
 163 The name referred to by ${rhost} is normalized relative to the
 164 host database before being used.
 165 The effect is to translate
 166 aliases into
 167 .Dq official
 168 names.
 169 .It Fl o Ar op_sys_ver
 170 Override the compiled-in version number of the operating system.
 171 Useful
 172 when the built in version is not desired for backward compatibility reasons.
 173 For example, if the build in version is
 174 .Dq Li 2.5.1 ,
 175 you can override it to
 176 .Dq Li 5.5.1 ,
 177 and use older maps that were written with the latter in mind.
 178 .It Fl p
 179 Print PID.
 180 Outputs the process ID of
 181 .Nm
 182 to standard output where it can be saved into a file.
 183 .It Fl r
 184 Restart existing mounts.
 185 The
 186 .Nm
 187 utility
 188 will scan the mount file table to determine which file systems
 189 are currently mounted.
 190 Whenever one of these would have
 191 been auto-mounted,
 192 .Nm
 193 .Em inherits
 194 it.
 195 .It Fl t Ar timeout.retransmit
 196 Specify the NFS
 197 .Ar timeout
 198 interval,
 199 in tenths of a second, between
 200 .Tn NFS/RPC
 201 retries (for UDP only).
 202 The default
 203 is 0.8 seconds.
 204 The second value alters the retransmit counter, which
 205 defaults to 11 retransmissions.
 206 Both of these values are used by the kernel
 207 to communicate with amd.
 208 Useful defaults are supplied if either or both
 209 values are missing.
 210 .Pp
 211 The
 212 .Xr amd 8
 213 utility
 214 relies on the kernel RPC retransmit mechanism to trigger mount retries.
 215 The values of these parameters change the overall retry interval.
 216 Too long
 217 an interval gives poor interactive response; too short an interval causes
 218 excessive retries.
 219 .It Fl v
 220 Version.
 221 Displays version and configuration information on standard error.
 222 .It Fl w Ar interval
 223 Specify an
 224 .Ar interval ,
 225 in seconds, between attempts to dismount
 226 file systems that have exceeded their cached times.
 227 The default is 2 minutes.
 228 .It Fl x Ar options
 229 Specify run-time logging options.
 230 The options are a comma separated
 231 list chosen from:
 232 .Li fatal , error , user , warn , info , map , stats , all .
 233 .It Fl y Ar domain
 234 Specify an alternative
 235 .Tn NIS
 236 domain from which to fetch the
 237 .Tn NIS
 238 maps.
 239 The default is the system domain name.
 240 This option is ignored if
 241 .Tn NIS
 242 support is not available.
 243 .It Fl A Ar arch
 244 Specifies the OS architecture.
 245 This is used solely to set the ${arch}
 246 selector.
 247 .It Fl C Ar cluster-name
 248 Specify an alternative HP-UX cluster name to use.
 249 .It Fl D Ar option
 250 Select from a variety of debug options.
 251 Prefixing an
 252 option with the string
 253 .Dq Li no
 254 reverses the effect of that option.
 255 Options are cumulative.
 256 The most useful option is
 257 .Dq Li all .
 258 .Pp
 259 Since
 260 .Fl D
 261 is only used for debugging other options are not documented here:
 262 the current supported set of options is listed by the
 263 .Fl v
 264 option
 265 and a fuller description is available in the program source.
 266 .It Fl F Ar conf_file
 267 Specify an
 268 .Nm
 269 configuration file to use.
 270 See
 271 .Xr amd.conf 5
 272 for description of this file's format.
 273 This configuration file is used to
 274 specify any options in lieu of typing many of them on the command line.
 275 The
 276 .Xr amd.conf 5
 277 file includes directives for every command line option amd has, and many
 278 more that are only available via the configuration file facility.
 279 The
 280 configuration file specified by this option is processed after all other
 281 options had been processed, regardless of the actual location of this option
 282 on the command line.
 283 .It Fl H
 284 Print help and usage string.
 285 .It Fl O Ar op_sys_name
 286 Override the compiled-in name of the operating system.
 287 Useful when the
 288 built in name is not desired for backward compatibility reasons.
 289 For
 290 example, if the build in name is
 291 .Dq Li sunos5 ,
 292 you can override it to
 293 .Dq Li sos5
 294 and use older maps which were written with the latter in mind.
 295 .It Fl S
 296 Do not lock the running executable pages of
 297 .Nm
 298 into memory.
 299 To improve
 300 .Nm Ns 's
 301 performance, systems that support the
 302 .Xr plock 3
 303 call, could lock the
 304 .Nm
 305 process into memory.
 306 This way there is less chance
 307 the operating system will schedule, page out, and swap the
 308 .Nm
 309 process as
 310 needed.
 311 This tends to improve
 312 .Nm Ns 's
 313 performance, at the cost of reserving the
 314 memory used by the
 315 .Nm
 316 process (making it unavailable for other processes).
 317 If this behavior is not desired, use the
 318 .Fl S
 319 option.
 320 .It Fl T Ar tag
 321 Specify a tag to use with
 322 .Xr amd.conf 5 .
 323 All map entries tagged with
 324 .Ar tag
 325 will be processed.
 326 Map entries that are not tagged are always processed.
 327 Map entries that are tagged with a tag other than
 328 .Ar tag
 329 will not be processed.
 330 .El
 331 .Sh FILES
 332 .Bl -tag -width ".Pa /etc/amd.conf"
 333 .It Pa /.amd_mnt
 334 directory under which file systems are dynamically mounted
 335 .It Pa /etc/amd.conf
 336 default configuration file
 337 .El
 338 .Sh CAVEATS
 339 Some care may be required when creating a mount map.
 340 .Pp
 341 Symbolic links on an
 342 .Tn NFS
 343 file system can be incredibly inefficient.
 344 In most implementations of
 345 .Tn NFS ,
 346 their interpolations are not cached
 347 by the kernel and each time a symbolic link is encountered during a
 348 .Em lookuppn
 349 translation it costs an
 350 .Tn RPC
 351 call to the
 352 .Tn NFS
 353 server.
 354 It would appear that a large improvement in real-time
 355 performance could be gained by adding a cache somewhere.
 356 Replacing symlinks with a suitable incarnation of the auto-mounter
 357 results in a large real-time speedup, but also causes a large
 358 number of process context switches.
 359 .Pp
 360 A weird imagination is most useful to gain full advantage of all
 361 the features.
 362 .Sh SEE ALSO
 363 .Xr domainname 1 ,
 364 .Xr hostname 1 ,
 365 .Xr syslog 3 ,
 366 .Xr amd.conf 5 ,
 367 .Xr mtab 5 ,
 368 .Xr amq 8 ,
 369 .Xr mount 8 ,
 370 .Xr umount 8
 371 .Pp
 372 .Dq am-utils
 373 .Xr info 1
 374 entry.
 375 .Rs
 376 .%A Erez Zadok
 377 .%B "Linux NFS and Automounter Administration"
 378 .%O ISBN 0-7821-2739-8
 379 .%I Sybex
 380 .%D 2001
 381 .Re
 382 .Pp
 383 .Pa http://www.am-utils.org/
 384 .Rs
 385 .%T Amd \- The 4.4 BSD Automounter
 386 .Re
 387 .Sh HISTORY
 388 The
 389 .Nm
 390 utility first appeared in
 391 .Bx 4.4 .
 392 .Sh AUTHORS
 393 .An Jan-Simon Pendry Aq jsp@doc.ic.ac.uk ,
 394 Department of Computing, Imperial College, London, UK.
 395 .Pp
 396 .An Erez Zadok Aq ezk@cs.sunysb.edu ,
 397 Computer Science Department, Stony Brook
 398 University, Stony Brook, New York, USA.
 399 .Pp
 400 Other authors and contributors to am-utils are listed in the
 401 .Pa AUTHORS
 402 file distributed with am-utils.