Documentation: Chapter 2
Installation for Windows (general)
If you are running Microsoft IIS or PWS, Netscape FastTrack or Enterprise, or O'Reilly WebSite, you should use their installation instructions instead.
Otherwise, follow these instructions in order to install FlashStats on a Windows 95/NT system with any other type of web server.
Step 1: Run Setup
Download the original setup program from the Maximized Software download site. After it has finished downloading, run setup by double-clicking on the file that you downloaded (FS_15.EXE).
Setup will provide reasonable guesses about where you have installed your web server, but be sure to correct any directory names as necessary. In particular, when Setup asks for the name of your web server's CGI directory, be sure to specify a valid CGI directory, not a WinCGI or DOSCGI directory.
Setup will also configure a sample "user account" in the FlashStats.ini configuration file, but you will still need to edit the file (see step 3 below).
Be sure to read the Read Me file for any last-minute information.
You have successfully installed the FlashStats files. The next step will help you to edit the FlashStats.ini file to properly configure FlashStats for your system.
Step 2: Set File Permissions
This step only applies if you are running FlashStats on a Windows NT system with the NTFS file system!
If you are running FlashStats on a Windows NT system, then you need to set certain file permissions. If you do not grant these permissions, then FlashStats will not be able to read or write necessary files and may generate empty reports. If you are not running FlashStats on a Windows NT system, or if you are running on NT but are not using the NTFS file system, then you can ignore this entire step and jump down to Step 3.
You need to determine which Windows NT user account is used by the web server when it runs. Check the your web server's configuration options to find out how the server is configured. If the web server runs as a desktop application, then the user account will usually be that of the user who is logged into the computer when the web server is launched, such as Administrator. If the web server runs as a server, then the user account will usually be System unless manually set to something else with the Services Control Panel.
You use the Directory Permissions dialog box to set directory permissions, and use the File Permissions dialog box to set file permissions.
Let's first set the directory permissions for the log files directory. Open the properties for the log file folder; click on the Security tab of the Properties dialog box, then click on the Permissions button.
Now, look at the permissions for the log file directory. Does the web server user account already have Change (or Full Control) permissions? Alternately, does the Everyone account have Change (or Full Control) permissions? If neither does, then you need to add Change permissions for the web server user account.
To do this, click on the Add... button. The Add Users and Groups dialog box will pop up. Click on the Show Users button. Select the web server user account from the top list box, and click on the Add button to add it to the lower list box. In the Type of Access drop-down list, choose Change. Then click the OK button to return to the Directory Permissions dialog box.
You will see that the web server user account has been added to the list of directory permissions, with Change rights. Make sure that the Replace Permissions on Existing Files checkbox is checked on (enabled). Finally, hit OK to apply the new values to all existing files and to the directory itself.
Now follow similar procedures to set the directory permissions for all of these directories (you just set the permissions for the second directory listed):
|FlashStats program directory
Example: C:\Program Files\Maximized Software\FlashStats
|(Archived) logs directory *
Example: C:\Program Files\WebServer\logs
|FlashStats HTML directory
Example: C:\Program Files\WebServer\docs\FlashStats
* Note: FlashStats needs Change directory permissions in order to be able to create and delete some special files in the archived logs directory. Note that if your current log file is in a different directory than your archived log files, then FlashStats only needs Change permissions to the directory containing the archived log files. Of course, as for file permissions, FlashStats needs to be able to read all log files.
After assigning directory permissions, use the File Permissions dialog box to set these file permissions:
Of course, you can grant a higher level of priveleges than described here; these values are just minimums. In addition, it doesn't matter if you grant these rights to the web server user account directly, or to a group that the user belongs to (such as Everyone).
Step 3: Configure a User Account
You need to edit the FlashStats.ini file to configure FlashStats for your system. To do this, first open the FlashStats.ini file in your cgi directory. Any standard text editor will work fine.
Take a minute to familiarize yourself with the format of the FlashStats.ini file. You will notice that any line beginning with a # character or a semicolon is treated as a comment, and is ignored by FlashStats. Feel free to add your own comments if you want to.
Notice that all of the information in the FlashStats.ini file is specified with a key=value format. In most cases, you will not have to change the key, but may need to replace any existing value.
There are two main types of lines in FlashStats.ini. The first type is a "single-value" line, where exactly one key=value pair is specified. Examples of this type of line are the lines that begin with Key= and Password=. The other type of line is the "user account" line, which begins with user=. These user account lines are how you tell FlashStats which users can run reports, and which log files they can access. 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.ini 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.ini 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:
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:
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:
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=C:\Program Files\WebServer\logs\today.log;logs=C:\Program Files\WebServer\logs\old\*.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 4: 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.
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 firstname.lastname@example.org so that we can take a look at them and let you know if FlashStats should support them.
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 your server for the log format changes to take effect.
Step 5: Edit the Report Request Form
In the final step (step 6) you will use your web browser to display an HTML page (index.htm). This page contains a form which you use to specify the options for the FlashStats reports that you want to generate. However, you first need to edit the index.htm file so that it matches your system configuration.
Open the index.htm file which was installed into your web server's CGI directory. Look for all occurances of comments with the word "CHANGE:". These lines indicate values and parameters that you may need to change in order for FlashStats to work correctly on your system.
When you are done editing the index.htm, save your changes and close the file. Then make the same changes to the Advanced Report Request Form (advanced.htm).
You're now ready to run your first FlashStats report!
Step 6: Run A Report
Fire up your web browser, and connect to the machine on which you installed FlashStats. Request this document (changing the host name as appropriate):
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.
If you encountered any problems, you may want to jump to the support area of our web site.
Version 1.5 -- Last update: 2/8/01