This is rpc-0.9 for Linux.  Together with Linux libc-4.2, it provides
a complete ANSI-C and C++ compatible Remote Procedure Call programming
environment.

Overview
--------

Remote Procedure Calls are a way of doing distributed computing where
functions can call functions on remote systems and the remote system
returns to results over the network.  This package implements ONC RPC
(Open Network Computing Remote Procedure Calls) as first implemented
by Sun Microsystems.  It differs from the other significant RPC
standard called Courier by Xerox.

The most significant and widely used application that is based on ONC
RPC is the NFS (Network Filesystem) standard.  NFS is based on RPC and
RPC is, in turn, based on the XDR (External Data Representation)
standard.  Each standard is formalized in an Internetworking RFC.
Because detailed standards exist for NFS, RPC and XDR, it makes them
ideal for use in a non-propietary operating system environment like
Linux.  No non-disclosure agreement or dubious reverse-engineering is
required.

Sun has provided two major freely distributable implementations of ONC
RPC that cover most of the RPC programming environment.  There are two
flavors of RPC programming.  The original and most widely used is
called SunOS 4 style RPC and is based on the BSD socket API.  The
other flavor is called TIRPC (Transport Independent RPC) which is
based on System V release 4.  It might have been better to call it TLI
Dependent RPC because it is based on STREAMS and the Transport Layer
Interface.  Linux uses the BSD socket API version of RPC which is
compatible with SunOS version 4.x.

Installation
------------

This is how I recommend you install it:

Distribution File	Where to Install	Notes
-------------------	------------------	----------------
inetd/inetd		/etc/inetd		RPC-capable version of inetd
lorder/lorder		/usr/bin/lorder		object dependency program
man/man?/*		/usr/man/man?/		C library RPC manpages
portmap/portmap		/etc/portmap		RPC portmapper
portmap/rpc		/usr/etc/inet/rpc	RPC analogue of /etc/services
rpcgen/rpcgen		/usr/bin/rpcgen		RPC program generator
rpcgen-old/orpcgen-old	/usr/bin/orpcgen-old	old RPC program generator
rpcinfo/rpcinfo		/etc/rpcinfo		portmapper query program
rpcsvc/librpcsvc.a	/usr/lib/librpcsvc.a	RPC service library
rpcsvc/*.[xh]		/usr/include/rpcsvc/	RPC service header files
rstat/rstat		/usr/bin/rstat		remote status monitor client
tsort/tsort		/usr/bin/tsort		topological sort utility
*/*.[1-8]*		/usr/man?/		all the other man pages

The rpc file is put in /usr/etc/inet only becuase libc-4.2 expects to
find it there.  Remember to save your rpcsvc directory if you upgrade
your compiler include files.  You don't really need lorder and tsort
for RPC but they are nice to have in general.

There is no need to use /usr/lib/librpclib.a with libc-4.2.  If you
have an old one from a previous RPC release please delete it.  It has
been merged into libc.so.4.2.  Also make sure you are using the
/usr/include/rpc header files from the Linux libc-4.2 distribution.

Be forewarned that there are a few files that have filenames longer
that 14 characters.  However, I don't think it will hurt anything if
they are truncated.

Sorry I didn't write an install script.  You will know your system
better for having done it all by hand.  :-)

Usage
-----

Because this distribution includes an RPC-capable version of inetd, it
is important to start the portmapper before inetd.  Here is an example
fragment from a system bootup script:

# now network interfaces are configured
if [ -f /etc/syslogd ]
then
	echo "Starting syslogd..."
	/etc/syslogd
fi
if [ -f /etc/portmap ]
then
	echo "Starting portmapper..."
	/etc/portmap
fi
if [ -f /etc/inetd ]
then
	echo "Starting inetd..."
	/etc/inetd
fi

Distribution
------------

These sections describe the subdirectories included in this distribution
in alphabetical order.

demo
----

These are some sample remote services to test out the RPC implementation.
You do not need to be connected to a real network to try these examples.
By studying them and modifying them, you will understand the basics of
RPC programming and be able to write your own RPC programs.  I modified
each of the demo programs to use the new rpcgen.

doc
---

These are some technical memos from Sun that were distributed with
sunrpc-4.0 which describe RPC and XDR programming in more detail.
They use the -ms roff macros require groff for formatting.

inetd
-----

This is a version of inetd from bsd-net2 that I modified to be able to
start RPC services.  It works the same way as it does on SunOS.
Warning: I compiled this version to use the configuration file
/etc/inetd.conf, not /usr/etc/inet/inetd.conf.

Here is some examples of the RPC syntax in inetd.conf:

mount/1		dgram	rpc/udp	wait	root	/etc/mountd	mountd
mount/1		stream	rpc/tcp	wait	root	/etc/mountd	mountd
nfs/2/2049	dgram	rpc/udp	wait	root	/etc/nfsd	nfsd
nfs/2/2049	stream	rpc/tcp	wait	root	/etc/nfsd	nfsd

Note the extension of to the SunOS syntax which allows an explicit
specification of the port to start an RPC service on.

I don't recommend using the nfsd examples as its probably better to
leave nfsd running all the time but it does work.  However is is very
convenient for mountd which is not used very often.  You must have the
mountd/nfsd from nfs-server-1.2 to use this feature.  Other RPC
applications will need to be recompiled with the new rpcgen using the
option -I to be able to be started from inetd.  See the rpcgen man
page for more information.

The idea behind starting RPC services from inetd is the same as
the original motivation for inetd.  Using inetd as a super-server
allows systems to provicde services that are infrequently used
without requiring their own permenant daemons.  Instead of a socket,
some memory/swap space and a process slot, they only use a single
socket when they are not in use.

lorder
------

This is a common object file utility I haven't seen
anywhere else with Linux so here is a slightly modified version
from bsd-net2.  It  doesn't have anything in particular to do
with RPC except that it is used to build the rpcscv library.
What lorder does is generate a list of dependencies within
a group of object files.  It is most useful when used with tsort
to generate an ordering of object files that allows the linker
to make a single pass over a library.

man
---

These are the man pages distributed with sunrpc-4.0 for the RPC and
XDR API.  They document the functions available with Linux libc-4.2.

portmap
-------

This program is from the sunrpc-4.0 package.  I have plans to add
local checking but it is still missing from this version.  However, it
does fix the bug of creating lots of zombie processes.

rfc
---

These are the RFC (Request for Comments) internetworking standards
documents directly from NOC (Network Operations Center) for
XDR, RPC and NFS.

rpc++
-----

This is mnl-rpc++-2.3.1 which is a C++ interface to RPC.
I have not used it since it requires that you patch gcc-2.3.3
and I don't have the resources to do that.  However the author
(Micheal Lipp) says he uses Linux now and it works once GCC is
patched so I am including it to advertise it to the Linux
community. The next version of GCC is supposed to fix the
problems so if you are interested in C++ and RPC, take a look
at this package.

rpcgen
------

This is a modifed version of rpcgen from the tirpc (Transport
Independent RPC) package.  The rest of tirpc depends on a STREAMS
implementation so we can't use it with Linux.  However, the rpcgen
from tirpc can generate ANSI-C and C++ compatible code which is very
nice for GCC under Linux.  See the man page for more info.

orpcgen
-------

This is the old rpcgen from the sunrpc-4.0 package.  It generates
K&R style code and so it is unsuitable for use with ANSI-C or C++.
However, it may be useful for compiling standard RPC programs
because the name of the server functions have changed with the
new rpcgen.  This had to happen because they take different
arguments and so can't be declared to have the same name in
the RPC header file when used with ANSI C.

To convert an old-style RPC program to the new ANSI-C compatible
style, change the name of the program_version functions in
the program_proc.c file to to program_version_svc and add
a second argument named svc_req declared as struct svc_req *.
See the demo programs for examples.

rpcinfo
-------

This is rpcinfo from sunrpc-4.0.  No major changes but lots of
warnings have been cleaned up.

rpcsvc
------

This is the /usr/include/rpcsvc directory (which is not included with
libc-4.2) and the /usr/lib/librpcsvc.a library.  I have not tested all
the files but I did try to make all the headers ANSI-C and C++
compatible by using the new rpcgen.

rstat
-----

This is a sample RPC client application that can query the statd
service from remote machines.  If you've ever heard of SunOS
perfmeter, you can understand that rstat uses the same service as
perfmeter does.  I haven't yet ported a Linux version of the
rpc.statd service but perhaps someone can do it as a learning excercise.

tsort
-----

This is tsort from bsd-net2 which is used to topologically sort
the output of lorder when making a library.  The difference
between a topological sort and an ordinary sort is that tsort only
requires a partial ordering of the input.  It is not specifically
related to RPC but is used to build the rpcsvc library.  See the
description of lorder for details.

yp
--

This is a minimal implementation of the NIS (Network Information Service),
formerly known as YP (Yellow Pages).  I have made no attempt to port
it to Linux but have included it for those who are interested in
porting NIS to Linux.  It was written by Theo de Raadt for 386BSD.
I suggest you contact him if you are interested in pursuing this project.

Summary
-------

I have worked on the RPC package because I needed it to support my NFS
implementation for Linux.  However, RPC is a flexible and valuable tool
for the development and implementation of remote services of all
kinds.  For example, it is straightforward to compile the PC-NFS
support daemon pcnfsd which provides authentication and printing
services to DOS based clients.

If you have a problem, mail me a complete description and I will try
to take a look at it.

Rick Sladkey
jrs@world.std.com
