SiteTrack Project
An Interestingly Average Open Source Project
ErrorTrack Documentation
Currently, with the present Beta release, only documentation for webmasters is available. More specific documentation will be released for server administrators at a later date. This page contains an HTML version of the documentation which is only available on this web site. The documentation included with the program is a text document.
Table of Contents
System Requirements
The server that this software is being installed on must have Perl, and you must have permission to install Perl scripts on the server. If you are installing the program on a server that is hosting your web site, you must have the ability to create and edit .htaccess files on the server. If you are installing the program on a server that you own or manage, your server must support the use of .htaccess files, or have an internal configuration option for managing errors. In addition, you must have the ability to send e-mail using sendmail. Support for other mail handling programs may be added in the future.
Configuring the Program
The server settings area requires information that most likely was provided to you by the host when you obtained your hosting account. The first thing that needs to be changed is the first line of the program, which is #! followed by the location of Perl on the server. Unless the script is being hosted on a Windows server, this line is required.
Next, below the comments section, are the paths to files and programs on the server. The first value is the location of sendmail. The application will use sendmail to send information about critical errors to an address that will be specified later. The next value is the location of the system time command. The program will use this to get the current time and write the time into the log, and to the e-mail if needed.
The next section is the site specific settings. First, enter the relative location of the directory you want the log file kept in. The log file should not be kept in the same folder as the program, and should be kept somewhere where it can not be served by the server. After the location of the log folder, enter your e-mail address. Make sure the @ is preceded by a backslash (name\@server.com, not name@server.com) to prevent errors when the program executes.
One of the most important features of this program is the ability to change what the program does to react to different types of errors. For example, you may want to log different information for an internal server error than for a page not found error. The error definitions allow you to specify exactly what is done when a certain type of error is encountered.
This is the basic format for an error definition:
if ($error_code eq "500") { or } elsif ($error_code eq "500") {
$error_file = "../errors/500.txt";
$log_color = "red";
$user_ip = $ENV{'REMOTE_ADDR'};
$calling_page = $ENV{'HTTP_REFERRER'};
$browser = $ENV{'USER_AGENT'};
$browser_detail = "0";
&logerror;
&emailadmin;
&show_results_page;
}
The first line contains $error_code eq "XXX", where XXX is the HTTP error code. To define a new error, copy an existing definition and change the three digit error code.
The error file variable is the location of the file containing the web page to be shown to the visitor to tell the visitor about the error. Instructions on setting up these files can be found in the next section, called Error Pages.
The log created is an HTML document. To tell different errors apart, it is often helpful to give each type of error a different color. Some users prefer to assign colors based on severity. Whatever value is entered for log color is the color of the text for the error entry in the log. The color can be the name of a color or the hex code for the color, preceeded by a pound sign.
The user ip value tells the program what environment value to get the ip address from. If you don't want the user's IP address logged, comment this line out by putting a # at the beginning of the line.
The calling page value is a reference to the page the user was at before the error occured. If you don't want to log this, place a # at the beginning of the line. This information can help you know, for example, what page has a bad link.
The browser value contains information about the user's browser. For most errors this information doesn't matter and this line can be commented out by placing a # at the beginning of the line.
The browser detail is for a feature that will be added in a future version of the software and can currently be commented out by placing a # at the beginning of the line.
The &logerror; line causes the program to log the error in the log file. If you do not want the error to be logged, simply comment the line out by placing a # at the beginning of the line.
The &emailadmin; line causes the program to send an e-mail about the error to the e-mail address specified in the site specific settings section. If you do not want an e-mail sent about this error, comment it out by placing a # at the beginning of the line.
The &show_results_page; causes the program to output the error message specified in the error file value to be output to the visitor. This is required and must not be commented out.
Error documents are external files that contain instructions for the web page to output to the visitor to give the visitor information about the problem. This program will import the file and treat it as a Perl subroutine. For this reason, there is a specific way the file must be set up. The first step is to design a complete web page that you want to be shown when an error occurs. Save the file with a .lib extension and add to the top of the file (before the tag) the following:
sub error_page {
print << "HTML Code";
After the print line, put the full code for the web page. At the very end of the page, after the </html> at the end of the page, put the following code:
HTML Code } 1;
The 1; must be alone on the very last line of the file.
Future versions of the software will add the ability to customize the page with specific information about the error. When that functionality is added, we will add the specifics to the features page on our web site.
Once the program has been set up for your server, it is ready to be installed. Connect to your server using FTP and go to the folder where you install Perl scripts. Upload the errortrack.cgi file and CHMOD it to 755. Then, create a sub-folder called errorlog and CHMOD the folder to 777. Note that if you specified a different folder name or location in the program, that is where you need to put the folder.
Configuring the Server
Currently, instructions for triggering this program using .htaccess files are not available. The instructions for setting up the .htaccess files to handle errors can be found in the documentation for the server software that you are using. The document you would set up is the location of the errortrack.cgi file followed by ?XXX where XXX is the error code. For example the line for an error 404 may be:
ErrorDocument 401 /cgi-bin/errortrack.cgi?401 ErrorDocument 404 /cgi-bin/errortrack.cgi?404 ErrorDocument 500 /cgi-bin/errortrack.cgi?500
but again this depends on how .htaccess files are formatted for your server.