Using Remote Procedure Calls

Programmers who write RPC routines usually make this layer available to others by way of a simple C language front end that entirely hides the networking.

At this level, a program can simply make a call to rnusers(), a C routine that returns the number of users on a remote machine. Users are not explicitly aware of using RPC - they simply call a procedure, just as they would call malloc().

The first two of these are the most fundamental: registerrpc() obtains a unique system-wide procedure identification number, and callrpc() actually executes a remote procedure call. At the middle layer, a call to rnusers() is implemented by way of these two routines.

Some of the available RPC service library routines are listed below:

Other RPC services, such as ether(), mount(), and spray(), are not available to the C programmer as library routines. They do, however, have RPC program numbers (which are discussed in the next section), so they can be invoked with callrpc(). Most of the other RPC services also have compilable rpcgen(1) protocol description files.

#include <stdio.h> 
#include <rpc.h> 
/* #include <rusers.h> /* not included with RPC/XDR */
#define RUSERSPROG 10002
#define RUSERSVERS 2
#define RUSERPROC-NUM 1
main(argc, argv) 
    int argc; char **argv; 
{ 
    unsigned long nusers; 
    int stat; 
    if (argc != 2) 
    { 
        fprintf(stderr, "usage: (char) nusers hostname\n"); 
        exit(-1); 
    } 
    if (stat = callrpc(argv[1], RUSERSPROG, RUSERSVERS, RUSERSPROC_NUM, 
                       xdr_void, 0, xdr_u_long, &nusers) != 0) 
       {
           clnt_perrno(stat); 
           exit(1); 
       } 
    printf("%d users on %s\n", nusers, argv[1]); 
    exit(0); 
}

• The program number specifies a group of related remote procedures, each of which has a different procedure number.

• Each program also has a version number, so when a minor change is made to a remote service, a new program number does not have to be assigned.

• Whenever a new procedure is added to a program, it is also given an identifying number.

When you want to call a procedure to find the number of remote users, you look up the appropriate program, version, and procedure numbers in a manual, just as you look up the name of a memory allocator when you want to allocate memory.

If callrpc() completes successfully, it returns zero; otherwise it returns a nonzero value. The return codes (cast into an integer) are found in clnt.h.

Since data types may be represented differently on different machines, callrpc() needs both the type of the RPC argument, as well as a pointer to the argument itself (and similarly for the result).

For RUSERSPROC_NUM, the return value is an unsigned long so callrpc() has xdr_u_long() as its first return parameter, which says that the result is of type unsigned long and &nusers is its second return parameter, which is a pointer to where the long result is placed. Since RUSERSPROC_NUM takes no argument, the argument parameter of callrpc() is xdr_void().

char * 
nuser(indata) 
    char *indata; 
{ 
    unsigned long nusers; 

    .
    .  Code here to compute the number of users 
    .  and place result in variable nusers. 
    .
    return((char *)&nusers); 
}

It takes one argument: a pointer to the input of the remote procedure call (ignored in the example), and it returns a pointer to the result.

Only the UDP transport mechanism can use registerrpc(); thus, it is always safe in conjunction with calls generated by callrpc().

To register a protocol specification, or to obtain a complete list of registered programs, send a request by network mail to rpc@sun.com, or write to:

RPC Administrator
Sun Microsystems
2550 Garcia Avenue
Mountain View, CA 94043

When registering a protocol specification, please include a compilable rpcgen ".x" file describing your protocol. You are given a unique program number in return. The RPC program numbers and protocol specifications of standard Sun RPC services can be found in the include files in /usr/include/rpcsvc on most UNIX machines. These services, however, constitute only a small subset of those that have been registered.

struct finalexample 
{ 
    char *string; 
    struct simple *simplep; 
} finalexample; 
xdr_finalexample(xdrsp, finalp) 
    XDR *xdrsp; 
    struct finalexample *finalp; 
{ 
    if (!xdr_string(xdrsp, &finalp->string, MAXSTRLEN)) 
          return (0); 
    if (!xdr_reference(xdrsp, &finalp->simplep, 
                      sizeof(struct simple), xdr_simple); 
          return (0); 
    return (1); 
} 

There are several occasions when you may need to use lower layers of RPC:

• Procedure NULLPROC (currently zero) returns with no results. This can be used as a simple test to detect if a remote program is running.

• There is a check for invalid procedure numbers. If one is detected, svcerr_noproc is called to handle the error.

The user service routine serializes the results and returns them to the RPC caller via svc_sendreply. Its first argument is the SVCXPRT handle, the second is the XDR routine, and the third is a pointer to the data to be returned.

xdr_chararr1(xdrsp, chararr) 
    XDR *xdrsp; 
    char chararr[]; 
{ 
    char *p; 
    int len;
    p = chararr; 
    len = SIZE; 
    return (xdr_bytes(xdrsp, &p, &len, SIZE)); 
} 

If space has already been allocated in chararr, it can be called from a server like this:

char chararr[SIZE];
svc_getargs(transp, xdr_chararr1, chararr); 

If you want XDR to do the allocation, you would have to rewrite the routine like this:

xdr_chararr2(xdrsp, chararrp) 
    XDR *xdrsp; 
    char **chararrp; 
{ 
    int len; 
    len = SIZE; 
    return (xdr_bytes(xdrsp, charrarrp, &len, SIZE)); 
} 

Then the RPC call might look like this:

char *arrptr;
arrptr = NULL; 
svc_getargs(transp, xdr_chararr2, &arrptr); 
/* Use the result here */ 
svc_freeargs(transp, xdr_chararr2, &arrptr); 

After being used, the character array can be freed with svc_freeargs. svc_freeargs does not attempt to free any memory if the variable indicating it is NULL.

When building simple examples like those in this section, a user does not have to worry about the three modes. See RFC 1014 for examples of more sophisticated XDR routines that determine which of the three modes they are in and adjust their behavior accordingly.

#include <stdio.h> 
#include <rpc.h> 
#include <utmp.h> 
#include <netdb.h> 
#define RUSERSPROG 10002
#define RUSERSVERS 2
#define RUSERSPROC-NUM 1
main(argc, argv) 
    int argc; char **argv; 
{ 
    struct hostent *hp; 
    struct timeval pertry_timeout, total_timeout; 
    struct sockaddr_in server_addr; 
    int sock = RPC_ANYSOCK; 
    register CLIENT *client; 
    enum clnt_stat clnt_stat; 
    unsigned long nusers; 
    if (argc != 2) 
    { 
        fprintf(stderr, "usage: nusers hostname\n"); 
        exit(-1); 
    } 
    if ((hp = gethostbyname(argv[1])) == NULL) 
    { 
        fprintf(stderr, "can't get addr for %s\n",argv[1]); 
        exit(-1); 
    } 
    pertry_timeout.tv_sec = 3; 
    pertry_timeout.tv_usec = 0; 
    bcopy(hp->h_addr, (caddr_t)&server_addr.sin_addr, hp->h_length); 
    server_addr.sin_family = AF_INET; 
    server_addr.sin_port = 0; 
    if ((client = clntudp_create(&server_addr, RUSERSPROG, 
                                 RUSERSVERS, pertry_timeout, &sock)) == NULL) 
        { 
            clnt_pcreateerror("clntudp_create"); 
            exit(-1); 
        } 
    total_timeout.tv_sec = 20; 
    total_timeout.tv_usec = 0; 
    clnt_stat = clnt_call(client, RUSERSPROC_NUM, xdr_void, 
                          0, xdr_u_long, (char*)&nusers, total_timeout); 
    if (clnt_stat != RPC_SUCCESS) 
    { 
        clnt_perror(client, "rpc"); 
        exit(-1); 
    } 
    clnt_destroy(client); 
    close(sock); 
    exit(0); 
} 

The CLIENT pointer is encoded with the transport mechanism. The callrpc() routine uses UDP, thus it calls clntudp_create to get a CLIENT pointer. To get Transmission Control Protocol (TCP), you use clnttcp_create.

Thus, the number of tries is the clnt_call() timeout divided by the clntudp_create() timeout.

If the socket was opened by the user, it stays open. This makes it possible, in cases where multiple client handles are using the same socket, to destroy one handle without closing the socket that other handles are using.

clnttcp_create(&server_addr, prognum, versnum, &sock, inputsize, outputsize); 

transp = svctcp_create(RPC_ANYSOCK, 0, 0); 

The last two arguments to svctcp_create are send and receive sizes, respectively. If 0 is specified for either of these, the system chooses a reasonable default.

You cannot broadcast RPC without the portmapper. Here are the main differences between broadcast RPC and normal RPC calls:

• Normal RPC expects one answer, whereas broadcast RPC expects many answers (one or more answer from each responding machine).

• Broadcast RPC can only be supported by packet-oriented (connectionless) transport protocols like UDP/IP.

• The implementation of broadcast RPC treats all unsuccessful responses as garbage by filtering them out. Thus, if there is a version mismatch between the broadcaster and a remote service, the user of broadcast RPC never knows.

• All broadcast messages are sent to the portmap port. Thus, only services that register themselves with their portmapper are accessible via the broadcast RPC mechanism.

• Broadcast requests are limited in size to the Maximum Transfer Unit (MTU) of the local network. For Ethernet, the MTU is 1500 bytes.

• Each RPC call in the pipeline requires no response from the server, and the server does not send a response message; and

• The pipeline of calls is transported on a reliable byte stream transport such as TCP/IP.

Since the server does not respond to every call, the client can generate new calls in parallel with the server executing previous calls. Furthermore, the TCP/IP implementation can buffer up many call messages, and send them to the server in one write system call. This overlapped execution greatly decreases the interprocess communication overhead of the client and server processes, as well as the total elapsed time of a series of calls.

Since the batched calls are buffered, the client should eventually do a nonbatched call to flush the pipeline.

Here is an example of batching. Assume a string rendering service (like a window system) has two similar calls: one renders a string and returns void results, while the other renders a string and remains silent. The service (using the TCP/IP transport) may look like this:

#include <stdio.h>
#include <rpc.h>
void windowdispatch();
main() 
{ 
    SVCXPRT *transp;
    transp = svctcp_create(RPC_ANYSOCK, 0, 0); 
    if (transp == NULL)
    { 
        fprintf(stderr, "can't create an RPC server\n");
        exit(1); 
    } 
    pmap_unset(WINDOWPROG, WINDOWVERS); 
    if (!svc_register(transp, WINDOWPROG, WINDOWVERS,                       windowdispatch, IPPROTO_)) 
    { 
        fprintf(stderr, "can't register WINDOW service\n");
        exit(1); 
    } 
    svc_run();                  /* Never returns */ 
    fprintf(stderr, "should never reach this point\n"); 
}
void windowdispatch(rqstp, transp) 
    struct svc_req *rqstp; 
    SVCXPRT *transp; 
{ 
    char *s = NULL; 
    switch (rqstp->rq_proc) 
    { 
        case NULLPROC: 
            if (!svc_sendreply(transp, xdr_void, 0))
                fprintf(stderr, "can't reply to RPC call\n" );
            return;
        case RENDERSTRING: 
            if (!svc_getargs(transp, xdr_wrapstring, &s)) 
            {
                fprintf(stderr, "can't decode arguments\n") ; 
                /* Tell caller about error */
                svcerr_decode(transp); 
                break;
            } 
            . 
            .  Code here to render the strings 
            . 
            if (!svc_sendreply(transp, xdr_void, NULL))
                fprintf(stderr, "can't reply to RPC call\n" );
            break; 
        case RENDERSTRING_BATCHED: 
            if (!svc_getargs(transp, xdr_wrapstring, &s)) 
            {
                fprintf(stderr, "can't decode arguments\n") ; 
                /* We are silent in the face of protocol errors */ 
            break; 
            } 
        .
        .  Code here to render strings, but send no reply! 
        .
        break; 
        default: 
            svcerr_noproc(transp); 
            return; } 
        /* Now free string allocated while decoding arguments */ 
        svc_freeargs(transp, xdr_wrapstring, &s); 
    }
} 

The service could have one procedure that takes the string and a boolean to indicate whether or not the procedure should respond.

Here is an example of a client that uses batching to render multiple strings; the batching is flushed when the client gets a null string (EOF):

#include <stdio.h> 
#include <rpc.h> 
#include <socket.h> 
#include <time.h> 
#include <netdb.h>
main(argc, argv) 
    int argc; 
    char **argv; 
{ 
    struct hostent *hp; 
    struct timeval pertry_timeout, total_timeout; 
    struct sockaddr_in server_addr; 
    int sock = RPC_ANYSOCK; 
    register CLIENT *client; 
    enum clnt_stat clnt_stat; 
    char buf[1000], *s = buf;
    if ((client = clnttcp_create(&server_addr, WINDOWPROG,
                       WINDOWVERS, &sock, 0, 0)) == NULL) 
    {
        error("clnttcp_create"); 
        exit(-1); 
    } 
    total_timeout.tv_sec = 0; 
    total_timeout.tv_usec = 0; 
    while (scanf("%s", s) != EOF) 
    { 
            clnt_stat = clnt_call(client, RENDERSTRING_BATCHED,
                   xdr_wrapstring, &s, NULL, NULL, total_timeout);
            if (clnt_stat != RPC_SUCCESS) 
            { 
                clnt_perror(client, "batched rpc"); 
                exit(-1); 
            } 
    }
    /* Now flush the pipeline */
    total_timeout.tv_sec = 20; 
    clnt_stat = clnt_call(client, NULLPROC, xdr_void, NULL,
        xdr_void, NULL, total_timeout); 
    if (clnt_stat != RPC_SUCCESS) 
    { 
        clnt_perror(client, "rpc"); 
        exit(-1); 
    } 
    clnt_destroy(client); 
    exit(0); 
}

Since the server sends no message, the clients cannot be notified of any of the failures that may occur. Therefore, clients are on their own when it comes to handling errors.

The previous example was completed to render all of the (2000) lines in the UNIX file /etc/termcap. The rendering service did nothing but throw the lines away. The example was run in these configurations, with the indicated results:

Running fscanf on the UNIX file /etc/termcap only requires six seconds. These timings show the advantage of protocols that allow for overlapped execution, though these protocols are often hard to design.

The authentication subsystem of the RPC package is open ended. That is, numerous types of authentication are easy to support.

clnt = clntudp_create(address, prognum, versnum, wait, sockp) 

clnt->serverl_auth = authnone_create()

The RPC client can choose to use UNIX style authentication by setting the field clnt->serverl_auth after creating the RPC client handle using:

clnt->serverl_auth = authunix_create_default()

This causes each RPC call associated with clnt to carry an authentication credentials structure:

.
. UNIX style credentials
.
struct authunix_parms 
{ 
    u_long   aup_time;          /* credentials creation time */ 
    char    *aup_machname;      /* host name where client is */ 
    int      aup_uid;           /* client's UNIX effective uid */
    int      aup_gid;           /* client's current group id */ 
    u_int    aup_len;           /* element length of aup_gids */ 
    int     *aup_gids;          /* array of groups user is in */ 
}; 

These fields are set by authunix_create_default by using the appropriate system calls. Since the RPC user created this new style of authentication, the user is responsible for destroying it with

auth_destroy(clnt->serverl_auth); 

This should be done in all cases to conserve memory.

.
.  Authentication info, mostly opaque to the programmer
.
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 */
}; 

The RPC package makes these guarantees to the service dispatch routine:

• The request's rq_cred is well formed. Thus the service implementor may inspect the request's rq_cred.oa_flavor to determine which style of authentication the caller used. The service implementor may also wish to inspect the other fields of rq_cred if the style is not one of the styles supported by the RPC package.

• The request's rq_clntcred field is either NULL or points to a well formed structure that corresponds to a supported style of authentication credentials. Remember that only UNIX style is currently supported, so (currently) rq_clntcred could be cast to a pointer to an authunix_parms structure. If rq_clntcred is NULL, the service implementor may wish to inspect the other (opaque) fields of rq_cred, in case the service knows about a new type of authentication that the RPC package does not know about.

This remote users service example can be extended so that it computes results for all users except UID 16.

nuser(rqstp, transp) 
    struct svc_req *rqstp; 
    SVCXPRT *transp; 
{ 
    struct authunix_parms *unix_cred; 
    int uid; 
    unsigned long nusers;   /* we don't care about authentication                               for null proc */ 
    if (rqstp->rq_proc == NULLPROC) 
    { 
        if (!svc_sendreply(transp, xdr_void, 0)) 
        {
            fprintf(stderr, "can't reply to RPC call\n" );
            return (1); 
        } 
        return; 
    } 
/* now get the uid */ 
    switch (rqstp->rq_cred.oa_flavor) 
    { 
        case AUTH_UNIX: 
          unix_cred = (struct authunix_parms *)rqstp->rq_clntcred;
          uid = unix_cred->aup_uid; 
          break; 
        case AUTH_NULL: 
        default: 
            svcerr_weakauth(transp); 
            return; 
    } 
    switch (rqstp->rq_proc) 
    { 
        case RUSERSPROC_NUM:   /* make sure caller is allowed 
                                 to call this proc */ 
            if (uid == 16) 
            { 
                svcerr_systemerr(transp); 
                return; 
            } 
            . 
            .  Code here to compute the number of users
            .  and assign it to the variable nusers 
            .
            if (!svc_sendreply(transp, xdr_u_long, &nusers)) 
            {
                fprintf(stderr, "can't reply to RPC call\n" ); 
                return (1); 
            } 
            return; 
        default: 
            svcerr_noproc(transp); 
            return; 
    } 
} 

A few things should be noted:

• It is customary not to check the authentication parameters associated with the NULLPROC (procedure number zero).

• If the authentication parameter's type is not suitable for your service, you should call svcerr_weakauth.

• The service protocol itself should return status for access denied; in the case of the example, the protocol does not have such a status, so the service primitive svcerr_systemerr is called instead.

• The last point underscores the relation between the RPC authentication package and the services; RPC deals only with authentication and not with individual services' access control. The services themselves must implement their own access control policies and reflect these policies as return statuses in their protocols.

For DES authentication to work, the keyserv(8c) daemon must be running on both the server and client machines. The users on these machines need public keys assigned by the network administrator in the publickey(5) database. They also need to have decrypted their secret keys using their login password. This happens automatically when you log in using login(1), or you can do it manually using keylogin(1).

When starting an RPC server from inetd, the only difference from the usual code is that the service creation routine should be called in this form, since inet passes a socket as file descriptor 0.

transp = svcudp_create(0);       /* For UDP */ 
transp = svctcp_create(0,0,0);   /* For listener tcp sockets */ 
transp = svcfd_create(0,0,0);    /* For connected tcp sockets */ 

Also, svc_register should be called with the final flag as 0, since the program would already be registered by inetd.

svc_register(transp, PROGNUM, VERSNUM, service, 0); 

Remember, if you want to exit from the server process and return control to inet, you need to explicitly exit, since svc_run() never returns.

The format of entries in /etc/inetd.conf for RPC services can be either one of these: