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