home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / bsd_srcs / usr.sbin / amd / text / INSTALL < prev    next >
Encoding:
Text File  |  1991-05-12  |  8.0 KB  |  203 lines
  1. Installation Notes for Amd.
  2.  
  3. NOTE: Please read all of this before starting.
  4.       It is not very long and may save you time in the long term.
  5.  
  6. 1.  ``Getting started...''
  7.  
  8. If you don't know what an Automounter does for you then read the
  9. documentation in doc/amdref.texinfo.  You can either use TeX to print
  10. it out or read it directly using the GNU info package.
  11.  
  12. 2.  ``Find out what version of UN*X you are running...''
  13.  
  14. To install Amd you need a port for your version of UN*X.  In the
  15. config/ directory are several files called os-*.h.  One of these
  16. should correspond to your version of UN*X.  Run the program
  17. "config/os-type" to find out what system Amd thinks you have.  Check
  18. the correspondong config/os-??? file to make sure that you and Amd are
  19. in agreement.  If os-type returns "unknown" then either no-one has yet
  20. done a port, or your version of UN*X is so braindead that a port is
  21. not possible (e.g. System V without reliable signals).  The current
  22. known operating systems (grouped by architecture) are:
  23.  
  24.     acis43            (AOS) ACIS 4.3BSD on an IBM RT
  25.     aix3            AIX 3.1
  26.     aux            Apple A/UX
  27.     bsd44            4.4 BSD on whatever
  28.     concentrix        Concentrix on an Alliant
  29.     dgux            Data General AViiON
  30.     fpx4            Celerity FPX 4.1/2
  31.     hlh42            4.2 BSD on HLH Orion 1/05
  32.     hpux            HP-UX 6.* and 7.* on a HP9000/300
  33.     irix            SGI Iris
  34.     next            NeXT
  35.     riscix            4.3 BSD on an Acorn Archimedes
  36.     sos3, sos4        SunOS 3.* and 4.* on a Sun-3 and Sun-4
  37.     u2_2            Ultrix 2.2 (or 2.*?) on a VAX (broken)
  38.     u3_0            Ultrix 3.0/4.0 (or 3.*?) on a VAX (broken)
  39.     umax43            4.3 BSD on an Encore Multimax
  40.     xinu43            More/BSD (4.3 BSD) on a VAX or HP9000/300
  41.  
  42.     + some others...
  43.  
  44. If you do define a new operating system type foo, you may need to create a
  45. file called Makefile.foo which defines the special Makefile parameters.
  46.  
  47. 3.  ``Hacking the Makefile...''
  48.  
  49. Amd tries very hard to determine what type of machine you are using
  50. and how best to compile itself.  If this does not work then you will
  51. have to find some heuristic which can differentiate your
  52. configuration.  You may need to edit "config/arch" and
  53. "config/os-type".  If you do make sure your changes can cope if
  54. /etc/motd is missing and please send it to the address below.
  55.  
  56. To check whether things are working, run:
  57.     sh config/arch
  58.     sh config/os-type
  59.  
  60. You may care to tailor some site specific preferences in "Makefile.com".  The
  61. variables most likely to be changes are at the top.  Any changes should be
  62. added to a file called config/Makefile.local (if they are applicable to all
  63. operating systems at your site) or Makefile.local.foo (where foo is the OS type
  64. as determined in part 2).
  65.  
  66. Additionally, some configuration options may be altered in
  67. "config/Makefile.config".  This means that you should not need to edit any
  68. distributed files apart from "config/Makefile.config".  As a minimum, you
  69. should check:
  70.  
  71. * You are using the correct C compiler.  Amd, as shipped, does not use GCC.
  72.   Note that using GCC version 1.34 or later (e.g. 1.36) gives structure
  73.   passing problems with some parts of Sun's RPC library at least on Sun-4's.
  74.   The current workaround is to use the system CC to compile the part of the
  75.   automounter that gets hit by this problem.  [[This is not the same problem
  76.   that is fixed by -fpcc-struct-return.]]  Amd contains no "register"
  77.   declarations, so using old PCC based code generators is probably bad news.
  78.  
  79.   To use GNU CC, add the following to config/Makefile.local{.os-type}:
  80.  
  81.     CC = gcc ${GCCOPTS}
  82.  
  83. * The installation directory (ETC) is set up correctly.
  84.  
  85. * If you are running tests then it may be worth switching on the DEBUG flag
  86.   which will cause a running commentary to be printed to the log file.  To
  87.   compile in the debug code, add the following to
  88.   config/Makefile.local{.os-type}:
  89.  
  90.     DEBUG = -DDEBUG
  91.     CCOPTS = -g
  92.  
  93.   The -g option will also allow you to use gdb.  Using dbx is not advisable
  94.   since it puts a breakpoint on exit() which causes all of Amd's child
  95.   processes to dump core.  gdb does not suffer from this problem.
  96.  
  97. 4.  ``Build the executable...''
  98.  
  99. Now you need to compile the automounter.  To do this you type:
  100.  
  101.     make
  102.  
  103. in the top-level directory.  You can also go into each of the program
  104. directories and just run make there.
  105.  
  106. If you are porting to a new machine you may want to do:
  107.  
  108.     make OS=foo
  109.  
  110. where foo is the name of your version of UN*X as determined in part 1, until
  111. you have made the changes to config/os-type and/or config/arch.  When the
  112. compilation is complete you will end up with a program called "A.arch_foo/amd".
  113.  
  114. Try running:
  115.  
  116.     A.arch_foo/amd -v
  117.  
  118. and check the output.  It should look something like:
  119.  
  120.   Copyright (c) 1990 Jan-Simon Pendry
  121.   Copyright (c) 1990 Imperial College of Science, Technology & Medicine
  122.   Copyright (c) 1990 The Regents of the University of California.
  123.   amd 5.2.1.5 of 90/09/16 13:22:46 5.3Alpha5 #0: Sun Sep 16 13:23:28 BST 1990
  124.   Built by pendry@okeeffe.Berkeley.EDU for a tahoe running bsd44 (big-endian)
  125.   Map support for: root, passwd, nis, file, error.
  126.   fstypes: ufs, nfs, nfsx, host, link, program, auto, direct, toplvl, error.
  127.  
  128. Make sure the O/S and architecture types were correctly derived during the
  129. build.
  130.  
  131. 5.  ``Installation...''
  132.  
  133. If you are not just testing Amd, then you can install it by typing:
  134.  
  135.     make install
  136.  
  137. to install "A.arch_foo/amd" in "/usr/local/etc/amd" (or as otherwise
  138. modified in part 3).
  139.  
  140. 6.  ``Update /etc/rpc''
  141.  
  142. Amq uses Sun RPC to talk to Amd using program number 300019 which has
  143. been registered with Sun.  Add the following lines to /etc/rpc or your
  144. YP or Hesiod master:
  145.  
  146. # Automount control protocol
  147. amd    300019    amq
  148.  
  149. Amd does not require this addition - it just keeps rpcinfo happy.
  150.  
  151. 7.  ``Hanging your machine...''
  152.  
  153. WARNING:  THIS MAY HANG YOUR MACHINE IF YOU GET IT WRONG.
  154.  
  155. Running Amd with a carelessly thought out mount map can cause your Amd to
  156. enter a deadlock inside the kernel.  For example, attempting to automount a
  157. directory which is automounted.  This will cause the automounter to issue a mount
  158. request causing the kernel to send an NFS request back to the same automounter,
  159. which is currently stuck in a system call and unable to respond - even
  160. kill -KILL won't get you out of this one.
  161.  
  162. There is nothing you can do to fix it without rebooting your machine, so...
  163.  
  164. Find a diskless workstation and play with that first before trying this on
  165. your main 200 user service machine (unless you hate your users).  Something
  166. like a diskless Sun-4 is best for development testing - you can compile on a
  167. Sun-4 server and run the binary on the diskless node.  They reboot very fast
  168. as well between tests.
  169.  
  170. Now you can try running Amd.  Please read the documentation in doc/Amd.tex
  171. for more details.  The configuration file "maps/a_master" provides a sample for
  172. you to play with.  Something like:
  173.  
  174.     ./amd -c 40 -D test,nodaemon /tmp/amnt ../maps/a_master &
  175.  
  176. is good for testing.  Note that Amd will clean up correctly if you send it a
  177. SIGINT or SIGTERM.  Other signals are either ignored or will blow it away,
  178. leaving your machine in a potentially dangerous state.
  179.  
  180. Remember that Amd needs to run as root in order to do mounts/unmounts
  181. though it does check this condition somewhere near line one of main().
  182. It will also need write permission in the working directory if you
  183. have built it with DEBUG defined and your system's mount table is
  184. reflected in a file.  In this case watch out for NFS stepping in and
  185. mapping root to nobody.
  186.  
  187. 8.  ``Report what happened...''
  188.  
  189. If anything interesting happened, eg it didn't work, please report it to me
  190. -- Jan-Simon Pendry <jsp@doc.ic.ac.uk> -- as detailed in the README file.
  191.  
  192. KNOWN PROBLEMS - Contact me for more details
  193.  
  194. * Amd does not work correctly on a DecStation 3100 system running
  195.   Ultrix 3.1 or 4.0.  This is a bug in Ultrix.  This is caused by a data structure
  196.   size problem in the Ultrix kernel.  Last I heard, this was still not fixed in
  197.   Ultrix 4.0.  Patches are available for anonymous ftp from dip.cs.wisc.edu:
  198.      pub/nfs_subr.o-3.1  (For Ultrix 3.1 -- probably breaks with 3.1C/D)
  199.      pub/nfs_subr.o-4.0  (For Ultrix 4.0, rev 179)
  200.   Thanks to Bruce Cole <cole@cs.wisc.edu> for making them available.
  201.  
  202. $Id: INSTALL,v 5.2.1.3 91/03/03 21:25:18 jsp Alpha $
  203.