NAME

the Karma System - Advanced Bulletin Board Software.


- introduction -- +

the Karma System is the single most simplistically complex piece of bulletin board software ever known to humble man.

the power that lies within allows the Operator to not only customize, but to completely and utterly alter the appearance and functionality that is presented to the User. this is because, simply put, Karma is not so much ``Open Source'' as she is ``Liquid Source''. what this means for you is that your bulletin board can become an extension of your body and mind. such as is the case with say, a weapon of mass destruction. the only difference being that, with Karma, there is love to be had.

and remember, what comes around goes around;

the Karma System is good for your soul.

..


- overview -- +

karma is based on many unix priciples. however, karma duplicates and extends on several services in order to avoid 'taking over' the host system. put more simply; Karma won't grow roots.

the following is a loose list of features for this release:

{ general features }

+ terminal independence
this means that karma can be accessed with any terminal which has an entry in your system's termcap/terminfo database, it also adds a great deal of flexibility to the bbs.

+ portability
this is one of the best aspects of karma. it should run on any system that perl and its supporting modules can. ( the second karma alpha pod is running on an IBM risc/6000 under AIX )

+ distribution
karma's architecture allows for the massive distribution of various services. this makes available a world of scalability, load balancing and the like.

systems sharing the same bbs are called 'shadows'; logging into any one shadow is indistinguishable from logging into the 'real thing'. think of it as a mirror.

systems belonging to the karma support network are called pods.

individual bbs entities are just called bbs's ;-) bbs's may share certain aspects, such as sig's (special interest groups), file bases, and teleconferences.

+ multiple simultaneous sessions
each user can log in to an Operator controlled number of nodes simultaneously. this gives karma bbs's the same functionality as Hotline type services. in that, a user can read news, download files, and chat all at the same time.

+ extensibility
from its inception karma has been designed to be the ultimate incarnation of bbs flexibility. this means that every aspect and behavior of the bbs can be changed, and in most cases in real time. any changes beyond that will take effect the next time a user logs on. karma will continue to grow as does perl (its host language ).

+ security
karma NEVER RUNS AS ROOT, and is therefore quite secure. there are also many security provisions to prevent malicious users from damaging the bbs.

karma is very secure!

+ open structure
karma keeps all information in clean, plane, simple text files. making it possible to write utilities easily in any language.

{ release specific features }

+ very few restrictions on the size/amount of anything
this includes, number of users, post, and files.

+ advanced arrow-key menus
personally, I can't stand the things, but some people on the team felt they should be included. we think they're the best implementation out there!!

+ tabbed input forms
karma provides many options for getting textual input from its users. some worthy of mention include:
+ single line, scrolling
+ single line, password masking
+ multi line, h scrolling and v scrolling
+ single character

these types may be combined in any order and contained within a Form.

+ display objects/widgets
karma also provides a growing collection of textual output objects, currently the most common include:
+ scrolling area
+ progress indicator
+ nntp and spool based messaging
nntp is the default message base type, we suggest that all boards run a news daemon and configure karma to access that. this daemon can then be connected to the hosts of other karma systems, thereby exploiting the power of Usenet for network dissemination. there are also many packages out there for bridging nntp and fidonet, if ftn's are your fancy.

optionally, an operator can choose the spool type of message base, in which the correspondence will only be stored locally ( but still accessible to shadows ).

+ inter bbs teleconferencing!!!
I told the kdc team that I wouldn't let karma out the door without a fully networked chat system. the reason being, that we need to make more of an effort to brink the shrinking bbs community closer together, yet still remain as individuals.

see the ktalkd ( karma talk daemon ) documentation for more specific information.

+ internet email
karma has the ability to provide both incoming and outgoing email access it's users ( using the associated unix tools )

+ unix overlay file bases
the way karma stores uploads is intended to make for the seamless integration with other file based services such as ftp / sftp / napster / whatnot. ( file bases may also be explicitly shared by multiple bbs's, and are implicitly shared by all shadows. )

+ announcements / wall / one-liners
all of the above at basically the same thing, and karma has them! quit nice, we think.

+ group and personal journals / diaries
we are developers, and we use karma. hence we also use karma to develop karma! as well as all of our other projects.

in karma's journal system users in the same group can read each others public diary entries. this is perfect for personal notes, changelog entries, and various things of that nature. in practice, I think we communicate more using this feature than with the post office!

+ statistical graphs.
one of my favorite memories of being a Sysop back in the old days was digging through all the user information an building charts based on the statistics. that is still something I enjoy, so karma comes with lots of tools to automate the process.

+ the power of perl!!!
karma is hosted by one of the most popular text manipulation languages to date. having perl at your hand can condense even the most complex operations into just a few lines of code.

most bbs software ends up creating its own little scripting / layout language anyway, so we at the kdc decided to leave the language development up to Larry Wall and his army of perl lovers, letting us focus on what's important; making an awesome bulletin board.

keep in mind, we've seen the other bbs software out there that is written in perl. although good intentioned, the authors of this software don't seem to grasp the entire scope of what a bbs should provide, and how to apply their knowledge of perl/cgi programming to the bbs paradigm. we hope that they will be inspired by our work just as much as we have been by theirs, and maybe even jump in the pool and contribute to the karma cause!

..


- theory -- +

when data is compressed, when ideas are crunched and forced into the time it takes to download 25 lines over a 300bps modem,

the mind is reborn.

suddenly, but not surprisingly, these thoughts take on new shape; a depth that could not be reached any other way.

 "into electric attitude, I extrude my world to you".
 as this dim, green text dances its way across my terminal,
 I read it and think.. think of all the things that could
 be so sweet, if only they had the chance.

this world inside the machine seems so perfect; so perfect because it is whatever you wish it to be. sometimes it can even be everything.

most of us grew up in this world. friends, enemies, lovers; they all shared some strange attraction to the unknown, to the dial tone. to the machine that waits on the other end, the one that would do anything to please you, to keep you coming back. it is our wish to share this, forever. in this ever changing world, one thing should stay the same.

there should always be a place for us.

..


- membership -- +

we urge one and all Karma operators to join the mailing list. there are always updates, tips, tricks, and bits of vital information within. you can either join privately, or add the list to your Karma archives.

In fact, if you love Karma as much as we do, why not become a developer?


--- slogans -+


while reading please keep in mind that these were intended
to amuse.
the Karma System - We do IPC through telekinesis.
You knew it would catch up with you someday - the Karma System
Can a BBS be written entirely in perl? Almost! - the Karma System
the Karma System - The only known BBS to support hazeltine braindamage!
No! No! No!!!!! Oh my holy God! - the Karma System
This is so cool! What does it do exactly? - the Karma System
the Karma System - Giving fingers something to do since 18.. uhh, 2001.


--- graphics display -+

as of today there are currently three methods available to store and display text graphics in the Karma System. these are as follows:

raw ansi
this has been a giant 'no no' ever since karma was converted over to a full curses interface.

chtype arrays
these are basically identicle to curses dumps, only without the window size information. although a common method for using character graphics in C curses programs, they really have no place in perl.

c strings
the 'c' here stands for color, not to be confused with the C programming language. c strings are Karma's way of using colors while maintaining terminal independence (for details see 'c strings explained'). the main advantage of this form is the fact that it doesn't have to be contained within a file; you can use c strings from within a menu or user profile without all of the un necessary overhead. c strings, just as everything else, do have their drawbacks. the only one that comes to mind is the extra processing involved in the decoding.


--- c strings explained -+

as much as I hated to have to include another terminal emulation in the system, it was necessary. curses, you see, lacks any way of expressing rendition changes within a string.. sure you can do it statement by statement, but that doesn't fit with Karma's style of interface. to be honest, nothing about curses fits with Karma.. there comes a time, however, when we must all make our sacrifices.

c strings are very simple; there are very few escape codes. they all begin with a caret (^), witch is then followed by either:

{y,x}
move cursor.

fb
alter foreground / background color.

B|b
enable / disable bold attribute.

A|a
enable / disable alternate character set.

example
^{,}^60^Bhello world.

the breakdown:

first the cursor is homed with the statement '^{,}', as
you can see the zeros may be omitted to save space.
bear in mind, that in curses (hence karma) all cursor/
screen locations begin at zero.
next, the foreground color is set to 6 (cyan) and the
background to 0 (black). currently these colors may
only be changed in tandem. finally, with the last
escape code '^B' we set the BOLD attribute so that
our cyan text will appear quite bright and offensive.

the direct interface to the c string interpretor is through a function by the name of printc(). just as many other curses calls, printc() takes a variable list of arguments:

        void printc(*WINDOW win, int y, int x, char* a)
        void printc(int y, int x, char* a)
        void printc(*WINDOW win, char* a)
        void printc(char* a)

a common idiom you will notice in the Karma base code is printc used in place of printf:

        printc $window, sprintf(FORMAT, LIST);

I found this to be such a convenient solution as to negate the need for any other type of work-around.


--- data structures -+

-+ nodes
the node tree (karma/node) is the location that karma stores all of a users temporal (ie. per session) data.

here you will find items such as the users current status, host name of the machine an pid of the karma process owning the node.

small temp files may be kept in the node tree (karma/node/num/tmp), as it is cleared upon every new instance of that node. Keep in mind, however, that on system utilizing karma's Shadow feature this may generate excess NFS traffic; in such cases it is better to use a unique file in /tmp instead.

-+ users
user information is a vital part of any bbs, and in our opinion, karma excels at providing the resources necessary to proper user management.

you'll notice that unlike most other UNIX(tm) based bbs software, the Karma System doesn't store user information in /etc/passwd. there are many reasons behind this, the foremost being Karma's modular nature; it would be far too invasive to interfere with the name space that may belong to other services you provide (ie, ftp, shell, pop). this can be especially usefull if you to not own the machine that your board is hosted on. combine that with the fact that Karma doesn't run as the super- user, and you've got yourself a win/win situation.

this is a key factor in the power of Karma.

[details]

Hidden users have a unix_name() that begins with '.' (period); once a user is hidden by the Operator she will no longer be listed in public settings (such as the node list).

[the following figure is a tree describing karmas user base layout.]

 karma/users/ -               - user base
                a user/       - exalted being, may be hidden by prepending a period (.)
                        info  - user information
                        rc    - initial script for user
                        mail/ - location of personal messages


--- in the future -+

As some of you close to Karma's development may well know, the project was never intended to be so complex. The goal was to create a lightweight yet capable bbs server in Perl. Well, it turns out that perl has some fundamental problems that make this somewhat difficult. All of this is supposed to change with the release of Perl 6, a completely new language from the people that brought us Perl. This, however, doesn't really simplify things for us now.

Perl 5's shortcomings aren't the only thing at fault, though. The inclusion of Curses in the karma structure was a real turning point in her development. I'm not sure if it was good or bad. Sure, it gives us some flexibility with terminal types, but we pay a large price in speed and simplicity. In the future karma might do away with screen handling libraries all together, or at least make one optional. I think 50% of our work goes tword working around little bugs in terminfo descriptions and curses routines. Sometimes it really doesn't seem worth all of the trouble. There is a bright side, though; Karma has the most advanced terminal support of any bbs software I know.

One might ask ``why not just rewrite the whole thing in C?''.

The answer to that is quite simple: ``That would defeat the entire point!!!!''

There is some talk among the ranks of using Ruby for future version, which does have many of the things that we've been waiting on in Perl 6.