INSTALLING SQUINT 

$Id: INSTALL,v 1.8 2005/07/28 11:38:36 andrewm Exp $

REQUIREMENTS

 . Squid proxy server
 . Perl (/usr/bin/perl)
 . Apache (to view documents), or a local web browser
 . Lotsa CPU time (it is very inefficient) (did I mention that it
   is inefficient?)
 . Bash (/bin/bash - for running from cron. /bin/sh doesn't work
   on some systems)

COMMAND LINE USAGE

 You can generate a once-off report by sending your access.log to
 squint.pl on standard input:

	cat /var/log/squid/access.log | ./squint.pl reportdir

 That will create a directory called 'reportdir' containing a
 browseable version of what users have done on your proxy server.


INSTALLATION

 # tar -zxvf squint.tgz
	I hope this part is easy enough

 # cp squint.pl squint.cron.sh /usr/local/bin
 	Install the binaries in a nice place

 # squint.cron.sh init
	This creates a place for the reports in
	/usr/local/httpd/htdocs (or whereever the htdocs
	directory is found).  It installs a crontab entry to run
	the report daily, weekly and monthly.  You may wish to
	edit the crontab entry first -- the system has not been
	optimised for security, and runs (unnecessarily) as the
	user root, rather than the user squid.

	Note that if you run squint.cron.sh at all, it is likely to make
	crontab entries for you (!)

 # squint.cron.sh all
	Create current daily, weekly and monthly reports -- don't
	do this twice! -- the reports get rotated every time you
	run the task, so things can get a little messy.

 # squint.cron.sh regen
	Recreate all the reports for your initial system, and
	also for when the program manges to mess things up.  You
	need to run this to maintain weekly and monthly reports
	if your server happens to miss a cron job.


CONFIGURATION OF SQUID

Usually you don't have to do any special configuration for squid for squint to
be able to create logs.  There are some special configurations that can cause
problems though.

  - squid log file format

  squint only understands the native squid log format.

	#  TAG: emulate_httpd_log       on|off
	#       The Cache can emulate the log file format which many 'httpd'
	#       programs use.  To disable/enable this emulation, set
	#       emulate_httpd_log to 'off' or 'on'.  The default
	#       is to use the native log format since it includes useful
	#       information that Squid-specific log analyzers use.
	#
	#Default:
	# emulate_httpd_log off

  If you have emulate_httpd_log on, squint will not produce reports for you.
  Sorry.

  - Upstream proxies

  squint RELIES	on the IP address provided in the squid log file.  If it's the
  IP address of the upstream proxy (e.g. dansguardian), then it is not correct.
  There is no fix for this at the moment, but squid can be configured to believe
  the "X-Forwarded-For" header provided by dans-guardian in certain versions.
  See http://devel.squid-cache.org/follow_xff/ -- with the patch, you can do
  this:

	acl localhost src 127.0.0.1
	follow_x_forwarded_for allow localhost
	log_uses_indirect_client on
	# you might want this too
	acl_uses_indirect_client on
	delay_pool_uses_indirect_client on


BUGS

This program generally expects to run as root, which is a little
unnecessary.


# ---------------------------------------------------------------------------
# Jan Henkins of Obsidian (obsidian.co.za) contributed these instructions,
# correspond to a slightly older version of squint.

Install Squint
==============

First things first:
-------------------

[ Update: REPORTS has been removed - important environment variables are now
BASEDIR (reports) and LOGDIR (squid logs) ]

After you have unpacked the squint-xxxxxxxx.tar.gz file, go into the
directory that was created. Before you install squint, check and edit
the squint.cron.sh file to reflect the correct paths to where you want
things to be put. Pay special attention to the REPORTS variable (line 3)
for a valid path to your HTML document root, and the "find" statement on 
line 45 to point to the correct directory where your squid stores it's
logs.

Installing the software:
------------------------

Simply run "make install", and make will put things in /usr/local/bin

Installing the crontab entry:
-----------------------------

Normally you can do this yourself, but the Makefile allows you to install
it automatically by running "make init". This will add an entry to the
bottom of the /etc/crontab file, as well as run the squint analyzer to
create you your first set of files in the HTML directory you have specified.
Your crontab entry should look something like this:

# squint squid reports
30 14 * * Fri  root /usr/local/bin/squint.cron.sh weekly
00 01 * 1 *    root /usr/local/bin/squint.cron.sh monthly
00 01 * * *    root /usr/local/bin/squint.cron.sh daily

Have fun!
