Kin icon

KIN DB 2004 Project - Usage Hints

 Project hosted at:
SourceForge.net Logo

 

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.

Index

Installing and compiling Kin

Please read INSTALL file present at distribution (package or SVN) for complete instructions. This is a (probably successful) quick guide:

  1. Get the sources. It is strongly recommended to get them from SVN (pretty simple instructions provided). If you get the package instead of SVN, uncompress it where you want to build (a temporary place is Ok, usually it is on your home directory). Use something like 
    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
  2. Go to kindb-dev directory 
    cd kindb-dev
    from where you SVN'd (for the first time) or untar'ed.
  3. There's a lot of subdirs. If you have to change standard configuration (for an instance, if you want kin to reside on a place other than /usr/local/kin), go to src directory, and edit do_config shell script. You may have to change variables like tS to set it to your CPU family (there's examples right there, if you're not sure, leave the default 'local' so it will be autodetected, provided you own an x86 or x86-64 processor -very likely-); you may want to change tB for a 64bit build, dm to enable or disable debug version, or mb to enable or disable modularized version.
    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.
  4. To install Kin node application, and basic modules, first we have to create installation directories. It is recommended to have a dedicated user and group for the kin system, so you may try 
    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.
  5. To install main application and modules, do (as dedicated kin user or your own, depending on what you choosed) 
    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.
  6. Go to configuration directory (default is /usr/local/kin/conf) and edit kin.cfg-sample to suit your needs. Then rename it as kin.cfg. Basic data to change is your user and group (if you decided to use a diferent than kin), and IP addresses of your node.
Cluster Kin installation is already done.

Generating a test database

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:

  1. Go to kindb-dev/src/tools/createdb, and then do 
    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.
  2. To compile example database, using default options, use 
    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).

Browsing database information

Once you have some data files, you can view some information inside with the viewdb tool. To compile it:

  1. Go to 
    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.
  2. To review some data file, use it like in example: 
    ./viewdb -f /usr/local/kin/data/empr.dta
    (provided you made the local version or installed)

Testing some performance figures

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:

  1. Go to 
    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).
  2. To start tests, just write 
    ./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.

Installation Troubleshooting

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):

Starting up

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.

Some make options

These are some commonly implemented make options for this project:

Return to home page from http://www.tuxgallery.org