1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
|
<!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">
<title>AWStats Documentation - Setup page</title>
<link rel="stylesheet" href="styles.css" type="text/css">
<!-- $Revision: 1.71 $ - $Author: eldy $ - $Date: 2005/02/18 19:39:59 $ -->
</head>
<body topmargin=10 leftmargin=5>
<table style="font: 10pt arial,helvetica,verdana" cellpadding=0 cellspacing=0 border=0 bgcolor=#FFFFFF width=100%>
<!-- Large -->
<tr style="font: 10pt arial,helvetica,verdana">
<td bgcolor=#9999cc align=center><a href="/"><img src="images/awstats_logo4.png" border=0></a></td>
<td bgcolor=#9999cc align=center>
<br>
<font style="font: 16pt arial,helvetica,sans-serif" color=#EEEEFF><b>AWStats logfile analyzer 6.4 Documentation</b></font><br>
<br>
</td>
<td bgcolor=#9999cc align=center>
</td>
</tr>
</table>
<br><br><H1 style="font: 26px arial,helvetica,sans-serif">Install, Setup and Use AWStats</H1>
AWStats common use is made in 3 steps:<br>
<ul>
<li>Step 0 : <a href="#INSTALL">The install and setup</a><br>
<li>Step 1 : <a href="#BUILD_UPDATE">The build/update of statistics</a><br>
<li>Step 2 : <a href="#READ">The reading of results</a><br>
</ul>
<br>
<!--
<br>
Before starting, check that your Perl version is at least 5.005_03 (or higher) by running the <i>perl -v</i> command.
If not, you can install a recent Perl interpreter from <a href="http://www.activestate.com/ActivePerl/">ActivePerl</a> (<font color=#221188>Win32</font>) or <a href="http://www.perl.com/pub/language/info/software.html">Perl.com</a> (<font color=#221188>Unix/Linux/Other</font>).<br>
-->
<br><a name="INSTALL"><H2 style="font: 22px arial,helvetica,sans-serif color: #606060"><u>Step 0 : Install and Setup with awstats_configure.pl</u></H2></a>
<br>
<a name="INSTALLAPACHE"><b>A) With Apache or compatible server (on Unix/Linux, Windows, MacOS...)</b></a><br>
<br>
<font style="color: #111155"><b>* Step 0-1</b>:</font><br>
(if you use a package provided with a Linux distribution or Windows installer, action done in step 0-1
might have already be done, if you don't know you, do it again)<br>
<br>
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 <b>tools</b> directory (If using the windows installer, the script is
automatically launched):<br>
<b><i>perl awstats_configure.pl</i></b><br>
<ul>
<u>This is what the script do/ask (you can do all those steps manually instead of running awstats_configure.pl if you prefer):</u><br>
<br>
A) awstats_configure.pl try to find your Apache web server config file (ask path if not found) and check
inside your server log format configuration.
If you use a <b>common</b> log, awstats_configure.pl will
suggest to change it to have <b>NCSA combined/XLF/ELF</b> log format (you can use your own log
format but this predefined logformat is often the best choice and make setup easier).<br>
If you answer yes, awstats_configure.pl will modify your <b>httpd.conf</b> to change all the
following directives:<br>
<i>CustomLog /yourlogpath/yourlogfile common</i><br>
into<br>
<i>CustomLog /yourlogpath/yourlogfile combined</i><br>
<br>
See your Apache manual for more information on this directive.<br>
To be sure the log format change is effective, later you can stop Apache, remove all old
log files, restart Apache and go to your homepage. This is an example of records you
should get then in your new log file:<br>
<i>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)"</i><br>
<br>
B) Then, awstats_configure.pl will add, if not already present, the following directives to your Apache config file
(note that the "/usr/local/awstats/wwwroot" path might differ according to your distribution or OS:<br>
<i>
<br>#
<br># Directives to add to your Apache conf file to allow use of AWStats as a CGI.
<br># Note that path "/usr/local/awstats/" must reflect your AWStats install path.
<br>#
<br>Alias /awstatsclasses "/usr/local/awstats/wwwroot/classes/"
<br>Alias /awstatscss "/usr/local/awstats/wwwroot/css/"
<br>Alias /awstatsicons "/usr/local/awstats/wwwroot/icon/"
<br>ScriptAlias /awstats/ "/usr/local/awstats/wwwroot/cgi-bin/"
<br>#
<br># This is to permit URL access to scripts/files in AWStats directory.
<br>#
<br><Directory "/usr/local/awstats/wwwroot">
<br> Options None
<br> AllowOverride None
<br> Order allow,deny
<br> Allow from all
<br></Directory>
</i>
<br>
<br>
C) awstats_configure.pl restart Apache to apply the changes made in A and B (if changes were made).<br>
<br>
D) awstats_configure.pl will ask you a name for a config profile file. Enter here the name of your
web server or any analysis profile name, for example <b>myvirtualhostname</b>.<br>
So awstats_configure.pl will copy the file <b>awstats.model.conf</b> file into a new file
named <b>awstats.myvirtualhostname.conf</b>.
You can use the value of your choice instead of "myvirtualhostname". This new file is stored into:<br>
- For Linux/BSD/Unix users: /etc/awstats.<br>
- For Mac OS X, Windows and other OS: Same directory than awstats.pl (so cgi-bin).<br>
<br>
E) awstats_configure.pl ends.<br>
<br>
</ul>
<font style="color: #111155"><b>* Step 0-2</b>:</font><br>
Once a config file has been automatically created (by awstats_configure.pl, by your package
installer or just by a manual copy of awstats.model.conf), it's important to edit it manually and change the "MAIN PARAMETERS"
to match all your needs:<br>
<br>
This is for example the parameters you should check seriously :<br>
- Check/Change <a href="awstats_config.html#LogFile">LogFile</a> value with full path of your server log file (You
can also use a relative path from your awstats.pl directory, but full path avoid errors).<br>
- Check/Change <a href="awstats_config.html#LogType">LogType</a> value with "W" for analyzing
web server log files, "S" for a streaming server log file, "M" for mail log files, "F" for ftp log files.<br>
- Check if <a href="awstats_config.html#LogFormat">LogFormat</a> has the value "1" (it means "NCSA apache combined/ELF/XLF log format")
or use a personalized log format if you don't use combined log format.<br>
- Edit <a href="awstats_config.html#SiteDomain">SiteDomain</a> parameter with the main domain name or the intranet
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 <a href="awstats_config.html#HostAlias">HostAlias</a> parameter.<br>
- You can also change other parameters if you want.<br>
<br>
Step 0 (Install and Setup) is finished. You can jump to the <a href="#BUILD_UPDATE">Build/Update Statistics</a> section.<br>
<br>
<br>
<br>
<a name="INSTALLIIS"><b>B) With IIS server</b></a><br>
<br>
<font style="color: #111155"><b>* Step 0-1</b>:</font><br>
<br>
Configure IIS to log in <b>"Extended W3C log format"</b> (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
Properties. Choose W3C Extended Log Format, then Properties, then the
Tab Extended Properties and uncheck everything under Extended Properties.
Once they are all unchecked, check all following fields:<br>
<i>
date<br>
time<br>
c-ip<br>
cs-username<br>
cs-method<br>
cs-uri-stem<br>
cs-uri-query<br>
sc-status<br>
sc-bytes<br>
cs-version<br>
cs(User-Agent)<br>
cs(Referer)<br>
</i>
To be sure the log format change is effective, you must stop IIS, remove all old log files, restart IIS and go to
your homepage. This is an example of records you should get then in the new log file:<br>
<i>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</i><br>
<br>
<font style="color: #111155"><b>* Step 0-2</b>:</font><br>
<br>
Copy the contents of the provided cgi-bin folder from your hard drive to your server's cgi-bin
directory (this includes <b>awstats.pl</b>, <b>awstats.model.conf</b>, and the <b>lang</b>, <b>lib</b> and <b>plugins</b> sub-directories).<br>
<br>
<font style="color: #111155"><b>* Step 0-3</b>:</font><br>
<br>
Move AWStats <b>icon sub-directories</b> and its content into a directory readable by your
web server, for example C:\yourwwwroot\icon.<br>
<br>
<font style="color: #111155"><b>* Step 0-4</b>:</font><br>
<br>
Create a config file by copying <b>awstats.model.conf</b> file into a new file named <b>awstats.myvirtualhostname.conf</b>.
You can use the value of your choice instead of "myvirtualhostname". This new file must be stored in<br>
- Same directory than awstats.pl (so cgi-bin)<br>
<br>
<font style="color: #111155"><b>* Step 0-5</b>:</font><br>
<br>
Edit this new config file with your own setup :<br>
- Change <a href="awstats_config.html#LogFile">LogFile</a> value with full path of your web server log file (You
can also use a relative path from your awstats.pl directory).<br>
- Change <a href="awstats_config.html#LogType">LogType</a> value with "W" for analyzing
web server log files, "S" for a streaming server log file, "M" for mail log files, "F" for ftp log files, "O" otherwise.<br>
- Change <a href="awstats_config.html#LogFormat">LogFormat</a> to a value with same field's name defined in step 0-1:<br><i>
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)"</i><br>
- Change <a href="awstats_config.html#DirIcons">DirIcons</a> parameter to reflect relative path of icon directory.<br>
- Edit <a href="awstats_config.html#SiteDomain">SiteDomain</a> parameter with the main domain name or the intranet
web server name used to reach the web site to analyze (Example: www.mydomain.com).<br>
- Set <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a> parameter to 1 if you don't have command line access and have only cgi access.<br>
- You can change other parameters if you want.<br>
<br>
Step 0 (Install and Setup) is finished. You can jump to the <a href="#BUILD_UPDATE">Build/Update Statistics</a> section.<br>
<br>
<br>
<br>
<b>C) With other web servers</b><br>
<br>
Setup process is similar to setup for Apache or IIS.<br>
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.<br>
<br>
<br>
<br>
<a name="BUILD_UPDATE"><H2 style="font: 22px arial,helvetica,sans-serif color: #606060"><u>Step 1 : Build/Update Statistics</u></H2></a>
<br>
<font style="color: #111155"><b>* Step 1-1</b>:</font><br>
<br>
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 1-2). The
AWStats update command line is:<br>
<b><i>awstats.pl -config=myvirtualhostname -update</i></b><br>
<br>
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.<br>
AWStats database files are saved in directory defined by <a href="awstats_config.html#DirData">DirData</a> parameter in config file.<br>
When update is finished, you should get on screen a result like this:<br>
<br><i>
Update for config "/etc/awstats/awstats.myvirtualhostname.conf"<br>
With data in log file "/pathtoyourlog/yourlog.log"...<br>
Phase 1 : First bypass old records, searching new record...<br>
Searching new records from beginning of log file...<br>
Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...<br>
Jumped lines in file: 0<br>
Parsed lines in file: 225730<br>
Found 122 dropped records,<br>
Found 87 corrupted records,<br>
Found 0 old records,<br>
Found 225521 new qualifed records.<br>
</i><br>
<b>Dropped records</b> are records discarded because they were not user HTTP request or requests were not qualified
by AWStats filters (See <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 <b>-showdropped</b> option on command line.<br>
<b>Corrupted records</b> 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.
This can be the result of several reasons: Web server internal bugs, bad requests made by buggy browsers, web server brutal stop...<br>
If all your lines are corrupted and <a href="awstats_config.html#LogFormat">LogFormat</a> parameter in AWStats config/domain file is
correct, it may be the log format setup in your web server that is wrong. Don't forget that
your <a href="awstats_config.html#OnlyFiles">LogFormat</a> parameter in AWStats config/domain file MUST match
the log file format you analyze.<br>
If you want to see which lines are corrupted, you can add the <b>-showcorrupted</b> option on command line.<br>
<b>Old records</b> 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.<br>
<b>New records</b> are records in your log file that were successfully used to build/update statistics.<br>
<br>
Note : A log analysis process is slow (one second for each 4500 lines of your
logfile with 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).<br>
See <a href="awstats_benchmark.html">Benchmark page</a> for more accurate information.<br>
<br>
<font style="color: #111155"><b>* Step 1-2</b>:</font><br>
<br>
AWStats statistics can be updated from a browser, to provide real-time statistics, by clicking
the "Update now" link that appears when AWStats is used as a CGI (Next section '<a href="#READ">Read Statistics</a>
dynamically' gives you URL to use for that).<br>
Warning !!<br>
To enable this link, your parameter <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a>
must be set to 1 in your config file (Link is not enabled by default).<br>
<br>
Then, using on-line update does not prevent you from running the update process from a scheduler
frequently (command is same than update of first process).<br>
For this, you have two choices:<br>
- Include the update command in your <b>logrotate</b> process. See <a href="awstats_faq.html#ROTATE">FAQ-COM120</a> for this.<br>
- Or add instructions in your <b>crontab</b> (Unix/Linux) or your <b>task scheduler</b> (for
Windows), to launch frequently the Awstats update process. See <a href="awstats_faq.html#CRONTAB">FAQ-COM130</a> for this.<br><br>
See AWStats <a href="awstats_benchmark.html">Benchmark page</a> for recommanded update/logrotate frequency.<br>
<br>
<br>
<br><a name="READ"><H2 style="font: 22px arial,helvetica,sans-serif color: #606060"><u>Step 2 : Read Statistics</u></H2></a>
<br>
To see results of analyze, you have several solutions depending on your <a href="awstats_security.html">security policy</a>.<br>
<br>
* 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):<br>
<b><i>perl awstats.pl -config=myvirtualhostname -output -staticlinks > awstats.myvirtualhostname.html</i></b><br>
<br>
You can use all other output options (each of them give you another report).
This is how to use all other possible output options(1) :<br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=alldomains -staticlinks > awstats.myvirtualhostname.alldomains.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=allhosts -staticlinks > awstats.myvirtualhostname.allhosts.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=lasthosts -staticlinks > awstats.myvirtualhostname.lasthosts.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=unknownip -staticlinks > awstats.myvirtualhostname.unknownip.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=alllogins -staticlinks > awstats.myvirtualhostname.alllogins.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=lastlogins -staticlinks > awstats.myvirtualhostname.lastlogins.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=allrobots -staticlinks > awstats.myvirtualhostname.allrobots.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=lastrobots -staticlinks > awstats.myvirtualhostname.lastrobots.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=urldetail -staticlinks > awstats.myvirtualhostname.urldetail.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=urlentry -staticlinks > awstats.myvirtualhostname.urlentry.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=urlexit -staticlinks > awstats.myvirtualhostname.urlexit.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=browserdetail -staticlinks > awstats.myvirtualhostname.browserdetail.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=osdetail -staticlinks > awstats.myvirtualhostname.osdetail.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=unknownbrowser -staticlinks > awstats.myvirtualhostname.unknownbrowser.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=unknownos -staticlinks > awstats.myvirtualhostname.unknownos.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=refererse -staticlinks > awstats.myvirtualhostname.refererse.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=refererpages -staticlinks > awstats.myvirtualhostname.refererpages.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=keyphrases -staticlinks > awstats.myvirtualhostname.keyphrases.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=keywords -staticlinks > awstats.myvirtualhostname.keywords.html</b></i><br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=errors404 -staticlinks > awstats.myvirtualhostname.errors404.html</b></i><br>
<br>
Note (1): If you prefer, you can use <a href="awstats_tools.html#awstats_buildstaticpages">awstats_buildstaticpages</a> tool to
build all those pages in one command or to generate PDF files.<br>
<br>
Note (2): You can also add a <i>filter</i> on the following output reports:<b>urldetail, urlentry, urlexit, allhosts, refererpages</b>.<br>
<i>filter</i> can be a regexp on the full key you want awstats to present information about and you must use it after the output
parameter separated by a ":".<br>
For example, to output the urldetail report, with a filter on all pages that contains /news, you
can use the following command line:<br>
<i><b>perl awstats.pl -config=myvirtualhostname -output=urldetail:</b>/news<b> -staticlinks > awstats.myvirtualhostname.urldetailwithfilter.html</b></i><br>
<br>
Note (3): If you want to build a report for a particular month, add options <i><b>-month=MM -year=YYYY</b></i>.<br>
To build a report for full year (warning: This may use a lot of memory and CPU), add options <i><b>-month=all -year=YYYY</b></i>.<br>
<br><br>
* Second solution is to view dynamically your statistics from a browser. For this, use URL:<br>
<b><i>http://www.myserver.mydomain/awstats/awstats.pl?config=myvirtualhostname</i></b><br>
where <i>myvirtualhostname</i> is used to know which config file to use (AWStats will use awstats.<i>myvirtualhostname</i>.conf file).<br>
<br>
Note (1): All output command line options (except -staticlinks) are still available when using AWStats as a browser.<br>
Just use them as URL parameters like this example <b><i>http://www.myserver.mydomain/awstats/awstats.pl?month=MM&year=YYYY&output=unknownos</i></b><br>
<br>
Note (2): If <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a> parameter is set to 1 in AWStats config/domain file,
you will also be able to run the update process from your browser. Just click on link "Update now".<br>
<br><br>
<hr>
<script language=javascript>
var date='$Date: 2005/02/18 19:39:59 $';
document.writeln("Last revision: "+date);
</script>
</body>
</html>
|
