pvpgn-1.7.4/docs/README.storage

                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)
1	sysadm	1.1	PvPGN storage configuration README File
2			-----------------------------------------
3
4
5			1. What is this "storage" ?
6
7			"storage" is what we call in PvPGN the way to save account files data
8			(usernames, passwords, many other stuff). Thus it is a very important part of
9			PvPGN and can drastically improve speed of the server depending on the chosen
10			method. Because we wanted to be easy to add new storage types we designed a
11			modular solution, like this:
12
13			<pvpgn account code> (mostly in bnetd/account.c)
14			\|
15			\|
16			<general storage code> (mostly wrappers, in bnetd/storage.c)
17			/ \
18			/ \
19			/ \
20			<file> <sql> (bnetd/storage_filc, bnetd/storage_sql.c)
21			/\ /\
22			/ \ / \
23			/ \ / \
24			<plain> <cdb> <mysql> <pgsql>
25
26			Thus PvPGN can be compiled with support for more than one storage type but
27			(of course) at runtime it will only use one (as chosen by the server admin
28			from the configuration file).
29
30			2. First you will need to make sure your PvPGN version has support
31			compiled in for the type of storage you want to use.
32
33			2.1 file (plain and cdb)
34
35			"file" storage support means to store accounts data directly in files in either
36			plain text files or cdb files (but its easy to add any other support in the
37			future) and is compiled by default, chosen by default (with the "plain" mode)
38			in configuration file (and the oldest and most used storage type).
39
40			The only advantages of the plain files storage type are that the account files
41			beeing human readable text are easy to read/write. It has the drawback of
42			beeing the slowest one.
43
44			Starting with PvPGN version 1.6.0 (and their prereleases) we offer "cdb"
45			userfiles support. For who dont know, cdb is a constant non-relational
46			database. We included and adapted code from the tinycdb project to achieve this.
47			Because cdb doesnt have any external dependencies and is pretty stable it is
48			(as the "file" driver) compiled by default. It has the advantage of potentially
49			beeing a lot faster than "file" storage driver (I say potentially because at
50			this moment there are other things in the code which make cdb slow almost as
51			plain files, but this things will get soon fixed). It has the drawback of having
52			to use a separate tool to read/write this files outside PvPGN.
53
54			2.2 MySQL/PGSQL
55
56			For unix if you compiled your own source you need to add --with-mysql or
57			--with-pgsql to configure command line (read INSTALL.unix for general UNIX
58			installation details). Even if you give configure --with-mysql/--with-pgsql
59			parameter it will NOT compile MySQL/PGSQL support if it doesnt detect the
60			MySQL/PGSQL includes and libraries. Check the configure output where it detects
61			the mysql/pgsql paths, it should find the right locations of your MySQL/PGSQL
62			includes and libs.
63
64			If you got binary unix packages you will need to know if the packet you got
65			was compiled with MySQL/PGSQL support (ex a MySQL rpm file should have "mysql"
66			in the name of file).
67
68			A more general way to tell if you have a PvPGN with MySQL/PGSQL on Unix is to
69			use the "ldd" command on the "bnetd" file (the main PvPGN server daemon) and see
70			if the output shows usage of the SQL library (libmysqlclient for MySQL, libpq
71			for PGSQL).
72
73			If you got a binary Windows package/installer just check from where you got it
74			if it tells you if it has MySQL/PGSQL support or not.
75
76			No matter on what OS you are and how you got PvPGN, when you run PvPGN it will
77			log a message like this:
78
79			Nov 26 16:07:20 [info ] storage_init: initializing storage layer (available drivers: file, cdb, mysql)
80
81			If in the list of available drivers you see mysql/pgsql then all is fine.
82
83			3. Even if your PvPGN has support for your chosen storage driver compiled in
84			(you see it in the list of available drivers from above) you will need to
85			configure PvPGN and tell to use your chosen storage type (default PvPGN uses
86			plain files, the "file" driver).
87
88			You will need to locate the file bnetd.conf and edit it (note that in the
89			configuration files all characters that follows a first # character on a line
90			are ignored, they are comments). Find the line storage_path (which is not
91			commented) in the bnetd.conf file. Edit it to use your chosen storage type as
92			in the examples in the config file which I paste them here:
93
94			Syntax:
95			- for plain file driver:
96			storage_path = file:dir=<path_to_user_files>;clan=<path_to_clan_files>;default=/path/to/default/account
97
98			- for cdb file driver:
99			storage_path = cdb:dir=<path_to_cdb_files>;clan=<path_to_clan_files>;default=/path/to/default/account
100
101			- for sql driver:
102			storage_path = sql:variable=value;...;default=0 (0 is the default uid)
103
104			The "sql" variables can be:
105			- "mode" : tells PVPGN the sql mode you will use (mysql/pgsql/etc..)
106			- "host" : the database host
107			- "port" : the TCP/IP port if needed
108			- "socket" : the UNIX local socket if needed
109			- "name" : database name
110			- "user" : db username
111			- "pass" : db password
112
113			Examples:
114			storage_path = file:dir=/usr/local/pvpgn/var/users;clan=/usr/local/pvpgn/var/clans;default=/usr/local/pvpgn/etc/bnetd_default_user
115
116			storage_path = cdb:dir=/usr/local/pvpgn/var/userscdb;clan=/usr/local/pvpgn/var/clanscdb;default=/usr/local/pvpgn/etc/bnetd_default_user.cdb
117
118			storage_path = sql:mode=mysql;host=127.0.0.1;name=PVPGN;user=pvpgn;pass=pvpgnrocks;default=0
119
120			storage_path = sql:mode=pgsql;host=127.0.0.1;name=pvpgn;user=pvpgn;pass=pvpgnrocks;default=0
121
122
123			3. Start PvPGN. If all is well you should see a line similare to the one bellow
124			in your pvpgn logs:
125
126			Nov 26 16:07:20 [info ] storage_init: using <driver> storage driver
127
128			where <driver> is your chosen storage driver.
129
130			4. Troubleshooting:
131
132			Q: I am compiling the UNIX source and using ./configure --with-mysql but somehow
133			I dont see from configure output that it detects the MySQL libs and includes
134			A. Did you installed MySQL devel package (on some systems is separate from the
135			main MySQL package) ? locate the following files on your system
136			$ locate mysql.h
137			$ locate libmysqlclient.so
138			$ locate libmysqlclient.a
139
140			If you dont have mysql.h and one at least of the libmysqlclient.so or
141			libmysqlclient.a then you should install them (ask your local linux community
142			how).
143
144			Q: I dont see mysql in the available drivers list in the log ?
145			A: That means your PvPGN has no MySQL support compiled in. Go to step 2 of this
146			document.
147
148			Q: I see something like this in the logs "no known driver specified(sql)", what
149			does it mean ?
150			A: Just like the previous question, means your PvPGN has no MySQL support
151			compiled in. Go to step 2 of this document.
152
153			Q: I see something like this in the logs "no known driver specified(<text>)",
154			where <text> is not the driver I want, what should I do ?
155			A: Somehow you did not configured in bnetd.conf to use your chosen driver .
156			Please see step 3 of this document. Make sure to have a SINGLE UNCOMMENTED
157			storage_path line (a SINGLE line which starts with storage_path and which DOESNT
158			have a # character in front of it)
159
160			Q: I see sql in the list of available drivers but I get an error "error
161			connecting to database" in the logs.
162			A: You did not configured properly the <dbhost>, <dbname>, <dbuser>, <dbpass>
163			from step 3 of this document OR your db server has a problem (is it started ?
164			is it firewalled ? did you gave the right privileges to <dbuser> sql user ? etc)
webmaster@leafok.com	ViewVC Help
Powered by ViewVC 1.3.0-beta1