Keith's Software and Tutorials Home Page
Knowledge Is Power

Bestdam Website Visitor Logger
+ Hit Counter

Setup  &  Installation





Sections:





Home

How Do I CGI ?

BDL Features

BDL Download

BDL Setup

Quick Setup

BDL Windows

BDL Help

BDL How To

BDL Log Tips

Hit History

BDL Duo

BDL Upgrade

Note:  The setup and installation information is also presented in the README.TXT file contained in the ZIP (DOS/Windows) and TAR (UNIX/Linux) download files.

For those experienced with CGI scripts, the top of the .PL file is well commented with everything you need to quickly set up the script and there is also a Quick Setup page.


Before Setting Up Bestdam Logger

Before proceeding with the setup, you may want to verify your ability to use the script by asking your host or ISP the following two questions:
1. Can I run CGI scripts from my Web pages ?

2. Does my CGI script support include SSI (Server Side Includes) ?

If the answer to both of these questions is "Yes", you're good to go.



Setup & Installation


Note:  You may get an empty e-mailed report shortly after installing the script. This is due to the "trigger" file resetting to the current day.

If you are new to using Perl scripts, you may want to check out the How To Use Free Perl Scripts section of the CGI page for a lot of good tips on setting up CGI scripts in general.


  1. Use a text editor to open the BDLOGGER.PL file


  2. The very first line of the file is the path to your host's installation of Perl. Verify that this path is correct or change it if necessary. If you are not sure of the location of your host's Perl installation ask them to provide you with the path to it. Another common location is:

    #!/usr/bin/perl



  3. Around line 65 of the BDLOGGER.PL file is where the list of user-option variables begins. This list has the heading:
    "YOU MUST SET THE FIRST 2 VARIABLES !"

    As the heading indicates, the first two variables, which are $sendto and $mailprgm must have the correct values entered for them. The remaining variables are for user customization but the program will work fine with the default values. The two variables that need to be set are:

    $sendto Enter, between the quote marks, the e-mail address of the person who is to receive the e-mailed reports. Be careful not to over-write the quote marks. The e-mail address must be enclosed in these quote marks (as given in the example near the variable list heading). If you want to send the report to multiple recipients, just put multiple e-mail addresses between the quote marks, separated by a comma (,). Example:

    $sendto = 'his@theirs.com,hers@theirs.com'


    $mailprgm This is the path to your host's server-based e-mail program. Verify that this path is correct or change it if necessary. If you are not sure of the location of your host's e-mail installation, ask them to provide you with the name and path to it. Another common location is   '/bin/sendmail'.   As with the $sendto variable, this variable must be enclosed in the quote marks.

    NT Users
    There is a version of Sendmail for NT but it carries a price. For this reason many ISPs/hosts with NT servers will use the freeware Blat mail program. If your ISP/host uses this program, enter BLAT (in upper case) for the $mail_prgm variable. Then enter the path to your Blat installation in the $blat_path variable. The default value for this variable is the default installation path for Blat.

    $blatpath = 'c:\\Winnt\\System32\\blat.exe';

    Note that both of the back-slash characters are needed between directories when specifying this path. The Blat software, and information about it, are available at

    www.blat.net


    For a detailed discussion of all of the optional variables, including IP tracking, IP blocking, and the Web-page versions of the hit count file and period report, please see the Optional Variables Reference below.



  4. Add the following SSI directive tag to each Web page that you want to "monitor", i.e. log and count hits.

    <!--#exec cgi="/cgi-bin/bdlogger/bdlogger.pl" -->

    If your CGI-BIN directory is called something other than CGI-BIN, modify the directory name in the tag accordingly.

    Notes On Tag Placement

    It is best to put the tag near the bottom of the page, but be sure to put it BEFORE the </body> tag. Putting it near the bottom of the page will help ensure that the first part of your page is not delayed in loading. The first person of a new "period" to view one of your monitored pages may notice a delay in the complete loading of the first monitored page as the "period process" executes. However, any server with reasonable power should process the script very quickly. In addition, the first hit of a new period is likely to be early in the morning when server loads are low.

    If you have the $display_count variable (see below) set to "Yes" (1), the placement of the tag will dictate where the counter appears on your page. The counter location will also be influenced by any formatting tags, such as <center>, <font>, <b>, etc.


  5. At this point you are ready to transfer the script and page files to your Web server and CHMOD the files accordingly. If you are unsure how to do this, step-by-step instructions, including screen-shots using the WS_FTP program, are available on this site's "How To..." page.


Once you start testing the script, you can look at the contents of the various data files, such as pagehits.cnt and period.log, using an FTP program. You can ftp the data files to your local hard-drive and look at them using a text editor, or if you're using WS_FTP you can just click once on the file name and click on the "View" button on the side of the remote file list. (Be sure you have ASCII mode selected before clicking on the View button.)

If the script doesn't appear to be working, there are any number of configuration-related things that could be the problem. Visit the Help page for information on things you'll want to check.




Top of page



Using Graphics Counter Digits


The ability to use graphics counter digits only applies to the Deluxe edition of Bestdam Logger.



  1. make a new sub-directory (folder) under your root Web directory and name it digits




  2. Double-click on the new digits folder to open it and   USE BINARY MODE !!!   to transfer the digit graphics files of your choice into your new digits sub-directory




  3. You do not need to CHMOD these files as they only need to have the Read permission and that is assigned by default.


IMPORTANT NOTES:

The graphics files must have the single character name for the number they represent. For example, if they are .gif files, they must be named:

1.gif 2.gif 3.gif etc. Use the "Rename" function of your FTP program to rename them if necessary.

Do NOT create the digits sub-directory under the cgi-bin sub-directory or people may not be able to access the digit files.

Make sure that you enter a 1 for the count_hits, display_count, and graphics_count option variables near the top of the script. More information on these variables is given in the Optional Variables Reference below.

The Resources page has a link to a site with loads of digit graphics you can download.


Top of page



Optional Variables Reference


The following variables can be set optionally. They are used to customize the performance to your preferences.


$count_hits Count page hits ?
Values are     1 = Yes     0 = No
1 is the default value.

$display_count Display the counter on the page ?
Values are     1 = Yes     0 = No
1 is the default value.
You must have $count_hits = 1

$reset_counts
Deluxe Edition
You have the option of resetting the hit counters to zero after the report is e-mailed.
Values are     1 = Yes     0 = No
0 is the default value.
You must have $count_hits = 1

$reporting_period The period between the updating of the logs and the mailing of the report.
Values are:
  • 0 = Not-at-all
  • 1 = Daily
  • 2 = Weekly
  • 3 = Monthly
NOTE: With this value set to '0' (not at all) Bestdam Logger will perform like your run-of-the-mill logger/counter.

"Updating of the logs" means the "period log" is cleared and if the $keep_history variable (see below) is set to "Yes", the contents of the period log are appended to the history log before the period log is cleared.
1 is the default value.
1 ("Daily") is the only valid value for this setting with the Lite Edition.

CAUTION: Choosing 3 (Monthly) could result in very big period log files by the last week of the month which could slow the execution of the script. It should only be used if you get less than several hundred hits a week or have a very fast server.

$day_of_week
Deluxe Edition
If you chose "Weekly" (2) for the above variable, this variable sets which day of the week the logs will be updated and the report will be e-mailed.
Values are:
  • 0 = Sunday
  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday
The logs are updated and report e-mailed when one of your pages being monitored receives the first hit of the day you specify (probably very early a.m.).
0 is the default value.

$mail_report E-mail the "period" log report & stats ?
Values are     1 = Yes     0 = No
1 is the default value.

$log_in_mail
Deluxe Edition
Include the contents of the period log in e-mailed reports ?
Values are     1 = Yes     0 = No
1 is the default value.

$double_space
Deluxe Edition
The log lines can be very long. The log data that is e-mailed is best viewed with the "wrap" feature turned off in your e-mail program. If you can't turn off "wrap", or just don't want to, this option will double-space the log lines in the e-mailed report.
Values are     1 = Yes     0 = No
You must have $mail_report = 1
0 is the default value.

$keep_history
Deluxe Edition
Keep a cumulative "history log" ?
Values are     1 = Yes     0 = No
1 is the default value.

$hit_count_history
Deluxe Edition
Keep a history of hit counts for a recurring period to tab-delimited text file for viewing and optional import into into a spreadsheet program for analysis and graphing ?
Values are:
  • 0 = Not-at-all
  • 1 = Daily
  • 2 = Weekly
  • 3 = Monthly
NOTE: If set to 1, 2, or 3, the $count_hits variable (No. 3) MUST be set to 'Yes' (1).

Due the varying number of days in months, montly logging for the previous month will be done when the first hit of the new month is received (probably very early a.m. on the 1st).

$hit_count_history_dow
Deluxe Edition
If you chose "Weekly" (2) for the above variable, this variable sets which day of the week the current count will be recorded to the "hit history" file.
Values are:
  • 0 = Sunday
  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday
The current count is written to the "hit history" file when one of your pages being monitored receives the first hit of the day you specify (probably very early a.m.).
0 is the default value.

$hit_count_history_page
Deluxe Edition
Enter the name of the page you want to you want to keep a history on (ONE PAGE ONLY). In most cases you want to keep this history for your entire site in general so enter the name of the home page.
(Ex: index.html, default.asp, etc.)

$hit_count_history_in_mail
Deluxe Edition
Include the contents of the hit history file in the e-mailed reports ?
Values are     1 = Yes     0 = No
0 is the default value.
You must have $hit_count_history set to 1.

$check_ip
Deluxe Edition
Check IP address so multiple hits from the same address aren't counted ?
Values are     1=Yes     0=No
1 is the default value
DON'T set to '1' if you are monitoring multiple pages

The default level of "back tracking" is 5 addresses. To lower this, open the 'iptrack.num' file in a text editor and delete the appropriate number # of '0.0.0.0' IP addresses. To increase it, add the appropriate number of '0.0.0.0' IP addresses with each being on their own line.

$graphics_count
Deluxe Edition
Use graphics digits for counter ?
Values are     1 = Yes     0 = No
0 is the default value.
You must have $display_count = 1

NOTE:   If you set $graphics_count = 1 you MUST verify/set the two additional variables below and follow the "Special Notes" below.

The following two variables have example values which are the default values.

$digits_path = '/digits/'; Specify the path to the digits files relative to the root URL.
This value MUST begin AND end with a slash (/).

Example:   Your root URL could be something like:
http://www.yourdomain.com
or
http://www.isp.com/~mydomain

$digits_type = '.gif'; File extension of digit graphics files. The period MUST be included.



SPECIAL NOTE:

With the above 2 values set correctly you should be able to view the digits on your browser. Using the above default values as an example, you'd be able to see the '1' digit by going to

www.yourdomain.com/digits/1.gif
If you can't see the digits this way, no one will be able to see them on your Web page.


$web_count
Deluxe Edition
Create the hits.htm Web page to view current hit counts using a browser ?
Values are     1 = Yes     0 = No
0 is the default value.
You must have $count_hits = 1
View the page at http://www.mydomain.com/hits.htm

NOTE:   If you set this value to '1' you MUST enter the value for the next variable.

$count_path
Deluxe Edition
If you entered '1' to create a hits.htm page you MUST enter the SYSTEM path to your Web root for the hits.htm file (typically where your home page is located).

The value here is just an example of what's needed. Be sure to leave the '/ at the beginning and the /hits.htm'; on the end.
If you wish, you can use a name other than 'hits' for the page.

$page_path = '/usr/local/etc/httpd/usersites/mysite/hits.htm';

$web_report
Deluxe Edition
Create a Web-page version of the period report (which also contains the hit count data) to view using a browser ? (preport.htm)
Values are     1 = Yes     0 = No
0 is the default value.
View the page at http://www.mydomain.com/preport.htm

NOTE:   If you set this value to '1' you MUST enter the value for the next variable.

$report_path
Deluxe Edition
If you entered '1' to create a preport.htm page you MUST enter the SYSTEM path to your Web root for the preport.htm file (typically where your home page is located).

The value here is just an example of what's needed. Be sure to leave the '/ at the beginning and the /preport.htm'; on the end.
If you wish, you can use a name other than 'preport' for the page.

$report_path = '/usr/local/etc/httpd/usersites/mysite/preports.htm';
$web_history
Deluxe Edition
Create the hithistory.htm Web page to view the hit history table using a browser ?
Values are     1 = Yes     0 = No
0 is the default value.
You must have $hit_count_history = 1
View the page at http://www.mydomain.com/hithistory.htm

NOTE:   If you set this value to '1' you MUST enter the value for the next variable.

$web_history_path
Deluxe Edition
If you entered '1' to create a hithistory.htm page you MUST enter the SYSTEM path to your Web root for the hithistory.htm file (typically where your home page is located).

The value here is just an example of what's needed. Be sure to leave the '/ at the beginning and the /hithistory.htm'; on the end.
If you wish, you can use a name other than 'hithistory' for the page.

$page_path = '/usr/local/etc/httpd/usersites/mysite/hithistory.htm';



Using IP Blocking - Deluxe edition

If you want to use IP blocking, you must create a text file with the name ipblock (no extension) and transfer it with the other files and CHMOD it 666 also.

In the file, enter one IP address (or partial IP address for entire sub-net blocking) per line to be blocked from the counting and logging. You can enter as many IP addresses or partial addresses as you like.

Examples:
Entering   123.45.678.9   will block this one IP address
Entering   123.45   will block all IP addresses that start with '123.45'.

Sample file:
123.45.678.9
123.45.678.20
174.22
90.
218.43.21



Top of page




Powered by Apache On Debian Linux


Contents, diagrams, and images    Copyright © 2004-2017    Keith Parkansky    All rights reserved.
"Bestdam Logger" and the BDL graphic logo are trademarks of Keith Parkansky.
Certain graphics, symbols, and terms used on this site and in its documents are registered trademarks
of their respective owners and are contained herein for identification purposes only.
No endorsement of this site, its contents, or its documents by these owners is expressed or implied.

LIABILITY
IN NO EVENT WILL KEITH PARKANSKY BE LIABLE TO ANY PARTY (i) FOR ANY DIRECT, INDIRECT, SPECIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR INFORMATION, AND THE LIKE), OR ANY OTHER DAMAGES ARISING IN ANY WAY OUT OF THE AVAILABILITY, USE, RELIANCE ON, OR INABILITY TO USE THE INFORMATION, METHODS, HTML OR COMPUTER CODE, OR "KNOWLEDGE" PROVIDED ON OR THROUGH THIS WEBSITE OR ANY OF ITS' ASSOCIATED DOCUMENTS, DIAGRAMS, IMAGES, REPRODUCTIONS, COMPUTER EXECUTED CODE, OR ELECTRONICALLY STORED OR TRANSMITTED FILES OR GENERATED COMMUNICATIONS OR DATA EVEN IF KEITH PARKANSKY SHALL HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, AND REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT, TORT, OR OTHERWISE; OR (ii) FOR ANY CLAIM ATTRIBUTABLE TO ERRORS, OMISSIONS, OR OTHER INACCURACIES IN, OR DESTRUCTIVE PROPERTIES OF ANY INFORMATION, METHODS, HTML OR COMPUTER CODE, OR "KNOWLEDGE" PROVIDED ON OR THROUGH THIS WEBSITE OR ANY OF ITS' ASSOCIATED DOCUMENTS, DIAGRAMS, IMAGES, REPRODUCTIONS, COMPUTER EXECUTED CODE, OR ELECTRONICALLY STORED, TRANSMITTED, OR GENERATED FILES, COMMUNICATIONS, OR DATA. USE OF THIS SITE CONSTITUTES ACCEPTANCE OF ALL STATED TERMS AND CONDITIONS.