contrib/amd/amd/amd.8

   1 .\"
   2 .\" Copyright (c) 1997-1999 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.3 1999/09/30 21:01:29 ezk Exp $
  42 .\" $FreeBSD: src/contrib/amd/amd/amd.8,v 1.6.2.9 2001/12/14 15:59:49 ru Exp $
  43 .\" $DragonFly: src/contrib/amd/amd/amd.8,v 1.2 2003/06/17 04:23:56 dillon Exp $
  44 .\"
  45 .Dd April 19, 1994
  46 .Dt AMD 8
  47 .Os
  48 .Sh NAME
  49 .Nm amd
  50 .Nd automatically mount file systems
  51 .Sh SYNOPSIS
  52 .Nm amd
  53 .Fl H
  54 .Nm amd
  55 .Op Fl F Ar conf_file
  56 .Nm amd
  57 .Op Fl nprvHS
  58 .Op Fl a Ar mount_point
  59 .Op Fl c Ar duration
  60 .Op Fl d Ar domain
  61 .Bk -words
  62 .Op Fl k Ar kernel-arch
  63 .Ek
  64 .Op Fl l Ar logfile
  65 .Op Fl o Ar op_sys_ver
  66 .Op Fl t Ar timeout.retransmit
  67 .Bk -words
  68 .Op Fl w Ar interval
  69 .Ek
  70 .Op Fl x Ar log-option
  71 .Op Fl y Ar YP-domain
  72 .Bk -words
  73 .Op Fl C Ar cluster-name
  74 .Ek
  75 .Op Fl D Ar option
  76 .Op Fl F Ar conf_file
  77 .Op Fl O Ar op_sys_name
  78 .Op Fl T Ar tag
  79 .Oo
  80 .Ar directory mapname
  81 .Op Fl map-options
  82 .Oc
  83 .Ar ...
  84 .Sh DESCRIPTION
  85 .Nm Amd
  86 is a daemon that automatically mounts filesystems whenever a file or directory
  87 within that filesystem is accessed.  Filesystems are automatically unmounted
  88 when they appear to be quiescent.
  89 .Pp
  90 .Nm Amd
  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 amd ,
  98 which uses the map defined by
  99 .Ar mapname
 100 to determine how to resolve the lookup.  Generally, this will be a host name,
 101 some filesystem information and some mount options for the given filesystem.
 102 .Pp
 103 In the first form depicted above,
 104 .Nm amd
 105 will print a short help string.  In the second form, if no options are
 106 specified, or if the
 107 .Fl F
 108 is used,
 109 .Nm amd
 110 will read configuration parameters from the file
 111 .Ar conf_file
 112 which defaults to
 113 .Pa /etc/amd.conf .
 114 The last form is described below.
 115 .Sh OPTIONS
 116 .Bl -tag -width Ds
 117 .It Fl a Ar temporary-directory
 118 Specify an alternative location for the real mount points.
 119 The default is
 120 .Pa /.amd_mnt .
 121 .It Fl c Ar duration
 122 Specify a
 123 .Ar duration ,
 124 in seconds, that a looked up name remains
 125 cached when not in use.  The default is 5 minutes.
 126 .It Fl d Ar domain
 127 Specify the local domain name.  If this option is not
 128 given the domain name is determined from the hostname.
 129 .It Fl k Ar kernel-arch
 130 Specifies the kernel architecture.  This is used solely
 131 to set the ${karch} selector.
 132 .It Fl l Ar logfile
 133 Specify a logfile in which to record mount and unmount events.
 134 If
 135 .Ar logfile
 136 is the string
 137 .Em syslog ,
 138 the log messages will be sent to the system log daemon by
 139 .Xr syslog 3 .
 140 The default syslog facility used is LOG_DAEMON.
 141 If you wish to change it, append its name to the log file name,
 142 delimited by a single colon.
 143 For example, if
 144 .Ar logfile
 145 is the string
 146 .Dq Li syslog:local7
 147 then
 148 .Nm amd
 149 will log messages via
 150 .Xr syslog 3
 151 using the LOG_LOCAL7 facility (if it exists on the system).
 152 .It Fl n
 153 Normalize hostnames.
 154 The name referred to by ${rhost} is normalized relative to the
 155 host database before being used.  The effect is to translate
 156 aliases into ``official'' names.
 157 .It Fl o Ar op_sys_ver
 158 Override the compiled-in version number of the operating system.
 159 Useful when the built in version is not desired for backward
 160 compatibility reasons.
 161 For example, if the build in version is
 162 .Dq 2.5.1 ,
 163 you can override it to
 164 .Dq 5.5.1 ,
 165 and use older maps that were written with the latter in mind.
 166 .It Fl p
 167 Print
 168 .Em PID .
 169 Outputs the process-id of
 170 .Nm amd
 171 to standard output where it can be saved into a file.
 172 .It Fl r
 173 Restart existing mounts.
 174 .Nm Amd
 175 will scan the mount file table to determine which filesystems
 176 are currently mounted.  Whenever one of these would have
 177 been auto-mounted,
 178 .Nm amd
 179 .Em inherits
 180 it.
 181 .It Fl t Ar timeout.retransmit
 182 Specify the NFS timeout
 183 .Ar interval ,
 184 in tenths of a second, between
 185 .Tn NFS/RPC
 186 retries (for UDP only).  The default
 187 is 0.8 seconds.  The second value alters the restransmit counter, which
 188 defaults to 11 retransmissions.  Both of these values are used by the kernel
 189 to communicate with amd.  Useful defaults are supplied if either or both
 190 values are missing.
 191 .Pp
 192 Amd relies on the kernel RPC retransmit mechanism to trigger mount retries.
 193 The values of these parameters change the overall retry interval.  Too long
 194 an interval gives poor interactive response; too short an interval causes
 195 excessive retries.
 196 .It Fl v
 197 Version.  Displays version and configuration information on standard error.
 198 .It Fl w Ar interval
 199 Specify an
 200 .Ar interval ,
 201 in seconds, between attempts to dismount filesystems that have exceeded their
 202 cached times.  The default is 2 minutes.
 203 .It Fl x Ar options
 204 Specify run-time logging options.  The options are a comma separated list
 205 chosen from: fatal, error, user, warn, info, map, stats, all.
 206 .It Fl y Ar domain
 207 Specify an alternative
 208 .Tn NIS
 209 domain from which to fetch the
 210 .Tn NIS
 211 maps.
 212 The default is the system domain name.
 213 This option is ignored if
 214 .Tn NIS
 215 support is not available.
 216 .It Fl C Ar cluster-name
 217 Specify an alternative HP-UX cluster name to use.
 218 .It Fl D Ar option
 219 Select from a variety of debug options.  Prefixing an
 220 option with the string
 221 .Em no
 222 reverses the effect of that option.  Options are cumulative.
 223 The most useful option is
 224 .Ar all .
 225 .Pp
 226 Since
 227 .Fl D
 228 is only used for debugging other options are not documented here:
 229 the current supported set of options is listed by the
 230 .Fl v
 231 option
 232 and a fuller description is available in the program source.
 233 .It Fl F Ar conf_file
 234 Specify an
 235 .Nm amd
 236 configuration file to use.  See
 237 .Xr amd.conf 5
 238 for description of this file's format.  This configuration file is used to
 239 specify any options in lieu of typing many of them on the command line.  The
 240 .Nm amd.conf
 241 file includes directives for every command line option amd has,
 242 and many more that are only available via the configuration file
 243 facility.  The configuration file specified by this option is
 244 processed after all other options have been processed, regardless
 245 of the actual location of this option on the command line.
 246 .It Fl H
 247 Print help and usage string.
 248 .It Fl O Ar op_sys_name
 249 Override the compiled-in name of the operating system.
 250 Useful when the built in name is not desired for backward
 251 compatibility reasons.
 252 For example, if the build in name is
 253 .Dq sunos5 ,
 254 you can override it to
 255 .Dq sos5
 256 and use older maps which were written with the latter in mind.
 257 .It Fl S
 258 Do not lock the running executable pages of
 259 .Nm amd
 260 into memory.  To improve
 261 .Nm amd's
 262 performance, systems that support the
 263 .Xr plock 3
 264 call, could lock the
 265 .Nm amd
 266 process into memory.  This way there is less chance the operating system will
 267 schedule, page out, and swap the
 268 .Nm amd
 269 process as needed.  This tends to improve
 270 .Nm amd's
 271 performance, at the cost of reserving the memory used by the
 272 .Nm amd
 273 process
 274 (making it unavailable for other processes).
 275 If this behavior is not desired, use the
 276 .Fl S
 277 option.
 278 .It Fl T Ar tag
 279 Specify a tag to use with
 280 .Xr amd.conf 5 .
 281 All Map entries tagged with tag will be processed.
 282 Map entries that are not tagged are always processed.
 283 Map entries that are tagged with a tag other than
 284 .Ar tag
 285 will not be processed.
 286 .El
 287 .Sh FILES
 288 .Bl -tag -width /axx
 289 .It Pa /.amd_mnt
 290 directory under which filesystems are dynamically mounted
 291 .It Pa /etc/amd.conf
 292 default configuration file
 293 .El
 294 .Sh CAVEATS
 295 Some care may be required when creating a mount map.
 296 .Pp
 297 Symbolic links on an
 298 .Tn NFS
 299 filesystem can be incredibly inefficient.
 300 In most implementations of
 301 .Tn NFS ,
 302 their interpolations are not cached by
 303 the kernel and each time a symbolic link is
 304 encountered during a
 305 .Em lookuppn
 306 translation it costs an
 307 .Tn RPC
 308 call to the
 309 .Tn NFS
 310 server.
 311 A large improvement in real-time
 312 performance could be gained by adding a cache somewhere.
 313 Replacing
 314 .Xr symlink 2
 315 with a suitable incarnation of the auto-mounter
 316 results in a large real-time speedup, but also causes a large
 317 number of process context switches.
 318 .Pp
 319 A weird imagination is most useful to gain full advantage of all
 320 the features.
 321 .Sh SEE ALSO
 322 .Xr domainname 1 ,
 323 .Xr hostname 1 ,
 324 .Xr syslog 3 ,
 325 .Xr amd.conf 5 ,
 326 .Xr mtab 5 ,
 327 .Xr amq 8 ,
 328 .Xr mount 8 ,
 329 .Xr umount 8
 330 .Rs
 331 .%T Amd \- The 4.4 BSD Automounter
 332 .Re
 333 .Pp
 334 .Pa http://www.cs.columbia.edu/~ezk/am-utils/
 335 .Sh AUTHORS
 336 .An Jan-Simon Pendry Aq jsp@doc.ic.ac.uk ,
 337 Department of Computing, Imperial College, London, UK.
 338 .Pp
 339 .An Erez Zadok Aq ezk@cs.columbia.edu ,
 340 Department of Computer Science, Columbia University,
 341 New York, USA.
 342 .Pp
 343 Other authors and contributors to am-utils are listed in the
 344 .Pa AUTHORS
 345 file distributed with am-utils.
 346 .Sh HISTORY
 347 The
 348 .Nm amd
 349 utility first appeared in
 350 .Bx 4.4 .