              5            The CCSO Nameserver Server-Client Protocol   !                                by 1                 Steven Dorner   s-dorner@uiuc.edu 6            Computer and Communications Services Office0                 University of Illinois at Urbana  '                           April 2, 1990     %                            updated by 0                 Paul Pomes   paul-pomes@uiuc.edu6            Computer and Communications Services Office0                 University of Illinois at Urbana  '                          August 2, 1992            Introduction  A This document describes the protocol used by the CCSO Nameserver. A It provides all the information necessary to write a program that @ interfaces with the Nameserver, or for a human to speak directly to the Nameserver.  @ While CCSO provides a client program for our Nameserver, we also> expect the Nameserver to be used from programs other than this8 client.  First, our client does not run on every system.A Secondly, the Nameserver is potentially of use for more than just 9 human lookup of information; other programs (such as mail 0 delivery agents) may wish to use the Nameserver.  = This was kept in mind when designing the protocol used by the < Nameserver.  It is fairly easy to generate and parse (if not= totally regular), and should prove easy to incorporate in any  program.   General Format  A The general format of the protocol is request/response, like that @ of FTP;[1] the client makes requests, and the server responds to9 them.  The conversation is in "netascii", with a carriage    ____________________A    Converted to portable n/troff format using the -me macros from " funky Next WriteNow format (icch).A    [1]  See  RFC-959, File Transfer Protocol (FTP), J. Postel and  J. Reynolds.                        A 2                      The CCSO Nameserver Server-Client Protocol     > return-linefeed pair[2] separating the lines, as in telnet.[3]@ This allows a user to use the Nameserver with any telnet client,
 if they wish.   ? A request begins with a keyword, and may have zero or more key- A words or values, separated by spaces, tabs, or newlines, and fol- < lowed by a carriage return-linefeed pair.  Values containing< spaces, tabs or newlines should be enclosed in double quotes? (`"').  Any printable characters may be used in a quoted string ? (except `"').  In addition, the sequences "\n", "\t", "\"", and 8 "\\" may be used to mean newline, tab, double quote, and backslash, respectively.  @ Like FTP, numerical values are used to indicate the Nameserver's= response to requests.  Unlike FTP, data is passed on the same @ connection as commands.  The format for responses is as follows:  0      result code:[entry index:][field name:]text  A Multiline responses should preface each line of the response with @ the appropriate result code, negated (prefaced with "-"), on all@ lines of the response but the last.  If a particular command can< apply to more than one entry, responses involving individual> entries will have an entry index directly following the resultA code.  This index will begin with 1, and be incremented each time = a new entry is being referred to.  Commands that can apply to @ more than one field will have the name of the field to which theA response applies directly following the entry index.  The text of ? the response will be either an error message intended for human @ consumption, or data from the Nameserver.  Whitespace (spaces or* tabs) may appear anywhere in the response.  @ Since more than one specific piece of information may be manipu-A lated by a particular command, it is possible for parts of a com- < mand to succeed, while other parts of the same command fail.? This situation is handled as a single multi-line response, with ( the result code changing as appropriate.  A As for FTP, numerical responses are in the range 100-599 (or from > -599 to -100 for multiline responses), where the leading digit has the following significance:        1: In progress     2: Success     3: More information needed;     4: Temporary failure; it may be worthwile to try again.      5: Permanent failure     ____________________'    [2] The carriage return is optional. =    [3] See RFC-854, Telnet Protocol Specification, J. Postel.                       A The CCSO Nameserver Server-Client Protocol                      3     = Specific numbers have meanings to some commands; all commands  obey the general scheme.  < Many commands generate more than one line of response; every@ client should be prepared to deal with such continued responses.A It is worthwhile to note that a command is finished when and only < when the result code on a response line (treated as a signed) integer) is greater than or equal to 200.   ; Keywords must be given in lower case; case in the values of = fields is preserved, although queries are not case-sensitive.    The Commands  2 query [field=]value. . .  [return field1 [field2]]/ ph [field=]value. . .  [return field1 [field2]]     ? This is the basic client request.  It may be used in any of the @ Nameserver modes.[4] Entries whose fields match the given values= will be found, and the requested fields printed.  If no field > name is specified in the query part of the command, the "name"; field is assumed.  If no fields are specified with a return > clause, a default set of fields will be returned.  Fields from= each entry will be prefaced with an entry index, a colon, the ? field name, and another colon.  If the special field name "all" @ is given in the return clause, all fields from the entry will be@ printed (subject to normal constraints with regard to Nameserver mode and field properties).   ? Note that to view some sensitive fields, it is necessary to use @ Nameserver login mode.  Note also that fields whose descriptions= include the property Encrypt cannot be printed by the server. @ Values containing newlines will be broken into lines and printed one line per response.  < The second number on each response is the entry index; it is9 incremented each time the response refers to a new entry.   ; Some implementations of qi return a 102 response before the ? actual entries, giving the number of entries found; be prepared   to see or not see this response.   "Query" and "ph" are synonyms.         ____________________A    [4] See The CCSO Nameserver - A Description, S. Dorner and  P. - Pomes, for a description of Nameserver modes.                         A 4                      The CCSO Nameserver Server-Client Protocol      Examples  $     query name=dorner phone=244-1765#     -200:1:         alias: s-dorner +     -200:1:          name: dorner steven c. 5     -200:1:         email: dorner@garcon.cso.uiuc.edu '     -200:1:         phone: (w) 244-1765 *     -200:1:       address: 181 DCL, MC 2567     -200:1:              : 1201 W. Washington, C, 61821 4     -200:1:    department: computing services office)     -200:1:         title: res programmer       -200:1:      nickname: Steve'     -200:1:         hours: 8-4 weekdays      200:Ok.      query alias=s-dorner#     -200:1:         alias: s-dorner +     -200:1:          name: dorner steven c. 5     -200:1:         email: dorner@garcon.cso.uiuc.edu '     -200:1:         phone: (w) 244-1765 *     -200:1:       address: 181 DCL, MC 2567     -200:1:              : 1201 W. Washington, C, 61821 4     -200:1:    department: computing services office)     -200:1:         title: res programmer       -200:1:      nickname: Steve'     -200:1:         hours: 8-4 weekdays      200:Ok. #     query dorner return alias hours #     -200:1:         alias: m-dorner 0     -508:1:         hours: Not present in entry.#     -200:2:         alias: j-dorner 0     -508:2:         hours: Not present in entry.#     -200:3:         alias: s-dorner '     -200:3:         hours: 8-4 weekdays $     -200:4:         alias: j-dorner10     -508:4:         hours: Not present in entry.     200:Ok. "     query alias=s-dorner return id7     -503:1:            id: You may not view this field.      200:Ok. "     query name=dorner address=moon!     501:No matches to your query.       + change [field=]value. . .  make field=value     < Change looks much like query.  The entries to be changed are> specified as in query.  They keyword make separates the searchA criteria from the fields to be changed.  The change command works 9 in hero mode, or in login mode if applied to fields whose                         A The CCSO Nameserver Server-Client Protocol                      5     > description contain the Change property[5] in the entry of theA logged-in user.  If it is desired remove a field, Adjacent double < quotes ("") should be given as the "new value" of the field.@ Fields whose descriptions include the property Encrypted must be> encrypted before transmission to the Nameserver, unless the qi? program is being run directly from a terminal.  This encryption 7 should be done with the password of the logged in user.    Examples  :     change alias=s-dorner make hours="when the sun shines"2     506:You must be logged in to use this command.&     change steven dorner make hours=""     200:1 entry changed.4     change steven dorner make name="Dr. Strangelove",     -505:name:you may not change this field.$     500:1 entry found, none changed.'     change ikenberry make email=zzz@xxx 2     518:Too many entries (3) selected; limit is 2./     change stanley ikenberry make email=zzz@xxx 3     -510:s-ikenberry:You may not change this entry. $     500:1 entry found, none changed.       login alias  answer code  clear password    > This is used to enter login or hero mode.  The Nameserver will9 respond with a random challenge, which may be returned in ? encrypted form via the answer command.  The encryption key will @ be a password known to both the Nameserver and the user.  Alter-? nately, the client may respond with the clear command, and give ? the proper password in clear text.  This is not the recommended ? method, and is only provided for the lazy protocol implementor.    Examples       login s_dorner     301:dkeiigjasdvvnmnmeigh     answer ewituegndvbngkgdfkgl       200:s-dorner:Hi how are you?     login s-dorner/     301:?;_?DB,F9X;8O=H8Y<H[H=FY?1*;>?#(^='<!HH &     answer ellwekkewdfasoiioiogdfkldfg     500:Login failed.  ____________________A    [5] See The CCSO Nameserver - A Description, S. Dorner and  P. A Pomes,  for a description of Nameserver field description proper-  ties.                       A 6                      The CCSO Nameserver Server-Client Protocol          login s-dorner.     301:aksjdsflkajajeruopqwda,mcdfkklqopakdjl     clear mysecret      200:s-dorner:Hi how are you?       logout    ? Exits login or hero mode, entering anonymous mode.  The connec-  tion is not closed, however.   Example   
     logout
     200:Ok       fields [field...]     < With no arguments, lists all field descriptions.  With field? names as arguments, descriptions of the named fields are given. : The second number of each response is the field id number.   Example   
     fieldsA     -200:6:alias:max 32 Indexed Lookup Public Default Change Turn 6     -200:6:alias:Unique name for user, chosen by user.4     -200:3:name:max 64 Indexed Lookup Public Default     -200:3:name:Full name.     ... 4     -200:24:def_account:Default account for printing     200:Ok.        add field=value...    A Creates a nameserver entry with the given fields.  Note that this A command adds an entry, not a field; to add a field to an existing A entry, the change command should be used.  Hero mode is required.    Examples  2     add name="churchill winston" address="england"+     511:You may not add Nameserver entries. 2     add name="churchill winston" address="england"     200:Ok.                     A The CCSO Nameserver Server-Client Protocol                      7      delete [field=]value...     ? Deletes one or more nameserver entries.  Note that this command A deletes an entry, not a field; to remove a field from an existing A entry, the change command should be used.  Hero mode is required.    Example        delete winston churchill     200:1 entries deleted.       siteinfo    ? Returns information about the server's site.  Some servers will A provide more information than others; clients should be ready for @ specific items to be missing, or for the whole command not to be implemented.   Defined data items are:   5     Maildomain - domain to use for phquery-type mail. 3     Mailfield - field to use for phquery-type mail. .     Administrator - guru in charge of service.F     Passwords - person in charge of ordinary password/change requests.     Example        siteinfo     -200:1:maildomain:uiuc.edu     -200:2:mailfield:alias*     -200:3:administrator:s-dorner@uiuc.edu&     -200:4:passwords:nameserv@uiuc.edu     200:Ok.        set option[=value]...     + Sets an option for this nameserver session.    Examples       set verbose=off 
     200:Done.      set language=french       -513:language:unknown option     513:No option recognized.                     A 8                      The CCSO Nameserver Server-Client Protocol      id information    ? Enters the given information in the Nameserver logs.  This com- ? mand is used by the CCSO Nameserver client to enter the user id  of the person running it.    Example   
     id 103     200:Thanks.        status    , Prints the current status of the Nameserver.   Examples  
     status     200:Database ready. 
     status"     201:Database ready, read-only.      ! help [{native|client} [topic...]]     A Prints help files for the Nameserver.  If client is specified, it = should be a valid Nameserver client identifier, such as "ph". > The client-specific help will first be searched for topic, and> then the native help will be searched.  If topic is omitted, a? list of all available help texts will be returned.  If "native" ? or client are also omitted, a list of clients will be returned.   ? The second number of each response is the help text index; this 9 number is incremented each time a new topic text is being  printed.   Examples       help+     -200:1:The following clients have help:      -200:1:native   ph     200:Ok.      help native 4     -200:1:These "native" help topics are available:/     -200:1:100              401             505      ...      200:Ok.                     A The CCSO Nameserver Server-Client Protocol                      9          help ph 0     -200:1:These "ph" help topics are available:G     -200:1:edit            login           password        uiuc.general      ... 9     -200:2:These "native" help topics are also available:      -200:2:site        policy      ...      200:Ok.      help ph add      -200:1:add: 8     -200:1:  SYNTAX: add name-of-field=value-of-field...     ...      200:Ok.        quit stop exit    @ Ends a nameserver session.  Qi will break the connection.  These) commands are synonymous with one another.    Example        quit     200:Bye!                                                                            &                            APPENDIX  A    (                          Command Summary      3           query [field=]value...  [return field...] 0           ph [field=]value...  [return field...]6           change [field=]value...  make field=value...           login alias            answer code            clear password           logout           fields [field...]            add field=value...!           delete [field=]value...            set option[=value]...            id information           status           siteinfo+           help [{native|client} [topic...]]            quit           exit           stop                                                            A 10                     The CCSO Nameserver Server-Client Protocol                     &                            APPENDIX  B    &                           Result Codes      !    100     In progress (general). #    101     Echo of current command. /    102     Count of number of matches to query.     200     Success (general). )    201     Database ready, but read only. &    300     More information (general).    301     Encrypt this string. %    400     Temporary error (general). #    401     Internal database error. 3    402     Lock not obtained within timeout period. +    475     Database unavailable; try later. %    500     Permanent error (general).     501     No matches to query. %    502     Too many matches to query. 4    503     Not authorized for requested information.8    504     Not authorized for requested search criteria.4    505     Not authorized to change requested field.9    506     Request refused; must be logged in to execute.      507     Field does not exist.3    508     Field is not present in requested entry.      509     Alias already in use./    510     Not authorized to change this entry. )    511     Not authorized to add entries.     512     Illegal value.     513     Unknown option.    514     Unknown command. %    515     No indexed field in query. (    516     No authorization for request.:    517     Operation failed because database is read only.7    518     Too many entries selected by change command. $    520     CPU usage limit exceeded.>    521     Change command would have overriden existing field,*            and the "addonly" option is on.-    522     Attempt to view "Encrypted" field. (    523     Expecting "answer" or "clear"4    524     Names of help topics may not contain "/".    598     Command unknown.     599     Syntax error.                    A The CCSO Nameserver Server-Client Protocol                     11       