UK Academic Community Directory Group Directory System Configuration Guide Paul Barker Date: Oct 19, 1989 Organisation: UCL Document Location: UCL ABSTRACT This document is a hardware and software configuration guide for UK academic sites participating in the Directory Pilot. Several people contributed considerably in the production of this document. I would like to acknowledge the help given by Andrew Findlay, Graham Carpenter, Chris Elvin, Tony Bates, Colin Robbins and John Andrews. July 3, 1990 UK Academic Community Directory Group Directory System Configuration Guide Paul Barker Date: Oct 19, 1989 Organisation: UCL Document Location: UCL 1. Introduction This document is a configuration guide for sites participating in the UK Academic Directory Pilot. The document addresses both hardware and software configuration issues. The topics covered are as follows: + The software distribution + Getting the software + Installation of the machine + X.25 cabling + Disk configuration + X.25 software installation and configuration + Installation of ISODE and QUIPU + Configuring the Directory This document attempts to describe the configuration and installation procedures fairly fully. However, it has to be assumed that the person installing the system has at least some limited knowledge of UNIX and an editor. More of the installation could be done with scripts. It is the author's feeling that, while this might be initially desirable, it would only postpone the day when the system installer would have to familiarise themselves with some of the more recondite details of UNIX, ISODE and Quipu. One point of contention is of where directory tailor files - 2 - should be stored. One view is that one should not follow the defaults assumed by ISODE, which usually puts these files in the /usr/etc directory. The reason for this is that files in this directory can be lost when installing upgrades to the operating system. Any tailoring has to be exactly repeated or the files carefully preserved. The other view is that the assumptions made by ISODE tend to be fairly ingrained. While it is trivial to configure ISODE differently, the documentation does not always acknowledge this. The author has thus taken the pragmatic view that, on balance, people who are unfamiliar with ISODE and Quipu should not try and reconfigure the default pathnames. But, you must remember to preserve any files you want in /usr/etc (probably dsaptailor, isoentities, isotailor and quiputailor) if you perform an operating system upgrade. Once acclimatised to ISODE, you may well decide to "do your own thing". 2. The software distribution It is recognised that not all sites will obtain the software in exactly the same way. Some sites will be able to get a copy of the software by file transfer (FTAM or NIFTP) while others may require a tape. However the software is obtained, the distribution comprises three components. i A disk configuration shell script which initialises the disk partitions appropriately. Some patches for sunlink. Some scripts which edit system files to arrange for automatic start-up of the X.25 services. ii The ISODE (and Quipu) source. iii Some shell scripts which configures ISODE suitably (and which eventually will add in other Quipu sources not provided as part of the standard ISODE distribution). 3. Getting the software 3.1. Software on a tape The tape will contain 3 files as described above. The instructions for getting the software off the tape are described at appropriate points later in the document. 3.2. Software by FTAM or NIFTP The 3 software components described above need to be copied by whichever means are convenient and appropriate. There are several possibilities: FTAM to 00000511320041, username = x500dist, password = x500dist - 3 - FTAM to 00000511160013, username = anon, no password NIFTP to uk.ac.ucl.cs, binary mode, username = guest, password = (Your mail address in the form user@site) filenames should be prepended with (Note that the angle brackets and capital letters are vital) The files to be copied are named uk-pilot-conf.tar.Z, isode-uk.tar.Z and uk-pilot.tar.Z Again, note that the final `Z' is a capital and the other letters are lower-case. 4. Installation of the machine It is assumed that a SUN engineer will have installed the SUN with its X.25 card, and that the machine will be running a generic version of UNIX. Subsequent sections give details on configuring the disks, UNIX and X.25. 5. X.25 cabling Connecting the SUN to the local X.25 switch is obviously a local issue. Cable specifications exist for connecting the SUN MCP (RS449) to a variety of switch types: namely X.21 DTE, X.21 DCE and the Camtec variant of X.21 DCE. At the time of writing these specifications are not available electronically. Copies of these specifications will be made available to the JNT as a paper appendix to this document. Interested parties should contact the JNT for details. 6. Disk configuration A basic disk configuration has been designed which allocates disk partitions for the ISODE and Quipu source, and the directory database and log files. In addition space has been reserved for the PP X.400 mail system which the machines may eventually run. Since the list of commands required to configure the disk partitions is long and forbidding, several scripts are provided in the uk-pilot-conf file set. 6.1. Installing the uk-pilot-conf files Tape distribution Insert the tape in the drive, and log in as root. Type the following commands to unpack the tape: cd / mt -f /dev/rst0 rew tar xf /dev/rst0 This sequence creates a directory called /pilot and puts various files in it. - 4 - Electronic distribution If you are using file transfer mechanisms, copy the file uk-pilot-conf.tar.Z onto the machine and uncompress and untar the contents: cd / uncompress < /...somewhere..../uk-pilot-conf.tar.Z | tar xf - 6.2. Configuring the disks This part of the process needs to be performed in single- user mode. To get to single-user mode type shutdown now The machine will respond with various messages and will eventually produce a hash (#) prompt. Move to the /pilot directory and start the disk configuration process like this: cd /pilot sh config-disks This process will reconfigure the disks and set up various directories for you. The process is completely automatic and takes about 35-40 minutes. The machine will re-boot itself twice during the process, you are not required to intervene at all. Finally the machine will re-boot and present you with the normal login message. You cannot proceed further until this script has run successfully. You may see some warning messages which can be safely ignored. If this script does not finish with a message telling you that it has configured the disks OK you should consult a guru. 7. X.25 software installation and configuration This section assumes that you now have a system running a generic version of UNIX. This section reconfigures the UNIX kernel to know about the MCP board and sets up the X.25 parameters. Regrettably there are quite a lot of steps - I hope it is reasonably easy to follow. It is anticipated that you will also have the SunLink X.25 System Administration Guide available while you are following this. The next section takes through the configuration, highlighting the main points in the dialogue. When you are required to type something, the expected input is emboldened. - 5 - 7.1. The configuration Login as "root" (no password) and CHANGE THE ROOT PASSWORD: passwd root (Type the new password twice, as directed by the prompts) 7.1.1. Installing MCP software Load the MCP tape into the drive. Type: extract_unbundled After a few messages have been displayed on the screen, you will be prompted "Enter tape drive location [local | remote]". Type local The next prompt wants the device name for the tape drive, but it fills in part of it for you: "Enter Device Name (e.g. st0 mt0 ar0): /dev/nr". Type st0 The first section of the tape gets read, and you will see various messages. At intervals the system asks whether you want to continue. You should obviously answer yes or just y to these questions! The next hard question is "Enter system type [standalone | server]:" Type standalone Lots of tar extraction messages will now be displayed ... A message saying "install_SunLink : **** Installation Completed ****" will be displayed. The job is not really finished as the file /sys/sun/conf.c must be modified. NOTE that this is a bugfix, and it applies to "SunLink 6.0 MCP" ONLY. If you have a later version it should not be needed. To avoid possible errors in editing, a script has been provided with the pilot distribution. To use it, type the following sequence of commands: cd /pilot sh fix-mcp-config Installation can now continue: cd /usr/sunlink/mcp/sys install.mcp The system now asks various questions to determine the configuration that you need. The answers are shown in bold - 6 - below: Enter the name of the kernel configuration file for this system. If you wish to use the GENERIC kernel, simply enter : SDST330 What do you wish to call the modified configuration file? If you wish to use the name GENERIC, simply enter : COMMS_SERVER Updating kernel configuration file. Adding mcp device entries to configuration file. Do you need MCP async (ALM-2) devices (yes or no)? no Do you need MCP hdlc devices (yes or no)? yes Adding mcph entries to configuration file. Do you need MCP sdlc devices (yes or no)? no Do you need MCP bsc devices (yes or no)? no Updating system modules in /usr/share/sys Updating /usr/share/sys/sun4/conf/files Do you want to build kernel (yes or no) ? no 7.1.2. Installing X.25 software Now, following the installation instructions for SunLink-X25 (which will include putting the tape in the drive, I would hope!): extract_unbundled A lot of the questions are similar to those asked when installing the MCP tape, so you should give the same answers. Media local , Device st0 Once again you see various messages to which you should respond y or yes as before. The next question is: Enter system type [standalone | server]: standalone You will now be asked lots of questions which you should answer by pressing to accept the default. You will now see lots of tar-type extraction messages... You will now get another message saying, "**** Installation Completed ****". There is still a bit more to do. cd /usr/sunlink/x25 install.x25 More tar extraction messages will be displayed ... and you will then be taken through the following dialogue. You will need to supply the following information: 1. An existing kernel configuration filename (eg, GENERIC). Using that file as a base, the X25 pseudo- device entries will be added. - 7 - 2. You may specify a new name for this modified kernel configuration. Do you have this information and wish to continue? [y or n]: y Enter the name of an existing kernel configuration file [GENERIC]: COMMS_SERVER What do you wish to call the kernel configuration file after the X25 pseudo-device entries are added? [COMMS_SERVER]: Various updating and so on... Configuring kernel...this can take up to several minutes. Compiling/loading kernel...this can take up to several minutes. /usr/share/sys/sun4/COMMS_SERVER/vmunix has been built. This new vmunix should be copied to /newvmunix and then booted single user mode to test it before installing it as /vmunix. Do you wish to create /dev/ifd entries? [y or n]: y The standard distribution of SunLink 6.0 has some bugs. Fixes exist for many of these, and are provided in the uk- pilot-conf file set. To install them, do this: cd /pilot/x25-fixes make You will see four files get copied into the system configuration area. This will only happen if the patch files are newer than the ones you got from the installation tape. As with the MCP software, if your version is later than 6.0 you may not need to do this step. It is necessary to re-build the kernel to include the patches: cd /sys/sun4/COMMS_SERVER make You will get a few informational messages during the make. If you get error messages during this stage, stop and consult a guru. The kernel is now built, so save the generic one and install it: cd /sys/sun4/COMMS_SERVER mv /vmunix /vmunix.generic cp vmunix /vmunix - 8 - You should now reboot the machine to check the new kernel: reboot If that fails, you will have to reboot using `/vmunix.generic' (which you should never delete, just in case....). If this happens you will need to consult a guru. Log in as root again. Now to configure. At this stage, things are very site- specific, so we cannot provide scripts to do the work. You will have to learn how to use a Unix editor. The standard screen editor is called `vi' (VIsual) and is almost, but not entirely, unlike anything else, ever. If you really detest `vi' after a few weeks, you may prefer to install `emacs', which can be provided pre-compiled by Brunel. cd /etc/sunlink/x25 cp x25params.sample x25params Edit x25params to show your correct DTE address as host_address e.g.: 000041160000 #host_address Also change hp_n1 from 134 to 262. This is apparently the usual value for JANET, though you may have different requirements locally. You should consult with the manager of your X.25 switch about the values for other things in this file. For those sites using a TELEPAC switch the file /pilot/x25fixes/TELEPAC contains a working x25params file and details of the TELEPAC settings. 7.2. Some preliminary testing Get one of the MCP ports connected to an X25 switch. If you cannot easily connect the RS449 ports, start with port 2 and use RS232 (X21bis) at 9600 Baud. Make sure that the X25 switch or modem supplies the clocks. Assuming port X [X=0,1,2 or 3] at baud rate YYYY, issue these commands: /usr/sunlink/x25/x25start 0 mcphX YYYY /usr/sunlink/x25/x25config -a /etc/sunlink/x25/x25params If all is well, you now have an X25 link. You can verify the X.25 operation with the command: /usr/sunlink/x25/vcstat -l0 -i1 - 9 - This should give a display showing HDLC and PACKET levels UP, and will also show the progress of any calls. /usr/sunlink/x25/x25trace is useful for detailed monitoring. 7.3. Arranging for automatic startup To make sure that the X.25 services are started each time the machine boots up, it is necessary to modify /etc/rc.local Rather than add lines to /etc/rc.local for each new service, we will create a file called /etc/rc.x25 and refer to that. [It is important to note that this script assumes that you will be adhering to ISODE's default settings for ETCDIR and SBINDIR. Edit the scripts if you wish to use your own configuration.] A script has been provided for this job, so: cd /pilot/rc make Important: The /etc/rc.x25 file contains commands which assume you are using port 2 at 9600 baud. If you are using some other port, or a different baud rate you will need to edit the x25start command in this file to have the correct values. 8. Installation of ISODE and QUIPU This section covers the compilation of the software and the sequence of actions that must be undertaken to perform some basic tests on the system. It is inadvisable (although possible) to compile and install all the software as the super-user. It is suggested that at this point an isode account is set up to compile and run the software. This account should be set up with /u1/home/isode as its home directory and to have /usr/local/bin in its path as this is where all the binaries will usually be installed. It is also assumed that you will be using /bin/csh as the isode shell. You should use a UID < 100 for the isode account (we suggest using the first free number in your /etc/passwd file). User and database manager accounts should normally have UID's > 100. Refer to the SUN manuals if you are unsure how to do this. Having created this account, you should login as isode to copy the ISODE and Quipu software into place. Two files are required to build the directory software. As - 10 - before these can either be obtained by file transfer or from the tape distribution. In both cases move to the appropriate directory. cd /u1/home/isode If you are using file transfer mechanisms, copy the files isode-uk.tar.z and uk-pilot.tar.z and uncompress and untar the contents. If you have a tape distribution, load the distribution tape cartridge and type the following commands to extract the software from the tape: mt -f /dev/nrst0 rew mt -f /dev/nrst0 fsf 1 tar xf /dev/nrst0 tar xf /dev/nrst0 The software should be easy to build. Type the following: cd ~isode/uk-pilot [If you wish to use non-standard path-names for ETCDIR and SBINDIR, you should edit the config files accordingly now.] build-pilot You will asked the following question: Enter X.25 address of tsapd: [Tsapd is a generic ISODE transport daemon which supports, inter alia, ftam. This tsapd needs to listen on its own address. You should provide your DTE number, usually with a sub-address and/or a PID. For example: 00000511160013 000021000018+PID+03010100 ] You will now be asked: Enter your telex number: [This should be an 8 digit number - 3 digits intenational code plus 5 digits for the national number. The reasons for requiring a telex number are abstruse and should be examined lightly. If you do not have a telex number, you can borrow a bit of someone else's. Email quipu-support@uk.ac.ucl.cs for details of what to do if you are in this situation] The script will now compile the system - it takes about an hour. On completion, type: su [Enter your root password when prompted] install-pilot You will now get several screenfuls of output which may include messages like ***Error Ignored. You can safely - 11 - ignore these too. Now start the tsap daemon. /usr/etc/tsapd -x -r >&/dev/null Exit the super-user shell. exit You need the following command so that the shell will find the binaries that have been created by the scripts that you have run. rehash [Note that the above procedures do not build or install ftam - this can be built separately by the following the instructions in the ISODE READ-ME file. The purpose of the running the tsapd daemon is to allow use of ISODE's isode- test program.] Now try and run the isode-test program to verify that ISODE is basically correctly installed. isode-test where is the name of the host excluding all the domain parts. If this works satisfactorily (this should be readily apparent from the diagnostics), you should be confident that ISODE is correctly installed. 9. Configuring the Directory A simple test should be performed before proceeding further. You should try to connect to a DSA at UCL using the user interface dish. dish -c giant At this point, you might like to play around for a while with dish ... Eventually even the most stoic will become bored with this and will want to set up their own DSA. It is strongly recommended that you read volume 5 of the ISODE manual before attempting the next stage. cd ~isode/isode*/others/quipu/quipu-db/organisation /usr/etc/ros.quipu -t ./quiputailor & This starts up a default DSA and will display some diagnostics to the screen. When the line DSA c=GB@cn=toucan has started on Internet=127.0.0.1+17003 is displayed (twice in fact!), you should type: dish - 12 - Dish will now try and contact your local DSA over a loop- back connection. Some logging from the DSA will appear on the screen along with a message welcoming you to dish. When you have bound to your local DSA, you will also get a dish prompt, thus: Dish -> You should now type quit Having established that a simple test system works in an albeit limited way, now is the time to set up a proper DSA for your organisation. Type the following: su chown isode /u2/quipu exit cp -r * /u2/quipu/quipu-db cd /u2/quipu/quipu-db/c=GB You now need to modify the EDB file to add in entries for your organisation and your DSA. You must read chapter 13 of volume 5 of the ISODE manual to get the details of how to do this. vi EDB When you think that you have done this correctly, mail the entries you have created to quipu-support@uk.ac.ucl.cs. To create the rest of your directory data, you should replace the o=UCL directory with a directory which reflects your own data. You MUST remove the o=UCL directory. Now you must edit a couple of configuration files. One of the things that you have to configure is the name of your local DSA. Table 13.1 of chapter 13 of volume 5 of the ISODE manual presents a list of suggested names. Select one from the list (or provide your own South American wildlife!) and email quipu-support to confirm that this name is still free for use. vi /usr/etc/quiputailor Modify the variables mydsaname and treedir so that those lines look like the following: mydsaname c=gb@cn=YOURDSANAME treedir /u2/quipu/quipu-db Now edit the dsaptailor file. vi /usr/etc/dsaptailor Modify the first line in the file beginning with the string dsa_address. Change the DSA name to YOURDSANAME and change the DSA address to be exactly the same as that in the presentationAddress attribute in the entry for your DSA. - 13 - To start the DSA, type: /usr/etc/ros.quipu >&/dev/null [If you get problems connecting to the DSA, try starting the DSA without redirecting the logging to /dev/null.] Now type: dish and you should be able to connect to your DSA and see your data. In addition, the DSA should start whenever you reboot the machine. You are nearly there!! You must now run one final script which sets up your network preferences. It excludes Internet and gives Janet preference over PSS. cd ~isode/uk-pilot ts_config When quipu-support confirms that your entries have been registered, you should make a further amendment to the file /usr/etc/quiputailor. Change the value on the line starting with the word update from off to on.