4. Amd 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

amd [options] [{ directory map-name [-map-options] } ...]

For each directory and map-name given or specified in the `amd.conf' file, Amd establishes an automount point. The map-options may be any sequence of options or selectors--see section Location Format. The map-options apply only to Amd's mount point.

`type:=toplvl;cache:=mapdefault;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 `/defaults'. When default options are given they are prepended to any options specified in the mount-map locations as explained in Map Defaults.

The options are any combination of those listed below.

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.

Note: Even if Amd has been built with `-DDEBUG' (via configure --enable-debug), it will still background itself and disassociate itself from the controlling terminal. To use a debugger it is necessary to specify `-D daemon' on the command line. However, even with all of this, mounts and unmounts are performed in the background, and Amd will always fork before doing them. Therefore, debugging what happens closely during un/mounts is more challenging.

All of Amd's command options (save -F and -T) can be specified in the `amd.conf' file. See section Amd Configuration File. If Amd is invoked without any command line options, it will default to using the configuration file `/etc/amd.conf', if one exists.

4.1 -a directory

Specifies the default mount directory. This option changes the variable ${autodir} which otherwise defaults to `/a'. For example, some sites prefer `/amd' or `/n'.

amd -a /amd ...

4.2 -c cache-interval

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 `-w' command line option or by the `utimeout' mount option.

The default cache-interval is 300 seconds (five minutes).

4.3 -d domain

Specifies the host's domain. This sets the internal variable ${domain} and affects the ${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 ${domain} is `unknown.domain'.

For example, if the local domain was `doc.ic.ac.uk', Amd could be started as follows:

amd -d doc.ic.ac.uk ...

4.4 -k kernel-architecture

Specifies the kernel architecture of the system. This is usually the output of `uname -m' (the "machine" value gotten from uname(2)). If the uname(2) system call is not available, the value of ${karch} defaults to that of ${arch}.

The only effect of this option is to set the variable ${karch}.

This option would be used as follows:

amd -k `arch -k` ...

4.5 -l log-option

Selects the form of logging to be made. Several special log-options are recognized.

1. If log-option is the string `syslog', Amd will use the syslog(3) mechanism. If your system supports syslog facilities, then the default facility used is `LOG_DAEMON'.
2. When using syslog, if you wish to change the facility, append its name to the log option name, delimited by a single colon. For example, if log-options is the string `syslog:local7' then Amd will log messages via syslog(3) using the `LOG_LOCAL7' facility. If the facility name specified is not recognized, Amd will default to `LOG_DAEMON'. Note: while you can use any syslog facility available on your system, it is generally a bad idea to use those reserved for other services such as `kern', `lpr', `cron', etc.
3. If log-option is the string `/dev/stderr', Amd will use standard error, which is also the default target for log messages. To implement this, Amd simulates the effect of the `/dev/fd' driver.

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.

Normally, when long-running daemons hold an open file descriptor on a log file, it is impossible to "rotate" the log file and compress older logs on a daily basis. The daemon needs to be told to discard (via close(2)) its file handle, and re-open the log file. This is done using amq -l log-option. See section Amq -l option.

If the `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.

Since Amd tends to generate a lot of logging information (especially if debugging was turned on), and due to it being an important program running on the system, it is usually best to log to a separate disk file. In that case Amd would be started as follows:

amd -l /var/log/amd ...

4.6 -n

Normalizes the remote hostname before using it. Normalization is done by replacing the value of ${rhost} with the (generally fully qualified) 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.

4.7 -o op-sys-ver

Overrides the compiled-in version number of the operating system, with op-sys-ver. Useful when the built-in version is not desired for backward compatibility reasons. For example, if the built-in version is `2.5.1', you can override it to `5.5.1', and use older maps that were written with the latter in mind.

4.8 -p

Causes Amd's process id to be printed on standard output. This can be redirected to a suitable file for use with kill:

amd -p > /var/run/amd.pid ...

This option only has an affect if Amd is running in daemon mode. If Amd is started with the -D daemon debug flag, this option is ignored.

4.9 -r

Tells Amd to restart existing mounts (see section Inheritance Filesystem (`inherit')).

4.10 -t timeout.retransmit

Specifies the RPC timeout interval and the retransmit counter used by the kernel to communicate to Amd. These are used to set the `timeo' and `retrans' mount options, respectively. The default timeout is 0.8 seconds, and the default number of retransmissions is 11.

Amd relies on the kernel RPC retransmit mechanism to trigger mount retries. The values of these parameters change the overall retry interval. Too long an interval gives poor interactive response; too short an interval causes excessive retries.

4.11 -v

Print version information on standard error and then exit. The output is of the form:

Copyright (c) 1997-1999 Erez Zadok
Copyright (c) 1990 Jan-Simon Pendry
Copyright (c) 1990 Imperial College of Science, Technology & Medicine
Copyright (c) 1990 The Regents of the University of California.
am-utils version 6.0a15 (build 61).
Built by ezk@example.com on date Wed Oct 22 15:21:03 EDT 1997.
cpu=sparc (big-endian), arch=sun4, karch=sun4u.
full_os=solaris2.5.1, os=sos5, osver=5.5.1, vendor=sun.
Map support for: root, passwd, union, nisplus, nis, ndbm, file, error.
AMFS: nfs, link, nfsx, nfsl, host, linkx, program, union, inherit,
      ufs, lofs, hsfs, pcfs, auto, direct, toplvl, error.
FS: autofs, cachefs, cdfs, lofs, nfs, nfs3, pcfs, tfs, tmpfs, ufs.
Network 1: wire="mcl-lab-net.cs.columbia.edu" (netnumber=128.59.13).
Network 2: wire="14-net.cs.columbia.edu" (netnumber=128.59.14).
Network 3: wire="old-net.cs.columbia.edu" (netnumber=128.59.16).

The information includes the version number, number of times Amd was compiled on the local system, release date and name of the release. Following come the cpu type, byte ordering, and the architecture and kernel architecture as ${arch} and ${karch}, respectively. The next line lists the operating system full name, short name, version, and vendor. These four values correspond to the variables ${full_os}, ${os}, ${osver}, and ${vendor}, respectively. See section Supported Platforms.

Then come a list of map types supported, filesystems internally supported by Amd (AMFS), and generic filesystems available (FS). Finally all known networks (if any) of this host are listed by name and number. They are available via the variables ${wire} or ${network}, and ${netnumber} (see section Selectors) or the `in_network' selector function (see section in_network Selector Function).

4.12 -w wait-timeout

Selects the interval in seconds between unmount attempts after the initial time-to-live has expired.

This defaults to 120 seconds (two minutes).

4.13 -x opts

Specifies the type and verbosity of log messages. opts is a comma separated list selected from the following options:

fatal

Fatal errors (cannot be turned off)

error

Non-fatal errors (cannot be turned off)

user

Non-fatal user errors

warn

Recoverable errors

warning

Alias for warn

info

Information messages

map

Mount map usage

stats

Additional statistics

all

All of the above

defaults

An alias for "fatal,error,user,warning,info".

Initially a set of default logging flags is enabled. This is as if `-x defaults' or `-x fatal,error,user,warning,info' had been selected. The command line is parsed and logging is controlled by the -x option. The very first set of logging flags is saved and can not be subsequently disabled using Amq. This default set of options is useful for general production use.

The `info' messages include details of what is mounted and unmounted and when filesystems have timed out. If you want to have the default set of messages without the `info' messages then you simply need `-x noinfo'. The messages given by `user' relate to errors in the mount maps, so these are useful when new maps are installed. The following table lists the syslog priorities used for each of the message types.

fatal

`LOG_CRIT'

error

`LOG_ERR'

user

`LOG_WARNING'

warning

`LOG_WARNING'

info

`LOG_INFO'

debug

`LOG_DEBUG'

map

`LOG_DEBUG'

stats

`LOG_INFO'

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

If Amd was built with debugging enabled the debug option is automatically enabled regardless of the command line options.

4.14 -y NIS-domain

Selects an alternate NIS 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.

4.15 -A architecture

Specifies the OS architecture of the system. The only effect of this option is to set the variable ${arch}.

This option would be used as follows:

amd -A i386 ...

4.16 -C cluster-name

Specifies the name of the cluster of which the local machine is a member. The only effect is to set the variable ${cluster}. The cluster-name is will usually obtained by running another command which uses a database to map the local hostname into a cluster name. ${cluster} can then be used as a selector to restrict mounting of replicated data. If this option is not given, ${cluster} has the same value as ${domain}. This would be used as follows:

amd -C `clustername` ...

4.17 -D opts

Controls the verbosity and coverage of the debugging trace; opts is a comma separated list of debugging options. The -D option is only available if Amd was compiled with `-DDEBUG', or configured with configure --enable-debug. The memory debugging facilities (`mem') are only available if Amd was compiled with `-DDEBUG_MEM' (in addition to `-DDEBUG'), or configured with configure --enable-debug=mem.

The most common options to use are `-D trace' and `-D test' (which turns on all the useful debug options). As usual, every option can be prefixed with `no' to turn it off.

all

all options (excluding hrtime and mtab)

defaults

"sensible" default options (all-excluding hrtime, mtab, and xdrtrace)

test

full debug options plus mtab,nodaemon,nofork,noamq

amq

register Amd with the RPC portmapper, for Amq

daemon

enter daemon mode

fork

fork child worker (hlfsd only)

full

program trace

hrtime

print high resolution time stamps (only if syslog(3) is not used)

info

info service specific debugging (hesiod, nis, etc.) In the case of hesiod maps, turns on the hesiod RES_DEBUG internal debugging option.

mem

trace memory allocations. Needs to be explicitly enabled at compile time with -enable-debug=mem.

mtab

use local mount-table file (defaults to `/tmp/mtab', see section debug_mtab_file Parameter)

readdir

show readdir progress

str

debug string munging

trace

trace RPC protocol and NFS mount arguments

xdrtrace

trace XDR routines

You may also refer to the program source for a more detailed explanation of the available options.

4.18 -F conf-file

Specify an Amd configuration file conf-file to use. For a description of the format and syntax, see section Amd Configuration File. This configuration file is used to specify any options in lieu of typing many of them on the command line. The `amd.conf' file includes directives for every command line option Amd has, and many more that are only available via the configuration file facility. The configuration file specified by this option is processed after all other options had been processed, regardless of the actual location of this option on the command line.

4.19 -H

Print a brief help and usage string.

4.20 -O op-sys-name

Overrides the compiled-in name of the operating system, with op-sys-name. Useful when the built-in name is not desired for backward compatibility reasons. For example, if the build in name is `sunos5', you can override it to the old name `sos5', and use older maps which were written with the latter in mind.

4.21 -S

Do not lock the running executable pages of Amd into memory. To improve Amd's performance, systems that support the plock(3) or mlockall(2) call lock the Amd process into memory. This way there is less chance the operating system will schedule, page out, and swap the Amd process as needed. This tends to improve Amd's performance, at the cost of reserving the memory used by the Amd process (making it unavailable for other processes). If this behavior is not desired, use the -S option.

4.22 -T tag

Specify a tag to use with `amd.conf'. All map entries tagged with tag will be processed. Map entries that are not tagged are always processed. Map entries that are tagged with a tag other than tag will not be processed.

This document was generated by Erez Zadok on November, 27 2006 using texi2html 1.76.