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


7 Run-time Administration

7.1 Starting Amd

Amd is best started from `/etc/rc.local' on BSD systems, or from the appropriate start-level script in `/etc/init.d' on System V systems.

if [ -f /usr/local/sbin/ctl-amd ]; then
    /usr/local/sbin/ctl-amd start; (echo -n ' amd') > /dev/console
fi

The shell script, `ctl-amd' is used to start, stop, or restart Amd. It is a relatively generic script. All options you want to set should not be made in this script, but rather updated in the `amd.conf' file. See section 6 Amd Configuration File.

If you do not wish to use an Amd configuration file, you may start Amd manually. For example, getting the map entries via NIS:

amd -r -l /var/log/amd `ypcat -k auto.master`

7.2 Stopping Amd

Amd stops in response to two signals.

`SIGTERM'
causes the top-level automount points to be unmounted and then Amd to exit. Any automounted filesystems are left mounted. They can be recovered by restarting Amd with the -r command line option.
`SIGINT'
causes Amd to attempt to unmount any filesystems which it has automounted, in addition to the actions of `SIGTERM'. This signal is primarily used for debugging.

Actions taken for other signals are undefined.

The easiest and safest way to stop Amd, without having to find its process ID by hand, is to use the `ctl-amd' script, as with:

ctl-amd stop

7.3 Restarting Amd

Before Amd can be started, it is vital to ensure that no other Amd processes are managing any of the mount points, and that the previous process(es) have terminated cleanly. When a terminating signal is set to Amd, the automounter does not terminate right then. Rather, it starts by unmounting all of its managed mount mounts in the background, and then terminates. It usually takes a few seconds for this process to happen, but it can take an arbitrarily longer time. If two or more Amd processes attempt to manage the same mount point, it usually will result in a system lockup.

The easiest and safest way to restart Amd, without having to find its process ID by hand, sending it the `SIGTERM' signal, waiting for Amd to die cleanly, and verifying so, is to use the `ctl-amd' script, as with:

ctl-amd restart

The script will locate the process ID of Amd, kill it, and wait for it to die cleanly before starting a new instance of the automounter. `ctl-amd' will wait for a total of 30 seconds for Amd to die, and will check once every 5 seconds if it had.

7.4 Controlling Amd

It is sometimes desirable or necessary to exercise external control over some of Amd's internal state. To support this requirement, Amd implements an RPC interface which is used by the Amq program. A variety of information is available.

Amq generally applies an operation, specified by a single letter option, to a list of mount points. The default operation is to obtain statistics about each mount point. This is similar to the output shown above but includes information about the number and type of accesses to each mount point.

7.4.1 Amq default information

With no arguments, Amq obtains a brief list of all existing mounts created by Amd. This is different from the list displayed by df(1) since the latter only includes system mount points.

The output from this option includes the following information:

For example:

/            root   "root"                    sky:(pid75)
/homes       toplvl /usr/local/etc/amd.homes  /homes
/home        toplvl /usr/local/etc/amd.home   /home
/homes/jsp   nfs    charm:/home/charm         /a/charm/home/charm/jsp
/homes/phjk  nfs    toytown:/home/toytown     /a/toytown/home/toytown/ai/phjk

If an argument is given then statistics for that volume name will be output. For example:

What         Uid   Getattr Lookup RdDir   RdLnk   Statfs Mounted@
/homes       0     1196    512    22      0       30     90/09/14 12:32:55
/homes/jsp   0     0       0      0       1180    0      90/10/13 12:56:58
What
the volume name.
Uid
ignored.
Getattr
the count of NFS getattr requests on this node. This should only be non-zero for directory nodes.
Lookup
the count of NFS lookup requests on this node. This should only be non-zero for directory nodes.
RdDir
the count of NFS readdir requests on this node. This should only be non-zero for directory nodes.
RdLnk
the count of NFS readlink requests on this node. This should be zero for directory nodes.
Statfs
the count of NFS statfs requests on this node. This should only be non-zero for top-level automount points.
Mounted@
the date and time the volume name was first referenced.

7.4.2 Amq -f option

The -f option causes Amd to flush the internal mount map cache. This is useful for example in Hesiod maps since Amd will not automatically notice when they have been updated. The map cache can also be synchronized with the map source by using the `sync' option (see section 5.18 Automount Filesystem (`auto')).

7.4.3 Amq -l option

Tell Amd to use log_file as the log file name. For security reasons, this must be the same log file which Amd used when started. This option is therefore only useful to refresh Amd's open file handle on the log file, so that it can be rotated and compressed via daily cron jobs.

7.4.4 Amq -h option

By default the local host is used. In an HP-UX cluster the root server is used since that is the only place in the cluster where Amd will be running. To query Amd on another host the -h option should be used.

7.4.5 Amq -m option

The -m option displays similar information about mounted filesystems, rather than automount points. The output includes the following information:

For example:

"root"           truth:(pid602)     root   1 localhost is up
hesiod.home      /home              toplvl 1 localhost is up
hesiod.vol       /vol               toplvl 1 localhost is up
hesiod.homes     /homes             toplvl 1 localhost is up
amy:/home/amy    /a/amy/home/amy    nfs    5 amy is up
swan:/home/swan  /a/swan/home/swan  nfs    0 swan is up (Permission denied)
ex:/home/ex      /a/ex/home/ex      nfs    0 ex is down

When the reference count is zero the filesystem is not mounted but the mount point and server information is still being maintained by Amd.

7.4.6 Amq -M option

The -M option passes a new map entry to Amd and waits for it to be evaluated, possibly causing a mount. For example, the following command would cause `/home/toytown' on host `toytown' to be mounted locally on `/mnt/toytown'.

amq -M '/mnt/toytown type:=nfs;rfs:=/home/toytown;rhost:=toytown;fs:=${key}'

Amd applies some simple security checks before allowing this operation. The check tests whether the incoming request is from a privileged UDP port on the local machine. "Permission denied" is returned if the check fails.

This option is very insecure as it is vulnerable to attacks such as IP Spoofing. In other words, it is relatively easy for an attacker who really wants to, to make your Amd process mount any filesystem from the Internet! Therefore, the complete code which supports the -M option in Amd and Amq is turned off by default. To turn it on, you have to reconfigure am-utils with configure --enable-amq-mount. Think twice before doing so, and use this option only if you absolutely need to.

A future release of Amd will include code to allow the mount(8) command to mount automount points:

mount -t amd /vol hesiod.vol

This will then allow Amd to be controlled from the standard system filesystem mount list.

7.4.7 Amq -p option

Return the process ID of the remote or locally running Amd. Useful when you need to send a signal to the local Amd process, and would rather not have to search through the process table. This option is used in the `ctl-amd' script.

7.4.8 Amq -P option

Contact an alternate running Amd that had registered itself on a different RPC program_number and apply all other operations to that instance of the automounter. This is useful when you run multiple copies of Amd, and need to manage each one separately. If not specified, Amq will use the default program number for Amd, 300019. For security reasons, the only alternate program numbers Amd can use range from 300019 to 300029, inclusive.

For example, to kill an alternate running Amd:

kill `amq -p -P 300020`

7.4.9 Amq -s option

The -s option displays global statistics. If any other options are specified or any filesystems named then this option is ignored. For example:

requests  stale     mount     mount     unmount
deferred  fhandles  ok        failed    failed
1054      1         487       290       7017
`Deferred requests'
are those for which an immediate reply could not be constructed. For example, this would happen if a background mount was required.
`Stale filehandles'
counts the number of times the kernel passes a stale filehandle to Amd. Large numbers indicate problems.
`Mount ok'
counts the number of automounts which were successful.
`Mount failed'
counts the number of automounts which failed.
`Unmount failed'
counts the number of times a filesystem could not be unmounted. Very large numbers here indicate that the time between unmount attempts should be increased.

7.4.10 Amq -T option

The -T option causes the Amq to contact Amd using the TCP transport only (connection oriented). Normally, Amq will use TCP first, and if that failed, will try UDP.

7.4.11 Amq -U option

The -U option causes the Amq to contact Amd using the UDP transport only (connectionless). Normally, Amq will use TCP first, and if that failed, will try UDP.

7.4.12 Amq -u option

The -u option causes the time-to-live interval of the named mount points to be expired, thus causing an unmount attempt. This is the only safe way to unmount an automounted filesystem. It is not possible to unmount a filesystem which has been mounted with the `nounmount' flag.

7.4.13 Amq -v option

The -v option displays the version of Amd in a similar way to Amd's -v option.

7.4.14 Other Amq options

Two other operations are implemented. These modify the state of Amd as a whole, rather than any particular filesystem. The -x and -D options have exactly the same effect as Amd's corresponding command line options.

When Amd receives a -x flag it limits the log options being modified to those which were not enabled at startup. This prevents a user turning off any logging option which was specified at startup, though any which have been turned on since then can still be turned off. The -D option has a similar behavior.


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