⟦1ac04f51d⟧

TextFile

KIP INSTALLATION INSTRUCTIONS				(6/88)

To install and run the KIP gateway code involves the following steps:

	Transfer the gateway source/binary files to a (UNIX) host.

	Compile gateway programs.

	Setup admin daemon and database.

	Edit /etc/atalk.local.

	Transfer gw.srec and prompt.config from UNIX to a Mac disk.

	Run Kinetics 'FastPath Manager' program to download gateway.

	Test gateway with 'ping' and 'ddt', 'chooser'.

	Install CAP with mods.

	Obtain and try out MacIP programs.


TRANSFER FILES

There are a number of files needed to use this gateway.  You can either
FTP these files if you have internet access, or (I believe) Kinetics
Users Group will have SONY disks available containing the same
information for a nominal copy fee.  The following files are in the
<info-mac> directory on sumex-aim.stanford.edu.  The file names are
prefixed with 'at-' in the directory to set them apart from other
info-mac files.  Use login name 'anonymous' with FTP.

kip.shar	gateway and daemon source
gw.srec		latest gateway 'binary' in S-record hex format
ddt.shar	source for the network debugger.

To obtain information about the Columbia University AppleTalk Package
for Unix, send mail to capinfo@cunixc.columbia.edu (internet),
columbia!cunixc!capinfo (uucp), or capinfo@cunixc.BITNET for more
information.

(A copy of CAP is also kept on <info-mac> at sumex under the at-cap*
prefix).


You don't have to compile any Macintosh or Kinetics source code unless
you wish to.  The file 'gw.srec' contains the latest gateway binary.
If you DO want to compile you will need a 68000 C compiler that runs
under UNIX.  We use our 4.X BSD VAX with the compiler distributed with
SUMacC.  But you can also use 68000 UNIX boxes, for example Kinetics
uses a Pyramid box.  For VAX people you can FTP these files from
sumex-aim.stanford.edu, login anonymous, directory <info-mac>.

sumacc.tar	68000 C compiler plus Mac libraries;  2.5 megabytes.
		SUMacC hasnt changed since Nov 84, so this is not a 'new'
		version.  (Also available from safe.stanford.edu).
sumacc-rmaker.shar	(dated Aug 85)
sumacc-rmaker-v2.shar	(dated Aug 86)
		Later versions of the Mac resource compiler;  I believe
		the efs.tar used the first of these but they should be
		upward compatible.


COMPILE GATEWAY PROGRAMS

Dearchive at-kip.shar into UNIX directory 'kip'.  The directory
'kip/etc' contains the following files:

	atalk.local	sample host number database, copied to /etc
	atalkad.c	appletalk admin daemon
	atalkrd.c	appletalk rebroadcast daemon (not usually needed)
	atalkatab	sample database for atalkad, copied to /etc
	b.out.h		68K object file format, used by dl68.c
	dl68.c		binary to hex conversion utility used by SUMacC;
			or use native utility, such as 'hex'.
	Makefile	makefile for C progs in this dir
	prompt.config	sample config file used by Kinetics 'prompt' program 

The directory 'kip/doc' contains documentation files:

	install		installation document
	broadcast	document explaining broadcast terminology
	ip.at		specification for IP on AppleTalk
	rev1086		documents revisions of the gateway
	rev0287
	rev0987
	rev0188
	rev0688
	stackdump	how to interpret Kinetics stack dumps


Typing 'make' in the 'kip/etc' directory will result in atalkad and other
binaries being produced.   

The 'at-gw.srec' file that you obtained in the 'TRANSFER FILES' step
can be directly downloaded to the gateway, so you can skip the gateway
compile steps in the remainder of this section if you wish.  (If so,
skip to the next section 'APPLETALK FORMS').

The makefile in the top level 'kip' directory is setup for a VAX.
Another file, makefile.68 can be used if you have a native 68000 UNIX;
unfortunately your native assembler may not understand the MIT-style
opcodes used.  If so, find a VAX(!)  If your machine doesnt support
'flexnames', edit the line in fp/kfps.h as shown:

	14c14
	< define(`flexnames')
	---
	> |# define(`flexnames')

If your UNIX prepends an '_' underscore in front of all C externals,
remove the '-Dnoprepend' from the makefile.  Now you should be able say
'make' and end up with a gw.srec file.  Gw.sym is also produced from
each load and contains the complete object file plus symbol table.

The network debugger ddt was developed on a VAX and assumes the b.out.h
object file header format produced by the MIT C compiler.  This should
be ifdefed for native compilers as well.  If you are going to
use ddt, fetch and dearchive it.  Typing 'make' in that directory
should result in a 'ddt' executable that can be copied to a directory
such as /usr/local/bin.


APPLETALK FORMS

Before we can discuss setting up the administrator daemon and database
(in the next section), we need to explain the different forms in which
appletalk exists.  'Appletalk' is the word used by Apple to describe
the protocol family that they designed.  This protocol family contains
protocols that implement various services such as name binding
(location), file access, and laserwriter printing.

The Appletalk protocol family can be used on a variety of communication
media.  For each of these media, appletalk takes on a unique 'form'
(or encapsulation) specific to that media.  Thus we can label three
different appletalk-forms:

  'Localtalk' is Appletalk on the original Apple-designed daisy-chain
  cabling system (shielded, twisted pair).  Localtalk would also refer to
  the alternate cable scheme developed by Farallon (PhoneNet) that uses
  standard phone company cables and connectors.

  'Ethertalk' is Appletalk running on ethernet hardware.  There are
  now cards for the Mac II (from Apple/3com and Kinetics) that speak
  ethertalk.  Additionally some commercial mainframe products such
  as TOPS for UNIX and Alisatalk for VMS use ethertalk.

  'Appletalk-in-IP' is Appletalk encapsulated inside IP datagrams,
  which in turn are carried on a media such as ethernet or fiber
  optics.  The advantage of putting appletalk inside of IP is that
  preexisting campus gateways and hosts dont have to be modified (at
  low levels) to understand appletalk.  There is much more equipment
  available on the market that understands the IP protocol family
  versus the relatively new Appletalk family.  For 4.X BSD derived UNIX
  machines, the CAP (Columbia Univ. Appletalk Package) software
  provides file access and print spooling capabilities.

The original KIP gateway software supported the localtalk and
appletalk-in-IP forms of appletalk.  The 0188 release of KIP added the
support of ethertalk.  Thus a single ethernet cable can support both
the ethertalk and the appletalk-in-IP encapsulations.  This is done
by assigning such ether cables TWO appletalk network numbers.  Traffic
directed to one of the net numbers goes out in ethertalk form, traffic
to the other net number goes out as appletalk-in-IP.  At a recent
Apple sponsored IP conference, this mechanism was dubbed 'doubletalk'(!)

You might encounter this confusion in terminology:  before 1987 Apple
Computer refered to the protocol family AND the physical cabling /
signaling system as 'appletalk'.  Just be aware that 'appletalk' NOW
means the protocol family and not just a particular physical
implementation such as localtalk or ethertalk.


SETUP ATALKAD AND DATABASE

The appletalk administrator daemon, /etc/atalkad, runs on only ONE of
the UNIX hosts in your organization / department.  So this document
section will only be used by your campus appletalk administrator.

Chdir to kip/etc, become su, and type 'make install' and 'make
installonce'.  The first install copies the daemon binary to /etc.  The
one-time only install copies atalkatab and atalk.local to /etc and
starts off the log file in /usr/adm/atalkalog.

You now need to edit the files /etc/atalkatab and /etc/atalk.local to
correspond to your local network configuration.  Print out and read
over the comments in atalkatab to see the format of the data.

In this example file, we show a campus using a class B network number,
128.222.s.h, where 128.222 is the class B net, 's' is the IP subnet
number of the ethernet cable, and 'h' is host number on that cable.
Remember that that there are no dependencies on subnets in the KIP
gateway code, so this example showing subnets could just as easily
have used separate class C numbers for the ethernet cables.

In the example note that the 16 bit (two byte) appletalk net number
(anet) can be written in 'dot notation', e.g. '55.13'.  This means the
upper byte of the anet is 55 and the lower byte is 13;  these values
are in decimal, so the maximum anet number would be 255.255.

For appletalk-in-IP ethernet cables there is a relation between the
IP address (combined net/host number) of a host on that cable, and the
appletalk net/node numbers of the same host.  The net number parts are
totally different, but the low byte of the IP address (host number)
corresponds exactly to the appletalk node number.  The appletalk net
and IP net numbers are only related by a line in the atalkatab file,
mapping an appletalk net number to an IP net number.

Now for administrative simplicity we have chosen to have three ranges
of anet numbers.  Anet numbers 55.XX will be used to represent
appletalk-in-IP ether cables, where XX is set equal to the third byte
of the IP address of that ether cable (i.e. the subnet number for class
B nets or simply the 3rd byte of a class C number).  And anet numbers
56.YY will be used to represent localtalk cables, where we just assign
a new number YY starting at 1 for each new cable.  Finally, anet
numbers 57.ZZ are used to represent ethertalk cables.  For your own
situation you can use whatever scheme you wish: you could use other
values than 55/56/57, or you could even decide to number all the cables
in the same range.  It's not important.

With this background you should now be able to understand the sample
file.  The first three lines describe appletalk-in-IP ether cables.
Note the 'N1' flag which means that this is an IP net number, and to
form the broadcast address we add a single '.255' to the given IP
address.  Note that your main campus IP gateways must support directed
broadcasts in one of these formats.

If your net doesn't have directed broadcast capability: (1) convince
your gateway vendor to put it in; (2) in the meantime you can use the
'H' flag in atalkatab.  The kboxes can act as 'rebroadcast' servers;
we also provide a program atalkrd.c (rebroadcast daemon) that can run
on a 4.X BSD UNIX machine.  The file 'doc/broadcast' explains
this in more detail.

After the first group of three lines in the sample atalkatab, there
follows three groups of about eight lines each.  Each of these groups
describes an appletalk-in-IP ether cable containing a kbox, the
localtalk cable / kbox, and then the configuration data for that kbox.
Probably the best way to proceed would be to use one of these groups of
seven as a template for your site.  And then for each additional kbox
at your site, dup your own template and further customize it.  Of
course you will want to delete or change all of the sample data we
provide to correspond to your site only.  Dont leave any of the
provided sample entries in your actual database.

In the following paragraph we describe the fields used in the current
configuration information.  The atalkad daemon is rather stupid when it
comes to interpreting this data.  It just treats the data as a byte
stream that is shipped to the gateway;  it has no knowledge of the
format or legal values possible in these fields.  So you have to be a
little careful.  That is why it is a good idea to dup an existing
template as a model in editing in your own data.  Note that each field
is preceded by a data type indicator;  it is very important to preserve
this type selection byte.  It also may be a little confusing, since the
'network description' line that preceeds the configuration information
does NOT use these prefix bytes.

FIELDNAME	DESCRIPTION
ipbroad		is the IP address used on the ethernet cable to do a
		broadcast on that ether cable.  Use the network number
		qualified form (NOT 255.255.255.255).
ipname		address of a name server, passed to MacIP programs.
ipdebug		address of the host allowed to run ddt.
ipfile		address of a file server, passed to MacIP programs.
ipother		four other IP addresses or long integers passed to
		MacIP programs.
atnetet		appletalk net number, ethertalk port;  this field may be
		zero if you are not using ethertalk.  Otherwise it should
		match the 'E' line that points to this kbox.
ddprangestart	is a short specifing the start of the UDP port range used to
		map well known udp ports to ddp "static assigned sockets"
flags		a long word of bit flags; see doc/rev0987
ipstatic	the number of statically assigned MacIP addresses;
		read the 'doc/ip.at' document.
ipdynamic	the number of dynamically assigned MacIP addresses;
		the gateway uses a 'range' of IP addresses on the ether
		side;  the number of addresses is 1+ipstatic+ipdynamic.
atneta		appletalk net number, localtalk port;  note that
		this should be the same number as was specified on the
		'K' line describing this kbox.
atnete		appletalk net number, appletalk-in-IP ether port; should
		match the number of the closest previous 'N' or 'H' line.

In three of the fields, you are asked to specify the appletalk network
numbers for the three different 'ports' (appletalk-forms) on the kbox:
localtalk, appletalk-in-IP, and ethertalk.  The localtalk and
appletalk-in-IP network numbers are mandatory while the ethertalk
network number is optional.  To simplify configuration, you can specify
"%n" in these fields.  The atalkad daemon will then try to fill in each
field with the correct appletalk network number.  "%n" does this by
following these rules:

  If %n is in the atnete field (e.g. refers to a appletalk-in-IP
  cable), then %n refers to the most recently seen "H" or "N"
  flagged entry that has the same network number (masked against
  255.255.255.0) as the Kinetics box in question

  If %n is in the atneta field (e.g. refers to a localtalk network)
  then %n refers to the anet number of the current 'K' line.

  If %n is in the atnetet field (e.g. refers to a ethertalk network)
  then %n refers to the most recently seen "E" flagged entry that
  has the same ip address as the kinetics box in question.

You can check your atalkatab by running atalkad in check mode by using
the "-c" flag.  "-c" with no arguments will read in the default
atalkatab and then dump it in format more oriented to human perusal.
This is useful for seeing if your "%n" entries match up to what you
expected them to.  "-c" also takes a file name as an argument that
overrides the default atalkatab.

Once /etc/atalkatab is complete, you should start the daemon,
/etc/atalkad.  You should be su for this.  Check the log file
/usr/adm/atalkalog to see if any errors were detected in parsing the
database.  Edit your /etc/rc.local to add a line to start atalkad
whenever your administrator host boots.

DDP START RANGE

In April, 1988, the NIC assigned a range of ports for using by KIP for
"static" or "well known" assigments.  In particular, it assigned:
  201 - AT-RMTP  -  AppleTalk Routing Maintenance
  202 - AT-NBP   -  AppleTalk Name Binding
  203 - AT-3     -  AppleTalk Unused
  204 - AT-ECHO  -  AppleTalk Echo
  205 - AT-5     -  AppleTalk Unused
  206 - AT-ZIS   -  AppleTalk Zone Information
  207 - AT-7     -  AppleTalk Unused
  208 - AT-8     -  AppleTalk Unused
for this purpose.

KIP had been using the range starting at 768.

The start range can now be specified in the ddprangestart
configuration field.  It is recommended that you use the new start
range value of 200 if you can.  A value of zero implies the old range
starting at 768.  CAP 5.0 allows the use of the new port range by
installing the names in /etc/services for use by getservent.  If you
do one of these, then you must do the other.

Following are the entries for /etc/services
	at-rtmp		201/udp				# udp: rtmp
	at-nbp		202/udp				# udp: nbp
	at-echo		204/udp				# udp: echo
	at-zip		206/udp				# udp: zip

WARNING: future versions of KIP and CAP will default to the new
mappings starting at 200.  The old mappings are being used now until
KIP and CAP get back into synchronization on this issue.


ETHERTALK CONSIDERATIONS

If you are using ethertalk, you will want to use the second group of
eight lines in the sample atalkatab as your template.  Note that the
'E' line points to the kbox that will be performing the ethertalk
gateway function.  

If you have more than one kbox on a given ether cable, only ONE of them
should have such an 'E' line.  This is because there will be only ONE
appletalk net number associated with that ethertalk cable and it must
point to ONE kbox.  (The kbox routing tables are such that one anet
number can only point to a single gateway).

  [If you have other kboxes on the same ether cable, you CAN set the
  'atnetet' field of those boxes to the anet number of the ethertalk.
  You would have to do this manually since the %n mechanism will not
  work.  However note the following:  Due to the way ethertalk hosts
  select a gateway (by listening to the last broadcast RTMP), the
  ethertalk host will be randomly selecting among the multiple
  kboxes.  This situation is inherent in the appletalk protocol
  specifications.]


EDIT /ETC/ATALK.LOCAL

EACH UNIX host that wishes to use CAP utilities and libraries must have
an /etc/atalk.local file.  (Atalkad doesnt need CAP).  Now that your
departmental appletalk administrator has chosen appletalk net numbers
for your local cables, you need to edit this information into
/etc/atalk.local.  This file looks like:

	# mynet mynode myzone 
	55.9 5 YourZoneName
	# bridgenet bridgenode bridgeIP
	55.9 240 128.222.9.240

Just type in the appletalk net number for the UNIX's ether cable as
the first number.  The second number will be the low byte of the
host's IP address.  The third field is the local zone name.  On the
second (noncomment) line we give the address for the 'closest' kbox.
The first and second numbers are the ANETE network number and node
numbers (note that the anete node number is always the last byte of
the ip address).  The third number is the IP address of the kbox.
(This can be a IP host name as well but since 4.2 BSD name lookup is
very slow, we recommend putting just the number here).  Note, it is
important to use the ANETE network number when specifying the location
of the Kinetics box since the anetet and aneta node numbers are not
knowable in advance.  The kbox is usually on the same ether cable as
your CAP host, but it does not have to be.  The CAP host can be on any
ether cable, as long as there is an 'N' (or 'H' with atalkrd) line in
atalkatab pointing to that cable (or host).


SETUP GW.SREC AND PROMPT.CONFIG ON MAC DISK

Each kbox must be downloaded with its program and minimal configuration
information.  These files plus the downloader must all exist on a Mac
disk.  The downloader program from Kinetics was previously called
'Prompt'.  On their latest shipments, they have renamed it 'FastPath
Manager'.  In either case the current version number is 2.0.

It also helps to have a copy of 'edit' or 'MockWrite' on the disk to
customize the prompt.config file.  So you need to use macput, efs,
kermit, etc., to put the files gw.srec and prompt.config onto this
disk.  Here is what the sample prompt.config file looks like in this
directory:

	* Config file for KFPS, KIP version, 10/86.
	*
	* A future version of the 'prompt' program will recognize
	* a line containing a 'dot format' address and convert those
	* four decimal byte values to four hex bytes(!)
	*
	* These bytes are ignored but must be left as placeholders: 
	0000 0000 FF FF FF 00 000000 000000
	* Gateway name (in this example, "gw")
	677700000000000000000000000000000000000000
	* File name (in this example, "gw.srec"): 
	67772E737265630000000000000000000000000000
	* reserved (this field should be 00FF): 
	00FF
	*
	* Start of 'mandatory' parameters, the minimum information that
	* must be supplied for the gateway to begin operation.
	*
	* IP address of myself, 'ipaddr'
	* 128.222.9.240
	80de09f0
	* IP addr of admin host
	* 128.222.9.5
	80de0905
	* IP addr of default route (nearest 'real' gateway)
	* 128.222.9.16
	80de0910
	* ethernet hardware addr of KFPS;
	* 080089 is the Kinetics manufacturer code,
	* remaining bytes are the serial number of your box.
	080089 F00777
	* next value is a flag, if it is '1234' the remainder 
	* of this file is considered valid;  any other value means
	* that the remaining parameters will be obtained from atalkad.
	0000

What we do here at Stanford is make a XXX.config file version for each
kbox, where XXX is replaced by the kbox name or address.  Since all
the 'prompt' parameters are supplied in this file, no typeins have to
be done into the prompt dialog boxes.  This simplifies the downloading
procedure for operations staff.

Here then is the procedure for downloading;  note that all of the
operations involving 'prompt' should allow no more than 30 seconds of
'idle' time for the gateway.  Otherwise the gateway will just enter its
automatic power up reboot sequence;  not what you want.  The 
instructions below are for prompt version 2.0;  Kinetics may make
some revisions/simplifications so these instructions may change
slightly.

(1) ensure the ethernet and appletalk cables are plugged in to the
kbox.  (2) power cycle the kbox.  It is possible to avoid power
cycling the kbox if you have version 3.0 or later of the EPROMs
installed: use the Options menu item "Show EPROM Info" in version 2.0
or later of Prompt to ascertain this.  Prior PROMs have a bug that
makes this unreliable and in these cases it is best to cycle the
power.  (3) run 'prompt' on the Mac and select menu Gateways/Find
Gateways.  (4) press the RESET button.  This will clear out any old
programs; answer 'yes' to any 'are you sure' questions.

(5) now do another Find Gateways.  Also pull down menu Options/Show
Diagnostics.  This will enable any diagnostic messages from the gateway
during loading to be visible.  (6) using the menu, pull down File/Open
Config File.  Specify your XXX.config file.  Don't be concerned that
the dialog boxes showing 'appletalk zone name' and 'appletalk net
number' look erroneous.  This is because the 'prompt' program doesnt
know the exact format of the XXX.config data used by KIP and
misinterprets some of it.  It is OK, only the dialog display is
incorrect, the download operation will proceed as normal.  DO NOT
attempt to edit any of the dialog data by hand;  it is only editable
via the XXX.config file.  (7) press the SEND CONFIG button;  there will
also be an acknowlegment message.

(8) press the SEND LOAD button, this will start the download and a
'thermometer' will show the progress.  (9) press GO, this will start
the new code.  You should see a diagnostic message at this time
indicating that the gateway has correctly started up.  It also shows
the number of free buffers in the KFPS memory.

If you are using version 2.0 or later of Prompt, you can use the
"Options" menu item "Show Diagnostics" to watch for the initial "boot
message" from KIP.  Otherwise, if you have a 'peek' running on the
appletalk (enable reception of RTMPs) you should see some gateway
broadcasts startup in a moment.  Also, if you look in atalkalog, you
will see messages indicating that config and routing info has been
sent to the new gateway.


TEST GATEWAY WITH PING, DDT, CHOOSER.

From UNIX you should be able get a response by sending an ICMP echo
packet to the gateway.  Use the 4.X BSD command 'ping IP_address'.  If
you have the ddt running you should be able to say 'ddt gw.sym
IP_address', then 'main/'.  Successive '/'s will open up following
locations.  On a Mac, run chooser and/or print some files on your
LaserWriter to verify that the name binding protocol is working ok.
Follow the same procedure for subsequent gateways.  Chooser should now
show the union of all your printers or other resources.


ATALKAD GLOBAL OPERATIONS

The admin daemon will reread its /etc/atalkatab file whenever the
write date changes.  But note that the file should rewritten in place
--some editors relink the old file to filename.BAK, etc.  (Note: this
restriction was removed as of KIP revision 0188).  The gateways only
ask for config and routing info when they boot, so if you have changed
this info, you must tell the daemon to force it out to all gateways in
your domain.  This is done by sending the running atalkad a special
signal.  Typing the command '/etc/atalkad route' will send new routing
tables to all the gateways.  Typing '/etc/atalkad boot' will cause all
gateways to reload their config info AND routing tables.  Note that a
backround atalkad must be running; these commands just send a signal
to that running daemon.

So the rule might be, whenever you add or change the routing
information in atalkatab (the lines that start in column 1), you should
do an atalkad route.  If you only change the kbox config info and are
going to manually reboot that box, there is no need to tell everybody
about it.  However if you want to change the kbox config without
leaving your chair, you'll have to reboot everybody with a atalkad
boot.  I suppose we should add a 'atalkad boot net#', to reconfigure a
specific box, but we havent yet.


INSTALL CAP OR KHOST

See the installation document provided.  CAP requires atalk.local!

The biggest problem usually face is that the atalkatab specifications
do not provide the proper routing.  IP services seem to work, but CAP
does not.  Generally, watch out to make sure if you specify N1, N2, N3
routing lines that the resulting broadcast addresses are valid (see
broadcast for more information).

MAC IP PROGRAMS

Several programs are available for IP communication on the Mac.  The
programs usually include services for 'telnet' (terminal connection
and emulation) and 'ftp' (file transfer protocol).  IP packages that
we know of include:

   Stanford University SU-MacIP
   NCSA (Nat. Center for Supercomputing Appl. at U of Ill.) Telnet/FTP
   TOPS Telnet/FTP
   Phil Karn (KA9Q) TCP/IP package

Some of these programs are assigned their IP addresses automatically by
the gateway, so no configuration or customization files are necessary
on your Mac disk.

* SU-MacIP

	The Stanford MacIP is currently only being distributed on a
	(low cost, $50) license arrangement.  For more information from
	the Stanford ACIS/Networking department you can email to:

		macip@ahwahnee.stanford.edu 

	or send U. S. Mail to:  

		SU-MacIP
		Stanford Univ.
		Information Resources, Networking
		Pine Hall
		Stanford, CA  94305

* NCSA Telnet

	For more information on the National Center for Supercomputing
	Applications (NCSA) Telnet program, please see the NCSA files
	in the <INFO-MAC> directory on SUMEX-AIM.STANFORD.EDU.  They
	are under the name NCSA-*.*.

	The complete set of NCSA Telnet files for the Macintosh (and
	PC) is available via anonymous FTP from ftp.ncsa.uiuc.edu
	(128.174.20.50).  On the NCSA host, the Mac files are in the
	subdirectory NCSA_Telnet/Mac.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦1ac04f51d⟧ TextFile

Derivation

TextFile
