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