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.

Columbia AppleTalk Package

From Higher Intellect Wiki
Revision as of 11:47, 16 July 2019 by Netfreak (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The Columbia AppleTalk Package (CAP) implements the AppleTalk protocol stack on a variety of UNIX machines. The main applications provide an AppleShare 2.1 compatible server (aufs), a LaserWriter Spooler (lwsrv) and a program to print to LaserWriters (papif).

Readme

	       CAP - Columbia AppleTalk Package for UNIX

	o RELEASE NOTES
	o CAP Distribution 6.0, Patch Level 198, June 1996

Notice
------

Copyright (c) 1986, 1987, 1988, The Trustees of Columbia University in
the City of New York.  Charlie C. Kim, User Services Group, Academic
Information Services Division, Libraries and Center for Computing
Activities and Bill Schilit, formerly of Computer Research Facilities,
Computer Science Department.

Permission is granted to any individual or institution to use, copy,
or redistribute this software so long as it is not sold for profit,
provided that this notice and the original copyright notices are
retained.  Columbia University makes no representations about the
suitability of this software for any purpose.  It is provided "as is"
without express or implied warranty.

--

Portions Copyright (c) 1985, Stanford Univ. SUMEX project.
May be used but not sold without permission.

Portions Copyright (c) 1984, Apple Computer Inc.
Gene Tyacke, Alan Oppenheimer, G. Sidhu, Rich Andrews.

Portions Copyright (c) 1990 - 1996 The University of Melbourne

Modules copyright in part or whole by any other entity than Columbia
University are clearly marked as such.

--

Portions are of the CAP distribution are public domain software.  The
specific items are:
	extras/att_getopt.c
	extras/des.c

Portions of the CAP distribution are contributed by other sites including:
	Rob Chandhok, Computer Science Department, Carnegie Mellon University
	Ed Moy, University of California at Berkeley
	David Hornsby, The University of Melbourne
	Rakesh Patel, Rutgers University
	Paul Campbell


ABSTRACT
--------

CAP was written for BSD 4.2 Unix and derivatives.  CAP implements a
library containing a portion of Apple Computer's AppleTalk protocols.
In order to use this package you may need an AppleTalk/Ethernet bridge
(e.g. Shiva FastPath, Webster MultiPort Gateway). CAP includes a number
of applications that can be used to print to a LaserWriter, spool for a
LaserWriter, and act as Unix based AppleShare compatible file server.
CAP also includes a number of sample programs and contributed software.

CAP library routines are structured, for the most part, the same as
the Apple routines described in "Inside AppleTalk" and "Inside
LaserWriter."  Refer to the Apple documents and the procedure comments
for a complete description of the routines and how to call them.

Bill Croft's original work in this area provided the inspiration for CAP.

Prerequisties
------------

 o CAP as originally shipped needs a gateway capable of supporting
   IPTalk (the transmission of AppleTalk DDP packets inside IP UDP packets)
   to translate (gateway) IPTalk packets to/from EtherTalk or LocalTalk.
   Suitable candidates include ...

     * Webster MultiPort Gateway
     * Cayman Gatorbox
     * Shiva FastPath
     * Cisco Router

 o This CAP version supports Native EtherTalk, UAR (Phase 1 or Phase 2) and
   Kernel AppleTalk, UAB (Phase 1) on certain hosts. A gateway as listed
   above is only required to access LocalTalk services.

 o baseline host system: Ultrix 2.0-1.  Most will work under BSD 4.2,
   BSD 4.3, Ultrix 1.0-1.2, Sun OS 3.2 or higher, ACIS 4.2, A/UX, IBM
   RISC 6000, IRIS/IRIX, HP/Apollo Domain (BSD environment), OSF/Alpha,
   386/BSD, FreeBSD and other systems with BSD like networking
   facilities with varying levels of functionality.  Under certain
   systems, only portions will work.

Where
-----

CAP can be obtained by anonymous FTP from

munnari.OZ.AU		mac/{cap60.pl100.tar.Z,cap.patches/*}
ftp-ns.rutgers.EDU      pub/cap/{cap60.pl100.tar.Z,cap.patches/*}
gatekeeper.DEC.COM	pub/net/appletalk/cap/{cap60.pl100.tar.Z,cap.patches/*}
ftp.kuis.kyoto-u.AC.JP	net/cap/{cap60.pl100.tar.Z,cap60.patches/*.Z}
src.doc.ic.AC.UK	packages/multigate/{cap60.pl100.tar.Z,cap.patches/*}

Please choose an appropriate site and an off-peak time for the transfer.

The patches are available individually or as the files "patches.1-100.tar.Z",
"patches.101-126.tar.Z", "patches.127-143.tar.Z", "patches.144-154.tar.Z",
"patches.155-162.tar.Z", "patches.163-182.tar.Z" & "patches.183-192.tar.Z".
Additionally, for new users, a partially patched source file is available
as "cap60.pl100.tar.Z" (beware: the file cap60.tar.Z is totally unpatched).

Patches
-------

To make the process of patching easier, you should get the 'patch' utility
written by Larry Wall, it is normally available from sites that archive
comp.sources.unix in volume7/patch2 and at GNU archive sites as
patch-2.1.tar.gz (which requires gzip-1.2.2.tar for unpacking).

For each of the patches, run 'patch -p < cap60.patchNNN' from the top level
cap60 directory, for example, in csh

		foreach i (cap60.patches/cap60.patch*)
		patch -p < $i >>& /tmp/patches
		end

and check the /tmp/patches file for patching errors (look for the strings
"rej", "failed", "offset", "fuzz" - should be none).  To remove the *.orig
files that patch leaves behind (containing the original version of the file),
run 'make spotless' from the top level directory (note that spotless also
removes all makefiles so gen.makes needs to be run to regenerate them).

Information
-----------

There is no CAP mailing list.  Instead, notices and information about
CAP are posted to the mailing list info-appletalk which is gatewayed
with the USENET news group comp.protocols.appletalk.  If you don't
have access to comp.protocols.appletalk and have access to the
ARPANET, you can get on the mailing list by sending mail to
[email protected]

Information about CAP and related UNIX AppleTalk packages is available
via the World Wide Web using

	http://www.cs.mu.OZ.AU/appletalk/atalk.html

The CAP FAQ (Frequently Asked Questions) file is available via FTP
from munnari.OZ.AU as the file

	mac/CAP.faq

Documentation
-------------

Important documentation resides in:

	doc/install.ms - stepwise installation document: assumes
	  you have read NOTES and this document
	doc/print.cookbook - simple steps to implement CAP printing
	man/* - UNIX manual entries for the various CAP programs
	NOTES - installation notes: READ THIS BEFORE STARTING INSTALLATION
	PORTING - notes on porting CAP to machines it doesn't know about

What's in CAP
-------------

The Columbia AppleTalk Package consists of a number of libraries, a
number of programs, and associated documentation.  Following is a list
of the main parts along with a brief description.  

 o NOTES for a general overview of installation and some overview material.

 o PORTING for information about making CAP work on systems not listed
   in NOTES

 netat - general header files used by various parts of CAP
 man - man pages for some of the programs
 doc - documentation
 lib/cap - main appletalk libraries: ASP, PAP, ATP, NBP, DDP
 lib/afp - generic AppleTalk Filing Protocol (AFP) routines
 lib/afpc - AFP client libraries
 lib/xenix - compatibility routines for XENIX use
 etc - support programs: only atis - support program for NBP
 extras - code and materials not necessarily related to AppleTalk
 samples - sample programs: allow simple interaction with lw, appleshare
	server, etc.  See README there.
 contrib - contributed programs
 support - alterative LAP delivery support, Native EtherTalk,
	Kernel AppleTalk and UAB.
 applications - main applications.

The following programs in applications are in regular use at Columbia
and are a main part of the reason we work on CAP:
  papif		- UNIX lpd "input" filter for spooling to appletalk
		- also includes sample "output" filter and printcap entry
		- Note: this is a very bare bones filter
  lwsrv		- Simple LaserWriter spooler suitable for extension
  aufs		- AppleTalk Filing Protocol Unix File Server

    NOTE: You must have the AppleShare 1.1 or 2.0 client code installed in
      your Macintosh to use this.  You must obtain this from Apple -
      we do not and do not plan to supply this.  The client code is
      a lot of work and Apple's already done an excellent job here.

Bug Reports
-----------

Send bug report, comments, etc. to [email protected] or uunet!munnari!cap

Notes
-----
Hasn't been througly checked out on any system except Ultrix 2.0 & SunOS.
It it known to have run or should be able to run under: BSD 4.2, BSD
4.3, Ultrix 1.0, 1.1, 1.2, 2.2, Sun OS 3.2 or higher, Pyramid's Unix
under the BSD universe, ACIS 4.2 or 4.3 for the IBM RT PC, A/UX, HP-UX
for the series 9000 (release 6.0), Convex Unix V6.1, Sequents, IBM AIX
on the RISC 6000, Silicon Graphics IRIS/IRIX, HP/Apollo Domain (BSD),
OSF/1 Alpha, 386/BSD, FreeBSD and the Encore Multimax.

LAP - will probably never be implemented
DDP - don't try to use it directly
Documentation - in shorter supply than it should really be


TODO list
---------
a) Complete NBP - completed.
b) Complete PAP - completed.  
c) Complete ATP - completed.
d) Complete DDP - essentially completed, but some minor parts missing.
e) Complete ASP - completed.
f) Start AFP - client side needs to be redone, server side okay.
g) Start ZIP work.  KIP modified to allow under rev 1/88.
h) Start RTMP work.  Not need under KIP.
i) miscellanous other fixes and cleanup


Credits
-------

Thanks to the User Services staff at Columbia University Center for
Computing Activies for patiently testing all the broken software that
was foisted on them as "working" with special thanks going to:
	Rob Cartolano for testing Aufs beyond the call of duty
	Alan Crosswell for making papif die more than anyone else and
		letting me use his RT.
	Lisa Covi and Jeff Eldredge for living with the software in
		our Mac MicroLab
	Mark Kennedy, Tom Chow, and Richard Sacks for giving Charlie
		the support and time to work on CAP
and Father Larry "Mac" McCormick from the Columbia University
Macintosh Users Group for his inspiration and support.

And to the following list of people for their
support, help, commentary, and bug fixes:
	Bill Croft, SUMEX, Stanford University
	Janet Tornow, Apple Computer
	Dan Tappan, Bolt Beranek and Newman
	Rakesh Patel, Rutgers University
	Charles Hedrick, Rutgers University
	Robert Elz, University of Melbourne, Australia
	Dan Sahlin, Swedish Institute of Computer Science, Sweden
	Scooter Morris, Genentech
	Mike Byron, Adobe Systems Incorporated
	Tom Mallory, Adobe Systems Incorporated
	Phil Farrell, School of Earth Sciences, Stanford University
	Mark Davies, VUW, New Zealand
	Roy Smith, Public Health Research Institute, NYC
	Ritch Ruff, Oregeon State
	Dan Lanciani, Harvard University
	Ravinder (Rob) Chandhok, Carnegie Mellon University
	Dwight Mckay, Purdue University
	Steve Fram, CITI, University of Michigan
	Paul Campbell, Unisoft
	Edward Moy, WSSG, University of California at Berkelely
	Tharen Debold, Georgia Tech
	Jim Guyton, The Rand Corporation
	and any we might accidently left out of this list
our thanks!
 

Further CAP 6.0 thanks to
	William Roberts, Queen Mary & Westfield College, UK
	Edward Moy, University of California at Berkeley
	Steve P. Andrewartha, University of Tasmania
	Tom Evans, Webster Computer Corp.
	Phil Budne, Shiva
	Rakesh Patel, Rutgers University
	Chip Salzenberg, Teltronics/TCT
	Dan Oscarsson, Lund Institute of Technology, Sweden
	Bridget Rogers, University of MN, Duluth
	Matthew Lewis, University of Amsterdam
	Max Tardiveau, University of St. Thomas
and lots of nice people at the University of Melbourne, Australia.

CAP 6.0

CAP 6.0
-------

This distribution of CAP is an attempt to collect together all of the patches
available for cap50 and provides an opportunity to perform some very necessary
maintenance. The code contains the original "official" patches plus bug fixes
and extra features contributed by *many* people.  Local configuration of the
extra features is controlled by the file 'm4.features'. For more details,
see Features below.

Other changes
-------------

	* AUFS support for AFP 2.0 is (practically) complete (see below).
	* 'Configure' will automatically recognize the host byte ordering.
	* 'Configure' has support for more machines and custom local features.
	* UAB is now bundled and configured with this CAP distribution.
	* UAB now supports Asynchronous AppleTalk on a UNIX host.
	* The format of 'atalk.local' has been extended for async appletalk.
	* Zone names in 'atalk.local' MUST now be quoted to include spaces.
	* A "free format" 'etalk.local' is used by EtherTalk LAPs (& UAB/UAR).
	* atis is now Phase 2 NBP compatible (partial obj/type matches).
	* There are more (& updated) manual entries and documentation.
	* There are more contributed packages bundled with CAP.


Features
--------

Additional features have been incorporated into CAP. Most of these were
supplied as patch files from a variety of sources.  In addition, some changes
were made at The University of Melbourne, these changes concentrated on making
AUFS comply with AFP2.0 specifications and adding extra facilities and host
support to Configure. Currently, AUFS supports ProDOS* (Apple IIgs)
workstations running AppleTalk, the extended directory and volume attributes
and the additional error result codes. AUFS supports user editable encrypted
passwords using the DISTRIB_PASSWDS feature.

  * ProDOS requires the NOCASEMATCH feature, or use of upper-case
    application filenames only.

Specific host support that was new with CAP 6.0 includes ...

	A/UX 2.0 Native AppleTalk	William Roberts <[email protected]>
	IBM Risc 6000 AIX System V	David Hornsby <[email protected]>
	Silicon Graphics IRIS-4D/IRIX	David Hornsby <[email protected]>
	SCO Xenix System V 		Chip Salzenberg <[email protected]>
	Sequent Balance			William Roberts <[email protected]>
	ICL DRS6000			Michael Brown <[email protected]>
	DEC OSF/1 Alpha			Scooter Morris <[email protected]>
	Amdahl UTS			Mark Haynie <[email protected]>
	Sun Solaris 2.N			Andy Polyakov <[email protected]>
	Sony NEWS			TAYA Shin'ichiro <[email protected]>
	Control Data CD4000-EP/IX	John Huntley <[email protected]>
	386/BSD, FreeBSD 2.0		Dave Matthews <[email protected]>
	NetBSD 1.0			Paul Nash <[email protected]>
	BSDI BSD/386 1.1		David Hornsby <[email protected]>
	HP/Apollo Domain BSD 4.3	Darrell Skinner
					<[email protected]>

The features file ("m4.features") can be edited from within Configure by
answering yes to the question "Do you wish to customise the feature list ?".
The contents of the file are not processed by Configure so you can edit the
feature list at any time then (re)generate the makefiles with "./gen.makes".
To include a particular feature, uncomment (remove '#') the definition line.

The available flags, their meanings and original authors are:

	SHORT_NAMES
		Include AUFS code to support short file names as required by
		AppleShare client implementations on PCs.
				Bridget Rogers <[email protected]>
	NOCASEMATCH
		Make AUFS filenames case insensitive as in other AppleShare
		servers and Mac applications.
				Edward Moy <[email protected]>
	SIZESERVER
		Compile 'sizeserver' daemon for AUFS to obtain volume size
		information.  Useful with operating systems that have no
		support for getmnt() or statfs() to determine the amount of
		free space on a filesystem.
				Edward Moy <[email protected]>
	FIXED_DIRIDS
		Implement server and AUFS code to provide support for
		fixed directory and file IDs. The 'afpidsrvr' daemon must
		be started before any AUFS processes. Refer to the file
		"applications/aufs/afpid.notes" for more information.
				John Forrest <[email protected]>
				Scooter Morris <[email protected]>
	LWSRV_AUFS_SECURITY
		Require LWSRV LaserWriter spooler users to have an AUFS
		volume connected (and therefore be password validated).
				Phil Budne <[email protected]>
	LWSRV_LPR_LOG
		Include stdout/stderr messages from lpr in the lwsrv log.
				Rakesh Patel <[email protected]>
	AUTHENTICATE
		AUFS or LWSRV connections must comply with the rules
		specified in "/etc/cap.auth".  This may specify permit
		or deny permission by network number and/or server type.
		Refer to the file cap60/doc/cap.auth.doc for details.
				Edward Moy <[email protected]>
	STAT_CACHE
		Provide a speed enhancement by caching UNIX stat(2) calls
		within AUFS.
				Dan Oscarsson <[email protected]>
	TREL_TIMEOUT
		ATP transaction release packets (TREL) can sometimes be
		lost. AUFS will timeout after 30 seconds and continue with
		the next request.  This option adds a second request
		listener to avoid the timeout delays.
				Dan Oscarsson <[email protected]>
	ATPREQCACHE
		Cache ATP TREQ packets to avoid 2 second wait if request
		control block (RqCB) not set up in time by AUFS.
				Rudy Nedved <[email protected]>
	RUTGERS
		Include Rutgers specific code.  You probably don't want
		either this or MELBOURNE unless you check the sources.

	MELBOURNE
		Include Melbourne specific code.

	USE_HOST_ICON
		If available, the AUFS volume ICON will represent the
		underlying  machine hardware (instead of the BSD daemon).

	PERMISSIVE_USER_NAME
		Allow the AUFS login name (from the Chooser User Name) to be
		partially matched to the gecos field in the password entry.
		IE: you can login with full user name, first name or surname.
				Jean-Luc Mounier <[email protected]>
	ULTRIX_SECURITY
		Activate AUFS login security based on an authorisation
		file.  Check this file if normal password field is "*".
				Rusty Wright <[email protected]>
	DIGITAL_UNIX_SECURITY
		Use Digital UNIX enhanced security for AUFS logins.
				Andrew Greer <[email protected]>
				Richard Rogers <[email protected]>
	USE_MAC_DATES
		Keep the modification date of the Mac file intact when
		copied to an AUFS volume (otherwise it is the latter of
		the UNIX creation and modify times).
				David Hornsby <[email protected]>
	DEV_NIT
		Allow an alternate name for the NIT interface. The default
		name is "/dev/nit".
				Austin Shelton <[email protected]>
	APPLICATION_MANAGER
		Control the maximum number of times an Application may be
		run and optionally prevent Finder copying for AUFS mounted
		volumes. More details in contrib/AppManager/README
				David Hornsby <[email protected]>
	DENYREADWRITE
		Implement AFP Access/Deny modes on AUFS file accesses.
				David Hornsby <[email protected]>
	AUFS_README
		Add '-r <arg>' option to AUFS. The <arg> is expected to
		be a full path name to an explanatory README file and is
		linked into the top level volume of a new AUFS user.
				Edward Moy <[email protected]>
	AUFS_IDLE_TIMEOUT
		Add -i and -I options to AUFS to disconnect users who
		exceed the specified idle time.  -I includes all users,
		-i is for guest sessions only.
				David Hornsby <[email protected]>
	REREAD_AFPVOLS
		A SIGUSR1 signal sent to AUFS causes the global AFP volumes
		file to be re-read.
				Eugene Bogaart <[email protected]>
	CLOSE_LOG_SIG
		A SIGUSR2 signal sent to AUFS causes the log file to be
		closed and then re-opened (allows the file to be truncated,
		for example, by a script which regularly does something like
		'cat > logfile; kill -USR2 <pid>'). See also PID_FILE.
				Scooter Morris <[email protected]>
	PID_FILE
		Cause AUFS to write a (named) process-ID file.
				Scooter Morris <[email protected]>
	XDEV_RENAME
		Allows AUFS to copy/move files across file systems.
				Mark Abbott <[email protected]>
	NOCHGRPEXEC
		Make AUFS use the third argument to chown(2) instead of
		exec'ing chgrp(1) to change group membership of file.
		NB: Unavailable under System V, recommended for others.
				Edward Moy <[email protected]>
	USEDIRSETGID
		Set the group ID bit on directories whose group is not the
		primary group of the AUFS user. Under SunOS and System V,
		new files and directories are by default created with the
		primary group unless the group ID bit of the parent is set.
				David Hornsby <[email protected]>
	USR_FILE_TYPES
		Map UNIX filename suffix to Mac Type/Creator. The map file
		may be global (specified with -F option to AUFS) or per
		user (~/.afpfile or ~/afpfile). The mapping also controls
		the file translation method used (ascii, text or raw). See
		the sample file in cap60/extras/afpfile.
				David Hornsby <[email protected]> et. al.
	CREATE_AFPVOL
		Create the .afpvols file, .finderinfo and .resource
		directories in a subdirectory (default 'mac') of the home
		directory of a new AUFS user (if they don't already exist).
		An alternate subdirectory/volume name is specified with
		the string -DCREATE_AFPVOL=\"other\" in m4.features
				Heather Ebey <[email protected]>
	CREATE_AFPVOL_NAME (now CREAT_AFPVOL_NAM)
		Modifies the CREATE_AFPVOL option to use the user/account
		name for the volume label instead of the value of the
		CREATE_AFPVOL variable.  Assumes CREATE_AFPVOL.
				Craig Zook <[email protected]>
	NETWORKTRASH
		Under System 7.0, the "Network Trash Folder" mode is set
		to 0x707 (world writeable). Defining NETWORKTRASH sets the
		mode to that of the parent (top level) directory.
				Edward Moy <[email protected]>
	ISO_TRANSLATE
		Translate ISO 8859 characters in command line arguments
		and configuration files into their Macintosh equivalents.
		Likewise translate Macintosh characters to ISO 8859 for
		etalk.local zone name, log file entries.
				Austin Shelton <[email protected]>
	ISO_FILENAMES
		Extend ISO/Mac character translation to AUFS file names
		(assumes ISO_TRANSLATE is in use)
				Dan Oscarsson <[email protected]>
	ISO_FILE_TRANS
		Translate ISO 8859 characters in Creator "unix", Type
		"TEXT" AUFS files into Mac characters on read and vice
		versa on write (assumes ISO_TRANSLATE is in use).
				Dan Oscarsson <[email protected]>
	NCS_ALL_TEXT
		Apply ASCII or ISO 8859 file translation to all files of
		type "TEXT", regardless of Creator.
				Dan Oscarsson <[email protected]>
	LOGIN_AUTH_PROG
		Allows AUFS -L command line argument to specify an external
		authorization program for AUFS logins.  See man/AUFS.8
				Irwin S. Tillman <[email protected]>
	PSJOBHEADER
		If defined, PAPIF will check for an environmental variable of
		the same name.  The variable specifies a file which contains
		a postcript header (for example to change paper trays or
		print double sided) to be sent before the print job.
				Jay Plett <[email protected]>
	DUPLEXMODE
		If defined, PAPIF accepts a -2 option (also if the printer
		name contains -dup*) to set double sided printing.  Duplex
		printing must be supported by the printer hardware.
				Dan Mosedale <[email protected]>
	TRANS3
		Setup PAPIF for 'psdman' from the TranScript 3.0 package.
				Dan Mosedale <[email protected]>
	PASS_THRU
		If defined for LWSRV, print jobs will be passed through
		with no Adobe pre-processing. This is useful for spoolers
		providing service for PCs.
				Gavin Longmuir <[email protected]>
	DONT_PARSE
		If defined for LWSRV, print jobs will be passed through
		with no Adobe pre-processing at all. This is useful for
		spoolers which require an unaltered file, as the PASS_THRU
		option does not disable some Adobe handling. The crtolf
		option will continue to work if it is enabled with this
		option.
				Rakesh Patel <[email protected]>
	LPRARGS
		Allows LWSRV -L command line arguments to be passed directly
		to lpr. For example, printing via TransScript without
		-T quote8bit set causes option-key characters to be printed
		incorrectly. Setting -T quote8bit causes binary PostScipt
		(usually gray scale images) to fail. In this situation use
		LWSRV argument "-L-l" to pass "-l" to lpr.
				Edward Moy <[email protected]>
	RUN_AS_USER & USER_REQUIRED
		Attempt to map Mac Chooser/Owner name to a real UNIX user
		name (based on map file, eg: cap60/extras/lib.cap.macusers)
		then setuid() the lwsrv session as this user. IE: lpr can be
		lprm'd as normal. USER_REQUIRED must find a match otherwise
		it prints a failure message eg: cap60/extras/lib.cap.refused.
		NB: no password authentication is provided.
				Maarten Carels <[email protected]>
	PROCSET_PATCH
		If defined for LWSRV, procset "patches" are not passed
		through to the printer. These patches are code changes
		for Apple LaserWriters and can have strange effects if
		used on non-Apple printers.
				Alexander Dupuy <[email protected]>
	ULT42PFBUG
		Workaround for ULTRIX 4.2 packet filter problem (see Gotchas)
				David Hornsby <[email protected]>
	STEAL_PORTS
		Extend DDP Dynamic Socket range down into the experimental
		AppleTalk socket range 64 - 128. Adds another 64 possible
		sockets for server use.
				Rakesh Patel <[email protected]>
				David Hornsby <[email protected]>
	USING_FDDI_NET
		Includes code to determine if interface is running on
		FDDI network and adjust packets accordingly. Digital UNIX
		and Ultrix only at this stage.
				Conrad Huang <[email protected]>
	NOCAPDOTPRINTERS
		If defined, PAPIF will not use /etc/cap.printers, instead
		the first line of the file /etc/lp/printers/lw/comment (for
		printer "lw") is expected to contain a fully qualified
		AppleTalk NBP name for the printer, ie: lw:[email protected]
		This option is intended for use on Solaris 2.N hosts only.
				Andy Polyakov <[email protected]>
	USESYSLOG
		If defined, PAPIF will send Information, Warning and Debug
		messages to syslog().
				Andy Polyakov <[email protected]>
	DISTRIB_PASSWDS
		If defined, CAP will use AUFS authentication methods that
		involve exchanging encrypted random numbers instead of
		sending passwords in clear text over the network. Refer to
		manual entries aufsmkkey.8 and aufsmkusr.8 in cap60/man.
				David Hornsby <[email protected]>
	AFP_DISTPW_PATH
		Specifies that the distributed password files used in
		DISTRIB_PASSWDS be kept in a directory other than the
		user's home directory. For example, you could use the
		following -DAFP_DISTPW_PATH=\"/usr/local/lib/cap/upw\"
				David Hornsby <[email protected]>
	AFP_DISTPW_MODE
		Modifies the file mode being enforced with DISTRIB_PASSWDS.
		For use when user home directories are mounted via NFS. Uses
		mode 0600 by default, use 0644 with NFS.
				David Hornsby <[email protected]>
	DEBUG_AFP_CMD
		If defined, AUFS will dump detailed logs of AFP command I/O
		parameters in the file specified with the AUFS -Z option.
		Use in conjunction with Inside AppleTalk 2nd edition for
		debugging the AUFS AFP implementation.
				David Hornsby <[email protected]>
	LOG_WTMP
		If defined, AUFS will write an entry into the wtmp log file
		on each successful AUFS connection. Allows usage tracking.
				Gavin Longmuir <[email protected]>
				Heather Ebey <[email protected]>
	LOG_WTMP_FILE
		Specifies alternate name for the wtmp file used in LOG_WTMP.
				Heather Ebey <[email protected]>
	ADMIN_GRP
		If defined, AUFS will check if the user is a member of a
		special admin group and connect them with superuser privs.
				Tim Leamy <[email protected]>
	TEMPFILE
		Allow the LWSRV temporary file path to be specified.
				Serge <[email protected]>
	USELPRSYM
		Option to allow optional lpr '-s' (broken under OSF/1).
				Serge <[email protected]>


	The following were originally to be defined in m4.setup, they have
	been moved to m4.features for convenience.

	NONLXLATE - don't translate newlines on "line-at-a-time" reads
	FULL_NCS_SUPPORT - National Character Support
	GGTYPE="gid_t" - Host type definition for groups
	DOCNAME - include document name in lpr job name
	PAGECOUNT - include page count in lpr job name
	ADOBE_DSC2_CONFORMANT - Conform to Adobe DSC2 specs


CAP Patches
-----------

The primary source of CAP information is, as always, the network newsgroup
comp.protocols.appletalk.  This forum will continue to be used to disseminate
information about CAP 6.0 updates, but we would very much like to encourage a
slightly more formal approach to the process of propogating CAP patches.

Therefore, please send patches for CAP bug-fixes and new features to

	[email protected]

Context diffs (from 'diff -c') are preferred, but not essential.  Patches
received will be assigned a patch number, a priority and will be included in
regular (but not too frequent) CAP releases.  In addition to then being sent
to comp.protocols.appletalk, the patches will be available via FTP from

	munnari.OZ.AU		(in mac/cap.patches)
	rutgers.EDU		(in src/cap60.patches)
	gatekeeper.DEC.COM	(in pub/net/appletalk/cap/cap.patches)
	ftp.kuis.kyoto-u.AC.JP	(in net/cap/cap60.patches)
	src.doc.ic.AC.UK	(in mac/multigate/cap.patches)

The intent is to minimise the nightmare of trying to apply useful patches
that have come from divergent versions of the source code.  Another goal is
to reduce the maintenance needed for CAP code, if the incremental patches are
applied in order, the result will be identical to any new release.

To apply the patches with an absolute 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 sources are applied, some CAP patches can fail if the unmodified patch
code is used.

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.patch0NN

where NN is the patch number. The -p option tells patch to obtain
information about which file to alter from the patch header (use -p0 on
a DEC Alpha under OSF/1). 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 (and bug), this
is not good ...


CAP and AppleTalk Phase 2
-------------------------

CAP 6.0 supports EtherTalk Phase 2 using the SunOS NIT interface, the enet
packet filter (requiring kernel mods, see cap60/support/enet) and the ULTRIX
packet filter (ULTRIX 4.0 or later). It also is possible to use CAP in a
Phase 2 environment with IPTalk as indicated below.

Traditionally, the CAP transport mechanism uses UDP/IP packets. This is
called IPTalk (also known as KIP) and is a "non-extended" (1 net number
and 1 zone name) network. CAP with IPTalk can run on a LARGE variety of
UNIX platforms.

On some machines, CAP can also produce EtherTalk Phase 1 packets directly
(using Native EtherTalk, Kernel AppleTalk or UAB - the UNIX AppleTalk
Bridge). EtherTalk Phase 1 is also a "non-extended" network.

Macintoshes on EtherNet can speak EtherTalk Phase 1 or Phase 2. EtherTalk
Phase 2 networks are always "extended", allowing multiple network numbers
and zone names on a single cable. An "extended" network can be "restricted"
to have one net number and one zone name. This permits the Phase 2 routing
information to be translated into Phase 1 routing packet format. This is
not otherwise possible.

For completeness, LocalTalk networks can use either Phase 1 or Phase 2
AppleTalk packets, but such networks are always "non-extended".

In a brief summary of AppleTalk Phase 1 and Phase 2 differences on LocalTalk,
routing information (RTMP) packet formats are different. NBP packets allow a
new character (approxEquals or 0xc5) for partial NBP name and type matching.
Nodes are no longer required to send to the last RTMP sender that they heard
from, rather, they can choose to send to the "best" router. There are other
differences for Phase 1 and Phase 2 EtherTalk packets on EtherNet. These
differences relate mainly to delivery mechanisms.

If you use CAP with IPTalk and *NO* AppleTalk routing over IP (ie: via an
IP link between IP gateways) then you can use CAP with Phase 2, "extended"
networks with no restrictions (except of course, that you must have an
AppleTalk Gateway capable of talking IPTalk and EtherTalk Phase 2).

On the other hand, if you are using CAP and IPTalk with AppleTalk routing
over IP, or CAP with EtherTalk Phase 1, then your Phase 2 networks must all
be "restricted" and you need to have a gateway capable of operating in
"transition" mode (the problem with the first case is due to the way IPTalk
works rather than CAP. IPTalk 2 is under development and will solve this).

The gateway translates the packets from one format to another. Suitable
IPTalk/Phase 2 gateways are the Webster MultiPort Gateway (running Megan
2.1 or later) and the Shiva FastPath 4 (running KSTAR 8.0 or later). Most
earlier versions of the gateway code will happily translate from IPTalk to
either Phase 1 or LocalTalk.


See Also
--------

	Manual entries		cap60/man/*
	Various documentation	cap60/doc/*
	Native EtherTalk	cap60/support/ethertalk/README
	Kernel AppleTalk	lib/cap/abkas.c, netatalk-1.2 distribution

	http://www.cs.mu.OZ.AU/appletalk/atalk.html

Gotchas
-------

There are various problems known to exist with CAP and particular UNIX
systems or programs.

	ULTRIX:
		You may see the error message
			open: ln0: No such file or directory
		when running aarpd. The problem is due to missing packet
		filter devices in /dev/pf. For details on how to make the
		devices, refer to the manual entry for 'packetfilter'.

	ULTRIX 4.1:
		There is a problem with packet filter code in ULTRIX 4.1
		that prevents CAP writing packets to the network. Before
		running CAP with 4.1 (on any hardware platform), request
		the patched version of the file "net_common.o" from your
		DEC Customer Support Center. You may also need to obtain
		the updated "if_ln.o" to prevent problems with LAT.

	ULTRIX 4.2/4.2A:
		There are three known "problems" with packet filter code
		and unicast/802.3 packet handling under ULTRIX 4.2. The
		problems have been identified and fixed. Contact your
		local DEC Customer Support Center and query the status
		of patches for "net_common.o" and "pfilt.o". The problems
		and WORKAROUNDS for UNPATCHED systems are as follows:

		"unicast packets are not delivered properly to PF clients"
			define COPYALL mode using 'ifconfig ... +copyall'

		"802.3 (phase 2) AARP packets converted to EtherNet equiv."
			apply CAP patch 75, define ULT42PFBUG in Configure

		"3rd-party Mac EtherNet cards that round up odd 802.3 packets"
			no workaround, requires new net_common.o, pfilt.o
			with less stringent 802.3 length sanity checking.

	ULTRIX 4.3
		under ULTRIX V4.3 you may need to obtain a patched version of
		/etc/lockd to use DENYREADWRITE code. A possible workaround is
		to 'nfssetlock off' ... this will impact NFS mounted volumes.

	HP/Apollo Domain BSD 4.3
		Avoid using the //node/path syntax in afpvols, either
		explicitly or from expansion of ~.  If such a definition
		appears in afpvols, the volume corresponding to it may
		be visible in the Chooser but be unmountable or may not
		appear in the Chooser.  Other volumes defined after such
		a line also may not show up in the Chooser.  You may use
		directories mounted on other nodes using soft links or
		a path such as /../node/path.  It is not clear how much of
		the file locking carries over directories on other nodes.
		See NOTES for avoiding the //node/path construction.

	NFS
		In some circumstances, CAP AUFS using NFS mounted
		filesystems may complain about files being locked when
		they are not obviously so.  Ensure that you have the latest
		NFS bugfixes for your UNIX platform.


Bug Fixes
---------

The following CAP 5.0 bug fixes were incorporated into CAP 6.0.

	abpap.c.tickletimer	Jim Guyton <[email protected]>
	abpaps.c.flowquantum	William Roberts <[email protected]>
	procset.c.looping	William Roberts <[email protected]>
	mips.ultrix.byteswap	<[email protected]>
	snitch.c.stringlength	Phil Farrell <[email protected]>
	papif.c.atpresponse	Phil Farrell <[email protected]>
	papif.c.variousbugs	Jeff Stearns <[email protected]>
	papif.c.reverse		Robert McLay <[email protected]>
	afpos.c.strcmp		JQ Johnson <[email protected]>
	simple.c.comment	Mark Rawling <[email protected]>
	rtmp.c.nocase		John Sellens <[email protected]>

CAP with UAR

Herewith 10 easy steps to installing CAP with UAR:

1. Get the UAR package (mac/uar.tar.Z) via anonymous FTP from munnari.OZ.AU
and place it in a local directory 'uar'.  'cd uar', un-compress and un-tar
the package with 'compress -d uar.tar.Z' and 'tar -xvf uar.tar'

2. Check the README to ensure that your host is supported, currently UAR
supports Phase 1 and Phase 2 EtherTalk networks connected to SUN, DEC ULTRIX,
SGI IRIX, Sony NEWS 4.2, HP-UX and IBM RS6000 AIX workstations, and Phase 1
only on Sony NEWS pre-4.2 workstations.

3. Edit the 'Makefile' to add the necessary info to CFLAGS= and LIBS=
The requirements are listed per machine type (only NEWS, AIX & Solaris 2.N).

4. Compile the program by typing 'make'.  If compilation procedes without
error, type 'make install'. This step copies the binary to /usr/local/cap/uar

5. Decide on whether or not you are going to run UAR as a "seed router".
That is, if UAR is to be configured with details of your local AppleTalk
network or is to determine information empirically from the network.  For
UAR to function as a "seed router", you must create a uar.conf file that
contains network number(s) and zone name(s) for each of the participating
ethernet interfaces on your UAR host (see the sample uar.conf provided).
The information in uar.conf *must* be identical to the configuration in
any other AppleTalk routers on the local networks, this is not optional!
Normally your campus/institution network manager is the best source of
such information.

6. If you are absolutely certain that there are no other local AppleTalk
routers then you may choose numbers for the "network", "networklo" and
"networkhi" entries.  A "node" entry is optional.  Network numbers are
16-bit quantities and can range from 1 to 65534 (the values 65280 to
65534 are reserved as the "startup range" on Phase 2 networks, don't
assign a network number in this range).  These 16-bit numbers can also
be represented as two decimal numbers separated by a dot.  In this
notation, 56284 is represented as 219.220 (ie: 219 x 256 + 220). The
node number is an 8-bit number, the valid range is 1 - 254 on Phase 1
AppleTalk networks and 1 - 253 on Phase 2 AppleTalk networks (assume
Phase 2 for recent Macintoshes unless you know otherwise).  Node numbers
specified for UAR should be towards the high end of the range, ie: 253.
You must also choose a zone name or list of zone names for your network,
in the latter case specify one of them as the "default" zone name.  The
interface names are the device names for your ethernet interfaces and
can be listed using the command 'netstat -i'.  Under AIX, use "ent0",
"ent1" rather than the listed "en0", "en1".

7. Ensure that your CAP distribution is at least at patch level 144.
Run the Configure script and answer 'y' or 'yes' to the question
"Do you wish to use UAR (Unix AppleTalk Router) (default no) ?" and 'y'
or 'n' as necessary to "Do you want Phase 2 compatibility (no) ? "
Run 'gen.makes', 'make include' and 'make programs'.  See the CAP
documentation for more details.

8. To use UAR with CAP you must specify an interface for CAP to be
"attached" to.  With a uar.conf file, this is achieved with a "cap on"
entry, all other interfaces should have "cap off".  If no uar.conf file
exists then run UAR with a -C option.  This attaches CAP to the first
interface name listed in the UAR arguments.

9. Run UAR.  For example, on a single interface machine where UAR is used
only to support CAP (and not in it's usual function as an AppleTalk Router)
you would use

	uar -C le0

or, on a multiple interface machine

	uar -C ie1 ie0

where CAP is attached to "ie1", or with a uar.conf file

	uar et0 enp0

where "et0" and "enp0" are listed in the uar.conf file with "interface"
entries containing network and node numbers, zones and one "cap on" entry.

10. Check for "/etc/etalk.local" created by UAR.  Normally this takes up
to 15 seconds to appear (so in a start-cap-servers file insert a "sleep 20"
after starting UAR before starting the rest of the CAP programs).  With CAP
compiled for use with UAR it should now be possible to run test programs such
as 'cap60/samples/getzones' and 'cap60/samples/atlook' and see meaningful
results.  If not, consult your local network administrator or send email to
[email protected]  Please note that UAR vers 1.0 is FreeWare. A ShareWare
or site-license fee is payable for UAR version 1.1.

CAP with IPTalk

Herewith 10 easy steps to installing CAP with IPTalk:

1. Make sure that you have the latest CAP code. If in doubt, FTP the CAP
FAQ file mac/cap.patches/CAP.faq from munnari.OZ.AU. It contains a list of
the sites where CAP is available, please choose the closest site.

2. Run the CAP Configure program, answer all of the questions with the
defaults (by hitting RETURN). Run gen.makes to create the makefiles.

3. Find out the IP address of the CAP host, say 132.45.67.89. This is a 32
bit number represented as four 8-bit quantities written as decimal numbers.
It could also be represented as a hexadecimal number, 0x842d4359. The CAP
host node number is the bottom eight bits of the IP address, written as a
decimal number, in this case 89.

4. Find out the IP address of the IPTalk compatible gateway, such as a
FastPath, GatorBox or MultiPort Gateway, say 132.45.67.90. The "bridge"
node number is the bottom eight bits of the IP address, in this case 90.

5. Check that the top 24-bits of the two IP addresses are identical, in
this case 132.45.67. For simplicity I'll call this the IP subnet number.
If they do not match you have to investigate the atalkad administration
package, or use CAP with Native EtherTalk or one of the AppleTalk routers.

6. Find out the IPTalk network number being used by the gateway. This is
a 16-bit number represented as two 8-bit quantities separated by periods
or a single decimal number. For example 93.57 is 93*256 + 57, or 23865.
Each IPTalk network number is uniquely associated with one IP subnet
number, each IPTalk installation must have a unique network number where
the IP subnets differ.

7. (optional) Check all the other network numbers in use on your network,
make sure that the IPTalk network number is not being used for LocalTalk,
EtherTalk (Phase 1 or Phase 2) or on any other IPTalk network where the
IP subnet numbers differ.

8. Find out the zone name associated with the IPTalk network number. This
may be the same as other zone names on the network but must be identical
to the zone name programmed into the IPTalk gateway. eg: unimelb-CompSci

9. Create a file called /etc/atalk.local using the template provided in
cap60/etc/atalk.local and the UNIX manual entry in cap60/man/atalk.local.5
As a minimum, the file would look like the following, using the numbers
from the examples used above, comment lines start with a '#'

# mynet         mynode          myzone
93.57		89		unimelb-CompSci
# bridgenet     bridgenode      bridgeIP
93.57		90		132.45.67.90

10. Find out what UDP ports are being used on the IP network. These are
also called the "NIC Assigned" ports. These ports map to AppleTalk socket
numbers and are used to deliver packets to the correct UNIX processes. By
default, CAP will use the ports starting at 768 so that the RTMP socket
number 1 maps to UDP port 769 and the ECHO socket 4 maps to 772. The
official port range starts at 200, so RTMP becomes 201 and ECHO becomes
204. To ensure that CAP uses the official ports, add the following entries
to the file /etc/services or the NIS database

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

The port numbers should already be defined in the gateway configuration.

Continue testing from the [10] Verification step in cap60/doc/install.ms

Note: if you are using CAP with Native EtherTalk then ignore all but step 1.
The Native EtherTalk code is able to learn the network configuration. If
you have an /etc/atalk.local file, you should remove it. If there are no
other routers on the network, start aarpd with "*" as the zone name. The
UDP ports are also used in Native EtherTalk, as markers for sockets in use.
If a CAP process has trouble starting the ZIS listener or ECHO or NBP
sockets are unavailable, consider installing the official UDP port entries.

CAP Documentation

See Also