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