contrib/amd/amd/amd.8

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