Welcome to NWSL's (previously CSTC) socksv5!

socksv5 allows UNIX hosts behind a firewall to gain full access to the
Internet without requiring direct IP reachability. socksv5 requires a SOCKS
daemon running on a host that can communicate directly with hosts behind the
firewall and with hosts on the Internet. socksv5 is based on the original
SOCKS, written by David Koblas <koblas@netcom.com>, and the IETF AFT working
group.

NEC developed the socks5 system using GNU's ANSI-C compiler. You must use an
ANSI-C compiler to build your socks5 system. If you experience problems
building socks5 with your native compiler, we recommend using GNU's ANSI-C
compiler. You can download GNU's ANCI-C compiler, tar, and zip from:
            ftp://prep.ai.mit.edu/pub/gnu/

To support some socks5 protocol features, requires available libraries and
programs on your system. Some of these requirements include:
    - To build socks5 with GSS-API authentication requires a Kerberos5-based
      GSS-API library.
    - To build socks5 with IDENT, you need an ident library.
    - To support the ping and traceroute proxies, you must have these
      programs in your PATH.


socks5 Daemon
=============

The socks5 daemon can run:
	- standalone
	- pre-forking, by adding the -p flag
	- threaded, by adding the -t flag if you configured with the
	  --with-threads options and the operating system supports
	  POSIX threads
	- through inetd, by adding the -i flag

socks runs in threaded mode if the operating system supports POSIX threads.
Because the optimum mode is highly operating system and hardware dependent,
it is impossible to state the best mode.

NEC has tested threading on Solaris and IRIX UNIX systems. Be aware that all
operating systems impose limits on the number of threads and the number of
open file descriptors per process.

The maximum number of child processes limits standalone and pre-forking
modes. The default number of child processes is 64. The socks5 daemon
includes a -n(--nchildren) option to change the default. The number of socks5
child processes can not exceed the system limit.

To turn on debug mode, include the -d flag or configure with the
--with-debug option. Only use debug mode when you must debug the server.
During debugging, you may want to include the -o flag to force the server
to accept only one request and to prevent it from forking.

Use the -f flag to keep standalone versions in the foreground. 

Kerberos users: You may experience problems building the shared library if
your Kerberos libraries are not sharable. After successfully including the
Kerberos libraries, extraneous characters may appear in your output. The
extra characters are a result of how your shared linker replaces read and
write calls. Try using runsocks without integrity or confidentiality
checking. To omit integrity and confidentiality, set SOCKS5_NOINTCHK in
your environment before using runsocks.

RealAudio requires no special setup.


Configuration Parameters
========================

Please read INSTALL for configure and compile instructions. socks5 includes
several package-specific options that you can include with the ./configure
command. Some of the most commonly used options include: 

--with-krb5[=path]
Sets socks5 to build with Kerberos support and optionally sets the location
of the Kerberos library. If you omit the path, socks5 checks for krlogin
lines in /etc/inetd.conf 

--with-ident[=path]
Sets socks5 to support ident mode and optionally sets the location of the
ident header file and library.

--with-debug
Turns on debug and compile time warnings, for gcc, and turns off
optimization

--with-static
Turns on static compilation of most binaries

--with-threads
Turns on thread support if the operating system supports it

--with-libconffile=filename
Sets the client configuration file. If you omit this option, socks5 uses
/etc/libsocks5.conf in most cases. Under FreeBSD's UNIX port, the configuration
file resides in /usr/local/etc/libsocks5.conf.

--with-srvconffile=filename
Sets the server configuration file. If you omit this option, socks5 uses
/etc/socks5.conf in most cases. Under FreeBSD's UNIX port, the configuration 
file resides in /usr/local/etc/socks5.conf.

--with-srvpidfile=filename
Sets the server pid file, where the socks5 daemon stores its process id. If
you omit this option, the daemon stores its pid in /tmp/socks5.pid.

--with-srvpwdfile=filename
Sets the server Username/Password authentication file. If you omit this
option, socks5 uses /etc/socks5.passwd in most cases. Under FreeBSD's UNIX 
port, the password file resides in /usr/local/etc/socks5.passwd.

--with-srvidtfile=filename
Sets the server ident file. If you omit this option, socks5 stores the ident 
file in /tmp/socks5.ident.

--with-default-port=number
Sets the default socks port number. socks5 uses port 1080 if you omit this
option.

--with-default-server=hostname
Sets the default socks server. If you omit this option, socks uses the local
host.

--with-default-version=number
Sets the default socks version. If you omit this option, socks uses direct
connect.

--with-syslog-facility=facility
Sets the default syslog facility. socks5 uses LOG_DAEMON when you omit this
option.

--with-passwd
Instructs socks5 to use the system password file in socks5 Username/Password
exchanges instead of the socks5 username and password file. For security
reasons, we do NOT recommend this option.

socks5 Configuration Files
==========================

The socks5 daemon requires a configuration file, socks5.conf. socks5 clients
optionally read the client configuration file, libsocks.conf. If you omit
the libsocks5.conf file, set the SOCKS5_SERVER environment variable.

socks5.conf supports these entries:

	auth lines        - identify the types of authentication the socks5
                            daemon can use. The server requires auth lines 
                            to perform authentication.

	interface lines   - identify to the server which network interfaces
                            the server should use for outbound connections.
                            We strongly recommend using interface entries in a
                            multi-homed server configuration file. It is
                            more efficient to use a default interface entry with
                            the destination address and port fields set to
                            any, "-". interface lines are not useful for 
                            single-homed servers.

	proxy lines       - identify to the server how it should establish a
                            proxy connection, directly or through another 
                            socks server. You MUST include proxy entries to
                            make server-to-server (VPN) connections.

	permit/deny lines - identify to the server the connection requests 
                            that it should authorize. The order of
                            permit/deny lines is critical because the server
                            checks permit/deny entries in sequential order.
                            When it locates a match, it stops checking. When
                            the server fails to locate a match, it denies
                            authorization. You MUST have at least one permit
                            entry in your socks5.conf file.

The socks5 daemon supports both socks4 and socks5 clients and communicates
with SOCKS4 servers. Be aware of the differences between socks5 and SOCKS4
servers.


socks5 Clients
==============

The socks5 package includes client applications intended to demonstrate the
socksification process. Developers using the socks5 package submitted the 
applications to NEC. NEC did NOT write the applications. Although they work,
they do contain bugs. NEC has no intention of fixing or maintaining these
applications. We will try to include newer versions of these applications in
future releases. This distribution includes these socks5 clients: ftp,
telnet, archie, finger, whois, rping, and rtraceroute.

If your operating systems supports shared libraries, the socks5 package
builds the socks shared library. The shared library allows non-socks5 clients
to run with the runsocks shell script included in the shlib directory.

runsocks re-orders the dynamic library, linking the new shared library
before libc, resulting in some socksified commands, including connect and
bind. runsocks works under FreeBSD 2, SunOS 4, Solaris 2, Irix 5, and OSF1.
runsocks dynamically socksifies existing applications, without recompiling.
To use runsocks:

    - Your operating system must support the socks5 shared library
    - Your operating system must support the dynamic shared library 
      loading path
    - You must build applications with the dynamic shared C and
      socket libraries

NEC tested the current version of runsocks on Solaris, SunOS, OSF1, IRIX,
and Linux.


Platforms
=========

socks5 relies on the operating system. We try to support as many operating
systems as possible. However, it is impossible to support all UNIX
platforms. We release the source and encourage others to support additional
UNIX platforms.

Operating systems do contain bugs. We cannot fix those bugs and encourage
you to submit these problems to your operating system developers for bug
fixes. For example, Linux 2.0 has bugs in the shared library loader that
cause a segmentation fault message following runsocks.


socks5 Error Messages
=====================

Developers are the intended audience for most logging messages. We recommend
that you refer to the source code to fully understand the messages. Error
messages in the log file do not mean the server malfunctioned. For example,
some HTTP proxies generate S5IORecv ...  messages.


Mailing Lists
=============

NEC maintains a mailing list, socks5@syl.dl.nec.com, to discuss problems
and suggestions. To subscribe, send mail to:

	majordomo@socks.nec.com

In your mail message, omit the Subject. Include a one-line body containing:

	subscribe socks5


socks5 Bugs
===========

We encourage all socks5 users to report problems and provide patches for
problems you encounter with socks5. 

PLEASE NOTE: When submitting bug reports, it is most helpful for you to
include debug output. Debug output greatly assists us in isolating problems.
To turn on debug mode for clients, set the client environment variable
SOCKS5_DEBUG. To turn on debug mode when you start the socks5 daemon,
include the -d flag.

To submit problem reports, or send mail not distributed to a mailing list,
send mail to:
        socks5-bugs@socks.nec.com


socks5 Information
==================

We welcome your comments to: socks5-comments@socks.nec.com

For more information on how to build and use the socks5, please visit our 
socks web site at:
	http://www.socks.nec.com/


