#
# File:		PROTOCOL
# Author:	G. Paul Ziemba <paul@alantec.com>
# SCCS:		@(#)PROTOCOL	1.2 2/24/95
# Purpose:	tcpr protocol description
#

		TCPR Protocol Description
		-------------------------

		    G. Paul Ziemba
		    <paul@alantec.com>
		    24 February 1995

ABSTRACT

The tcpr protocol is used by clients behind firewalls to set up
proxy stream (TCP) connections to distant hosts beyond the firewall.
A proxy server running on the firewall machine accepts requests,
initiates stream connections to distant hosts, and passes connection
information back to clients.


MODEL

When a client-TCPR process desires to set up a proxy connection
across a firewall, it establishes a full-duplex TCP control channel
to the server-TCPR.  TCPR commands are generated by the
client-TCPR and sent to the server-TCPR. TCPR replies are sent
from the server-TCPR in response to the commands.

    The client-TCPR informs the server-TCPR, via commands on the
control channel, of the distant host and TCP port to which it
desires to open a connection. The client-TCPR may optionally
advise the server-TCPR of other incidental information, such as
the userid of the client, for logging purposes.

    The server-TCPR attempts to establish a new connection to
the distant host using parameters given by the client. Success
or failure indications are returned over the control channel to
the client-TCPR. In the event of success, the server (or its
agent) listens on a new TCP port (the proxy port) on the
server-TCPR's host, and informs the client-TCPR of the proxy
port number.

    The client-TCPR then establishes a data connection to the
server host at the proxy port number; the server-TCPR (or its
agent) relays data bidirectionally between the data connection
from the client-TCPR and the distant host.

    After the client-TCPR has received the proxy port information
from the server, the control connection is no longer needed and
may be closed.


COMMANDS


Commands sent by the client-TCPR consist of single lines of
ascii text terminated by a newline or return-newline combination.

    When the control connection is first etablished, the server
emits a "ready" message; it is reasonable for clients to await
receipt of this initial message before sending commands.

    The valid commands are shown here. Commands marked "required"
must be given to the server before the "relay" command in order to
set up a proxy connection successfully.

    Required?	Command			Comments

	Y	server <dist-host>	<dist-host> may be given
					as a dotted-quad ascii representation
					of the host's IP address, or as
					a domain name. If given as the latter,
					the server-TCPR will attempt a name-
					lookup.

	Y	service <port>		<port> may be given either as
					a numeric ascii representation
					of the TCP port number on the
					distant host, or as a service
					name of a well-known port. If given
					as the latter, the server-TCPR
					will attempt a lookup in its
					services database.

		mode ftp		indicate that the proxy connection
					will be used for FTP. The relay
					service will scan the FTP control
					stream for PORT commands and
					set up subsidiary proxy streams
					for FTP data automatically.

		relay			Initiate connection to the
					distant host.  This command
					should be given last.
					
					In the event of success, the
					response will be:

					    212 PORT <portnum>

					which indicates the proxy
					port number.


		euser <username>	Advise the server of the
					effective username of the
					client process.

		ruser <username>	Advise the server of the
					real username of the client
					process.

		nop			Do nothing.

		quit			Close the control channel.


RESPONSES

    Responses sent by the server-TCPR consist of an initial
3-digit code, followed by either a hyphen or a space, followed
by ascii text and terminated by a newline or return-newline
combination.

    Responses to a command may consist of a single line or
multiple lines. The fourth character of a line (space or hyphen)
indicates whether the line is the final line of the response:
a hyphen means that at least one more line is to follow, whereas
a space indicates that this is the final line of the response.

    Response codes are shown here. Text, except for the "212 PORT"
message, may vary.

	220 <host> tcpr-portmapper version <foo> ready
	212 PORT <portnum>
	221 Closing connection
	230 <info>
	250 Ok

	500 Syntax error
	503 Bad Command Sequence
	550 Invalid argument
	551 exec failed

    Codes starting with 2 indicate success; codes starting with 5
indicate failure.
