BK - Bummskraut Chat/Messaging Client Framework
4.01
Bummskraut is a chat (and messaging in general) client framework written in Perl. It has a distributed architecture and is based on AnyEvent::MP a message passing toolkit for Perl.
Its main user interface is a simple ncurses client. There is a core entity, which can run inside the client itself or as separate node in an AnyEvent::MP network.
The chat protocols (like IRC, XMPP) or utility backends that handle other (not purely chat) protocols (like Twitter or RSS/Atom feed reading) are implemented as backends who connect to the core. These backends can also run inside the same process where the node runs, or in their own processes, possibly distributed over multiple hosts.
It is assumed that all protocol backends are installed and used, even though they are optional.
Here are some general features:
You can write your own protocol backends and clients using well documented APIs (see BK::Client and BK::Backend).
The rest of the code usually has comments to allow contributors to find their way into the code a bit more quickly.
(But note that there is still some amount of Perl experience demanded from the developers who want to mess with the internals.)
Like explained above in the DESCRIPTION you can run all parts of the chat client framework on different hosts. You could for instance dedicate one host to run the core of Bummskraut, which logs and keeps track of the state of backends and clients. And then dedicate another host to run your protocol backends (where the actual IRC connections will originate from).
You can run clients on multiple hosts at the same time, for instance, if you have a laptop and a workstation, just run clients on both, to have an eye on your chat sessions all the time.
How you actually set everything up is mostly left to you. The documentation
only provides some hints and examples how to setup everything using
AnyEvent::MP's aemp command.
All communication between the core and the protocol backends and clients is done using messages. Using message passing paradigms Bummskraut can provide a distributed and reliable architecture.
It will also provide you with all the features AnyEvent::MP has, for instance the possibility of encrypting all traffic with TLS if you want to run it over the internet.
Status: Basic features done.
Status: Basic implementation done.
Status: Done, needs testing.
Status: TODO, needs reimplementation.
The (n)curses user interface has the following features:
If you use a terminal that can display the fonts. (I can highly recommend: rxvt-unicode)
The client can intentionally only display one buffer (e.g., IRC channel or XMPP chat session) at a time. If you need more windows, you can just start more clients.
If you stop all clients the backend will still receive messages and you can resume chatting anytime later by restarting your clients.
You can write your own user interfaces, for instance one in GTK, there are (nearly) no assumptions made that the curses client is used.
One could also write a bot that poses as a frontend.
You will need a more or less recent Perl, version 5.10 is highly recommended.
Next you need to get the BK Perl module, which comes also with the frontend script. You need to install it usually like any Perl module, either via CPAN or manually:
~# tar -xvzf BK-4.1.tar.gz ~# cd BK-4.1 ~/BK-4.1# perl Makefile.PL ~/BK-4.1# make install
In the perl Makefile.PL step the script will give you a list
of missing dependencies, which need to be installed (usually the same
way) before you have to retry the perl Makefile.PL step.
If you are using CPAN the missing dependencies should be installed automatically.
If you installed the BK module then you need to check which backends you want to use and install their dependencies:
Required dependencies are:
Required dependencies are:
From the 'connection_ref' branch in my git repository:
~# git clone http://git.ta-sa.org/AnyEvent-XMPP.git ~# cd AnyEvent-XMPP ~/AnyEvent-XMPP# git checkout -t origin/connection_ref ~/AnyEvent-XMPP# perl Makefile.PL && make && make install
Required dependencies are:
TODO
After you installed everything and the required dependencies you need to setup everything. If you are a programmer (or if you are interested anyway) I recommend to read AnyEvent::MP::Intro to understand what base Bummskraut uses to communicate internally.
This is the description of a simple setup. The AnyEvent::MP message passing framework and the design of the Bummskraut services allow very specialized and custom setups.
I've tried to document a simple setup with one AnyEvent::MP node running the
core and chat protocol services and the other nodes being the bkcl
frontends.
First we are going to setup the shared secret used by AnyEvent::MP to connect the Bummskraut services. Enter this command (be sure to give your own unique string in <secret123>).
# aemp setsecret secret123
It will generate a shared secret in the AnyEvent::MP configuration file
(Which is usually stored in ~/.perl-anyevent-mp).
NOTE: Be sure to do this on all hosts/user accounts you want to run the Bummskraut services on. If they don't have the same shared secret they will not be able to communicate with each other.
Now you setup the AnyEvent::MP profile for the Bummskraut core. In this case we will use bk_core as the name for the core profile, but you can of course also use another profile name.
First we set which TCP port the core service should listen on. The following command will let it listen on port 4050 on the local network interface:
# aemp profile bk_core setbinds "127.0.0.1:4050"
You can of course also configure multiple binds, for multiple interfaces:
# aemp profile bk_core setbinds "127.0.0.1:4050,192.168.0.1:4050"
You can also use a * instead of the IP (or hostname), to bind to
all available network interfaces:
# aemp profile bk_core setbinds "*:4050"
NOTE: Please note that this might fail, as finding the local network interfaces is not standardized and Net::Interface (which is used) has a tough job finding them).
Next we configure which Bummskraut services should be started by the bk_core profile:
# aemp profile bk_core addservice BK::Core::start
That service is the central core service. Without it nothing in Bummskraut will work. It does manage all configuration and logging files for the other protocol backends and the frontends.
Next we are going to add the chat protocol backends/services to the bk_core profile. This is a list of protocols and the corresponding AnyEvent::MP services:
IRC - BK::Backend::IRC::start XMPP - BK::Backend::XMPP::start Twitter - BK::Backend::Twitter::start
So, next for the purpose of an example we add the IRC protocol backend to the core profile:
# aemp profile bk_core addservice BK::Backend::IRC::start
Now we need to configure the frontend, so it can find the core. The profile
name of the bkcl (Bummskraut Curses client) is fixed and is
"BK::Frontend::Curses".
First we have to setup the nodeid of the frontend:
# aemp profile BK::Frontend::Curses setnodeid "anon/"
That nodeid will allow you to connect multiple bkcl instances to the core
later.
Then you need to tell it at which host/port to find the core. This can be done like this:
# aemp profile BK::Frontend::Curses addseed 127.0.0.1:4050
Of course you can also, if the core runs on another host, configure another hostname (or IP):
# aemp profile BK::Frontend::Curses addseed 192.168.0.10:4050
Just make sure that the shared secret configured above is the same!
To control your setup you can use the aemp showprofile and aemp showconfig
command. The output of the showconfig command:
# aemp showconfig
Should resemble something like this (shorted to "secret" field, the rest of the fields that might show up are just default values):
{
...
"secret" : "secret123",
...
}
Next check showprofile bk_core:
# aemp showprofile bk_core
It should look like this:
{
"services" : [
"BK::Core::start",
"BK::Backend::IRC::start"
],
"binds" : [
"127.0.0.1:4050"
]
}
Then check the showprofile BK::Frontend::Curses output:
# aemp showprofile BK::Frontend::Curses
It should look like this:
{
"seeds" : [
"127.0.0.1:4050"
],
"nodeid" : "anon/"
}
Now it's time to startup the core. Type in:
# aemp run bk_core
You should see log messages spawning on the terminal, similar to these:
2009-11-09 23:09:47 INFO [core ]: Bummskraut core is starting up. 2009-11-09 23:09:47 INFO [core ]: Read externalized states and started writer. 2009-11-09 23:09:47 INFO [bknd: irc ]: irc//log: Looking for the BK::Core ... ...
Next start the frontend:
# bkcl
It should print stuff like this in the Curses interface:
09 23:13:43 INFO : [frnt: curses] Initialized frontend. 09 23:13:43 INFO : [frnt: curses] Looking for BK::Core ... 09 23:13:44 INFO : [??? ] MP: bk_core asked us to seed it. 09 23:13:44 INFO : [??? ] Found bk-core at bk_core#fS6TKx0Bo.a, going to connect 09 23:13:44 INFO : [frnt: curses] Connected to the core. ...
If something is wrong, you can boost the printed logging in all parts of Bummskraut
using the BK_LOG_DEBUG environment variable. There are debugging levels 1 to 9.
So set it to 10 to get all debugging messages:
# export BK_LOG_DEBUG=10 # aemp run bk_core
Debuggin messages that have the string MP DEBUG in them are usually AnyEvent::MP
related and gives information about the actual networking stuff:
2009-11-09 23:16:02 DEBUG7 [??? ]: MP DEBUG: 127.0.0.1:38443 connected as BK::Frontend::Curses 2009-11-09 23:16:02 DEBUG5 [??? ]: MP DEBUG: selected new master: BK::Frontend::Curses. 2009-11-09 23:16:02 DEBUG5 [??? ]: MP DEBUG: BK::Frontend::Curses is up () ...
Let me point you to the man-page of the aemp utility:
# perldoc aemp
It might be an interesting read, and reveal more configuration and setup options of the AnyEvent::MP network and the Bummskraut services.
The next step you want to do is to configure the parts of Bummskraut.
In the bkcl frontend type:
/edit_config
Which should give you some output resembling something like this:
Available configurations:
- global
- client
- irc
Next you can discover the configurations yourself by typing for example:
/edit_config irc
That will startup an editor (the editor in the EDITOR environment variable) with the current IRC backend configuration. The opened file should contain comments explaining how to configure the IRC backend.
Same holds true for the other available configurations, every configuration should come with comments that document the available configuration options.
NOTE: The configuration is done using a relaxed version of JSON.
You can find further help in the bkcl frontend. You might be interesting
in the list of available commands, which can be retrieved with:
/commands
If you need explanation to an available command use the /help command:
/help /goto
It's a German word I created/invented that could be translated into English as: bang cabbage or maybe even bang weed. There is no real meaning attached to it except that it is the name for this distributed chat client framework.
Because of the more or less recent inflation of stupid program names, to mark a lower bar on the "bad name for a computer program"-scale.
Let me ask: In which aspect is Firefox, Iceweasel, Parrot, Java or Pidgin a better name for some computer program. They are absolutely undescriptive and could even lead to confusions. Fire foxes, pidgins and parrots are animals for the fsck's sake!
The recent development of pimping up some stupid computer program with a flashy name that just sounds cool has to stop at some point. Bummskraut is there to remind others to pick better names for their software.
Robin Redeker, <elmex@ta-sa.org>
Thanks to:
For fixing the English in the main manual page.
You can look for information at:
IRC Network: http://freenode.net/ Server : irc.freenode.net Channel : #ae_xmpp Author nick: elmex Feel free to join and ask questions!
Copyright 2009 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.