INSTALL.historical

Quick Installation Instructions
-------------------------------

1. Unpack the archive (though if you're reading this you've already
achieved that)

   tar -zxvf tsocks-<version>.tar.gx

2. Run ./configure, options which might be of interest (and that are 
   specific to tsocks include):
	--enable-socksdns	This option causes tsocks to intercept
				DNS lookups and attempt to force them
				to use TCP instead of UDP and thus
				be proxied through the socks server. This
				is not a very elegant thing to do and
				should be avoided where possible.
	--disable-debug		This configuration option tells tsocks
				to never output error messages to stderr.
				This can also be achieved at run time
				by defining the environment variable
				TSOCKS_NO_ERROR to be "yes"
	--enable-oldmethod	This forces tsocks not to use the
				RTLD_NEXT parameter to dlsym to get the
				address of the connect() method tsocks
				overrides, instead it loads a reference
				to the libc shared library and then uses
				dlsym(). Again this is not very elegant
				and shouldn't be required.
	--disable-hostnames	This disables DNS lookups on names
				provided as socks servers in the config
				file. This option is necessary
				if socks dns is enabled since tsocks
				can't send a socks dns request to resolve
				the location of the socks server. 
	--with-conf=<filename>	You can specify the location of the tsocks
				configuration file using this option, it
				defaults to '/etc/tsocks.conf'

Other standard autoconf options are provided by typing './configure
--help'

NOTE: The install path for the library is _NOT_ prefixed with --prefix,
this is because it is strongly recommended that tsocks is installed into
/lib (and not /usr/lib). This is important if tsocks is put into
/etc/ld.so.preload since /usr is not mounted on many systems at boot
time, meaning that programs running before /usr is mounted will try to
preload tsocks, fail to find it and die, making the machine unusable. If
you really wish to install the library into some other path use --libdir.

3. Compile the code by typing:

	make

This should result in the creation of the following:
	- libtsocks.so - the libtsocks library
	- validateconf - a utility to verify the tsocks configuration file
	- inspectsocks - a utility to determine the version of a socks server
	- saveme - a statically linked utility to remove /etc/ld.so.preload
		   if it becomes corrupt

4. If you experience any errors at this step and don't know how to fix
them, seek help using the contacts listed on
http://tsocks.sourceforge.net/contact.php

5. Install the compiled library. You can skip this step if you only plan
to use the library for personal use. If you want all users on the machine
to be able to use it however, su to root then type

   make install

This will install the library, the tsocks script and its man pages
(tsocks(8), tsocks(1) and tsocks.conf(5)) to the paths specified to
configure.

Note that by default the library is installed to /lib and that the
configure --prefix is IGNORED. See above for more detail. 

6. At this point you'll need to create the tsocks configuration file.
There are two samples provided in the build directory called
tsocks.conf.simple.example and tsocks.conf.complex.example.
Documentation on the configuration file format is provided in the
tsocks.conf man page ('man tsocks.conf'). 

7. Having created the tsocks.conf file you should verify it using
validateconf (some detail on validateconf can be found in the tsocks.conf
man page). Normally validateconf is run without arguments
('./validateconf'). Any errors which are displayed by validateconf need
to be rectified before tsocks will function correctly.

8. You can now choose to make the library affect all users or just those
who choose to use it. If you want users to use it themselves, they can
simply use the tsocks(1) shell script to run programs (see 'man tsocks')
or do the following in their shell before running applications that need
to be transparently proxied:

	(in Bash) export LD_PRELOAD=<path to library>

	(in CSH) setenv LD_PRELOAD <path to library>

	<path to library> = e.g /lib/libtsocks.so.1.8

If you want all users to pick up the library, place the full path to the
full library in the file /etc/ld.so.preload (e.g "/lib/libtsocks.so"). Be
EXTREMELY careful if you do this, if you mistype it or in some way get it
wrong this will make your machine UNUSABLE. Also, if you do this, make
sure the directory you put the library in is in the root of the
filesystem, if the library is not available at boot time, again, your
machine will be UNUSABLE. 

9. Go ahead and use it! At this point everything should work. Again, if
you experience any problems, use the contact points listed at
http://tsocks.sourceforge.net/contact.php. If you do happen to break your
machine with /etc/ld.so.preload, the build process creates a statically
linked executable called saveme in the build directory. This executable
simply unlinks /etc/ld.so.preload, this may or may not save you so give
it a try. If it fails, you'll need to switch off the machine and get a
rescue disk (e.g tomsrtbt) mount the disk and remove the file manually.

Thats it, 

Thanks, Shaun Clowes (delius@progsoc.org)