INTERNET-DRAFT T. Shemsedinov RIST Expires: 12 December, 2002 M. Shemetilo NPUOU June 2002 Universal Service Protocol draft-shemsedinov-usp-03.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 except that the right to produce its updatings is not granted. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them in other cases than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft shadow directories can be accessed at http://www.ietf.org/shadow.html. This section will be updated with the appropriate verbiage from RFC 2223 should this document has been found ready for publication as an RFC. This document is a product of the Research Institute of System Technologies and National Polytechnic University of Ukraine. Abstract This document contains the description of call and response packets of USP protocol. The protocol is the maximally generalized way of the complex hierarchical information coding, in its basis the principles of object analysis and modeling are fixed. The protocol is not assigned to any specific service and gives only basic developing rules of any service protocols, however USP was developed as RPC protocol. Packets of the latter should be multipart structures similar to MIME or XML, but with support of a multilevel enclosure and other expansions. Unfortunately, the majority of the modern protocols represent the information differently, it is caused by the fact that they were created by the independent developers, at different time and for different operational systems. The protocols simplification to a common format of representation of the information will essentially enable to facilitate development of the new protocols and new servers, besides it will remove problems connected with any incompatibility, and will increase speed of information processing. I am distinctly aware of all complexities connected with USP implementation, but standardization always brings more benefits, than problems. It was obvious in the case with SNMP and MIB. Shemsedinov RIST [Page 1] Internet-Draft USP June 2002 1. Common structure of packets The protocols of this family are intended to run dialogue between the set of clients and a server, i.e. for realization of the remote procedure calls and reception of the structured results. Packets are divided into three types: calls, responses and events. One USP packet can consist of a set of TCP packets. The following symbols #46#13#10 are used to mark the end of USP packet. The clients transfer packets containing the information necessary for execution of function in such format: FunctionName(par1..., parN). Server should respond to the timeout expiration in such format: Field1[val1] Field2[val2] ... FieldN[valN]. The responses are divided into fields, each of which consists of a name and value in square brackets. The fields are divided by blanks (#32) or symbols #13#10. In the names of fields, as well as values, the following symbols are possible: any from #32 up to #255 except listed: #35, #36, #37, #38, #40, #41, #44, #91, #93. Other symbols are transferred as a pair of symbols #36 ("$") and the symbol with a code increased by 48. Such coding of fields values allows to get rid of all managing symbols. The capital and small letters in the names of fields and functions differ. 2. Classification of response packets The response packets are of two types: simple and structural. The simple packets transfer values of the certain fields, and structural ones can comprise hierarchy of subpackets, arrays and files. 2.1. Packet header The first line of each packet contains a header. The first field of heading is "Res", it contains a code of correct inquiry execution In case of successful execution the field has value "OK", another code is an error code in a format "ERR_*". The second obligatory field "Model" has two possible values: "small" and "large". This field defines, whether the packet is simple or contains the structured data. Further there are either fields of a simple packet or structure of the data. 2.2. Classification of data structures Each structure has obligatory fields; they are located in its first line and determine the name of structure (field "Part") and type Shemsedinov RIST [Page 2] Internet-Draft USP June 2002 of structure (field "Type"). The type of structure can accept 5 values: "plain", "multipart", "array", "table", "file ". The end of structure is marked by the field "Endpart" containing the name of the closed structure. 2.2.1. Plain structures The type of structure "plain" allows to store a set of fields with unique names in structure. The order of fields has no importance. The unit of this type may be not divided on the fields in general and can contain the text with the allowed symbols or any others symbols that must be coded in the same way as values of fields. 2.2.2. Multipart structures The type of structure "multipart" enables to divide the structure into substructures. The format of the substructure corresponds to this description, and all substructures can have a multiple enclosure. 2.2.3. Array structures The type of structure "array" speaks that the structure stores in each line an element of array. Each element can have a similar set of fields, or they can differ. 2.2.4. Table structures The type of structure "table" should have identical fields in each record. The names of fields are specified in the header, and each record only contains values of fields. Each record is limited to a pair of symbols "[]" (#91#93). The values between them are separated by "," (#44). This type differs from a type "array" by reduction of the record size. 2.2.5. File structures The structure type "file" allows to place the whole binary files coded in the format Base64 (RFC 2045) in packets. However, the affiliated protocols can have the variety of coding, in such cases a field that contains the coding method identifier should be added in structure definition. 2.3. Examples of response packets For better understanding, we can consider the various information representations in formatted USP packets in the following examples. 2.3.1. Elementary (not structured) packet In this example the packet contains one set of not repeating fields only. In particular it is the data about any user. Shemsedinov RIST [Page 3] Internet-Draft USP June 2002 Res[OK] Model[small] User[Vasia Pupkin] Email[vasia@pupkin.com] Usertype[extended_user] State[Connected]. 2.3.2. Packet with one array section Continuing the previous example, we admit, that we need to transfer the information about several users. Then the packet will look as the following: Res[OK] Model[large] Part[Users] Type[array] User[Vasia Pupkin] Email[vasia@pupkin.com] User[XNP] Email[xnp@zhadum.anfacom.net] User[Nut_M] Email[Nut@rulez4ever.org] Endpart[Users]. 2.3.3. Packet with table The same information, as in the previous example. Res[OK] Model[large] Part[Users] Type[table] Count[3] [User,Email] [Vasia Pupkin,vasia@pupkin.com] [XNP,xnp@zhadum.anfacom.net] [Nut_M,Nut@rulez4ever.org] Endpart[Users]. 2.3.1. Structured packet with various substructures This example shows the possibility to present the information about my workstation. Res[OK] Model[large] Part[MyWorkstation] Type[multipart] Name[WS1] IP[10.18.8.51] Sysop[Shemsedinov Timur] Domain[RIST] Building[18] Room[435] Organization[Research Institute of System Technologies] Part[Display] Type[multipart] Name[Sampo] Diagonal[14] ManufDate[May.1998] Part[ModeList] Type[table] [Resolution,Color,Frq] [640x480,True,85] [800x600,True,85] [1024x768,65535,85] [1280x1024,256,85] [1600x1200,256,60] Endpart[ModeList] Part[Adapter] Type[plain] Chip[S3 Trio64V2] Dac[S3 SDAC] Memory[2Mb] Shemsedinov RIST [Page 4] Internet-Draft USP June 2002 Manuf[S3 Incorporated] Endpart[Adapter] Endpart[Display] Part[Keyboard] Type[plain] Name[FTC] ModelName[KWD-203] Alpha[Roman,Cyrillic] KeyCount[104] Endpart[Keyboard] Part[Disks] Type[array] Disk[A] Type[Floppy] Descr[3inch] Disk[C] Size[38974345] Disk[D] Size[2398459] Disk[E] Size[29038429] Disk[F] Type[CDROM] Descr[x32] Disk[G] Size[9873653] Endpart[Disks] Part[RAM] Type[plain] MemType[DIMM] Size[128] Descr[two chips] Endpart[RAM] Part[CPU] Type[plain] Name[K6-2] Manuf[AMD] Speed[300] Descr[with 3dNow] Endpart[CPU] Endpart[Computer]. 3. Event packets The event packets differ from the answer packets only by the fact that they can be transferred by a server to any connected client at any time without a function call. It is necessary in case when we need to notify the clients about events occurring on a server. The text of an event packet differs only by the first line, which contains the name of the event in a format: "Event[name]". 3.1. Example of an event without parameters If the event does not require transferring of the additional information except for the name of event, it can be limited to one line. For example, to notify the USP server administrator about change in a configuration and necessity to re-read it such packet can be transferred: Event[cfg_changed]. 3.2. Example of a packet with structure transferred as parameter In event packets all cases of the structural and enclosed packets, arrays and files are possible, etc. For example, if there is a remote administration interface in the USP server it is possible to notify the client-manager about new user's connections through transferring an event packet: Event[client_connected] Model[large] Part[c_info] Type[plain] Shemsedinov RIST [Page 5] Internet-Draft USP June 2002 Name[...] IP[...] TimeOfConnection[...] Port[...] SelectedService[...] UserGroup[...] Endpart[c_info]. However, the same information can be transferred with Model = "small": Event[client_connected] Model[small] Name[...] IP[...] TimeOfConnection[...] Port[...] SelectedService[...] UserGroup[...]. 4. Handshake There is a primary dialogue between the server and the client on the connection of each client, and as the result the server identifies the client and determines to which subprotocol to transfer the inquiries. The format of handshake consists of standard USP packets with the fixed set of fields. First a server sends a greeting packet, with such fields: Res, Model, Servername, Time, Date, Owner, Services. The client decides on the basis of the received information whether this server gives an access to the necessary service. If it is so, the client calls "SelectService" with parameters: ServiceName, UserName, Password. The server only confirms or rejects a choice of service, its accessibility to the specified user and correctness of the password. Instead of "SelectService" here a pseudonym "sls" may be used. 4.1. Example of handshake Having connection established the server sends a packet: Res[OK] Model[small] Servername[First USP Server] Owner[rist] Time[8:11] Date[25.Sep.2000] Services[RA,RMU,UOD,SHFS]. The client chooses the subprotocol and transfers the name and password by calling the function: SelectService(RA,asutp,asutp). Server confirms successful connection with the subprotocol: Res[OK] Model[small]. From this point all packets from this client are transformed into calls of functions from the separate module that realizes the specific subprotocol. Thus subprotocols become a usual API. However, the basic module watches calls of functions and if the function "SelectService" is carried out repeatedly, it switches the client to another module of the server. Shemsedinov RIST [Page 6] Internet-Draft USP June 2002 4.2. System functions After the successful end of the first handshake, except for the functions of the current interface and "SelectService" the two system functions "listinterface" and "man" can be called at any time. A pseudonym for "listinterface" is "li". Function "listinterface" returns the list of accessible functions of the chosen service (is called without parameters). The function "man" with the name of the function specified in its single parameter returns a format of a call of the interface function. 5. Simplifications of packet structures In frequently occurring cases some fields of USP packets can be omitted, since their meanings are exactly defined by other fields or they contain no useful information. Also arrays can have a simplified structure: if a set of fields in each line of an array is identical, there is no necessity to store names of fields in each line. Such cases will be considered in the following sections. 5.1. Returning of the function performance code If the packet contains only field "Res", the field "Model" can contain only value "small", so it can be not specified. For example: instead of "Res[OK] Model[small]." it is possible to transfer "Res[OK].". The call of event without parameters can be reduced too, as it was already shown above: "Event[Name].". 5.2. Simplicity of reading versus the size of packets We used indents in all examples of text-packets for simplicity of reading and distinct visual separation between beginnings and ends of structures. These indents are not obligatory at all, because the structure of a packet without them is precisely determined. However, they can take place in the packets, if instead of the application there is a person with Telnet compatible terminal on the client side. 5.3. One-dimensional arrays If it is necessary to transfer a one-dimensional array, it can be made without creating subpackets of the root packet, and simply by listing values separated by the symbol #44 (it is a special symbol for the fields values, and it was reserved for this case). 6. The subprotocol of the remote administration of USP server. This protocol is not obligatory on all USP servers but it gives some opportunities for flexible server configuration without its reloading. The protocol has the name "RA/USP" and the line "SelectService" in handshake should look as shown in the following example: Shemsedinov RIST [Page 7] Internet-Draft USP June 2002 SelectService(RA,name,password). 6.1. The basic functions of RA/USP. Call: GetIPs(). Response: Res[OK] Model[large] Part[IPS] Type[plain] 10.18.8.54 10.18.8.52 10.18.8.3 Endpart[IPS]. Description: Receive the list of IP addresses (or masks) of clients, which can work with server (i.e. AccessList). Call: AddIP(IPAddr). Response: Res[OK]. Description: Add IP (or mask) in AccessList. Call: DelIP(IPAddr). Response: Res[OK]. Description: Remove IP (or mask) from AccessList. Call: GetLog(). Response: Res[OK] Model[large] Part[LogFile] Type[plain] 9/25/2000 20:30:38 10.18.8.51 Error #10053 9/25/2000 20:30:44 10.18.8.51 connected 9/25/2000 20:30:52 10.18.8.51 disconnected Endpart[Logfile]. Description: Receive logfile in which the date and time of some operations of the users is registered. Call: GetInfo(). Response: Description: Receive common information about the server. Call: GetUsers(). Response: Res[OK] Model[large] Part[Users] Type[array] User[Asutp] Service[OODB] IP[..] Inc[..] Out[..] Socket[..] User[Timur] Service[RA] IP[..] Inc[..] Out[..] Socket[..] User[Nps5] Service[RMU] IP[..] Inc[..] Out[..] Socket[..] Endpart[Users]. Description: Receive the information about the users and their parameters. The values of some fields are replaced by ".." for brevity. The field "Socket" contains ID of the connection. This value can be transferred as the parameter of function "CloseUser". Shemsedinov RIST [Page 8] Internet-Draft USP June 2002 Call: CloseUser(UserID) Response: Res[OK]. Description: Disconnection of the client. Call: GetINI(). Response: Res[OK] Model[large] Part[INIfile] Type[plain] alias=test syslogin=asutp syspass=asutp Endpart[INIfile]. Description: Receive the list and values of environment variables. Call: SetINI(varName,varValue). Response: Res[OK]. Description: Establish the value of a specified variable. Call: Sleep(). Response: Res[OK]. Description: Put the server into quiescent condition. Call: Wake(). Response: Res[OK]. Description: Put the server into active condition. Call: Restart(). Response: Res[OK]. Description: Gently restart the server. Shemsedinov RIST [Page 9] Internet-Draft USP June 2002 7. References [1] Postel, J., "Transmission Control Protocol - DARPA Internet Program Protocol Specification", RFC-793, ISI, September 1981. [2] Freed,Borenstein, RFC-2045 "Multipurpose Internet Mail Extensions" Unit: "Base64 Content-Transfer-Encoding", November 1996. [3] Sun Microsystems, Inc. "RPC: Remote Procedure Call", RFC-1057, June, 1988. [4] Grady Booch, "Object-Oriented Design", 1991. 8. Author's Address Timur Shemsedinov Research Institute of System Technologies Ukraine, Kiev E-mail: timur@niist.ntu-kpi.kiev.ua Marina Shemetilo Computer Inter Service - PolySystem Ukraine, Kiev E-mail: Marina@cis-kiev.com Expires: 12 December, 2001 Shemsedinov RIST [Page 10]