Documentation for razor-caching-proxy.pl
Copyright 2002 William Stearns (wstearns@pobox.com)
This documentation and the razor-caching-proxy.pl script are both
released under the GPL.

(Quickstart at the end)

	razor-caching-proxy.pl is a perl script that acts as a caching
proxy for razor (http://razor.sourceforge.net) spam queries.  The
permanent site for this package is
http://www.stearns.org/razor-caching-proxy/ .

	As of version 0.3.0, the script is generally functioning, but
has not been extensively tested.  Translation: it seems to work pretty
well here, but it needs a few more pairs of eyes to check it over. 
Plese send any feedback, patches, feature requests to William Stearns
(wstearns@pobox.com).

	The proxy does _not_ need to run as root.  I'd strongly
recommend running it as a completely new user; just create the log file
writable by that user and the cache file readable and writable by that
user.

	If you've used a version up to 0.2.3 and want to move up to
version greater than or equal to 0.3.0, you'll either need to delete
your cache or add a timestamp to the beginning of each line; easily done
with the following commands:

#shutdown current (up to) 0.2.3 razor cache
cat /var/cache/razor/razor-cache | sed -e "s@^@`date +%%s`/@" >/var/cache/razor/razor-cache.v3
less /var/cache/razor-cache.v3	#Check that timestamps were added as the first field.
mv -f /var/cache/razor/razor-cache.v3 /var/cache/razor/razor-cache
#startup new 0.3.x (or greater) razor cache

	The proxy can now set maximum ages for positive and negative
entries with the --max_pos_age (seconds) and --max_neg_age (seconds)
command line parameters.  For example, if you only want to cache
Positive entries for 1 day, add "--max_pos_age 86400" to the proxy
command line.  Your cache file may hold entries older than a day, but
they won't be used in an invocation of the proxy with that parameter.

	I'd suggest a relatively small number for negative entries (the
default is 2 hours) and a much larger entry for positive (default 30
days).

	To test the basic network operation of the script, copy the
script to some directory in your path, make it executable, enable the
tcp echo port on your machine and run:

razor-caching-proxy.pl --server_n=localhost:7 --ca=/tmp/razor-echo-cache --foreground --v --v
	then:
telnet localhost 2702
	in another window.  In the telnet session, hand the proxy requests such as:
key:d97b1764b257f4f67a7d7fc9e6988aace12c5a56&action:lookup
	End your input with a single '.' (no quotes) on a line by itself.

	By declaring that the real razor server can be found at
localhost:7 (the echo port), we get whatever we typed back as a
response.  Good for basic networking and functionality tests only. 
Because the echo port never closes the connection at its end, the proxy
children that actually handle client requests don't close correctly. 
You'll need to kill them off by hand at the end of testing.

	To start it up as a full caching proxy, create /var/log/razor,
make it writable by the user who will be starting the daemon, and run:

razor-caching-proxy.pl -v

	To start a simple test client run to check functionality:
cat testkeys | nc localhost 2702
cat testkeys | nc localhost 2702

	Each run should return:
Vipul's Razor 1.11, protocol version 2.
Negative 52b08efcfed6a9911248ce7592f9b08d7949d840
Positive d97b1764b257f4f67a7d7fc9e6988aace12c5a56
Positive f02b50ba6ac221e1ca423ca8d96e82d581314d81
Unknown command.

	The testkeys file included with this package looks like this:

key:52b08efcfed6a9911248ce7592f9b08d7949d840&action:lookup
key:d97b1764b257f4f67a7d7fc9e6988aace12c5a56&action:lookup
key:f02b50ba6ac221e1ca423ca8d96e82d581314d81&action:lookup
.

	The first is not a spam, the second and third are (the second
one is the key from the spam distributed with razor-agents).  To create
your own keys to add to this test file:
cat raw.message | razor-check -H | sed -e 's/^/key:/' -e 's/$/\&action:lookup/'

	If you're comfortable with its operation, you can instruct the
razor client programs (razor-check, etc.) to use it:

sudo chattr -i /home/wstearns/.razor.lst
mcedit /home/wstearns/.razor.lst
	#Add the line "127.0.0.1" (or the IP of your proxy) to the top
	#of the file.  Save and exit
sudo chattr +i /home/wstearns/.razor.lst

	Now do the same for .razor-report.lst :

sudo chattr -i /home/wstearns/.razor-report.lst
mcedit /home/wstearns/.razor-report.lst
	#Add the line "127.0.0.1" (or the IP of your proxy) to the top
	#of the file.  Save and exit
sudo chattr +i /home/wstearns/.razor-report.lst

	To see all options:
razor-caching-proxy.pl --help

	For some reason, I can't get the following approach to work:
touch ~/razor.cache.conf
mcedit ~/razor.cache.conf
#add
listfile = /home/wstearns/.razor.cache.lst
turn_off_discovery
rediscovery_wait = 86400000
debug

	#(86400000 seconds = 1000 days)
echo 127.0.0.1 >~/.razor.cache.lst

razor-check -conf=~/razor.cache.conf [other params]

	To instruct the cache to recheck all stale entries, try:


( cat /var/cache/razor/razor-cache | grep 'Positive' | sort | \
sed -e 's@^[^/]*/@@' -e 's@/[^/]*$@@' ; echo '.' ) | nc localhost 2702


	Sufficiently young answers will be answered from cache, too old
answers will be resent to the server for revalidation.  This should be
done at some time between 1 and 7 am to reduce load on the main servers.
	Unfortunately, the servers only answer 20 queries at a time, so
I need to think about this a little more.

	To run independantly, i.e. without any parent server to consult,
add
--server_name ''



Server Setup Quickstart:

As root, go to the directory to which you downloaded
razor-caching-proxy.pl and razor-cache (substitute a non-root username
for wstearns):

# cp -p razor-caching-proxy.pl /usr/bin
# mkdir /var/cache/razor
# cp -p razor-cache /var/cache/razor/razor-cache 
# chown -R wstearns.wstearns /var/cache/razor
# touch /var/log/razor
# chown wstearns.wstearns /var/log/razor
# chown -R wstearns.wstearns /var/cache/razor

Now switch to the non-root user that owns those files:
$ razor-caching-proxy.pl -v
or run the following as root:
su wstearns -c '/usr/bin/razor-caching-proxy.pl -v'

To start on every boot, as root edit /etc/rc.d/rc.local and add:
su wstearns -c '/usr/bin/razor-caching-proxy.pl -v'