Ejabberd is an open-source XMPP server written in Erlang. Although XMPP has been known for building instant messaging applications for a long time now, over the last few years, people have used it for building very interesting realtime applications. In fact both XMPP and Erlang are being boosted by a new found enthusiasm in the last couple of years. Having played with Erlang for a couple of years now, Ejabberd is an obvious choice for me as an XMPP server. Here I am just documenting things for myself as I learn to write simple modules - which is a powerful way of extending and plugging into the basic Ejabberd server.
Installation:
I assume you already have Erlang installed. So lets install Ejabberd from the source.
$ cd ERLANG_LIB
$ svn co http://svn.process-one.net/ejabberd/trunk ejabberd
$ cd ejabberd/src
$ ./configure
$ make
$ sudo make install
Upon installation you will notice the following important directories and files created, whose meanings are quite obvious from their names:
/etc/ejabberd
-> ejabberd.cfg
-> ejabberdctl.cfg
/sbin/ejabberdctl
/lib/ejabberd
/var/log/ejabberd/ejabberd.log
You can then use the following commands to start and stop the server.
$sudo /sbin/ejabberdctl start
$sudo /sbin/ejabberdctl status
The node ejabberd@localhost is started with status: started
ejabberd 2.1.0-alpha is running in that node
$sudo /sbin/ejabberdctl stop
Writing an Inernal Module:
All internal modules in Ejabberd start with the name ‘mod_’ implement the gen_mod behavior through the two methods:
start(Host, Opts) -> ok
stop(Host) -> ok
where Host is the name of the virtual host running the module, and Opts is the set of options.
So lets just write a basic module that will print something when it starts.
$ cd /ERLANG_LIB/ejabberd/src
$ vi mod_hello.erl
-module(mod_hello).
-behavior(gen_mod).
-export([
start/2,
stop/1
]).
start(_Host, _Opt) ->
?INFO_MSG("Loading module 'mod_hello' ", []).
stop(_Host) ->
ok.
Compile the module, move the beam file to /lib/ejabberd/ebin:
$ erlc mod_hello.erl
$ sudo mv mod_hello.beam /lib/ejabberd/ebin
Now we need to configure our Ejabberd Configuration File to load the mod_hello module. So lets go to the sections where modules are enabled in the ejabberd.cfg, and add the following line to the file.
$ sudo vi /etc/ejabberd/ejabberd.cfg
{modules,
[
.....
{mod_first_module, []},
.....
]
}
Start the server and verify that the message is printed in the log.
$ sudo /sbin/ejabberdctl start
$ less /var/log/ejabberd.log
Sweet!
Writing an HTTP module:
Building an HTTP module is similar to building internal modules but the nice thing about HTTP modules is you can get requests from URLs, process them in the module and then send the response back. So if you need any extra interactivity or information exposed via the URL, HTTP module is the way do it.
Each HTTP module implements the gen_mod behavior. That means, it has start/2 and stop/1 functions. It also has a request handler process/2 function, that handles the actual request.
Now lets write a HTTP module mod_available_user.erl. Given a URL like http://localhost:5280/users/sacharya, lets build an HTTP module that will send a response back telling whether the username ’sacharya’ is already registered or not. So let me grab the sample template from Ejabberd Documentation, and modify it.
$ vi mod_available_user.erl
-module(mod_available_user).
-behavior(gen_mod).
-export([
start/2,
stop/1,
process/2
]).
-include("ejabberd.hrl").
-include("jlib.hrl").
-include("web/ejabberd_http.hrl").
start(_Host, _Opts) ->
ok.
stop(_Host) ->
ok.
process(Path, _Request) ->
{xmlelement, "html", [{"xmlns", "http://www.w3.org/1999/xhtml"}],
[{xmlelement, "head", [],
[{xmlelement, "title", [], []}]},
{xmlelement, "body", [],
[{xmlelement, "p", [], [{xmlcdata, is_user_exists(Path)}]}]}]}.
is_user_exists(User) ->
Result = ejabberd_auth:is_user_exists(User, "localhost"),
case Result of
true -> "The username " ++ User ++ " is already taken.";
false ->"The username " ++ User ++ " is available."
end.
How the process works is pretty clear if you have some familiarity with Erlang. All we are doing is using the function is_user_exists/1 provided in the the ejabberd_auth module and deciding what message to display in the response.
Compile the file and move the beam to ebin.
$ erlc -I /lib/ejabberd/include/ mod_available_user.erl
$ sudo mv mod_available_user.beam /lib/ejabberd/ebin
The flags ‘I’ (Include) in the erlc command is just used to reference to the directory where the included .hrl files are located.
Now lets add the module into the configuration file so that the request handler will dispatch any requests to /users to our module.
$ vi /etc/ejabber/ejabberd.cfg
{5280, ejabberd_http, [
captcha,
http_poll,
web_admin,
{request_handlers, [{["users"], mod_available_user}]}
]}
Create some Users and Test:
To test the above module, we need some users. So lets create an admin user in the domain, login as admin and create a couple of users.
$ sudo ejabberdctl start
$ sudo ejabberdctl register admin localhost password
User admin@localhost succesfully registered
Now go to /lib/erlanged/ejabberd.cfg and add this user:
{acl, admin, {user, "admin", "localhost"}}
Now bring localhost:5280/admin in the browser and login using, username: admin@localhost and password: password
Once you are logged in, go to http://localhost:5280/admin/server/localhost/users/, and add a few users eg. sudarshan@localhost, acharya@localhost.
Now that we have the users created and the HTTP module to check the users ready, lets test some URLs:
Request: http://localhost:5280/users/sudarshan
Response: The username sudarshan is already taken.
Request: http://localhost:5280/users/joeuser
HTTP Response: The username sacharya is available.
So in a very easy way, you can build applications that interact with your core Ejabberd services through the URL.
