This is CSTC version 4.2 of SOCKS, a package that allows Unix hosts
behind a firewall to gain full access to the internet without requiring
direct IP reachability. It does require a SOCKS server program being
run on a hosts that can communicate directly to hosts behind the firewall
as well as hosts on the Internet at large.  It is based on the original
SOCKS written by David Koblas <koblas@netcom.com>.

The package includes full source for the SOCKS server and SOCKSified
client programs of finger, ftp, telnet, and whois. A few other SOCKSified
clients may be found on ftp.nec.com, in directory /pub/security/socks.cstc.
Increasingly, software developers are beginning to include SOCKS support
directly into their products, for example, Mosaic, Netscape, Trumpet
Winsock, TCP/Connect II (from InterCon for Macintosh; they also intend
to do so for their Windows version), OutsideVew for Windows (from Crystal
Point, currently in beta).

Besides various minor bug fixes and improvements, the major differences
between this release and 4.1 are:

1) Can handle nonblocking connect() calls, or at least the way such calls
   are used in Mosaic.

2) SOCKSification of application programs is simplified. No code modification
   is necessary, just recompile with appropriate directives (see the file
   How_to_SOCKSify).

3) Option to build stand-alone sockd. This is especially beneficial for
   sites that have to use a big sockd.conf file.

This version is known to work on the following Unix platforms:

SunOS 4.1.3
Irix 4.0.5H, 5
Ultrix 4.3
HP-UX 9.05
AIX 3.2.5
Interactive 4.1
DEC OSF/1 AXP 3.0
Solaris 2.3, 2.4
Linux 1.1.18
SCO/ODT 2.x
DG/UX 5.4.3
FreeBSD 1.1.5.1

Though I have not received final confirmation, it is likely that
the package may also work on the following platforms:

NetBSD 0.9
UnixWare
BSDi 1.0
PS/2 AIX 1.2.1
NextStep 3.2 (server and library only)

-------------------
All 4.2 clients work with all 4.x servers. 4.0 clients work
with single-homed 4.2 servers but NOT with 4.2 multi-homed servers.
4.1 clients work with 4.2 servers, both single- and multi-homed.
'sockd -ver' tells you not only the version number but also whether
it is single- or multi-homed.

Please see below for the procedure for building and testing.
Remember that the names of the control files are all configurable
in include/socks.h. It will probably greatly reduce your frustration
while you are flipping between the old and the new versions if you
uses different file names for the new version. 

There is now a mailing list devoted to issues related
to SOCKS. To join the list, please send an email subscription request
to majordomo@syl.dl.nec.com with

	subscribe socks your@email.address

in the body of the message.

Finally, I want to thanks all the people who have helped in making
and shaping this release. These are the ones that I remember:

Jason Baietto, Brad Beach, David Blob, John Brezak, Dave Brower,
Brian M. Clapper, Matt Cohen, Adrian Colley, Bryan Curnutt, Ian Dunkin,
Steve Danz, Thomas Essebier, Andrew Fullford, Matthew R. Ganis,
Phil Hochstetler, LaMont Jones, Larry Jones, Cornell Kinderknecht,
Edwin Kremer, William Lewis, Rob Liebschutz, Jon Luini, Stephen Ma,
Andy McFadden, Alain Mellan, Craig Metz, David Mischel, Heinz Naef,
David Nochlin, Garry M. Paxinos, Hal Pomeranz, Chris Riney,
Andreas Siegert, John Scott, Fred Stephens, Shin'ichiro Tanaka,
Mike Tollerton, Satoshi Toyosawa, Paul van Deurzen, Syd Weinstein

My sincere apologies to those that I forget to mention -- please
remind me!

Without in any way diminishing the contributions of others in the
list, I would like to pay special tribute to David Mischel for his
code for the stand-alone sockd, and to Bryan Curnutt for porting to
and testing the package on 9 (!) platforms.

	Ying-Da Lee	(214)518-3490	(214)518-3552 (FAX)
	Principal Member, Technical Staff
	NEC Systems Laboratory, C&C Software Technology Center /
	NEC USA, Corporate Network Administration Division
	ylee@syl.dl.nec.com
====================================================================

Please read the file 'COPYRIGHTS' before you proceed further.

In the following section, by 'top directory' we mean the top
directory of the SOCKS package, i.e., the directory you are
in right now.

-------------------------------------------------------------

HOW TO BUILD THE PROGRAMS

1. Check and modify the following files to suit your systems:

	Makefile
	include/socks.h

   Be sure that the macro 'SOCKS_DEFAULT_SERVER' in include/socks.h
   is set correctly to the host that will be running the proxy server
   for your site.  Although this can be overridden at run time with
   environment variable SOCKS_SERVER, it is a lot simpler if you put
   in the right name at compile time. Also be sure to uncomment and set
   the macro 'SOCKS_DEFAULT_NS' in the same file if your client machines
   normally can't do DNS resolution for outside hosts.

   Be sure that the macros 'ORIG_FINGER' and 'MULTIHOMED_SERVER' in
   include/socks.h are set correctly.

   If you need a large configuartion file with many rules for access
   control (I have heard of sites with up to 2,000 lines in sockd.conf!),
   you should try using a stand-alone SOCKS server, i.e., one that runs
   without the control of inetd. To build a stand-alone SOCKS server,
   you must define the macro NOT_THROUGH_INETD in include/socks.h.

   In most cases, you should have no needs to modify the Makefiles
   in the subdirectories. But if you run into problems, you may
   have to look into modifying

	sockd/Makefile
	libident/Makefile
	lib/Makefile
	rfinger/Makefile
	rftp/Makefile
	rtelnet/Makefile

   If your system is not among those included in the top Makefile,
   then you may also have to construct an entry for your system
   in the file rtelnet/Config.local.

2. cd to the top directory and issue 'make' command.  It's a good
   idea to direct stdout and stderr to a file so that you can
   see what's being done afterwards. There will be a few warning
   messages which you can ignore. This builds the server as well
   as all the clients.

   If you only want to build the server, use command 'make server'
   instead.  Use command 'make clients' to build only the client
   programs. You can also build the individual clients using
   'make RFINGER', 'make RFTP', and 'make RTELNET', all from the
   top directory.

3. All the man pages (except for libident) are in directory doc.
   You are encouraged to print them out and read them before proceeding
   to the next part.

-------------------------------------------------------------

HOW TO INSTALL THE SERVER

1. Become superuser on the proxy server host for your site. 

2. cd to the top directory and issue 'make install.server'.
   This installs sockd and its man page.

3. Add the line
socks	1080/tcp
   to file /etc/services. It would be nice also to include
gopher	70/tcp
WWW	80/tcp
   in the file if you don't already have them.

4. Set up access control with file /etc/sockd.conf. You have to
   read the man pages for sockd and sockd.conf for the details.
   For a quick test, you can use these four lines in the file: (Replace
   'client_IP' with the IP address of the host on which you will be
   testing the client programs.)
permit	client_IP   255.255.255.255
# One LONG line follows:
deny	0.0.0.0 0.0.0.0 : /usr/ucb/finger @%A | /usr/ucb/mail -s 'SOCKD: rejected -- from %u@%A to host %Z (service %S)' root
# Another LONG line:
#BAD_ID: /usr/ucb/finger @%A | /usr/ucb/mail -s '%U pretends to be %u on host %A' root@%A root
# Last line:
#NO_IDENTD: /usr/ucb/mail -s 'Please run identd on %A' %u@%A root@%A
   This is essentially the contents of file sockd/sockd.conf.sample.

5. If the server host is multi-homed and you built sockd with the
   macro MULTIHOMED_SERVER in include/socks.h defined, you must
   also supply the file /etc/sockd.route. For a typical dual-homed
   server, this can simply be a one-liner:
out_interface	0.0.0.0 0.0.0.0
   where out_interface is the IP address of the server's network
   interface leading to the outside world. The format for lines
   in this file should be
# comments
Interface_addr	dst_addr dst_mask

   Read the man page on sockd.route !!!

6a. For sockd that is to be controlled through inetd (i.e.,
   you made the server with NOT_THROUGH_INETD in include/socks.h
   undefined):
   Add the line
socks	stream	tcp	nowait	nobody	/usr/etc/sockd	sockd
   to file /etc/inetd.conf. Use the actual path where sockd
   is installed if not in /usr/etc. If you want to make use of
   identd on your client machines when it is available, use
socks	stream	tcp	nowait	nobody	/usr/etc/sockd	sockd -i
   If you want to REQUIRE identd be run on your client machines,
   use
socks	stream	tcp	nowait	nobody	/usr/etc/sockd	sockd -I
   Running sockd with -I will reject all requests from hosts that
   do not run identd.
   Send a SIGHUP signal to the running inetd process so that it will
   use the new configuration.

6b. For stand-alone sockd (i.e., you made the server with
   NOT_THROUGH_INETD in include/socks.h defined):
   Just invoke the sockd program, e.g., /usr/etc/sockd. Use the
   actual path where sockd is installed if not in /usr/etc. If you
   want to make use of identd on your client machine when it is
   available, use the -i option. If you want to REQUIRE identd be
   run on your client machines, use the -I option.

7. You may have to do some other things to accommodate syslog. Read
   the man pages on syslogd and syslog.conf.

-------------------------------------------------------------

HOW TO TEST THE CLIENT PROGRAMS

   NOTE: Build and install identd on your client hosts first. This is
   required if you run sockd with -I option. It is a good idea anyway.

   Set up the file /etc/socks.conf on the client host. Lines in this
   file should be of the form
# comments
deny [*=userlist] dst_addr dst_mask [op port]
direct [*=userlist] dst_addr dst_mask [op port]
sockd [@=serverlist] [*=userlist] dst_addr dst_mask [op port]
   Fields in square brackets are optional. The optional @=serverlist
   field with a 'sockd' line specifies the list of SOCKS servers
   the client should try (in the given order) instead of the default
   SOCKS server.  If the @=serverlist part is omitted, then the default
   SOCKS server is used. Commas are used in the userlist and serverlist
   as separators, no white spaces are allowed.

   Read the man page on socks.conf !!!

   On a client host (for testing purpose, this can be the same as
   the proxy server), the clients rfinger, rwhois, rftp, and rtelnet,
   can be tried out without any additional setup on the
   client host once the server is running. They should behave like
   finger, whois, ftp, and telnet, respectively. rftp DOES
   echo your password IF you are using 'anonymous' as the log-in name.

   Quite a lot of details of operations of both the clients and the
   server are logged. Checking the contents of the log files may be
   helpful when you run into problems. You should try using these
   clients to connect to both inside and outside hosts and check the
   log messages to see whether the correct ways are used.

-------------------------------------------------------------

HOW TO INSTALL CLIENT PROGRAMS

1. Become superuser on the client host.

2. cd to the top directory, then issue the command 'make install.clients'.
   This installs rfinger, rwhois, rftp, rtelnet, and
   their man pages.

3. Rename your regular 'finger', 'whois', 'ftp', and 'telnet'
   to something else. The new name for the 'finger' program
   must be EXACTLY what you used for defining the macro ORIG_FINGER in
   include/socks.h. Then either rename the SOCKS clients or use symbolic
   links for them. For example, if you have installed the clients in
   directory /usr/local/bin and your regular 'finger', 'whois', 'ftp',
   and 'telnet' were in /usr/ucb, then you should do
ln -s /usr/local/bin/rfinger /usr/ucb/finger
ln -s /usr/local/bin/rftp /usr/ucb/ftp
ln -s /usr/local/bin/rhwois /usr/ucb/whois
ln -s /usr/local/bin/rtelnet /usr/ucb/telnet