        	PvPGN storage configuration README File
	       -----------------------------------------


1. What is this "storage" ?

    "storage" is what we call in PvPGN the way to save account files data
(usernames, passwords, many other stuff). Thus it is a very important part of
PvPGN and can drastically improve speed of the server depending on the chosen 
method. Because we wanted to be easy to add new storage types we designed a 
modular solution, like this:

                   <pvpgn account code>  (mostly in bnetd/account.c)
		            |
		            |
		  <general storage code> (mostly wrappers, in bnetd/storage.c)
		       /         \
		      /           \
		     /             \
		<file>            <sql> (bnetd/storage_filc, bnetd/storage_sql.c)
		 /\                 /\
		/  \		   /  \
	       /    \		  /    \
	    <plain> <cdb>     <mysql> <pgsql>

Thus PvPGN can be compiled with support for more than one storage type but 
(of course) at runtime it will only use one (as chosen by the server admin 
from the configuration file).

2. First you will need to make sure your PvPGN version has support 
compiled in for the type of storage you want to use.

2.1 file (plain and cdb)

"file" storage support means to store accounts data directly in files in either 
plain text files or cdb files (but its easy to add any other support in the 
future) and is compiled by default, chosen by default (with the "plain" mode) 
in configuration file (and the oldest and most used storage type). 

The only advantages of the plain files storage type are that the account files 
beeing human readable text are easy to read/write. It has the drawback of 
beeing the slowest one.

Starting with PvPGN version 1.6.0 (and their prereleases) we offer "cdb" 
userfiles support. For who dont know, cdb is a constant non-relational 
database. We included and adapted code from the tinycdb project to achieve this.
Because cdb doesnt have any external dependencies and is pretty stable it is 
(as the "file" driver) compiled by default. It has the advantage of potentially 
beeing a lot faster than "file" storage driver (I say potentially because at 
this moment there are other things in the code which make cdb slow almost as 
plain files, but this things will get soon fixed). It has the drawback of having 
to use a separate tool to read/write this files outside PvPGN.

2.2 MySQL/PGSQL

For unix if you compiled your own source you need to add --with-mysql or 
--with-pgsql to configure command line (read INSTALL.unix for general UNIX 
installation details). Even if you give configure --with-mysql/--with-pgsql 
parameter it will NOT compile MySQL/PGSQL support if it doesnt detect the 
MySQL/PGSQL includes and libraries. Check the configure output where it detects 
the mysql/pgsql paths, it should find the right locations of your MySQL/PGSQL 
includes and libs.

If you got binary unix packages you will need to know if the packet you got 
was compiled with MySQL/PGSQL support (ex a MySQL rpm file should have "mysql" 
in the name of file). 

A more general way to tell if you have a PvPGN with MySQL/PGSQL on Unix is to 
use the "ldd" command on the "bnetd" file (the main PvPGN server daemon) and see 
if the output shows usage of the SQL library (libmysqlclient for MySQL, libpq 
for PGSQL).

If you got a binary Windows package/installer just check from where you got it 
if it tells you if it has MySQL/PGSQL support or not.

No matter on what OS you are and how you got PvPGN, when you run PvPGN it will 
log a message like this:

Nov 26 16:07:20 [info ] storage_init: initializing storage layer (available drivers: file, cdb, mysql)

If in the list of available drivers you see mysql/pgsql then all is fine.

3. Even if your PvPGN has support for your chosen storage driver compiled in 
(you see it in the list of available drivers from above) you will need to 
configure PvPGN and tell to use your chosen storage type (default PvPGN uses 
plain files, the "file" driver).

You will need to locate the file bnetd.conf and edit it (note that in the 
configuration files all characters that follows a first # character on a line 
are ignored, they are comments). Find the line storage_path (which is not 
commented) in the bnetd.conf file. Edit it to use your chosen storage type as 
in the examples in the config file which I paste them here:

Syntax:
- for plain file driver:
storage_path = file:dir=<path_to_user_files>;clan=<path_to_clan_files>;default=/path/to/default/account

- for cdb file driver:
storage_path = cdb:dir=<path_to_cdb_files>;clan=<path_to_clan_files>;default=/path/to/default/account

- for sql driver:
storage_path = sql:variable=value;...;default=0 (0 is the default uid)

 The "sql" variables can be:
  - "mode" : tells PVPGN the sql mode you will use (mysql/pgsql/etc..)
  - "host" : the database host
  - "port" : the TCP/IP port if needed
  - "socket" : the UNIX local socket if needed
  - "name" : database name
  - "user" : db username
  - "pass" : db password

Examples:
storage_path = file:dir=/usr/local/pvpgn/var/users;clan=/usr/local/pvpgn/var/clans;default=/usr/local/pvpgn/etc/bnetd_default_user

storage_path = cdb:dir=/usr/local/pvpgn/var/userscdb;clan=/usr/local/pvpgn/var/clanscdb;default=/usr/local/pvpgn/etc/bnetd_default_user.cdb

storage_path = sql:mode=mysql;host=127.0.0.1;name=PVPGN;user=pvpgn;pass=pvpgnrocks;default=0

storage_path = sql:mode=pgsql;host=127.0.0.1;name=pvpgn;user=pvpgn;pass=pvpgnrocks;default=0


3. Start PvPGN. If all is well you should see a line similare to the one bellow 
in your pvpgn logs:

Nov 26 16:07:20 [info ] storage_init: using <driver> storage driver

where <driver> is your chosen storage driver.

4. Troubleshooting:

Q: I am compiling the UNIX source and using ./configure --with-mysql but somehow 
I dont see from configure output that it detects the MySQL libs and includes
A. Did you installed MySQL devel package (on some systems is separate from the 
main MySQL package) ? locate the following files on your system
$ locate mysql.h
$ locate libmysqlclient.so
$ locate libmysqlclient.a

If you dont have mysql.h and one at least of the libmysqlclient.so or 
libmysqlclient.a then you should install them (ask your local linux community 
how).

Q: I dont see mysql in the available drivers list in the log ?
A: That means your PvPGN has no MySQL support compiled in. Go to step 2 of this 
document.

Q: I see something like this in the logs "no known driver specified(sql)", what 
does it mean ?
A: Just like the previous question, means your PvPGN has no MySQL support 
compiled in. Go to step 2 of this document.

Q: I see something like this in the logs "no known driver specified(<text>)", 
where <text> is not the driver I want, what should I do ?
A: Somehow you did not configured in bnetd.conf to use your chosen driver . 
Please see step 3 of this document. Make sure to have a SINGLE UNCOMMENTED 
storage_path line (a SINGLE line which starts with storage_path and which DOESNT 
have a # character in front of it)

Q: I see sql in the list of available drivers but I get an error "error 
connecting to database" in the logs.
A: You did not configured properly the <dbhost>, <dbname>, <dbuser>, <dbpass> 
from step 3 of this document OR your db server has a problem (is it started ? 
is it firewalled ? did you gave the right privileges to <dbuser> sql user ? etc)
