
<COMMENT>(This file processed with symbol generator:  5-NOV-1994 12:42:41.25.)

<FRONT_MATTER>(NETLIB_INST_1)

<TITLE_PAGE>
<TITLE>(NETLIB Installation Guide)
<ABSTRACT>(November, 1994)
<P>This manual describes the installation of NETLIB, a library for
writing TCP/IP-based network applications.
<ENDABSTRACT>
<REVISION_INFO>(This is a new manual.)
<REVISION_INFO>(Operating System and Version:\VAX/VMS V5.2 or later; 
OpenVMS AXP V1.0 or later)
<REVISION_INFO>(Software Version:\NETLIB V2.0)
<ENDTITLE_PAGE>(Matthew Madison<LINE>MadGoat Software)

<COPYRIGHT_PAGE>
<PRINT_DATE>(17 November 1994)
<p>Permission is granted to copy and redistribute this document for
no commercial gain.
<P>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.
<p><emphasis>(DISCLAIMER:\bold)   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.
<P>AXP, DEC, VAX, VMS, and OpenVMS are trademarks of Digital Equipment Corporation.
<P>UNIX is a trademark of Unix System Laboratories, Inc.
<P>MultiNet is a trademark of TGV, Inc.
<P>TCPware is a trademark of Process Software Corporation.
<P>PathWay is a trademark of The Wollongong Group, Inc.
<COPYRIGHT_DATE>(1994\MadGoat Software.  All Rights Reserved.)
<ENDCOPYRIGHT_PAGE>
<CONTENTS_FILE>
<PREFACE>(\NETLIB_INST_2)
<P>
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 <quote>(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.
<P>
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.
<P>
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.

<head1>(Intended Audience\NETLIB_INST_3)
<p>This manual is intended for system managers or users
responsible for installing and setting up NETLIB.
<head1>(Document Structure\NETLIB_INST_4)
<p>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.

<head1>(Related Documents\NETLIB_INST_5)
<p>The <emphasis>(NETLIB Programmer's Guide) describes how to use NETLIB
and provides descriptions of the NETLIB routines.

<ENDPREFACE>
<ENDFRONT_MATTER>
<CHAPTER>(Preparing to Install NETLIB\NETLIB_INST_6)
<P>
This chapter describes the steps that should be taken prior to installing
NETLIB.

<HEAD1>(Prerequisite Software\NETLIB_INST_11)
<P>
NETLIB requires VAX/VMS V5.2 or later, or any version of OpenVMS AXP.
It supports any of the following TCP/IP packages for VMS:
<table>
<table_setup>(2\30)
<table_row>(CMU TCP/IP\(VAX only) V6.5 or later)
<table_row>(DEC TCP/IP Services for VMS\V2.0 or later)
<table_row>(PathWay from The Wollongong Group\any version)
<table_row>(TCPware from Process Software Corporation\any version)
<table_row>(TGV MultiNet\any version)
<endtable>
<P>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.
<head1>(VMScluster Support\NETLIB_INST_12)
<P>
NETLIB supports all VMScluster configurations.  For mixed VAX and AXP
cluster configurations, you must install NETLIB twice, once for VAX and
once for AXP.  Different directories must be used for each platform.
<P>
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/AXP clusters) and select all of the
TCP/IP packages you use for the one installation.  Follow the steps
described in <reference>(postinstall) to modify the NETLIB startup
procedure for selecting the appropriate TCP/IP support on a per-node
basis.
<head1>(Installation Requirements\NETLIB_INST_13)
<P>NETLIB requires the following resources:
<list>(unnumbered)
<le>Approximately 3,000 (VAX) or 4,000 (AXP) free disk blocks on the
installation working device (the system disk, or the device specified in
the AWD option for VMSINSTAL).
<le>Approximately 1,000 disk blocks after installation on the disk
where NETLIB is installed for common files, plus an additional 50 (VAX) or
(100) AXP disk blocks per TCP/IP package selected.
<le>If NETLIB is installed system-wide, you will need
3 global sections and 14 (VAX) or 112 (AXP) global pages for the
common NETLIB transfer vector library, plus 3 global sections and
approximately 50 (VAX) or 210 (AXP) global pages for each TCP/IP-specific
library.
<le>Approximately 5 to 20 mintues for installation time, depending on
system type and installation media.
<le>If you are running CMU TCP/IP, the SYSGEN parameter MAXBUF must
be set to at least 2300.
<endlist>

<HEAD1>(Release Notes\NETLIB_INST_14)
<p>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:
<interactive>
<s>($ )<u>(@SYS$UPDATE:VMSINSTAL NETLIB020 load-device OPTIONS N)
<endinteractive>
<p>where <emphasis>(load-device) represents the location of the
NETLIB installation kit.

<chapter>(Installing NETLIB System-wide\NETLIB_INST_8)
<P>This chapter describes the NETLIB installation process for a system-wide
NETLIB installation.
<HEAD1>(Invoking the Installation Procedure\NETLIB_INST_15)
<P>NETLIB is installled using the VMSINSTAL utility:
<interactive>
<s>($ )<u>(@SYS$UPDATE:VMSINSTAL NETLIB020 load-device)
<endinteractive>
<p>where <emphasis>(load-device) represents the location of the NETLIB
installation kit.
<SUBHEAD1>(Installation Questions\NETLIB_INST_16)
<p>
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.
<P>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.
<P>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 be
placed (the programming support files go into the NETLIB library directory).
<P>Once all questions, the appropriate binaries (VAX or AXP)
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.

<HEAD1>(Post-Installation Steps\postinstall)
<P>If you have installed NETLIB with support for multiple TCP/IP packages,
you should review the startup command procedure created by the installation
to ensure that the correct TCP/IP support has been selected.  For VMScluster
environments, you should customize the startup procedure to select the
appropriate TCP/IP support for each node in your cluster.
<P>The name of the startup procedure is SYS$STARTUP:NETLIB_STARTUP.COM.
TCP/IP support is selected through the definition of the NETLIB_SHR logical
name.  The translation strings for selecting a TCP/IP package are shown
in <reference>(trstr_table).
<table>(NETLIB_SHR Values\trstr_table)
<table_setup>(2\30)
<table_heads>(Translation String\TCP/IP Package Selected)
<table_row>(NETLIB_DIR:NETLIB_CMU_SHR\CMU TCP/IP)
<table_row>(NETLIB_DIR:NETLIB_MULTINET_SHR\TGV MultiNet)
<table_row>(NETLIB_DIR:NETLIB_PATHWAY_SHR\TWG PathWay)
<table_row>(NETLIB_DIR:NETLIB_TCPWARE_SHR\PSC TCPware)
<table_row>(NETLIB_DIR:NETLIB_UCX_SHR\DEC TCP/IP Services)
<endtable>
<head2>(Starting NETLIB\NETLIB_INST_18)
<p>Once NETLIB has been installed, it should be started by invoking
its startup command procedure:
<interactive>
<s>($ )<u>(@SYS$STARTUP:NETLIB_STARTUP)
<endinteractive>
<p>This should be done from a suitably privileged account.
This invocation of NETLIB_STARTUP should also be added to your
system startup command procedure.

<CHAPTER>(Installing NETLIB for Personal Use\personal_install)
<P>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:
<interactive>
<s>($ )<u>(CREATE/DIRECTORY [.TEMP])
<s>($ )<u>(SET DEFAULT [.TEMP])
<endinteractive>
<p>Next, unload the contents of the NETLIB save sets into the working
directory.  All installations require the A save set:
<interactive>
<s>($ )<U>(BACKUP disk:[dir]NETLIB020.A/SAVE [])
<endinteractive>
<P>For VAX systems, you will need the B save set:
<interactive>
<s>($ )<U>(BACKUP disk:[dir]NETLIB020.B/SAVE [])
<endinteractive>
<P>For AXP systems, you will need the C save set:
<interactive>
<s>($ )<U>(BACKUP disk:[dir]NETLIB020.C/SAVE [])
<endinteractive>
<P>Next, invoke the user-install command procedure:
<interactive>
<S>($ )<U>(@NETLIB_USER_INSTALL)
<endinteractive>
<p>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:
<interactive>
<s>($ )<u>(SET DEFAULT [-])
<s>($ )<u>(DELETE [.TEMP]*.*;*)
<s>($ )<U>(SET PROTECTION=O:RWED TEMP.DIR)
<S>($ )<U>(DELETE TEMP.DIR;)
<ENDINTERACTIVE>
<P>
If you want to use the programming support files or documentation,
use BACKUP to retrieve them from saveset NETLIB020.D.

<head1>(Personal NETLIB Restriction\NETLIB_INST_10)
<p>You cannot use a personal NETLIB with NETLIB-based applications that
are installed with privileges.


<chapter>(On-Line Documentation\online_doc)
<P>
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.

<appendix>(CMU TCP/IP Considerations\cmuip)
<P>
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.
<head1>(DNS Resolver\cmudns)
<P>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:
<interactive>
<S>($ )<U>(DEFINE NETLIB_NAMESERVERS "x.x.x.x")
<ENDINTERACTIVE>
<P>Where <quote>(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.

<head1>(Bypassing NAMRES\bypass)
<p>
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:

<INTERACTIVE>
<S>($ )<U>(DEFINE NETLIB_BYPASS_CMU_RESOLVER anyvalue)
<ENDINTERACTIVE>
<P>The NETLIB_NAMESERVERS logical name <emphasis>(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.
<P>Please note that NETLIB's name resolver, unlike NAMRES, <emphasis>(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.
<P>In addition, bypassing NAMRES will cause name lookups to be resolved
<emphasis>(only) through the Domain Name System.  Local host table
definitions will not be available.
<endappendix>