GoStats version 1

Written by:
  Byte Of Software Systems Inc.
  #75 - 20465 Douglas Crescent
  Langley, British Columbia
  V3A 4B6

  http://www.bossi.com
  gostats@bossi.com

All rights reserved.

You may copy and distribute this version of Gostats to your hearts content,
as long as the original files are included, along with this document.

Suggestions for changes to GoStats are welcome. Be aware that not all ideas
will be implemented.

GoStats is shareware, not crippleware. If you feel that it is useful, please
send a nice amount to the above address. All donations are accepted :-))
If you want a reply (and possibly an upgrade version), include your eMail
address.


Purpose:
~~~~~~~~
  GoStats was written to allow GoServe Web Server administrators and users to
see their usage statistics.

  GoStats reads through the GoServe audit file (normally GOAUDIT.80) and
creates an HTML page which contains the usage stats. By reading modifying the
GOFILTER.80 file that GoServer uses, it is possible to allow users to extract
their own statistics online, based on the IP address that they are using.

Note that this is the most usefull on INTRANET systems, where users tend to
have the same IP address all the time, either by using static IP, or DHCP.

GoStats tries very hard to be YEAR2000 compliant :-))


Installation
~~~~~~~~~~~~
You have. When you de-compressed the ZIP file you completed the installation.
If you want GoStats in a different location, simply move it there. Note that
the GOSTATS.INI file MUST be in the same directory as GoStats.EXE.


Files Included
~~~~~~~~~~~~~~
GoStats.txt   This file
GoStats.exe   The program file
GoStats.ini   A sample ini file, commented
GoFilter.80   A sample GoServer Filter file with the required changes
GoStats.htm   A sample page to ask for a stats generation


Syntax:
~~~~~~~
  GoStats ACTION <ip> <html_file> DATES
	ACTION  - required word:
			  - parse          : no screen o/p   - usual mode
			  - verbose        : some screen o/p - testing aid
			  - debug:filename : Lots of o/p to filename, some to screen
	ip       - IP address to find
	html_out - file name to write the stats to (HTML format)
	DATES    - date limitation control:
			  - all       : stats for all dates (never use this online!)
			  - today     : stats for current date only
			  - this-month: stats for current month
			  - this-year : stats for current year
			  - last-month: stats for previous month
			  - last-year : stats for previous year

GoStats parse 240.34.65.12 c:\st\$_123.html last-month


Command Line Options:
~~~~~~~~~~~~~~~~~~~~~
These are the command line options in detail.

ACTION
 This determines how much information GoStats will send to the screen while
 it is running. The options that you would use during normal running is PARSE.

   PARSE
   Parse will not produce any screen output except where a syntax error is
   detected during the INI parsing. You should test your INI file berfore you
   put it online.

   VERBOSE
   Displays on the screen various messages while it is parsing the GoServer
   Audit file.

   DEBUG:filename
   This is the action that produces the most output. Every line that GoStats
   reads is printed to the file, every internal ordering is printed, and
   other internal messages are printed. In most cases, the file will be at
   least twice as large as the original audit file. Only use this option if
   you are having problems using GoStats.

 IP
 This is the IP address that GoStats will produce a report for. You can also
 specify ALL as an IP address, in which case you will get stats for all the
 IP address. DO NOT use ALL online! The runtime is quite lengthy.

 HTML_OUT
 The name of a file that GoStats uses to create the Web page. See the GOFILTER
 section of this document for a suggested name.

 DATES
 GoStats will limit the stats to the date range given.

   ALL
   All dates. This takes a long time to generate and should not normally be
   presented for online use.

   TODAY
   The stats for today.

   THIS-MONTH, THIS-YEAR
   The current month or year.

   LAST-MONTH, LAST-YEAR
   The previous month or year.


 The longest generation times happen when you use the command line:
   gostats debug:c:\gostats\run.log all c:\gostats\stats.html all

 Run times in the minutes will result.
 Use caution when using the ALL keywords!!

GoStats.INI
~~~~~~~~~~~
   You can greatly alter the functioning of GoStats using this initialization
 file. This file MUST exist, and it MUST be in the same directory as
 GoStats.EXE

 The following ini file commands are presented in no particular order, and
 they can appear in the ini file in any order, except as indicated. The sample
 INI file has any comment lines. You can decrease the time required by
 GoStats to read the file by removing all the comment lines. This will have
 the greatest effect on slwo machines.

 Basic INI File Syntax
   The first non-blank, non-comment line in the INI file MUST BE:
	 GoStats INI File 1

   As new verswino of GoSTats are created, and if they have added INI file
   commands, then this line will change, however new version will be able to
   read older version, ar at least be able to convert them.

   Blank lines are ignored. Any line beginning with the character * is also
   ignored, which allows you to comment your ini files.

   All commands can be either upper or lower case. IN the sample INI file
   manditory keywords are shown in UPPER case. Optional keywords are shown
   in lower case.

   GoStats will change any text that is not within double quotes to upper
   case:
	 keyword = text
	 keyword2 = "text"
   These resolve to:
	 KEYWORD=TEXT
	 KEYWORD2=text

   You can place double quotes by using two adjacent double quotes:
	 keyword="The name I found, ""Bob"", starts with the letter ""B""."
   This resolves to:
	 KEYWORD=The name I found, "Bob", starts with the letter "B".

   Some keywords are shown as two words. GoStats will ignore all spaces in a
   key word. The following are equivalent:
	 Key Word=
	 keyword =
	 k e y w o r d =

  The maximum line length in the INI file is 1024 characters. If you need more,
  them split your line. This should only be required when you are setting
  Web page text and formatting. Web browsers ignore line splits.

  When the key words require a file name or path, GoStats will convert
  back slashes "\" to forward slashes "/".

KeyWords

 The following keywords are presented in a readable manner, but in no
 particular order. Feel free to group them as you want. The presentaton here
 and in the INI file makes sense to me :-))

BEEP RUN = YES | NO

   optional

   Every time that GoStats encounters this line in the INI file, it will
   beep. This can be used to indicate that someone wnated a stats page. The
   default is NO.

	 BEEP RUN = YES


BEEP ERROR = YES | NO

   optional

   GoStats runs quietly, that is it produces no screen output. If an error
   is encountered after the INI file has been read, the error is written to
   the Web page, and sent to the user. There is no indication at the server]
   that an erro occurred. You can have GoStats beep when this type of error
   occurs. The default is NO.


PERSONALITY = GOSERVE2

   REQUIRED

   The define the type of audit log that GoStats will read. Note that as of
   this release, GoStats can only read GoServer version 2.x audit files. So
   the only setting allowed is GOSERVE2.

	 PERSONALITY = GOSERVE2


AUDIT FILE = <file-name>

   REQUIRED

   The name of the audit log file. This is probably in the same directory as
   the GoServer application. GoStats does not allow multiple audit files in
   this release.

	 AUDIT FILE = c:\GoServer\goaudit.80


BASE FILE  = <file-name>

   REQUIRED

   The name of the base file. This is the file that is returned to the user
   when they do not specify a file. It is usually INDEX.HTML, but you may
   have given it a different anme.

	 BASE FILE  = \index.html


HTML PATH  = <path>

   REQUIRED

   The path that is used to get to the Web pages on the server. Note that this
   is ONLY at the local level. GoStats will remove this path from the stats
   page. After all the user does not need to know the local path, and it
   could be a security problem. You must use a trailing slash.

	 HTML PATH = d:\intranet\


TEMP PATH  = <path>

   REQUIRED

   The path that is used by GoServer for temporary files. This might be
   different from the BASE PATH if the base path points to a read only
   drive, such as a CD-ROM. The temp path is used during Special Start and
   Special File processing.

	 TEMP PATH = c:\temp\


SHOW = <type> , YES | NO

   optional

   This series of setting determine what stats will be generated. The default
   for all of the settings is NO. The stats will be shown in the order in which
   you place them into the INI file. Each stat will be shown once, even if you
   have it twice in the INI file.

   The generation stat will ALWAYS be shown at the end.

	 show = ip list    , yes
	 show = connection , yes
	 show = file list  , yes
	 show = hours      , yes
	 show = date list  , yes
	 show = generation , yes

 CONNECTION

   The connections are shown in chronological order. Please note: If you use
   the IP address ALL, then this is automatically set to NO.

 FILE LIST

   The file list is shown in alphabetical order.

 HOURS

   The number of connections for each hour.

 DATE LIST

   The number of connections for each date.

 IP LIST

   IP address stats, such as number of connections, max trasnfer rate, ...

 GENERATION

   The stats for the generation of the stats. These are always written into
   the Web page as comments.


BODY = <settings>

   optional

   You can place any <body> commands into the generated Web page.

	 body = "link=""#3333FF"" vlink=""#663366"" alink=""#FF0000"""


COLOR TABLE = <text>, <background>

   REQUIRED

   The colours to use for the normal table text and background. At this time,
   images for the background are not supported. Use the standard Web page
   colour scheme.

	 COLOR TABLE = #000000, #CCFFFF


COLOR TITLE = <text>, <background>

   REQUIRED

   The colours to use for the table titles text and background. At this time,
   images for the background are not supported. Use the standard Web page
   colour scheme.

	 COLOR TITLE = #FFFFCC, #003300


BROKEN CONNECTION = <text colour>, <background colour>, <message>

   REQUIRED

   The colours and text to use to indicate that the user started a connection
   but it was broken. This can occur when a user starts to download a file,
   such as a ZIP file, but cancels the download. Use the standard Web page
   colour scheme.

	 BROKEN CONNECTION = #FFFFFF, #FF0000, "** Broken Connection **"


SPECIAL START = <character>, <text colour>, <background colour>, <message>

   REQUIRED

   In the normal GOFILTER.80 file that GoServer uses, is the definition for a
   temporary file. By default all the temporary files start with the
   character "$". However you may have changed this character. GoStats will
   replace the actual file name used by the temporary file, and replace it
   with the message that you specify.

   So, using the example below and the TEMP PATH example above, if a file was
   returned to the user named "c:/temp/$123.80", the statistics file name
   would be: ** Request for Unknown File **

	 SPECIAL START = $ , #000000, #FFFF00, "** Request for Unknown File **"


SPECIAL FILE = <character>, <text colour>, <background colour>, <message>

   optional - multiple

   Given that GoStats processes temporary files differently, and that the
   statistics file is temporary, you do not want to "scare" the user into
   thinking that they are requesting "funny files" when they are doing
   stats requests. Since you may also have other special temporary files that
   your GOFILTER creates, GoStats allows for an unlimited number of special
   file types. The character used here must immediately follow the SPECIAL START
   character given. I have used the underscore to indicate stats files, so:

	 special file  = _ , #FFFFFF, #999900, "** Statistics Request **"

   If the file returned was named "c:/temp/$_12.80", the statistics file name
   would be: ** Statistics Request **


PAGE TITLE  = <message>

   REQUIRED

   This is the message that will be placed into the Web page title. This is
   shown in the Web Browser title bar, and is also the text used when
   bookmarks are added.

   You can place the user's IP addres into the title, by placing a %s into the
   title. Note that you can only use one %s, and that no other character may
   follow the %. If you want the actual character % to be shown, then use
   two of them, %%.

	 PAGE TITLE  = "Web Server Stats for %s - Generated"


PAGE TOP = <message>

   REQUIRED - multiple

   This is the text that will be written to the Web page just before the stats
   categories are generated. You can have as many of these as you require.
   You cannot use a percent sign followed by any other character other than
   another percent sign, %%.

	 PAGE TOP = "<CENTER><H2>My Web Server</H2></CENTER>"
	 page top = "<B>This page is generated.</B> If you have problems please"
	 page top = "contact <A HREF=""mail:webmaster@domain.com"">Webmaster</A>"
	 page top = "<br>"
	 page top = "<b>Please note. All dates and times are based on Greenwich"
	 page top = "Mean Time (GMT)</b><br>"
	 page top = "<i>On the West Coast of North America this is -8 hours,"
	 page top = "so 16:00:00 GMT is 08:00:00 Pacific</i>"


PAGE BOTTOM = <message>

   REQUIRED - multiple

   This is the text that is placed at the very bottom of the Web page. You
   should include any copywright and date messages here.

	 PAGE BOTTOM = "<CENTER><I>Copyrighted: My Organization 1999</I></CENTER>"


PAGE ERROR = <message>

   REQUIRED - multiple

   This is the message that is displayed in the case of an error while the Web
   page was being generated. You should include information on how to reach
   the Webmaster.

   In most cases an error will occur when the user tries to use there own date
   syntax.

   PAGE ERROR = "<CENTER><B>An error has occurred."
   page error = "Contact the Webmaster.</B></CENTER><BR>"
   page error = "<CENTER><B>Or print this page and FAX it"
   page error = "to 555-1212.</B><CENTER>"


GOAUDIT FILE
~~~~~~~~~~~~

GoStats does not report for every possible GOAUDIT action condition. Four
actions are supported:

D - Date
A - Start of Connection
S - Request for file
C - Completion of request

All other actions are ignored.

Please note that GoServer must be set to use GMT, so that the date line reads:
  153055 D 0 19980828 GMT ----- GoServe 2.52 -----

The "GMT" is used to verify a date change.


GOFILTER Changes
~~~~~~~~~~~~~~~~

To allow the online use of GoStats, you must make modification to the GOFILTER
file, otherwise GoServer will not be able handle a stats request.

** WARNING **
GoServer will halt on any GOFILTER error. Always test your changes on an
offline machine.
** WARNING **

Locate the section of REXX code that starts with:
--------------
   tempfile=dir'$'transaction'.'port                      /* Often used */
--------------

Place the following line after it. Note that there is an underscore after
the dollar sign. If you are using a character other than the dollar sign for
the "tempfile", then you must use the same character here.
--------------
   statfile=dir'$_'transaction'.'port                     /* stats file name */
--------------

Now locate the REXX code:
--------------
   /* Allow some special 'control' requests.  For these, the verb is */
   /* ignored (though would usually be GET) */
   if left(sel,1)='!' then do
--------------

And place the following code after the last line. Please note that you need to
change the program and file locations to match your system.

--------------
	if left(sel,6)='!stats' then do	  /* * stats * */
	  'extract clientaddr'            /* get the IP address */
	  st_type = substr(sel,8,50)	  /* could be !stats-this-month */

	  address cmd
	  'call c:\GoStats\GoStats.exe parse 'clientaddr' 'statfile' 'st_type
	  return 'FILE ERASE TYPE text/html NAME ' statfile
	end
--------------

And that's it. Now when a stats request is received by GoServer, a stats page
will be created and sent back. Use and change the sample stats request page.


Disclaimer
~~~~~~~~~~

GoStats is presented as-is. Any errors, problems, server crashes, and/or
network impact that GoStats may or may not cause is the responsibility of
the user.

Always test your INI file OFFLINE.

While reasonable care has been taken in the writing and testing of GoStats,
it is possible that a fatal error can occur.

Always test your INI file OFFLINE.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'nuf said....
