Please consider a donation to the Higher Intellect project. See https://preterhuman.net/donate.php or the Donate to Higher Intellect page for more info.

CAP installation procedures

From Higher Intellect Wiki
Jump to navigation Jump to search
                CAP installation procedures


                          ABSTRACT

          This document gives a step by step approach
     to installation of the Columbia AppleTalk Package
     for UNIX.




SEE ALSO

Notes and cookbooks in cap60/doc and UNIX manual entries  in
cap60/man.

Notes on CAP with EtherTalk

This file describes how to install CAP in its  "traditional"
default  configuration IPTalk - which is  based on Appletalk
protocols   encapsulated   in   UDP/IP   packets    -    and
configurations  that  support  communications  via EtherTalk
Phase 1 or Phase 2 - Native EtherTalk, Kernel  AppleTalk  or
the UNIX AppleTalk Bridge, UAB (both Phase 1 only, obsolete)
or via the UNIX AppleTalk Router, UAR.

Native EtherTalk mode is available on  a  limited  range  of
hosts  -  those that support the Stanford ENET Packet Filter
model - currently SUN workstations and DEC OSF/1  or  ULTRIX
hosts  only.  UAR will run on SGI IRIX, Sony NEWS, DEC OSF/1
or  ULTRIX,  SUN  SunOS  and  Solaris,  IBM  AIX  and  HP-UX
workstations.   IPTalk mode is supported on all of the above
and more and is easily ported to other platforms.


     Note: UAR is not bundled with CAP, see the CAP FAQ  for
     more  information,  the most recent copy of the FAQ can
     always  be  obtained  via  FTP  from  munnari.OZ.AU  in
     mac/CAP.faq.


The setup for Native EtherTalk, Kernel AppleTalk, UAB/UAR is
performed  from  within  the  Configure  script (but only if
Configure determines that the host is suitable) by modifying
the  CAP  libraries as necessary.  Refer to the README files
in the support/uab or support/ethertalk directories for more
information.

The choice of whether to use IPTalk, Native EtherTalk/Kernel
AppleTalk  or  UAB/UAR depends on your network setup. If you



                      January 16, 1995





                           - 2 -


have a majority of Macintoshes on LocalTalk connected to  an
IPTalk  gateway  (see "Prerequisites" below) then use CAP in
IPTalk mode.  If your Macintoshes are mostly  connected  via
EtherNet  and  you have other EtherTalk gateways (Ciscos for
example) then  use  CAP  with  Native  EtherTalk  or  Kernel
AppleTalk.  If you have no other gateways, or need to bridge
two EtherTalk networks, or want to run CAP with EtherTalk on
hosts that don't have Native EtherTalk support then use UAR.
On a SUN running SunOS you may choose to use the native  NIT
interface  or install kernel modifications to run the 'ENET'
driver.

Prerequistes

To use CAP with IPTalk you must have a hardware bridge  that
has  the  ability  to  gateway  IPTalk  packets  to and from
EtherTalk and/or  LocalTalk.  Suitable  candidates  are  the
Webster  MultiPort GateWay, Cisco Router, Shiva FastPath and
Cayman GatorBox. The code originally written to  handle  the
IPTalk  gateway  function  on the FastPath is often known as
KIP (Kinetics IP).

The  file  /etc/atalk.local  (see   atalk.local.5   in   the
cap60/man  directory)  contains  routing information for the
static IPTalk network and node numbers. It is not  necessary
to create this file if you are using Native EtherTalk or UAR
drivers and its presence may cause problems if you are using
Native EtherTalk without a gateway box.

Before you start here, you should have read the "README" and
"NOTES" files in the cap60 directory.  The README file gives
a very basic overview of CAP  necessary  to  understand  the
following.

The installation NOTES file tries to point out places  where
you  might  want  to  redefine  things  a  little,  explains
configurations, and points out machine dependencies.

A simple cookbook approach to CAP installation and  printing
is available in cap60/doc/print.cookbook.

Review

or the the "before you do anything else" step.  If you had a
previous distribution of CAP (eg: 5.00), you should consider
whether it is important enough to dump it to tape and put it
away  for safe keeping or not.  There are often considerable
changes between distributions.  You  should  make  sure  you
keep  around  modifications, patches, etc. even if you think
they should be installed in the  new  distribution  just  in
case  they  are  not.  You don't have to do this, but if you
are  paranoid  about  problems  occurring,  you  will   (and
probably would without this prompting).




                      January 16, 1995





                           - 3 -


UDP Ports

Versions of IPTalk/UDP gateway code prior to April, 1988 had
"well  known"  AppleTalk  DDP  sockets mapped to priviledged
UDP/IP ports starting at 768 (so the NBP socket  2  was  UDP
port 770, ECHO socket 4 was 772 etc).

In April, 1988, the  NIC  assigned  a  range  of  UDP  ports
starting  at  200  for the defined DDP services and assigned
the names  "at-rtmp",  "at-nbp",  "at-echo",  "at-zis"  (not
"at-zip"  as  documented  in  some  versions  of  KIP).   In
addition, ports were allocated where  there  were  holes  or
unused  sockets between at-rtmp and at-zis.  CAP Release 6.0
and above dynamically decides which mappings to use by doing
"getservbyname()" calls based upon those names and using the
UDP port number returned.  getservbyname() normally searches
the  file  /etc/services  but  the  information  may also be
cached by a NIS (aka Yellow Pages) server.  If the requested
service name does not exist, then the old mappings (based on
768) are used.

Entries to be put in /etc/services to utilise the NIC  range
are

at-rtmp         201/udp
at-nbp          202/udp
at-echo         204/udp
at-zis          206/udp

[Important Note: In some circumstances,  ports  in  the  768
range can be "stolen" by the portmapper. The symptom of this
is that atis complains that the NBP or ECHO  ports  are  not
available.  There  are  two  solutions,  start  atis  before
portmap or change to the NIC assigned ports].

It should be clear from the above that you  must  make  sure
that  any  mappings defined in /etc/services do not conflict
with the mappings used by the IPTalk gateway you are  using.
Refer  to  the  gateway  documentation for details on how to
alter the port range.

Preparation

or the "make sure things are okay first" step.  Some of  the
steps  require  that you have access to directories that are
often only accessible by a systems  person.   We'll  try  to
identify  them  below.  In addition, some of the servers can
only be run from the "root" id.  We'll try to identify these
too.

[1] Get CAP Files.

CAP is distributed as a compressed tar file (see below for a
list  of  anonymous  FTP  sites). Since you are reading this



                      January 16, 1995





                           - 4 -


information it could be assumed  that  you  have  everything
unpacked already. For completeness, however, the commands to
unpack the distribution are

                % compress -d cap60.pl100.tar.Z
                % tar xf cap60.pl100.tar

This creates a 'cap60' directory containing the patch  level
100  CAP  distribution.   CAP  updates  and  bug  fixes  are
normally distributed as  'patch'  files.  These  are  simply
context  diffs  of  the  original and the new files (see the
UNIX command diff(1)).  To apply the patches with a  minimum
of  effort,  it  is  recommended  that  you  use the 'patch'
program written by Larry Wall. This  can  be  obtained  from
sites    that    archive   postings   from   the   newsgroup
comp.sources.unix in the  directory  volume7/patch2.  It  is
important to ensure that any patches for the 'patch' program
sources are applied, some CAP 6.0 patches can  fail  if  the
unmodified patch code is used.

CAP   6.0   patches    are    sent    to    the    newsgroup
comp.protocols.appletalk,  and,  for  sites with FTP access,
patches for CAP 6.0 are archived  on  munnari.OZ.AU  in  the
directory     mac/cap.patches,     on     rutgers.EDU     in
src/cap60.patches      and       gatekeeper.DEC.COM       in
pub/net/cap/cap.patches.    The   current   patch  level  is
recorded in the cap60/README file.  New patches are  applied
from the top level directory with the command

                % patch -p < cap60.patches/cap60.patchNNN

where NNN is the patch number. The -p option tells patch  to
obtain  information about which file to alter from the patch
header. If you attempt to apply  a  patch  more  than  once,
patch  will  enquire about "a reversed or previously applied
patch", answering yes to this will remove the patch, leaving
the original file, this is not good ...

In the following, it is assumed that  you  are  in  the  top
level directory (e.g. so an ls(1) shows up samples, contrib,
etc, lib, applications, etc.)

[2] Configuration

                % ./Configure


You should run Configure to establish the baseline setup for
your  system.  The  Configure script has inbuilt support for
various hardware platforms, making suitable changes for  the
vagaries  of  each.  Configure also checks the byte ordering
on the host machine and if necessary ensures that  the  code
is  built correctly for "little-endian" machines.  Answering
Configure questions with the  default  answers  is  normally



                      January 16, 1995





                           - 5 -


enough  to  build  an  IPTalk  version  of  CAP with a basic
feature set, it is also possible to include an extra set  of
features  for  the  various  CAP  components,  see the files
CAP60.README and m4.features for more details.

One Configure option allows the CAP files to  be  built  and
used within a single directory hierarchy. This is useful for
testing or evaluation (see below).

[3] Make sure things will end up where you want them.

Figure out where you want everything.  The assumptions are:

        cap libraries - /usr/local/lib - as a unix archive file
        cap programs - /usr/local/cap - as programs
        cap servers - /usr/local/cap - as programs
        cap config files - /usr/local/lib/cap or /etc

If you want things elsewhere, edit the file m4.setup  before
running gen.makes.

By the way, /etc may be a  bad  place  to  put  things.   At
Columbia,  everything is generally put in /usr/local/lib/cap
instead of /etc.  (Warning:  if  you  want  cap.printers  in
/etc,  it  is not enough to redefine the "etcdir".  You must
also uncomment  the  definition  that  allows  an  alternate
location  for  cap.printers.  This  also applies to the file
atalk.local. You  have  to  change  the  definition  in  the
makefile in lib/cap).

This is also a  good  point  to  think  about  reconfiguring
papif,  lwsrv,  etc. to do what you want.  If you don't know
yet, then don't worry, you can recompile  after  you  verify
basic functionality.

[4] Generate system makefiles

                % ./gen.makes


After Configure, or if you have edited the files m4.setup or
m4.features,  run  gen.makes  to  (re)generate your baseline
makefiles.  There are "Makefile"s  included,  but  they  are
included   for  systems  without  the  m4  preprocessor  and
shouldn't be used unless absolutely necessary. Some machines
will generate a 'make' warning message about the presence of
both makefile and Makefile. You can  ignore  these  warnings
or,  after  the  first  gen.makes, run 'make spotless' which
removes  both  makefile  versions.   At  this  point  it  is
necessary  to  run  gen.makes again to continue with the CAP
build.






                      January 16, 1995





                           - 6 -


[5] Install header files.

                % make include


The simplest method is to type "make  include".   This  will
create   /usr/include/netat   and   copy   the  contents  of
cap60/netat to /usr/include/netat.  Alternatively, you could
symbolically link /usr/include/netat to cap60/netat with the
command

                % ln -s cap60/netat /usr/include/netat


[6] Testing

You can test  things  out  without  installing  programs  in
system   directories  by  answering  'y'  to  the  Configure
question relating to installing CAP in  a  single  directory
tree.

This will put:
        libraries in cap60/lib
        programs and servers in cap60/bin
        etc stuff in cap60/etc

In this case, it is not  necessary  to  install  the  header
files.


[7] Build Libraries.

                % make libsmade


Type: "make libsmade" from  the  top  level  cap  directory.
This  should  build the cap libraries.  If this step doesn't
work, then:

        (a) you didn't get the distribution correctly
        (b) you didn't install the header files correctly
        (c) you didn't Configure and generate the makefiles correctly
        (d) or worst of all the libraries don't work on your machine

If the problem is (d), you can refer to "PORTING"  for  some
help.

[8] Installing libraries and building sample programs.

                % make programs


After building the libraries, you  use  "make  programs"  to
install  the  libraries  into  a  readily  accessible  place



                      January 16, 1995





                           - 7 -


(usually   /usr/local/lib)   and   compile   the    samples,
applications and contributed programs.

[9] Installation

                % make install


You can  install  the  various  programs  into  their  final
destinations by typing "make install", but you might want to
test them first.

Change directory to cap60/etc.   Look  at  start-cap-servers
and  figure  out  if  this  is  what you want - modify it if
necessary.  If you don't know what you want it to be,  don't
worry  - you can do it later, but make sure you don't remove
the line with atis in it.

You should then copy start-cap-servers to /usr/local/lib/cap
(or other desired location).

At this point, primary installation is done.

[10] Verification.


If you are using IPTalk, you should have already tested  the
gateway software before proceeding further and you must have
/etc/atalk.local installed (see the  file  man/atalk.local.5
for details of the file contents). Skip from here to step A.
below.

If you are using Native EtherTalk, then you should read  the
file  cap60/support/ethertalk/README and then run aarpd with
suitable interface and zone name arguments. Follow  this  by
atis which determines the AppleTalk network numbers from the
network (see step C below for atis verification procedure).

If you are using Kernel AppleTalk, ensure that the necessary
code     is     installed     in     the     kernel,    read
cap60/support/capd/README, run capd with suitable  interface
and zone name arguments. Follow this with atis, as above.

If you are using UAB, read the file cap60/support/uab/README
and  the  files to which it refers. Ensure that you edit and
install the 'bridge_desc' file.

If you are using UAR, see the README file supplied with  the
distribution.   The  CAP FAQ also contains information about
where to get UAR and its use with CAP.

At this point, the /etc/etalk.local file should look similar
to the following:




                      January 16, 1995





                           - 8 -


        #
        # EtherTalk dynamic configuration data
        #
        # Last update:  Sat Dec 29 14:46:45 1990
        #
        # Generated by Native EtherTalk (Phase 1)
        #
        thisNet         99.116
        thisNode        69
        thisZone        "unimelb-CompSci"
        bridgeNet       99.116
        bridgeNode      69
        bridgeIP        127.0.0.1
        nisNet          99.116
        nisNode         69
        asyncNet        170.170
        asyncZone       "unimelb-Async"

If things look OK to this point, proceed with  the  rest  of
the verification steps.


A.  Change directory to cap60/samples and run getzones.  You
should see something similar to the following:

        % getzones
        unimelb-CivEng
        unimelb-AgEng
        unimelb-Ed1888
        unimelb-History
        unimelb-FineArts
        unimelb-Research
        unimelb-Classic
        unimelb-Language
        unimelb-Chemistry
        unimelb-Registrar
        ...

If getzones prints a warning message or fails with  a  -1096
error then the problem is usually that there is no AppleTalk
router  on  the  local  network  and  therefore   no   zones
available.  In this situation you should be using "*" as the
zone name argument for aarpd.

The next program to try is atlook.  If everything  is  okay,
you  should  see  some appletalk entities.  If you installed
the IPTalk gateway code (aka KIP) correctly before, then you
should  minimially see the IPGATEWAY entry.  [Should you not
see the IPGATEWAY entry, then the assumption is that the UDP
code  isn't  functional  or  you are not using IPTalk].  For
example:
        % atlook
        abInit: [ddp:  55.32, 130] starting
        01 - 128.59.35.40:[email protected]* [Net: 58.01 Node:220 Skt: 72]



                      January 16, 1995





                           - 9 -


        ...
        $
Another really simple program to try is atlooklws which will
look for and query LaserWriters.

If atlook doesn't work, then:

     (a) you may  not  have  installed  the  IPTalk  gateway
     correctly

     (b) you may not have installed atalk.local in the place
     atlook  expects  it, although it should complain if the
     /etc/atalk.local file is not there  or  is  incorrectly
     formatted

     (c) if  atlook  coredumps,  then  something  is  really
     wrong.   you are probably on a machine that CAP doesn't
     work on.

B.  If you have a LaserWriter and you see it in atlook, then
another  level  of  testing is to run the sample program tlw
(just type "tlw <laserwriter name>").

C.  To test the server functionality, as  "root"  run  atis.
To  see if atis is running properly, run "atistest" from the
samples directory.

        % atistest
        CAP distribution 6.00 using UDP encapsulation, January 1991
        Copyright (c) 1986,1987,1988 by The Trustees of Columbia
        University in the City of New York

        abInit: [ddp:  93.38, 1] starting
        debugging NBP
        Registering "atis test:[email protected]*"
        NBP SndNBP: sending
        NBP nbp_timeout: 4 tick timeout on -134218532, 3 remain
        NBP SndNBP: sending
        NBP nbp_timeout: 4 tick timeout on -134218532, 2 remain
        NBP SndNBP: sending
        NBP nbp_timeout: 4 tick timeout on -134218532, 1 remain
        NBP SndNBP: sending
        NBP nbp_timeout: 4 tick timeout on -134218532, 0 remain
        NBP SndNBP: sending
        NBP status done: found -134218532
        Okay

If it signals proper operation with an "Okay" message,  then
you  can  confirm things again (odds are everything is okay)
by:

     (a) running atlook, there should be an entry like

     1 - atis test:[email protected]*                      [Net: 93.38  Node:  1 Skt:143]



                      January 16, 1995





                           - 10 -


     (b)  typing  "atis  dump"  (as  root)  and  looking  at
     /usr/tmp/nis.db   you   should  see  (apart  from  some
     comments at the top of the file)

     net=93.38, node=1, skt=143, enum=7, !9!7!1! ? atis test:[email protected]*

     (the nis.db entry is the information that atis  returns
     when  an  NBP  name  lookup  is  performed,  such as by
     atlook).

To  get  rid  of  the  "atis  test"   entry,   simply   edit
/usr/tmp/nis.db and delete the line, then type "atis reload"
(as root).  Alternatively,  simply  kill  the  running  atis
process.   A  useful maintenance tool is to alias 'nised' to
'atis dump; vi /usr/tmp/nis.db; atis reload'.

The most common problem in getting atis to run is failing to
setup  IPTalk  on  the gateway, the atalk.local file (or, if
used, atalkatab) properly. The UNIX/CAP host and the gateway
may  also  not  agree on the network broadcast address, this
will affect NBP lookups.


D.  After verification, you will want  things  to  start  up
automatically,   edit   (or   get   a   superuser  to  edit)
/etc/rc.local to run the following lines (or an equivalent):

if [ -f /usr/local/lib/cap/start-cap-servers ]; then
   /usr/local/lib/cap/start-cap-servers & echo -n " CAP " > /dev/console
fi


[11] Cleaning Up.

                % make clean


After final installation, you can do a  'make  clean'.  This
removes  all  the  compiled  binaries  and object files thus
saving on disc space.

CHANGES FROM RUTGERS CAP

There are some important changes to note if you are  already
using   Native   EtherTalk   from   the   original   Rutgers
distribution. Shared memory is  no  longer  used,  the  file
/etc/cap.ether.shared    is    thus    not   required.   The
modifications needed to the file /etc/atalk.local to  select
a  zone  and an ethernet interface are not needed as CAP now
uses the file /etc/etalk.local for both Native EtherTalk and
UAB.  See  the man files atalk.local.5 and etalk.local.5 for
more details. For Native EtherTalk, you may use  etalk.local
to  seed  the  values for "interface" and "thisZone" but the
preferred method is to supply this information as  arguments



                      January 16, 1995





                           - 11 -


to aarpd, as in

                aarpd  ie0  myZone