Return to cmdline.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / usr.sbin / amd / doc

Annotation of 43BSDReno/usr.sbin/amd/doc/cmdline.tex, revision 1.1

1.1     ! root        1: % $Id: cmdline.tex,v 5.2 90/06/23 22:21:53 jsp Rel $
        !             2: %
        !             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 are permitted provided
        !            12: % that: (1) source distributions retain this entire copyright notice and
        !            13: % comment, and (2) distributions including binaries display the following
        !            14: % acknowledgement:  ``This product includes software developed by the
        !            15: % University of California, Berkeley and its contributors'' in the
        !            16: % documentation or other materials provided with the distribution and in
        !            17: % all advertising materials mentioning features or use of this software.
        !            18: % Neither the name of the University nor the names of its contributors may
        !            19: % be used to endorse or promote products derived from this software without
        !            20: % specific prior written permission.
        !            21: % THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            22: % WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            23: % MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            24: %
        !            25: %      @(#)cmdline.tex 5.1 (Berkeley) 7/19/90
        !            26: 
        !            27: 
        !            28: \Chapter{Command Line Options}
        !            29: Many of \amd's parameters can be set from the command line.
        !            30: The command line is also used to specify automount points
        !            31: and maps.
        !            32: 
        !            33: The general format of a command line is
        !            34: \begin{quote}
        !            35: {\tt amd} {\em options} directory map-name [{\tt -}{\em map-options}] \ldots
        !            36: \end{quote}
        !            37: For each directory and map-name given, \amd\ establishes an automount point.
        !            38: The {\em map-options} may be any sequence of options or selectors as described
        !            39: in \Ref{opts:values}.
        !            40: The {\em map-options} apply only to \amd's mount point.
        !            41: {\tt type:=auto;cache:=none;fs:=\$\{map\}} is the default value for the map options.
        !            42: Default options for
        !            43: a map are read from a special entry in the map whose key is the string
        !            44: {\tt /defaults}.
        !            45: When default options are given they are prepended to any
        !            46: options specified in the mount-map locations as explained in \Ref{/defaults}.
        !            47: 
        !            48: The {\em options} are any combination of the following:
        !            49: 
        !            50: \begin{description}
        !            51: \item[\tt -a \em directory]\mbox{}\\
        !            52: specifies the default mount directory.
        !            53: This option changes the variable \Var{autodir} which
        !            54: otherwise defaults to {\tt /a}.
        !            55: For example, some sites prefer {\tt /am}.
        !            56: \begin{quote}
        !            57: \tt
        !            58: amd -a /am ...
        !            59: \end{quote}
        !            60: 
        !            61: \item[\tt -c \em cache-interval]\mbox{}\\
        !            62: selects the period, in seconds, for which a name is cached by \amd.
        !            63: If no reference is made to the volume in this period,
        !            64: \amd\ discards the volume name to filesystem mapping.  Once the last
        !            65: reference to a filesystem has been removed, \amd\ attempts to unmount the filesystem.
        !            66: If the unmount fails the interval is extended by a further period
        !            67: as specified by the {\tt -w} command line option or by the {\tt utimeout} mount option.
        !            68: The default {\em cache-interval} is 300 seconds (five minutes).
        !            69: 
        !            70: \item[\tt -d \em domain]\mbox{}\\
        !            71: specifies the host's domain.  This sets the internal variable \Var{domain}
        !            72: and affects the \Var{hostd} variable.
        !            73: If this option is not specified and
        !            74: the hostname already contains the local domain then that is
        !            75: used, otherwise the default value of \Var{domain} is {\tt unknown.domain}.
        !            76: For example, if the local domain was {\tt doc.ic.ac.uk}, \amd\ could be
        !            77: started as follows:
        !            78: \begin{quote}
        !            79: \tt
        !            80: amd -d doc.ic.ac.uk ...
        !            81: \end{quote}
        !            82: 
        !            83: \item[\tt -k \em kernel-architecture]\mbox{}\\
        !            84: specifies the kernel architecture of the system.  This is usually
        !            85: the output of {\tt arch -k} and its only effect is to set the
        !            86: variable \Var{karch}.  If this option is not given, \Var{karch}
        !            87: has the same value as \Var{arch}.
        !            88: This would be used as follows:
        !            89: \begin{quote}
        !            90: \tt
        !            91: amd -k `arch -k` ...
        !            92: \end{quote}
        !            93: 
        !            94: \item[\tt -l \em log-option]\mbox{}\\
        !            95: selects the form of logging to be made.
        !            96: Two special {\em log-option}s are recognised.
        !            97: If {\em log-option} is the string {\tt syslog}, \amd\ will use
        !            98: the {\bf syslog}(3) mechanism.
        !            99: If {\em log-option} is the string {\tt /dev/stderr}\footnote{
        !           100: This pathname is interpreted internally by \amd; a {\tt /dev/fd}
        !           101: driver is not required.
        !           102: }, \amd\ will use
        !           103: standard error, which is also the default target for log messages.
        !           104: Any other string is taken as a filename to
        !           105: use for logging.  Log messages are appended to the file if it already
        !           106: exists, otherwise a new file is created.
        !           107: The file is opened once and then held open, rather than being re-opened
        !           108: for each message.
        !           109: If the {\tt syslog} option is specified but the system does not support syslog or
        !           110: if the named file cannot be opened or created, \amd\ will use standard error.
        !           111: Error messages generated before \amd\ has finished parsing the command line
        !           112: are printed on standard error.
        !           113: Using {\tt syslog} is usually best, in which case \amd\ would be
        !           114: started as follows:
        !           115: \begin{quote}
        !           116: \tt
        !           117: amd -l syslog ...
        !           118: \end{quote}
        !           119: 
        !           120: %\item[\tt -m]\mbox{}\\
        !           121: %is an obsolete option that was the equivalent of appending
        !           122: %{\tt `ypcat -k am.master`} to the command line.
        !           123: %tells \amd\ {\em not} to obtain a list of automount points from Yellow Pages.
        !           124: %By default, \amd\ attempts to enumerate the YP maps {\tt am.master} and {\tt auto.master}.
        !           125: %The default YP domain is used unless the ``-y'' option is given.
        !           126: %{\em This option will be removed in the next release.}
        !           127: 
        !           128: \item[\tt -n]\mbox{}\\
        !           129: normalises the remote hostname before using it.
        !           130: Normalisation is done by replacing the value of \Var{rhost} with the primary name returned by
        !           131: a hostname lookup.
        !           132: This option should be used if several names are used to refer to a single host in a
        !           133: mount map.
        !           134: 
        !           135: \item[\tt -p]\mbox{}\\
        !           136: causes \amd's process id to be printed on standard output.
        !           137: This can be redirected to a suitable file for use with kill:
        !           138: \begin{quote}
        !           139: \tt
        !           140: amd -p > /var/run/amd.pid ...
        !           141: \end{quote}
        !           142: 
        !           143: \item[\tt -r]\mbox{}\\
        !           144: tells \amd\ to restart existing mounts (see the Inheritance File System \Ref{ifs}).
        !           145: %{\em This option will be made the default in the next release.}
        !           146: 
        !           147: \item[\tt -t \em afs-timeout.afs-retransmit]\mbox{}\\
        !           148: specifies the RPC timeout and retransmit intervals used by the kernel to communicate
        !           149: to \amd.  These are used to set the {\tt timeo} and {\tt retrans} mount options.
        !           150: \Amd\ relies on the kernel RPC retry mechanism to trigger mount retries.
        !           151: The value of this parameter changes the retry interval.  Too long an interval
        !           152: gives poor interactive response, too short an interval causes excessive
        !           153: retries.
        !           154: 
        !           155: \item[\tt -v]\mbox{}\\
        !           156: print version information on standard error and then exit.
        !           157: The output is of the form:
        !           158: \begin{verbatim}
        !           159: amd 5.2 of 90/06/23 23:55:04 Rel5.2 #0: Sat Jun 23 16:24:42 PDT 1990
        !           160: Built by [email protected] for a tahoe running bsd44 (big-endian)
        !           161: Map support for: root, passwd, file, error.
        !           162: \end{verbatim}
        !           163: The information includes the version number, release date and name
        !           164: of the release.
        !           165: The architecture (\see \Ref{table:arch}), operating system (\see \Ref{table:os})
        !           166: and byte ordering are also printed as they appear in the \Var{os},
        !           167: \Var{arch} and \Var{byte} variables.
        !           168: 
        !           169: \item[\tt -w \em wait-timeout]\label{opt:wait}\mbox{}\\
        !           170: selects the interval in seconds between unmount attempts after
        !           171: the initial time-to-live has expired.
        !           172: This defaults to 120 seconds (two minutes).
        !           173: 
        !           174: \item[\tt -x \em opts]\mbox{}\\
        !           175: specifies the type and verbosity of log messages.  {\em opts} is
        !           176: a comma separated list selected from the options in table \ref{table:x opts}.
        !           177: \begin{table}[htb]
        !           178: \centering
        !           179: \begin{tabular}{ll}
        !           180: Log option  & Messages logged \\\hline
        !           181: \tt fatal   & Fatal errors \\
        !           182: \tt error   & Non-fatal errors \\
        !           183: \tt user    & Non-fatal user errors \\
        !           184: \tt warn    & Recoverable errors \\
        !           185: \tt warning & Alias for \tt warn \\
        !           186: \tt info    & Information messages \\
        !           187: \tt map     & Mount map usage \\
        !           188: \tt stats   & Additional statistics \\
        !           189: \tt all     & All of the above \\
        !           190: \end{tabular}
        !           191: \caption{Logging options\label{table:x opts}}
        !           192: \end{table}
        !           193: The default logging option, if none is given on the command line,
        !           194: is {\tt -x~all,nomap,nostats} which is also reasonable for production use.
        !           195: The {\tt info} messages
        !           196: include details of what is mounted and unmounted and when filesystems
        !           197: have timed out.  The messages given by {\tt user} relate to errors
        !           198: in the mount maps, so these are useful when new maps are installed.
        !           199: 
        !           200: The options can be prefixed by the string {\tt no} to indicate
        !           201: that this option should be turned off.  For example, to obtain all
        !           202: but {\tt info} messages the option {\tt -x~all,noinfo} would be used.
        !           203: 
        !           204: \item[\tt -y \em yp-domain]\mbox{}\\
        !           205: selects an alternate YP domain.  This is useful for debugging and
        !           206: cross-domain shared mounting.
        !           207: If this flag is specified, \amd\ immediately attempts to
        !           208: bind to a server for this domain.
        !           209: %\Amd\ refers to YP maps when it starts, unless the ``-m'' option
        !           210: %is specified, and whenever required in a mount map.
        !           211: 
        !           212: \item[\tt -C \em cluster-name]\mbox{}\\
        !           213: specifies the name of the cluster of which the local machine is a member.
        !           214: The only effect is to set the variable \Var{cluster}.
        !           215: The {\em cluster-name} is will usually obtained by running another command which uses
        !           216: a database to map the local hostname into a cluster name.
        !           217: \Var{cluster} can then be used as a selector to restrict mounting of
        !           218: replicated data.
        !           219: If this option is not given, \Var{cluster} has the same value as \Var{domain}.
        !           220: This would be used as follows:
        !           221: \begin{quote}
        !           222: \tt
        !           223: amd -C `clustername` ...
        !           224: \end{quote}
        !           225: 
        !           226: \item[\tt -D {\em opts}]\mbox{}\\
        !           227: controls the verbosity and coverage of the debugging trace;
        !           228: {\em opts} is a comma separated list of debugging options.
        !           229: The ``-D'' option is only available if \amd\ was compiled with {\tt -DDEBUG}.
        !           230: The memory debugging facilities are
        !           231: only available if \amd\ was compiled with {\tt -DDEBUG\_MEM}
        !           232: (in addition to {\tt -DDEBUG}).
        !           233: The most common options to use are {\tt -D~trace} and {\tt -D~test}
        !           234: (which turns on all the useful debug options).
        !           235: See the program source for a more detailed explanation of the available options.
        !           236: 
        !           237: \end{description}
        !           238: 
        !           239: Once the command line has been parsed, the automount points are mounted.
        !           240: The mount points are created if they do not already exist, in which case they
        !           241: will be removed when \amd\ exits.
        !           242: Finally, \amd\ disassociates itself from its controlling terminal and
        !           243: forks into the background.
        !           244: 
        !           245: {\em Note\/}: Even if \amd\ has been built with {\tt -DDEBUG} it
        !           246: will still background itself and disassociate itself from the controlling terminal.
        !           247: To use a debugger it is necessary to
        !           248: specify {\tt -D~nodaemon} on the command line.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.