|
|
The RPC protocol provides for the following:
The RPC call message has three unsigned fields:
Program numbers are administered by a central authority (see ``Program number assignment'').
The first implementation of a program will most likely have version number 1. Because most new protocols evolve into better, stable, and mature protocols, a version field of the call message identifies the version of the protocol the caller is using. Version numbers make speaking old and new protocols through the same server process possible.
The procedure number identifies the procedure to be called. These numbers are documented in the specific program's protocol specification. For example, a file service's protocol specification may state that its procedure number 5 is ``read'' and procedure number 12 is ``write.''
Just as remote program protocols may change over several versions, the RPC message protocol itself may change. Therefore, the call message also has in it the RPC version number, which is always equal to 2 for the version of RPC described here.
The reply message to a request message has enough information to distinguish the following error conditions:
Provisions for authentication of caller to service and vice-versa are provided as a part of the RPC protocol. The call message has two authentication fields, the credentials and verifier. The reply message has one authentication field, the response verifier. The RPC protocol specification defines all three fields to be the following opaque type:
enum auth_flavor {
AUTH_NONE = 0,
AUTH_SYS = 1,
AUTH_SHORT = 2,
AUTH_DES = 3
/* and more to be defined */
};
struct opaque_auth {
enum_t oa_flavor; /* style of credentials */
caddr_t oa_base; /* address of more auth stuff */
u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
};
That is, any
opaque_auth
structure is an
auth_flavor
enumeration followed by bytes that are opaque to the RPC protocol
implementation.
The interpretation and semantics of the data contained within the authentication fields is specified by individual, independent authentication protocol specifications. (See ``Authentication protocols'' for definitions of the various authentication protocols.)
If authentication parameters are rejected, the response message contains information stating why they are rejected.
Program numbers are given out in groups of 0x20000000 according to the following chart:
| Program numbers | Description |
|---|---|
| 0 - 1fffffff | Defined by Sun Microsystems® |
| 20000000 - 3fffffff | Defined by user |
| 40000000 - 5fffffff | Transient |
| 60000000 - 7fffffff | Reserved |
| 80000000 - 9fffffff | Reserved |
| a0000000 - bfffffff | Reserved |
| c0000000 - dfffffff | Reserved |
| e0000000 - ffffffff | Reserved |
The second group of numbers is reserved for specific customer applications. This range is intended primarily for debugging new programs.
The third group is reserved for applications that generate program numbers dynamically.
The final groups are reserved for future use, and should not be used.
To register a protocol specification, send a request by electronic mail to
rpc@sun.com,
or write to:
RPC Administrator
Sun Microsystems
2550 Garcia Ave.
Mountain View, CA 94043
Please include a compilable rpcgen .x file describing your protocol. You will be given a unique program number in return.
The RPC program numbers and protocol specifications of standard RPC services can be found in the include files in /usr/include/rpcsvc. These services, however, constitute only a small subset of those that have been registered.
The intended use of this protocol is for calling remote procedures. That is, each call message is matched with a response message. However, the protocol itself is a message-passing protocol with which other (non-RPC) protocols can be implemented. Some of the non-RPC protocols supported by the RPC package are:
Batching allows a client to send an arbitrarily large sequence of call messages to a server; batching typically uses reliable byte stream protocols (like TCP/IP) for its transport. In batching, the client never waits for a reply from the server, and the server does not send replies to batch requests. A sequence of batch calls is usually finished by a non-batch RPC call to flush the pipeline (with positive acknowledgement).
In broadcast RPC-based protocols, the client sends a broadcast packet to the network and waits for numerous replies. Broadcast RPC uses unreliable, packet-based protocols (like UDP/IP) as its transports. Servers that support broadcast protocols only respond when the request is successfully processed, and are silent in the face of errors. Broadcast RPC uses the rpcbind service to achieve its semantics. See ``rpcbind protocol'' for more information.