#(@)rcsid = "$Header: /Nfs/blyth/glob/src/usr.bin/spad/src/RCS/README,v 1.27 1993/11/13 14:44:52 pb Exp $"

spad relies upon SunNet X.25 (we're running version 7.0) or a DEXPAND
This has been tested using a serial line on the CPU board at 9600,
an MCP board up to 132Kb, and an HSI board up to 512Kb.

It client code will also run on other systems, e.g. ULTRIX, SUNOS, HPUX, ..
For a Computer Centre with lots of hosts wanting spad, see README.binary     ||

For those upgrading only:
NB: BEFORE YOU START: decide what version of x25b structure you want.
	This is defined in x25b.h -- change line 4 as appropriate and ensure
	that all other copies (e.g. in unix-niftp sources) are up to date.
	Version 6 works even on compiler which pad structures excessively.
If you have an existing version 5 system and do not need version 6, you can
safely remain on verion 5.
If you are starting a new system, or can change everything to verion 6 easily,
use version 6.
If you have lots of systems useing version 5 and have some which need version
6, then there are a few aids to making the transition not too painful.
(If you need them, contact me for details)
You can also change it dynamically by setting X25IOVER in the makefile.

New this (1.27 93/11/13) release:
RFC931 support -- works for telnet
failures (auth, duff addresses, etc) can be logged to a file
Support for Linux

========== READ THIS AND CHECK THE OPTIONS IN THE MAKEFILE ==========
The options are:
LOGFN		default location of the accnt log ("/usr/adm/Padlog")
PROF_FILE	default location of x29profile ("/etc/x29profile")
PRIV_PROF	default filename in $HOME of user file (".x29profile")

BREAKINCHAR	default breakin character (DLE == ^P)
GATEWAY		default server names (x29-serv)
SERVERNAME	default server name and service name -- and/or number        ||

NRSDBM		define on server if there is an NRS DBM available
NRSSRC		(this is part of unix-niftp which allows fast lookups)
ADDRSP		ordered list of address spaces to be tried (null string->all)
ALAISES		set the various prefix aliases (see below).

CALLING		default calling address (TS29)
IDLE_TIMEOUT	default session timeout interval and grace interval

CMDNAME		the command name -- anything else calls the given name (spad)
DESTDIR		the pathname of the binaries (/usr/bin)
INETDB		the inetd binary (/usr/etc/in.spadd)
SPADD		if using inetd (do) then $(INETDB) else $(DESTDIR)/spadd

IPATH		The Include path (for C .h file) [ e.g. NRSDBM headers ]
LPATH		library modules	[ e.g. NRSDBM libraries ]
INSTALL		command to install (e.g. cp or install -c ..)
LNOPT		how to link the various command names (default is -s)
LNDEP		set if hard links and install used
DEXPAND_DTE	should be set to the DTE if running on a DEXPAND
DEXPAND_CHANS	Set to the channels to try (default is "AB")
SECURITY	Define this if you want to control the use of spad
AUTHFILE	Defines location of authorisation file
LOCALAUTH	define if a local_auth modula is available
SPADAUTHO	name of the module containing local_auth
TELNET		If the telnetd replacemenet is to be used, see details below.
PROMPT		Pad prompt, e.g. "\r\n%s Pad> " includes the hostname
X25IOVER	the version of the x25b protocol to use (see SERVFORM)
SYSV		Some flags which may be set for SYSV machines (see Appendix C)
SERVFORM	sprintf strings for multiple simultaneous x25b versions
RFC931D		-D to specify whether RFC931 is to be supported, and also
		what the default timeout should be.
RFC931L		-l (or whatever) to include RFC 931 library libauth-4.0-p3
		from Peter Eriksson (pen@lysator.liu.se)
ERRFILE		file to which errors (auth failure, duff host) are logged

Other spacial variable which may be set (using -Dxx=y) are:
INTR2BREAK	whether to convert a un*x intr char -> BREAK
STTY_IGN	a value which forces and stty paramater to be ignored
NOGETHOSTNAME	there is no gethostname() routine

LOOP_INTERVAL	(DEXPAND only) poll interval in uS              (500000)
MAX_POLL	(DEXPAND) Max value that POLL_INTERVAL can take (5000000)
MIN_POLL	(DEXPAND) Min value that POLL_INTERVAL can take (50000)
NO_RESET	(sun only) inhibit resets [crashes the system under SUNLINK 5]
NO_GUESS_SUN_BUGS (sun only) do not try to guess the current SunLink bugs
DEF_ROLE	(server only) the default role e.g. CLIENT or DIRECT (CLIENT)
SYSTEM_HOME	path to use for .spad.rc if no $HOME (default /etc)
======== READ THE ABOVE AND CHECK THE OPTIONS IN THE MAKEFILE =======

Same sample patches are included in make.patch.*

To install spad (other than binary -- see README.binary):                    ||

0) if LOCAL_AUTH is defined, (i.e. you want to do some additional checking of
   authorisation rights after the standard code), link spadauth.c to
   spadauthnull.c (or edit it if necessary)
1) compile it (make)
2) if SECURITY is defined, create $AUTHFILE with the entry
		ALLOW . .
	at this stage, you should be able to make (numeric) calls from your
	X.25 connected machine (spad -D 000008019006)
3) move it somewhere sensible & install links (make install)
   [ on client only, use (make client-install) ]
4) insert a "spad/tcp" service in your /etc/services file (or yp) -
	we have the lines:

spad		1127/tcp	# sun remote x.29 pad
spadg		1128/tcp	# spadg is for spad debugging

	Using SECURITY you will probably want secure sockets (<1024) if
	you want to authorise by calling username.
	If you do not use yp, then type (make services).
	If you have room, add a line
spad	tcp	/usr/etc/in.spadd
	to /etc/servers (make servers), restart inetd and it should fly.
	On systems with /etc/inetd.conf (e.g. ultrix) add the line
spad	stream	tcp	nowait	/where/you/put/it	in.spadd
	or on SUNOS4.0, use
spad	stream	tcp	nowait	root /where/you/put/it	in.spadd
	e.g. ".. nowait root /usr/bin/spad in.spadd"

	Otherwise, start spadd in /etc/rc.
5) update your /etc/hosts file to include x29-serv as an alias for the machine
	which is going to act as the gateway.  On thet machine, kill off and
	restart the inetd.  You should now be able to make make numeric calls
	from clients (spad 000008019006).
	If you have define SECURITY, there should be a line in $AUTHFILE
		ALLOW root STARTSERVER
6) If you do not have a unix-niftp NRS dbm (-DNRSDBM in makefile), construct
	a directory.
7) If using SECURITY create a real $AUTHFILE (see the example file)
8) If using telnetd code, ...
9) MOST IMPORTANT !! If you found any mistakes, problems or cofusing wording,
   PLEASE let me know (preferably with corrections) so that others do not need
   to suffer as you have.

For NeXT users:
> The NeXT has the files /etc/hosts and /etc/services BUT DOESN'T USE THEM!!
> Instead it uses a system called netinfo. If any other NeXT user mails you
> describing the same problem, suggest that use NetInfoManager to create
> a new service called spad. Give it the following properties and values:
> 
> 	Property	Value
> 
> 	port		1127
> 	protocol	tcp
> 	name		spad
> 
> Then use NetManager to create a host called x29-serv in the root domain
> with the same IP and ethernet address as the server (there doesn't appear
> to be an alias type entry allowed in the hosts database of NetInfo).

If you enhance spad, please let us know. We're aware it could be more robust
w.r.t. X.25 RESET, signals, and so on, but it works at the moment.

Enjoy it!

Originally:	Alasdair <arawsthorne@man.cs.ux>
Mainly:		Piete Brooks <pb@uk.ac.cam.cl>
Help by:	Andrew <Andrew.Findlay@brunel>
NeXT info:	andy@cd.psw.ac.uk


Appendix A: aliases.

When looking up a name in the x29profile file, spad tries to prefix
(or suffix) each name with some local domain components.
The default values are set in the Makefile by setting ALIAS<n>_PREFIX to a
string (where <n> is 1 - 20).
These may be over-ridden at runtime by setting SPADALIAS<n>_PREFIX in the
environment, or setting SPADALIAS_PREFIX to a comma separated list of domains.
Each prefix should end in a domain separator, e.g. "uk.ac.".
If a suffix is wanted, the "prefix" should start with a domain separator,
e.g. ".berkeley.edu".
Null preficies are ignored.

Appendix B: telnetd replacement.

To make calls from telnet clients which cannot make calls to a non-standard
port number, it is necessary to replace the standard telnetd server on the
gateway machine by spad.
This can be achived either by editing the inetd conf file to invoke spad as
in.tpadd, or by moving the standard in.telnetd to in.Telnetd (or some such --
set TELNETD1 accordingly) and making in.telnetd a link to spad.

When a telnetd call is made, spad will ask the user for the remote host to
call, or if no host is given, it will invoke in.Telnetd (or whatever TELNETD1
is set to) and if that fails it will try in.telnetd (i.e. TELNETD2).

If it is desired that certain LAN hosts can only call one X.25 host, there is
sample code to show how to achive this.
Any other requirements can be code instead - please send me any examples.

Appendix C: SYS V

This code runs as client only mode on HPUX and ICL CLAN which are SYS V.

The flags which might be relevant for some SYS V systems are:

	MEMCPY	use memcpy() rather than bcopy()
	MEMSET	use memset() rather than bzero()
	STRCHR	use strchr() rather than index()
	NOSGTTY	don't #include <sgtty.h>, just use <termio.h>
	NOSYSTIME don't use <sys/time.h> but <time.h>


Appendix D: Other code

There are some other goodies available which us the the same "X.25 over TCP"
protcol which maye be of ineterest to some people. If there are are any you
would be interested in, please email me.

x29out	send data to a remote terminal (normally a pad printer).
x29in	accept data from a remote host (e.g. emulate a pad printer).
x29d	(related) awaits incoming X29 calls [also ybtsd for the UK]
x25r	forward an incoming X.25 call to a TCP only host.

c-nrs	process the UK NRS directory to a useable format.
niftp	unix-niftp supports the UK coloured books over x25b.
UKUUCP	UKUUCP has a driver which talks X.29 (e.g. f proto) over x25b.



--------------------------------------- ------------------------------------

Changes 1.4 -> 1.5:

Only generate x29out if wanted
Handle local authorisation better.
allow setting of x25b version in the makefile (X25IOVER)
use $(CC) to do the link steps (rather than cc)
-C selects the channel to use (for SunLink 6.0)
