###############################################################################
#                                                                             #
# admin-faq.txt - Admininstrator's Frequently Asked Questions for HalfStats   #
#               - Copyright Zach Karpinski                                    #
#               - Distributed under the GPL terms - see the docs for info     #
#               - http://www.halfstats.com                                    #
#                                                                             #
###############################################################################
# CVS $Id: admin-faq.txt,v 1.7 2001/03/14 03:27:34 smccrory Exp $
###############################################################################

I.	What is halfStats?
II.	What do I need to run halfStats?
III.	How much memory does halfStats need?
IV.	How much CPU does halfStats need?
V.	Where do I put the halfStats files?
VI.	How can I reset my data file?
VII.	How can I totally clear my data file and log files?
VIII.	Why do I get warnings?  
IX.	Why wont my listen server logs work?
X.	How can I delete logs, reset stats, etc?
XI. 	How can I make halfStats NOT save its data? (reparse)

I.
	halfStats is a log analzyer for half-life servers.  It takes
log files generated by a linux or windows server and turns them into
pretty stats that can be put onto your web server.  It works for 
internet or LAN servers and has a variety of options you can use to
customize your statistics page.

II.
	halfStats requires a running half-life server.  It does not
work on normal clients unless you run a listen server (bad).  It
its preferred you use a dedicated server.  
    
	halfStats also requires perl.  Perl comes free with most 
versions of unix (FreeBSD and Linux are the only two you should
be interested in running a dedicated halflife server on).  For
windows servers, you must download perl from www.activestate.com.

	If you want your stats to show up on the world wide web, 
you'll need to have a web server installed.  Any webserver will do
as halfStats only generates static HTML files.  It has been tested
on Apache, IIS and Personal Web Server. 

III.
	This depends.  How busy is your server?  How long do you want
to save stats before resetting them?  Weekly? Monthly? Yearly? (lol)
I run a 10 player gasworks server that is relatively busy.  After 3139
connections, 1818 unique players and 41,160 deaths in one month's worth
of logs, halfStats took up to 64mb of my machine's ram.  Keep that in
mind.  If you are worried about halfStats sucking up too much ram,
reset your logs more frequently.  I've tried to clear out memory usage 
best as possible during runtime, but to track the things I do, the 
program really needs its fair share of memory.

IV.
	To a certain extent, you can control this.  In the default
configuration file, you'll notice two variables towards the end.
sleep_interval and sleep_time.  These two variables control how
halfStats attempts to slow itself down and not use as much CPU.
sleep_interval tells halfStats "after you've done something 
this many times, stop doing anything for <sleep_time>"  The lower
the sleep_interval, the more halfStats pauses.  The higher
the sleep_time, the longer halfStats waits when it does pause.
Generally, the less logs you have, setting sleep_interval slows
the program down efficiently.  If you more than a couple MBytes
of logs, you'll want to set sleep_time higher because sleep interval
becomes less effective.

V.
	halfStats needs to know about three different directories.  The
directory it runs from, the directory your half-life logs are in and the
directory it should write the html to.  You only need to copy files into
or make directories in two of them, the program directory and the
html directory.
	halfStats should not be run from anywhere in your web server.  It 
usually should go in its own directory.  If you are in linux, try 
/usr/local/halfStats.  If you are in windows try c:\halfStats.  When you 
put your config files in your web directories, you let people know a bit 
about your computer (file locations and such) and its the best rule to 
not do that.  The halfStats program directory needs to have one directory 
in it.  This directory is "data".  You'll have to make this by hand.  Also 
in the program directory, you should have the halfStats.pl file, the 
Player.pm file, a .cfg file, and the documentation for this program.
	The html directory should contain all of your .css files, the
image directory, which should contain 3 subdirectories: maps, help, weapons.
The images directory should by default come with these files: awards.gif,
banner.jpg, green.jpg, help.gif, index.gif, players.gif, red.jpg, server.gif,
yellow.jpg.

VI.
	Run halfStats like usual, but after your config file, supply the 
"reset" command.  

	In linux this is: ./halfStats.pl config.cfg reset
	In windows it is: perl halfStats.pl config.cfg reset

	This command resets the data file but leaves the log files in
place in your logdir.

VII.
	The only way you can have halfStats totally start fresh by
deleting your logs and resetting the stats is to supply the "reset clean"
command, much like in section V.  Keep in mind, once you do this, you 
lose the data file and all log files it has parsed.  
     
        halfStats will not create backups for you.  It is up to you to 
decide how you will backup your previous stats.  It is recommended you copy 
the html content to a new folder.

VIII.
	Warnings are normal during this stage of development.  halfStats 1.0 
is not totally done.  At present we are gradually coming from pre-beta 
into the beta stage.  I initally did not plan to release any code at this
point, but so many people were interested in something.  I have warnings 
in there to show when your logs aren't 100% perfect.  Not much you can 
do about it.  Its not a fatal error, which is why halfStats keeps running.  
Any time halfStats finishes competely without a fatal error, things are OK.  
	
IX.
	halfStats will only work on listen servers by store_method=name
The support for listen servers isnt as high as for dedicated, as listen
servers are only used for small lan games.  This version adds support
for name based stats and the other two options are not available to 
listen servers. 

X.

To just run the stats you would use this command:
perl halfStats.pl config.cfg 

To reset the stats and keep all log files, run this command:
perl halfStats.pl config.cfg reset 

To keep present stats and just delete already parsed logs, run this:
perl halfStats.pl config.cfg clean 

To reset stats and then delete the logs, run this command:
perl halfStats.pl config.cfg reset clean 

If you ever want to forcefully delete every logfile from your logs
directory, supply the "wipe" command after clean, like so:

perl halfStats.pl config.cfg clean wipe
or
perl halfStats.pl config.cfg reset clean wipe

Instead of just deleting the logs it knows about, halfStats will 
just delete EVERY log in that directory (be careful!!)

XI.
halfStats now has the option to not save its data.  If you have a VERY
busy server saving data may be more trouble than it is worth towards the
end of the month.  If you wish to have halfStats run and not save data
use this command:

perl halfStats.pl config.cfg nosave