The CCSO Nameserver Server-Client Protocol

                              by
               Steven Dorner   [email protected]
          Computer and Communications Services Office
               University of Illinois at Urbana

                         April 2, 1990


                          updated by
               Paul Pomes   [email protected]
          Computer and Communications Services Office
               University of Illinois at Urbana

                        August 2, 1992





Introduction

This document describes the protocol used by the CCSO Nameserver.
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 this
client.  First, our client does not run on every system.
Secondly, the Nameserver is potentially of use for more than just
human lookup of information; other programs (such as mail
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

The general format of the protocol is request/response, like that
of FTP;[1] the client makes requests, and the server responds to
them.  The conversation is in "netascii", with a carriage

____________________
  Converted to portable n/troff format using the -me macros from
funky Next WriteNow format (icch).
  [1]  See  RFC-959, File Transfer Protocol (FTP), J. Postel and
J. Reynolds.












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-
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
"\\" 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:

    result code:[entry index:][field name:]text

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 result
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 the
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-
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.

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.











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.
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

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 is
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.




____________________
  [4] See The CCSO Nameserver - A Description, S. Dorner and  P.
Pomes, for a description of Nameserver modes.












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.
   -200:1:         email: [email protected]
   -200:1:         phone: (w) 244-1765
   -200:1:       address: 181 DCL, MC 256
   -200:1:              : 1201 W. Washington, C, 61821
   -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.
   -200:1:         email: [email protected]
   -200:1:         phone: (w) 244-1765
   -200:1:       address: 181 DCL, MC 256
   -200:1:              : 1201 W. Washington, C, 61821
   -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
   -508:1:         hours: Not present in entry.
   -200:2:         alias: j-dorner
   -508:2:         hours: Not present in entry.
   -200:3:         alias: s-dorner
   -200:3:         hours: 8-4 weekdays
   -200:4:         alias: j-dorner1
   -508:4:         hours: Not present in entry.
   200:Ok.
   query alias=s-dorner return id
   -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 search
criteria from the fields to be changed.  The change command works
in hero mode, or in login mode if applied to fields whose












The CCSO Nameserver Server-Client Protocol                      5


description contain the Change property[5] in the entry of the
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
should be done with the password of the logged in user.

Examples

   change alias=s-dorner make hours="when the sun shines"
   506:You must be logged in to use this command.
   change steven dorner make hours=""
   200:1 entry changed.
   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
   518:Too many entries (3) selected; limit is 2.
   change stanley ikenberry make email=zzz@xxx
   -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 will
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.
____________________
  [5] See The CCSO Nameserver - A Description, S. Dorner and  P.
Pomes,  for a description of Nameserver field description proper-
ties.











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

   fields
   -200:6:alias:max 32 Indexed Lookup Public Default Change Turn
   -200:6:alias:Unique name for user, chosen by user.
   -200:3:name:max 64 Indexed Lookup Public Default
   -200:3:name:Full name.
   ...
   -200:24:def_account:Default account for printing
   200:Ok.



add field=value...


Creates a nameserver entry with the given fields.  Note that this
command adds an entry, not a field; to add a field to an existing
entry, the change command should be used.  Hero mode is required.

Examples

   add name="churchill winston" address="england"
   511:You may not add Nameserver entries.
   add name="churchill winston" address="england"
   200:Ok.










The CCSO Nameserver Server-Client Protocol                      7


delete [field=]value...


Deletes one or more nameserver entries.  Note that this command
deletes an entry, not a field; to remove a field from an existing
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
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:

   Maildomain - domain to use for phquery-type mail.
   Mailfield - field to use for phquery-type mail.
   Administrator - guru in charge of service.
   Passwords - person in charge of ordinary password/change requests.


Example

   siteinfo
   -200:1:maildomain:uiuc.edu
   -200:2:mailfield:alias
   -200:3:administrator:[email protected]
   -200:4:passwords:[email protected]
   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.










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...]]


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
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
   -200:1:These "native" help topics are available:
   -200:1:100              401             505
   ...
   200:Ok.










The CCSO Nameserver Server-Client Protocol                      9


   help ph
   -200:1:These "ph" help topics are available:
   -200:1:edit            login           password        uiuc.general
   ...
   -200:2:These "native" help topics are also available:
   -200:2:site        policy
   ...
   200:Ok.
   help ph add
   -200:1:add:
   -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



         query [field=]value...  [return field...]
         ph [field=]value...  [return field...]
         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






























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.
  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.
  503     Not authorized for requested information.
  504     Not authorized for requested search criteria.
  505     Not authorized to change requested field.
  506     Request refused; must be logged in to execute.
  507     Field does not exist.
  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.
  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"
  524     Names of help topics may not contain "/".
  598     Command unknown.
  599     Syntax error.










The CCSO Nameserver Server-Client Protocol                     11

You are viewing proxied material from bitreich.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.