Go to the first, previous, next, last section, table of contents.


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 3.3 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 section 3.3.1 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 nodaemon' 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 6 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 7.4.3 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

Override 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 nodaemon debug flag, this option is ignored.

4.9 -r

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

4.10 -t timeout.retransmit

Specifies the RPC timeout and retransmit intervals used by the kernel to communicate to Amd. These are used to set the `timeo' and `retrans' mount options.

Amd relies on the kernel RPC retransmit 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.

4.11 -v

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

Copyright (c) 1997-1998 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@cs.columbia.edu 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 full name of the system, the variables ${os} and ${osver}, and the vendor's name. See section 2 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 3.3.3 Selectors) or the `in_network' selector function (see section 3.3.3.20 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
error
Non-fatal errors
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

Initially a set of default logging flags is enabled. This is as if `-x all,nomap,nostats' 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 -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.16 -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
amq
register for amq
daemon
enter daemon mode
fork
fork server
full
program trace
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
mtab
use local `./mtab' file
str
debug string munging
test
full debug but no daemon
trace
protocol trace

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

4.17 -F conf-file

Specify an Amd configuration file conf-file to use. For a description of the format and syntax, see section 6 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.18 -H

Print a brief help and usage string.

4.19 -O op-sys-name

Override 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.20 -S

Do not lock the running executable pages of Amd into memory. To improve Amd's performance, systems that support the plock(3) 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.21 -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.


Go to the first, previous, next, last section, table of contents.