Documentation: Chapter 2
Installation for Unix
This chapter provides instructions for installing FlashStats for use with an Apache or Netscape web server on the following platforms:
- BSDI
- Digital UNIX (Alpha)
- FreeBSD
- Linux (Alpha)
- Linux (Intel)
- SCO
- Solaris (SPARC)
Step 1: Install the Files
Download the original distribution .gz file from the Maximized Software download site. Uncompress and untar the FlashStats distribution file by using the gunzip and tar xf commands. These commands will extract the files from the archive and create the flashstats directory hierarchy. You can then delete the archive files (.gz and .tar) if you wish.
Now, run the setup script fs-install. This script requires the Bourne shell. The script will ask you many questions, and when it has all of the necessary information it will install and configure FlashStats.
After running setup, you can jump down to Step 3. If you have any problems or need to do a manual installation, then continue with this step and then also follow Step 2.
When doing a manual installation, you first need to install two files into your web server's cgi directory. From the flashstats/cgi/ directory, copy the files " flashstats.cgi" and "flashstats.conf" into the CGI directory of your site. Make sure the binary can be executed and the flashstats.conf file can be read by the HTTPD user (or whatever name your web server uses). If the user running HTTPD has a shell pointed to "/dev/null", you may need to "setuid" the binary. Please refer to your UNIX manual for information on how to "setuid".
Next, you will install the HTML files used by FlashStats. Create a directory in your web server's document root for the html file used to access FlashStats. We suggest a directory named flashstats. From the flashstats/htmldocs/ distribution directory, copy the files index.html, advanced.html, blue2x5.gif, red2x5.gif, and fs15-reg.gif to this new directory that you created under your document root. This index.html file will be used to run FlashStats from your browser. If you create the directory flashstats in your web server's document root then you will access FlashStats with a URL like:
http://yourserver.com/flashstats/
You have successfully installed the FlashStats files. The next step will help you to edit the FlashStats.conf file to properly configure FlashStats for your system.
Step 2: Configure a User Account
FlashStats uses the concept of a "user account" to control who has the abililty to run reports. These user accounts are private to FlashStats, and do not relate to any other type of user account that your web server or operating system may maintain, such as user name or account name (under Mac, Windows NT, or UNIX). You edit the flashstats.conf to create accounts for each user that you would like to be able to run FlashStats.
Of course, several end users can share the same FlashStats user account. And if you'd like to do away with user accounts entirely, you can just set up one account named something simple like "public" and no password and then always use that account. We'll get to those details later. For now, let's go ahead and create a basic user account so that you can begin using FlashStats.
We're going to create a user account named "sample". The flashstats.conf file that you installed to your cgi directory in Step 1 already contains a "sample" user account with some "dummy" values; let's modify those dummy values to reflect your system's configuration.
Locate the line that begins with user=sample. This is a user account line. Note that all parameters for this user account must be placed entirely on one line, with each key=value separated by a semicolon; do not press Return to wrap the text to a new line. If the text breaks onto a new line, then FlashStats will not see any text on lines other than the first line, and therefore the user account will not be configured properly. Of course, if your text editor wraps lines "logically" so that they fit on the screen, without actually breaking the lines by inserting a carriage return, then that's okay.
Notice that parameters on the user account line are separated by a semicolon. Find the password= parameter for the "sample" user account. The value of the password is preset to no string so that this user account does not require a password. This is fine for our purposes right now, so you don't need to change that parameter.
Now look at the third parameter: url=. Change the value after the equal sign to be the base URL for the web site that you'll be generating statistics for. For example, if your web site's home page is http://www.mydomain.com, then use that as the value of the url= parameter. Or, if your home page is http://www.myisp.com/mycompany, then use that. Here are some examples of what the url= parameter might look like:
url=http://www.mydomain.com
url=http://www.myisp.com/mycompany
url=http://www.myschool.edu/~username
Note that you don't need to end the value with a slash, and that you don't need to specify the filename of your home page, just its URL base location.
Next, give your report a title. This simple title will print at the top of the summary report generated by FlashStats. Keep the parameter relatively short, something like: title=My Domain Analysis.
Next, you need to specify the location of the log files generated by your web server. Edit the accesslog= parameter so that it specifies the full path to the "current" log file generated by your web server. For example, you may enter a value like this:
accesslog=/usr/www/logs/access_log
Finally, you need to indicate the full path and wildcard pattern to match all of the old log files generated by your server. (Most web servers can automatically rotate, or "archive," their log files every day, week, or month.) Simply make sure that there's a parameter on the user account line that reads something like:
logs=/usr/www/logs/*.log
That's it! You should now have a user account line for an account named "sample" that looks something like this (all on one line):
user=sample;password=;url=http://www.mydomain.com;title=My Domain Analysis;accesslog=/usr/www/logs/access_log;logs=/usr/www/logs/*.log
Save and close the configuration file.
Now you need to make one change to your web server logging configuration, and then you'll be ready to run your first FlashStats report.
Step 3: Configure Logging Options
The final step is to make sure that your web server is generating log files in a format that can be read by FlashStats. Fortunately, FlashStats can recognize all major log file formats. Your web server will mostly likely be generating the Common Log Format. This will work fine with FlashStats.
An even better format is the "Extended Log Format" (or sometimes called the "Combined Log Format"). This format consists of the standard Common Log Format fields, followed by the REFERER field, followed by the USER_AGENT field. Each of these two fields is enclosed in double-quotes, and are separated with a space. If you can configure your web server to support this log format, FlashStats will be able to generate all of its supported reports.
So at this stage, you should stop to reconfigure your web server if necessary so that it outputs the best possible log files in the future. (This won't affect any existing log files, but it will improve any future log files.) You may need to restart (or hup) your server for the log format changes to take effect.
If you're unsure of the log format generated by your web server, just go ahead and try to use FlashStats. FlashStats will auto-detect all of the major known log formats, so the chances are that it'll just work! If you have problems, you may want to send the first few lines of your log file to support@maximized.com so that we can take a look at them and let you know if FlashStats should support them.
You will see the FlashStats report form. Later you may want to change some of the fields on this form, but for now just accept the defaults. Hit the Generate Report button, then wait for FlashStats to generate the report.
That's it! You've successfully run your first FlashStats report. If you'd like to customize your FlashStats installation, you should continue on to Chapter 3.
You can configure your Netscape web server to generate Extended Log Format log files by using the web server's Administrator utility. Choose the Server Status button, then choose Log Preferences from the left-hand frame. Choose Only log: and make sure that at least the following checkboxes are checked: