Return to cmdline.tex CVS log

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

BSD 4.3reno

% $Id: cmdline.tex,v 1.1.1.1 2018/04/24 16:12:57 root Exp $
%
% Copyright (c) 1989 Jan-Simon Pendry
% Copyright (c) 1989 Imperial College of Science, Technology & Medicine
% Copyright (c) 1989 The Regents of the University of California.
% All rights reserved.
%
% This code is derived from software contributed to Berkeley by
% Jan-Simon Pendry at Imperial College, London.
%
% Redistribution and use in source and binary forms are permitted provided
% that: (1) source distributions retain this entire copyright notice and
% comment, and (2) distributions including binaries display the following
% acknowledgement:  ``This product includes software developed by the
% University of California, Berkeley and its contributors'' in the
% documentation or other materials provided with the distribution and in
% all advertising materials mentioning features or use of this software.
% Neither the name of the University nor the names of its contributors may
% be used to endorse or promote products derived from this software without
% specific prior written permission.
% THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
% WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
%
%	@(#)cmdline.tex	5.1 (Berkeley) 7/19/90


\Chapter{Command Line Options}
Many of \amd's parameters can be set from the command line.
The command line is also used to specify automount points
and maps.

The general format of a command line is
\begin{quote}
{\tt amd} {\em options} directory map-name [{\tt -}{\em map-options}] \ldots
\end{quote}
For each directory and map-name given, \amd\ establishes an automount point.
The {\em map-options} may be any sequence of options or selectors as described
in \Ref{opts:values}.
The {\em map-options} apply only to \amd's mount point.
{\tt type:=auto;cache:=none;fs:=\$\{map\}} is the default value for the map options.
Default options for
a map are read from a special entry in the map whose key is the string
{\tt /defaults}.
When default options are given they are prepended to any
options specified in the mount-map locations as explained in \Ref{/defaults}.

The {\em options} are any combination of the following:

\begin{description}
\item[\tt -a \em directory]\mbox{}\\
specifies the default mount directory.
This option changes the variable \Var{autodir} which
otherwise defaults to {\tt /a}.
For example, some sites prefer {\tt /am}.
\begin{quote}
\tt
amd -a /am ...
\end{quote}

\item[\tt -c \em cache-interval]\mbox{}\\
selects the period, in seconds, for which a name is cached by \amd.
If no reference is made to the volume in this period,
\amd\ discards the volume name to filesystem mapping.  Once the last
reference to a filesystem has been removed, \amd\ attempts to unmount the filesystem.
If the unmount fails the interval is extended by a further period
as specified by the {\tt -w} command line option or by the {\tt utimeout} mount option.
The default {\em cache-interval} is 300 seconds (five minutes).

\item[\tt -d \em domain]\mbox{}\\
specifies the host's domain.  This sets the internal variable \Var{domain}
and affects the \Var{hostd} variable.
If this option is not specified and
the hostname already contains the local domain then that is
used, otherwise the default value of \Var{domain} is {\tt unknown.domain}.
For example, if the local domain was {\tt doc.ic.ac.uk}, \amd\ could be
started as follows:
\begin{quote}
\tt
amd -d doc.ic.ac.uk ...
\end{quote}

\item[\tt -k \em kernel-architecture]\mbox{}\\
specifies the kernel architecture of the system.  This is usually
the output of {\tt arch -k} and its only effect is to set the
variable \Var{karch}.  If this option is not given, \Var{karch}
has the same value as \Var{arch}.
This would be used as follows:
\begin{quote}
\tt
amd -k `arch -k` ...
\end{quote}

\item[\tt -l \em log-option]\mbox{}\\
selects the form of logging to be made.
Two special {\em log-option}s are recognised.
If {\em log-option} is the string {\tt syslog}, \amd\ will use
the {\bf syslog}(3) mechanism.
If {\em log-option} is the string {\tt /dev/stderr}\footnote{
This pathname is interpreted internally by \amd; a {\tt /dev/fd}
driver is not required.
}, \amd\ will use
standard error, which is also the default target for log messages.
Any other string is taken as a filename to
use for logging.  Log messages are appended to the file if it already
exists, otherwise a new file is created.
The file is opened once and then held open, rather than being re-opened
for each message.
If the {\tt syslog} option is specified but the system does not support syslog or
if the named file cannot be opened or created, \amd\ will use standard error.
Error messages generated before \amd\ has finished parsing the command line
are printed on standard error.
Using {\tt syslog} is usually best, in which case \amd\ would be
started as follows:
\begin{quote}
\tt
amd -l syslog ...
\end{quote}

%\item[\tt -m]\mbox{}\\
%is an obsolete option that was the equivalent of appending
%{\tt `ypcat -k am.master`} to the command line.
%tells \amd\ {\em not} to obtain a list of automount points from Yellow Pages.
%By default, \amd\ attempts to enumerate the YP maps {\tt am.master} and {\tt auto.master}.
%The default YP domain is used unless the ``-y'' option is given.
%{\em This option will be removed in the next release.}

\item[\tt -n]\mbox{}\\
normalises the remote hostname before using it.
Normalisation is done by replacing the value of \Var{rhost} with the primary name returned by
a hostname lookup.
This option should be used if several names are used to refer to a single host in a
mount map.

\item[\tt -p]\mbox{}\\
causes \amd's process id to be printed on standard output.
This can be redirected to a suitable file for use with kill:
\begin{quote}
\tt
amd -p > /var/run/amd.pid ...
\end{quote}

\item[\tt -r]\mbox{}\\
tells \amd\ to restart existing mounts (see the Inheritance File System \Ref{ifs}).
%{\em This option will be made the default in the next release.}

\item[\tt -t \em afs-timeout.afs-retransmit]\mbox{}\\
specifies the RPC timeout and retransmit intervals used by the kernel to communicate
to \amd.  These are used to set the {\tt timeo} and {\tt retrans} mount options.
\Amd\ relies on the kernel RPC retry mechanism to trigger mount retries.
The value of this parameter changes the retry interval.  Too long an interval
gives poor interactive response, too short an interval causes excessive
retries.

\item[\tt -v]\mbox{}\\
print version information on standard error and then exit.
The output is of the form:
\begin{verbatim}
amd 5.2 of 90/06/23 23:55:04 Rel5.2 #0: Sat Jun 23 16:24:42 PDT 1990
Built by [email protected] for a tahoe running bsd44 (big-endian)
Map support for: root, passwd, file, error.
\end{verbatim}
The information includes the version number, release date and name
of the release.
The architecture (\see \Ref{table:arch}), operating system (\see \Ref{table:os})
and byte ordering are also printed as they appear in the \Var{os},
\Var{arch} and \Var{byte} variables.

\item[\tt -w \em wait-timeout]\label{opt:wait}\mbox{}\\
selects the interval in seconds between unmount attempts after
the initial time-to-live has expired.
This defaults to 120 seconds (two minutes).

\item[\tt -x \em opts]\mbox{}\\
specifies the type and verbosity of log messages.  {\em opts} is
a comma separated list selected from the options in table \ref{table:x opts}.
\begin{table}[htb]
\centering
\begin{tabular}{ll}
Log option  & Messages logged \\\hline
\tt fatal   & Fatal errors \\
\tt error   & Non-fatal errors \\
\tt user    & Non-fatal user errors \\
\tt warn    & Recoverable errors \\
\tt warning & Alias for \tt warn \\
\tt info    & Information messages \\
\tt map     & Mount map usage \\
\tt stats   & Additional statistics \\
\tt all     & All of the above \\
\end{tabular}
\caption{Logging options\label{table:x opts}}
\end{table}
The default logging option, if none is given on the command line,
is {\tt -x~all,nomap,nostats} which is also reasonable for production use.
The {\tt info} messages
include details of what is mounted and unmounted and when filesystems
have timed out.  The messages given by {\tt user} relate to errors
in the mount maps, so these are useful when new maps are installed.

The options can be prefixed by the string {\tt no} to indicate
that this option should be turned off.  For example, to obtain all
but {\tt info} messages the option {\tt -x~all,noinfo} would be used.

\item[\tt -y \em yp-domain]\mbox{}\\
selects an alternate YP domain.  This is useful for debugging and
cross-domain shared mounting.
If this flag is specified, \amd\ immediately attempts to
bind to a server for this domain.
%\Amd\ refers to YP maps when it starts, unless the ``-m'' option
%is specified, and whenever required in a mount map.

\item[\tt -C \em cluster-name]\mbox{}\\
specifies the name of the cluster of which the local machine is a member.
The only effect is to set the variable \Var{cluster}.
The {\em cluster-name} is will usually obtained by running another command which uses
a database to map the local hostname into a cluster name.
\Var{cluster} can then be used as a selector to restrict mounting of
replicated data.
If this option is not given, \Var{cluster} has the same value as \Var{domain}.
This would be used as follows:
\begin{quote}
\tt
amd -C `clustername` ...
\end{quote}

\item[\tt -D {\em opts}]\mbox{}\\
controls the verbosity and coverage of the debugging trace;
{\em opts} is a comma separated list of debugging options.
The ``-D'' option is only available if \amd\ was compiled with {\tt -DDEBUG}.
The memory debugging facilities are
only available if \amd\ was compiled with {\tt -DDEBUG\_MEM}
(in addition to {\tt -DDEBUG}).
The most common options to use are {\tt -D~trace} and {\tt -D~test}
(which turns on all the useful debug options).
See the program source for a more detailed explanation of the available options.

\end{description}

Once the command line has been parsed, the automount points are mounted.
The mount points are created if they do not already exist, in which case they
will be removed when \amd\ exits.
Finally, \amd\ disassociates itself from its controlling terminal and
forks into the background.

{\em Note\/}: Even if \amd\ has been built with {\tt -DDEBUG} it
will still background itself and disassociate itself from the controlling terminal.
To use a debugger it is necessary to
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.