Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/3/3543/UCSPI

Text File | 1991-06-26 | 9.2 KB | 207 lines

UNIX Client-Server Program Interface, UCSPI-1991
Copyright 1991, Daniel J. Bernstein


1. Introduction

This document describes the UNIX Client-Server Program Interface, UCSPI
(ooks-pie), a standard program-based interface to client-server
communications tools under UNIX and its variants. (UNIX is a trademark
of AT&T.)

UCSPI is designed to solve several problems. First, although most
networked applications today are essentially independent of the
underlying communications protocol, each program must provide direct
support for each protocol. To run a TCP/IP program over DECnet or
through other IPC mechanisms requires rewriting and recompiling the
program. In contrast, an application written for UCSPI will work without
change over any communications medium.

Second, no standard tools are provided for shell scripts to take
advantage of networking. A UCSPI-compliant communications tool is
automatically usable within a shell script or from other languages.

Third, current applications have no mechanism for passing information
about a communications link. A typical TCP/IP connection to a BSD
machine may go through inetd, an access controller, and one or two
applications. Each level may do several system calls, disk reads, and
network requests for a name lookup and possibly authentication, instead
of getting the information once and passing it down to the next level.
In the case of logins, a user shell cannot even determine reliably where
the connection is from. In contrast, a UCSPI-compliant tool will collect
all necessary information and pass it through environment variables to
the lower layers.

A program is not compliant with UCSPI-1991 if it does not satisfy any
rule marked MUST. It is compliant if it satisfies all the rules marked
MUST. In that case, it is unconditionally compliant if it satisfies all
the rules marked SHOULD, and conditionally compliant otherwise.


2. The general UCSPI interface

UCSPI clients and servers are executable programs. They MUST accept a
command line in the following general format:

  <program> <options> <address> <userprogram> <arg...>

Here <program> is the name of the client or server, <options> are zero
or more option arguments, <address> is a protocol-specific address,
<userprogram> is a user-specified program to run upon any connection,
and <arg...> are zero or more arguments to pass through to <userprogram>
without interpretation.

UCSPI killers are executable programs. They MUST accept a command line
in the following general format:

  <program> <options> <address>

Each client, server, and killer MUST support some protocol, as defined
below. <address> SHOULD take up a constant number of arguments, as
defined by the protocol. <options> SHOULD be processed by the getopt
standard; in particular, an argument of -- SHOULD terminate <options>.

If <program> is a client or server, it MUST change descriptors 6 and 7
and certain environment variables as described below before executing
<userprogram>. <program> MUST NOT interpret, quote, or unquote <arg...>
in any way. <program> may or may not fork before executing
<userprogram>. <program> SHOULD NOT change its process state in any
other way before executing <userprogram>. <program> SHOULD close
descriptors 6 and 7 immediately upon entry.

<program> MUST NOT assume that any other particular descriptors are open
or closed. <program> may assume that a certain number of descriptors are
available. <program> SHOULD NOT assume anything else about its process
state; in particular, <program> SHOULD NOT attempt to find its
controlling terminal device, and <program> SHOULD NOT use getlogin().


3. Servers

If <program> is a UCSPI server, it MUST wait for a client to connect to
<address>. It SHOULD NOT accept connections from clients that do not
support the same protocol. Upon accepting a connection, it MUST spawn
<userprogram> with the given <arg...>, descriptor 6 reading from the
connection, and descriptor 7 writing to the connection. It MUST then
continue accepting connections to the same <address>.

<program> MUST set the following environment variables for
<userprogram>: PROTO=<PROTO>, where <PROTO> is the communications
protocol used by the connection; <PROTO>LOCAL=<serveraddress>, where
<serveraddress> is <address> in a server format defined by the protocol;
<PROTO>REMOTE=<clientaddress>, where <clientaddress> is some information
about the client in a client format defined by the protocol. <PROTO>
MUST consist of characters selected from ABCDEFGHIJKLMNOPQRSTUVWXYZ,
abcdefghijklmnopqrstuvwxyz, and 0123456789; it MUST NOT be longer than
100 characters. <serveraddress> and <clientaddress> SHOULD use solely
printable ASCII characters, SHOULD have a predefined maximum length,
and MUST NOT contain newline or null.

A server SHOULD accept the following options: -q to turn off all error
messages; -Q to turn on error messages, negating any previous -q; -4 to
immediately write the value of <PROTO>LOCAL, followed by a newline, to
descriptor 4, and then close descriptor 4.

If the server receives signal SIGTERM, it MUST exit with exit code 0;
this SHOULD NOT terminate any current connections. If the server cannot
perform its functions, it MUST exit with a nonzero exit code. The server
SHOULD interpret SIGINT the same way as SIGTERM.


4. Clients

If <program> is a UCSPI client, it MUST connect to a server at
<address>. It SHOULD NOT connect to a server that does not support the
same protocol. Upon connecting, it MUST spawn <userprogram> with the
given <arg...>, descriptor 6 reading from the connection, and descriptor
7 writing to the connection. It SHOULD NOT make further connections.

<program> MUST set the following environment variables for
<userprogram>: PROTO=<PROTO>, <PROTO>LOCAL=<clientaddress>, and
<PROTO>REMOTE=<serveraddress>. Here <PROTO>, <clientaddress>, and
<remoteaddress> are under the same rules as for servers, but note that
the roles of <PROTO>LOCAL and <PROTO>REMOTE are reversed. The protocol
may allow <clientaddress> and <serveraddress> to be only partially
defined for a given connection, so the client's <PROTO>LOCAL may not
agree with the server's <PROTO>REMOTE, and vice versa.

A client SHOULD accept the following options: -q to turn off all error
messages; -Q to turn on error messages, negating any previous -q.

If the client cannot perform its functions, it MUST exit with a nonzero
exit code.


5. Killers

If <program> is a UCSPI killer, it MUST tell a server at <address> to
immediately stop accepting connections, just as if the server process
had received SIGTERM. It SHOULD NOT have this effect upon a server that
does not support the same protocol. The server may or may not accept the
kill request.

A killer SHOULD accept the following options: -q to turn off all error
messages; -Q to turn on error messages, negating any previous -q.

If the killer cannot perform its functions, it MUST exit with a nonzero
exit code.


6. Protocols

A protocol MUST define at least the following information: Its name,
<PROTO>. The format and meaning of <address>. The number of arguments
<address> takes, or a notice that it does not take a constant number of
arguments. Client and server address format. The maximum lengths of
<serveraddress> and <clientaddress>, or a notice that they may grow to
any length. The address character set, if it is not merely alphanumeric.

A protocol may define the following information, and more: Supported
options. The forking behavior of clients and servers. Any changes to the
process state not required by UCSPI. The implementation of the
underlying protocol, and how it interacts with other protocols. The
nature of the descriptors passed to <userprogram>. The preferred names
of the client, server, and killer programs. The circumstances under
which a server will ignore a killer.

It is expected that all protocols will provide reliable two-way
full-duplex strictly ordered not necessarily timed stream communication,
though some protocols may also provide other types of communication
(e.g., expedited [``out-of-band''] transmission, in which the stream is
no longer ordered).

All clients and servers must obey any rules imposed by a protocol in
order to support that protocol. If a program supporting a protocol
cannot be unconditionally compliant with UCSPI-1991, the protocol is
at most conditionally compliant.


7. Protocol management

Public protocol definitions may be registered with the UCSPI
Administrator. The UCSPI Administrator will normally refuse a
registration request only on the grounds of a namespace problem, and in
that case he will suggest an acceptable name.

All protocol names beginning with X are reserved for experimental or
nonstandard use. All protocol names beginning with x are reserved for
extended namespaces whose management is allocated to other authorities.

Further requests for interpretation or revision of UCSPI should be sent
to the UCSPI Administrator. The UCSPI Administrator may designate one or
more reference implementations of a registered protocol, and where the
reference implementation establishes an interpretation not required by
this document but not in conflict with this document, that
interpretation should be considered binding until the UCSPI standard is
revised.


The following protocol names have been registered as of 6/16/91:

  TCP
  UNDOM


UCSPI Administrator
Daniel J. Bernstein, [e-mail]