NETLIB Installation Guide February, 2002 This manual describes the installation of NETLIB, a library for writing TCP/IP-based network applications. Revision/Update Information: This an updated manual. Operating System and Version: VAX/VMS V5.2 or later; OpenVMS Alpha V1.5 or later Software Version: NETLIB V2.3D Matthew Madison MadGoat Software ________________________ 04 February 2002 Permission is granted to copy and redistribute this document for no commercial gain. The information in this document is subject to change without notice and should not be construed as a commitment by the author. The author assumes no responsibility for any errors that may appear in this document. DISCLAIMER: The author, the author's employer, and MadGoat Software make no representations or warranties with respect to the contents hereof and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. AXP, DEC, VAX, VMS, and OpenVMS are trademarks of Digital Equipment Corporation. UNIX is a trademark of Unix System Laboratories, Inc. MultiNet and TCPware are registered trademarks of Process Software Corporation. PathWay is a trademark of Attachmate, Inc. __________ Copyright ©2002 MadGoat Software. All Rights Reserved. _______________________________________________________ Contents _________________________________________________ PREFACE v _______________________________________________________ CHAPTER 1 PREPARING TO INSTALL NETLIB 1-1 _________________________________________________ 1.1 PREREQUISITE SOFTWARE 1-1 _________________________________________________ 1.2 VMSCLUSTER SUPPORT 1-1 _________________________________________________ 1.3 INSTALLATION REQUIREMENTS 1-2 _________________________________________________ 1.4 RELEASE NOTES 1-3 _______________________________________________________ CHAPTER 2 INSTALLING NETLIB SYSTEM-WIDE 2-1 _________________________________________________ 2.1 INVOKING THE INSTALLATION PROCEDURE 2-1 _________________________________________________ 2.2 POST-INSTALLATION STEPS 2-2 _______________________________________________________ CHAPTER 3 INSTALLING NETLIB FOR PERSONAL USE 3-1 _________________________________________________ 3.1 PERSONAL NETLIB RESTRICTION 3-2 iii Contents _______________________________________________________ CHAPTER 4 ON-LINE DOCUMENTATION 4-1 _______________________________________________________ APPENDIX A CMU TCP/IP CONSIDERATIONS A-1 _________________________________________________ A.1 DNS RESOLVER A-1 _________________________________________________ A.2 BYPASSING NAMRES A-2 iv _______________________________________________________ Preface There are several TCP/IP packages available for VMS systems today. Each provides a VMS-style programming interface, using the $QIO system service, and most also provide a "socket" programming library, based on the communications model developed for BSD UNIX. Unfortunately, there is no standard among all of the packages for the $QIO-based programming interface (most, but not all, emulate Digital's, at least to some degree), and the $QIO-based interface is not very easy to use. The socket libraries provided with these packages provide a somewhat easier-to-use programming interface, but don't permit VMS-style asynchronous programming (using ASTs), and generally require at least a re-LINK, and sometimes source modifications, when moving from one vendor's library to another. NETLIB was originally developed to support MadGoat Software's Message Exchange mail package, which needed to support many TCP/IP packages doing VMS- style asynchronous programming. NETLIB provides a consistent, VMS-style interface for TCP/IP-based network programs, operating with all of the currently available TCP/IP packages available today for VMS (with one minor exception). In addition, NETLIB allows for flexibility in in the use of a TCP/IP package, by selecting the vendor-dependent library code at run-time, rather than link-time. __________________________________________________________________ Intended Audience This manual is intended for system managers or users responsible for installing and setting up NETLIB. v Preface __________________________________________________________________ Document Structure This document consists of two chapters. Chapter 1 describes the installation of NETLIB, the network interface library used by NETLIB. Chapter 2 describes the installation and configuration of NETLIB. __________________________________________________________________ Related Documents The NETLIB Programmer's Guide describes how to use NETLIB and provides descriptions of the NETLIB routines. vi _______________________________________________________ 1 Preparing to Install NETLIB This chapter describes the steps that should be taken prior to installing NETLIB. __________________________________________________________________ 1.1 Prerequisite Software NETLIB requires VAX/VMS V5.2 or later, or OpenVMS Alpha V1.5 or later. It supports any of the following TCP/IP packages for VMS: CMU TCP/IP (VAX only) V6.5 or later DEC TCP/IP Services for V2.0 or later VMS PathWay from Attachmate, any version Inc. TCPware from Process any version Software Corporation MultiNet from Process any version Software Corporation The target packages do not have to be installed or running on the system in order for NETLIB to be installed; however, you must be running the target package before any NETLIB-based applications are run. __________________________________________________________________ 1.2 VMScluster Support NETLIB supports all VMScluster configurations. For mixed VAX and Alpha cluster configurations, you must install NETLIB twice, once for VAX and once for Alpha. Different directories must be used for each platform. 1-1 Preparing to Install NETLIB If you are running different TCP/IP packages on different nodes in your cluster, you can still install NETLIB just once (once per platform for mixed VAX/Alpha clusters) and select all of the TCP/IP packages you use for the one installation. Follow the steps described in Section 2.2 to modify the NETLIB startup procedure for selecting the appropriate TCP/IP support on a per-node basis. __________________________________________________________________ 1.3 Installation Requirements NETLIB requires the following resources: o Approximately 3,000 (VAX) or 4,000 (Alpha) free disk blocks on the installation working device (the system disk, or the device specified in the AWD option for VMSINSTAL). o Approximately 1,000 disk blocks after installation on the disk where NETLIB is installed for common files, plus an additional 50 (VAX) or (150) Alpha disk blocks per TCP/IP package selected. o If NETLIB is installed system-wide, you will need 3 (VAX) or 7 (Alpha) global sections and 15 (VAX) or 30 (Alpha) global pages for the common NETLIB transfer vector library, plus 3 (VAX) or 10 (Alpha) global sections and approximately 50 (VAX) or 80 (Alpha) global pages for each TCP/IP-specific library. o Approximately 5 to 20 mintues for installation time, depending on system type and installation media. o If you are running CMU TCP/IP, the SYSGEN parameter MAXBUF must be set to at least 2300. 1-2 Preparing to Install NETLIB __________________________________________________________________ 1.4 Release Notes NETLIB is provided in a distribution kit suitable for installation with VMSINSTAL. The release notes in the A save set of the distribution kit describe installation requirements for NETLIB. You can retrieve the release notes by using OPTIONS N on VMSINSTAL: $ @SYS$UPDATE:VMSINSTAL NETLIB023 load-device OPTIONS N where load-device represents the location of the NETLIB installation kit. 1-3 _______________________________________________________ 2 Installing NETLIB System-wide This chapter describes the NETLIB installation process for a system-wide NETLIB installation. __________________________________________________________________ 2.1 Invoking the Installation Procedure NETLIB is installled using the VMSINSTAL utility: $ @SYS$UPDATE:VMSINSTAL NETLIB023 load-device where load-device represents the location of the NETLIB installation kit. Installation Questions The NETLIB installation procedure will ask you for a device and directory specification for the location where NETLIB should be installed, and will ask you to select the TCP/IP package support you want to install. The procedure attempts to select automatically the appropriate TCP/IP support for your system. You will next be asked to specify a directory into which the NETLIB libraries will be installed. If NETLIB is already installed and started, the installation procedure will provide the current NETLIB directory location as the default answer; otherwise, it will use SYS$COMMON:[SYSLIB] as the default. If the directory you specify does not already exist, it will be created by the installation procedure. After selecting a directory, you will be asked if you want the NETLIB programming support files and documentation installed. If so, you will be asked for a directory into which the documentation will 2-1 Installing NETLIB System-wide be placed (the programming support files go into the NETLIB library directory). Once all questions, the appropriate binaries (VAX or Alpha) are loaded, and the requested libraries are created and moved to the directory you specified. If you elected to install the programming support and/or documentation, those files will be loaded and moved into the appropriate directories. __________________________________________________________________ 2.2 Post-Installation Steps Once NETLIB has been installed, it should be started by invoking its startup command procedure: $ @SYS$STARTUP:NETLIB_STARTUP This should be done from a suitably privileged account. This invocation of NETLIB_STARTUP should also be added to your system startup command procedure. 2-2 _______________________________________________________ 3 Installing NETLIB for Personal Use If you are not a system manager but still want to use NETLIB, you can install a copy of NETLIB for your own personal use. To do this, create a temporary working directory and SET DEFAULT to it: $ CREATE/DIRECTORY [.TEMP] $ SET DEFAULT [.TEMP] Next, unload the contents of the NETLIB save sets into the working directory. All installations require the A save set: $ BACKUP disk:[dir]NETLIB023.A/SAVE [] For VAX systems, you will need the B save set: $ BACKUP disk:[dir]NETLIB023.B/SAVE [] For Alpha systems, you will need the C save set: $ BACKUP disk:[dir]NETLIB023.C/SAVE [] Next, invoke the user-install command procedure: $ @NETLIB_USER_INSTALL Answer the questions from the installation script and the NETLIB files will be created. Once the installation procedure is complete, you can delete the files and the working directory: $ SET DEFAULT [-] $ DELETE [.TEMP]*.*;* $ SET PROTECTION=O:RWED TEMP.DIR $ DELETE TEMP.DIR; If you want to use the programming support files or documentation, use BACKUP to retrieve them from saveset NETLIB023.D. 3-1 Installing NETLIB for Personal Use __________________________________________________________________ 3.1 Personal NETLIB Restriction You cannot use a personal NETLIB with NETLIB-based applications that are installed with privileges. 3-2 _______________________________________________________ 4 On-Line Documentation The NETLIB documentation set is provided in a form suitable for use with the VMS DECwindows Bookreader program (VMS V5.3 and later). To make the NETLIB on- line documentation available automatically through Bookreader, you should add a reference to the directory containing the documentation (if you elected to install those files) to the DECW$BOOK logical name. 4-1 _______________________________________________________ A CMU TCP/IP Considerations All of the TCP/IP packages that NETLIB supports, with the exception of CMU TCP/IP, are already based on the Berkeley socket model for network programming, and all except CMU use the BIND (Berkeley Internet Name Daemon) software for performing domain name resolution. __________________________________________________________________ A.1 DNS Resolver Emulating sockets over CMU TCP/IP is not difficult, but due to the way the CMU name resolver, NAMRES, is implemented, performing BIND-style queries requires some additional setup over the other TCP/IP packages. The list of DNS servers that NAMRES uses is not available to NETLIB, so you must define an additional logical name for NETLIB's DNS_QUERY routine to be used: $ DEFINE NETLIB_NAMESERVERS "x.x.x.x" Where "x.x.x.x" is the dotted-decimal IP address of the name server that DNS_QUERY should use. You may specify more than one nameserver, by defining NETLIB_ NAMESERVERS as a search-list logical name. The logical name should be defined in the system logical name table to be available to all users on the system. A-1 CMU TCP/IP Considerations __________________________________________________________________ A.2 Bypassing NAMRES By default, NETLIB's support for the CMU TCP/IP package uses the native NAMRES for all name and address lookups (routines NETLIB_NAME_TO_ADDRESS, NETLIB_ADDRESS_TO_NAME, and NETLIB_DNS_MX_LOOKUP). However, you can configure NETLIB to bypass NAMRES and use NETLIB's name resolver routines instead by defining the logical name: $ DEFINE NETLIB_BYPASS_CMU_RESOLVER anyvalue The NETLIB_NAMESERVERS logical name must also be defined. If the above logical name is defined, NETLIB will automatically bypass NAMRES and use its own resolver routines for all lookups. Please note that NETLIB's name resolver, unlike NAMRES, does not cache the results it gets (this is typical behavior for BIND-style resolvers). Bypassing NAMRES, therefore, can increase network traffic for DNS lookups. For this reason, when using bypass mode, you should ensure that NETLIB_NAMESERVERS references only name servers that are on your local network. In addition, bypassing NAMRES will cause name lookups to be resolved only through the Domain Name System. Local host table definitions will not be available. A-2