ejabberd provides an event mechanism. Each module can subscribe to events and a hook in the module code is called when the event occurs.
The module mod_offline.erl is an example of how the events/hooks mechanism can be used.
ejabberd_hooks:add(Hook, Host, Module, Function, Priority)
ejabberd_hooks:remove(Hook, Host, Module, Function, Priority)
* Hook = atom()
* Host = string()
* Module = atom()
* Function = atom()
* Priority = integer()
To stop ejabberd from calling other functions in that hook, your function must return the atom() stop. An another way to stop the call chain is to return tuple {stop, Val} to override the return value.
The list of available events, and the type of corresponding hooks, is described below.
adhoc_local_items(Acc, From, To, Lang) -> Adhoc
adhoc_sm_items(Acc, From, To, Lang) -> Adhoc
c2s_stream_features(Acc)
c2s_unauthenticated_iq(Acc, Server, IQ) -> Adhoc
disco_local_features(Acc, From, To, Node, Lang) -> Adhoc
disco_local_identity(Acc, From, To, Node, Lang) -> Adhoc
disco_local_items(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_features(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_identity(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_items(Acc, From, To, Node, Lang) -> Adhoc
ejabberd_ctl_process(Args) -> CtlStatus
filter_packet({From, To, Packet}) -> {From, To, Packet}
local_send_to_resource_hook(From, To, Packet) -> ok
offline_message_hook(From, To, Packet) -> ok
privacy_check_packet(Acc, User, Server, PrivacyList, {From, To, Packet}, Dir) -> Auth
privacy_get_user_list(Acc, User, Server) -> PrivacyList
privacy_iq_get(Acc, From, To, IQ) -> {result, Packet} | {error, Error}
privacy_iq_set(Acc, From, To, IQ) -> {result, Packet} | {error, Error}
privacy_updated_list(Acc, OldPrivacyList, NewPrivacyList) -> PrivacyList
pubsub_publish_item(From, To, Node, ItemID, Payload) -> ok
remove_user(User, Server) -> ok
resend_offline_messages_hook(Acc, User, Server) -> [Route]
resend_subscription_requests_hook(Acc, User, Server) -> [Packet]
roster_get(Acc, {User, Server}) -> [RosterItem]
roster_get_jid_info(Acc, User, Server, JID) -> {Subscription, Groups}
roster_get_subscription_lists(Acc, User, Server) -> {[FromSubscription], [ToSubscription]}
roster_in_subscription(User, Server, JID, SubscriptionType, Reason) -> bool()
roster_out_subscription(User, Server, JID, SubscriptionType) -> bool()
roster_process_item(RosterItem, Server) -> RosterItem
set_presence_hook(User, Server, Resource, Packet) -> none
sm_register_connection_hook(SID, JID) -> ok
sm_remove_connection_hook(SID, JID, SessionInfo) -> ok
unset_presence_hook(User, Server, Resource, Status) -> void()
user_available_hook(JID) -> ok
user_receive_packet(JID, From, To, Packet) -> ok
user_send_packet(From, To, Packet) -> ok
To = From = JID = ServerJID = #jid (see jlib)
Packet = Payload = {xmlelement, Name, Attrs, SubEl}
IQ = #iq (see jlib)
Error = ?STANZA_ERROR/3 (see jlib.h)
Lang = string()
Dir = in | out
Auth = allow | deny
PrivacyList = OldPrivacyList = NewPrivacyList = none | #userlist
CtlStatus = false | ?STATUS_SUCCESS | ?STATUS_ERROR | ?STATUS_USAGE | ?STATUS_BADRPC (see ejabberd_ctl.hrl")
Adhoc = {result, I} | {error, Error} | empty
Arg = [string()]
Node = [string()]
ItemID = string()
Route = {route, From, To, Packet
RosterItem = #roster (see mod_roster.hrl)
Subscription = none | from | to | both | remove
SubscriptionType = subscribe | subscribed | unsubscribe | unsubscribed
Reason = string()
Groups = [string()]
SimpleJID = FromSubscription = ToSubscription = {User, Server, Resource}
User = string()
Server = string()
Resource = string()
Status = string()
SID = {Time, pid()}
Time = {MegaSecs, Secs, MicroSecs} (see erlang:now/0)
MegaSecs = Secs = MicroSecs = int()
Acc = same type as the return type of the function. Each module adds to the accumulator Acc their contribution
This hook is related to XEP-0030
This hook is related to XEP-0030
Triggered when a message is sent to an offline user. The ejabberd session manager adds a default function to the offline_message_hook chain that bounces the incoming message with a service unavailable error. This hook is added at the lowest priority so that it executes after anything else in the chain.
This hook is processed whenever a connected user sends a presence stanza to the server.
ejabberd internal modules works as plugins. Each module is an erlang module with a name beginning with “mod_”. If you don’t already know Erlang, you should also take a look at this doc.
All the internal modules must use the “gen_mod” behavior.
It must provide the following API:
start(Host, Opts) -> ok
stop(Host) -> ok
* Host = string()
* Opts = [{Name, Value}]
* Name = Value = string()
Host is the name of the virtual host running the module. The start/2 and stop/1 functions are called for each virtual host at start and stop time of the server.
Opts is a lists of options set in the configuration file for the module. They can be retrieved with the gen mod:get opt/3 function.
The modules interact with ejabberd using one or several of the following mechanisms:
ejabberd internal modules using only the route table can also be used as external modules conform to XEP-0114 with epeios, and thus, they can be used with any other XEP-0114 compliant XMPP servers.
]]>Assume that you want to write a simple “mod_http_hello” module to handle
all requests whose URL path begins with “/hello”, such as:
Start by writing a “mod_http_hello.erl” file that contains request
handlers, which are clauses of the process/2 function. For
example, to handle a request with the “/hello/world” path:
process(_LocalPath = ["world"], _Request) ->
{xmlelement, "html", [{"xmlns", "http://www.w3.org/1999/xhtml"}],
[{xmlelement, "head", [],
[{xmlelement, "title", [], []}]},
{xmlelement, "body", [],
[{xmlelement, "p", [], [{xmlcdata, "Hello, world!"}]}]}]};
The entire mod_http_hello.erl file would look like:
%%%----------------------------------------------------------------------
%%% File : mod_http_hello.erl
%%% Author : Your Name <your [at] email [dot] org>
%%% Purpose : Sample module that extends embedded ejabberd HTTP server
%%% Created :
%%% Id :
%%%----------------------------------------------------------------------
-module(mod_http_hello).
-author('your@email.org').
-vsn('').
-define(ejabberd_debug, true).
-behaviour(gen_mod).
-export([
start/2,
stop/1,
process/2
]).
-include("ejabberd.hrl").
-include("jlib.hrl").
-include("ejabberd_http.hrl").
%%%----------------------------------------------------------------------
%%% REQUEST HANDLERS
%%%----------------------------------------------------------------------
process(["world"], _Request) ->
{xmlelement, "html", [{"xmlns", "http://www.w3.org/1999/xhtml"}],
[{xmlelement, "head", [],
[{xmlelement, "title", [], []}]},
{xmlelement, "body", [],
[{xmlelement, "p", [], [{xmlcdata, "Hello, world!"}]}]}]};
process(["produce_error"], _Request) ->
{400, [], {xmlelement, "h1", [],
[{xmlcdata, "400 Bad Request"}]}};
process(LocalPath, _Request) ->
{xmlelement, "html", [{"xmlns", "http://www.w3.org/1999/xhtml"}],
[{xmlelement, "head", [],
[{xmlelement, "title", [], []}]},
{xmlelement, "body", [],
[{xmlelement, "p", [], [{xmlcdata, io_lib:format("Called with path: ~p", [LocalPath])}]}]}]}.
%%%----------------------------------------------------------------------
%%% BEHAVIOUR CALLBACKS
%%%----------------------------------------------------------------------
start(_Host, _Opts) ->
ok.
stop(_Host) ->
ok.
Modify ejabberd.cfg so that mod_http_hello is loaded when ejabberd starts:
{modules,
[
%% ...
{mod_http_hello, []},
%% ...
]}.
Also in ejabberd.cfg, configure ejabberd_http so that it dispatches requests beginning with “/hello/” to mod_http_hello:
{5280, ejabberd_http, [http_poll, web_admin,
{request_handlers, [{["hello"], mod_http_hello}]}]}
Apart from callbacks required by gen_mod, your module only has to implement (one or more clauses of) process/2:
The process/2 function handles an HTTP request. It returns the data to be sent back to the client, optionally with a status code and additional headers.
process/2 will be called with two arguments: LocalPath and Request.
The LocalPath argument is a list containing the part of the requested URL path that is “local to the module”.
Example: mod_foo was configured in ejabberd.cfg to handle requests whose path begins with “/a/b”:
{5280, ejabberd_http, [http_poll, web_admin,
{request_handlers, [{["a", "b"], mod_foo}]}]}
User requests the URL:
http://server:5280/a/b/c/d
Path “local to the module” will be:
["c", "d"]
Usually you will want to select a handler based on the local path instead of the full path (Request#request.path), so that server administrators can make the module available under the path prefix of their choice.
The Request argument is a record containing information about the HTTP request as defined in ejabberd_http.hrl. It consists of the following fields:
{
"request",
method, %% HTTP method ("GET" or "POST")
path, %% Full path to requested resource
%% e.g. for "http://server:5280/a/b/c/d": ["a", "b", "c", "d"]
q, %% Query part of the URL
%% e.g. for "http://server:5280/a/b/c/d?foo=bar": [{"foo", "bar"}]
us, %% Authenticated user and server. Used in ejabberd_web_admin for now.
%% e.g. for "foo@jabber.server.org": {"foo", "jabber.server.org"}
auth, %% Information provided for HTTP-auth (if any)
%% e.g. for a user "john" who entered the password "secret": {"john", "secret"}
lang = "", %% Language code
data = "", %% POST data
}
{5280, ejabberd_http, [http_poll, web_admin,
{request_handlers, [{["hello"], mod_http_hello}]}]}
this if one http handler, but if two?
{5280, ejabberd_http, [http_poll, web_admin,
{request_handlers, [{["hello"], mod_http_hello},
{request_handlers, [{["http-bind"], mod_http_bind}]}
am I right?
]]>Since tsung is used to test servers lets define a simple server for testing. myserver.erl provides 3 operations: echo, add and subtract.
myserver.erl assumes the first byte to be a control instruction followed by 2 or more byte data. The echo operation merely returns the byte data while add and subtract performs these operations on the 2 byte data before returning the results. See the code of myserver.erl for details.
We assume the source files for tsung-1.2.1 are available. This example was compiled using Erlang OTP R11B-3.
The source code for this tutorial is available: tutorial_tsung_1.tgz
Based on the 3 operations we want to test we define the myclient.xml which
will take place of tsung.xml. You will notice myclient.xml looks very much
like any normal tsung configuration file. The main difference is in the
session definition. Here we use the ts_myclient type.
<session probability="100" name="myclient-example" type="ts_myclient">
This indicates which plugin tsung should call when creating a server request.
We choose to name this plugin ts_myclient.
The next difference is within the request element. Here we define a ‘myclient’
element indicates the operations to test followed by the relevant data.
Notice that myclient has 2 attributes: type and arith (optional).
We now need to modify the tsung-1.0.dtd or validation would fail.
In the request element we add the myclient tag.
<!ELEMENT request ( match*, dyn_variable*, ( http | jabber | raw | pgsql | myclient ) )>
Next we create the myclient element.
<!ELEMENT myclient (#PCDATA) >
Followed by defining the attributes list for myclient.
<!ATTLIST myclient
arith (add | sub) #IMPLIED
type (echo | compute) #REQUIRED >
Next, we add the ts_myclient option into the element’s type attribute list.
type (ts_http | ts_jabber | ts_pgsql | ts_myclient ) #IMPLIED
We do the same to the session’s type attribute list.
type (ts_jabber | ts_http | ts_raw | ts_pgsql | ts_myclient ) #REQUIRED>
In PATH/include create the include file ts_myclient.hrl.
This include file should have a minimum of two records:
Create the ts_config_myclient.erl in PATH/src/tsung_controller to parse the XML file. This file must export parse_config/2.
ts_config_myclient:parse_config/2 is called from ts_config:parse/1.
However trying to run ts_config:parse/1 seperately seem to throw an undefined case error.
The important function definition is:
parse_config(Element = #xmlElement{name=myclient}, ...)
Within this pattern we gather the various attributes, echo, compute, add, sub,
and data creating a myclient_request record as needed. Notice for the case
of type compute we parse the data into a list of 2 integers. Ensure you keep
any data manipulation here consistant with calls in ts_myclient:get_message/1.
If your configuration file support several element types then you will need a parse_config function for each.
The final file to create is ts_myclient.erl in PATH/src/tsung.
The get_message/1 function builds the actual data to be transmitted to the server. The function returns a binary even if your protocol uses strings.
In ts_myclient:get_message/1, you can see how we create the message from the myclient_request record. Compare this with myserver:test/3 and myserver:test/1.
parse/2 deals with server responses. It is possible to parse the return data and update monitoring parameters. In the ts_myclient:parse/1 we count the number of single and multi bytes returned from the server. Obviously these must match echo and add / _sub calls.
The ts_mon:add/1 parameters are restricted to:
Return to PATH and type make followed by make install.
There is no need to update any make files.
Start myserver then call myserver:server() in the erlang shell to start listening to the socket.
sh> erl -s myserver start_link
1> myserver:server().
Run tsung, passing it myclient.xml:
sh> tsung -f myclient.xml
The first version of this tutorial has been written by tty.
]]>Here is some documentation, mainly targetting developers of contributed modules:
- tutorial: Writing a Tsung plugin
]]>This module is the main router for XMPP packets on each node. It routes packets based on their destination domains. It has two tables: local and global routes. First, the destination domain of each packet is searched in local table. If found, the packet is routed to the appropriate process. Else, it searches in global table, and routes to the appropriate ejabberd node or process. If it does not exists in either tables, then the packet is sends to the S2S manager.
This module routes packets which have a destination domain equal to one of the virtual host name of the server. If destination JID has a non-empty user part, then it routes packets to the session manager, else it is processed depending on it’s content.
Handle the currently opened sessions.
This module routes packets to local users. It determines which user resource the packet must be sent via the presence table. If this resource is connected to this node, it is routed to the C2S manager. If it’s connected via another node, then the packet is sent to the session manager on that node.
Various helper functions. Modules should include the jlib.hrl file in order to use the records defined by this module.
Utility functions useful in a module. This module also define the “gen_mod” behavior.
Various utilities to manipulate XML packets.
Used to run SQL queries.
]]>This module is the main router for XMPP packets on each node. It routes packets based on their destination domains. It has two tables: local and global routes. First, the destination domain of each packet is searched in local table. If found, the packet is routed to the appropriate process. Else, it searches in global table, and routes to the appropriate ejabberd node or process. If it does not exists in either tables, then the packet is sends to the S2S manager.
route(From, To, Packet)
* Packet = {xmlelement, Name, Attrs, SubEl}
* Attrs = [{Name, Value}]
* Name = Value = string()
* SubEl = [Packet]
register_route(Host)
unregister_route(Host),
* Host = string()
dirty_get_all_routes() -> [RouteName]
* RouteName = string()
dirty_get_all_domains() -> [Domains]
* Domains = string()