From: eldy <> Date: Sat, 27 Sep 2003 19:30:59 +0000 (+0000) Subject: Updated documentation X-Git-Tag: AWSTATS_6_0_BETA~219 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=29bad3a097619a36bbd1592bd13daaea17a12ff1;p=thirdparty%2FAWStats.git Updated documentation --- diff --git a/docs/awstats_setup.html b/docs/awstats_setup.html index d559a587..8491e175 100644 --- a/docs/awstats_setup.html +++ b/docs/awstats_setup.html @@ -44,9 +44,11 @@ AWStats common use is made in 3 steps:

Step 1 : Install and Setup
-A) With Apache or compatible server (on Unix/Linux, Windows, MacOS...)
+A) With Apache or compatible server (on Unix/Linux, Windows, MacOS...)
+
+* Step 1-1:
+(in most cases, if Apache is correctly setup, this step is not required, just read it to know)

-* Step 1-1
Configure your apache web server to have NCSA combined/XLF/ELF log format (you can use your own log format but this predefined logformat is often the best choice and make setup easier). You can do this by changing, in httpd.conf, following directives (See your apache manual for more information):
@@ -58,29 +60,41 @@ To be sure the log format change is effective, you can stop Apache, remove all o your homepage. This is an example of records you should get then in your new log file:
62.161.78.75 - - [dd/mmm/yyyy:hh:mm:ss +0000] "GET / HTTP/1.1" 200 1234 "http://www.from.com/from.html" "Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)"

-* Step 1-2
-Copy the contents of the uncompressed cgi-bin folder from your hard drive to your server's cgi-bin + +* Step 1-2:
+(if you use a package provided with a Linux distribution, this might not be necessary)

+Copy the contents of the provided cgi-bin folder from your hard drive to your server's cgi-bin directory (this includes awstats.pl, awstats.model.conf, and the lang, lib and plugins sub-directories).

-* Step 1-3
-If necessary (should not with most Perl interpreter), edit the first (top-most) line of awstats.pl file that is
+ +* Step 1-3:
+(with most Perl interpreter, this step is not required)

+If necessary, edit the first (top-most) line of awstats.pl file that is
#!/usr/bin/perl
to reflect the path were your Perl interpreter is installed. Default value works for most of Unix OS, but it also might be
#!/usr/local/bin/perl
With Apache for Windows and ActivePerl interpreter, it might be
#!c:/program files/activeperl/bin/perl

-* Step 1-4
+ +* Step 1-4:
+(if you use a package provided with a Linux distribution, this might not be necessary)

Move AWStats icon sub-directories and its content into a directory readable by your web server, for example /yourwwwroot/icon or /yourwwwroot/icons.

-* Step 1-5
-Copy awstats.model.conf file into a new file named awstats.myvirtualhostname.conf. -This new file must be stored in
-- /etc/awstats or /etc/opt/awstats or /etc or same directory than awstats.pl (so cgi-bin) for Unix/Linux users.
-- same directory than awstats.pl (so cgi-bin) for Windows and other OS.
+ +* Step 1-5:
+(if you use a package provided with a Linux distribution, your config file might +have been already created under /etc/awstats directory)

+Create a config file by copying awstats.model.conf file into a new file named awstats.myvirtualhostname.conf. +You can use the value of your choice instead of "myvirtualhostname". This new file must be stored in
+- For Unix/Linux users: /etc/awstats or /usr/local/etc/awstats or /etc or same directory than awstats.pl (so cgi-bin).
+- For Windows and other OS: Same directory than awstats.pl (so cgi-bin).

-* Step 1-6
+ +* Step 1-6:
+(if you use a package provided with a Linux distribution, your config file +might have been already edited and stored in /etc/awstats)

Edit this new config file with your own setup :
- Change LogFile value with full path of your web server log file (You can also use a relative path from your awstats.pl directory).
@@ -89,7 +103,8 @@ web server log files, "M" for mail log files, "F" for ftp log files, "O" otherwi - Check if LogFormat has the value "1" (it means "NCSA apache combined/ELF/XLF log format").
- Change DirIcons parameter to reflect relative path of icon directory.
- Edit SiteDomain parameter with the main domain name or the intranet -web server name used to reach the web site to analyze (Example: www.mydomain.com).
+web server name used to reach the web site to analyze (Example: www.mydomain.com). If you have several +possible name for same site, add list in HostAlias parameter.
- You can change other parameters if you want.

Step 1 (Install and Setup) is finished. You can jump to the Build/Update Statistics section.
@@ -97,9 +112,10 @@ Step 1 (Install and Setup) is finished. You can jump to the B) With IIS server
+
+* Step 1-1:

-* Step 1-1
Configure IIS to log in "Extended W3C log format" (You can still use your own log format but setup is easier if made like suggested). So, for this, start the IIS Snap-in, select the web site and look at its @@ -123,20 +139,28 @@ To be sure the log format change is effective, you must stop IIS, remove all old your homepage. This is an example of records you should get then in the new log file:
2000-07-19 14:14:14 62.161.78.73 - GET / 200 1234 HTTP/1.1 Mozilla/4.0+(compatible;+MSIE+5.01;+Windows+NT+5.0) http://www.from.com/from.htm

-* Step 1-2
-Copy the contents of the uncompressed cgi-bin folder from your hard drive to your server's cgi-bin + +* Step 1-2:
+
+Copy the contents of the provided cgi-bin folder from your hard drive to your server's cgi-bin directory (this includes awstats.pl, awstats.model.conf, and the lang, lib and plugins sub-directories).

-* Step 1-3
+ +* Step 1-3:
+(if your IIS and Perl are setup correctly, this step is not required)

Move AWStats icon sub-directories and its content into a directory readable by your web server, for example C:\yourwwwroot\icon.

-* Step 1-4
-Copy awstats.model.conf file into a new file named awstats.myvirtualhostname.conf. -This new file must be stored in
-- same directory than awstats.pl (so cgi-bin)
+ +* Step 1-4:
+
+Create a config file by copying awstats.model.conf file into a new file named awstats.myvirtualhostname.conf. +You can use the value of your choice instead of "myvirtualhostname". This new file must be stored in
+- Same directory than awstats.pl (so cgi-bin)
+
+ +* Step 1-5:

-* Step 1-5
Edit this new config file with your own setup :
- Change LogFile value with full path of your web server log file (You can also use a relative path from your awstats.pl directory).
@@ -146,6 +170,7 @@ web server log files, "M" for mail log files, "F" for ftp log files, "O" otherwi - Change DirIcons parameter to reflect relative path of icon directory.
- Edit SiteDomain parameter with the main domain name or the intranet web server name used to reach the web site to analyze (Example: www.mydomain.com).
+- Set AllowToUpdateStatsFromBrowser parameter to 1 if you don't have command line access and have only cgi access.
- You can change other parameters if you want.

Step 1 (Install and Setup) is finished. You can jump to the Build/Update Statistics section.
@@ -156,7 +181,8 @@ Step 1 (Install and Setup) is finished. You can jump to the LogFormat to value "3" if you have WebStar native log format.
+Use LogFormat to value "3" if you have WebStar native log format, use +a personalized LogFormat if your log format is other.

@@ -165,24 +191,34 @@ Use LogFormat to value "3" if you ha

Step 2 : Build/Update Statistics
-* Step 2-1
-The first analyze/update of statistics can be made the first time manually from the command line (the first time, -process may be long) :
+* Step 2-1:
+
+The first analyze/update of statistics should be made the first time manually from the command line since first time, +process may be long and it's easier to solve problems (if you don't have Command Line access, just go to Step 2-2). The +AWStats update command line is:
awstats.pl -config=myvirtualhostname -update

AWStats will read the config file awstats.myvirtualhostname.conf (or if not found, awstats.conf) and create/update its database with all summary information issued from analyzed log file.
AWStats database files are saved in directory defined by DirData parameter in config file.
-When update is finished, you should get a result like this:
-Lines in file: 225730
-Found 5 dropped records,
-Found 124 corrupted records,
-Found 0 old records,
-Found 225601 new records.
+When update is finished, you should get on screen a result like this:
+
+Update for config "/etc/awstats/awstats.myvirtualhostname.conf"
+With data in log file "/pathtoyourlog/yourlog.log"...
+Phase 1 : First bypass old records, searching new record...
+Searching new records from beginning of log file...
+Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
+Jumped lines in file: 0
+Parsed lines in file: 225730
+ Found 122 dropped records,
+ Found 87 corrupted records,
+ Found 0 old records,
+ Found 225521 new qualifed records.

Dropped records are records discarded because they were not user HTTP request or requests were not qualified by AWStats filters (See SkipHosts, SkipUserAgents, -SkipFiles, and OnlyFiles parameters). +SkipFiles, OnlyHosts, +OnlyUserAgents and OnlyFiles parameters). If you want to see which lines were dropped, you can add the -showdropped option on command line.
Corrupted records are records that does not match log format defined by "LogFormat" parameter in AWStats config/domain file. With all webservers you can experience a little bit corrupted records (<5%) even when everythings work correctly. @@ -192,8 +228,9 @@ correct, it may be the log format setup in your web server that is wrong. Don't your LogFormat parameter in AWStats config/domain file MUST match the log file format you analyze.
If you want to see which lines are corrupted, you can add the -showcorrupted option on command line.
-Old records are simply records that were already processed by a previous update process. So it's not necessary to -purge your log file after each update process even if it's highly recommended to do it as often as possible.
+Old records are simply records that were already processed by a previous update process. +You understood that it's not necessary to purge your log file after each update process even +if it's highly recommended to do it as often as possible.
New records are records in your log file that were successfully used to build/update statistics.

Note : A log analysis process is slow (one second for each 4500 lines of your @@ -202,13 +239,15 @@ address in your logfile if DNSLookup See Benchmark page for more accurate information.

-* Step 2-2
-Even if AWStats allows "real-time" statistics with its "update from browser feature" (See next -section Read Statistics), you should run an update process from a scheduler (command is same than -first process) frequently.
+* Step 2-2:
+
+AWStats statistics can be updated web, to provide real-time statistics, by clicking +the "Update now" link on web page (See next section Read Statistics dynamically).
+However, it is HIGHLY recommanded to run an update process from a scheduler frequently (command +is same than update of first process).

You have two choice:
-- Include the update in your logrotate process. See FAQ-COM120 for this.
+- Include the update command in your logrotate process. See FAQ-COM120 for this.
- Or add instructions in your crontab (Unix/Linux) or your task scheduler (for Windows), to launch frequently this Awstats update process. See FAQ-COM130 for this.

See AWStats Benchmark page for recommanded update/logrotate frequency.
@@ -221,7 +260,8 @@ See AWStats Benchmark page for recommanded To see results of analyze, you have several solutions depending on your security policy.

-* First solution is to build the main reports, in a static HTML page, from the command line, like this :
+* First solution is to build the main reports, in a static HTML page, from the command line, +like this (jump to second solution if you have ONLY CGI access):
perl awstats.pl -config=myvirtualhostname -output -staticlinks > awstats.myvirtualhostname.html

You can also use all other output options (each of them give you another report). @@ -247,7 +287,7 @@ This is how to use all other possible output options(1) :
perl awstats.pl -config=myvirtualhostname -output=errors404 -staticlinks > awstats.myvirtualhostname.errors404.html

Note (1): If you prefer, you can use awstats_buildstaticpages tool to -build all those pages in one command.
+build all those pages in one command or to generate PDF files.

Note (2): You can also add a filter on the following output reports:urldetail, urlentry, urlexit, allhosts, refererpages.
filter can be a regexp on the full key you want awstats to present information about and you must use it after the output @@ -260,7 +300,7 @@ Note (3): If you want to build a report for a particular month, add options < To build a report for full year (warning: This may use a lot of memory and CPU), add options -month=all -year=YYYY.


-* Another solution is to view dynamically your statistics from a browser. For this use URL:
+* Another solution is to view dynamically your statistics from a browser. For this, use URL:
http://www.myserver.mydomain/cgi-bin/awstats.pl?config=myvirtualhostname
where myvirtualhostname is used to know which config file to use (AWStats will use awstats.myvirtualhostname.conf file).

diff --git a/wwwroot/cgi-bin/awstats.pl b/wwwroot/cgi-bin/awstats.pl index 79e22179..13a7b552 100644 --- a/wwwroot/cgi-bin/awstats.pl +++ b/wwwroot/cgi-bin/awstats.pl @@ -969,15 +969,15 @@ sub GetSessionRange { #------------------------------------------------------------------------------ sub Read_Config { # Check config file in common possible directories : - # Windows : "$DIR" (same dir than awstats.pl) - # Mandrake and Debian package : "/etc/awstats" - # FHS standard, Suse package : "/etc/opt/awstats" - # Other possible directories : "/etc", "/usr/local/etc/awstats" + # Windows : "$DIR" (same dir than awstats.pl) + # Standard, Mandrake and Debian package : "/etc/awstats" + # Other possible directories : "/usr/local/etc/awstats", "/etc" + # FHS standard, Suse package : "/etc/opt/awstats" my $configdir=shift; my @PossibleConfigDir=(); if ($configdir) { @PossibleConfigDir=("$configdir"); } - else { @PossibleConfigDir=("$DIR","/etc/awstats","/etc/opt/awstats","/etc","/usr/local/etc/awstats"); } + else { @PossibleConfigDir=("$DIR","/etc/awstats","/usr/local/etc/awstats","/etc","/etc/opt/awstats"); } # Open config file $FileConfig=$FileSuffix=''; @@ -5095,11 +5095,11 @@ if ((! $ENV{'GATEWAY_INTERFACE'}) && (! $SiteConfig)) { print " First, $PROG tries to read $PROG.virtualhostname.conf as the config file.\n"; print " If not found, $PROG tries to read $PROG.conf\n"; print " Note 1: Config files ($PROG.virtualhostname.conf or $PROG.conf) must be\n"; - print " in /etc/awstats, /etc/opt/awstats, /etc or same directory than awstats.pl\n"; - print " file.\n"; + print " in /etc/awstats, /usr/local/etc/awstats, /etc or same directory than\n"; + print " awstats.pl file.\n"; print " Note 2: If AWSTATS_FORCE_CONFIG environment variable is defined, AWStats will\n"; - print " use it as the \"config\" value, whatever is the value on command line or URL.\n"; - print " See AWStats documentation for all setup instrutions.\n"; + print " use it as the \"config\" value, whatever is the value on command line or URL.\n"; + print " See AWStats documentation for all setup instrutions.\n"; print "\n"; print "Options to update statistics:\n"; print " -update to update statistics (default)\n";