NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt LLaanngguuaaggee
by Steven Dorner
Computing Services Office
University of Illinois
6/1/89
IInnttrroodduuccttiioonn
The language (or _p_r_o_t_o_c_o_l, if you prefer) used between the CSO
Nameserver and its clients is meant to be relatively easy to gen-
erate and to parse, so that it can be used by programs. It is
also meant to be not too onerous for use by humans directly.
GGeenneerraall FFoorrmmaatt
The general format of the language is a request/response language
like that of FTP. The conversation is in netascii, with a car-
riage return-linefeed pair separating the lines. The client
makes requests, and the server responds to them. This allows a
_t_e_l_n_e_t client to connect to the Nameserver so that users may use
the Nameserver without any intervening 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 _d_o_u_b_l_e quotes
(``"''). Any printable characters may be used in the string (ex-
cept ``"''). In addition, the sequences ``0' and ``'' may be
used to mean newline and tab, respectively.
Like FTP, numerical values will be used to indicate the
NameServer's response to requests. Unlike FTP, data will be
passed on the same connection as commands. The format for
responses will be as follows:
_n_u_m_b_e_r:_r_e_s_p_o_n_s_e
Multiline responses should preface the number with a minus sign
(``-'') on all lines of the response but the last.
Notice that since more than one specific piece of information may
be manipulated by a particular command, it is possible for parts
of a command to succeed, while other parts of the same command
fail. This will be handled as a single continued response, with
the result code changing as appropriate. Also, if a particular
field in the request is objectionable, that field should be iden-
tified after the colon following the result code. The field name
should be separated by a colon from the text of the error mes-
sage. The text of the message is primarily for human consump-
tion, and may vary from the examples given here.
As for FTP, numerical responses will be in the range 100-599,
where the leading digit has the following significance:
1: In progress
2: Success
3: More information needed
4: Temporary failure
5: Permanent failure
Specific numbers have meanings to some commands; all commands
obey the general scheme.
In practice, almost every command will generate more than one
line of response; every client should be prepared to deal with
such continued responses. It is worthwhile to note that no com-
mand is finished unless the result code (treated as a signed in-
teger) is greater than or equal to 200.
TThhee CCoommmmaannddss
qquueerryy [[ffiieelldd==]]vvaalluuee...... [[rreettuurrnn ffiieelldd......]]
This is the basic client request. It does not require (in
the common case) any identification from the client. En-
tries whose fields match the given values will be found, and
the requested fields printed. If no query fields are speci-
fied, the name field is assumed. If no return fields are
specified, default fields will be returned. Fields from
each entry will be prefaced with a sequence number, a colon,
the field name, and another colon.
Note that to view some sensitive fields, it is necessary to
login to the Nameserver. Values containing newlines will be
broken into lines and printed one line per response.
qquueerryy aalliiaass==ssddoorrnneerr
-200:1:name:Steven Dorner
-200:1:alias:sdorner
-200:1:phone:333-3339
200:1:address:189 DCL
200:1:address:1304 W. Springfield
qquueerryy ddoorrnneerr rreettuurrnn aalliiaass ""hhoommee pphhoonnee""
200-:1:alias:adorner
-508:1:home phone:This field is not present.
-200:2:alias:anotherdorner
-200:2:home phone:555-1212
-200:3:alias:sdorner
508:3:home phone:This field is not present.
qquueerryy aalliiaass==ssddoorrnneerr rreettuurrnn uunniivviidd
503:univid:You are not authorized for this information.
cchhaannggee [[ffiieelldd==]]vvaalluuee...... mmaakkee ffiieelldd==vvaalluuee......
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 user
must be logged in for change to work, and must have the au-
thority to change the fields in the entries selected by the
query portion. If it is desired delete a field, Adjacent
double quotes (``""'') should be used. Fields marked _e_n_-
_c_r_y_p_t_e_d must be encrypted before transmission to the
Nameserver. This encryption should be done with the pass-
word of the logged in user.
cchhaannggee nnaammee==iikkeennbbeerrrryy pphhoonnee==333333--33333399
510:ikenberry:You may not change this entry.
llooggiinn aalliiaass
aannsswweerr ccooddee
This is used to identify the user of a particular connec-
tion. The NameServer will respond with a random challenge,
which must be returned in encrypted form. The encryption
key will be a password known to both the NameServer and the
user (or user's trusted host). Note that this scheme pre-
cludes the use of login through a direct telnet connection
(unless the user is very good at encrypting text).
llooggoouutt
Any user identity established with a previous login will be
forgotten. The connection is not closed, however.
Examples:
llooggoouutt
200:Ok
ffiieellddss [[ffiieelldd......]]
With no arguments, echoes the contents of the NameServer's
fields.config file. Otherwise, descriptions of the named
fields are given.
Examples:
ffiieellddss
200:<too verbose to print here>
aadddd ffiieelldd==vvaalluuee......
Creates a nameserver entry with the given fields. Only cer-
tain users will be allowed to execute this command
100 In progress (general).
101 Echo of current command.
200 Success (general).
201 Database ready, but read only.
300 More information (general).
301 Encrypt this string.
400 Temporary error (general).
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 encrypted.
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.
599 Syntax error.
