support/rpc/README

   1 RPCSRC 4.0 7/11/89
   2
   3 This distribution contains Sun Microsystem's implementation of the
   4 RPC and XDR protocols and is compatible with 4.2BSD and 4.3BSD.  Also
   5 included is complete documentation, utilities, RPC service
   6 specification files, and demonstration services in the format used by
   7 the RPC protocol compiler (rpcgen).  See WHAT'S NEW below for
   8 details.
   9
  10 NOTE ABOUT SECURE RPC:
  11
  12 This release of RPCSRC contains most of the code needed to implement
  13 Secure RPC (see "DES Authentication" in the RPC Protocol Specification,
  14 doc/rpc.rfc.ms).  Due to legal considerations, we are unable to
  15 distribute an implementation of DES, the Data Encryption Standard, which
  16 Secure RPC requires.  For this reason, all of the files, documentation, and
  17 programs associated with Secure RPC have been placed into a separate
  18 directory, secure_rpc.  The RPC library contained in the main body of this
  19 release *DOES NOT* support Secure RPC.  See secure_rpc/README for more
  20 details.  (A DES library was posted in Volume 18 of comp.sources.unix.)
  21
  22 If you wish to report bugs found in this release, send mail to:
  23
  24 Portable ONC/NFS
  25 Sun Microsystems, Inc
  26 MS 12-33
  27 2550 Garcia Avenue
  28 Mountain View, CA  94043
  29
  30 or send Email to nfsnet@sun.com (the Internet) or sun!nfsnet (Usenet).
  31
  32 ROADMAP
  33
  34 The directory hierarchy is as follows:
  35
  36     demo/       Various demonstration services
  37     demo/dir        Remote directory lister
  38     demo/msg        Remote console message delivery service
  39     demo/sort       Remote sort service
  40
  41     doc/        Documentation for RPC, XDR and NFS in "-ms" format.
  42
  43     etc/        Utilities (rpcinfo and portmap).  portmap must be
  44                 started by root before any other RPC network services are
  45                 used.  SEE BELOW FOR BUGFIX TO 4.3BSD COMPILER.
  46
  47     man/        Manual pages for RPC library, rpcgen, and utilities.
  48
  49     rpc/        The RPC and XDR library.  SEE BELOW
  50                 FOR BUGFIX TO 4.2BSD COMPILER.
  51
  52     rpcgen/     The RPC Language compiler (for .x files)
  53
  54     rpcsvc/     Service definition files for various services and the
  55                 server and client code for the Remote Status service.
  56
  57     secure_rpc/ The files in this directory are used to build a version of
  58                 the RPC library with DES Authentication.  See the README
  59                 file in that directory for more details.
  60
  61 BUILD INSTRUCTIONS
  62
  63 Makefiles can be found in all directories except for man.  The
  64 Makefile in the top directory will cause these others to be invoked
  65 (except for in the doc, man and demo directories), in turn building the
  66 entire release.
  67
  68 WARNING!  THE DEFAULT INSTALLATION PROCEDURES WILL INSTALL FILES
  69 IN /usr/include, /usr/lib, /usr/bin and /etc.
  70
  71 The master RPC include file, rpc/rpc.h, is used by all programs and
  72 routines that use RPC.  It includes other RPC and system include files
  73 needed by the RPC system.  PLEASE NOTE: If your system has NFS, it
  74 may have been based on Sun's NFS Source.  The include files installed
  75 by this package may duplicate include files you will find on your NFS
  76 system.  The RPCSRC 4.0 include files are upwardly compatible to all
  77 NFS Source include files as of the date of this distribution (not
  78 including any new definitions or declarations added by your system
  79 vendor).  HOWEVER: Please read the comments towards the end of
  80 rpc/rpc.h regarding rpc/netdb.h.  You may need to uncomment the
  81 inclusion of that file if the structures it defines are already
  82 defined by your system's include files.
  83
  84 After making any compiler fixes that are needed (see below), at
  85 the top directory, type:
  86
  87     make install
  88
  89 For all installations, the Makefile macro DESTDIR is prepended to the
  90 installation path.  It is defined to be null in the Makefiles, so
  91 installations are relative to root.  (You will probably need root
  92 privileges for installing the files under the default path.)  To
  93 install the files under some other tree (e.g., /usr/local), use the
  94 command:
  95
  96     make install DESTDIR=/usr/local
  97
  98 This will place the include files in /usr/local/usr/include, the RPC
  99 library in /usr/local/usr/lib, rpcgen in /usr/local/usr/bin, and the
 100 utilities in /usr/local/etc.  You'll have to edit the Makefiles or
 101 install the files by hand if you want to do anything other than this
 102 kind of relocation of the installation tree.
 103
 104 The RPC library will be built and installed first.  By default it is
 105 installed in /usr/lib as "librpclib.a".  The directory
 106 /usr/include/rpc will also be created, and several header files will
 107 be installed there.  ALL RPC SERVICES INCLUDE THESE HEADER FILES.
 108
 109 The programs in etc/ link in routines from librpclib.a.  If you change
 110 where it is installed, be sure to edit etc/'s Makefile to reflect this.
 111 These programs are installed in /etc.  PORTMAP MUST BE RUNNING ON
 112 YOUR SYSTEM BEFORE YOU START ANY OTHER RPC SERVICE.
 113
 114 rpcgen is installed in /usr/bin.  This program is required to build
 115 the demonstration services in demo and the rstat client and server in
 116 rpcsvc/.
 117
 118 The rpcsvc/ directory will install its files in the directory
 119 /usr/include/rpcsvc.  The Remote Status service (rstat_svc) will be
 120 compiled and installed in /etc.  If you wish to make this service
 121 available, you should either start this service when needed or have
 122 it started at boot time by invoking it in your /etc/rc.local script.
 123 (Be sure that portmap is started first!)  Sun has modified its
 124 version of inetd to automatically start RPC services.  (Use "make
 125 LIB=" when building rstat on a Sun Workstation.)  The Remote Status
 126 client (rstat) will be installed in /usr/bin.  This program queries
 127 the rstat_svc on a remote host and prints a system status summary
 128 similar to the one printed by "uptime".
 129
 130 The documentation is not built during the "make install" command.
 131 Typing "make" in the doc directory will cause all of the manuals to
 132 be formatted using nroff into a single file.  We have had a report
 133 that certain "troff" equivalents have trouble processing the full
 134 manual.  If you have trouble, try building the manuals individually
 135 (see the Makefile).
 136
 137 The demonstration services in the demo directory are not built by the
 138 top-level "make install" command.  To build these, cd to the demo
 139 directory and enter "make".  The three services will be built.
 140 RPCGEN MUST BE INSTALLED in a path that make can find.  To run the
 141 services, start the portmap program as root and invoke the service
 142 (you probably will want to put it in the background).  rpcinfo can be
 143 used to check that the service succeeded in getting registered with
 144 portmap, and to ping the service (see rpcinfo's man page).  You can
 145 then use the corresponding client program to exercise the service.
 146 To build these services on a Sun workstation, you must prevent the
 147 Makefile from trying to link the RPC library (as these routines are
 148 already a part of Sun's libc).  Use: "make LIB=".
 149
 150 BUGFIX FOR 4.3BSD COMPILER
 151
 152 The use of a 'void *' declaration for one of the arguments in
 153 the reply_proc() procedure in etc/rpcinfo.c will trigger a bug
 154 in the 4.3BSD compiler.  The bug is fixed by the following change to
 155 the compiler file mip/manifest.h:
 156
 157 *** manifest.h.r1.1     Thu Apr 30 13:52:25 1987
 158 --- manifest.h.r1.2     Mon Nov 23 18:58:17 1987
 159 ***************
 160 *** 21,27 ****
 161   /*
 162    * Bogus type values
 163    */
 164 ! #define TNULL PTR             /* pointer to UNDEF */
 165   #define TVOID FTN             /* function returning UNDEF (for void) */
 166
 167   /*
 168 --- 21,27 ----
 169   /*
 170    * Bogus type values
 171    */
 172 ! #define TNULL INCREF(MOETY)   /* pointer to MOETY -- impossible type */
 173   #define TVOID FTN             /* function returning UNDEF (for void) */
 174
 175   /*
 176
 177 If you cannot fix your compiler, change the declaration in reply_proc()
 178 from 'void *' to 'char *'.
 179
 180 BUGFIX FOR 4.2BSD COMPILER
 181
 182 Unpatched 4.2BSD compilers complain about valid C.  You can make old
 183 compilers happy by changing some voids to ints.  However, the fix to
 184 the 4.2 VAX compiler is as follows (to mip/trees.c):
 185
 186 *** trees.c.r1.1        Mon May 11 13:47:58 1987
 187 --- trees.c.r1.2        Wed Jul  2 18:28:52 1986
 188 ***************
 189 *** 1247,1253 ****
 190                 if(o==CAST && mt1==0)return(TYPL+TYMATCH);
 191                 if( mt12 & MDBI ) return( TYPL+LVAL+TYMATCH );
 192                 else if( (mt1&MENU)||(mt2&MENU) ) return( LVAL+NCVT+TYPL+PTMATCH+PUN );
 193 !               else if( mt12 == 0 ) break;
 194                 else if( mt1 & MPTR ) return( LVAL+PTMATCH+PUN );
 195                 else if( mt12 & MPTI ) return( TYPL+LVAL+TYMATCH+PUN );
 196                 break;
 197 --- 1261,1269 ----
 198                 if(o==CAST && mt1==0)return(TYPL+TYMATCH);
 199                 if( mt12 & MDBI ) return( TYPL+LVAL+TYMATCH );
 200                 else if( (mt1&MENU)||(mt2&MENU) ) return( LVAL+NCVT+TYPL+PTMATCH+PUN );
 201 !               /* if right is TVOID and looks like a CALL, is not ok */
 202 !               else if (mt2 == 0 && (p->in.right->in.op == CALL || p->in.right->in.op == UNARY CALL))
 203 !                       break;
 204                 else if( mt1 & MPTR ) return( LVAL+PTMATCH+PUN );
 205                 else if( mt12 & MPTI ) return( TYPL+LVAL+TYMATCH+PUN );
 206                 break;
 207
 208 WHAT'S NEW IN THIS RELEASE: RPCSRC 4.0
 209
 210 The previous release was RPCSRC 3.9.  As with all previous releases,
 211 this release is based directly on files from Sun Microsystem's
 212 implementation.
 213
 214 Upgrade from RPCSRC 3.9
 215
 216 1)  RPCSRC 4.0 upgrades RPCSRC 3.9.  Improvements from SunOS 4.0 have
 217     been integrated into this release.
 218
 219 Secure RPC (in the secure_rpc/ directory)
 220
 221 2)  DES Authentication routines and programs are provided.
 222 3)  A new manual, "Secure NFS" is provided, which describes Secure RPC
 223     and Secure NFS.
 224 4)  Skeleton routines and manual pages are provided which describe the
 225     DES encryption procedures required by Secure RPC.  HOWEVER, NO DES
 226     ROUTINE IS PROVIDED.
 227
 228 New Functionality
 229
 230 5)  rpcinfo can now be used to de-register services from the portmapper
 231     which may have terminated abnormally.
 232 6)  A new client, rstat, is provided which queries the rstat_svc and
 233     prints a status line similar to the one displayed by "uptime".