~ubuntu-branches/ubuntu/maverick/awstats/maverick

If not, you can install a recent Perl interpreter from <a href="http://www.activestate.com/ActivePerl/">ActivePerl</a> (Win32) or <a href="http://www.perl.com/pub/language/info/software.html">Perl.com</a> (Unix/Linux/Other).

-->

<a name="INSTALL"><H2 style="font: 22px arial,helvetica,sanserif color: #606060">Step 1 : Install and Setup with configure.pl</H2></a>

<a name="INSTALLAPACHE">A) With Apache or compatible server (on Unix/Linux, Windows, MacOS...)</a>

* Step 1-1:

(if you use a package provided with a Linux distribution or Windows installer, this might be

already done, however it is recommanded to do it)

After downloading and running the AWStats package, you must run the configure.pl script.

You will find it in the tools directory (If using the windows installer, the script is

automatically launched):

perl configure.pl

This is what the script do for you (you can do all of this manually if you prefer):

A) configure.pl check your apache web server log format configuration.

If you use a common log, configure will

suggest to change it 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).

If you answer yes, configure will modify your httpd.conf to change all the

following directives (See your apache manual for more information):

CustomLog /yourlogpath/yourlogfile common

into

CustomLog /yourlogpath/yourlogfile combined

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:

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)"

B) configure.pl will add, if not already done, the following directives to your Apache config 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 install 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.

#

Options None

AllowOverride None

Order allow,deny

Allow from all

100

</Directory>

101

102

103

104

105

C) configure.pl restart Apache to apply the changes made in A and B.

106

107

108

D) configure.pl will ask you a name for a config profile. Enter here the name of your

109

web server or any analysis profile name, for example myvirtualhostname.

110

So configure.pl will copy the file awstats.model.conf file into a new file

111

named awstats.myvirtualhostname.conf.

112

You can use the value of your choice instead of "myvirtualhostname". This new file must

113

be stored in

114

- For Unix/Linux users: /etc/awstats.

115

- For Windows and other OS: Same directory than awstats.pl (so cgi-bin).

116

117

118

E) configure.pl ends.

119

120

121

122

* Step 1-2:

123

Once a config file has been automatically created (by configure.pl or you package

124

installer), it's important to edit it manually and change the "MAIN PARAMETERS"

125

to match all your needs:

126

127

This is for example the parameters you should check seriously :

128

- Check/Change <a href="awstats_config.html#LogFile">LogFile</a> value with full path of your web server log file (You

129

can also use a relative path from your awstats.pl directory).

130

- Check/Change <a href="awstats_config.html#LogType">LogType</a> value with "W" for analyzing

131

web server log files, "S" for a streaming server log file, "M" for mail log files, "F" for ftp log files.

132

- Check if <a href="awstats_config.html#LogFormat">LogFormat</a> has the value "1" (it means "NCSA apache combined/ELF/XLF log format")

133

or use a personalized log format if you don't use combined log format.

134

- Check/Change <a href="awstats_config.html#DirIcons">DirIcons</a> parameter to reflect relative URL of awstats icon directory.

135

- Edit <a href="awstats_config.html#SiteDomain">SiteDomain</a> parameter with the main domain name or the intranet

136

web server name used to reach the web site to analyze (Example: www.mydomain.com). If you have several

137

possible name for same site, add list in <a href="awstats_config.html#HostAlias">HostAlias</a> parameter.

138

- You can change other parameters if you want.

139

140

141

* Step 1-3:

142

(if Perl interpreter is correctly setup, this step is not required)

143

If necessary, edit the first (top-most) line of awstats.pl file that is

144

#!/usr/bin/perl

145

to reflect the path were your Perl interpreter is installed. Default value works for most of Unix OS, but it also might be

146

#!/usr/local/bin/perl

147

With Apache for Windows and ActivePerl interpreter, it might be

148

#!c:/program files/activeperl/bin/perl

149

150

151

Step 1 (Install and Setup) is finished. You can jump to the <a href="#BUILD_UPDATE">Build/Update Statistics</a> section.

152

153

154

155

156

<a name="INSTALLIIS">B) With IIS server</a>

157

158

* Step 1-1:

159

160

Configure IIS to log in "Extended W3C log format" (You can still use

161

your own log format but setup is easier if made like suggested). So, for

162

this, start the IIS Snap-in, select the web site and look at its

163

Properties. Choose W3C Extended Log Format, then Properties, then the

164

Tab Extended Properties and uncheck everything under Extended Properties.

165

Once they are all unchecked, check all following fields:

166

167

date

168

time

169

c-ip

170

cs-username

171

cs-method

172

cs-uri-stem

173

cs-uri-query

174

sc-status

175

sc-bytes

176

cs-version

177

cs(User-Agent)

178

cs(Referer)

179

180

To be sure the log format change is effective, you must stop IIS, remove all old log files, restart IIS and go to

181

your homepage. This is an example of records you should get then in the new log file:

182

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

183

184

185

* Step 1-2:

186

187

Copy the contents of the provided cgi-bin folder from your hard drive to your server's cgi-bin

188

directory (this includes awstats.pl, awstats.model.conf, and the lang, lib and plugins sub-directories).

189

190

191

* Step 1-3:

192

193

Move AWStats icon sub-directories and its content into a directory readable by your

194

web server, for example C:\yourwwwroot\icon.

195

196

197

* Step 1-4:

198

199

Create a config file by copying awstats.model.conf file into a new file named awstats.myvirtualhostname.conf.

200

You can use the value of your choice instead of "myvirtualhostname". This new file must be stored in

201

- Same directory than awstats.pl (so cgi-bin)

202

203

204

* Step 1-5:

205

206

Edit this new config file with your own setup :

207

- Change <a href="awstats_config.html#LogFile">LogFile</a> value with full path of your web server log file (You

208

can also use a relative path from your awstats.pl directory).

209

- Change <a href="awstats_config.html#LogType">LogType</a> value with "W" for analyzing

210

web server log files, "S" for a streaming server log file, "M" for mail log files, "F" for ftp log files, "O" otherwise.

211

- Change <a href="awstats_config.html#LogFormat">LogFormat</a> to a value with same field's name defined in step 1-1:

212

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)"

213

- Change <a href="awstats_config.html#DirIcons">DirIcons</a> parameter to reflect relative path of icon directory.

214

- Edit <a href="awstats_config.html#SiteDomain">SiteDomain</a> parameter with the main domain name or the intranet

215

web server name used to reach the web site to analyze (Example: www.mydomain.com).

216

- 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.

217

- You can change other parameters if you want.

218

219

Step 1 (Install and Setup) is finished. You can jump to the <a href="#BUILD_UPDATE">Build/Update Statistics</a> section.

220

221

222

223

224

C) With other web servers

225

226

Setup process is similar to setup for Apache or IIS.

227

Use <a href="awstats_config.html#LogFormat">LogFormat</a> to value "3" if you have WebStar native log format, use

228

a personalized <a href="awstats_config.html#LogFormat">LogFormat</a> if your log format is other.

229

230

231

232

233

234

<a name="BUILD_UPDATE"><H2 style="font: 22px arial,helvetica,sanserif color: #606060">Step 2 : Build/Update Statistics</H2></a>

235

236

237

* Step 2-1:

238

239

The first analyze/update of statistics should be made the first time manually from the command line since first time,

240

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

241

AWStats update command line is:

242

awstats.pl -config=myvirtualhostname -update

243

244

AWStats will read the config file awstats.myvirtualhostname.conf (or if not found, awstats.conf)

245

and create/update its database with all summary information issued from analyzed log file.

246

AWStats database files are saved in directory defined by <a href="awstats_config.html#DirData">DirData</a> parameter in config file.

247

When update is finished, you should get on screen a result like this:

248

249

Update for config "/etc/awstats/awstats.myvirtualhostname.conf"

250

With data in log file "/pathtoyourlog/yourlog.log"...

251

Phase 1 : First bypass old records, searching new record...

252

Searching new records from beginning of log file...

253

Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...

254

Jumped lines in file: 0

255

Parsed lines in file: 225730

256

Found 122 dropped records,

257

Found 87 corrupted records,

258

Found 0 old records,

259

Found 225521 new qualifed records.

260

261

Dropped records are records discarded because they were not user HTTP request or requests were not qualified

262

by AWStats filters (See <a href="awstats_config.html#SkipHosts">SkipHosts</a>, <a href="awstats_config.html#SkipUserAgents">SkipUserAgents</a>,

263

<a href="awstats_config.html#SkipFiles">SkipFiles</a>, <a href="awstats_config.html#OnlyHosts">OnlyHosts</a>,

264

<a href="awstats_config.html#OnlyUserAgents">OnlyUserAgents</a> and <a href="awstats_config.html#OnlyFiles">OnlyFiles</a> parameters).

265

If you want to see which lines were dropped, you can add the -showdropped option on command line.

266

Corrupted records are records that does not match log format defined by "LogFormat" parameter in AWStats config/domain file.

267

With all webservers you can experience a little bit corrupted records (<5%) even when everythings work correctly.

268

This can be the result of several reasons: Web server internal bugs, bad requests made by buggy browsers, web server brutal stop...

269

If all your lines are corrupted and <a href="awstats_config.html#LogFormat">LogFormat</a> parameter in AWStats config/domain file is

270

correct, it may be the log format setup in your web server that is wrong. Don't forget that

271

your <a href="awstats_config.html#OnlyFiles">LogFormat</a> parameter in AWStats config/domain file MUST match

272

the log file format you analyze.

273

If you want to see which lines are corrupted, you can add the -showcorrupted option on command line.

274

Old records are simply records that were already processed by a previous update process.

275

You understood that it's not necessary to purge your log file after each update process even

276

if it's highly recommended to do it as often as possible.

277

New records are records in your log file that were successfully used to build/update statistics.

278

279

Note : A log analysis process is slow (one second for each 4500 lines of your

280

logfile with Athlon 1Ghz, plus DNS resolution time for each different IP

281

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).

282

See <a href="awstats_benchmark.html">Benchmark page</a> for more accurate information.

283

284

285

* Step 2-2:

286

287

AWStats statistics can be updated from a browser, to provide real-time statistics, by clicking

288

the "Update now" link that appears when AWStats is used as a CGI (Next section '<a href="#READ">Read Statistics</a>

289

dynamically' gives you URL to use for that).

290

Warning !!

291

To enable this link, your parameter <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a>

292

must be set to 1 in your config file (Link is not enabled by default).

293

294

Then, using on-line update does not prevent you from running the update process from a scheduler

295

frequently (command is same than update of first process).

296

For this, you have two choices:

297

- Include the update command in your logrotate process. See <a href="awstats_faq.html#ROTATE">FAQ-COM120</a> for this.

298

- Or add instructions in your crontab (Unix/Linux) or your task scheduler (for

299

Windows), to launch frequently the Awstats update process. See <a href="awstats_faq.html#CRONTAB">FAQ-COM130</a> for this.

300

See AWStats <a href="awstats_benchmark.html">Benchmark page</a> for recommanded update/logrotate frequency.

301

302

303

304

<a name="READ"><H2 style="font: 22px arial,helvetica,sanserif color: #606060">Step 3 : Read Statistics</H2></a>

305

306

307

To see results of analyze, you have several solutions depending on your <a href="awstats_security.html">security policy</a>.

308

309

310

* First solution is to build the main reports, in a static HTML page, from the command line,

311

like this (jump to second solution if you have ONLY CGI access):

312

perl awstats.pl -config=myvirtualhostname -output -staticlinks > awstats.myvirtualhostname.html

313

314

You can use all other output options (each of them give you another report).

315

This is how to use all other possible output options(1) :

316

perl awstats.pl -config=myvirtualhostname -output=alldomains -staticlinks > awstats.myvirtualhostname.allhosts.html

317

perl awstats.pl -config=myvirtualhostname -output=allhosts -staticlinks > awstats.myvirtualhostname.allhosts.html

318

perl awstats.pl -config=myvirtualhostname -output=lasthosts -staticlinks > awstats.myvirtualhostname.lasthosts.html

319

perl awstats.pl -config=myvirtualhostname -output=unknownip -staticlinks > awstats.myvirtualhostname.unknownip.html

320

perl awstats.pl -config=myvirtualhostname -output=alllogins -staticlinks > awstats.myvirtualhostname.alllogins.html

321

perl awstats.pl -config=myvirtualhostname -output=lastlogins -staticlinks > awstats.myvirtualhostname.lastlogins.html

322

perl awstats.pl -config=myvirtualhostname -output=allrobots -staticlinks > awstats.myvirtualhostname.allrobots.html

323

perl awstats.pl -config=myvirtualhostname -output=lastrobots -staticlinks > awstats.myvirtualhostname.lastrobots.html

324

perl awstats.pl -config=myvirtualhostname -output=urldetail -staticlinks > awstats.myvirtualhostname.urldetail.html

325

perl awstats.pl -config=myvirtualhostname -output=urlentry -staticlinks > awstats.myvirtualhostname.urlentry.html

326

perl awstats.pl -config=myvirtualhostname -output=urlexit -staticlinks > awstats.myvirtualhostname.urlexit.html

327

perl awstats.pl -config=myvirtualhostname -output=browserdetail -staticlinks > awstats.myvirtualhostname.browserdetail.html

328

perl awstats.pl -config=myvirtualhostname -output=osdetail -staticlinks > awstats.myvirtualhostname.osdetail.html

329

perl awstats.pl -config=myvirtualhostname -output=unknownbrowsers -staticlinks > awstats.myvirtualhostname.unknownbrowsers.html

330

perl awstats.pl -config=myvirtualhostname -output=unknownos -staticlinks > awstats.myvirtualhostname.unknownos.html

331

perl awstats.pl -config=myvirtualhostname -output=refererse -staticlinks > awstats.myvirtualhostname.refererse.html

332

perl awstats.pl -config=myvirtualhostname -output=refererpages -staticlinks > awstats.myvirtualhostname.refererpages.html

333

perl awstats.pl -config=myvirtualhostname -output=keyphrases -staticlinks > awstats.myvirtualhostname.keyphrases.html

334

perl awstats.pl -config=myvirtualhostname -output=keywords -staticlinks > awstats.myvirtualhostname.keywords.html

335

perl awstats.pl -config=myvirtualhostname -output=errors404 -staticlinks > awstats.myvirtualhostname.errors404.html

336

337

Note (1): If you prefer, you can use <a href="awstats_tools.html#awstats_buildstaticpages">awstats_buildstaticpages</a> tool to

338

build all those pages in one command or to generate PDF files.

339

340

Note (2): You can also add a filter on the following output reports:urldetail, urlentry, urlexit, allhosts, refererpages.

341

filter can be a regexp on the full key you want awstats to present information about and you must use it after the output

342

parameter separated by a ":".

343

For example, to output the urldetail report, with a filter on all pages that contains /news, you

344

can use the following command line:

345

perl awstats.pl -config=myvirtualhostname -output=urldetail:/news -staticlinks > awstats.myvirtualhostname.urldetailwithfilter.html

346

347

Note (3): If you want to build a report for a particular month, add options -month=MM -year=YYYY.

348

To build a report for full year (warning: This may use a lot of memory and CPU), add options -month=all -year=YYYY.

349

350

351

* Second solution is to view dynamically your statistics from a browser. For this, use URL:

352

http://www.myserver.mydomain/cgi-bin/awstats.pl?config=myvirtualhostname

353

where myvirtualhostname is used to know which config file to use (AWStats will use awstats.myvirtualhostname.conf file).

354

355

Note (1): All output command line options (except -staticlinks) are still available when using AWStats as a browser.

356

Just use them as URL parameters like this example http://www.myserver.mydomain/cgi-bin/awstats.pl?month=MM&year=YYYY&output=unknownos

357

358

Note (2): If <a href="awstats_config.html#AllowToUpdateStatsFromBrowser">AllowToUpdateStatsFromBrowser</a> parameter is set to 1 in AWStats config/domain file,

359

you will also be able to run the update process from your browser. Just click on link "Update now".

360

361

362

<hr>

363

364

365

var date='$Date: 2004/01/13 13:32:33 $';

366

document.writeln("Last revision: "+date);

367

</script>

368

369

</body>

370

</html>

Older »