The following modules must be loaded before this module:

The following libraries or applications must be installed before running Kamailio with this module loaded:

epmd must running on the same host where Kamailio is running. Erlang does not need to be installed on the same host where Kamailio is running.

Number of erlang C node processes to be started to handle the communication tasks. A C node is a C program written to act as a hidden node in a distributed Erlang system.

Default value is 1.

...
modparam("erlang", "no_cnodes", 2)	
...

alivename is the registered name of the Kamailio process.

Note, if the no_cnodes greater then 1, then alivename of Kamailio process will be suffixed with number.

...
modparam("erlang", "cnode_alivename", "proxy")
...

C node host is the name of the machine we're running on. If long names are to be used, it should be fully qualified.

...
modparam("erlang", "cnode_host", "kamailio.lan")
...

The format of the node name is an name@host where name is the name given by the user and host is the full host name if long names are used, or the first part of the host name if short names are used.

...
modparam("erlang", "erlang_nodename", "node1@erlang.lan")
...

Each node has its own magic cookie. When a nodes tries to connect to another node, the magic cookies are compared If they do not match, the connected node rejects the connection.

...
modparam("erlang", "cookie", "secretcookie")
...

Used to set tracing on the distribution. The parameter is different verbosity level. A higher level means more information. Useful in development, but in production should be disabled.

The different tracelevels has the following messages:

...
modparam("erlang", "trace_level", 5)
...

Prepend Erlang atom struct in RPC Kamailio reply where RPC struct is generated. Some libraries for converting erlang term in JSON require atom struct as first element in tuple to convert list of properties into javscript object.

Erlang provides a number of data types but not all of them are supported by Kamailio. This module provides several of them as pseudo variables. These pseudo variables allow user to create Erlang message or function arguments and receive result from Erlang node. Some Erlang variables can contain other data types, so we introduced several attributes to determine type, length, or get formatted output useful for debug, quick compare or put into the log.

Exported pseudo variable has several attributes to get type, length and formatted output readable by transformations or user. Pseudo variable by self determine variable type, but we need to know what type on some position is.

...
xlogl("L_DEBUG","The number of elements in list L: $erl_list(L=>length)\n");
xlogl("L_DEBUG","The number of elements in tuple T: $erl_tuple(T=>length)\n");
...

> example of log output:

DEBUG: <script>: 120:The number of elements in list L: 4
DEBUG: <script>: 121:The number of elements in tuple T: 2
...

...
xlogl("L_DEBUG","list L in clear text: $erl_list(L=>format), the type at index 2: $erl_list(L[2]=>type)\n");
xlogl("L_DEBUG","tuple T in clear text: $erltuple(T=>format), the type at index 1: $erl_tuple[T[1]=>type)\n");
...

> example of log output:

DEBUG: <script>: 130:list L in clear text: [example, list, 4, "items"], the type at index 2: integer
DEBUG: <script>: 131:tuple T in clear text: {example, tuple}, the type at index 1: atom
...

erl_atom pseudo variable allows create analog to Erlang atom data type. Erlang atom is a literal, a constant with name. Formatted output pseudo variable atom could be enclosed in single quotes (') if it does not begin with a lower-case letter or if it contains other characters than alphanumeric characters, underscore (_), or @.

...
$erl_atom(A) = "badrpc";
xlogl("L_DEBUG","$$erl_atom(A): $erl_atom(A=>format)\n");
...

> log output is:

DEBUG: <script>: 123:$erl_atom(A): badrpc
...

Compound data type with a variable number of terms. Formally, a list is either the empty list [] or consists of one or more elements.

Behavior of the list is the same as AVP variable. Set value without index prepends element on list. You are able to replace element at given index. List supports [*] index to get whole list or reset all elements in the list. To create empty list set whole list to $null.

...
$erl_atom(E) = "example";
$erl_list(L) = "list";
$erl_list(L) = "of";
$erl_list(L) = $erl_atom(E);

xlogl("L_DEBUG","length(L): $erl_list(L=>length), format(L): $erl_list(L=>format)\n");

# empty list
$erl_tuple(E[*]) = $null;

xlogl("L_DEBUG","length(E): $erl_list(E=>length), format(E): $erl_list(L=>format)\n");
...

> log output is:

DEBUG: <script>: 143:length(L): 3, format(L): [example, "of", "list"]
DEBUG: <script>: 148:length(E): 0, format(E): []
...

From the Erlang point of view the tuple compound data type with a fixed number of terms. The module implementation of tuple has the same behavior as the list.

...
$erl_atom(line) = "line";
$erl_atom(id)   = "id";
$erl_atom(owner)= "owner";

$var(user)  = "Bob";

$erl_tuple(owner) = $var(user);
$erl_tuple(owner) = $erl_atom(owner);

$erl_tuple(id) = 23;
$erl_tuple(id) = $erl_atom(id);

$erl_list(L) = $erl_tuple(owner);
$erl_list(L) = $erl_tuple(id);

$erl_tuple(T) = $erl_list(L);
$erl_tuple(T) = $erl_atom(line);

xlogl("L_DEBUG","length(T): $erl_tuple(T=>length), format(T): $erl_tuple(T=>format)\n");
...

> log output is:
...
DEBUG: <script>: 153:length(T): 2, format(T): {line, [{id, 23}, {owner, "Bob"}]}
...

erl_pid holds Eralng process identifier. Provides access to Erlang PID value and could be used in send message.

...
if ($erl_xbuff(msg[0]=>type) == "pid") {
	$erl_pid(pid) = $erl_xbuff(msg[0]);
	xlogl("L_INFO","Received PID: $erl_pid(pid=>format)\n");
}
...

erl_ref holds Erlang reference. Provides access to reference value and could be used in send message.

...
if ($erl_xbuff(msg[0]=>type) == "ref") {
	$erl_ref(ref) = $erl_xbuff(msg[0]);
	xlogl("L_INFO","Reference: $erl_ref(ref=>format)\n");
}
...

erl_xbuff is created as generic pseudo variable to acts as other pseudo variables exported from module. It's useful when in advance we don't know what variable type to expect. The behavior of variable depends of initialization. Module functions expect this PV as return value, and PV for incoming Erlang message.

...
# Tuple T from previous example

$erl_xbuff(X) = $erl_tuple(T);

xlogl("L_DEBUG","typeof(X): $erl_xbuff(X=>type), length(X): $erl_xbuff(X=>length), format(X): $erl_xbuff(X=>format)\n");
...

> log output is:
...
DEBUG: <script>: 410:typeof(X): tuple, length(X): 2, format(X): {line, [{id, 23}, {owner, "Bob"}]}
...

This function supports calling Erlang functions on remote nodes.

The parameter mod and fun are module and function name respectively. It can be a static string or a dynamic string value with config variables.

The parameter args is list of arguments passed to function, so it must be list, or xbuff that contains list.

The parameter reply is result from RPC call. It must be xbuff to accept any result.

Function returns false on error to send or wrong arguments passed to function. If executing remote function caused error function still returns true but error is encoded into repl parameter.

...
# example of call erlang:list_to_tuple(["one","two"])
# on remote node

$erl_list(L) = "two";
$erl_list(L) = "one";

# put list into list
$erl_list(args) = $erl_list(L);

erl_rpc("erlang", "list_to_tuple", "$erl_list(args)", "$erl_xbuff(repl)");

xlogl("L_DEBUG","type(repl): $erl_xbuff(repl=>type), format(repl): $erl_xbuff(repl=>format)\n");

> log output:
...
DEBUG: <script>: 386:type(repl): tuple, format(repl): {"one", "two"}
...

This function sends an Erlang term to a registered process.

The argument server is the registered name of the intended recipient process on remote node.

The argument msg is containing the message to be sent.

...
# example of send message to registered process
# {notifier,'node1@erlang.lan'} ! {example,message}

$erl_atom(example) = "example";
$erl_atom(message) = "message";

$erl_tuple(M) = $erl_atom(message);
$erl_tuple(M) = $erl_atom(example);

erl_reg_send("notifier","$erl_tuple(M)");
...

This function sends an Erlang term to a process. This function can be used from ANY_ROUTE. The argument pid is the Erlang process id of the intended recipient process on remote node. The argument msg is containing the message to be sent.

...
# example of send message to process
# Pid ! {example,message}

$erl_atom(notifier) = "notifier";
$erl_list(args) = $erl_atom(notifier);

erl_rpc("erlang", "whereis", "$erl_list(args)", "$erl_xbuff(pid)");

$erl_atom(example) = "example";
$erl_atom(message) = "message";

$erl_tuple(M) = $erl_atom(message);
$erl_tuple(M) = $erl_atom(example);

erl_send("$erl_xbuff(pid)","$erl_tuple(M)");
...

Function to send message from event route (pseudo process). Function sends reply message msg to the sender process.

...
# event route acts as registered process
event_route[erlang:greetings] {

	xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n");

	$erl_atom(hello) = "hello";
	$erl_tuple(reply) = "Erlang";
	$erl_tuple(reply) = $erl_atom(hello);

	# reply greeting
	erl_reply("$erl_tuple(reply)");
}
...

%% in erlang shell

(node1@erlang.lan)24> {greetings,'proxy@kamailio.lan'} ! {hello,"Kamailio"}.
{hello,"Kamailio"}
(node1@erlang.lan)25> flush().
Shell got {hello,"Erlang"}
ok

> logged info message:
INFO: <script>: 951:Received message: {"hello", "Kamailio"}
>

To create pseudo erlang registered process in Kamailio scrip create event route in form of event_route[erlang:<my_process_name>]. Where <my_process_name> is the name of pseudo process.

...
# event route acts as registered process
event_route[erlang:handler] {

	xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n");

}
...

%% in erlang shell send message to registered process

(node1@erlang.lan)12> {handler,'proxy@kamailio.lan'} ! {"hello","Kamailio"}.
{"hello","Kamailio"}

> logged info message:
INFO: <script>: 951:Received message: {"hello", "Kamailio"}
>

The reserved pseudo process name to receive messages sent to Kamailio C node. The message are sent to non registered process.

...
# default event route from erlang
event_route[erlang:self] {

	xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n");

	if(pv_isset("$erl_xbuff(msg[1])") && $erl_xbuff(msg[1]=>type) == "pid") {
		xlogl("L_INFO","Echo reply to: $erl_xbuff(msg[1]=>format)\n");
		erl_send("$erl_xbuff(msg[1])","$erl_xbuff(msg[0])");
	}
}
...

%% in erlang shell send message to registered process

(node1@erlang.lan)12> Pid=rpc:call('proxy@kamailio.lan',erlang,whereis,[self]).
<14808.9.0>
(node1@erlang.lan)14> Pid ! ["hello from",self()].
["hello from",<0.247.0>]
(node1@erlang.lan)15> flush().
Shell got "hello from"
ok

> logged info messages:
INFO: <script>: 653:Received message: ["hello from", <node1@erlang.lan.247.0>]
INFO: <script>: 656:Echo reply to: <node1@erlang.lan.247.0>]
>

Function to be called directly from other modules to load the API. On success return 0, on error 1.

Meaning of the parameters is as follows:

This function supports calling Erlang functions on remote nodes. On success function returns 0.

Meaning of parameters is as follows:

This function sends an Erlang term to a registered process. On success return 0.

Meaning of parameters is as follows:

This function sends an Erlang term to a process. On success return 0.

Meaning of parameters is as follows:

Function to send reply on processed message.

Meaning of parameters is as follows:

Function encodes XAVP variable into ei dynamic buffer. How to create XAVP variable see source code.

Meaning of parameters is as follows:

Function decodes ei dynamic buffer into XAVP variable.

Meaning of parameters is as follows: