!! This document is outdated !! 
    Information inside may be correct, slightly wrong, or exactly opposite how it currently works.
    New documentation to be written and released when cPGS is no longer BETA, expected in 2012 for version 1.0
 !! This document is outdated !! 

###################################################################
Basic Requirements for cpgsd
###################################################################
gcc
perl 5+
openssl (including headers, usually in a separate package called something like openssl-devel or ssl-dev)
Net::SSLeay perl module 
IO::Socket::SSL perl module
IO::Pty perl module

Versions 0.4.0 and later, cPGS uses a server/client mechanism. This allows cPGS
to control gameservers running on remote machines (without cpanel installed)
so as to elliminate any overhead of running cPanel itself on the same server
the gameservers will run on. Every game of every user has a unique configuration
for the remote server. Note that if you wish, you may run the cpgsd daemon on the
local machine alongside cPanel, in which case you will use the loopback IP 127.0.0.1
for all user's connections.

Things you need to do:

1) Run the `install` script provided in the cPGS gzipped tarball on the cPanel server(s).

2) On any remote gameserver machines, run the cpgsd_install script. If only using the cPanel machine,
   run this script on there as well as the `install` script.

3) On any remote gameserver machines, set up the config file (/var/cpanel/cpgs/cpgsd.cfg) (this applies to the cPanel machine if only one server is used)
    
	Values are:
		allowedips:	comma delimited list of IP addresses that are allowed to talk to the daemon server (default: 127.0.0.1)
		logfile:	path to the log for cPGSD (default: /var/log/cpgsd.log)
		sslpem:		the SSL PEM file to use. This can be generated by the cpgsd_install script (default: /var/cpanel/cpgs.pem)
		pkgdir: 	location of the gameserver package files (default: /home/gameservers/)
		secret: 	the shared secret key/pass you will use between servers. Be sure this value is the same on any servers involved in cPGS
		qstat:		path to the qstat binary for getting stats on some games (default: /usr/local/bin/qstat)
		root:		the base directory for cpgsd files (default: /var/cpanel/)
		port:		port that cpgsd listens on. do not change if at all possible. (default: 2092)

4) Start up the cpgsd.pl daemon on any gameserver boxes. For example:

	/var/cpanel/cpgsd.pl
	
	This will log data to /var/log/cpgsd.log by default . You can change the log file by editing /var/cpanel/cpgs/cpgsd.cfg and setting the logfile= variable.

5) Log into WHM on the cPanel machine and begin configuring the users you want to allow to run gameservers.

        The "core config" option is where you will enter the IP address of the remote gameserver box for that user and the
	particular gameserver you select. A user can have an UT2004 server running on 1.2.3.4, while having a HLDS server running
	on 5.6.7.8, for example.
 
	IPs (that the user's server will be allowed to bind to on the gameserver machine) and Ports for each user/game should be
	self explanitory.

	Note that from 0.6.0+, it ispossible to run multiple types of the same type of game under one account. For example, "userabc" can run a CS:S server
	on 1.2.3.4:27015 , another CS:S server on 1.2.3.4:27025, a CS 1.6 server on 1.2.3.4:27018 and an ArmyOps server on 3.4.5.6:7617 .

6) Log into the user's cPanel account and configure the gameserver, start it up and, assuming all is well, play :)

*notes*
--> if you do not have the perl module IO::Socket::SSL , you will need to install it on all servers involved ( perl -MCPAN -e'install IO::Socket::SSL' )
--> if you do not have `wget` installed on the remote cpgsd.pl servers, you will need to in order to download and install gameserver packages from WHM

###################################################################
Username Mapping
###################################################################

This is a very basic feature that allows "UserA" on the cPanel server to control gameservers
on remote servers as whatever user you designate. For example, "drdoom" on the cPanel server
could control CS:S on 1.2.3.4 as the user "malcom", Call of Duty on 1.2.3.4 as "mickey", and
Savage on 5.6.7.8 as "janky". Remote usernames may be configured in WHM with each user/game.


###################################################################
Creating a custom game package
###################################################################
The steps to making a package are as follows..
In this example we have a working server in /home/user/cod14/ .
Use the following commands to package it, inject the meta data and move it to
the right place:

>> change into the directory the server is in:
# cd /home/user/cod14/

>> create a gzipped tarball of the contents from the current directory to
somewhere outside the current directory:
# tar czvf ../cod14.cpgs ./

>> go into the directory where the newly created package file is:
# cd ../

>> inject the metadata into the newly created file so cPGS can handle it.
The arguments are the new server package file, -p means we are going to pack a
new file, "cod" is the internal name for CoD servers (cod2 for CoD2,
cod4 for CoD4, etc), 1.4 is the version, and the last bit is just a short
description of the package:
# /var/cpanel/cpgs/cpgs_pkg cod14.cpgs -p "cod" "1.4" "Custom package"

>> This will take some time as the cpgs_pkg script searches through the
file and appends the meta data. After it is done, move it into the directory
with the rest of your packages:
# mv cod14.cpgs /home/gameservers/

After that you should be able to select the cod14.cpgs in WHM for the
user/game/install to use when installing.

###################################################################
Automatic restart on reboot
###################################################################

When a client starts any of the gameservers, it adds the server name into
/var/cpanel/gameserv.restart and the command line used to
/var/cpanel/gameserv_saved/$user_$game_$installnum

The actual restart script, /usr/local/cpanel/bin/cpgs_chk , reads through all
the users with gameservers installed and reads the ".restart" file.
If the restart script can find the command line it needs to restart the gameserver,
it will drop privileges to the user and try to start it. Currently the script does
no checking to see if the server is running already or not, so it is advised
not to run it unless it's directly after a reboot.

Currently this script is not added to the init system since it has not been thoroughly tested.
It is suggested you add it to the rc.local, local.start, etc file (depends on the distro) to have
it run after the server reboots if manually running it is not feasible.

###################################################################
Unique command lines per user/game
###################################################################

If the admin has declared a custom command line (looks for existence of 
/var/cpanel/gameserv_saved/$user_$game_$installnum_useuniq), then client's starting their
game server will always use the custom command line, regardless of what the
client changes it to. This is mainly useful to allow special mods that are
not yet supported by cPGS directly and should only be used by those who
understand what they are doing.

###################################################################
Post install script
###################################################################
If /var/cpanel/cpgs_postinstall exists, it will be called upon finishing the installation of a game with the following arguments:

/var/cpanel/cpgs_postinstall $user $query $srvn $maxc $defip $lowport

$user is the system username of the game being installed for
$query is the game server "shorthand" name
$srvn is the server number
 --> these 3 variables together are what is seen in /var/cpanel/gameserv.cfg and other configs in the form of user_game_# 
$maxc is the max clients/players allowed for the server
$defip is the first IP address allowed for the server
$lowport is the first port allowed for the server

The cpgs_postinstall script can be written in your language of choice.
Be sure to do error checking, the first 3 arguments are the only consistantly reliable ones at this time.


###################################################################

From within WHM you should find at the very bottom of the menu on the left a link to the
gameserver control where you can control how many players and which type of servers are allowed. 

Clients can admin the servers they have access to from the GameServers link in the "x", "x2" and "gs" themes.
The "gs" theme only provides cPGS support for strictly gameserver-only accounts.

https://server.com:2083/

For all questions, suggestions, and bug reports, please email darren@cpanel.net

###################################################################
Brief description of core cPGS config files
###################################################################

/var/cpanel/gameserv_saved/user_game_servernum

This file is automatically created by cpgsd when a game is started to record
the last used startup line for the restart script called from cron, so it can
start the server just the same as it was before in case it crashes or across a
reboot. You shouldn't need to 

/var/cpanel/gameserv_saved/user_game_servernum_unique

This is kind of like the user_gametype_servernum file, in that it holds a full
custom command line to be used in starting/stopping the server, but it
supercedes any config options normally passed on the command line. It is most
useful when you need ultimate control over the command line. Note that this is
(normally) set in WHM in the "Manage Game" option of the advanced
config section, and must be specifically enabled to be used by cpgsd. Whether
or not it is used is determined by the existence of an empty file,
/var/cpanel/gameserv_saved/user_gametype_servernum_useuniq .

/var/cpanel/gameserv_ips.cfg

This file holds config information about which IPs the users are allowed to
choose from when configuring their server from cPanel.

/var/cpanel/gameserv_ports.cfg

The same as the IPs file, but for ports. Some servers need as many as 3 unique
ports, so be sure to allow enough.

/var/cpanel/gameserv_rem.cfg

This holds the config info for each user_game_num in where the frontend should
connect to the backend. For accounts where the games are actually run on the
same server cPanel is installed on, use 127.0.0.1 . For remote servers, use any
reachable IP on it that cPGSD is bound to.

/var/cpanel/gameserv_restart

This just holds a list of user_game_num instances that are supposed to be
restarted, across reboots and after crashes.

/var/cpanel/gameserv.cfg 

This file holds a list of all the users_games_servernums configured for cPGS and 
various info about them, such as remote user name, max clients/slots, the server
package file to use, whether the gameserver is allowed to be mangaged by the user
or not, a list of allowed mods for the server and command line append options, etc.