Home

RPC2 User Manual - Carnegie Mellon University

1. break case 4 rc AuthQuit cid if rc AUTHSUCCESS printf Call failed gt s n RPC2_ErrorMsag rc RPC2_Unbind cid break Comp 0 RPC2_ Handle cid int Op rc x SE_ Descriptor sed char cmd 100 buf 100 printf Connection id dgets buf cid atoi buf printf Operation 1 Square 2 Cube 3 Age 4 Exec 5 Quit dgets buf op atoi buf switch op case 1 printf x dgets buf x atoi buf rc CompSquare cid x if rc gt 0 printf x 2 d n rc else printf Call failed gt s n RPC2_ErrorMsg rc break l case 2 printf x dgets buf x atoi buf rc CompCube cid x if rc gt 0 printf x 3 d n rc else printf Call failed gt s n RPC2_ErrorMsg rc break case 3 rc CompAge cid if rc gt 0 printf Age of connection d seconds n rc else printf Call failed gt s n RPC2_ErrorMsg rc break case 4 printf Remote command gets cmd bzero amp sed sizeof sed How I wish C had a with clause like Pascal sed Tag DUMBFTP sed Value DumbFTPD Tag FILEBYNAME sed Value DumbFTPD Filelnfo ByName ProtectionBits 0644 sed Value DumbFTPD TransmissionDirection SERVERTOCLIENT sed Value DumbFTPD ByteQuota 1 strcpy sed Value DumbFTPD Filelnfo ByName LocalFileName tmp result rc CompExec cid cmd amp sed if rc COMPSUCCESS system echo Result of remote e
2. break case 4 rc MakeMulti AuthQuit OP AuthQuit PTR howmany cid Handle AuthQuit NULL if rc RPC2_ SUCCESS printf Call failed gt s n RPC2_ErrorMsg rc break long Handle AuthUserid HowMany cid thishost rpcval name uid int HowMany thishost rpcval uid RPC2_ Handle cid char name printf received reply from connection d n cid thishost if rpcval AUTHSUCCESS printf Id d n uid thishost else if rpcvat AUTHFAILED printf Bogus user name n if returns gt HowMany return 1 wait for all returns else return 0 long Handle AuthUserName HowMany cid thishost rpcval uid bbs int HowMany thishost rpcval uid RPC2_BoundedBsS bbs RPC2_ Handle cid printf received reply from connection d n cid thishost if rpcval AUTHSUCCESS printf Name s n bbs thishost SeqBody else if rpcval AUTHFAILED printf Bogus user id n else printf Call failed gt s n RPC2_ ErrorMsg rpcval if returns gt HowMany return 1 wait for all returns return 0 long Handle AuthUsertnfo HowMany cid thishost rc uid ainfo int HowMany thishost rc uid Authinfo ainfof RPC2_ Handle cid printf received reply from connection d n cid thishost if rc AUTHSUCCESS printf Group d Home S n ainfo thishost Groupid ainfo thishost HomeDir else if rc AUTHFAILED prin
3. The workhorse routine used to make remote calls after establishing a connection The call is sequential and the calling Iwp is blocked until the call completes The associated side effect if any is finished before the call completes The listed completion codes are from the local RPC stub Check the RPC2_ReturnCode fields of the reply and the status fields of SDesc to see what the remote site thought of your request Without an explicit timeout interval the remote site can take as long as it wishes to perform the requested operation and associated side effects The RPC protocol checks periodically to ensure that the remote site is alive if an explicit Patience timeout interval is specified the call must complete within that time 27 RPC2_MultiRPC Make a collection of remote procedure calls Call long RPC2_MultiRPC in long HowMany in RPC2_ Handle ConnHandleListf in RPC2_ PacketBuffer Request in SE_Descriptor SDescList in long UnpackMulti in out ARG_INFO Arginto in struct timeval Patience Parameters HowMany How many servers to contact ConnHandleList l List of HowMany connection handles for the connections on which calls are to be made Request A properly formatted request buffer SDescList List of HowMany side effect descriptors UnpackMulti Pointer to unpacking routine called by RPC2 when each server response as received If RP2Gen is used this will be supplied by MRPC_MakeMulti Otherwise it must
4. name RPC2_ Struct name name name name RPC2_ Byte namef name The client is only responsible for understanding the parameter type interface to the MakeMulti and HandleResult routines and for allocating all necessary storage MRPC_MakeMulti and MRPC__UnpackMulti are included in the RPC2 libraries 104 5 4 1 MultiRPC Call Specifications MRPC_MakeMulti Pack arguments and initialize state for RPC2_MultiRPC Call long MRPC_MakeMulti in long ServerOp in ARG ArgTypesf in long HowMany in RPC2_Handle CIDList in long HandleResult in struct timeval Timeout lt Variable Length Argument List Parameters ServerOp For server routine foo foo OP RP2GEN generated opcode defined in include file Note that subsystems with overlapping routine names may cause problems in a MakeMulti cali Arglypes For server routine foo foo PTR RP2GEN generated array of argument type specifiers A pointer to this array is located in the generated include file foo h HowMany How many servers are being called CIDList Array of connection handles one for each of the servers HandleResult User procedure to be called after each server response Responses are processed as they come in Client can indicate when he has received sufficient responses see below MRPC_MakeMuiti will not return the server responses Timeout User specified timeout Note that the default timeout set in the pc file will not be act
5. CompExec Handle CompQuit int returns define MAXCONNS 10 define dgets p if gets p NULL perror stdin abort allow RPC to get control periodically main int a char buf 100 printf Debug Levei 0 dgets buf RPC2_DebugLevel atoi buf IntRPC while TRUE LWP_DispatchProcess otherwise we get RPC2_DEADs printf Action t New Conn 2 Auth Request 3 Comp Request dgets buf a atoi buf switch a case 1 NewConn continue case 2 Auth Q continue case 3 Comp continue default continue NewConnQ char hname 100 buf 100 int newcid rc RPC2_Hostldent hident RPC2_Portalldent pident RPC2_ Subsysident sident printf Remote host name dgets hident Value Name hident Tag RPC2_HOSTBYNAME printf Subsystem Auth d Comp d AUTHSUBSYSID COMPSUBSYSID dgets buf sident Value Subsysid atoi buf sident Tag RPC2_SUBSYSBYID pident Tag RPC2_PORTALBYINETNUMBER pident Vaiue InetPortNumber htons AUTHPORTAL same as COMPPORTAL re RPC2_Bind RPC2_OPENKIMONO NULL amp hident amp pident amp sident SMARTFTP NULL NULL amp newcid if rc RPC2_SUCCESS printf Binding succeeded this connection id is d n newcid else l printf Binding failed s n RPC2_ErrorMsg rc Auth RPC2_ Handle cid MAXCONNS int op rc uid MAXCONNS howmany i char name 100 buf 100 AuthI
6. routine If the RP2Gen interface is not used the client must supply a pointer to a routine with the specified interface see section 5 4 1 to RPC2_MultiRPC 5 3 3 4 HandieResult HandleResult is a place holder used to refer to the Client supplied handler routine It is called once for each connection by MRPC_UnpackMulti with the newly arrived server reply It can perform as much or as little processing as the client deems necessary and controls the continuation or termination of the MultiRPC call with its return code The argument specifications of this routine are explained in detail in section 5 4 1 9 3 4 Error Cases and Abnormal Behavior The semantics for errors in the MultiRPC case are somewhat different from those in the RPC2 case Since several messages are being transmitted in the same call an error on one connection should not necessarily cause the call to terminate The client does however need to be informed of error states on any of his connections The handler routine will be called at most once for each connection submitted to the MultiRPC call either with an error condition or with the server response No packet will actually be sent on any connection for which an error was detected in the course of processing As mentioned earlier the additional flexibility provided by the client handler routine incurs some risks RPC2 makes no guarantees as to the state of the connections which are not examined because of an abort b
7. 2 35 1 41 2 82 5 63 11 26 1 88 3 75 7 51 15 01 3 75 7 51 15 01 30 03 4 69 9 38 18 77 37 54 22 52 44 16 30 03 59 38 60 06 119 82 75 07 149 94 10 retries 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 94 0 50 0 50 0 59 1 17 0 70 1 44 2 81 5 63 11 26 22 51 43 68 0 94 1 88 3 75 7 50 15 01 30 01 58 91 1 88 3 75 7 50 15 01 30 01 60 03 119 38 2 34 4 69 9 38 18 76 37 52 75 04 149 51 Tabte Il 2 Retry Constants Biot ai 90 to 300 seconds 0 50 secs lower limit 116 117 Appendix Il Implementation Notes Some of these refer to bugs others to restrictions still others to random useful observations These are specific to the current state of the RPC2 implementation and are very likely to change in the near future as refinements are made to RPC2 1 RPC2 runs on Suns Vaxen and the IBM PC RT machines 2 Only one portal in RPC2_ Init 3 Only DumbFTPD currently supported 4 getsubsysbyname is a fake routine It knows about Vice2 FileServer and DumbFTP Server and Vice2 CallBack 5 RPC2__MultiRPC not implemented yet 118 119 Appendix lV Recent Changes This appendix summarizes the differences between the latest release of RPC i e corresponding to this manual and the previous release This is release 7 Version 7 0 The immediately preceding release was 6 Version 6 2 Changes visible to the user are 1 There is a new call RPC2_Enable which you must us
8. 55 57 57 73 73 73 74 77 78 81 81 SUSEESR 99 100 100 100 101 101 101 102 104 Appendix Usage Notes for the ITC Appendix Il Remote Site and Communication Failures Appendix Ill Implementation Notes Appendix IV Recent Changes Appendix V Summary of RPC related Calls 109 111 117 119 121 Preface This document is a programmer s reference manual for RPC2 the ITC remote procedure call package This package is being used at the present time for a variety of distributed applications such as file servers authentication servers and database servers Considerable effort has gone into making this mechanism flexible and robust In particular it works well even under conditions of heavy server load However the package is simple enough to be used by relatively unsophisticated applications Do not let the size of this user manual scare you A tutorial introduction to this manual and procedures to simplify RPC initialization are in preparation Until the tutorial introduction is available the best way to learn RPC2 is as follows 1 Study the example in Chapter 1 This is an actual piece of working code and you should try running the example Read Chapter 4 next This describes the procedural abstraction provided by RP2Gen the stub generator for RPC2 Read Chapter 2 which describes the RPC2 runtime system Some of these calls are not relevant to you if you use RP2Gen Others such as the init
9. 76 6 41 0 50 0 50 0 50 0 50 0 50 0 94 1 883 76 5 92 0 50 0 50 0 50 0 50 0 50 0 50 0 94 1 88 3 75 5 43 0 50 0 50 0 50 0 50 0 50 0 50 0 50 0 94 1 88 3 75 4 93 10 00 20 00 4 29 8 57 17 14 2 00 4 00 8 00 16 00 0 97 1 94 3 87 7 74 15 48 0 50 0 95 1 90 3 81 7 62 15 21 0 50 0 50 0 94 1 89 3 78 7 56 14 83 0 50 0 50 0 50 0 94 1 88 3 76 7 53 14 38 0 50 0 50 0 50 0 50 0 94 1 88 3 76 7 51 13 91 0 50 0 50 0 50 0 50 0 50 0 94 1 88 3 75 7 51 13 42 0 50 0 50 0 50 0 50 0 50 0 50 0 94 1 88 3 75 7 50 12 93 45 secs 15 00 30 00 6 43 12 86 25 71 3 00 6 00 12 00 24 00 1 45 2 90 5 81 11 61 23 23 0 71 1 43 2 86 5 71 11 43 22 86 0 50 0 71 1 42 2 83 5 67 11 34 22 53 0 50 0 50 0 71 1 41 2 82 5 65 11 29 22 12 0 50 0 50 0 50 0 70 1 41 2 82 5 64 11 27 21 66 0 50 0 50 0 50 0 50 0 70 1 41 2 82 5 63 11 26 21 18 0 50 0 50 0 50 0 50 0 50 0 70 1 41 2 81 9 63 11 26 20 69 60 secs 20 00 40 00 8 57 17 14 34 29 4 00 8 00 16 00 32 00 1 94 3 87 7 74 15 48 30 97 0 95 1 90 3 81 7 62 15 24 30 48 0 50 0 94 1 89 3 78 7 56 15 12 30 21 0 50 0 50 0 94 1 88 3 76 7 53 15 06 29 82 0 50 0 50 0 50 0 94 1 88 3 76 7 51 15 03 29 38 0 50 0 50 0 50 0 50 0 94 1 88 3 75 7 51 15 01 28 91 0 50 0 50 0 50 0 50 0 50 0 94 1 88 3 75 7 50 15 01 28 42 Table Il 1 Retry Constants B otal 15 to 60 seconds 0 50 secs lower limit 115 90 s
10. C routine that corresponds to an RPC2 procedure with an initial implicit argument of type RPC2_Handle Upon invocation this argument will be bound to the address of a handle that indicates the address of the 18 caller The ExecuteRequest Routine RP2GEN generates another routine that serves to interpret and execute an RPC2 request The name of this routine is subsystem_name_ExecuteRequest and its header is int subsystem_name_ExecuteRequest cid Request bd RPC2_Handle cid RPC2_PacketBuffer Request SE_Descriptor bd This routine will unmarshall the arguments and call the appropriate interface routine The return value from this routine will be the return value from the interface routine Programming rules for the server and client The client program is responsible for actually making the connection with the server and must pass the connection id as an additional parameter the first on each call to the interface 4 5 External Data Representations This section defines the external data representation used by RP2GEN that is the representation that is sent out over the wire Each item sent on the wire is required to be a multiple of 4 8 bit bytes Items are padded as necessary to achieve this constraint The bytes of an item are numbered 0 through n 1 where n mod 4 0 The bytes are read and written such that byte m always precedes byte m 1 RPC2_Integer An RPC2_integer is a 32 bit item that encodes a
11. Creation time 0 S AuthQuit cid Get rid of user state note that we do not do RPC2_Unbind here because this request itself has to complete The invoking Server LWP therefore checks to see if this connection can be unbound struct Userinfo p RPC2_GetPrivatePointer cid amp p assert p NULL we have a bug then free p RPC2_SetPrivatePointer cid NULL return AUTHSUCCESS S AuthUserld cid userName userld char userName int userld struct passwd pw if pw getpwnam userName NULL return AUTHFAILED userld pw gt pw uid return AUTHSUCCESS S AuthUserName cid userld userName int userld RPC2_BoundedBS userName Struct passwd pw if pw getpwuid userld NULL return AUTHFAILED Strcpy userName gt SeqBody pw gt pw name we hope the buffer is big enough userName gt SeqLen 1 strlen pw gt pw name return AUTHSUCCESS S AuthUserInfo cid userid ulnfo int userid Authinfo ulnfo Struct passwd pw if pw getpwuid userld NULL return AUTHFAILED ulnfo gt Groupid pw gt pw gid strcpy ulnfo gt HomeDir pw gt pw dir return AUTHSUCCESS 7 eee 5 522225 Bodies of Comp RPC routines 22 2 22r222 e228 S CompNewConn cid seType secLevel encType cident RPC2_ Handle cid RPC2__Integer seType secLevel encType RPC2_CountedBS cident struct Userinfo p p struct Userinfo malloc s
12. Integer Userld Returns AUTHSUCCESS or AUTHFAILED AuthUserName IN RPC2_ Integer Userld IN OUT RPC2_BoundedBS Username Returns AUTHSUCCESS or AUTHFAILED AuthUserInfo IN RPC2_ Integer Usertd OUT AuthInfo UInfo Returns AUTHSUCCESS or AUTHFAILED AuthQuit 1 2 2 Comp Subsystem rpc file M Satyanarayanan Information Technology Center Carnegie Mellon University c IBM Corporation November 1985 RPC interface specification for a trivial computational subsystem Finds squares and cubes of given numbers Server Prefix S Subsystem comp define COMPSUBSYSID 200 The subsysid for comp subsystem define COMPSUCCESS 1 define COMPFAILED 2 CompNewConn IN RPC2_ Integer seType INRPC2_integer secLevel IN RPC2_ Integer encType IN RPC2__CountedBS cident NEW CONNECTION CompSquare IN RPC2_Integer X returns square of x CompCube IN RPC2__Integer X returns cube of x CompAge returns the age of this connection in seconds CompExec IN RPC2_ String Command IN OUT SE_ Descriptor Sed Executes a command and ships back the result in a file Returns COMPSUCCESS or COMPFAILED CompQuit 1 3 Server for Auth and Comp Subsystems exserver c Trivial server to demonstrate basic RPC2 functionality Exports two subsystems auth and comp each with a dedicated LWP M Satyanarayanan Information Technology Center Carnegie Mellon University c Copyright IBM Corporation November 1985 static char IBMid c C
13. RPC2__GetRequest amp reafilter amp cid amp reqbuffer NULL NULL NULL NULL lt RPC2_WLIMIT HandleRPCError rc cid if rc auth ExecuteRequest cid reqbuffer lt RPC2_WLIMIT HandleRPCError re cid if RPC2_GetPrivatePointer cid amp pp RPC2_SUCCESS Il pp NULL RPC2_Unbind cid This was almost certainly an AuthQuit Q call _ CompLWP p char p single parameter passed to LWP_CreateProcess RPC2_RequestFilter reafilter RPC2_ PacketBuffer reqbuffer RPC2__Handle cid int rc char pp Set filter to accept comp requests on new or existing connections reqfilter FromWhom ONESUBSYS reqfilter OldOrNew OLDORNEW reqfilter ConnOrSubsys Subsysid COMPSUBSYSID while TRUE cid 0 if rc RPC2_GetRequest amp reafilter amp cid amp reqbuffer NULL NULL NULL NULL lt RPC2_WLIMIT HandleRPCError rc cid if rc comp ExecuteRequest cid reqbuffer lt RPC2_WLIMIT HandieRPCError rc cid pp NULL if RPC2_GetPrivatePointer cid amp pp RPC2_SUCCESS pp NULL RPC2_Unbind cid This was almost certainly an CompQuit call SF eee Se Bodies of Auth RPC routines 2 2 s 22 222 e528 S AuthNewConn cid seType secLevel encType cident RPC2_ Handle cid RPC2_Integer seType secLevel encType RPC2_ CountedBS cldent Struct Userinfo p p struct Userinfo malloc sizeof struct Userlnfo RPC2_ SetPrivatePointer cid p p gt
14. You may also wish to do a higher level check to ensure that the client and server application code are compatible 24 The SecurityLevel parameter determines the degree to which you can trust this connection If RPC2_OPENKIMONDO is specified the connection is not authenticated and no encryption is done on future requests and responses If RPC2_ONLYAUTHENTICATE is specified an authentication handshake is done to ensure that the client and the Server are who they claim to to be the fact that the server can find SharedSecret from Clientident is assumed to be proof of its identity If RPC2_ SECURE is specified the connection is authenticated and all future transmissions on it are encrypted using a _ session key generated during the authentication handshake RPC2_HEADERSONLY is similar to RPC2_SECURE except that only RPC headers are encrypted The kind of encryption used is specified in EncryptionType The remote site must specify an RPC2_GetRequest with an EncryptionTypeMask that includes this encryption type 25 RPC2_MakeRPC Make a remote procedure call with possible side effect Call long RPC2_MakeRPC in RPC2_Handle ConnHandle in RPC2_PacketButfer Request in SE_Descriptor SDesc out RPC2_PacketBuffer Reply in struct timeval Patience in long EnqueueRequest Parameters ConnHandle identifies the connection on which the call is to be made Request A properly formatted request buffer SDesc A side effect descripto
15. a possibly longer sequence of bytes An RPC2_BoundedBS is transmitted as two RPC2_Integer s representing the maximum and current lengths of the byte strings This is followed by the bytes representing the contents of the buffer padded to a multiple of 4 The byte with the lowest address is byte 0 RPC2_EncryptionKey An RPC2_EncryptionKey is used to transmit an encryption key surprise A key is sent as a sequence of RPC2_KEYSIZE bytes padded to a multiple of 4 Element 0 of the array is byte 0 SE_Descriptor Objects of type SE_Descriptor are never transmitted RPC2_ Struct An RPC2_Struct is transmitted as a sequence of items representing its fields The fields are sent in textual order of declaration i e from left to right and top to bottom Each field is sent using recursively its RPC2 representation RPC2_ Enum An RPC2_Enum has the same representation has an RPC2_Integer and the underlying integer used by the compiler is transmitted as the value of an RPC2_Enum Note that in C this underlying value may be specified by the user This is recommended practice Array The total number of bytes transmitted for an array must be a multiple of 4 However the number of 80 bytes sent for each element depends on the type of the element Currently only arrays of RPC2_Byte are defined The elements of such an array are each sent as a single byte no padding with array element n 7 preceding element n 81 5 Mult
16. absence of RPC calls in progress is an orthogonal issue and can be reduced to this issue by generating artificial keepalive RPC calls Ideally the detection of these failures should be independent of the specific RPC call in progress In other words as long as we are sure that communication medium is not broken and that the remote server process is alive we should not care how long it takes to receive the reply to an RPC request At the same time failures should be detected as soon as possible so that suitable recovery actions can be performed The following paragraphs show this goal is achieved in RPC2 When the RPC2 runtime system receives a retry packet for a request it is already working on it responds with a Busy packet There are two constants B and N These constants are set in total RPC2_Init with suitable defaults built in These semantics of these two constants are 1 Communication failure is declared if N successive retries of a packet fail to provoke any kind of response The response may be a reply a Busy packet an acknowledgement if the packet being sent is a reply or an implicit piggy backed acknowledgement 2 Site failure is declared if silence is observed for a total period of time in the range B 2Btotal total to RPC2 does not try to accurately distinguish between site failure and communication failure one may masquerade as the other and a single failure RPC2_DEAD reflects both cases Loosely speakin
17. passwd pw if pw getpwuid userld NULL return AUTHFAILED strcpy userName gt SeqBody pw gt pw name we hope the buffer is big enough userName gt SeqLen 1 strlen pw gt pw name return AUTHSUCCESS S AuthUserlnfo cid userid ulnfo int userld AuthInfo ulnfo struct passwd pw if pw getpwuid userld NULL return AUTHFAILED ulnfo gt Groupld pw gt pw gid strcpy ulnfo gt HomeDir pw gt pw dir return AUTHSUCCESS F 55s222222 2 BodiesofCompRPCroutines 2222525s 2222 S CompNewConn cid seType secLevel encType cident RPC2_ Handle cid RPC2_ Integer seType secLevel encType RPC2_CountedBS cident struct Userinfo p struct Userinfo malloc sizeof struct Userinfo RPC2_SetPrivatePointer cid p p gt Creation time 0 S CompQuit cid Get rid of user state note that we do not do RPC2_Unbind here because this request itself has to complete The invoking Server LWP therefore checks to see if this connection can be unbound struct Userlnfo p RPC2_GetPrivatePointer cid amp p assert p NULL we have a bug then free p RPC2_ SetPrivatePointer cid NULL return O S CompSquare cid x int x return x x S CompCube cid x RPC2__ Handle cid int x return x x x S CompAge cid x RPC2_Handle cid int x struct Userinfo p assert RPC2__GetPrivatePointer cid amp p RPC2_SUCCESS
18. programmer writes his code to make normal calls on the interface Then the client program is linked with ld base client o Irpc2 and the server program with ld base server o Irpc2 The server module provides a routine the ExecuteRequest routine that will decode the parameters of the request and make an appropriate call on the interface The routine is described below in the language interface sections The client module translates calts on the interface to messages that are sent via the RPC2 package The h file contains type definitions that RP2GEN generated from the type definitions in the input file and definitions for the op codes used by RP2GEN This file which is automatically included in the server and client files may be included by any other module that needs access to these types 4 3 Format of the description file In the syntax of a description file below non terminals are represented by italic names and literals are represented by bold strings file pretixes header_line default_timeout deci_or_proc_list prefixes empty prefix prefix prefix prefix Server Prefix string Client Prefix string _ header_line Subsystem subsystem_name subsystem_name string String zero_or_more_ascil_chars default_timeout Timeout id_number empty 75 Gecl_or_proc_list decl_or_proc decl_or_proc decl_or_proc_list decl_or_proc include define typedef procedure_d
19. return time 0 p gt Creation S CompExec cid cmd RPC2_ Handle cid char cmd We should really have a formal of type SE_Descriptor at the end but it is adummy anyway SE_ Descriptor sed char mycmd 100 sprintf mycmd s gt tmp answer 2 gt amp 1 cmd system mycmd _ beware if this takes too long client will get RPC2_DEADI bzero amp sed sizeof sed sed Tag DUMBFTP sed Value DumbFTPD Tag FILEBYNAME How I wish C had a with clause like Pascal sed Value DumbFTPD TransmissionDirection SERVERTOCLIENT sed Value DumbFTPD ByteQuota 1 strcpy sed Value DumbFTPD Filelnfo ByName LocalFileName tmp answer if RPC2__InitSideEffect cid amp sed RPC2_SUCCESS return COMPFAILED if RPC2_ CheckSideEffect cid amp sed SE_ AWAITLOCALSTATUS RPC2_ SUCCESS return COMPFAILED return COMPSUCCESS iopen is a system call created at the ITC put a dummy here for other sites lopen InitRPC int mylpid 1 89 DFTP_Initializer dftpi RPC2_ Portalldent portalid portallist 1 RPC2_ Subsysident subsysid Struct timeval tout assert LWP_InitializeProcessSupport LWP_NORMAL PRIORITY amp mylpid LWP_ SUCCESS portalid Tag RPC2_PORTALBYINETNUMBER portalid Value inetPortNumber htons AUTHPORTAL portallist O amp portalid tout tv sec 240 tout tv usec 0 DFTP_ SetDefaults amp dftpi DFTP_ Activate amp dftpi assert RPC2_Init RPC2_ VE
20. well RPC2_DUPLICATESERVER Your have already exported Subsys RPC2_BADSERVER Subsys is invalid RPC2_FAIL Something else went wrong Sets up internal tables so that when a remote client performs an RPC2_Bind operation specifying this host portal subsystem triple the RPC runtime system will accept it A server may declare itself to be serving more than one subsystem by making more than one RPC2_ Export calls l 30 RPC2_DeExport Stop accepting new connections for one or all subsystems Call long RPC2_DeExport in RPC2_Subsysident Subsys Parameters Subsys Specifies the subsystem to be deexported This is either an integer or a symbolic name that can be translated to the unique integer identifying this subsystem A value of NULL deexports all subsystems Completion Codes RPC2_SUCCESS All went well RPC2_BADSERVER Subsys is not a valid subsystem or has not been previously exported RPC2_FAIL Something else went wrong After this call no new connections for subsystem Subsys will be accepted The subsystem may however be exported again at a later time Note that existing connections are not broken by this call 31 RPC2 GetRequest Wait for an RPC request or a new connection Call long RPC2_GetRequest in RPC2_RequestFilter Filter out RPC2_Handle ConnHandle out RPC2_PacketBuffer Request in struct timeval Patience in long GetKeys in long EncryptionTypeMask in long AuthFail
21. will do the necessary name to port number conversion Support for other kinds of portals such as Unix domain may be available in future Subsys Which of the potentially many subsystems supported by the remote server is desired May be specified as a number or as a name in the latter case the RPC runtime system will do the translation from name to number SideEffectType What kind of side effects are to be associated with this connection The only side effects intially supported are bulk transfers of files identified by type DUMBFTP or SMARTFTP May be 0 if no side effects are ever to be attempted on this connection Clientident Adequate information for the server to uniquely identify this client and to obtain SharedKey Not interpreted by the RPC runtime system Only the GetKeys callback procedure on the server side need understand the format of Clientident May be NULL if SecurityLevel is RPC2_OPENKIMONO 23 SharedSecret An encryption key known by the callback procedure on the server side to be uniquely associated with Clientident Used by the RPC runtime system in the authentication handshakes May be NULL if SecurityLevel is RPC2_ OPENKIMONO ConnHandle An unique integer returned by the call identifying this connection This is not necessarily a small valued integer Completion Codes RPC2 SUCCESS All went well RPC2_NOBINDING The specified host server or subsystem could not be contacted RPC2_WRONGVERSION The client a
22. 2_ErrorMsg rc RPC2_ Unbind cid l if returns gt HowMany return 1 wait for all returns return O we ee ee eee eee ee RPC Initialization and Error handling 2 s 22s 222222eres InitRPC int mylpid 1 Struct timeval t DFTP Initializer dftpi SFTP Initializer sftpi Struct timeval tout assert LWP_InitializeProcessSupport 0 amp mylpid LWP__SUCCESS t tv sec gt t tv usec 0 assert PRE InitPreempt amp t LWP_SUCCESS PRE PreemptMe 96 DFTP SetDefaults amp dftpi dftpi ChunkSize 1024 2K and 4K give much better performance DFTP Activate amp dftpi SFTP SetDefaults amp sftpi SFTP Activate amp sftpi tout tv sec 30 tout tv usec 0 assert RPC2_ Init RPC2_ VERSION 0 NULL 1 1 amp tout RPC2_ SUCCESS iopen 97 5 3 Usage Support for MultiRPC exists both at the language level and at the runtime level The runtime level Support includes the MultiRPC routines themselves along with the associated library routines which perform argument packing and unpacking The language level support consists mainly of the argument descriptor information Supplied by RP2Gen for each subsystem The client may choose to interface directly with the runtime MultiRPC system without taking advantage of the RP2Gen simplifications but the discussion in the following sections assumes the existence of the RP2Gen interface except where expl
23. C calls packet transmissions and packet reception Set it to 1 for tracing Set to zero for stopping tracing The internal circular trace bufter can be printed out by calling RPC2_DumpTrace extern long RPC2_DebugLevel extern long RPC2_Perror extern long RPC2_ Trace FESHHTAAEKS eH EEHRRAREHESES Data Types known to RPGen FHS RARHTHKAAEHEHREHREHETAEHEREEREOEEREE typedef long RPC2_ integer 32 bit 2 s complement representation On other machines an explicit conversion may be needed typedef unsigned long RPC2_Unsigned 32 bits 18 typedef unsigned char RPC2_ Byte A single 8 bit byte typedef RPC2_ Byte RPC2_ ByteSeq A contiguous sequence of bytes In the C implementation this is a pointer RPC2Gen knows how to allocate and transform the pointer values on transmission Beware if you are not dealing via RPC2Gen May be differently represented in other languages typedef RPC2_ ByteSeq RPC2_ String no nulls except last byte A null terminated sequence of characters Identical to the C language string definition typedef struct RPC2_ Integer SeqLen length of SeqBody RPC2_ByteSeq SeqBody no restrictions on contents RPC2__CountedBS A means of transmitting binary data typedef struct RPC2_ Integer MaxSeqLen max size of buffer represented by SeqBody RPC2_ Integer SeqLen l number of interesting bytes in SeqBody RPC2_ByteSeq SeqBody No restrictions on contents RPC2_ BoundedBsS RPC2_BoundeaBsS i
24. C2_integer ReturnCode RPC2_ Unsigned Lamport RPC2_integer Uniquefier RPC2_Integer Spare2 RPC2__Integer Spare3 Header RPC2_ Byte Body 1 RPC2_ PacketBuffer Meaning of Flags field in RPC2 packet header define RPC2_RETRY 0x1 define RPC2_ ENCRYPTED 0x2 Leftmost byte of Flags field is reserved for use by side effect routines This is in addition to the SEFlags field Flags is not encrypted but SEFLAGS is Format of filter used in RPC2_GetRequest typedef struct The first four fields are never encrypted Set by runtime system Set by runtime system 1 indicates unencrypted error packet Set by runtime system Used by runtime system only Everything below here can be encrypted of the portion after the header Set by client unique identifier for this message on this connection set by runtime system odd on packets from client to server even on packets from server to client Values greater than O are Subsystem specitlic set by client Values less than 0 reserved set by runtime system Type of packet determined by Opcode value gt 0 gt request packet Values of RPC2_REPLY gt reply packet RPC2_ACK gt ack packet and so on Bits for use by side effect routines Offset of piggy backed side effect data from the start of Body Subsystem identifier Filled by runtime system Set by server on replies meaningless on request packets For distributed clock mechanism Used only in Init packets t
25. CMU LTC 85 038 RPC2 User Manual M Satyanarayanan Information Technology Center Carnegie Mellon University Schenley Park Pittsburgh PA 15213 NOTE Reference manual only tutorial in preparation Table of Contents Preface 1 Design Concepts 1 1 Introduction 1 2 An Example 1 2 1 Auth Subsystem rpc file 1 2 2 Comp Subsystem rpc file 1 3 Server for Auth and Comp Subsystems 1 4 Client using Auth and Comp Subsystems 2 The RPC2 Runtime System 2 1 Constants Types and Globals from file rpc2 h 2 2 Client related Calls 2 3 Server related RPC Calls 2 4 Miscellaneous Routines 3 Side Effects 3 1 Constants and Globals from file se h 3 2 Adding New Kinds of Side Effects 3 2 1 Notes 4 RP2Gen A Stub Generator for RPC2 4 1 Introduction 4 2 Usage l 4 3 Format of the description file 4 4 The C interface 4 5 External Data Representations S5 MultiRPC 5 1 Design Issues 5 2 An Example 5 2 1 Auth Subsystem rpc file 5 2 2 Comp Subsystem rpc file 5 2 3 Server for Auth and Comp Subsystems 5 2 4 Client using Auth and Comp Subsystems 5 3 Usage 5 3 1 The Client Handler 5 3 2 Flow of Control in MultiRPC 5 3 3 MultiRPC Related Calls 5 3 3 1 RPC2_MultiRPC 5 3 3 2 MRPC_MakeMulti 5 3 3 3 MRPC__UnpackMulti 5 3 3 4 HandleResult 5 3 4 Error Cases and Abnormal Behavior 5 4 C Interface Specification 5 4 1 MultiRPC Call Specifications anh ON AWW O 15 15 22 29 55
26. D if RPC2_CheckSideEffect cid amp sed SE_AWAITLOCALSTATUS RPC2_SUCCESS return COMPFAILED return COMPSUCCESS iopen is a system Call created at the ITC put a dummy here for other sites iopen InitRPC int mylpid 1 DFTP_ Initializer dftpi RPC2_Portalident portalid portallist 1 RPC2_Subsyslident subsysid struct timeval tout assert LWP _InitializeProcessSupport LWP_NORMAL PRIORITY amp mylpid LWP_SUCCESS portalid Tag RPC2_PORTALBYINETNUMBER portalid Vaiue InetPortNumber htons AUTHPORTAL portallist 0 amp portalid tout tv sec 240 tout tv usec 0 DFTP_SetDefaults amp dftpi DFTP_Activate amp dftpi assert RPC2_Init RPC2_ VERSION 0 portallist 1 1 amp tout RPC2_ SUCCESS subsysid Tag RPC2_SUBSYSBYID subsysid Value Subsysid AUTHSUBSYSID assert RPC2_Export amp subsysid RPC2_SUCCESS subsysid Value Subsysid COMPSUBSYSID assert RPC2_Export amp subsysid RPC2_SUCCESS HandleRPCError rCode connld int rCode RPC2_ Handle connld fprintf stderr exserver s n RPC2_ErrorMsg rCode if rCode lt RPC2_FLIMIT amp amp connid 0 RPC2_Unbind connid void DebugOn RPC2_DebugLevel 100 void DebugOff RPC2_DebugLevel 0 10 1 4 Client using Auth and Comp Subsystems exclient c Trivial client to demonstrate basic RPC2 functionality M Satyanarayanan Information Technology Cent
27. It is NOT interpreted by the runtime system and is used to transmit the input and output parameters of an RPC The actual header files are the authoritative source of these definitions and will be more up to date than this manual 2 1 Constants Types and Globals from file rpc2 h M Satyanarayanan Information Technology Center Carnegie Mellon University c Copyright IBM Corporation November 1985 ifndef RPC2 define RPC2 define RPC2_VERSION Version 7 0 Satya 9 April 1986 11 30 This string is used in RPC initialization calls to ensure that the runtime system and the header files are mutually consistent Also passed across on RPC2_Bind for advisory information to other side Changes to this string may cause RPC2_OLDVERSION to be returned on RPC2_Bind s For really minor changes alter RPC2_LastEdit in globals c define RPC2_PROTOVERSION 6 Found as the first 4 bytes of EVERY packet Change this if you change any aspect of the protocol sequence or if you change the packet header or the body formats of the initialization packets Used in inital packet exchange to verify that the client and server speak exactly the same protocol Orthogonal to RPC2_VERSION We need this in the header at the very beginning else we cannot change packet formats in a detectable manner The following constants are used to indicate the security level of RPC connections define RPC2_OPENKIMONO 98 Neither authenticated nor encrypted def
28. It takes the place of the individual client side stub routines generated by RP2Gen In additon to the usual information supplied in an RPC2 call it takes as arguments RP2Gen generated argument and operation descriptors the number of servers to be called and a pointer to a client supplied handler routine see section 5 4 1 for more detailed information Using the argument descriptors MRPC_MakeMulti packs the supplied server arguments into an RPC2 request buffer and creates a data structure containing call specific information and a pointer to the client handler routine It then makes the MultiRPC call and passes the final return code back to the client when the call terminates OUT and IN OUT parameters must be supplied in the form of arrays of pointers to the appropriate argument types The parameter interface specifications are discussed in sectin 5 4 The size of the array is dependent on the number of servers designated by the client For IN OUT parameters it is only necessary to actually fill in a value for the first element of the array although storage must be properly allocated for all of the elements 101 9 3 3 3 MRPC_UnpackMulti MRPC__UnpackMulti is a RPC2 library routine which functions as the other half of MRPC_MakeMulti It unpacks the contents of the response buffer into their appropriate places in the client s arguments and calls the client handler routine It returns with the return code supplied by the client handler
29. ORTAL rc RPC2_Bind RPC2_OPENKIMONO NULL amp hident amp pident amp sident DUMBFTP NULL NULL amp newcid if rc RPC2_SUCCESS printf Binding succeeded this connection id is d n newcid else printf Binding failed s n RPC2_ErrorMsg rc Auth RPC2_ Handle cid int op rc uid char name 100 buf 100 AuthInfo ainfo RPC2_BoundedBsS bbs printf Connection id dgets buf cid atoi buf printf Operation 1 Id 2 Name 3 Info 4 Quit dgets buf op atoi buf switch op case 1 printf Name dgets name rc AuthUserld cid name amp uid if rc AUTHSUCCESS printf Id d n uid else if r AUTHFAILED printf Bogus user name n else printf Call failed gt s n RPC2_ErrorMsg rc break case 2 printt Id dgets buf uid atoi buf bbs MaxSeqLen sizeof name bbs SeqLen 0 bbs SeqBody RPC2_ByteSeq name rc AuthUserName cid uid amp bbs if rc AUTHSUCCESS printf Name s n bbs SeqBody else if rc AUTHFAILED printf Bogus user id n else printf Call failed gt s n RPC2__ErrorMsg rc break case 3 printf Id dgets buf uid atoi buf rc AuthUserInfo cid uid amp ainfo if rc AUTHSUCCESS printf Group d Home s n ainfo Groupid ainfo HomeDinr else if rc AUTHFAILED printf Bogus user id n else printf Call failed gt s n RPC2__ErrorMsg rc
30. PC2_DEAD You were waiting for requests on a specific connection and that site has been deemed dead or unreachable RPC2_FAIL Something irrecoverable happened The call blocks the calling lightweight process until a request is available a new connection is made or until the specified timeout period has elapsed The Filter parameter allows a great deal of flexibility in selecting precisely which calls are acceptable New connections result in a fake request with a body of type RPC2_NewConnection Do not try to do a RPC2_SendResponse to this call All other RPC2_ GetRequest calis should be eventually matched with a corresponding RPC2__SendResponse call The fields of RPC2_NewConnection are self explanatory Note that you must invoke RPC2_Enabie after you have handled the new connection packet for further requests to be visible If you are using RP2Gen this is done for you automatically by the generated code that deals with new connections The callback procedure for key lookup should look like this long GetKeys in Clientident out IdentKey out SessionKey RPC2_CoundedBS Clientident RPC2_EncryptionKey IdentKey RPC2_EncryptionKey SessionKey GetKeys will be called at some point in the authentication handshake It should return O if Clientident is successfully looked up and 1 if the handshake is to be terminated It should fill IdentKey with the key to be used in the handshake and SessionKey with an arbitrary key to be used for the
31. PC2_FreeBuffer Free a packet buffer Call long RPC2_FreeButfer inout RPC2_PacketBufter Buff Parameters Buff Pointer to the buffer to be freed Set to NULL by the call Completion Codes RPC2_SUCCESS Buffer has been freed Buff has been set to NULL RPC2_FAIL Could not free buffer Returns a packet buffer to the internal free list Buff is set to NULL specifically to simplify locating bugs in buffer usage RPC2_ GetPrivatePointer Obtain private data mapping for a connection Call long RPC2_GetPrivatePointer in RPC2_Handle WhichConn out char PrivatePtr Parameters WhichConn Connection whose private data pointer is desired PrivatePtr Set to point to private data Completion Codes RPC2_SUCCESS PrivatePtr now points to the private data associated witH this connection RPC2_FAIL Bogus connection specified Returns a pointer to the private data associated with a connection No attempt is made to validate this pointer 44 RPC2_SetPrivatePointer Set private data mapping for a connection Call long RPC2_SetPrivatePointer in RPC2_Handle WhichConn in char PrivatePtr Parameters WhichConn Connection whose private data pointer is to be set PrivatePtr Pointer to private data Completion Codes RPC2_ SUCCESS Private pointer set for this connection RPC2_FAIL Bogus connection specified Sets the private data pointer associated with a connection No attempt is made to val
32. PC2_String WorkStationName IN RPC2_String VenusName ViceRemoveCaliBack IN ViceFid Fid 4 4 The C Interface This section describes the C interface generated by RP2GEN The following table shows the relationship between RP2GEN parameter declarations and the corrseponding C parameter declarations RPC2 Type C Declaration IN OUT IN OUT RPC2_ Integer long long long RPC2_Unsigned unsigned long unsigned long unsigned long RPC2_ Byte unsigned char unsigned char unsigned char RPC2_ String unsigned char unsigned char unsigned char RPC2_CountedBS RPC2_CountedBS RPC2_CountedBS RPC2_CountedBS RPC2_BoundedBS RPC2_BoundedBsS RPC2_BoundedBS RPC2_BoundedBs RPC2_EncryptionKey RPC2_EncryptionKey RPC2_ EncryptionKey RPC2__EncryptionKey SE_ Descriptor illegal illegal SE_ Descriptor RPC2_Enum name name name name RPC2_ Struct name name name name RPC2_ Byte namef name name name In all cases it is the caller s responsibility to allocate storage for all parameters This means that for IN and IN OUT parameters of a non fixed type it is the callee s responsibility to ensure that the value to be copied back to the caller does not exceed the storage allocated by the callee The caller must call an RPC2 procedure with an initial implicit argument of type RPC2_Handle that indicates the destination address es of the target process es The callee must declare the
33. Parameters Filter A filter specifying which requests are acceptable See description below ConnHandle Specifies the connection on which the request was received Request l Vaiue ignored on entry On return it will point to a buffer holding the response from the client Free this buffer after you are done with it j Patience A timeout interval specifying how long to wait for a request If NULL infinite patience is assumed GetKeys Pointer to a callback procedure to obtain authentication and session keys See description below May be NULL if no secure bindings to this server are to be accepted EncryptionTypeMask A bit mask specifying which types of encryption is supported Binds from clients who request an encryption type not specified in this mask will fail AuthFail Pointer to a callback procedure to be called when an authentication failure occurs See description below May be NULL if server does not care to note such failures Completion Codes RPC2_SUCCESS have a request for you in Request New connections result in a fake request RPC2_TIMEOUT Specified time interval expired RPC2_BADFILTER A nonexistent connection or subsystem was specified in Filter 32 RPC2_SEFAIL1 The associated side effect routine indicated a minor failure Future calls on this connection will still work RPC2_SEFAIL2 The associated side effect routine indicated a serious failure Future calls on this connection will fail too R
34. RPC2_ Integer secLevel INRPC2__Integer encType INRPC2_CountedBS cldent NEW CONNECTION CompSquare IN RPC2_Integer X returns square of x CompCube IN RPC2__ Integer X returns cube of x CompAge returns the age of this connection in seconds CompExec IN RPC2_ String Command IN OUT SE_ Descriptor Sed Executes a command and ships back the result in a tile Returns COMPSUCCESS or COMPFAILED CompQuit 5 2 3 Server for Auth and Comp Subsystems exserver c Trivial server to demonstrate basic RPC2 functionality Exports two subsystems auth and comp each with a dedicated LWP M Satyanarayanan Information Technology Center Carnegie Mellon University c Copyright IBM Corporation November 1985 static char IBMid c Copyright IBM Corporation November 1985 include lt stdio h gt include lt potpourri h gt include lt strings h gt include lt sys signal h gt include lt sys time h gt include lt sys types h gt include lt netinet in h gt include lt pwd h gt include lt Iwp h gt include lt rpc2 h gt include lt se h gt include auth h include comp h This data structure provides per connection info It is created on every new connection and ceases to exist after AuthQuit struct Userinfo int Creation Time at which this connection was created other fields would go here J int NewCLWP AuthLWP CompLWP bodies of LWPs void DebugOn DebugOff si
35. RSION 0 portallist 1 1 amp tout RPC2_SUCCESS subsysid Tag RPC2_SUBSYSBYID subsysid Value Subsysid AUTHSUBSYSID assert RPC2_Export amp subsysid RPC2_SUCCESS subsysid Value Subsysid COMPSUBSYSID assert RPC2_Export amp subsysid RPC2_SUCCESS HandleRPCError rCade connid int rCode RPC2_ Handle connld fprintf stderr exserver s n RPC2_ErrorMsg rCode if rCode lt RPC2_FLIMIT amp amp connid 0 RPC2_Unbind connid void DebugOnQ RPC2_DebugLevel 100 void DebugOff RPC2_DebugLevel 0 9 2 4 Client using Auth and Comp Subsystems exClient c Trivial client to demonstrate RPC2 MultiRPC functionality M Satyanarayanan and E Siegel Information Technology Center Carnegie Mellon University c Copyright IBM Corporation November 1985 static char IBMid c Copyright IBM Corporation November 1985 include lt stdio h gt include lt potpourri h gt include lt strings h gt include lt sys time h gt include lt sys types h gt include lt netinet in h gt include lt pwd h gt include lt iwp h gt include lt rpce2 h gt include lt se h gt include lt preempt h gt include auth h include comp h long Handie AuthUserld Handle AuthUserName long Handle AuthUsert nfo Handle AuthQuit long Handle CompSquare Handle CompCube long Handle CompAge Handie
36. Request in RPC2_Handle ConnHandle inout RPC2_PacketBuffer Request SE_InitSideEffect in RPC2_Handle ConnHandle inout SE_Descriptor SDesc vi 69 70 71 72 104 106 107 SE_CheckSideEffect in RPC2_Handle ConnHandle inout SE_Descriptor SDesc in jong Flags SE_SendResponse in RPC2_Handle ConnHandle in RPC2_PacketBuffer ReplyPtr SE_PrintSEDescriptor in SE_Descriptor SDesc in FILE outFile SE_SetDefaults XXX_Initializer SInit SE_Activate in XXX_Initializer SInit MRPC_MakeMulti in long ServerOp in ARG ArgTypes in long HowMany in RPC2_ Handle CIDList in long HandleResult in struct timeval Timeout Variable Length Argument List MRPC_UnpackMulti in long HowMany in RPC_Handle ConnHandleList in out ARG_INFO Arginfo in RPC_PacketBuffer Response in long rpcval in long thishost HandleResult in long HowMany in RPC2_Handle ConnArray in long WhichHost in long rpcval Variable Length Argument List
37. The dump has been produced You should typically call this routine after calling RPC_DumpTrace 50 RPC2_InitTraceBuffer Set trace buffer size Call long RPC2_InitTraceBuffer in long HowMany Parameters HowMany How many entries the trace buffer shouid have Set it to zero to delete trace buffer Completion Codes RPC2_SUCCESS The trace buffer has been adjusted appropriately Allows you to create and change the trace buffer at runtime All existing trace entries are lost 51 RPC2 DumpTrace Print a trace of recent RPC calls and packets received Call long RPC2_DumpTrace in FILE OutFile in long HowMany Parameters OutFile File on which the trace is to be produced A value of NULL implies stdout HowMany The HowMany most recent trace entries are printed A value of NULL implies as many trace entries as possible Values larger than TraceBufferLength specifed in RPC2_ Init are meaningless Completion Codes RPC2_SUCCESS The requested trace has been produced RPC2_ FAIL The trace buffer had no entries Note that it is not necessary for RPC2_ Trace to be currently set You can collect a trace and defer calling RPC2_DumpTrace until a convenient time This call does not alter the current value of RPC2_ Trace l 52 XXX_SetDefaults Set an SE initializer to its default values Call long XXX_SetDefaults in XXX_Initializer Initializer Parameters initializer Initializer for side effe
38. YSID while TRUE f cid 0 if rc RPC2_GetRequest amp reafilter amp cid amp reqbuffer NULL NULL NULL NULL lt RPC2_WLIMIT HandleRPCError rc cid if rc comp ExecuteRequest cid reqbuffer lt RPC2_WLIMIT HandleRPCError re cid pp NULL if RPC2_GetPrivatePointer cid amp pp RPC2_SUCCESS pp NULL RPC2_Unbind cid This was almost certainly an CompQuit call Te eee 255552 Bodies of AuthRPC routines 222s2s222r22es S AuthNewConn cid seType secLevel encType cident RPC2_ Handle cid RPC2_ Integer seType secLevel encType RPC2__CountedBS cldent Struct Userinfo p p struct Userinfo matloc sizeof struct Userinfo RPC2_ SetPrivatePointer cid p p gt Creation time 0 S AuthQuit cid Get rid of user state note that we do not do RPC2_Unbind here because this request itself has to complete The invoking server LWP therefore checks to see if this connection can be unbound Struct Userinfo p RPC2__GetPrivatePointer cid amp p assert p NULL we have a bug then free p RPC2_SetPrivatePointer cid NULL 87 return AUTHSUCCESS S AuthUserld cid userName userid char userName int userld struct passwd pw if ow getpwnam userName NULL return AUTHFAILED userld pw gt pw uid return AUTHSUCCESS S AuthUserName cid userid userName int userid RPC2_BoundedBS userName Struct
39. ation The following table shows the C type interface between the client routine and MRPC_MakeMulti for all the possible combinations of legal parameter declarations and types In all cases it is the client s responsibility to allocate storage for all parameters just as in the RPC2 case For all types IN parameters are handled the same as in the single MakeRPC case For OUT and IN OUT parameters arrays of pointers to parameters must be supplied in order to hold the multiple server responses The array for each parameter must contain the same number of items as the number of servers contacted and they must be filled sequentially starting from element zero For all IN OUT parameters except for SE_Descriptors only the first element of the array need be filled in For SE_Descriptors all elements must be filled in The following table should be consulted for specific formats 103 RPC2 Type C Declaration an gt RPC2_ Integer long long long RPC2_Unsigned unsigned long unsigned long unsigned long RPC2_ Byte unsigned char unsigned char unsigned char f RPC2_ String unsigned char unsigned char unsigned char RPC2_CountedBS RPC2_CountedBS RPC2_CountedBs RPC2_CountedBS RPC2_BoundedBS RPC2_BoundedBsS RPC2_BoundedBS RPC2_BoundedBS RPC2__EncryptionKey RPC2_EncryptionKey RPC2_EncryptionKey RPC2_EncryptionKey SE_ Descriptor illegal illegal SE_ Descriptor RPC2_Enum name name name
40. be NULL x if rc RPC2_SUCCESS printf MakeMulti call failed gt s n RPC2_ErrorMsg rc break case 3 rc MakeMulti CompAge OP CompAge PTR howmany cid Handle CompAge NULL if rc RPC2_ SUCCESS printf MakeMulti call failed gt S n RPC2_ErrorMsg rc break case 4 printf Remote command gets cmd for i 0 i lt howmany i bzero amp sed i sizeof sed How I wish C had a with clause like Pascal sed i Tag SMARTFTP sed i Value DumbFTPD Tag FILEBYNAME sed i Value DumbFTPD Filelnfo ByName ProtectionBits 0644 sed i Vaiue DumbFTPD TransmissionDirection SERVERTOCLIENT sed i Value DumbFTPD ByteQuota 1 Sprintt fname tmp result d cid iBag filename with connection id strcpy sed i Value DumbFTPD FileInfo ByName LocalFileName fname rc MakeMuiti CompExec OP CompExec PTR howmany cid Handie CompExec NULL cmd sed if rc RPC2_SUCCESS printf MakeMulti call failed gt S n RPC2_ErrorMsg rc break case 5 rc MakeMulti CompQuit OP CompQuit PTR howmany cid Handle CompQuit NULL long Handle CompSquare HowMany cid thishost re x int HowMany thishost rc x RPC2_ Handle cid printf received reply from connection d n cid thishost if rc 0 printf x 2 d n rc else printf Call failed gt s n RPC2_ErrorMsg rc if returns gt HowMany return 1 wait for all re
41. be supplied by the client Arginfo A pointer to a structure containing argument information This structure is not examined by RPC2 it is passed untouched to UnpackMulti If RP2Gen is used this structure will be supplied by MRPC_MakeMulti Otherwise it can be used to pass any structure desired by the client or supplied as NULL Patience Maximum time to wait for remote sites to respond A NULL pointer indicates infinite patience as long as RPC2 believes that the server is alive Note that this timeout value is orthogonal to the RPC2 internal timeout for determining connection death Completion Codes RPC2_SUCCESS All servers returned successfully or all servers until client initiated abort returned successfully Individual server response information is supplied via UnpackMulti to the user handler routine supplied in the Arginfo structure RPC2_TIMEOUT The user specified timeout expired before all the servers responded 28 RPC2_FAIL Something other than SUCCESS or TIMEOUT occurred More detailed information is supplied via UnpackMulti to the user handier routine supplied in the Arginfo structure Logically identical to iterating through ConnHandleList and making RPC2_MakeRPC calls to each specified connection using Request as the request block but this call will be considerably faster than explicit iteration The calling lightweight process blocks until either the client requests that the call abort or one of the following is true ab
42. cal and remote status will be returned Completion Codes RPC2_SUCCESS The requested status fields have been made available RPC2_NOTSERVER No side effect is ongoing on ConnHandie RPC2_SEFAIL1 The associated side effect routine indicated a nonfatal failure Future calls on this connection will work RPC2_SEFAIL2 The associated side effect routine indicated a serious failure Future calls on this connection will fail too RPC2_ FAIL Other assorted calamities Checks the status of a previously initiated side effect This is a potentially blocking call depending on the specified flags 38 2 4 Miscellaneous Routines RPC2_init Perform runtime system initialization Call long RPC2_Init in char Versionlid in long Options in RPC2_ Portalldent PortalList in long HowManyPortals in long RetryCount in struct timeval KeepAliveinterval Parameters Versionid Set this to the constant RPC2_VERSION The current value of this string constant must be identical to the value at the time the client runtime system was compiled Options Right now there are no options PortalList An array of unique network addresses within this machine on which requests can be listened for and to which responses to outgoing calls can be made In the internet domain this translates into a port number or a Symbolic name that can be mapped to a port number You need to specify this parameter even if you are only going to be a cli
43. ct XXX which you wish to set to default values Completion Codes RPC2_SUCCESS Each side effect type XXX defines an initialization structure type XXX_Initializer and an initialization routine XXX_SetDefaults A typical initialization sequence consists of the following for each side effect XXX that you care about 1 declare a local variable of type XXX_Initializer 2 call XXX_SetDefaults with this local variable as argument 3 selectively modify those initial values you care about in the local variable and 4 call XXX_Activate with this local variable as argument Finally call RPC2_ Init This allows you to selectively set parameters of XXX without having to know the proper values for all of the possible parameters Alas if only C allowed initialization in type declarations this routine would be unnecessary XXX Activate Activates a side effect type and initializes it Call long XXX_Activate in XXX_Initializer Initializer Parameters initializer Initializer for side effect XXX Completion Codes RPC2_SUCCESS Activates side effect XXX Code corresponding to this side effect will not be linked in otherwise See comment for XXX_SetDefaults for further details 55 3 Side Effects 3 1 Constants and Globals from file se h M Satyanarayanan Information Technology Center Carnegie Mellon University c Copyright IBM Corporation November 1985 ifndef SE define SE st
44. duration of this connection You may of course make SessionKey the same as IdentKey The callback procedure for noting authentication failure should look like this long AuthFail in Clientident in EncrType in PeerHost in PeerPortal RPC2_CoundeaBS Clientident RPC2_iInteger EncryType RPC2_Hostldent PeerHost RPC2_Portalldent PeerPortal AuthFail will be called after an RPC2_NOTAUTHENTICATED packet has been sent to the client The 33 parameters give information about the client who was trying to authenticate himself the type of encryption requested and the site from which the RPC2__Bind was attempted The callback procedure will typically record this in a log file somewhere 34 RPC2_Enable Allow servicing of requests ona new connection Call long RPC2_Enable in RPC2_Handle ConnHandle Parameters ConnHandle Which connection is to be enabled Completion Codes RPC2_SUCCESS Enabled the connection RPC2_NOCONNECTION A bogus connection was specified Typically invoked by the user at the end of his NewConnection routine after setting up his higher level data structures appropriately Until a connection is enabled RPC2 guarantees that no requests on that connection will be returned in a RPC2_ GetRequest call Such a request from a client will however be held and responded to with RPC2_ BUSY signals until the connection is enabled This call is present primarily to avoid race hazards in higher le
45. e The currently supported machines are Suns Vaxes and the IBM PC RT The directory cmu itc nfs release rpc2 contains a copy of the sources used to build the current version of RPC2 Use this in conjunction with dbx or if you just wish to examine the source corresponding to the released version The sources of the immediately preceding released version of RPC2 are in cmu itc nfs oldv rpc2 Compile thus NFS cmu itc nfs cc g IS NFS include lt lt your files gt gt NFS lib librpc2 a NFS lib Iwp o NFS lib timer o NFS lib iomgr o o lt lt output file gt gt Stack checking is possible Refer to the LWP manual for details The following external variables may be set for debugging RPC2_DebugLevel values of 0 1 10 and 100 are meaningful Initial value is 0 RPC2_Perror set to 1 to see Unix error messages on stderr Initial value is 1 RPC2_Trace set to 1 to enable tracing 0 turns off tracing Initial value is 0 Setting the hashmark variable to a non zero character in DumbFTP descriptors will allow you to watch the progress of file transfers re ray psd Tracing will still work 110 111 Appendix Il Remote Site and Communication Failures Two hazards face the user of an RPC package 1 The communication medium may fail 2 The peer process at a remote site may crash A key problem in RPC is reliably detecting either of these events when an RPC call is in progress Detection of failures in the
46. e on the server side to enable connections after they are established This is done for you by RP2Gen if you use it 2 You must now call XXX_Activate to activate each type of side effect XXX If you do not call this routine code for that side effect will not be linked in For example you must call DFTP_Activate to enable the dumb file transfer protocol 3 Each side effect XXX now has a XXX_SetDefaults routine which sets defaults initialization values on a variable of type XXX Initializer 4 RPC2_GetPeerlnfo now returns information in a structure rather than as a long sequence of arguments 5 RPC2_SendResponse no longer has a SE__Descriptor argument 6 You no longer have to include dftp h if you are using the DFTP side effect routines Changes internal to RPC2 and invisible to the user 1 Support is being added for SFTP the faster file transfer protocol However it will not be enabled by default The next release will have it enabled 120 Appendix V Summary of RPC related Calls Note The numbers in square brackets indicate the page on which the call is described 121 122 References 1 Jonathan Rosenberg Larry Raper David Nichols M Satyanarayanan LWP Manual Information Technology Center CMU ITC 037 1985 2 M Satyanarayanan RPC Manual information Technology Center CMU ITC 011 1984 List of Tables Table Il 1 Retry Constants Bota 15 to 60 seconds 0 50 secs lower limit 114 Table Il 2 Ret
47. e to piggy back the side effect with the reply later 68 SE_CheckSideEffect Call long SE_CheckSideEffect in RPC2_Handle ConnHandle inout SE_Descriptor SDesc in long Flags Parameters ConnHandle SDesc Flags Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called when the server does an RPC2_CheckSideEffect call The Flags parameter will specify what Status is desired You may have to actually initiate the side effect depending on the circumstances 69 SE_SendResponse Call long SE_SendResponse in RPC2_Handle ConnHandle in RPC2_PacketBuffer ReplyPtr Parameters ConnHandle ReplyPtr Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called just before the reply packet is network ordered encrypted and transmitted You may wish to add piggy back data to the reply modify the BodyLength field in that case If you are not piggybacking data make sure that the side effect is complete before returning from this call If you need more space than available in the buffer passed to you you may allocate a larger packet copy the current contents and add additional data Return a pointer to the packet you allocated in ReplyPtr this is the packet that will actually get sent over the wire DO NOT free the buffer pointed to by ReplyPtr initially If you allocate a packet it will be freed immediately after successful transmission 70 SE_PrintSEDescriptor Cail long SE_PrintSEDescriptor i
48. ecs 120 secs 240 secs 300 secs 1 retries 30 00 60 00 40 00 80 00 80 00 160 00 100 00 200 00 2 retries 12 86 25 71 51 43 17 14 34 29 68 57 34 29 68 57 137 14 42 86 85 71 171 43 3 retries 6 00 12 00 24 00 8 00 16 00 32 00 16 00 32 00 64 00 20 00 40 00 80 00 48 00 64 00 128 00 160 00 4 retries 2 90 5 81 11 61 23 23 3 87 7 74 15 48 30 97 7 74 15 48 30 97 61 94 9 68 19 35 38 71 77 42 46 45 61 94 123 87 154 84 5 retries 1 43 2 86 5 71 11 43 1 90 3 81 7 62 15 24 3 81 7 62 15 24 30 48 4 76 9 52 19 05 38 10 22 86 45 71 30 48 60 95 60 95 121 90 76 19 152 38 6 retries 0 71 1 42 2 83 5 67 0 94 1 89 3 78 7 56 1 89 3 78 7 56 15 12 2 36 4 72 9 45 18 90 11 34 22 68 45 35 15 12 30 24 60 47 30 24 60 47 120 94 37 80 75 59 151 18 7 retries 0 50 0 71 1 41 2 82 0 50 0 94 1 88 3 76 0 94 1 88 3 76 7 53 1 18 2 35 4 71 9 41 5 65 11 29 22 59 7 53 15 06 30 12 15 06 30 12 60 24 18 82 37 65 75 29 45 03 60 21 120 47 150 59 8 retries 0 50 0 50 0 70 1 41 0 50 0 50 0 94 1 88 0 50 0 94 1 88 3 76 0 59 1 17 2 35 4 70 2 82 5 64 11 27 22 54 3 76 7 51 15 03 30 06 7 51 15 03 30 06 60 12 9 39 18 79 37 57 75 15 44 62 59 82 120 20 150 29 9 retries 0 50 0 50 0 50 0 70 0 50 0 50 0 50 0 94 0 50 0 50 0 94 1 88 0 50 0 59 1 17
49. ed Completion Codes RPC2_SUCCESS Peer information has been obtained for this connection RPC2_FAIL Bogus connection specified Returns the peer information for a connection Also returns other miscellaneous connection related information such as the securrity level in use This information may be used by side effect routines or high level server code to perform RPC bindings in the opposite direction The RemoteHandle and Uniquefier information are useful as end to end identification between client code and server code 48 RPC2_LamportTime Get Lamport time Call long RPC2_LamportTime Parameters None Completion Codes None Returns the current Lamport time Bears no resemblance to the actual time of day Each call is guaranteed to return a value at least one larger than the preceding call Every RPC packet sent and received by this Unix process has a Lamport time field in its header The value returned by this call is guaranteed to be greater than any Lamport time field received or sent before now Useful for generating unique timestamps in a distributed system 49 RPC2 DumpState Dump internal RPC state Call long RPC2_DumpState in FILE OutFile in long Verbosity Parameters OutFile File on which the trace is to be produced A value of NULL implies stdout Verbosity Controls the amount of information dumped Right now two values 0 and 1 are meaningful Completion Codes RPC2_SUCCESS
50. ed on server side when a new connection is established just prior to exit from the corresponding RPC2_GetRequest 64 SE_MakeRPC1 Call long SE_MakeRPC1 in RPC2_Handle ConnHandle inout SE_Descriptor SDesc inout RPC2_PacketBuffer RequestPtr Parameters ConnHandle SDesc RequestPtr Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called after a request has been completely filled just prior to network ordering of header fields encryption and transmission You may use the Prefix information to determine the actual size of the buffer corresponding to RequestPtr If you add data remember to update the BodyLength field of the header in RequestPtr You also probably wish to update the SideEffectFlags and SideEffectDataOffset fields of the header SDesc points to the side effect descriptor passed in by the client If you need more space than available in the buffer passed to you you may allocate a larger packet copy the current contents and add additional data Return a pointer to the packet you allocated in RequestPtr this is the packet that will actually get sent over the wire DO NOT free the buffer pointed to by RequestPtr initially If you allocate a packet it will be freed immediately after successful transmission 65 SE_MakeRPC2 Call long SE_MakeRPC2 in RPC2_Handle ConnHandle inout SE_Descriptor SDesc inout RPC2_PacketBuftfer Reply Parameters ConnHandle SDesc Reply Completion Code
51. ent and not export any subsystems A value of NULL will cause RPC2 to select an arbitrary nonassigned portal HowManyPortals Specifies the number of elements in the array PortalList RetryCount How many times to retransmit a packet before giving up all hope of receiving acknowledgement of its receipt Should be in the range 1 to 30 Use a value of 1 to obtain the default KeepAlivelnterval How often to probe a peer during a long RPC call This value is also used to calculate the retransmission intervals when packet loss is suspected by the RPC runtime system Use NULL to obtain the default Completion Codes RPC2_SUCCESS All went well RPC2_FAIL Unable to initialize client Check for bogus parameter values RPC2_WRONGVERSION The header file and the library have different versions This should never happen in a properly administered system RPC2_LWPNOTINIT The LWP package has not been properly initialized Be sure to call LWP_InitializeProcessSupport before calling RPC2_ Init0 RPC2_BADSERVER The PortaiList field specifies an invalid address RPC2_DUPLICATESERVER An entry in PortalList specifies an address which is already in use on this machine RPC2_SEFAIL1 The associated side effect routine indicated a minor failure RPC2_SEFAIL2 The associated side effect routine indicated a serious failure Initializes the RPC runtime system in this process This call should be made before any other call in this packa
52. er Carnegie Mellon University c Copyright IBM Corporation November 1985 static char IBMid c Copyright IBM Corporation November 1985 i include lt stdio h gt include lt potpourri h gt include lt strings h gt include lt sys time h gt include lt sys types h gt include lt netinet in h gt include lt pwd h gt include lt lwp h gt include lt rpc2 h gt include lt se h gt include auth h include comp h define dgets p L WP__DispatchProcess gets p allow RPC to get control periodically main int a char buf 100 printf Debug Level 0 dgets buf RPC2_ DebugLevel atoi buf InitRPC while TRUE i LWP_DispatchProcess otherwise we get RPC2_DEADs printf Action 1 New Conn 2 Auth Request 3 Comp Request dgets buf a atoi buf switch a case 1 NewConnQ continue case 2 Auth continue case 3 Comp continue default continue NewConnQ 11 char hname 100 buf 100 int newcid rc RPC2_Hostlident hident RPC2_Portalldent pident RPC2_Subsysident sident printf Remote host name dgets hident Value Name hident Tag RPC2_HOSTBYNAME printf Subsystem Auth d Comp d AUTHSUBSYSID COMPSUBSYSID dgets buf sident Value Subsysid atoi buf sident Tag RPC2_SUBSYSBYID pident Tag RPC2_PORTALBYINETNUMBER pident Value inetPortNumber htons AUTHPORTAL same as COMPP
53. es is name to id and id to name conversions Server Prefix S Subsystem auth gt Internet port number note that this is really not part of a specific subsystem but is part of a server we should really have a separate ex h file with this constant am being lazy here define AUTHPORTAL 5000 define AUTHSUBSYSID 100 The subsysid for auth subsystem Return codes from auth server define AUTHSUCCESS 0 define AUTHFAILED 1 typedef RPC2_ Byte PathName 1024 typedef RPC2_ Struct RPC2_ Integer Groupld PathName HomeDir Authinfo AuthNewConn IN RPC2_Integer seType IN RPC2_ Integer secLevel INRPC2_Integer encType IN RPC2_CountedBS cident NEW CONNECTION AuthUserld IN RPC2_ String Username OUT RPC2_ Integer Userld Returns AUTHSUCCESS or AUTHFAILED AuthUserName IN RPC2_lInteger Userid IN OUT RPC2_BoundedBS Username Returns AUTHSUCCESS or AUTHFAILED AuthUserinfo IN RPC2_Integer Userld OUT Authinfo Uinfo Returns AUTHSUCCESS or AUTHFAILED AuthQuit 5 2 2 Comp Subsystem rpc file M Satyanarayanan Information Technology Center Carnegie Mellon University c IBM Corporation November 1985 RPC interlace specification for a trivial computational subsystem Finds squares and cubes of given numbers Server Prefix S Subsystem comp define COMPSUBSYSID 200 The subsysid for comp subsystem define COMPSUCCESS 1 define COMPFAILED 2 CompNewConn iN RPC2_Integer seType IN
54. escription include include file_name define define identifier number typedef typedef rpc2_type identifier array_Spec rpc2_type type_name rpe2_struct rpc2_enum type_name RPC2_Integer RPC2_Unsigned RPC2_ Byte RPC2_String RPC2_CountedBs RPC2_BoundedBS SE_Descriptor RPC2_EncryptionKey identifier rpc2_struct RPC2_Struct field_list field_list field field field_list field type_name identitier_list identifier list identifier identifier identifier_list rpc2_enum RPC2_Enum enum_list enum_list enum enum list enum enum identifier number array_spec empty id_number id_number number identifier procedure_description proc_name formal_list timeout_override new_connection proc_name identifier formal_list empty formal_parameter formal_parameter formal_list formal_parameter usage type_name parameter_name usage IN OUT IN OUT parameter_name identifier timeout_override Timeout id_number empty new_connection NEW_CONNECTION empty empty In addition to the syntax above text inclosed in and is treated as a comment and ignored Appearances of an include statement will be replaced by the contents of the specified file All numbers are in decimal and may be preceded by a single sign Identifiers follow C syntax except that the underline character _ may not begin an identi
55. ffer space within the Unix kernel 40 RPC2_Unbind Terminate a connection by client or server Call long RPC2_Unbind in RPC2_Handle ConnHandle Parameters ConnHandle identifies the connection to be terminated Completion Codes RPC2_SUCCESS All went well RPC2_NOCONNECTION ConnHandle is bogus d RPC2_SEFAIL1 The associated side effect routine indicated a minor failure RPC2_SEFAIL2 The associated side effect routine indicated a serious failure RPC2_FAIL Other assorted calamities Removes the binding associated with the specified connection Normally a higher level disconnection should be done by an RPC just prior to this call Note that this call may be used both by a server and a client and that no client server communication occurs the unbinding is unilateral 41 RPC2_AllocBuffer Allocate a packet buffer Call long RPC2_AllocBuffer in long MinBodySize out RPC2_PacketBuffer Buff Parameters MinBodySize Minimum acceptable body size for the packet buffer Buff Pointer to the allocated buffer Completion Codes RPC2_SUCCESS Buffer has been allocated and Buff points to it RPC2_FAIL Could not allocate a buffer of requested size Allocates a packet buffer of at least the requested size The BodyLength field in the header of the allocated packet is set to MinBodySize The RPC runtime system maintains its own free list of buffers Use this call in preference to malloc 42 R
56. fier Note that a particular language interface defines what identifiers may actually be used in various contexts The following are reserved words in RP2GEN server client prefix subsystem timeout typedef rpc2_struct rpc2_enum in and out Case is ignored for reserved words so that for example subsystem may be spelled as SubSystem if desired Case is not ignored however for identifiers Note that the predefined type names RPC2_Integer RPC2_ Byte etc are identifiers and must be written exactly as given above The prefixes may be used to cause the names of the procedures in the interface to be prefixed witha unique character string The line Server Prefix test will cause the server file to assume that the name of the server interface procedure name is test_name Likewise the statement 76 Client Prefix real affects the client interface This feature is useful in case it is necessary to link the client and server interfaces together Without this feature name conflicts would occur The header_line defines the name of this subsystem The subsystem name is used in generating a unique for the execute request routine The defau t_timeout is used in both the server and client stubs Both are specified in seconds Zero is interpreted as an infinite timeout value The value specifies the timeout value used on RPC2__MakeRPC and RPC2_SendResponse calls in the client and server stubs respectively The timeout
57. for MRPC_MakeMulti Completion Codes 0 Continue processing server responses 1 Terminate MRPC_MakeMulti call and return This routine must return either O or 1 A return value of zero indicates that the client wants to continue receiving server responses as they come in normal case A return value of 1 indicates that the client has received enough responses and wants to terminate the MakeMulti call in which the client is still blocked This allows the client to call a large number or servers and terminate after the first n responses are received Note that the name of this routine is arbitrary and may be determined by the client RPC2_MultiRPC Sees it only as a pointer supplied as an argument to MRPC_MakeMulti The parameter list is predefined however and the client must follow the structure specified here in writing the routine 108 109 Appendix Usage Notes for the ITC The h files rpc2 h se h are in cmu itc nfs include There are actually two versions of the library and the normal one librpc2 a and one with debugging completely turned off librpc2_s a Using librpc2_s a will make your final load module considerably smaller but will produce no debugging information at all For the Suns these libraries are in cmu itc nfs lib For any other supported machine the libraries will be in cmu itc nfs machine lib Rp2gen is in cmu itc nfs bin for the Suns and in cmu itc nfs machine bin for any other supported machin
58. g IN union struct 06 long ProtectionBits char LocaiFileName 256 Unix mode bits to be set for created files ByName if Tag FILEBYNAME standard Unix open Struct long Device device on which file resides tong Inode inode number of file inode MUST exist already Bylnode it Tag FILEBYINODE ITC inode open FileInfo everything is IN define SFTP_Descriptor DFTP_ Descriptor enum SE_ Status SE_NOTSTARTED 33 SE_INPROGRESS 24 SE_SUCCESS 57 SE_FAILURE 36 typedef struct SE_ SideEffectDescriptor enum SE_ Status LocalStatus l E enum SE_ Status RemoteStatus tong Tag DUMBFTP or SMARTFTP or ASYNCFTP union struct DFTP_ Descriptor DumbF TPD struct SFTP__ Descriptor SmartFTPD Value SE_ Descriptor typedef struct DFTPI long NoOfBulkLWPs long ChunkSize long SupportedEncryptionTypes Mask long EnforceQuota DFTP _Initializer typedef struct SFTPI long PacketSize long WindowSize long RetryCount long Retry nterval long SendAhead long AckPoint long EnforceQuota SFTP _Initializer bytes in data packet max number of outstanding unacknowledged packets in milliseconds number of packets to read and send ahead when to send ack 0 gt don t Flag options in RPC2_CheckSEStatus OR these together as needed 57 define SE_AWAITLOCALSTATUS 1 define SE_AWAITREMOTESTATUS 2 extern struct SE_ Definition SE_DefS
59. g N characterises the probability of packet loss in the communication medium while B izi characterises how sluggish a server may get before it is declared dead Given Bota and N we can determine B B By such that B B B By Biot 4 and B lt B 7 Each B is a retry interval and the progressive lengthening of these intervals is to allow for transient overloads at remote sites In RPC2 B iti minimum bound on the values for B s to avoid send out packets too close to each other 2B In practise we may place a 112 The RPC2 packet transmission algorithm is based on these concepts and is outlined as follows while TRUE for i O iC Nj i send packet awaitresponse B if reply or lastack arrived quit if BUSY arrived break if i gt N goto TimeOut sleep B total TimeOut mark connection RPC2_DEAD mark all other connections to this host portal pair as RPC2_DEAD Failure is detected in time Blota f the remote site dies just after the sleep call ends If the failure occurs immediately after the remote site sends a Busy packet failure is detected after a total of 2B otar These cases bound the time it takes to detect failure Failure is also declared if all N of the retries are lost due to communication failure This will occur in a time exactly equal to B star How does this mesh with side effects The above algorithm will work regardless of the duration of a t
60. ge is made It should be preceded by an initialization call to the LWP package and a cali to SE_SetDefaults with InitialValues as argument If you get a wrong version indication obtain a consistent version of the header files and the RPC runtime library and recompile your code Note that this call incorporates a call to initialize IOMGR RetryCount and KeepAlivelnterval together define what it means for a remote site to be dead or unreachable Packets are retransmitted at most RetryCount times until positive acknowledgement of their receipt is received This is usually piggy packed with useful communication such as the reply to a request The KeepAlivelnterval is used for two purposes to determine how often to check a remote Site during a long RPC call and to calculate the intervals between the RetryCount retransmissions of a packet The RPC runtime system guarantees detection of remote site failure or network partition within a time period in the range KeepAliveinterval to twice KeepAliveinterval See Appendix Il for further information on the retry algorithm Remember to activate each side effect XXX that you are interested in by invoking the corresponding XXX Activate call prior to calling RPC2_Init You may get a warning about SO GREEDY being undefined if your kernel does not have an ITC bug fix RPC2 will still work but may be slower and more likely to drop connections during bulk transfer This is because of insufficient default packet bu
61. gnal handlers main int mypid signal SIGEMT DebugOn signal SIGIOT DebugOff InitRPC Q LWP_CreateProcess AuthLWP 4096 LWP_NORMAL PRIORITY AuthLWP NULL amp mypid LWP_CreateProcess CompLWP 4096 LWP_NORMAL PRIORITY CompLWP NULL amp mypid LWP_WaitProcess main Sleep here forever no one will ever wake me up AuthLWP p char p single parameter passed to LWP_CreateProcess RPC2_RequesiFilter reafilter RPC2_PacketBuffer reqbuffer RPC2_ Handle cid l int rc char pp Set filter to accept auth requests on new or existing connections reqfilter FromWhom ONESUBSYS reqfilter OldOrNew OLDORNEW reqfilter ConnOrSubsys Subsysld AUTHSUBSYSID while TRUE cid 0 if rc RPC2_GetRequest amp reqfilter amp cid amp reqbuffer NULL NULL NULL NULL lt RPC2__WLIMIT HandleRPCError rc cid if rc auth ExecuteRequest cid reqbuffer lt RPC2_WLIMIT HandleRPCError rc cid pp NULL if RPC2_GetPrivatePointer cid amp pp RPC2_SUCCESS pp NULL RPC2_Unbind cid This was almost certainly an AuthQuit call CompLWP p char p single parameter passed to LWP_CreateProcess RPC2_RequestFilter regfilter RPC2__PacketButfer reqbuffer RPC2_ Handle cid int rc char pp Set filter to accept comp requests on new or existing connections reqfilter FromWhom ONESUBSYS reqfilter OldOrNew OLDORNEW reqfilter ConnOrSubsys Subsysid COMPSUBS
62. his pointer is the same one passed in to MultiRPC so for the non RP2Gen case its type is determined by the client Response RPC2 response buffer rpcval Individual connection error code or server response code thishost Index into ConnHandleList to identify the returning connection Completion Codes 0 Continue accepting and processing server responses 7 Abort MultiRPC call and return This routine is fixed in the RP2Gen case and can be ignored by the client For the non RP2Gen case a pointer to a routine with the argument structure described must be supplied as an argument to RPC2_MultiRPC The functionality of such a client supplied routine is unconstrained but note that the return codes have an important effect on the process of the MultiRPC call 107 HandleResult Process incoming server replies as they arrive Call long HandleResult in long HowMany in RPC2_ Handle ConnArray in long WhichHost in long rpcval lt Variable Length Argument List Parameters HowMany ia number of servers from MRPC_MakeMulti call ConnArray array of connection ids as supplied to MRPC_MakeMulti WhichHost i this is an offset into ConnArray and into any OUT or IN OUT parameters Using this to index the arrays will yield the responding server and its corresponding argument values rpcval this is the RPC2 return code from the specified server lt Variable Length Argument List gt These should be specified as described above
63. iRPC 5 1 Design Issues The MultiRPC facility is an extension to RPC2 that provides a parallel RPC capability for sending a single request to multiple servers and awaiting their individual responses Although the actual transmission is done sequentially the resultant concurrent processing by the servers results in a significant increase in time and efficiency over a sequence of standard RPC calls The RPC2 runtime overhead is also reduced as the number of servers increases For the purposes of this discussion the base RPC2 facility will be referred to simply as RPC2 A noteworthy feature of the MultiRPC design is the fact that the entire implementation is contained on the client side of the RPC2 code The packet which is finally transmitted to the server is identical to a packet generated by an RPC2 call and the MultiRPC protocol requires only a normal response from a server A major design goal was the desire to automatically provide MultiRPC capability for any subsystem without requiring any additional support from the subsytem designer or implementor This has been achieved through modifications to RP2Gen the RPC2 stub generation package see chapter 4 RP2Gen generates an array of argument descriptor structures for each server operation in the specification file and these arrays are inserted in the beginning of the client side stub file These Structures are made available to the client through definitions in the associated h file a
64. ialization and export calls are pertinent to all users of RPC2 This material will make more sense in conjunction with the example of Chapter 1 Read Chapter 3 to get an idea of how to add new kinds of side effects to RPC2 You will probably not need this materiai unless you intend to extend RPC2 but an overview of this material will probably be useful At all times keep available a copy of the LWP reference manual 1 and refer to it as needed Some key features of this package are e Clients and servers are each assumed to be using the ITC lightweight process package 1 The RPC2 package will not work independently of the LWP package The LWP package makes it possible for a single Unix process to contain multiple threads of control LWPs An RPC call is synchronous with respect to an individual LWP but it does not block the encapsulating Unix process There is no a priori binding of RPC connections to LWPs within a client or server RPC connections and threads of control are orthogonal concepts There is no a priori restriction other than resource limitations on the number of clients a server may have or on the number of servers a client may be connected to e A server sends and receives requests via many different Portals and may service many different Subsystems A good analogue to a server supporting many subsystems is the Inet daemon in Unix 4 2 which is the rendezvous point for the FTP Telnet and Mail
65. icitly noted otherwise The procedure for making a MultiRPC call is very similar to that for making an RPC2 call The subsystem is designed and the specification is written into a lt subsys gt rpc2 file the specification format is described in section 4 RP2Gen is then invoked on the specification file and it generates both the standard server and client side interfaces as well as the MultiRPC argument descriptor Structures and definitions for each server operation The relevant descriptor pointers are made available to the client through the associated lt subsys gt h file Once the interface has been specified the subsystem implementor is responsible for writing the server main loop and the procedures to perform the server operations This implementation is completely independent of any considerations relating to MultiRPC MultiRPC is completely transparent to the server side of a subsystem From the client s perspective making a MultiRPC call is slightly different from the RPC2 case Instead of the procedure like client side interface supplied by the stub routines the single library routine MRPC_MakeMulti is used to interface to RPC2_MultiRPC The use of the library routine represents a large space savings in the executable files but requires some additional information from the client making the call see sections 5 3 3 2 and 5 4 1 The client is also responsible for supplying a handler routine for any server operation which is used
66. idate this pointer RPC2 GetSEPointer Obtain per connection side effect information Call long RPC2_GetSEPointer in RPC2_Handle WhichConn out char SEPtr Parameters WhichConn Connection whose side effect data pointer is desired SEPtr Set to point to side effect data Completion Codes RPC2_SUCCESS SEPtr now points to the side effect data associated with this connection RPC2_FAIL Bogus connection specified Returns a pointer to the side effect data associated with a connection No attempt is made to validate this pointer This call is should only by the side effect routines not by clients 46 RPC2_SetSEPointer Set per connection side effect connection Cail long RPC2_SetSEPointer in RPC2_Handle WhichConn in char SEPtr Parameters WhichConn Connection whose side effect pointer is to be set SEPtr Pointer to side effect data Completion Codes RPC2_SUCCESS Side effect pointer set for this connection RPC2_FAIL Bogus connection specified Sets the side effect data pointer associated with a connection No attempt is made to validate this pointer This call should only be used by the side effect routines not by clients 47 RPC2 GetPeerinfo Obtain miscellaneous connection information Call long RPC2_GetPeerinfo in RPC2_Handle WhichConn out RPC2_Peerinfo Peerinfo Parameters WhichConn Connection whose peer you wish to know about Peerinfo Data structure to be fill
67. in a MultiRPC call This handler routine is called by RPC2 as each individual server response arrives it is used both for providing individual server return codes to the client and for giving the client control over the continuation or termination of the MultiRPC call The handler routine is discussed in greater detail in the following section and its interface is described in section 5 4 1 98 5 3 1 The Client Handler The client handler routine is intended to give the client control and flexibility in handling the incoming server responses from the MultiRPC call For each connection specified in a RPC2_MultiRPC call the client handler is called either when a connection error is detected or when the server response for that connection arrives This allows the client to examine the replies as they arrive and provides the opportunity to perform incremental bookeeping and analysis of the responses The handler also has the ability to abort the MultiRPC call at any time A more detailed discussion of the handler specifications can be found in section 5 4 1 Since a MultiRPC call could potentially last a long time it is crucial to provide the client with some measure of control over the progress and termination of the call With many server responses there are many variables that the client might wish to monitor in order to evaluate the progress of the call In particular the server responses and return codes themselves have a significant effec
68. ine RPC2_AUTHONLY 12 Authenticated but not encrypted define RPC2 _HEADERSONLY 73 Authenticated but only headers encrypted define RPC2_ SECURE 66 Authenticated and fully encrypted RPC2 supports multiple encryption types the key length is fixed and you must always supply a field of RPC2_KEYSIZE bytes wherever an encryption key is called for However individual algorithms can choose to ignore excess bytes in the keys 16 The encryption types are specified as integer bit positions so that the EncryptionTypesMask field of RPC2_GetRequest can be a mask of these types The required type must also be specified in RPC2_Bind To add support for other encryption types only the constants below and the internal runtime procedures RPC2_Encrypt and RPC2_Decrypt have to be modified define RPC2_ DES 1 define RPC2_XOR 2 define RPC2_ENCRYPTIONTYPES RPC2_DES RPC2_XOR union of all supported types define RPC2_KEYSIZE 8 Size in bytes of the encryption keys RPC procedure return codes These may also occur in the RPC2_ReturnCod e field of reply headers Values of 0 and below in those fields are reserved for RPC stub use Codes greater than 0 are assigned and managed by subsystems There are three levels of errors Warning Error and Fatal Error RPC2_SUCCESS gt RPC2_WLIMIT gt warning codes gt RPC2_ELIMIT gt error codes gt RPC2_FLIMIT gt fatal error codes The semantics of these codes are RPC2_SUCCESS Everything was
69. initiated RPC2_NOTSERVER Only one side effect is allowed per RPC call This has to be initiated between the GetRequest and SendResponse of that call You are violating one of these restrictions RPC2_S EFAIL1 The associated side effect routine indicated a nonfatal failure Future calis on this connection will work RPC2_SEFAIL2 The associated side effect routine indicated a serious failure Future calls on this connection will fail too RPC2_ FAIL Other assorted calamities Initiates the side effect specified by SDesc on ConnHandle The call does not wait for the completion of the side effect If you need to know what happened to the side effect do a RPC2__CheckSideEffect call with appropriate flags 37 RPC2_CheckSideEffect Check progress of side effect Call long RPC2_CheckSideEffect in RPC2_Handle ConnHandle inout SE_ Descriptor SDesc in long Flags Parameters ConnHandle The connection on which the side effect has been initiated SDesc The side effect descriptor as it was returned by the previous RPC2_InitSideEffect or RPC2_CheckSideEffect call on ConnHandle On output the status fields are filled in Flags Specifies what status is desired This call will block until the requested status is available This is a bit mask with RPC2_GETLOCALSTATUS and RPC2_GETREMOTESTATUS bits indicating local and remote status A Flags value of 0 specifies a polling status check no blocking will occur and the currently known lo
70. into a request buffer and calls RPC2_MultiRPC with the request buffer some argument packing information and a pointer to MRPC_UnpackMulti the library unpacking routine RPC2__MultiRPC sets up the processing environment initializes the request packet headers for all the designated servers and performs any necessary side effect initialization It then calls an internal routine to perform the transmission of the request packets This transmission routine does not return until either the client supplied timeout expires or until it has received responses from all of the designated servers Once the request packets have been transmitted the routine settles into a loop waiting for server responses to arrive As each response arrives some preliminary processing is performed and any remaining side effect processing is completed Then RPC2 calls MRPC_UnpackMulti to unpack the response buffer into the clients original arguments MRPC_UnpackMulti unpacks the buffer and calls the client handler routine with the current servers s information The client then performs whatever processing he wishes and returns with his instructions to continue or terminate the call If he wishes to continue the internal loop continues until all the server responses have been received Otherwise the loop terminates and the transmission routine cleans up any loose ends caused by the termination Control then returns to RPC2__MultiRPC which checks the return code and retur
71. is for each RPC connection Multiple encryption types are also supported to allow servers to deal with various types of clients e This is a completely revised implementation of an earlier RPC package 2 used in Vice l The earlier implementation is no longer Supported 1 Design Concepts 1 1 Introduction lt lt lt lt lt lt to be written gt gt gt gt gt gt gt 1 2 An Example lt lt lt lt lt intro to be written gt gt gt gt gt gt 1 2 1 Auth Subsystem rpc file M Satyanarayanan Information Technology Center Carnegie Melion University c IBM Corporation November 1985 RPC interface specification for a trivial authentication subsystem This is only an example all it does is name to id and id to name conversions Server Prefix S Subsystem auth Internet port number note that this is really not part of a specific subsystem but is part of a server we should really have a Separate ex h tile with this constant am being lazy here define AUTHPORTAL 5000 define AUTHSUBSYSID 100 The subsysid for auth subsystem Return codes trom auth server define AUTHSUCCESS 0 define AUTHFAILED 1 typedef RPC2_ Byte PathName 1024 typedef RPC2_ Struct RPC2_ Integer Groupld PathName HomeDir Authinfo AuthNewConn IN RPC2_Integer seType IN RPC2_ Integer secLevel IN RPC2_ Integer encType IN RPC2_CountedBS cident NEW CONNECTION AuthUserld IN RPC2_ String Username OUT RPC2_
72. ive here a NULL value will be passed through to MultiRPC where it will indicate infinite patience as long as RPC2 believes that the server is alive Note that this timeout value is orthogonal to the RPC2 internal timeout for determining connection death lt Variable Length Argument List gt This is just the list of the server arguments as they are declared in the rpc2 file It is represented in this form since each cail will have a different argument list Completion Codes RPC2_SUCCESS All went well 105 RPC2_ TIMEOUT The user specified timeout expired before all the server responses were received RPC_FAIL For all OUT or IN OUT parameters an array of HowMany of the appropriate type should be allocated and supplied by the client For example if one argument is an OUT integer an array of HowMany integers i e int foo HowMany should be used For Structures an array of structures and NOT an array of pointers to structures should be used IN arguments are treated as in the RPC2_MakeRPC case 106 MRPC_UnpackMulti Unpack server arguments and call client handler routine Call long MRPC_UnpackMulti in long HowMany in RPC_ Handle ConnHandleList in out ARG_INFO Arginfo in RPC_PacketBuffer Response in fong rpcval in long thishost Parameters HowMany How many servers were included in the MultiRPC call ConnHandleList Array of HowMany connection ids Arginfo Pointer to argument information structure T
73. izeof struct Userinfo RPC2__SetPrivatePointer cid p p gt Creation time 0 S CompQuit cid Get rid of user state note that we do not do RPC2_Unbind here because this request itself has to complete The invoking server LWP therefore checks to see it this connection can be unbound struct Userinfo p RPC2_GetPrivatePointer cid amp p assert p NULL we have a bug then free p RPC2__SetPrivatePointer cid NULL return 0 S CompSquare cid x int x return x x S CompCube cid x RPC2_ Handle cid int x return x x x S CompAge cid x RPC2__ Handle cid int x struct Userinfo p assert RPC2_ GetPrivatePointer cid amp p RPC2_SUCCESS return time Q p gt Creation S CompExec cid cmd RPC2_ Handle cid char cmd We should really have a formal of type SE_Descriptor at the end but it is a dummy anyway SE__Descriptor sed char mycmd 100 sprintf mycmd s gt tmp answer 2 amp 1 cmd system mycmd beware if this takes too long client will get RPC2_DEADI bzero amp sed sizeof sed sed Tag DUMBFTP sed Value DumbFTPD Tag FILEBYNAME How I wish C had a with clause like Pascal sed Value DumbFTPD TransmissionDirection SERVERTOCLIENT sed Value DumbFTPD ByteQuota 1 strcpy sed Value DumbFTPD Fileinfo ByName LocaiFileName tmp answer if RPC2_InitSideEffect cid amp sed RPC2_ SUCCESS return COMPFAILE
74. l RPC2_Hostident RemoteHost RPC2__Portalldent RemotePortal RPC2_Subsysident RemoteSubsys RPC2_Handie RemoteHandle RPC2_ Integer SecurityLevel RPC2_Integer EncryptionType RPC2_Integer Uniquefier RPC2_EncryptionKey SessionKey RPC2_ Peerinfo The RPC2_PacketButfer definition below deals with both requests and replies The runtime system provides efficient buffer Storage management routines use them typedef struct RPC2_ PacketBuffer struct RPC2_ PacketBufferPrefix NOTE The Prefix is only used by the runtime system on the local machine Neither clients nor servers ever deal with it It is never transmitted struct RPC2_ PacketBuffer Next pointer to next element in buffer chain Struct RPC2_ PacketBuffer Prev pointer to prev element in buffer chain long MagicNumber to detect storage corruption long LEState to detect buffer chain addling Struct RPC2_PacketBuffer Qname name of queue this packet is on long BufferSize Set at malloc time size of entire packet including prefix long LengthOfPacket size of data actually transmitted header body 20 Prefix The transmitted packet begins here struct RPC2_PacketHeader RPC2_Integer ProtoVersion RPC2_Integer RemoteHandle RPC2_Integer LocaiHandle RPC2_Integer Flags RPC2_Unsigned BodyLength RPC2_Unsigned SeqNumber RPC2_Integer Opcode RPC2_ Unsigned SEFlags RPC2_Unsigned SEDataOffset RPC2__Unsigned Subsysid RP
75. lable servers and abort the call as soon as the first n responses arrive This has the advantage of supplying the fastest possible execution for the replicated call furthermore since the n members of the quorum need not be chosen explicitly the call will rarely have to be repeated if one of the servers is busy or inoperational The handler receives full sets of arguments each time it is called along with an index identifying the 99 current connection The types of the server arguments to the client handler are identical to the types in the original MakeMulti call the argument list is in fact passed through RPC2 and returned to the handler Any processing is permissible in the handler routine although it should be noted that since RPC2_MultiRPC does not support enqueueing of server requests any call made on a connection already active in a MultiRPC call will generate a return code of RPC2_BUSY Also for lengthy blocking computations the same cautions with respect to lightweight processes apply as for RPC2 it should also be noted that the use of the abort facility of the client handler carries with it some risks These are discussed in more detail in section 5 3 4 5 3 2 Flow of Control in MultiRPC The flow of control in MultiRPC is much the same as for RPC2 except for the iterative calling of the client handler The client initiates the MultiRPC call by calling the library routine MRPC_MakeMulti MakeMulti packs the client arguments
76. long Options in RPC2_Portalident PortalList in jong HowManyPortals in long RetryCount in struct timeval KeepAliveinterval RPC2_Unbind in RPC2_Handle ConnHandle RPC2_AllocButter in long MinBodySize out RPC2_PacketBuffer Buff RPC2_FreeButfer inout RPC2_PacketBuftter Buft RPC2_GetPrivatePointer in RPC2_Handle WhichConn out char PrivatePtr 44 45 46 47 48 49 50 51 52 53 59 60 61 62 63 64 65 66 67 68 RPC2_SetPrivatePointer in RPC2_Handle WhichConn in char PrivatePtr RPC2_GetSEPointer in RPC2_Handle WhichConn out char SEPtr RPC2_SetSEPointer in RPC2_Handle WhichConn in char SEPtr RPC2_GetPeerInfo in RPC2_Handle WhichConn out RPC2_ Peerinfo Peerinfo RPC2_LamportTime RPC2_DumpState in FILE OutFile in long Verbosity RPC2_InitTraceBuffer in long HowMany RPC2_DumpTrace in FILE OutFile in long HowMany XXX_SetDefaults in XXX_Initializer Initializer XXX_Activate in XXX_Initializer Initializer SE_Init SE_Bind1 in RPC2_Handle ConnHandle in RPC2_CountedBS Clientident SE_Bind2 in RPC2_Handle ConnHandle SE_Unbind in RPC2__Handle ConnHandle SE_NewConnection in RPC2_Handle ConnHandle in RPC2_CountedBS Clientident SE_MakeRPC1 in RPC2_Handle ConnHandle inout SE_Descriptor SDesc inout RPC2_PacketBuffer RequestPtr SE_MakeRPC2 in RPC2_Handle ConnHandle inout SE_Descriptor SDesc inout RPC2_PacketBufter Reply SE_Get
77. mented RP2GEN also defines a set of external data representations for RPC types These representations are defined at the end of this document in the section entitled External Data Representations Any program wishing to communicate with a remote program using the RP2GEN semantics must obey these representation standards 4 2 Usage RP2GEN is invoked as follows rp2gen server language client language file Where server language is the language to be used for the server interface and client language is the language for the client interface The possibilities for these fields are C f FORTRAN 77 p PASCAL If only one language option is specified the same language is used for both the server and the client The default options are c c Note that a particular language option may not support al of the data types File is the file containing the description of the interface Normally these files have the extension rpc2 RPGen creates three files named base client ext base server ext and base h where base is the 74 name of the file without the extension and the pathname prefix and ext is the appropriate language specific extension The options indicate the target language for the generated output The default is c Thus rp2gen samoan rpc2 would yield the files samoan client c samoan server c and samoan h A person wanting to provide a package remotely writes his package with a normal interface The client
78. n SE_Descriptor SDesc in FILE outFile Parameters SDesc Guaranteed to refer to your type of side effect outFile Already open and ready to receive bytes Completion Codes RPC2_SUCCESS Called when printing debugging information You should print out SDesc suitably formatted on outFile SE SetDefaults Call long SE_SetDefaults XXX_Initializer SiInit Parameters S nit An initializer for this side effect XXX Completion Codes RPC2_SUCCESS Called to set SInit to appropriate default values 71 72 SE_ Activate Call long SE_Activate in XXX_Initializer SiInit Parameters Sinit Initialization values to be used for this side effect XXX Completion Codes RPC2_SUCCESS Called to activate this side effect type The body of this procedure should allocate and fill in a routine vector in the side effect table in file se c It should also obtain its initialization parameters from Sinit 73 4 RP2Gen A Stub Generator for RPC2 NOTE This chapter is derived from the original documents by Jon Rosenberg David Nichols and M Satyanarayanan RP2Gen was written by Jon Rosenberg 4 1 Introduction RP2GEN takes a description of a procedure call interface and generates stubs to use the RPC2 package making the interface available on remote hosts RP2GEN is designed to work with a number of different languages C FORTRAN 77 PASCAL however only the C interface is currently imple
79. n integer represented in two s complement notation The most significant byte of the integer is 0 and the least significant byte is 3 RPC2_Unsigned An RPC2_Unsigned is a 32 bit item that encodes an unsigned integer The most significant byte of the integer is 0 the least significant byte is 3 RPC2_ Byte An RPC2_Byte is transmitted as a single byte followed by three padding bytes RPC2_ String An RPC2_String is a C style null terminated character String It is sent as an RPC2_Integer indicating the number of characters to follow not counting the null byte which is however sent This is 79 followed by bytes representing the characters padded to a multiple of 4 where the first character i e farthest from the null byte is byte 0 A RPC2_String of length 0 is representing by sending an RPC2_Integer with value 0 followed by a 0 byte and three padding bytes RPC2_CountedBS An RPC2_CountedBsS is used to represent a byte string of arbitrary length The byte string is not terminated by a null byte An RPC2_CountedBS is sent as an RPC2_Integer representing the number of bytes followed by the bytes themselves padded to a multiple of 4 The byte with the lowest address is sent as byte 0 RPC2_BoundedBS An RPC2_BoundedBsS is intended to allow you to remotely play the game that C programmers play allocate a large buffer fill in some bytes then call a procedure that takes this buffer as a parameter and replaces its contents by
80. nd allow the use of MultiRPC with any routine in any Subsystem with RP2Gen generated interfaces The orthogonality of the MultiRPC modifications also extends to the side effect mechanism see appropriate chapter Side effects for MultiRPC work exactly as in the RPC2 case except that the client must supply a separate SE_Descriptor for each connection Parameter packing and unpacking for MultiRPC is provided in the RPC2 runtime library by a pair of routines These library routines provide the functionality of the client side interface generated by RP2Gen as well as some additional modifications to support MultiRPC It was decided to perform the packing and unpacking in RPC2 library routines rather than in individual client side stub routines as in the RPC2 case this requires some extra processing time but saves a significant amount of space in the client executable file This approach has the added advantage of modularity execution of RPC2 Calls will not be affected at all and even for MultiRPC calls the additional processing time is negligable in comparison to the message transmission overheads imposed by the UNIX kernel 82 Another feature of MultiRPC is the client supplied handler routine Through the handler routine the client is allowed to process each server response as it arrives rather than waiting for the entire MultiRPC call to complete After processing each response the client can decide whether to continue accepting server respo
81. nd server runtime systems are incompatible Note that extreme incompatibilty may result in the server being unable to respond even with this error code In Such a case the server will appear to be down resulting in a RPC_NOBINDING return code RPC2_OLDVERSION This is a warning The RPC2_VERSION values on client and server sides are different Normal operation is still possible but one of you is running an obsolete version of the run time System You should obtain the latest copy of the RPC runtime system and recompile your code RPC2_NOTAUTHENTICATED A SecurityLevel other than RPC2_OPENKIMONO was Specified and the server did not accept your credentials RPC2_SEFAIL1 The associated side effect routine indicated a minor failure The connection is established and usable RPC2_SEFAIL2 The associated side effect routine indicated a serious failure The connection is not established RPC2_FAIL Some other mishap occurred Creates a new connection and binds to a remote server on a remote host The subsystem information is passed on to that server to alert it to the kind of remote procedure calls that it may expect on this connection A client server version check is performed to ensure that the runtime Systems are compatible Note that there are really two version checks One is for the RPC network protocol and packet formats and this must succeed The other check reports a warning if you have a different RPC runtime system from the server
82. nfo ainfo MAXCONNS RPC2_BoundedBS bbs MAXCONNS while 1 printf How many servers dgets buf howmany atoi buf if howmany lt 10 amp amp howmany gt 0 break for i 0 i lt howmany i printf Connection id dgets buf cid i atoi buf printf Operation 1 Id 2 Name 3 Info 4 Quit dgets buf op atoi buf returns 0 Zero return counter switch op case 1 printf Name dgets name rc MakeMulti AuthUserld OP AuthUserld PTR howmany cid Handle AuthUserld NULL name uid if rc RPC2_SUCCESS printf Call failed gt s n RPC2_ErrorMsg re break case 2 printf Id dgets buf uid 0 atoi buf bbs 0 MaxSeqLen sizeof name bbs 0 Seqlen 0 bbs 0 SeqBody RPC2_ByteSeq name for i 1 1 lt howmany i 91 92 bbs i MaxSeqLen sizeof name bbs i Seqlen 0 bbs i SeqBody RPC2_ByteSeq malloc sizeof name rc MakeMulti AuthUserName OP AuthUserName PTR howmany cid Handie AuthUserName NULL uid 0 bbs if rc RPC2_ SUCCESS printf Call failed gt s n RPC2_ErrorMsq rc for i 1 i lt howmany i free bbs i SeqBody break case 3 printf Id dgets buf uid 0 atoi buf rc MakeMuiti AuthUserInfo OP AuthUserlnfo PTR howmany cid Handle AuthUserinfo NULL uid 0 ainfo if rc RPC2_SUCCESS printf Call failed gt s n RPC2_ErrorMsg rc
83. ns to MRPC__MakeMulti MakeMulti simply passes the supplied return code back to the client as it returns Since side effects are completely determined by the SE_ Descriptor and the connection extending the side effect mechanism to MultiRPC requires nothing more than supplying a unique 100 SE_Descriptor for each connection 5 3 3 MultiRPC Related Calls 9 3 3 1 RPC2_MultiRPC RPC2_MultiRPC is the RPC2 runtime routine responsible for setting up the internal state properly for sending the request packets to the specified servers It is called via the RPC2 library routine MRPC__MakeMulti One of the arguments to MultiRPC is the Arginfo structure This structure is never examined by RPC2 but is simply passed through UnpackMulti If the RP2Gen interface is used this argument is supplied by MRPC_MakeMulti and need not concern the client If the RP2Gen meraca is not used this can point to any structure needed by the client s unpacking routine The UnpackMulti argument is also related to the RP2Gen interface If the RP2Gen interface is used this argument is automatically supplied by MRPC_MakeMulti and will point to the RPC2 library unpacking routine If the RP2Gen interface is not used the client is responsible for supplying a pointer to a routine matching the UnpackMulti specification see section 5 4 1 9 3 3 2 MRPC_MakeMulti MRPC_MakeMulti is the library routine which provides the parameter packing interface to RPC2_ MultiRPC
84. nses or whether to abort the remainder of the call This facility can be useful if only a subset of responses are required or if one failed message renders the entire call useless to the client This capability is discussed further in section 5 3 1 MultiRPC also provides the same correctness guarantees as RPC2 except in the case where the client exercises his right to terminate the call RPC2 guarantees that a request or response will be processed exactly once in the absence of network and machine crashes otherwise it guarantees that it will be processed at most once If the call completes normally a return code of RPC2_SUCCESS guarantees that all messages have been received by the appropriate servers 5 2 An Example The following example is the same as the one in section 1 2 but here it has been converted to use MultiRPC Comparison of the two examples will illustrate the differences in the client code necessary to use the MultiRPC facility Only the code in the file exclient c has been changed exserver c and both of the rpc2 files were unaffected by the modifications This example illustrates the MultiRPC interface to a simple system The system exports two subsystems an authentication server and a computation server The authentication operations _ include looking up either a user name or a user id given the complementary information or looking up some user statistics given the user id The computation server operations include sq
85. nter extern long RPC2_ SetSEPointer extern long RPC2_ GetPeerInfo extern char RPC2_ErrorMsaq NOT long HII extern long RPC2_ DumpTrace extern long RPC2_DumpState extern long RPC2_InitTraceBufferQ extern long RPC2_LamportTime extern long RPC2_EnableQ endif 22 2 2 Client related Calls RPC2_ Bind Create a new connection Call long RPC2_Bind in long SecurityLevel in long EncryptionType in RPC2_Hostident Host in RPC2_Portalident Portal in RPC2_Subsysident Subsys in jong SideEffectType in RPC2_CountedBS Clientident in RPC2_EncryptionKey SharedSecret out RPC2_Handle ConnHandle Parameters SecurityLevel One of the constants RPC2_OPENKIMONO RPC2_ONLYAUTHENTICATE RPC2_HEADERSONLY or RPC2_SECURE EncryptionType The kind of encryption to be used on this connection For example RPC2_XOR RPC2_DES etc Ignored if SecurityLevel is RPC2_OPENKIMONO The bind will fail if the remote site does not support the requested type of encryption Host The identity of the remote host on which the server to be contacted is located This may be specified as a string name or as an Internet address In the former case the RPC runtime system will do the necessary name resolution Portal An identification of the server process to be contacted at the remote site Portals are unique on a given host A portal may be specified as a string name or as an Internet port value in the former case the RPC runtime system
86. opyright IBM Corporation November 1985 include lt stdio h gt include lt potpourri h gt include lt strings h gt include lt sys signal h gt include lt sys time h gt include lt sys types h gt include lt netinet in h gt include lt pwd h gt include lt lwp h gt include lt rpc2 h gt include lt se h gt include auth h include comp h This data structure provides per connection info It is created on every new connection and ceases to exist after AuthQuit struct Userinfo int Creation Time at which this connection was created other fields would go here J int NewCLWP AuthLWP CompLWP bodies of LWPs void DebugOn DebugOff signal handlers main int mypid signal SIGEMT DebugOn signal SIGIOT DebugOff InitRPC LWP_CreateProcess AuthLWP 4096 LWP_NORMAL PRIORITY AuthL WP NULL amp mypid LWP_CreateProcess CompLWP 4096 LWP_NORMAL PRIORITY CompLWP NULL amp mypid LWP__WaitProcess main sleep here forever no one will ever wake me up AuthLWP p char p Single parameter passed to LWP_CreateProcess RPC2_RequestFilter reafilter RPC2_PacketBuffer reqbuffer RPC2_ Handle cid int rc char pp Set filter to accept auth requests on new or existing connections reqfilter FromWhom ONESUBSYS reqfilter OldOrNew OLDORNEW reqfilter ConnOrSubsys Subsysid AUTHSUBSYSID while TRUE cid 0 if rc
87. otar Note that it is immaterial whether the side effect involves asynchronous Unix processes or not If such processes side effect as long as Busy packets are sent out by that server at intervals of B are involved their failure will be detected perhaps as RPC2_ DEAD failures or in other ways and reported by the remote server explicitly as RPC2_SEFAIL2 Only if the remote server is itself dead or 113 unreachable is the RPC return code RPC2_DEAD and this will occur no later than 2B otal after the failure In DUMBFTP side effect failure is detected because it is implemented using RPC2 In cases where TCP or other protocols are being used for side effects the failure detection mechanisms of these protocols will be relied upon to detect side effect failure Tables Il 1 and 2 show how the N retransmissions take place within B for typical values of N and total Botar The original attempt is at time 0 The numbers in parentheses indicate the time B y that RPC2 waits after the transmission of the last retry before declaring failure A lower limit of 500 milliseconds for the retry interval is assumed 114 1 retries 2 retries 3 retries 4 retries 5 retries 6 retries 7 retries 8 retries 9 retries 10 retries 15 secs 5 00 10 00 2 14 4 29 8 57 1 00 2 00 4 00 8 00 0 50 0 97 1 94 3 87 7 73 0 50 0 50 0 95 1 90 3 81 7 33 0 50 0 50 0 50 0 94 1 89 3 78 6 89 0 50 0 50 0 50 0 50 0 94 1 88 3
88. out each of the connections specified in ConnHandleList a reply has been received a hard error has been detected for that connection or the specified timeout has elapsed The Arginfo structure exists to supply argument packing and unpacking information in the case where RP2Gen is used Since its value is not examined by RPC2 it can contain any pointer that a non RP2Gen generated client wishes to supply Similarly UnpackMulti will point to a specific unpacking routine in the RP2Gen case If the RP2Gen interface is not used you should assume that the return codes of the supplied routine must conform to the specifications in section 5 4 1 Side effects are supported as in the standard RPC2 case except that the client must supply a separate SE_Descriptor for each connection The format for the SE_Desc riptor argument is described in section 5 4 It will often be useful to supply connection specific information such as unique file names inthe SE_ Descriptor A further discussion of the MultiRPC facility can be found in chapter 5 29 2 3 Server related RPC Calls RPC2_ Export Indicate willingness to accept calls for a subsystem Call long RPC2_Export in RPC2_Subsysident Subsys Parameters Subsys Specifies a subsystem that will be henceforth recognized by this server This is either an integer or a symbolic name that can be transiated to the unique integer identifying this subsystem Completion Codes RPC2_SUCCESS Ail went
89. parameter may be overriden for individual procedures by specifying a timeout_override Note that the timeouts apply to each individual Unix blocking system call not to the entire RPC2 procedure The new_connection is used to designate at most one server procedure that will be called when the Subsystem receives the initial RPC2 connection The new connection procedure must have 4 arguments in the following order with the following usages and types IN RPC2_Integer SideEffectType IN RPC2 _Integer SecurityLevel IN RPC2_Integer EncryptionType IN RPC2 _CountedBS ClientIdent where SideEffectType SecurityLevel EncryptionType and Clientldent have the values that were specified on the client s call to RPC2_Bind Note that RP2Gen will automatically perform an RPC2__Enable call at the end of this routine If no new connection procedure is specified then the call to the execute request routine with the initial connection request will return RPC2_ FAIL The usage tells whether the data for the parameter is to be copied in copied out or copied in both directions The usage and type_name specifications together tell how the programmer should declare the parameters in the server code An Example TT Subsystem fs2 typedef RPC2_Unsigned Volumeld typedef RPC2_ Unsigned Vnodeld typedef RPC2_Unsigned Unique typedef RPC2_ Struct VolumeId Volume Vnodeld Vnode Unique Unique ViceFid ViceConnectFS IN RPC2_String UserName IN R
90. pecs array extern long SE_ DefCount how many are there extern void SE_ SetDefaults endif 3 2 Adding New Kinds of Side Effects The rest of this chapter is not intended for the average user Only a system programmer who intends to add support for a new kind of side effect needs to understand the semantics of the calls described here The normal user need only concern himself with the format of the side effect descriptor described above 3 2 1 Notes 1 You will modify two RPC2 files se h and se c and add one more file containing the code implementing your new side effect Also modify the Makefile to compile and link in your new file 2 Client and server programs will cause the appropriate side effect routines to be linked in by calling the appropriate SE_Activate for each side effect they are interested in Note that these calls must precede RPC__Init 3 None of these procedures will be called for a connection if the RPC2_Bind that created the connection specified NULL for the SideEffectType parameter 4 In each of the calls ConnHandle is the handle identifying the connection on which the side effect is desired It is not likely to be a small integer Since you cannot access the internal data structures of the RPC2 runtime system you cannot use this for much It is passed to you primarily for identification 5 You can use RPC2_GetSEPointer and RPC2_SetSEPointer to associate per connection side effect data st
91. perfect Warning Advisory information Error Something went wrong but the connection i any is still usable Fatal The connection if any has been marked unusable Note that the routine RPC2_ErrorMsg will translate return codes into printable strings define RPC2_SUCCESS 0 define RPC2_WLIMIT 1 define RPC2_ELIMIT 1000 define RPC2_FLIMIT 2000 Warnings define RPC2_OLDVERSION RPC2_WLIMIT 1 define RPC2_INVALIDOPCODE RPC2_WLIMIT 2 Never returned by RPC2 itself Used by higher levels such as rp2gen define RPC2_BADDATA RPC2_WLIMIT 3 Never used by RPC2 itself used by rp2gen or higher levels to indicate bogus data Errors define RPC2_CONNBUSY RPC2_ELIMIT 1 define RPC2_SEFAIL1 RPC2_ELIMIT 2 define RPC2_TOOLONG RPC2_ELIMIT 3 Fatal Errors define RPC2_FAIL RPC2_FLIMIT 1 define RPC2_NOCONNECTION RPC2_FLIMIT 2 define RPC2_ TIMEOUT RPC2_FLIMIT 3 define RPC2_NOBINDING RPC2_FLIMIT 4 define RPC2_DUPLICATESERVER RPC2_FLIMIT 5 17 define RPC2_NOTWORKER RPC2_FLIMIT 6 define RPC2_NOTCLIENT RPC2_FLIMIT 7 define RPC2_WRONGVERSION RPC2_FLIMIT 8 define RPC2_NOTAUTHENTICATED RPC2_FLIMIT 9 define RPC2_CLOSECONNECTION RPC2_FLIMIT 10 define RPC2_BADFILTER RPC2_FLIMIT 11 define RPC2_LWPNOTINIT RPC2_FLIMIT 12 define RPC2_BADSERVER RPC2_FLIMIT 13 define RPC2_SEFAIL2 RPC2_FLIMIT 14 define RPC2_DEAD RPC2_FLIMIT 15 detine RPC2_NAKED RPC2_FLIMIT 16 Universal opcode values opcode values e
92. qual to or less than 0 are reserved Values greater than O are usable by mutual agreement between clients and servers define RPC2_INIT1OPENKIMONO 2 Begin a new connection with security level RPC2_OPENKIMONO define RPC2_INIT1AUTHONLY 3 Begin a new connection with security level RPC2_AUTHONLY define RPC2_INITIHEADERSONLY 4 Begin a new connection with security level RPC2_HEADERSONLY define RPC2_INITI1SECURE 5 Begin a new connection with security level RPC2_SECURE define RPC2_LASTACK 6 Packet that acknowledges a reply define RPC2_REPLY 8 Reply packet define RPC2_INIT2 10 Phase 2 of bind handshake define RPC2_INIT3 11 Phase 3 of bind handshake define RPC2_INIT4 12 Phase 4 of bind handshake define RPC2_NEWCONNECTION 13 opcode of fake request generated by RPC2_GetRequest on new connection define RPC2_BUSY 14 keep alive packet System Limits define RPC2_MAXPACKETSIZE 10000 size of the largest acceptable packet buffer in bytes includes pretix and header Global variables tor debugging RPC2_DebugLevel controls the level of debugging output produced on stdout A value of 0 turns off the output altogether values of 1 10 and 100 are currently meaningtul The default value of this variable is 0 RPC2_Perror controls the printing of Unix error messages on stdout A value of 1 turns on the printing while 0 turns it off The default value for this variable is 1 RPC2_Trace controls the tracing of RP
93. r with local fields filled in May be NULL if no side effects will occur as a result of this call Reply On return it will point to a response buffer holding the response from the server You should free this buffer when you are done with it Patience Maximum time to wait for remote site to respond A NULL pointer indicates infinite patience EnqueueRequest Specifies whether the caller should be blocked if ConnHandle is already servicing an RPC request from some other lwp If this variable ts 1 the caller is blocked Otherwise a return code of RPC2__CONNBUSY is returned Completion Codes RPC2_SUCCESS All went well RPC2_NOCONNECTION ConnHandle does not refer to a valid connection RPC2_TIMEOUT A response was not received soon enough Occurs only if the Patience parameter was non NULL RPC2_SEFAIL1 The associated side effect resulted in a minor failure Future calls on this connection will still work RPC2_SEFAIL2 The associated side effect resulted in a serious failure Future calls on this connection will fail 26 RPC2_DEAD The remote site has been deemed dead or unreachable Note that this is orthogonal to an RPC2_ TIMEOUT return code 3 RPC2_NAKED The remote site sent an explicit negative acknowledgement This can happen if that site thought you were dead or if someone at that site unbound your connection RPC2_CONNBUSY EnqueueRequest specified 0 and ConnHandle is currently servicing a call Try again later
94. ready incremented the connection at the termination of R2 In order to keep the connection from hanging around uselessly S3 will send a RPC2__NAK return code if it ever receives a request R3 on the same connection with a sequence number greater than R2 This will kill the connection forcing the client to rebind if he wants to continue communicating with S3 _ Another risk associated with the use of abort is the risk of not identifying dead connections If a server S2 is dead but the client always chooses to abort his MultiRPC call before a response from 2 arrives RPC2 may not have time to notice that the connection is dead These problems are a result of the cients ability to ignore the responses on some connections in a MultiRPC call and will generally only manifest themselves in a case where a server is forced to queue a request because it is busy processing an earlier request This means that the MultiRPC call should be used with caution in cases where simultaneous binding to a single site might result although the severity of the problem can be lessened by providing a greater number of LWPs at the single site It is important to note that these problems arise only in the case where the client chooses to abort the call before all replies have been received However the explicit NAK by the server at least gives the client the opportunity to learn that something has gone wrong with the connection and act accordingly 5 4 C Interface Specific
95. ruct SE_ Definition long SideEffectType what kind of side effect am 1 long SE__Init Q on both client amp server side long SE_Bind1 0 on client side long SE_ Bind2 on client side long SE_Unbind on client and server side long SE_NewConnection 0 on server side long SE_MakeRPC1 on client side long SE_MakeRPC2 on client side long SE__GetRequest on server side long SE__InitSideEffect on server side long SE_CheckSideEffect on server side long SE_SendResponse on server side long SE_PrintSEDescriptor for debugging long SE_ SetDefaults for initialization J Types of side effects use this in the RPC2_Bind call define DUMBFTP 231 define SMARTFTP 1189 enum WhichWay CLIENTTOSERVER 93 SERVERTOCLIENT 87 enum FilelnfoTag FILEBYNAME 33 FILEBYINODE 58 Struct DFTP_Descriptor enum WhichWay TransmissionDirection IN char hashmark IN 0 for non verbose transfer long SeekOffset IN gt 0 position to seek to before first read or write long BytesTransferred OUT value after RPC2_CheckSideEffect meaningtul long ByteQuota IN maximum number of data bytes to be sent or received SE_FAIL1 is returned and the transfer aborted if this limit would be exceeded EnforceQuota in DFTP_Initializer must be specitied as 1 at RPC initialization for the quota enforcement to take place A value of 1 implies a limit of infinity enum FilelnfoTag Ta
96. ructures 6 Use RPC2__GetPeerInfo to get the identity of a connection s peer 7 Three return codes RPC2_SUCCESS and RPC2_SEFAIL1 and RPC2_SEFAIL2 are recognized for each of the calls The successful return causes the RPC runtime system to resume normal execution from the point at which the side effect routine was invoked The failure returns abort the call at that point and returns RPC2_SEFAIL1 or RPC_SEFAIL2 to the client or server code that invoked the RPC system call RPC2_SEFAIL1 is an error but not a fatal error Future RPC calls on this connection will still work RPC2_SEFAIL2 is a fatal error 8 To add a new type of side effect do the following a Define an appropriate side effect descriptor add it to the header file se h and to the discriminated union in the definition of SE__Descriptor b Define an appropriate Initializer structure and a corresponding component in the SE__Initializer structure in file se h c Write a set of routines corresponding to each of the SE_ XXX routines described in the following pages This includes a SE_Activate routine to enlarge the table in file se c and a SE_ SetDefaults routine to deal with SE__Initializer structures SE_Init Cail long SE_Init Parameters None Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called just prior to return from RPC2_Init 59 60 SE_Bind1 Call long SE_Bind1 in RPC2_Handle ConnHandle in RPC2_CountedBS Clientiden
97. ruly unique random number Arbitrary length body For requests IN and INOUT parameters For replies OUT and INOUT parameters Header BodyLength gives the length of this field The second and third fields actually get sent over the wire set by runtime system set by runtime system enum E1 ANY 12 ONECONN 37 ONESUBSYS 43 FromWhom enum E2 OLD 27 NEW 38 OLDORNEW 69 OldOrNew union RPC2__Handle WhichConn long Subsysid ConnOrSubsys ONECONN ONESUBSYS if FroomWhom if FroomWhom 21 RPC2__RequestFilter l Type of Filter parameter in RPC2_GetRequest The following data structure is the body of the packet synthesised by the runtime system on a new connection and returned as the result of an RPC2_GetRequest typedef Struct RPC2_ Integer SideEffectType RPC2_Integer SecurityLevel RPC2_ Integer EncryptionType RPC2__CountedBS Clientident RPC2_NewConnectionBody RPC2 runtime routines extern long RPC2_InitQ extern long RPC2_Export extern long RPC2_DeExport extern long RPC2__AllocBuffer extern long RPC2_ FreeBuffer extern long RPC2_ SendResponse extern long RPC2_ GetRequest extern long RPC2_MakeRPC extern long RPC2_MultiRPCQ extern long RPC2_ Bind 0 extern long RPC2_ InitSideEffectQ extern long RPC2_CheckSideEffect extern long RPC2_ Unbind extern long RPC2__GetPrivatePointerQ extern long RPC2_SetPrivatePointer extern long RPC2__GetSEPoi
98. ry Constants B 90 to 300 seconds 0 50 secs lower limit 115 li total 22 25 27 29 30 31 34 35 36 37 38 40 41 42 43 RPC2_Bind in long SecurityLevel in long EncryptionType in RPC2_Hostident Host in RPC2_Portalldent Portal in RPC2_Subsysident Subsys in long SideEffectType in RPC2__CountedBS Clientident in RPC2_EncryptionKey SharedSecret out RPC2_Handle ConnHandle RPC2_MakeRPC in RPC2_Handle ConnHandle in RPC2_PacketBuffer Request in SE_ Descriptor SDesc out RPC2_PacketBuffer Reply in struct timeval Patience in long EnqueueRequest RPC2__MultiRPC in long HowMany in RPC2_Handle ConnHandleList in RPC2_PacketBuffer Request in SE_Descriptor SDescList in long UnpackMulti in out ARG_INFO Arginfo in struct timeval Patience RPC2_Export in RPC2_Subsysident Subsys RPC2_DeExport in RPC2_Subsysident Subsys RPC2_GetRequest in RPC2_RequestFilter Filter out RPC2_ Handle ConnHandie out RPC2_PacketBuffer Request in struct timeval Patience in long GetKeys in long EncryptionTypeMask in long AuthFail RPC2_Enable in RPC2_Handle ConnHandle RPC2_SendResponse in RPC2_Handle ConnHandle in RPC2_PacketBuffer Reply RPC2_InitSideEffect in RPC2_Handle ConnHandle in SE_Descriptor SDesc RPC2_CheckSideEffect in RPC2_ Handle ConnHandle inout SE_Descriptor SDesc in long Flags RPC2_Init in char Versionld in
99. s RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called just after Reply has been received after decryption and host ordering of header fields Examine the SideEffectFlags and SideEffectDataOffset fields to determine if there is piggy backed Side effect data for you in Reply If you remove data remember to update the BodyLength field of the header in Reply SDesc points to the side effect descriptor You will probably wish to fill in the status fields of this descriptor If the MakeRPC call fails for some reason this routine will be called with a Reply of NULL This allows you to take suitable cleanup action 66 SE_GetRequest Call long SE_GetRequest in RPC2_Handle ConnHandle inout RPC2_PacketBufter Request Parameters ConnHandle Request Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called just prior to successful return of Request to the server You should look at Request extract Side effect data if any modify the header fields appropriately 67 SE_InitSideEffect Call long SE_InitSideEffect in RPC2_Handle ConnHandle inout SE_Descriptor SDesc Parameters ConnHandle SDesc Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called when the server does an RPC2_InitSideEffect call You will probably want to examine some fields of SDesc and fill in some status related fields Note that there is no requirement that you should actually initiate any side effect action You may choos
100. s intended to allow you to remotely play the game that C programmers play all the time allocate a large buffer fill in some bytes then call a procedure which takes this buffer as a parameter and replaces its contents by a possibly longer sequence of bytes Example strcat typedef RPC2_Byte RPC2_EncryptionKey RPC2_KEYSIZE Keys used for encryption are fixed length byte sequences Dene eee eee eee eo ee ae Data Types used only in runtime Calls hd oe eR 2 2 2 typedef RPC2_ Integer RPC2_ Handle actually a pointer in the remote machine s addr space NOT a small integeriil typedef struct enum HostType RPC2_HOSTBYINETADDR 17 RPC2_HOSTBYNAME 39 Tag dbx bogosity if anonymous enum union unsigned long InetAddress NOTE in network order not host order char Name 20 this is a pretty arbitrary length Value RPC2_Hostident 19 typedef struct enum PortalType RPC2_PORTALBYINETNUMBER 53 RPC2_PORTALBYNAME 64 Tag dbx bogosity if anonymous enum union unsigned short InetPortNumber NOTE in network order not host order char Name 20 this is a pretty arbitrary length Value RPC2_ Portalident typedef struct enum SubsysType RPC2_SUBSYSBYID 71 RPC2_SUBSYSBYNAME 84 Tag dbx bogosity if anonymous enum union long Subsysid char Name 20 l this is a pretty arbitrary length Value RPC2_ Subsysident typedef struct data structure filled by RPC2_GetPeerinto cal
101. subsystems Binding by clients is done to a host portal subsystem triple e Host portal subsystem and side effect descriptor specifications are discriminated union types to allow a multiplicity of representations For example hosts may be specified either by name or by Internet address Files may be specified by a file name or a low level identifier or in future perhaps even a file descriptor e RPC connections may be associated with Side Effects to allow application specific network optimizations to be performed An example is the use of a specialized protocol for bulk transfer of large files Detailed information pertinent to each type of side effect is specified in a Side Effect Descriptor Side effects are explicitly initiated by the server and occur asynchronously Synchronization occurs due to an explicit RPC2__CheckSideEffect call by the server e Adding support for a new type of side effect is analogous to adding a new device driver in Unix To allow this extensibility the RPC code has hooks at various points where side effect routines will be called Global tables contain pointers to these side effect routines The basic RPC code itself knows nothing about these side effect routines e RPC2 has builtin mechanisms to allow authentication of mutually suspicious clients and Servers and to provide encrypted transmissions after connection establishment Multiple levels of security are available and may be specified on an individual bas
102. t Parameters ConnHandle Clientident Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called on RPC2_ Bind on client side The call is made just prior to sending the first connection establishment packet to the server The connection establishment is continued only if RPC2_ SUCCESS is returned 61 SE_Bind2 Call long SE_Bind2 in RPC2_Handle ConnHandle Parameters ConnHandle Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called on RPC2_Bind on client side The call is made just after the connection is successfully established before control is returned to the caller If SE _Bind2 returns RPC2_SEFAIL1 or RPC2_SEFAIL2 that code is returned as the result of the RPC2_ Bind Otherwise the usual code is returned 62 SE_Unbind Call long SE_Unbind in RPC2_Handle ConnHandle Parameters ConnHandle Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Called when RPC2_Unbind is executed on the client or server side You are expected to free any side effect storage you associated with this connection and to do whatever cleanup is necessary Note that the connection state is available to you and is not destroyed until you return RPC2_ SUCCESS SE _NewConnection Call long SE_NewConnection in RPC2_ Handle ConnHandle in RPC2_CountedBS Clientident Parameters ConnHandle Clientident Completion Codes RPC2_SUCCESS RPC2_SEFAIL1 RPC2_SEFAIL2 Call
103. t on the client s perception of the progress of the call To address these requirements RPC2 periodically passes control to the client during execution of the MultiRPC call A client supplied routine designed to be called as each server response arrives provides access to complete current information about the status of the call it also gives the client the ability to perform any incremental processing he considers necessary or useful The client then indicates his decision to either continue accepting server responses or to terminate the MultiRPC call via the handler return code The value of client control over the progress of the MultiRPC call can best be illustrated with some specific examples One example is in the case of connection errors If the client requires responses on ali of the designated connections and one of them returns an error then the final result of the MultiRPC call will be useless and the remainder of the processing time will have been wasted With the client handler routine the client has the ability to notice the connection error He then has the ability to abort the call or even to use the handler routine as an opportunity to rebind to the failed site and make an RPC2 call on that connection Another example is in the implementation of a replicated server A useful way to deal with operation quorums specified as some subset n of the total number of replicated servers is to send messages out to all or many of the avai
104. tf Bogus user id n else printf Call failed gt s n RPC2_ErrorMsg rc if returns gt HowMany return 1 wait for all returns return 0 long Handle AuthQuit HowMany cid thishost rc int HowMany thishost re RPC2__Handle cid printf received reply from connection d n cid thishost if rc AUTHSUCCESS printf Call failed for connection d gt s n cid thishost RPC2_ rrorMsg rc RPC2_ Unbind cid thishost if returns gt HowMany return 1 wait for all returns return O Comp RPC2_Handie cid MAXCONNS int op rc x howmany i SE Descriptor sed MAXCONNS char cmd 100 buf 100 fname 30 while 1 printf How many servers dgets buf howmany atoi buf if howmany lt 10 amp amp howmany gt 0 break for i 0 i lt howmany i printt Connection id dgets buf cid i atoi buf printf Operation 1 Square 2 Cube 3 Age 4 Exec 5 Quit dgets buf op atoi buf returns 0 Zero return counter switch op case 1 printf x dgets buf x atoi buf rc MakeMulti CompSquare OP CompSquare PTR howmany cid Handle CompSquare NULL x if rc RPC2_SUCCESS printf MakeMulti call failed gt s n RPC2_ErrorMsg rc break case 2 94 printf x dgets buf x atoi buf rc MakeMulti CompCube OP CompCube PTR howmany cid Handle CompCu
105. turns return 0 long Handle CompCube HowMany cid thishost rc x int HowMany thishost rc x RPC2_ Handle cid printf received reply from connection d n cid thishost if rc gt 0 printf x 3 d n rc else printf Call failed gt s n CompCube n if returns gt HowMany return 1 wait for all returns return 0 95 long Handle CompAge HowMany cid thishost rc int HowMany thishost re RPC2_ Handle cid printf received reply from connection d n cid thishost if rc gt 0 printf Age of connection d seconds n rc else printf Call failed gt s n CompAge n if returns gt HowMany return 1 wait for all returns return O long Handle CompExec HowMany cid thishost rc cmd sed int HowMany thishost re RPC2_ Handle cid char cmd SE Descriptor sed char ucmd 100 printf received reply from connection d n cid thishost Sprintf ucmd echo Result of remote exec cat tmp result d cid thishost if rc COMPSUCCESS system ucmd i else if rc COMPFAILED printf Could not do remote exec n else printf Calt failed gt s n CompExec n if returns gt HowMany return 1 wait for all returns return O long Handle CompQuit HowMany cid thishost rc int HowMany thishost rc RPC2_ Handle cid if rc lt 0 printf Call failed gt s n RPC
106. uaring a number cubing a number requesting the age of a given connection and causing the remote host to exec a specified command and return the results as a side effect in a file A user can create a new connection or make a request to either the authentication or computation subsystem The new connection choice results in an RPC2_Bind to the subsystem specified subsystem requests cannot be made until a new connection has been created The bind returns a connection id which can be used to identify the connection when making server requests Once a connection has been established to a subsystem a subsystem request can be made The client will prompt for the number of servers to which the request is to be made and for their connection ids In each case except the Bind the call is made using MultiRPC using the MRPC_MakeMulti library routine interface Note that RPC2_MultiRPC is used even when only one server is requested A minimal handler routine is supplied for each server operation It is adequate to demonstrate the format of the routine even though it does little actual processing of the responses The handler corresponds to the HandleResult routine described in sections 5 4 1 and 5 3 3 4 5 2 1 Auth Subsystem rpc file M Satyanarayanan Information Technology Center Carnegie Mellon University c IBM Corporation November 1985 RPC interface specification for a trivial authentication subsystem This is only an example all it do
107. vel connection establishment Note that RP2Gen automatically generates this call at after a NewConnection routine RPC2_SendResponse Respond to a request from my client Call long RPC2_SendResponse in RPC2__Handle ConnHandle in RPC2_PacketButfer Reply Parameters ConnHandle Which connection the response is to be sent on Reply A tilled in buffer containing the reply to be sent to the client Completion Codes RPC2_SUCCESS sent your response RPC2_NOTWORKER You were not given a request to service RPC2_DEAD The remote site is dead or unreachable RPC2_NAKED The remote site sent an explict negative acknowlegment RPC2_SEFAIL1 The associated side effect routine indicated a minor faiture Future calls on this connection will still work RPC2_SEFAIL2 The associated side effect routine indicated a serious failure Future calis on this connection will fail too RPC2_FAIL Some irrecoverable failure happened Sends the specified reply to the caller Any outstanding side effects are completed before Reply is sent Encryption if any is done in place and will clobber the Reply buffer 36 RPC2_InitSideEffect Initiate side effect Call long RPC2_InitSideEffect in RPC2_Handle ConnHandle in SE_Descriptor SDesc Parameters ConnHandle The connection on which the side effect is to be initiated SDesc A filled in side effect descriptor Completion Codes RPC2_SUCCESS The side effect has been
108. xec cat tmp result else if rc COMPFAILED printf Could not do remote exec n else l printf Call failed gt s n RPC2_ErrorMsg rc break case 5 rc CompQuit cid if rc lt 0 printf Call failed gt s n RPC2_ErrorMsg rc RPC2_ Unbind cid break See ees eee ee ee s RPC Initialization and Error handling s szssssss2222 l InitRPC int mylpid 1 DFTP_Initializer dftpi struct timeval tout assert LWP _InitializeProcessSupport L WP_NORMAL PRIORITY amp mylpid LWP_SUCCESS DFTP_SetDefaults amp dftpi dftp ChunkSize 1024 2K and 4K give much better performance DFTP_Activate amp dftpi tout tv sec 240 tout tv usec 0 assert RPC2_Init RPC2_VERSION 0 NULL 1 1 amp tout RPC2_SUCCESS 14 iopen 15 2 The RPC2 Runtime System The purpose of this section is to describe the physical layout of data in transmissions between client and server RPC runtime systems The runtime system deals with contiguous packet Buffers each of which consists of a Prefix which is of fixed length and is used internally by the runtime system It is NOT transmitted a Header which is also of fixed length and whose format is understood by the runtime system The opcode associated with the RPC sequencing information and the completion code returned by the remote site are the kinds of information found here a Body of arbitrary size
109. y the client When the client returns an abort code there may still be some outstanding server replies RPC2_MultiRPC increments the connection sequence number and resets the connection State thus pretending that the response in question was actually received This allows the system to continue with normal operation The risks of this approach can be illustrated with some examples A client makes a MultiRPC request R1 to 3 servers and terminates the call after two of the server responses have been received At server S3 the request has been queued because the server was busy with a previous request The client then decides to make another MultiRPC request R2 on a set of servers that includes server 3 from the first call S3 then receives R2 tagged with the next logical sequence number on the same connection as R1 If S3 has not yet begun processing R1 then it will throw R2 away because it recognizes that its sequence number is too high S3 will then proceed to process R1 and send the 102 response back to the client the client however will promptly throw the response away as a retry because the semantics of his abort command was to pretend that the response to R1 from S3 had already arrived Now assuming that the client chooses to terminate his second call before 3 returns the client and S3 are completely out of synch 3 having thrown away R2 will always be expecting a packet with R2 s sequence number the client however has al

RPC2 User Manual - Carnegie Mellon University

Contents

Download Pdf Manuals

Related Search

Related Contents