I've taken the liberty of making an install manual for those of you who wish to run a stats server under linux.

Currently, there's already an install manual present for linux, though this install manual is mainly written for Cpanel (webserver hosters often use cpanel as manage tool).

This installer is written on the debian lenny system I'm running my servers on.
Although most software and commands you use are the same, some may vary depending on what distribution OS you use.

Please note you need at least some understanding on how to use basic commands on linux. Thought most commands and things you'll have to do to install HLStatsX on a linux machine are explained, I will not go in-dept to the linux commands used!

All that is left now is to wish you luck :)

If there are still questions regarding this manual (stuff isn't working like it should), please use the hlxcommunity forums for questions. You can also send me a pm on the forum there.

– Rawh out

This manual has been made with debian in mind. It is however possible to use the manual for operating systems like fedora and centos as well. Although restarting services is done in a different way, installing software is almost the same as in debian.

With debian you use “aptitude” (or apt-get). On fedora and CentOS you do this with “yum”. So simply replace all aptitude commands with yum and it should install fine¹⁾!

• Linux software:
  • linux web server (apache2 will do nicely)
  • linux sql server (this install manual covers mysql5)
  • linux php5, php5-cli, php5-mysql, libapache2-mod-php5
  • OPTIONAL: phpmyadmin (for webbased sql management)
• MySQL stuff:
  • Database (for this manual we use the database “manual_hlx”.)
  • User with write access to the database (for this manual we use the user “manual”.)
• Shell stuff:
  • Login user and password
  • Putty (windows ssh program to login on a server)
• Stats software:
  • Latest hlstatsx (can be obtained from their website.)
• Perl modules:
  • DBD::mysql
  • Geo::IP::PurePerl

Notice:
Please IGNORE these steps and continue to 4. HlstatsX setup if you are not installing HLStatsX on a new machine.
This also applies to those of you who rent webspace, as the following software will most likely already be present on the machine you are installing HLStatsX on!!

With debian there's this fantastic installation tool called “aptitude” which you can use to download, compile and install linux packages. Sometimes the system can ask you for stuff (when upgrading or defining things it needs your help with). I use aptitude to install all the packages. Below I will give a small how to on the usage, thought it mostly speaks for itself.

IMPORTANT:

1. Before we are going to install any packages it's useful to update the current package list, you do this as the user “root” by typing “aptitude update”. You'll see loads of data scrolling by and after a time your normal shell should popup again.
2. Aptitude has to be run as “root”. Root is the superuser on the system. You can compare it to the Administrator on a windows machine.

For the webserver on linux I tend to use apache2. Apache2 can be downloaded by typing:

aptitude install apache2

The system will ask you several things which I can't answer for you. Just sit back, read the text and decide on your own.
After installing apache2, it will have created the directory /etc/apache2/ in which configuration files and directories have been made. The website and all it's files have been put on /var/www/ (which should be empty now :)).

In order to use apache2 for hlstatsx you are going to have to enable a few modules first.
The next kind of handlings might be a bit to much if you haven't used linux before. If you have any problems using these, please consult a friend with more knowledge about linux or ask for some help on the forum! A reference to this manual would be extremely helpful for those who wish to help you!

Apache2 can load different modules to enable userdirs. A userdir is a directory that is linked on apache for all users on a linux machine. If your user (called “manual” in this case) creates a directory called “public_html” (/home/manual/public_html/) and puts files in that directory, those files should be hosted on the internet that way. In order to use this we now have to set up the module:

Login as root on the linux machine.

Go to the apache2 configuration directory (cd /etc/apache2/).
Go to the apache2 mods-enabled directory (cd mods-enabled/).
Type "ln -s ../mods-available/userdir* ." to link the userdir module files.
Now restart apache2 by typing "/etc/init.d/apache2 restart".

If all goes well and apache does not show any error, the public_html directory created above should now have it's files hosted on the internet. To test this lets go to the manual public_html directory (cd /home/manual/public_html) and create an empty file (touch filename). Now open up any website browser and go to your machine (http://my.computers.internet.address/~manual/). You can now see the file “filename” in your browser which means apache2 runs and the userdir module is loaded!

Another module to install with apache2 is php. Php is a scripting language originally designed for producing dynamic web pages ²⁾. HLStatsX uses php code to create the statspages you are browsing.

This module does not come with apache2 itself and has to be installed seperatly by typing:

aptitude install php5 php5-mysql libapache2-mod-php5

The above will install php5, php5-cli (a commandline package for php5), php5-mysql (the ability for php5 to talk with mysql databases) and libapache2-mod-php5 (the library file to communicate between php and apache2).

Aptitude should restart apache2 after it installed the above programs. Should this not be the case you can manually restart apache2 by typing: (as root)

/etc/init.d/apache2 restart

Now in order to test if apache2 and php are running we are going to create a test file. We will name this testfile “phpinfo.php”.
Below will be a short list of commands and instruction you can follow to create this file. There are ofcourse other ways of completing this part, but since we are installing things on linux I'm going to handle it via an editor which is available in linux by default:

Go to your public_html dir of the user (cd /home/manual/public_html/).
Start the editor with the filename already present (vi phpinfo.php).
Hit the "insert" button on your keyboard (it should show INSERT in white on the bottem left side of the screen).
Type the following:
<? php
phpinfo();
?>
Hit this "esc" key on your keyboard (the white INSERT should now vanish).
Hit the ":" key (shift-;) on your keyboard followed by the letters "wq" and hit enter.
It should show you the file has been saved.

Next we are going to use a webbrowser to look at the file. Open your browser and browse to the machine. You can do this by either using the machine's ip address or hostname (http://<ip address/hostname>/~manual/phpinfo.php). If all goes well you should see a load of information on your screen. If this is the case then you've installed php correctly and can move on to the next part. If by any chance there are errors and you are unsure of how to continue, feel free to visit the forum and present your problem!

One of the requirements for HLStatsX is a SQL server. Though there are several sql servers I will only be handling mysql in this manual. Again, with debian lenny and the fantastic use of aptitude, we are going to let that program do the installing of the package:

aptitude install mysql5-server

aptitude will most likely present you with a screen that tells you it will need other packages as well to get the mysql5-server to be installed. Don't worry about that part, just accept the result by pressing “Y” followed by a slam on the enter key :)

Now that mysql has been setup we will have to setup usernames and passwords. First we are going to set the root password for mysql. To do this type the following in a shell:

mysqladmin -u root password NEWPASSWORD
Where NEWPASSWORD would be the password you'd like to set.

Next in line we are going to create a user and a database. While there are almost endless possibilities to do this, I myself tend to use the commandline a lot (like the command mysqladmin shown above). For those of you who wish to do this yourself I'd advise phpmyadmin. Phpmyadmin is a tool that allows you to connect to a mysql server with a webbrowser and set it all up that way. You can install phpmyadmin by using aptitude again (as root ofc!)

aptitude install phpmyadmin

After installing it this way we're going to reset the apache2 server, just to be sure.

/etc/init.d/apache2 restart

Next in line would be browsing to phpmyadmin. To your convenience phpmyadmin installs itself on the machine by using it's name as a directory to access. Just browse towards it using http://<ip address/hostname>/phpmyadmin. A screen should popup that looks something like the image to the right.

Next we are going to login to phpmyadmin using the username 'root' and the password which you choose. I was planning on just linking a few manuals regarding phpmyadmin but as my google skills seem to fail me I decided to create a (small) howto / manual regarding phpmyadmin here.

Phpmyadmin has it's own manual which can be found here.

HlstatsX is divided into a few parts. All parts are equally important to HlstatsX as a whole and will be explained below.

First we are going to create a few directories.

install/
stats/
stats/public_html/
stats/scripts/

The install directory will keep the install file(s). You should use 'wget' to get the latest version of HlstatsX (website) and put that file in the 'install' directory.
The stats/public_html/ directory will be filled later on in this manual. Be sure to make the directory accessible via http though. You could do this by installing apache2 (with the manual above) and put a symlink to the 'stats/public_html/' directory in '/var/www/'.

cd /var/www/
ln -s /home/<user>/stats/public_html stats

(Now your stats/public_html dir will be accessible via http://IP/stats/)

The stats/scripts/ directory will be filled later as well.

Second I'm going to create a user & database which HlstatsX will use.
No idea how to do this? Look at 3.4 phpmyadmin for details!
For the purpose of this manual I will use the following:

Username: hlxuser
Password: hlxpassword
Database: hlstatsx

Go to the 'install' directory. Extract the current release file (name: HLXCommunityEditionX.X.XFULL.zip) with 'unzip' or something simular. This should create quite a few files and directories.

Go the the directory with the name 'web'. Use an editor to edit 'config.php'. Fill in the following fields:

// DB_NAME - The name of the database
define("DB_NAME", "hlstatsx");

// DB_USER - The username to connect to the database as
define("DB_USER", "hlxuser");

// DB_PASS - The password for DB_USER
define("DB_PASS", "hlxpassword");

// DB_ADDR - The address of the database server, in host:port format.
//           (You might also try setting this to e.g. ":/tmp/mysql.sock" to
//           use a Unix domain socket, if your mysqld is on the same box as
//           your web server.)
define("DB_ADDR", "localhost");

Exit and save the file. Now copy over all the content of the 'install/web/' to your 'stats/public_html/' directory.

cp -R /home/<user>/install/web/* /home/<user>/stats/public_html/

The website part is done… for now!

Go to the 'install/sql/' directory. Use the following command line to import the sql tables and config into your sql database:

mysql -uhlxuser -phlxpassword hlstatsx < install.sql

A few seconds / minutes will pass and the SQL database will be filled with the required tables. In addition to doing the import via the command line, you can also use phpmyadmin for this.

Note: This is one of the core parts of Hlstatsx as it uses perl to open a listenserver to which the logs will be send. Be sure to understand what you are doing here as most of the problems of not getting it to work occur here!

Go to the 'install/scripts/' directory. Open 'hlstats.conf' with an editor and fill in the next information:

# DBHost - Database server "address" or "address:port". Address can be an IP or
#          a hostname. The default MySQL port is 3306 (tcp).
DBHost "localhost"

# DBUsername - User to connect to the database as.
DBUsername "hlxuser"

# DBPassword - Password for the database user.
DBPassword "hlxpassword"

# DBName - Name of the database to use.
DBName "hlstatsx"

# DBLowPriority - Use INSERT DELAYED and DELETE LOW_PRIORITY for some queries.
#                 This can give better performance, but may make statistics less
#                 "real time". 1=on 0=off
DBLowPriority 1


##
## UDP Socket Settings (should match "logaddress ip port" on the game servers)
##

# BindIP - IP address to bind to (leave empty to use all interfaces).
BindIP ""

# Port - Port to listen on for log data from the game servers.
Port 27500

Save and exit the file.

Note: In 6 of the 10 cases leaving 'BindIp' empty will be fine. Several (if not all these days) users use a router to divide their internet connection to more pc's. Those users who wish to setup a HlstatsX server on their own pc (behind the router) will need to use their outside ipaddress (look it up via http://www.whatismyip.com)! After this the user should check their firewall on the pc if it blocks Port 27500, last one should check the router if the port 27500 is forwarded from the router to the pc that's hosting the website part of HlstatsX!

After editting we need to make the following files executable:

hlstats-awards.pl
hlstats.pl
hlstats-resolve.pl
run_hlstats

Via Cpanel & Cronjob
We're going to use the cronjob option within Cpanel to get the script to run. In order to do this we need to set the starting time together with a command.
Lets take the current time, add 2 minutes and add that to the time part of a cronjob.
Example: It's 9:55 am now. We want the script to run at 9:57. Lets add the cronjob line: '57 09 * * * cd /path/to/scripts/ && /usr/bin/perl run_hlstats.pl start'.
After the above rule is executed, there should be a .log file in the perl dir that allows you to see if there were any/no errors with starting hlstats.
(To stop hlstats for now, add the same line as we did before, with the 2 minute rule (10:05 now, +2 means 10:07, thus: '07 10 * * * cd /path/to/scripts/ && /usr/bin/perl run_hlstats.pl stop'))

Via ssh console
This can be done in 2 steps:

1. Edit each file with your editor. Change the first line '#!/path/to/perl' (usually something like /usr/bin/perl).
2. chmod the files with the 'x' flag ('chmod +x <filename>'

To test if this works, run './hlstats.pl'. You can use ctrl+c to exit the process. Next look for the log file, any error you've seen in the hlstats screen will also be in the log file.

For both cases: If there are any errors in the log file and it's not working, yet you have no idea what it means. Post it at the hlstatsx forums! Someone is bound to help you there!!

Go to the 'install/' directory. In there there will be 2 plugin directories.

My own servers are using sourcemod so I would naturally do:

1. Change to the 'sourcemod' dir
2. Copy over the 'scripting' directory to '/home/<user>/servers/hl2mp/FortressForever/addons/sourcemod/'
3. Change to the 'scripting/' directory and use 'compile.sh' to compile my own .smx file.
   
4. After which I will copy the .smx file from '/home/<user>/servers/hl2mp/FortressForever/addons/sourcemod/scripting/compiled/' to '/home/<user>/servers/hl2mp/FortressForever/addons/sourcemod/plugins/'
   
5. Now all that remains is (re)start the server and the plugin will be loaded and installed :)
   

Next in line would be enabling and using all we've done above and wrap it up into running stats:

1. Website:
   1. Go to the website URL (http://IP/stats).
   2. Login as admin on the website (login url on bottom of page)
      • Username: admin
      • Password: 123456
   3. Go to 'Admin Users'.
      • Make yourself a new user.
      • Give it admin privileges.
      • Delete the old admin user.
   4. Go to 'HLstatsX:CE Settings' and edit the settings to your liking
   5. Go to 'Games' and select the game you want the stats page to facilitate. You can do this by setting the dropdown menu for that particular game to 'show' and all other games to hide.
   6. Setting the above to the game you wish to host will unlock the 'Game Settings' for that game. Click on this and then click on 'Quick-Add Server'. Fill in all those required fields and hit the save button. This server will now be displayed on the main page as well.
2. Perl Important!
   1. Starting the Perl Daemon
      1. Go to the '/home/<user>/stats/scripts/' directory.
      2. Start up the server by typing: './hlstats.pl'. Some important know-hows:
         • The above will start the program in the opened ssh session you are currently using. If you close this windows, so will the hlstats daemon and thus it won't log anything anymore.
         • You are able to also launch hlstats.pl into the background by typing './hlstats.pl &'. It will still show you all the data at the start but will move to the background after that. Disadvantage to this method is that you can't see what is going on on the console of it now.
         • You can use the 'run_hlstats' script to use the second option. Just type the command: './run_hlstats start' to start the hlstats daemon in the background. The 'run_hlstats' script has several benefits instead of just using the above command. Just type './run_hlstats' without any comment and you'll see it's options.
      3. The Daemon is running now.
   2. Keeping it running
      • One of the most fantastic parts of linux is the crontab. The crontab can be compared to windows it's “scheduled tasks”.
      • We are going to use the crontab to setup daily refreshes regarding the hlstats-awards.
      • We are also going to use the crontab to check if the server is still running every 5 minutes.
      1. Crontab
         • Edit the crontab by typing 'crontab -e'.
         • I can go quite into-dept on how crontab works, which I won't. Please have a look at this site if you wish to know a lot more about crontab. Below I'm simply going to show what lines should be added for hlstats.
         • Every 5 minute checks: '*/5 * * * * cd /home/<user>stats/scripts/ && ./run_hlstats start'
         • Stats update each day at 23:55: '55 23 * * * cd /home/<user>/stats/perl && ./hlstats-awards.pl'
         • Updates the resolve database (ip –> address –> domain/host –> country) at 00:15: '15 00 * * * cd /home/<user>/stats/perl && ./hlstats-awards.pl'
         • Exit the crontab by typing: ':wq' followed by an enter.
3. Gameserver
   1. Logaddress.
      • In order for the gameserver to send it's logs to the statsserver you need to enable logging and add a logaddress.
      • This is usually done in the config file of the server (server.cfg) by adding 'log on' and 'logaddress_add ip:port'.
      • Since our statsserver is hosted on the machine with IP <ip> and port 27500, we add the following lines to our server.cfg file: 'log on' and 'logaddress_add ip:27500'.
   2. Rcon & Plugin
      • The HlstatsX daemon communicates with the gameserver via rcon. Next to that it uses the hlstatsx plugin “talk” to the users via specific commands.
      • Make sure that the rcon_password set on the server is the same password as used in the 'Game Settings' on the website.
      • To check if the plugin is correctly loaded (with sourcemod) type 'sm plugins list' and look for hlstatsx in the list.
   3. Now join the server, wait for some players and see if the spam will start ingame :)

Note: For more information regarding ingame commands, please type 'help' in to the main chat window (defaultkey “y”) and read the windows contents!

This section will be filled over time with problems and their answers to it.

The vast majority of the time when the daemon isn't receiving the logs, the problem is one of the following:

1. The server is not logging
   • Either add “log on” to the server.cfg (or autoexec.cfg) file or type “log on” in console!
2. The logaddress on the game server is incorrect
   • Double check your logaddress_add line and make sure there are no logaddress_del or logaddress_delall lines in any configs
3. There's an outgoing firewall blocking the game server sending
4. There's in incoming firewall blocking the daemon receiving
5. The daemon is listening on the wrong ip address
   • Look in 'hlstats.conf' and set BindIP to the ip it should listen on!

Pfff, that was quite a job getting putting this manual together!

First I'd like to thank the following people:

1. Psychonic - For making such a damn great program and for taking up all my constant whining on steamfriends, like “Can you check it now?”, “How does it look so far?”, “Have you read it yet?”, “How about now?”, “When is the next version due?” and “I don't mean to be annoying… but can you check the manual?”.
   
2. Bully - For being there most of the time during the day and read this manual.
   
3. Bonzo - For giving the commands that should work under redhat/fedora and CentOS.
   

Again, if there are any questions and/or comments regarding this manual, please post them on the hlxcommunity forum (or send me a forum pm there)!

Cheers for reading :)

– Rawh