EVOLUTION-MANAGER

Edit File: awstats_setup.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta name="description" content="AWStats Documentation - Setup page">
<meta name="keywords" content="awstats, awstat, setup, config, install">
<meta name="robots" content="index,follow">
<meta name="title" content="AWStats Documentation - Setup page">
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>AWStats Documentation - Setup page</title>
<link rel="stylesheet" href="styles.css" type="text/css">
<link href="https://plus.google.com/+LaurentDestailleur-Open-Source-Expert" rel="publisher" />
</head>

<body topmargin="10" leftmargin="5">
<table
 style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;"
 bgcolor="#ffffff" border="0" cellpadding="0" cellspacing="0"
 width="100%">
 <tbody>
 <tr
 style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;">
 <td align="center" bgcolor="#9999cc"><a href="/"><img
 src="images/awstats_logo6.png" border="0"></a></td>
 <td align="center" bgcolor="#9999cc"> 
 <font
 style="font-family: arial,helvetica,sans-serif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 16pt; line-height: normal; font-size-adjust: none; font-stretch: normal;"
 color="#eeeeff">AWStats logfile analyzer 7.7 Documentation 
 
</td>
 <td align="center" bgcolor="#9999cc">&nbsp; </td>
</tr>
 </tbody>
</table>
 
 
<h1
 style="font-family: arial,helvetica,sans-serif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 26px; line-height: normal; font-size-adjust: none; font-stretch: normal;">AWStats
Installation, Configuration and Reporting</h1>
There are 3 steps to begin using AWStats: 
<ul>
 <li><a href="#INSTALL">I. Setup: Installation and configuration</a> 
 </li>
 <li><a href="#BUILD_UPDATE">II. Process logs: Building/updating
statistics database</a> 
 </li>
 <li><a href="#READ">III. Run Reports: Building and reading reports</a> 
 </li>
</ul>

<a name="INSTALL">
<h2 style="">I. Setup: Installation and configuration using
awstats_configure.pl</h2>
</a> 
<a name="INSTALLAPACHE">A) Setup for an Apache or compatible web
server (on Unix/Linux, Windows, MacOS...)</a> 
 
* Step 1: 
 
(if you use a package provided with a Linux distribution or Windows
installer, step 1
might have already been done; if you don't know, you can run this step
again) 
 
After downloading and extracting the AWStats package, you should run
the awstats_configure.pl script to do
several setup actions.
You will find it in the AWStats tools directory (If using the
Windows installer, the script is
automatically launched): 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
perl awstats_configure.pl
</td></tr></table>
 
<ul>
 This is what the script does/asks (you can do all these steps
manually instead of running awstats_configure.pl if you prefer): 
 
A) awstats_configure.pl tries to determine your current log format from
your Apache web server
configuration file httpd.conf (it asks for the path if not found).
If you use a common log, awstats_configure.pl will
suggest changing it to the NCSA combined/XLF/ELF format (you
can use your own custom log
format but this predefined log format is often the best choice and
makes setup easier). 
If you answer yes, awstats_configure.pl will modify your httpd.conf,
changing the
following directive: 
 from 
CustomLog /yourlogpath/yourlogfile common 
to 
CustomLog /yourlogpath/yourlogfile combined 
 
See the Apache manual for more information on this directive (possibly
installed on your server as www.mysite.com/manual). 
 
B) awstats_configure.pl will then add, if not already present, the
following directives to your Apache configuration file
(note that the "/usr/local/awstats/wwwroot" path might differ according
to your distribution or OS: 
 
# 
# Directives to add to your Apache conf file to allow use of AWStats as
a CGI. 
# Note that path "/usr/local/awstats/" must reflect your AWStats
Installation path. 
# 
Alias /awstatsclasses "/usr/local/awstats/wwwroot/classes/" 
Alias /awstatscss "/usr/local/awstats/wwwroot/css/" 
Alias /awstatsicons "/usr/local/awstats/wwwroot/icon/" 
ScriptAlias /awstats/ "/usr/local/awstats/wwwroot/cgi-bin/" 
# 
# This is to permit URL access to scripts/files in AWStats directory. 
# 
&lt;Directory "/usr/local/awstats/wwwroot"&gt; 
Options None 
AllowOverride None 
Order allow,deny 
Allow from all 
&lt;/Directory&gt; 
 
C) if changes were made as indicated in parts A and B,
awstats_configure.pl restarts Apache to apply the changes.&nbsp; To be
sure the log format change is effective, go to your homepage. This is
an example of the type of records you should see inserted in your new
log file after Apache
was restarted: 
 
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)" 
 
D) awstats_configure.pl will ask you for a name for the configuration
profile file. Enter an appropriate name such as that of your
web server or the virtual domain to be analyzed, i.e. mysite. 
 
awstats_configure.pl will create a new file called awstats.mysite.conf
by copying the template file awstats.model.conf.
The new file location is: 
- For Linux/BSD/Unix users: /etc/awstats. 
- For Mac OS X, Windows and other operating systems: the same directory
as awstats.pl
(cgi-bin).

E) awstats_configure.pl ends. 
 
</ul>
* Step 2: 
 
Once a configuration file has been created (by
awstats_configure.pl, by your package
installer or just by a manual copy of awstats.model.conf), it's
important to verify that the "MAIN PARAMETERS"
match your needs.&nbsp; Open awstats.mysite.conf in
your favorite text editor (i.e. notepad.exe, vi, gedit, etc) -
don&acute;t use a word processor - and make changes as required. 
 
Particular attention should be given to these parameters: 
- Verify the <a href="awstats_config.html#LogFile">LogFile</a>
value.&nbsp; It should be the full path of your server log file (You
can also use a relative path from your awstats.pl directory, but a full
path avoids errors). 
- Verify the <a href="awstats_config.html#LogType">LogType</a>
value.&nbsp; It should be "W" for analyzing
web log files. 
- Check if <a href="awstats_config.html#LogFormat">LogFormat</a> is
set to "1" (for "NCSA apache combined/ELF/XLF log format")
or use a custom log format if you don't use the combined log format. 
- Set the <a href="awstats_config.html#SiteDomain">SiteDomain</a>
parameter to the main domain name or the intranet web server name
used to reach the web site to analyze (Example: www.mysite.com). If
you have several
possible names for same site, use the main domain name and add the
others to the list in the <a href="awstats_config.html#HostAlias">HostAlias</a>
parameter. 
- You can also change other parameters if you want. The full list is
described in <a href="awstats_config.html">Configurations/Directives
options</a> page. 
 
Installation and configuration is finished. You can jump to the <a
 href="#BUILD_UPDATE">Process logs: Building/updating statistics
database</a> section. 
 
 	
 
<a name="INSTALLIIS">B) Setup for Microsoft's IIS server</a> 
 
* Step 1: 
 
Configure IIS to create logs in the "Extended W3C log format" (You can
still use
your own custom log format but setup is easier if you use the standard
extended format). To do so, start the IIS management console snap-in,
select the
appropriate web site and open its
Properties. Choose "W3C Extended Log Format", then Properties, then the
Tab "Extended Properties" and
uncheck everything under Extended
Properties.
Once they are all cleared, check just the following fields: 
<table width="95%" border=1 cellpadding=0 cellspacing=0 bgcolor=#F4F4F4 class=CFAQ><tr class=CFAQ><td class=CFAQ>
date 
time 
c-ip 
cs-username 
cs-method 
cs-uri-stem 
cs-uri-query 
sc-status 
sc-bytes 
cs-version 
cs(User-Agent) 
cs(Referer) 
</td></tr></table>
 
To be sure the log format change is effective, you must stop IIS,
backup it up (if you desire) and remove all of the old log files, restart IIS and go to
your homepage. This is an example of the type of records you should
find in the
new log file: 
<table width="95%" border=1 cellpadding=0 cellspacing=0 bgcolor=#F4F4F4 class=CFAQ><tr class=CFAQ><td class=CFAQ>
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
</td></tr></table>

* Step 2: 
 
Copy the contents of the AWStats provided cgi-bin folder, from where
the AWStats package put it on your local 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 3: 
 
Move AWStats icon sub-directories and its content into a
directory readable by your
web server, for example C:\yourwwwroot\icon. 
 
* Step 4: 
 
Create a configuration file by copying awstats.model.conf to a
new file named awstats.mysite.conf
where "mysite" is a
value of your choice but usually is the domain or virtual host name.
This new file must be saved in the same directory as awstats.pl (i.e.
cgi-bin). 
 
* Step 5: 
 
Edit your new awstats.mysite.conf
file to match your specific environment: 
- Change the <a href="awstats_config.html#LogFile">LogFile</a> value
to the
full path of your web server log file (You
can also use a relative path from your awstats.pl (cgi-bin) directory). 
- Change the <a href="awstats_config.html#LogType">LogType</a> value
to
"W" for analyzing
web log files. 
- Change the <a href="awstats_config.html#LogFormat">LogFormat</a> to
2 if you are using the "Extended W3C log format" described in
step 1; in the case of a custom format, list the IIS fields
being logged, for example: 
LogFormat="date time c-ip cs-username cs-method cs-uri-stem
cs-uri-query sc-status sc-bytes cs-version cs(User-Agent) cs(Referer)" 
- Change the <a href="awstats_config.html#DirIcons">DirIcons</a>
parameter to reflect relative path of icon directory. 
- Set the <a href="awstats_config.html#SiteDomain">SiteDomain</a>
parameter to the main domain name or the intranet
web server name used to reach the web site being analyzed (Example:
www.mydomain.com). 
- Set the <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a>
parameter to 1 if you don't have command line access and have only cgi
access. 
- Review and change other parameters if appropriate. 
 
Installation and configuration is finished. You can jump to the <a
 href="#BUILD_UPDATE">Process logs: Building/Updating statistics
database</a> section. 
 
C) Setup for other web servers 
 
The setup process is similar to the setup for Apache or IIS. 
Use <a href="awstats_config.html#LogFormat">LogFormat</a> to value "3"
if you have WebStar native log format.
Use a personalized <a href="awstats_config.html#LogFormat">LogFormat</a>
if your log format is other. 
 
D) Setup for other Internet servers, i.e. FTP, Mail, Streaming media 
 
The setup process for other file formats is described in the relevant
FAQ topics:&nbsp;
<a href="awstats_faq.html#FTP">FAQ-COM090: FTP</a>&nbsp;
<a href="awstats_faq.html#MAIL">FAQ-COM100: Mail</a> and <a
 href="awstats_faq.html#MEDIASERVER">FAQ-COM110: Streaming media</a>.

<a name="BUILD_UPDATE">
<h2 style="">II. Process logs: Building/updating statistics database</h2>
</a> 
* Update from command line (recommended): 
 
The first log analysis should be done
manually from the command line since the
process may be long and it's easier to solve problems when you can see
the
command output (if you don't
have Command Line access, skip to Step 2). The
AWStats create (and update) statistics database command is: 
 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
perl awstats.pl -config=mysite -update
</td></tr></table>
 
where mysite must
be substituted with the domain/virtual host name you selected earlier
during AWStats configuration. 
 
AWStats will read the configuration file awstats.mysite.conf
(or if
not found, awstats.conf)
and create/update its database with all summary information issued from
analyzed log file. 
 
AWStats statistics database files are saved in directory defined by the
<a href="awstats_config.html#DirData">DirData</a> parameter in
configuration file. 
When the create/update is finished, you should see a similar result on
your screen: 
 
<table width="95%" border=1 cellpadding=0 cellspacing=0 bgcolor=#F4F4F4 class=CFAQ><tr class=CFAQ><td class=CFAQ>
Update for config "/etc/awstats/awstats.mysite.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 
&nbsp;Found 122 dropped records, 
&nbsp;Found 87 corrupted records, 
&nbsp;Found 0 old records, 
&nbsp;Found 225521 new qualified records. 
</td></tr></table>
 
Dropped records are records discarded because they were not
"user HTTP requests" or were requests matching AWStats filters (See the
<a href="awstats_config.html#SkipHosts">SkipHosts</a>,
<a href="awstats_config.html#SkipUserAgents">SkipUserAgents</a>,
<a href="awstats_config.html#SkipFiles">SkipFiles</a>, <a
 href="awstats_config.html#OnlyHosts">OnlyHosts</a>,
<a href="awstats_config.html#OnlyUserAgents">OnlyUserAgents</a> and <a
 href="awstats_config.html#OnlyFiles">OnlyFiles</a> parameters).
If you want to see which lines were dropped, you can add the -showdropped
option on the command line. 
 
Corrupted records are records that do not match the log format
defined by the "LogFormat" parameter in the AWStats configuration file.
All web servers will typically have a few corrupted records
(&lt;5%) even when everything works correctly.
This can result for several reasons: 1) Web server internal bugs,
2) bad requests made by buggy browsers, 3) a dirty web server shutdown,
such as unplugging the server...&nbsp; 
 
If all of your lines are corrupted and the <a
 href="awstats_config.html#LogFormat">LogFormat</a> parameter in
AWStats configuration file is
correct, then there may be a setup problem with your web server log format.
Don't forget that
your <a href="awstats_config.html#OnlyFiles">LogFormat</a> parameter
in the AWStats configuration file MUST match
the log file format you analyze.&nbsp; If you want to see which lines
are corrupted, you can add the -showcorrupted
option on the command line. 
 
Old records are simply records that were already processed by a
previous update session.
Although it is not necessary to purge your log file after
each update process, it is highly recommended that you do so as often
as possible. 
 
New records are records in your log file that were successfully
used to build/update the statistics database. 
 
Note: A log analysis process might be slow (one second for each 4500
lines of your
logfile with an Athlon 1Ghz, plus DNS resolution time for each
different
IP
address in your logfile if <a href="awstats_config.html#DNSLookup">DNSLookup</a>
is set to 1 and not already done in your log file).&nbsp; See the <a
 href="awstats_benchmark.html">Benchmarks page</a> for more detailed
information.

* Update from a browser: 
 
AWStats statistics can also be updated from a browser, providing
real-time statistics, by clicking
the "Update now" link that appears when AWStats is used as a CGI (The
URL is described in the next
section '<a href="#READ">Run reports: Building and reading reports</a>'). 
 
Warning!! 
To enable this link, the configuration file parameter <a
 href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a>
must be set to 1 (The link is not enabled by
default). 
Using the on-line update does not prevent you from running the update
process automatically on a scheduled basis (the command is same as that
of the first update process above). 
For this, you have two choices: 
- Include the update command in your logrotate process. See <a
 href="awstats_faq.html#ROTATE">FAQ-COM120</a> for details. 
- Or add instructions in your crontab (Unix/Linux) or your task
scheduler (Windows), to regularly launch the Awstats update
process. See <a href="awstats_faq.html#CRONTAB">FAQ-COM130</a> for
details. 
 
See the AWStats <a href="awstats_benchmark.html">Benchmarks page</a>
for
the recommended update/logrotate frequency.

<a name="READ">
<h2 style="">III. Run reports: Building and reading reports</h2>
</a> 
To see the analysis results, you have several options depending on your
<a href="awstats_security.html">security policy</a>. 
 
Note: you must have created a statistics data base for the analysis
period by processing your
log files before you try to create reports.&nbsp; See the previous
section. 
 
1. The first option is to build the main reports, in a static HTML
page,
from the command line,
using the following syntax (skip to the second option if you only have
CGI access): 
 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
perl awstats.pl -config=mysite -output -staticlinks
&gt; awstats.mysite.html
</td></tr></table>
 
where mysite must
be substituted with the domain/virtual host name you selected earlier
during AWStats configuration. 
 
To create specific individual reports, specify the report name on the
command
line as follows&sup1;: 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
perl awstats.pl -config=mysite -output=alldomains
-staticlinks &gt; awstats.mysite.alldomains.html 
perl awstats.pl -config=mysite -output=allhosts
-staticlinks &gt; awstats.mysite.allhosts.html 
perl awstats.pl -config=mysite -output=lasthosts
-staticlinks &gt; awstats.mysite.lasthosts.html 
perl awstats.pl -config=mysite -output=unknownip
-staticlinks &gt; awstats.mysite.unknownip.html 
perl awstats.pl -config=mysite -output=alllogins
-staticlinks &gt; awstats.mysite.alllogins.html 
perl awstats.pl -config=mysite -output=lastlogins
-staticlinks &gt; awstats.mysite.lastlogins.html 
perl awstats.pl -config=mysite -output=allrobots
-staticlinks &gt; awstats.mysite.allrobots.html 
perl awstats.pl -config=mysite -output=lastrobots
-staticlinks &gt; awstats.mysite.lastrobots.html 
perl awstats.pl -config=mysite -output=urldetail
-staticlinks &gt; awstats.mysite.urldetail.html 
perl awstats.pl -config=mysite -output=urlentry
-staticlinks &gt; awstats.mysite.urlentry.html 
perl awstats.pl -config=mysite -output=urlexit
-staticlinks &gt; awstats.mysite.urlexit.html 
perl awstats.pl -config=mysite -output=browserdetail
-staticlinks &gt; awstats.mysite.browserdetail.html 
perl awstats.pl -config=mysite -output=osdetail
-staticlinks &gt; awstats.mysite.osdetail.html 
perl awstats.pl -config=mysite -output=unknownbrowser
-staticlinks &gt; awstats.mysite.unknownbrowser.html 
perl awstats.pl -config=mysite -output=unknownos
-staticlinks &gt; awstats.mysite.unknownos.html 
perl awstats.pl -config=mysite -output=refererse
-staticlinks &gt; awstats.mysite.refererse.html 
perl awstats.pl -config=mysite -output=refererpages
-staticlinks &gt; awstats.mysite.refererpages.html 
perl awstats.pl -config=mysite -output=keyphrases
-staticlinks &gt; awstats.mysite.keyphrases.html 
perl awstats.pl -config=mysite -output=keywords
-staticlinks &gt; awstats.mysite.keywords.html 
perl awstats.pl -config=mysite -output=errors404
-staticlinks &gt; awstats.mysite.errors404.html 
</td></tr></table>
 
&sup1;If you prefer, you can use the <a
 href="awstats_tools.html#awstats_buildstaticpages">awstats_buildstaticpages</a>
tool to
build all these pages in one command, or to generate PDF files. 
 
Notes: 
 
a) You can also add a filter on the following reports: urldetail,
urlentry, urlexit, allhosts, refererpages.&nbsp; The filter
can be a regexp (regular expression) on the full key you want AWStats
to report on and is appended to the output
parameter separated by a ":". 
 
For example, to output the urldetail report, including only pages which
contain /news in their URL, you
can use the following command line: 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
perl awstats.pl -config=mysite -output=urldetail:/news
-staticlinks &gt; awstats.mysite.urldetailwithfilter.html
</td></tr></table>
 
b) If you want to build a report for a particular month, add
the options -month=MM -year=YYYY where MM is the month
expressed as two digits, i.e. 03, and year is the four digit
year.&nbsp; To build a
report for a full year, add the options -month=all -year=YYYY
(warning: this is often resource intensive and might use a lot of
memory
and CPU.&nbsp; Unix/Linux like operating systems might benefit from use
of the "nice" command.) 
 
 
2) The second option is to dynamically view your statistics from a
browser.&nbsp; To do this, use the URL: 
<table border=1 cellpadding=1 cellspacing=0 bgcolor=#F4F4F4 width="95%" class=CFAQ><tr class=CFAQ><td class=CFAQ>
http://www.myserver.mydomain/awstats/awstats.pl?config=mysite
</td></tr></table>
 
where mysite specifies the configuration
file to
use (AWStats will use the file awstats.mysite.conf). 
 
All output command line options (except -staticlinks and -logfile) are
also available when using AWStats with a browser. Just use them as URL
parameters: change "-option" to
"&amp;option", i.e.&nbsp; http://www.myserver.mydomain/awstats/awstats.pl?month=MM&amp;year=YYYY&amp;output=unknownos 
 
Reports are generated in real time from the statistics data
base.&nbsp; If this is slow, or putting too much load on your server,
consider generating static reports instead. 
 
If the <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a>
parameter is set to 1 in AWStats configuration file,
you will also be able to run the update process from your browser. Just
click on the link "Update now". 
 
 
<hr>

<div class="htmldoc-ignore">

Article written by <a href="https://plus.google.com/+LaurentDestailleur-Open-Source-Expert?rel=author" rel="author" style="color: #ccc; font-weight: normal;">Laurent Destailleur</a>. 
 
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
<g:plusone></g:plusone>

<div id="fb-root"></div>
<script>(function(d, s, id) {
 var js, fjs = d.getElementsByTagName(s)[0];
 if (d.getElementById(id)) return;
 js = d.createElement(s); js.id = id;
 js.src = "//connect.facebook.net/fr_FR/all.js#xfbml=1";
 fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
<div class="fb-like" data-href="http://www.awstats.org/docs/awstats_setup.html" data-layout="button_count" data-action="recommend" data-show-faces="false" data-share="true"></div>
 

<a href="https://twitter.com/awstats_project" class="twitter-follow-button" data-show-count="false">Follow @awstats_project</a>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
</div>

</body>
</html>