maddog.wpd:/usr/annex/README		Last updated by cwilson, 92/08/05

---------------------------------------------------
What is this Annex Box and why do I want to use it?
---------------------------------------------------

An Annex box is an ethernet terminal server that can serve upto 64
terminals.  We are using them 'in reverse' to connect to machines in the OS
Lab in Building 9U and the Hardware lab in Building 7U, allowing a
telnet (or cu) session to console ports of the desired system.  

This gives you the ability to do remote software installs, debugging,
testing, anything that doesn't need a graphics head.

Along with the Annex box, there is an I/O board in maddog that
controls the reset switch on the machines connected to the Annex box
in 9U.  This allows remote resetting of machines as well as remote
console access, a boon for machines stuck in a kernel panic.


--------------------------------
What's TELNET, CU, and RTELNETD?
--------------------------------

TELNET, CU, and RTELNETD are all communications programs of various flavors:  

TELNET uses the TELNET protocol to talk to the desired host, passing
along DISPLAY, SHELL, and TERM envariables.  The default escape
character for TELNET is ^].  To end a TELNET session, hit the escape
character followed by 'c'.  ( ^]c <return> )

CU is a UUCP program that is normally used to talk to modems and
dialers.  However, since it will talk to any device, it can be used in
conjunction with rtelnetd.  The default escape character for CU is
`~`.  To end a CU session, hit the escape character followed by '.'.
( <return> ~. <return> )

RTELNETD gives telnet capability to programs that don't understand
networks that well.  Upon startup, RTELNETD scans the
/usr/annex/portsfile, creates appropriate entries in /dev/annex, and
proceeds to listen to these devices.  When one of the devices is
opened (via 'cu', for example), it starts a TELNET session to the
corresponding host and acts as a bridge between the host process and
the TELNET session.


------------------
Annex Box Programs:
------------------

o	kwho 
	     find out who is using the annex box and which machine
	     they are connected to.

o	kcons {-lock} {-cu} <machinename> {cpu#}
	      Connect via TELNET to the indicated machine's console
	      port, if not in use.  Optionally lock the port and/or
	      specify which cpu's console port to connect to.  If '-cu'
	      is specified, attempt to use CU instead of TELNET to
	      connect to the host.

o	kgrab {-lock} <machinename> 
	      Connect via TELNET to the indicated machine's console
	      port, if not in use, and start up additional xwsh's
	      connected to the console and debug ports of any
	      additional cpus on the machine. Optionally lock the
	      ports.  

o	kreset <machinename> 
	       Reset a machine that you have an annex connection to.

o	ksteal {-grab} {-f} <machinename>
	       Steal the indicated machine's console port and start a
	       kcons to the machine, if the port is not locked.  Idle
	       time must be greater than 2 hours. Mail is sent to the
	       person whom the port was stolen from.  Optionally
	       invoke kgrab instead of kcons and/or forcefully steal
	       the port if the idle time is less than two hours.

-------------------------------------
Other files that reside in /usr/annex
-------------------------------------

o	portsfile
		This is the configuration file for all the annex box
		programs that specify what host is connected to what
		annex box via which port.  

o	rtelnetd
		This is a 'chkconfig-able' deamon that does a
		'reverse' telnet from your machine to the annex box.
		Upon startup, it gropes through the portsfile and
		creates the necessary entries in /dev/annex.  
		
o	cu_devices_names and cu_system_names
		These two files contain UUCP Device and System
		specifications for use with cu.  Only hosts listed in
		these files can be reached via cu.

---------------------------------
To install the Annex Box Programs:
---------------------------------

On your machine:
   su
   mkdir /usr/annex
   cd /usr/annex
   rcp guest@maddog:/usr/annex/INSTALL .
   ./INSTALL
   exit

Now add /usr/annex to your path.

-----
NOTES:
-----

o	The escape character for a TELNET session is Ctrl-].  To close
	a kcons or kgrab connection, type Ctrl-] c <return>.

o	The annex box programs and data files are updated when the
	programs change or when machines are added to the annex box.
	An automatic update is done of all machines that have
	INSTALLed the annex box software if there is an open guest
	account. 


For questions, comments and problems about and with the Annex box and
resetter, please contact Chan Wilson (cwilson@wpd, x7006), Curt
Schimmel (curt@wpd, x1144), or Curtis Anderson (curtis@wpd, x1193).