|
|
KIN DB 2004 Project - Usage Hints |
Project hosted at: |
These are simple instructions to get a basic Kin system running. Here we cover how
to create a sample database, how to browse it, and how to launch server nodes.
This is not intended as a comprehensive manual, but as
a "quick guide" with basic common procedures and ideas.
Note on updating sources: as this project is still in an alpha stage, sometimes
a source file is removed from version to version (or renamed), and a remaining object
file in your system may lead you to get "duplicate" function definitions (as may be
present in both old and new object files). If you find any trouble with an update to
rebuild, please try make clean from src directory first.
Also sometimes a change in a header file is not detected by the rebuild system as
such, and some object files may use wrong data, leading to segmentation violations.
If that's your case, issue a make clean, then build and install again.
Please read INSTALL file present at distribution
(package or
SVN) for complete instructions. This is a (probably successful)
quick guide:
Cluster Kin installation is already done.
tar zxvf kindb-dev-0.5-alpha.tgz
(use real package file name). If your tar version can't pipe through gzip, first
gunzip kindb-dev-0.5-alpha.tgz
then
tar xvf kindb-dev-0.5-alpha.tar
cd kindb-dev
from where you SVN'd (for the first time) or untar'ed.
For most people, defaults are ok.
Go to src
cd src
directory. Here type
make
and wait. For the first time, some files may be created (like config.h), then
compilation starts.
If all goes right, make will end with no errors.
groupadd kin
and then
useradd -g kin kin
(default configuration file uses that values for user and group). For development,
usually user and group are set to your user and group, so you don't have to
sudo to root or to kin user every time you install or run it (in that case,
just remember to set User and Group in kin.cfg to the desired values).
As root, do (this is for kin based user, change to your user if that's your case):
mkdir /usr/local/kin; chown kin:kin /usr/local/kin
Then, back to your user or kin user:
make installdirs
to get all the tree created. As this is alpha, you may have to use this again in
some future, so some new directory gets created whenever it is the case after a
sources update.
make install
Tools have to be compiled and eventually installed specifically from their own
directories (see below), if you need them. They need main Kin library to be
installed first (as we did a few lines ago), when you choosed modularized version,
else, at least, kinlib directory has to been made before.
With the distribution there are a few database source files, to allow a very basic example
database to be created. These are simple xml files, you need createdb tool to create
real database files from them. So:
make
to compile it. As dedicated user kin or your own (depends on what you choosed), do
make install
to install it with the kin application, or
make link
to compile but not install, but just leave it on source directory.
make check
(provided you generated the local version or installed).
If you changed standard locations, try this:
./createdb -c../../examples/kin.cfg-sample -f../../examples/record_def_base.txt -d../../examples
changing -c parameter to your kin.cfg file (once it is edited to reflect your paths).
Once you have some data files, you can view some information inside with the viewdb
tool. To compile it:
kindb-dev/src/tools/viewdb
and then do
make
to compile it. As dedicated user kin or your own, do
make install
to install it with the kin application, or make link
to compile a
local version which is not installed but just left on source directory.
./viewdb -f /usr/local/kin/data/empr.dta
(provided you made the local version or installed)
There's a tool to check some routines throughput on your machine. It uses some of
the system's rutines, so it may give an approximated figure of the final speed
for some usual operations. Checks are about RAM+cache+CPU speed, hard disk
transfer rates (currently disabled), and some other special tests (cache only, etc.)
To compile it:
kindb-dev/src/tools/stress
and then do
make
to compile it. As dedicated user kin or your own, do
make install
to install it with the kin application, or make link
to compile a
local version which is not installed but just left
on source directory (I recomend the former, as you seldom use this tool again).
./stress
(provided you make the local version or installed), and wait for the results.
Of course, it is better to use this tool on an idle system, to get better
values, but feel free to test it on the real environment you're system will
work on.
If you found some trouble trying to compile Kin, please refer first to the README file
that comes with your distribution or better, from SVN. If anything fails, please
provide me some information as what you did and some piece of the result on your
console, or at least, the message you get, posting at project's
bugtrack
(thank you).
You may also try some of the scripts I used to clean the source tree, instead of reinstalling,
but these are deprecated nowadays (just try make clean instead):
Kin system is based on a cluster. Thus, it works over the concept of a node. To start a Kin
cluster, you have to start up several nodes, to create the "working force".
Do not desperate if you have a lonely computer! A cluster may be "created" on a single machine :-)
First step is to configure Kin. Go to:
cd /usr/local/kin/conf
(provided you installed on the standard place). Then simply move kin.cfg-sample to
kin.cfg (only for the first time), and edit it with your favourite text editor.
Things you may want to change are Log Quota if you want to let bigger or smaller log
files, and Debug Level (be careful to set a big value, tons of logs may happen!).
Debug Filter lets you to selectively filter what gets logged (not the level, which
is done by the former command). I do not recomend you to set bit 2 or even 3, as these
modules generate lots of information (every task switch may be logged), if you're not debugging
those parts of the system.
If you selected some sort of user and/or group, please set it at User and Group
(for a debugging system, I usually set them to my user instead of the default kin:kin)
What you really want to change are the connection parameters: cluster doesn't work without
network addresses! It should work with the default local host addresses, if you're on a single
machine cluster, but broadcasts often don't work locally, and the cluster is never build as it
starts looking for other nodes by broadcasting... so please set those addresses to your ethernet
local address. I do not recommend you to change port numbers (yet).
Once configured, you can begin to start nodes. These are initial instructions to do so,
please refer to this page to get some other fine details.
To start, first, go to (for easier typing):
cd /usr/local/kin
Then, we first start a Query Manager module, and (for an instace) a Backup Manager (Storage):
bin/kinode -mQB
As QM won't find another module, it will take some 10 seconds to get you again on the shell
prompt. After that, you have a first QM running, and a BM starting up (hope you made a
"make check" into src/tools/createdb to create and install a sample database). You can see how
it is doing by having a look at the basic logs:
tail logs/info.log
tail logs/debug.log
tail logs/warn.log
tail logs/fatal.log
Try something like a ps af to see if they are still running, you'll see something like:
7308 pts/4 S 0:00 kinode bM guardian
7309 pts/4 S 0:00 \_ kinode bM process
7289 pts/4 S 0:00 kinode qM guardian
7290 pts/4 S 0:00 \_ kinode qM process
Then, you may want to have an object item manager:
bin/kinode -mI
Have a look at the logs (basically, info.log and debug.log) to see what's on.
After having the inner cluster nodes on, you may start the last one: a CAP (Client
Access Point), usually known as CM (Client Manager):
bin/kinode -mC
Now you have a complete Kin cluster up and running (if nothing failed).
When you want to stop the system, you can kill node processes in any order, or just issue
killall kinode
Remember that guardian processes don't kill the real process if they die, so if you
want to be selective, you have to kill the process processes, guardians will die
by themselves when their process was killed by a TERM signal.
Log fields are pretty self explaining, for an instance, on the following log line:
20050821-211047.513516 (7309) B kinstorLoadAll: passed integrity check (1 data blocks)
First comes date in ISO format (YYYYMMDD), then time (HHMMSS) with microsecond resolution.
Value in parentheses is process ID (useful when you have a lot of processes loggin into the same log)
followed by a letter identifying the kind of module (capital for processes, lowercase for
guardians). Usually, logging process writes function name (in this example is kinstorLoadAll) where
the log took place (this is not enforced, but very useful for debugging), and whatever it wanted to
record.
These are some commonly implemented make options for this project:
make
This simply checks and builds dependancies, and object files ("compiles")
make link
Links object files to build an executable or library (where applicable)
make install
Installs linked executables or libraries. First links them if no object files are available.
make debug
This is now deprecated, just do a make link to get executables for testing.
make clean
Deletes all the compilation results (dependancies, object files, and executables/libraries)
make installdirs
Creates the installation dirs (if not already created and have enough privileges)
| Return to home page |
|