#
# File:		INSTALL
# Author:	G. Paul Ziemba <paul@alantec.com>
# SCCS:		@(#)INSTALL	1.9 9/29/94
# Purpose:	installation instructions
#

Contents
--------

	1. Bug reports
	2. Prerequisites
	3. The procedure

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

    Send them to tcpr-bugs@alantec.com.


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

    Obviously, you'll need perl. Tcpr was developed with perl 4; it
probably won't work with earlier versions.
    
    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.


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

    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.

	h. CONFIGFILE - this defines the location of the configuration
	   file. At present, only the logging configuration may be
	   specified here (i.e., what types of messages get sent to
	   syslog, and with what facility/priority).

    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. Debug logging.
       
       If you give the -l switch to tcprpmd, it will log information
       to syslog with facilities daemon.debug and daemon.info. It's
       usually a good idea to turn on logging when you set up tcpr
       so that you can verify its operation (and debug your installation).

       See below for info on customizing the logging output.



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

Invoke the clients as

	% ptelnet remote.host.name

	% pftp remote.host.name

	% pfinger user@host
	% pfinger @host

	% pwhois user@host
	% pwhois @host


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.


Logging Customization
---------------------

The old way: the -d switch to tcprelay turned on messages to stderr
and syslog.

The new way: -d controls output to stderr, and -l controls output
to syslog.

By default, syslog messages are logged at daemon.info or daemon.debug.
You can override the default behavior with a config file. By default,
the name of the config file is /etc/tcpr.conf, but you can specify
a different file name to tcprpmd with the -c option (either -c<FILE>
or -c <FILE> is permitted).

Config file format:

	1. Comments start with # and end with a newline.

	2. Leading and trailing whitespace on a line is ignored.

	3. Logging control lines have three words:

	   a. The first word is the keyword LOG.

	   b. The second word is one of (default, request, connect,
	      alarm, fork, exit, interface, ftp, bytecount). This word
	      identifies the particular tcpr operation being logged.
	      If you omit one of the operations from the config file,
	      it will be logged with the priority given for "default".

	   c. The third word is the priority argument to be given to
	      the logger(1) program, e.g., "daemon.debug". You may also
	      specify this priority as "null", in which case these
	      events are not logged at all.

Here is a sample config file:
#
# tcpr.conf - tcpr logging configuration
#
LOG     default         daemon.debug
LOG     request         daemon.info
LOG     connect         daemon.info
LOG     alarm           null
LOG     fork            daemon.debug
LOG     exit            daemon.debug
LOG     interface       daemon.debug
LOG     ftp             daemon.debug
LOG     bytecount       daemon.debug


