Tutorial

Assume that you want to write a simple “mod_http_hello” module to handle
all requests whose URL path begins with ”/hello”, such as:

• http://localhost:5280/hello/world
• http://localhost:5280/hello/hedgehog

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:

The entire mod_http_hello.erl file would look like:

Modify ejabberd.cfg so that mod_http_hello is loaded when ejabberd starts:

Also in ejabberd.cfg, configure ejabberd_http so that it dispatches requests beginning with ”/hello/” to mod_http_hello:

API

Apart from callbacks required by gen_mod, your module only has to implement (one or more clauses of) process/2:

• your_http_module:process(LocalPath, Request)

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

User requests the URL:

Path “local to the module” will be:

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:

this if one http handler, but if two?

am I right?

Introduction

ejabberd provides an event mechanism. Each module can subscribe to events and a hook in the module code is called when the event occurs.

Example

The module mod_offline.erl is an example of how the events/hooks mechanism can be used.

API

The Hook parameter is the name of the event (see below). Host is the name of the virtual host related to the event. Module and Function describe the hook to be called when the event occurs. Priority is the hook rank, to determine in which order the hooks are run (when several hooks are defined for the same event), use it if you have dependencies between hooks.

List of events

The list of available events, and the type of corresponding hooks, is described below.

Events

Types

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.

Step 0. Download the source code for this tutorial

The source code for this tutorial is available: tutorial_tsung_1.tgz

Step 1. Create tsung configuration file

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.

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

Step 2. Update DTD

We now need to modify the tsung-1.0.dtd or validation would fail.

In the request element we add the myclient tag.

Next we create the myclient element.

Followed by defining the attributes list for myclient.

Next, we add the ts_myclient option into the element’s type attribute list.

We do the same to the session’s type attribute list.

Step 3. Create include file

In PATH/include create the include file ts_myclient.hrl.
This include file should have a minimum of two records:

1. myclient_request: for storing request information parsed from tsung configuration. Will be use to generate server requests.
2. myclient_dyndata: for storing dynamic information. Not used in this case.

Step 4. Config reader

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:

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.

Step 5. ts_myclient

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:

1. {count, Type} – increments a running counter
2. {sum, Type, Val} – adds Val to running counter
3. {sample_counter, Type, Value} – updates sample_counter
4. {sample, Type, Value} – updates counter

Step 6. Build and install

Return to PATH and type make followed by make install.

There is no need to update any make files.

Step 7. Running

Start myserver then call myserver:server() in the erlang shell to start listening to the socket.

Run tsung, passing it myclient.xml:

Authors

The first version of this tutorial has been written by tty.

Category:tutorials

Here is some documentation, mainly targetting developers of contributed modules:

ejabberd

• ejabberd documentation

Tsung

• tsung documentation

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.

API of the module

All the internal modules must use the “gen_mod” behavior.

It must provide the following API:

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.

ejabberd API

The modules interact with ejabberd using one or several of the following mechanisms:

• ejabberd core modules
• ejabberd events and hooks
• ejabberd IQ handlers
• ejabberd route table
• ejabberd HTTP request handlers

Running an internal module as an external module

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.

Router (ejabberd_router)

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.

• Router API

Local router (ejabberd_local)

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.

• Local router API

Session manager (ejabberd_sm)

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.

• Session manager API

Utilities (jlib)

Various helper functions. Modules should include the jlib.hrl file in order to use the records defined by this module.

• jlib API

Modules utilities (gen_mod)

Utility functions useful in a module. This module also define the “gen_mod” behavior.

• gen mod API

XML utilities (xml)

Various utilities to manipulate XML packets.

• XML API

Relational database (ejabberd_odbc)

Used to run SQL queries.

• Relational database API

Router (ejabberd_router)

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.

API

route/3

register_route/1 and unregister_route/1

dirty_get_all_routes/0

dirty_get_all_domains/0

• ejabberd module development