OS/2 Shareware BBS: 35 Internet

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / gostats.zip / gostats.txt < prev

Wrap

Text File | 1999-03-12 | 17KB | 540 lines

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 = "This page is generated. If you have problems please" page top = "contact <A HREF=""mail:webmaster@domain.com"">Webmaster</A>" page top = " " page top = "Please note. All dates and times are based on Greenwich" page top = "Mean Time (GMT) " page top = "On the West Coast of North America this is -8 hours," page top = "so 16:00:00 GMT is 08:00:00 Pacific" 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>Copyrighted: My Organization 1999</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>An error has occurred." page error = "Contact the Webmaster.</CENTER> " page error = "<CENTER>Or print this page and FAX it" page error = "to 555-1212.<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....