README for Transport Independent RPC (TIRPC) 91/03/18

This is a source distribution of TIRPC, for release at Connectathon '91.

This package is derived from the RPC library developed for System V, Release
4.  It is directly based on the version of the TIRPC library used with the ONC
RPC Application Toolkit for SunOS.

TIRPC uses the Transport Level Interface (TLI) to access the network.
Applications built with the socket-based RPC library may be ported to TIRPC,
however any direct socket calls (such as calls to getsockname(3n)) will not
work and need to be removed.

The build scripts install the libraries and binaries in /usr/onctk by default.
The destination directory *must* be on a partition that is mounted at boot
time.


This distribution includes the following directories:

        tirpc       The tranport independent RPC library.  Its sub-
		    directories are:
                rpc       - the RPC library itself
                netdir    - the "driver" part of the name-to-address library
                netsel    - network selection routines
		yp-compat - compatability code (object-only)
        n2a         Name-to-address translation routines
        rpcbind     The rpcbind server (formerly portmap)
        rpcinfo     Tool to dump rpcbind's binding tables
        keyserv     Secure RPC support programs
        rpcsvc      RPCL files for various RPC services, including
                        header files and XDR routines
        rpcgen      The RPC protocol compiler
	rpcgen.new  The latest RPC protocol compiler
        services    Servers and clients for these RPC services, currently
                    currently only rstat, the remote CPU state service.
        etc         Sample /etc/netconfig file and the /etc/rpc file
        man         man pages for TIRPC
        doc         TIRPC documentation in nroff/troff -ms format
        demo        Some demonstration RPC programs
	sys         UDP and LODG loadable TLI transports (object-only)


The file etc/netconfig specifies the transports that are available.  The file
in this release only defines TCP, UDP, and loopback transports.  Add any other
transports that you wish to support.  This file *must* be installed as
/etc/netconfig.

PREREQUISITES

TIRPC requires that the SunOS 4.1 TLI optional system software package
be installed and configured in the kernel.

	To check that the TLI package is installed, do the following:
	    ls /usr/include/nettli
	    ls /usr/lib/libnsl.a
        If either of the above fails, then you must install the TLI
	package before proceeding with this process.  See pages 175-185 of the
	SunOS 4.1 System Network and Administration Manual for information
        about how to install optional system software packages.

        To check that the TLI package is configured, do the following:
	    view the configuration file of the active kernel
	    ensure that there are entries for the following:
		pseudo-device tim64
		pseudo-device tirw64
		pseudo-device tcptli32
        If any of the above are missing, then you must configure the TLI
	package before proceeding with this process.

The kernel driver files that implement the TCP TLI transport on SunOS 4.1
have three bugs that limit the usefulness of that transport with TIRPC.  The
bug IDs associated with these bugs are:

        1035527, 1035529, and 1039287.

Because of these bugs, the release requires that the SunOS 4.1 or SunOS 4.1.1
TLI Jumbo Patch be installed.For SunOS 4.1, this is patch 100120-02; for SunOS
4.1.1, this is patch 100199-01.  Contact your Sun Customer Support
representative to obtain these patches.

TIRPC requires that the loadable modules driver be configured in your kernel.

	To check that loadable modules driver is supported, do the following:
	    view the configuration file of the active kernel
	    ensure that there are entries for the following:
		options       VDDRV
		pseudo-device clone
        If either of the above is missing, then you must add these lines
        to your config file and rebuild your kernel before proceeding
        with this process.

TIRPC requires that the SunOS U. S. Encryption Kit, Part # 702-1191-10,
be installed.  The Encryption Kit is not available outside of the United
States;  hence, this distribution of TIRPC cannot be installed outside of the
United States.  (The source code can still be used for reference purposes,
however.)

        To check that the Encryption Kit is installed, do the following:
	    cd /usr/lib
	    nm libc.a | grep 'T _ecb_crypt'
	If there is no output from the above, then you must install the
	Encryption Kit before proceeding with this process.


BUILDING THE LIBRARY

The top-level Makefile has several available targets:

        make
		Builds only the libraries, rpcgen and the documentation.

        make install DESTDIR=/usr/onctk
                Builds and installs the libraries and programs into the named
		DESTDIR.  (Generally, DESTDIR=/usr/onctk.)  The DESTDIR tree
		consists of

		    $DESTDIR/bin
		    $DESTDIR/etc
		    $DESTDIR/include
		    $DESTDIR/include/rpc
		    $DESTDIR/include/rpcsvc
		    $DESTDIR/install
		    $DESTDIR/install/sys
		    $DESTDIR/install/sys/nettli
		    $DESTDIR/install/etc
		    $DESTDIR/install/etc/modules
		    $DESTDIR/lib
		    $DESTDIR/man
		    $DESTDIR/man/man1
		    $DESTDIR/man/man3
		    $DESTDIR/man/man4
		    $DESTDIR/man/man5
		    $DESTDIR/man/man8

        make demo DESTDIR=/usr/onctk
                Builds the demonstration RPC services.  ASSUMES THAT A
		make install WAS PREVIOUSLY DONE into the same DESTDIR.

        make clean
                Removes objects and other temporary files generated during
                a build, but NOT the files installed into DESTDIR.


INSTALLATION

After the TIRPC binaries and libraries are installed in /usr/onctk, a number
of other steps must be taken to complete installation.  These involve
installing certain essential files (such as /etc/netconfig and the loadable
library modules) and modifying /etc/rc.local to start-up rpcbind and other
TIRPC servers.

AUTOMATED INSTALLATION

The (Bourne) shell script "install.onctk" is provided to automate the
installation operations; the script also performs most of the checks outlined
under the heading "PREREQUISITES".

You should read the section "MANUAL INSTALLATION" before running install.onctk
to see what the script will do for you.

To run install.onctk:

	1.  Change to the $DESTDIR/install directory
	2.  Run the install.onctk script, responding to all prompts
	3.  Reboot the system to activate TIRPC.

The (Bourne) shell script "deinstall.onctk" will back out the system
modifications done by "install.onctk".

MANUAL INSTALLATION 

Build and install the RPC programs and libraries in /usr/onctk or an
equivalent directory that is on a partition that is mounted at boot time.
Then perform the following:

    1.  Copy the headers for the loadable TLI drivers into /usr/include (this
	step is optional, but recommended):

            cp $DESTDIR/install/sys/nettli/udp_tli.h \
	       /usr/include/nettli/udp_tli.h
            cp $DESTDIR/install/sys/nettli/udp_tlivar.h \
	       /usr/include/nettli/udp_tlivar.h
            cp $DESTDIR/install/sys/nettli/lodg_tli.h \
	       /usr/include/nettli/lodg_tli.h

    2.  Establish a symbolic link to the TIRPC shared library into /usr/lib
	(This step is not necessary, but recommended):

            ln -s  $DESTDIR/lib/librpc.sa.1.2 /usr/lib
            ln -s  $DESTDIR/lib/librpc.so.1.2 /usr/lib

    3.  Copy the TI driver routines into /etc (This step is required.):

            cp \
	      $DESTDIR/install/etc/modules/udptli_sun4.o \
              /etc/modules/udptli_sun4.o
            cp \
	      $DESTDIR/install/etc/modules/udptli_sun4c.o \
              /etc/modules/udptli_sun4c.o
            cp \
	      $DESTDIR/install/etc/modules/udptli_load.sh \
              /etc/modules/udptli_load.sh
            cp \
	      $DESTDIR/install/etc/modules/lodgtli_sun4.o \
              /etc/modules/lodgtli_sun4.o
            cp \
	      $DESTDIR/install/etc/modules/lodgtli_sun4c.o \
              /etc/modules/lodgtli_sun4c.o
            cp \
	      $DESTDIR/install/etc/modules/lodgtli_load.sh \
              /etc/modules/lodgtli_load.sh

    4.  Update the /etc/rc.local file to initialize TIRPC:

	a.  Add code to load the TI drivers, as follows:

	    Before the line that reads
		"echo -n 'starting rpc and net services:'"
	    insert the following:
		K_ARCH=`arch -k`
		echo 'loading loadable transport drivers:'
		if [ -f /etc/modules/lodgtli_$K_ARCH.o -a \
			-f /etc/modules/lodgtli_load.sh ];
		then
		      modload -entry _lodgtli_init -exec \
			      /etc/modules/lodgtli_load.sh \
		              /etc/modules/lodgtli_$K_ARCH.o;
		fi
		if [ -f /etc/modules/udptli_$K_ARCH.o -a \
			-f /etc/modules/udptli_load.sh ];
		then
		      modload -entry _udptli_init -exec \
			      /etc/modules/udptli_load.sh \
		              /etc/modules/udptli_$K_ARCH.o;
		fi

        b.  Add code to start "rpcbind", if available, rather than "portmap":

	    Replace the line that reads
		"if [ -f /usr/etc/portmap ]; then"
	    With the following:
		if [ -f /usr/onctk/etc/rpcbind ]; then
		     (LD_LIBRARY_PATH=/usr/onctk/lib /usr/onctk/etc/rpcbind)
		     echo -n ' rpcbind'
		     ONCTKLIB=/usr/onctk/lib
		elif [ -f /usr/etc/portmap ]; then
		     ONCTKLIB=

	c.  Add code to start the TIRPC key server:

	    Before the line that reads
		"if { -f /usr/etc/keyserv }; then"
	    Insert the following:
		if [ -f /usr/onctk/etc/keyserv ]; then
		    (LD_LIBRARY_PATH=/usr/onctk/lib /usr/onctk/etc/keyserv)
		    echo -n ' ONC-Toolkit-keyserv'
		fi

	d.  Add code to cache the TIRPC libraries for the link-editor:

	    Replace the line that reads
		"ldconfig; echo "link-editor directory cache""
	    With the following:
		ldconfig $ONCTKLIB; echo "link-editor directory cache"

NOTES ON rpcbind STARTUP

The rpcbind program must be started before any other RPC program can be used.

PLEASE NOTE that rpcbind cannot run if portmap is running.  portmap is the
name of the previous version of rpcbind.  If your system starts portmap,
replace the command that starts it with an equivalent command to start
rpcbind.  All services built with the previous version of the RPC library
which operated with portmap will continue to operate with rpcbind.

