atjj1 (at) cs.waikato.ac.nz)
SRG is an HTML report generating tool for use with the Squid proxy's log files.
SRG was initially created for the CRCNet group to combat an overly time-intensive and confused report generator.
Very simple. Extract the archive to any directory. cd to this directory, and type
make
This will compile the SRG executable.
make install
Will install the executable. See the examples directory for some help with
configuration.
If you run debian there are also some very basic packages available that you
may find useful. These can be downloaded from the main SRG website.
SRG has many command-line configurable options. They can be viewed by running SRG with the -h switch.
More detail about individual options can be found here.
SRG can use a config file to store its options. By default this file is called "srg.conf" and is stored in the
directory SRG is installed to. If this file is missing, SRG will only take options passed through the command line.
Alternatively, a config file path can be specified with the -C command line option.
Examples of all config file options can be found in the examples/srg.conf file.
Very simple. Extract the archive to any directory. cd to this directory, and type
make
This will compile the SRG executable. If this fails... err... get a better compiler? :D
By default, SRG will set the following:
Input file: access.log
Output directory: srg_reports
CSS file: style.css
HTML title: SRG - Squid User Access Reports
All other options are disabled by default.
To use the authentication system in SRG, you must specify a PHP header file using the -p option (passing a filename to a PHP header), as well as the -A switch.
e.g. "./srg -p header.php -A"
In the PHP header file must exist two user-specified functions:
function can_view($group_name) (Which takes a the current groupname as an argument) and
function report_error($error_message) (Which displays an error message in whatever way you see fit).
Within these functions you are free to do whatever you want, to acheive the authentication you desire.
Due to the fact that the Title and CSS files are specified in the HTML header, which is overridden when using a PHP header, you will have to specify the CSS file and title in the PHP header file.
SRG has the ability to convert given IP ranges to user specified Group names. To do this, run SRG with the -E switch, and pass a filename of the file you wish to use.
e.g. "./srg -E ip2user.txt".
The structure of the file is as follows:
NetworkIPaddress Netmask Groupname
Comments can be added using a '#' at the start of the line.
NOTE: The behaviour of the -H switch changed with version 1.1 of SRG. The previous functionality it documented below. From version 1.1 of SRG onwards -H specifies whether IP addresses should be resolved to a hostname before being displayed in generated reports. By default IP addresses are not resolved as it could be quite a slow process.
-H behaviour prior to version 1.1: The -H
By
passing -HL, SRG will perform a DNS lookup on any hostnames which are IP
addresses (to try to get a more meaningful report).
-HN will ignore this, and simply show the IP address.
As of version 1.1 of SRG the -L switch has been deprecated and location reports are automatically generated.
-L behaviour prior to version 1.1: The -L switch tells SRG to show a report
for the URL location, rather than just a link to the site.
This location
report can hold very useful information, such as the times the site was
accessed.
SRG automatically creates directories in the format of YYYYMMDD-YYYMMDD. If, while creating the latest report, a directory is found to be older than the value specified by -m (in days), that directory is deleted, and will no longer show up in reports. So, if you use this option and require archival, make sure to do it before the folders expire.
Squid needs to output the log files using two options:
1) Native log
file format. The 'emulate_httpd_log' option breaks this.
2) No spaces in URLs. This is the default configuration for uri_whitespace.
So, as long as you don't specify either of these options, everything should be
fine. If, however, stray whitespace does enter the URL, SRG has no way of
parsing this, and so drops the log line.
In SRG 1.1 several command line options were deprecated with the intention
of simplifying how SRG is executed. Each option can still be controlled via
an appropriate directive in the configuration file. The table below details
the old option, it's equivalent configuration directive and a short
descroption. Although you receive a warning when using these command line
options they are still in effect. However you should stop using them as they
may be completely removed in a future version.
| Option | Config File Directive | Description |
|---|---|---|
| -A | php_authentication | Enable PHP authentication support |
| -c | cssfile | CSS File - if none specified a default css is generated |
| -D | dontshow_onlydeniedusers | Suppress groups with only denied hits from the output |
| -e | nonameexists_showip | Display the IP address as the username if there is no username specified in the logfile |
| -L | *Removed* This used to specify that location reports should be generated - this functionality has been made the default in SRG 1.1 | |
| -p | phpheader | PHP header file to include in output |
| -P | phpfooter | PHP footer file to include in output |
| -T | title | Title for generated report pages |
As of SRG 1.1 you can use the -r command line option or the sort_columns configuration file directive. This enables the inclusion of a javascript file in every report generated. This javascript allows you to sort by any column in the output by clicking on the column heading, multiple clicks will toggle the order of the sort.