Alan Jackson (atjj1 (at)

v.00, 12 February 2003

This is the SRG FAQ file. Copyright © 2003-, Alan Jackson, Matthew Brown.

1. General information

2. Getting and installing SRG

4. SRG Configuration

4. General usage, features and bugs


1. General information

1.1 What is SRG?

SRG is an HTML report generating tool for use with the Squid proxy's log files.

1.2 What is its history?

SRG was initially created for the CRCNet group to combat an overly time-intensive and confused report generator.

1.3 What are SRG's main features?


2. Getting and installing SRG

2.1 Where do I get SRG? should have all the details you require to get statred.

2.2 What is the latest version of SRG?

You are reading the FAQ for srg v1.1. Check the website above to ensure that you have the latest version.

2.3 How do I install SRG?

Very simple. Extract the archive to any directory. cd to this directory, and type
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.


3. SRG Configuration

3.1 SRG Command line options

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.

3.2 Using a config file with SRG

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.

3.3 How do I install SRG?

Very simple. Extract the archive to any directory. cd to this directory, and type
This will compile the SRG executable. If this fails... err... get a better compiler? :D


4. General usage, features and bugs

4.1 What are SRG's default settings?

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.

4.2 How do I use PHP header file authentication?

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.

4.3 How can I use both PHP Header files and CSS/Title?

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.

4.4 How do I use an IP2Username 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.

4.5 What do these options for the -H switch do?

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 switch forces SRG to show the hostname that requested an URL in the corresponding Location report.
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.

4.6 What is the -L switch for?

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.

4.7 How does the -m option function?

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.

4.8 What settings should I use for Squid?

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.

4.9 Why do I get an error about a deprecated command line option

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

4.10 How can I sort the reports by any column?

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.