# @(#)README	1.11 00/01/27

This software represents the "Packet Shell", an extensible
TCL/Tk based software toolset for protocol development and testing.

In Sun Engineering, the packet shell is available for installation
as SVR4 packages in /home/internet/psh/pkgs for either the sparc or
i386 architectures.  Elsewhere it is available on the Internet from
anonymous ftp to playground.sun.com in the directory /pub/psh
for either the sparc or i386 architectures:

	Current Official Release:

	psh-sparc-40.Z		Compressed file of binaries for SPARC
	psh-i386-40.Z		Compressed file of binaries for i386
	psh-src-40.tar.Z	Compressed tar file of source files
	tcltk-sparc-40.Z	Compressed file of Tcl/Tk for SPARC
	tcltk-i386-40.Z		Compressed file of Tcl/Tk for i386

	Current Development Release:

	psh-sparc-41alpha.Z	Compressed file of binaries for SPARC
	psh-i386-41alpha.Z	Compressed file of binaries for i386
	psh-src-41alpha.tar.Z	Compressed tar file of source files
	tcltk-sparc-41alpha.Z	Compressed file of Tcl/Tk for SPARC
	tcltk-i386-41alpha.Z	Compressed file of Tcl/Tk for i386

Please note that the Development Releases are an early snapshot of
future technology in the Packet Shell and as such are treated "as is".

You can install these files as root using the pkgadd command 
(example below).

 # uncompress psh-sparc-40.Z tcltk-sparc-40.Z
 # pkgadd -d tcltk-sparc-40
 # pkgadd -d psh-sparc-40

The directories installed under /opt/tcltk are:

	bin	Binaries (Tcl Version 7.6 and Tk Version 4.2)
	lib	Libraries for Tcl/Tk
	include	Include files for Tcl/Tk
	man	Manual pages and demos for Tcl/Tk

The directories installed under /opt/psh are:

	bin     Binaries (psh and xpsh for Tk support)
	lib	Dynamically linked protocol libraries
	man	Documentation and manual pages
	scripts	Scripts written for the packet shell (some better than others)
	tcllib  Tcl/Tk resource files for the packet shell

To build and install on a SunOS 5.5 system:

	(Install TCL & Tk.  7.6 and 4.2 are recommended, respectively.)
	% cd src; make
	% make install

Environment variables:
	  
PSH_LIB
	This environment variable specifies the location of the psh
	libraries, if they are not in the default location (/opt/psh/lib).

TCL_LIBRARY:
	This environment variable specifies the location of the tcl
	libraries, if they are not in the default location
	(/opt/tcltk/lib/tcl7.6).

Example:
1.Setting environment variable TCL_LIBRARY:
	setenv TCL_LIBRARY /net/kitzbuhl2/opt/tcltk/lib/tcl7.6
2.Setting environment variable PSH_LIB:
	setenv PSH_LIB /net/kitzbuhl2/opt/psh/lib
3.Running Packet Shell:
	/net/kitzbuhl2/opt/psh/bin/psh
	  
Development Release Gotchas:

The pinit command now always takes two optional length arguments. 
The first argument, if provided is the length of the allocated buffer
space.  If another argument is specified, it is the desired length of
this protocol layer.  Only if both length arguments are specified can
optional protocol library arguments be sent.  We have provided a default
interface by specifying '-' as the arguments.  It will then use the default
values for these two arguments.

For IPv6 support, please add the following to /etc/protocols (You
might also need to change your /etc/nsswitch.conf settings):

ipv6		41	IPv6		# IPv6 in IP encapsulation
ipv6-route	43	IPv6-Route	# Routing Header for IPv6
ipv6-frag	44	IPv6-Frag	# Fragment Header for IPv6
ipv6-icmp	58	IPv6-ICMP	# IPv6 ICMP
ipv6-nonxt	59	IPv6-NoNxt	# No Next Header extension for IPv6
ipv6-opts	60	IPv6-Opts	# Destination Options for IPv6

The Makefile supplied is intended for SunOS 5.6 and later systems,
in which ld(1) supports a -N<object> option.  When linking file `foo',
passing `-Nbar' to the linker adds information to the `foo' object
that tells the dynamic linker to link in `bar' before it attempts to
link in `foo'.  This is used because some protocol libraries in the
packet shell use utilities provided by other libraries.  For example,
the TCP library uses the IP library's checksum routine for computing
the TCP checksum.  On systems which do not support -N, remove -Nbar
from the Makefile -- however, if "Bad object" errors appear when psh
is run, you must reinstall the protocol libraries in /opt/psh/lib.  In
general, this shouldn't be a problem.

It includes <pthread.h>.  If you running on an older system (Solaris 
2.4), you may not have that include file.  It's okay to delete it -
only a weird internal protocol library needs it.

The following protocol libraries exist currently:

 IP
 IPv6
 IPv6 extensions (fragment, hop-by-hop, destination, routing options)
 ICMP
 ICMPv6
 Ethernet Layer
 Data
 File (snoop and tcpdump formats)
 Socket
 TCP
 TLI
 Streams (Internal Sun Engineering Only)
 DHCP
 Syscall

Ether Protocol Support:

The ether protocol library now uses libpcap, making the Packet Shell
much more portable.  It will soon provide access to other link layers
than just ethernet.

Though libpcap can normally be fetched from ftp.ee.lbl.gov, it's
included in the Tcl/Tk package so that you don't need to get it and
build it.

TCP Protocol Support:

The TCP protocol library uses a socket(AF_INET, SOCK_RAW, IPPROTO_TCP)
and assumes this will allow an application to send and receive connections
on a particular address, and *not* give the TCP in the kernel those packets
which are for the connection the Packet Shell has bound.  To our knowledge
only more recent SunOS releases actually support this.  SunOS 5.6 is strongly
recommended for this.  To use earlier versions of SunOS, the old version of
tcp.c, from PSH version 4.0 is recommended.  You can just drop in that binary
into /opt/psh/lib.

Care needs to be taken that the correct checksum is provided on the TCP
packet when sent.  Add that code to tcp_send(), if the SOCK_RAW socket
does not provide it.

Correspondence on a better BSD solution for future releases is encouraged.


Disclaimers, Contact Info:

At this time, the packet shell is an experimental, unsupported
prototype.  Feedback and code contributions are gratefully accepted and
will normally be redistributed.  However no promise can be made about
what attention can be given to your feedback.

Send any comments, fixes, etc. to:

	owner-packet-shell@sunroof.eng.sun.com

Tutorial, Help Info:

We are currently in the process of building an online tutorial via
the Web.  We have placed an early version of it on the Web site:

http://playground.sun.com/psh/tutorial.html
