1Installation Notes for Amd. 2 3NOTE: Please read all of this before starting. 4 It is not very long and may save you time in the long term. 5 61. ``Getting started...'' 7 8If you don't know what an Automounter does for you then read the 9documentation in doc/amdref.texinfo. You can either use TeX to print 10it out or read it directly using the GNU info package. 11 122. ``Find out what version of UN*X you are running...'' 13 14To install Amd you need a port for your version of UN*X. In the 15config/ directory are several files called os-*.h. One of these 16should correspond to your version of UN*X. Run the program 17"config/os-type" to find out what system Amd thinks you have. Check 18the correspondong config/os-??? file to make sure that you and Amd are 19in agreement. If os-type returns "unknown" then either no-one has yet 20done a port, or your version of UN*X is so braindead that a port is 21not possible (e.g. System V without reliable signals). The current 22known 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 44If you do define a new operating system type foo, you may need to create a 45file called Makefile.foo which defines the special Makefile parameters. 46 473. ``Hacking the Makefile...'' 48 49Amd tries very hard to determine what type of machine you are using 50and how best to compile itself. If this does not work then you will 51have to find some heuristic which can differentiate your 52configuration. 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 56To check whether things are working, run: 57 sh config/arch 58 sh config/os-type 59 60You may care to tailor some site specific preferences in "Makefile.com". The 61variables most likely to be changes are at the top. Any changes should be 62added to a file called config/Makefile.local (if they are applicable to all 63operating systems at your site) or Makefile.local.foo (where foo is the OS type 64as determined in part 2). 65 66Additionally, some configuration options may be altered in 67"config/Makefile.config". This means that you should not need to edit any 68distributed files apart from "config/Makefile.config". As a minimum, you 69should 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 974. ``Build the executable...'' 98 99Now you need to compile the automounter. To do this you type: 100 101 make 102 103in the top-level directory. You can also go into each of the program 104directories and just run make there. 105 106If you are porting to a new machine you may want to do: 107 108 make OS=foo 109 110where foo is the name of your version of UN*X as determined in part 1, until 111you have made the changes to config/os-type and/or config/arch. When the 112compilation is complete you will end up with a program called "A.arch_foo/amd". 113 114Try running: 115 116 A.arch_foo/amd -v 117 118and 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 128Make sure the O/S and architecture types were correctly derived during the 129build. 130 1315. ``Installation...'' 132 133If you are not just testing Amd, then you can install it by typing: 134 135 make install 136 137to install "A.arch_foo/amd" in "/usr/local/etc/amd" (or as otherwise 138modified in part 3). 139 1406. ``Update /etc/rpc'' 141 142Amq uses Sun RPC to talk to Amd using program number 300019 which has 143been registered with Sun. Add the following lines to /etc/rpc or your 144YP or Hesiod master: 145 146# Automount control protocol 147amd 300019 amq 148 149Amd does not require this addition - it just keeps rpcinfo happy. 150 1517. ``Hanging your machine...'' 152 153WARNING: THIS MAY HANG YOUR MACHINE IF YOU GET IT WRONG. 154 155Running Amd with a carelessly thought out mount map can cause your Amd to 156enter a deadlock inside the kernel. For example, attempting to automount a 157directory which is automounted. This will cause the automounter to issue a mount 158request causing the kernel to send an NFS request back to the same automounter, 159which is currently stuck in a system call and unable to respond - even 160kill -KILL won't get you out of this one. 161 162There is nothing you can do to fix it without rebooting your machine, so... 163 164Find a diskless workstation and play with that first before trying this on 165your main 200 user service machine (unless you hate your users). Something 166like a diskless Sun-4 is best for development testing - you can compile on a 167Sun-4 server and run the binary on the diskless node. They reboot very fast 168as well between tests. 169 170Now you can try running Amd. Please read the documentation in doc/Amd.tex 171for more details. The configuration file "maps/a_master" provides a sample for 172you to play with. Something like: 173 174 ./amd -c 40 -D test,nodaemon /tmp/amnt ../maps/a_master & 175 176is good for testing. Note that Amd will clean up correctly if you send it a 177SIGINT or SIGTERM. Other signals are either ignored or will blow it away, 178leaving your machine in a potentially dangerous state. 179 180Remember that Amd needs to run as root in order to do mounts/unmounts 181though it does check this condition somewhere near line one of main(). 182It will also need write permission in the working directory if you 183have built it with DEBUG defined and your system's mount table is 184reflected in a file. In this case watch out for NFS stepping in and 185mapping root to nobody. 186 1878. ``Report what happened...'' 188 189If 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 192KNOWN 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