Getting started with ejabberd. Overview; Options to use ejabberd; Architecture. However, the guide is believed to help you understanding ejabberd’s code. These tutorials assume installation on localhost for development purposes.
|Published (Last):||3 October 2008|
|PDF File Size:||5.52 Mb|
|ePub File Size:||19.93 Mb|
|Price:||Free* [*Free Regsitration Required]|
This guide is a brief explanation of ejabberd internals. It is not intended to be a comprehensive ejabberd’s internal API documentation. You still need to read and understand ejabberd’s source code.
However, the guide is believed to help you understanding ejabberd’s code faster: Note that there is absolutely no need to know every line of code of ejabberd, but some parts are crucial to understand. In order to read and understand the guide you must be pretty fluent with Erlang programming language and understand basics of the XMPP protocol: If you see these words for the first time in your life you’re unlikely to understand the guide.
The guide describes ejabberd Previous and next versions can differ drastically from the one described herein. If you’re hacking ejabberd for internal needs, you are free to choose whatever coding style you like.
In some cases the rules can be bypassed, but the reason doing so should be really ejabbberd. The rules shouldn’t be ignored just because a contributor doesn’t like them. It’s worth noting that the code itself should be indented using Emacs indentation style that is the standard indentation style for Erlang programs. This function makes some initialization such as logger, mnesia, configuration file, etc.
The ejabberd core is not well-defined. Moreover, the described core layers are pure abstraction grouping several modules together by some criteria for better understanding of ejabberd internal euabberd rules. Once ejabberd is started, some external events should obviously make it doing something.
Besides explicit administrative commands, the most relevant such events are incoming connections. Incoming connections are handled inside Network Layer. This has lead to unmaintainable monolithic spaghetti code with a lot of code duplication between these modules. The state is represented by a map in both cases. Examples of such callback functions are:. It’s pretty small and straightforward module whose the only task is to find the fjabberd for a stanza.
Mentioned modules are explained in more details in the following sections. This is also the most notable function of the module. Calling to other functions is not recommended.
The internal session table is backend-dependent and is implemented in the corresponding backend module: Any process can register a route to itself. There are two types of IQ handlers: Once registered, matching IQ stanzas are handled by calling Module: An IQ discipline defines how an IQ handler a function will be executed.
Configuring ejabberd | ejabberd Docs
There are the following disciplines: This is a fast method to execute a handler, however, the drawback is that it ejabbrrd the caller. The drawback is that the created process’ message queue can be overloaded if manusl doesn’t process incoming IQs fast enough, which, in the worst case may crash emulator due to OOM out-of-memory.
N parallel processes are created for the handler and all matching IQs are relayed to one of these processes. The processes are picked up randomly. However, the drawback is that the order of IQs is not maintained, i.
Care should be taken on choosing too large value for N because picking up a process from the pool has O N complexity. Anyway, in practice, seems like there is no much benefit to set N larger than This discipline is not recommended because uncontrolled processes creation is in general a bad idea.
When ejabberd is processing an arbitrary event incoming IQ, outgoing presence, configuration change, etcit is convenient to consider some of them notable. In order for someone to be notified of such events, ejabberd executes “hooks”.
A hook is represented by a unique name. All functions associated with the hook’s name will be called in some specified order. The conception of hooking is not ejabberd specific, see Hooking Wikipedia page for a general description.
Several modules need to listen for an event represented by this hook that is, a packet and a C2S stateso they associate their internal functions with it: Note that Host argument is omitted in this case. In some cases a new hook should be introduced. There is no need to explicitly register the new hook, one only needs to run a hook in the required place.
The following functions can be used for this:. You can use it to check hook correctness and find mishooked functions. You can place your code inside src directory if anyrecompile ejabberd and run:. As you might know, ejabberd is a modular software. The best method to add new functionality to it is to write a new module.
While some modules don’t need to maintain an internal state “stateless” modulesothers are required to do this “stateful” modules.
There is a couple of helpers to deal with such modules:. If a stateful module is intended to maintain a state in the form of a table, ETS can be used for this. But make sure you’re not calling ets: There is a plenty of examples of modules: It performs configuration file parsing and validation.
The callback accepts an option name as an atom and must return either validating function if an option is known for the Module or a list of available options as a list of atoms.
Welcome to ejabberd, your superpowerful messaging framework
A validating function is a fun of a single argument – the value of the option. The validating function must return any new value for the option whether it’s modified or not or should crash if the value doesn’t match expected format. Here is an example:. The function is used to get a value Value of a configuration option Option. The ValidatingFun is a validating function described in the previous section and Default is the default value if the option is not defined in the config.
Prior to version This is now deprecated and actually not possible. Instead, the new API functions are used from brand new xmpp library. You can use these functions for de serialization of data stored on disc or in a database. The same is true for header files: At that level “lazy” decoding is applied: For example, an xmlel packet. Note that the sub-element is still in xmlel format.
This “semi-decoded” packet is then passed upstream at the Routing Layer. Thus, a programmer should explicitly decode sub-elements if needed.
Managing an ejabberd server
To accomplish this one can use the following function:. By default, full decoding mnaual applied, i. Namespace is a “top-level” namespace: There is also xmpp: The value of Why can be used to format the failure reason into human readable description using xmpp: Ejabberf dialyzer checks of your code for validation.
Luckily, there is a helper function for sub-elements decoding, described in the next section and in a lot of cases it’s more convenient to use it.
To accomplish this the following function can be used:. This function finds a Tag by its well-known record inside sub-elements of the Stanza. Note that the function doesn’t fail if some of sub-elements are invalid.
In order to inject a sub-element into or delete one from arbitrary stanza one can use xmpp: Every stanza element has from and to record fields. Every stanza element has meta field represented as a map. It’s useful when there is a need to attach some metadata to the stanza before routing it further.
A programmer can manipulate with this field directly using maps module, or use xmpp: The example is message. To avoid writing a lot of extracting code the following functions can be used: In order to generate stanza errors or stream errors xmpp: If a stanza should be bounced back with an error, xmpp: There are many predefined macros for XML namespaces in ns.
However, this file must NOT be included, as it’s already included in xmpp. There are two common types of internal representation of JIDs:. Inspect exported functions of jid.