freebsd-dev/usr.sbin/amd/text/INSTALL

Installation Notes for Amd.

NOTE: Please read all of this before starting.
      It is not very long and may save you time in the long term.

1.  ``Getting started...''

If you don't know what an Automounter does for you then read the
documentation in doc/amdref.texinfo.  You can either use TeX to print
it out or read it directly using the GNU info package.

2.  ``Find out what version of UN*X you are running...''

To install Amd you need a port for your version of UN*X.  In the
config/ directory are several files called os-*.h.  One of these
should correspond to your version of UN*X.  Run the program
"config/os-type" to find out what system Amd thinks you have.  Check
the correspondong config/os-??? file to make sure that you and Amd are
in agreement.  If os-type returns "unknown" then either no-one has yet
done a port, or your version of UN*X is so braindead that a port is
not possible (e.g. System V without reliable signals).  The current
known operating systems (grouped by architecture) are:

	acis43			(AOS) ACIS 4.3BSD on an IBM RT
	aix3			AIX 3.2
	aux			Apple A/UX
	bsd44			4.4 BSD on whatever
	concentrix		Concentrix on an Alliant
	dgux			Data General AViiON
	fpx4			Celerity FPX 4.1/2
	hlh42			4.2 BSD on HLH Orion 1/05
	hpux			HP-UX 6.* and 7.* on a HP9000/300
	irix3			SGI Iris
	irix4			SGI Iris w/Irix 4.0.x
	next			NeXT
	riscix			4.3 BSD on an Acorn Archimedes
	sos3, sos4		SunOS 3.* and 4.* on a Sun-3 and Sun-4
	u2_2			Ultrix 2.2 (or 2.*?) on a VAX (broken)
	u3_0			Ultrix 3.0 (or 3.*?) on a VAX (broken)
	u4_2			Ultrix 4.2
	umax43			4.3 BSD on an Encore Multimax
	xinu43			More/BSD (4.3 BSD) on a VAX or HP9000/300

	+ some others...

If you do define a new operating system type foo, you may need to create a
file called Makefile.foo which defines the special Makefile parameters.

3.  ``Hacking the Makefile...''

Amd tries very hard to determine what type of machine you are using
and how best to compile itself.  If this does not work then you will
have to find some heuristic which can differentiate your
configuration.  You may need to edit "config/arch" and
"config/os-type".  If you do make sure your changes can cope if
/etc/motd is missing and please send it to the address below.

To check whether things are working, run:
	sh config/arch
	sh config/os-type

You may care to tailor some site specific preferences in "Makefile.com".  The
variables most likely to be changes are at the top.  Any changes should be
added to a file called config/Makefile.local (if they are applicable to all
operating systems at your site) or Makefile.local.foo (where foo is the OS type
as determined in part 2).

Additionally, some configuration options may be altered in
"config/Makefile.config".  This means that you should not need to edit any
distributed files apart from "config/Makefile.config".  As a minimum, you
should check:

* You are using the correct C compiler.  Amd, as shipped, does not use GCC.
  Note that using GCC version 1.34 or later (e.g. 1.36) gives structure
  passing problems with some parts of Sun's RPC library at least on Sun-4's.
  The current workaround is to use the system CC to compile the part of the
  automounter that gets hit by this problem.  [[This is not the same problem
  that is fixed by -fpcc-struct-return.]]  Amd contains no "register"
  declarations, so using old PCC based code generators is probably bad news.

  To use GNU CC, add the following to config/Makefile.local{.os-type}:

	CC = gcc ${GCCOPTS}

* The installation directory (ETC) is set up correctly.

* If you are running tests then it may be worth switching on the DEBUG flag
  which will cause a running commentary to be printed to the log file.  To
  compile in the debug code, add the following to
  config/Makefile.local{.os-type}:

	DEBUG = -DDEBUG
	CCOPTS = -g

  The -g option will also allow you to use gdb.  Using dbx is not advisable
  since it puts a breakpoint on exit() which causes all of Amd's child
  processes to dump core.  gdb does not suffer from this problem.

4.  ``Build the executable...''

Now you need to compile the automounter.  To do this you type:

	make

in the top-level directory.  You can also go into each of the program
directories and just run make there.

If you are porting to a new machine you may want to do:

	make OS=foo

where foo is the name of your version of UN*X as determined in part 1, until
you have made the changes to config/os-type and/or config/arch.  When the
compilation is complete you will end up with a program called "A.arch_foo/amd".

Try running:

	A.arch_foo/amd -v

and check the output.  It should look something like:

  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.
  amd 5.2.1.5 of 90/09/16 13:22:46 5.3Alpha5 #0: Sun Sep 16 13:23:28 BST 1990
  Built by pendry@okeeffe.Berkeley.EDU for a tahoe running bsd44 (big-endian)
  Map support for: root, passwd, nis, file, error.
  fstypes: ufs, nfs, nfsx, host, link, program, auto, direct, toplvl, error.

Make sure the O/S and architecture types were correctly derived during the
build.

5.  ``Installation...''

If you are not just testing Amd, then you can install it by typing:

	make install

to install "A.arch_foo/amd" in "/usr/local/etc/amd" (or as otherwise
modified in part 3).

6.  ``Update /etc/rpc''

Amq uses Sun RPC to talk to Amd using program number 300019 which has
been registered with Sun.  Add the following lines to /etc/rpc or your
YP or Hesiod master:

# Automount control protocol
amd	300019	amq

Amd does not require this addition - it just keeps rpcinfo happy.

7.  ``Hanging your machine...''

WARNING:  THIS MAY HANG YOUR MACHINE IF YOU GET IT WRONG.

Running Amd with a carelessly thought out mount map can cause your Amd to
enter a deadlock inside the kernel.  For example, attempting to automount a
directory which is automounted.  This will cause the automounter to issue a mount
request causing the kernel to send an NFS request back to the same automounter,
which is currently stuck in a system call and unable to respond - even
kill -KILL won't get you out of this one.

There is nothing you can do to fix it without rebooting your machine, so...

Find a diskless workstation and play with that first before trying this on
your main 200 user service machine (unless you hate your users).  Something
like a diskless Sun-4 is best for development testing - you can compile on a
Sun-4 server and run the binary on the diskless node.  They reboot very fast
as well between tests.

Now you can try running Amd.  Please read the documentation in doc/Amd.tex
for more details.  The configuration file "maps/a_master" provides a sample for
you to play with.  Something like:

	./amd -c 40 -D test,nodaemon /tmp/amnt ../maps/a_master &

is good for testing.  Note that Amd will clean up correctly if you send it a
SIGINT or SIGTERM.  Other signals are either ignored or will blow it away,
leaving your machine in a potentially dangerous state.

Remember that Amd needs to run as root in order to do mounts/unmounts
though it does check this condition somewhere near line one of main().
It will also need write permission in the working directory if you
have built it with DEBUG defined and your system's mount table is
reflected in a file.  In this case watch out for NFS stepping in and
mapping root to nobody.

8.  ``Report what happened...''

If anything interesting happened, eg it didn't work, please report it to me
-- Jan-Simon Pendry <jsp@doc.ic.ac.uk> -- as detailed in the README file.

$Id$