#
# File:		INSTALL
# Author:	G. Paul Ziemba <paul@alantec.com>
# SCCS:		@(#)INSTALL	1.8 3/2/93
# Purpose:	installation instructions
#

Bug reports
-----------

    Send them to me at the email address shown above.


What other pieces do I need to get tcpr running?
------------------------------------------------

    Obviously, you'll need perl.
    
    In addition, you'll need to get one of the packages that allows
you to filter incoming connections by address. We use Wietse Venema's
fine log_tcp software, which goes between inetd and the various network
daemons.

How does it work?
-----------------

    (This section has been moved to the file HOW-IT-WORKS)



Ok, how do I install tcpr?
--------------------------

    1. Edit Makefile, in particular, the following items:
	a. INST_PATH - set this to the location where you want the
	   executables to be installed
	b. INST_OWNER and INST_GROUP - set these to the desired owner
	   and group of the executables
	c. INST_MODE - set to the desired mode of the executables

	d. RELAYHOST - the name of the firewall host whereon the
	   server code runs
	e. EXEC_PATH - directory where the installed tcprelay program
	   can be found. Usually this will be just ${INST_DEST}, but
	   some sites (such as ours) use different paths for
	   installation and execution.
	e. PERL_PATH - full path name of the perl program.

	f. NETSTATPATH, IFCONFIGPATH, LOGGERPATH -
	   These are search paths  to be used by tcprelay to find
	   the respective system programs. Each of these may be:

		1) a colon-separated lists of directories, or
		2) a single directory, or
		3) a full pathname of an executable.

	   In general you can probably leave these alone, since the
	   default path specified in the Makefile is adequate for
	   most places, but if not, you can change these.

	g. CHARMODE_PORT - leave this undefined unless you are certain
	   you need it. It will break some telnets. See the discussion
	   on telnet linemode, below, after you have installed everything.


    2. Build the executables (i.e., substitute values you just defined
       into the executable versions of the scripts):

	    % make all

    3. Install the executables:

	    % make install

    4. Define the port numbers in your services database. You can do
       this by adding the following line to your /etc/services file(s).
       Of course, sites that run NIS (nee YP) will need to push a
       new services map.

	tcprpm          1090/tcp        # tcp relay port mapper service

    5. Edit /etc/inetd.conf on the firewall (relay) machine to start
       up the tcprpmd program.
       
	WARNING:  You MUST use some sort of filtering mechanism, such as
		  the log_tcp software, to restrict the set of remote
		  hosts that can access this server. If you do not, you
		  will destroy any protection your firewall gives you!!

	Add a line like the following to /etc/inetd.conf:

	   tcprpm  stream  tcp     nowait  nobody  /usr/etc/log_tcpd tcprpmd

	Configure your filters to permit access to this server from
	your inside hosts only.

    6. verify that the server runs by telneting to the relay host

	    % telnet relayhost tcprpm

       The server program should respond with a "ready" message. Type
       "quit" to exit.

    7. If you want to turn on debug logging, see README-debug.


Running tcpr
------------

Invoke the clients as

	% ptelnet remote.host.name
	% pftp remote.host.name


Telnet line mode
----------------

    Some telnets default to line-mode if they do not connect to port
23. There are several possible remedies for this. One way of dealing
with it is to escape to telnet command mode and set mode char. Here
are some other possibilities for a more permanent fix:

    The new bsd client seems to interpret a leading hyphen on the
port number argument as a request to use character mode. If your
telnet supports this (it might not be documented, so you'll just
have to try it out), define CHARMODE_PORT to be a single hyphen
in the Makefile, and then rebuild and install pclient.

    If this solves the problem, you're all set. If, however, telnet
gets confused when you invoke ptelnet, you can either comment out
the CHARMODE_PORT definition, rebuild, and reinstall, or you can
try building a telnet client that interprets the hyphen properly.

    The bsd telnet client is available from fine ftp sites everywhere;
if you succeed in building a client telnet that does the right thing,
I'd be interested in hearing about it, so I can document the system
type here.
