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