$Modified: Thu Sep  9 16:46:55 1993 by cwilson $

sherwood/irix/cmd/ktools/README

Quick rundown of operation.  Feel free to add your comments.  :-)

Ktools are front ends to accessing machines hooked up to Annex boxes
(terminal servers).  Instead of trying to remember what port on what
annex a machine's console is connected to, a simple 'kcons fubar' will
do the trick.

kcons and kgrab have one difference - kgrab puts the telnet session
inside an xwsh.

ksteal steals a connection from another user, or resets a port.

kwho, kfree, and klist list machine status and availability.

kreset attempts to reset the machine (ie, NMI, push the button).  This
requires additional hardware, either 
	1) a System Controller connection on Everest systems 
or
	2) dangling wires soldered to the reset button connected to
	   some sort of relay box on everything else.

Currently, kreset only groks system controller and 'real_reset'
resettable machines.

-----

ktools have the notion of classes -- machines are in classes, thus
limiting the scope of the view. The envariable KTOOLS_CLASS determines
what class is active, this is a colon seperated list.  'klist -c'
lists the available classes.

If KTOOLS_CLASS is not set, all classes will be looked at.

***** It would be a good enhancement to "disable" some classes unless
      specified, ie, a hidden class, or such.

Access lists are possible; there is space allocated in the map but it
currently isn't implimented by anything.  Easy to add.

-----

all but kwho are perl programs.  kcons, kgrab, ksteal, kfree, and
klist are one program.  

Man pages are out of date, describing the old versions.

there is a -steal option to kcons and kgrab that does the same thing
as 'ksteal -grab machine' or 'ksteal machine' would do.  (ie, ksteal
is a hangover from before).

the -f option resets the port via na regardless of if the port is in
use or not.  

-lock specifies that the machine cannot be stolen. (as long as
everyone plays nice).

kgrab has the notion that it should fork off an addition xwsh for each
console grabbed with the KDBXPORT envariable set.  This can be
disabled by the -nodebug | -nodbg flag to kcons/kgrab.

$HOME/.kgrabrc holds configurable things.  Look at the code or
sample.kgrabrc for ideas.

-noyp tells the tools to look in /usr/annex/ktools.map for
configuration info instead of YP.  ktools.map is generated via Makemap
from portsfile.new; see below.

-----

All ktools use the yp map 'ktools' for the configuration information.
This map is generated from portsfile.new via Makemap, ala
     Makemap -u < portsfile.new > ktools.map
the -u flag tells Makemap to push the new annex configuration to the
annexes.

kwho works because kcons/kgrab set the user_name field in the annex
via 'na'.  

machines are named "machine_con_X", where X is the # of the cpu that
the port is attatched to, ie babylon_con_0, babylon_con_1, etc.  There
is the capabilty for debug consoles to be hooked up (this only makes
sense on single-cpu and power series machines); they are called
"machine_dbg_X".   Everest class machines access the various consoles
via either the system controller or idbg/symmon; Everest style
machines have 3 serial ports *per IO4*, CPUs have no serial ports
(that are easily accessable, anyway).

All tools look for a "progname_version" entry to determine if there is
an updated version of the tools available.  This version is slurped
from the RCS identifier in the code.

----

The tools are an inst image, available from
babylon.wpd:/usr/dist/misc/ktools.  Source is in the /sherwood tree in
irix/cmd/ktools.   Other source (na, rtelnetd) has yet to be checked
in.

na and rtelnetd have been modified.  na has the permissions removed
so anyone can run it.  rtelnetd looks for a /usr/annex/portsfile file
to determine what ports to listen to.  This is out of date and needs
to be changed -- rtelnetd should look at the YP map and also wake up
every half hour and check for changes to the ktools.map (this will
require putting a version identifier into the ktools map).

---