====== Presence User Agent Modules ======

It was designed with extensibility in mind, not to be tied to SIP or Kamailio (OpenSER) specific entities.

At this moment, there are three modules:

* [b]pua[/b] ([[http://www.kamailio.org/docs/modules/1.5.x/pua.html|see readme file]])- includes the common API for presence user agents, cannot be used standalone
* [b]pua_mi[/b] [[http://www.kamailio.org/docs/modules/1.5.x/pua_mi.html#id2496192|see readme file]])- enhance Kamailio (OpenSER) with the ability to publish presence information sent by external applications via management interface (MI - at this moment FIFO file and XMLRPC transports are available)
* [b]pua_usrloc[/b] [[http://www.kamailio.org/docs/modules/1.5.x/pua_usrloc.html|see readme file]])- enhance Kamailio (OpenSER) with the ability to publish presence information for records stored in user location table. Kamailio (OpenSER) can publish in behalf of phones which have no SIMPLE/Presence support information with online/offline status.
* [b]pua_xmpp[/b] ([[http://www.kamailio.org/docs/modules/1.5.x/pua_xmpp.html|see readme file]])- SIMPLE- XMPP gateway enhances presence information exchange between clients from SIP/SIMPLE and Jabber/XMPP clients -([[presence:pua_xmpp|see sample config file]]).
* [b]pua_bla[/b] ([[http://www.kamailio.org/docs/modules/1.5.x/pua_bla.html|see readme file]])-  implements Bridged Line Appearances according to the specifications in draft-anil-sipping-bla-03.txt -([[presence:pua_bla|see sample config file]]).


===== Publish Presence Information Via Management Interface =====

There two new components involved, so small examples to get it started should make people attracted a bit and willing to test. Below is presented the config file and two shell scripts which are able to publish details from the operating system and from Kamailio (OpenSER) statistics.

Beware that you have to create the tables required by [[http://www.kamailio.org/docs/modules/1.2.x/presence.html|presence]] and [[http://www.kamailio.org/docs/modules/1.2.x/pua.html|pua]] modules -- see README of those module for the SQL statements.

==== Kamailio (OpenSER) Configuration file ====

The configuration file is based on default config file which comes with Kamailio (OpenSER). It should allow to identify quickly the changes done to add presence capabilities.

[color=brown]NOTE: the config file and shell scripts use 192.168.2.5 as SIP domain, you have to replace it with the value specific to you.[/color]

<code c>
#
# simple quick-start config script + presence + pua usage
#

# ----------- global configuration parameters ------------------------

/* Uncomment these lines to enter debugging mode */ 
debug=3            # debug level (cmd line: -dddddddddd)
fork=yes
log_stderror=no

check_via=no	# (cmd. line: -v)
dns=no          # (cmd. line: -r)
rev_dns=no      # (cmd. line: -R)
listen=udp:192.168.2.5:5060
children=2
disable_tcp=yes

#
# uncomment the following lines for TLS support
#disable_tls = 0
#listen = tls:your_IP:5061
#tls_verify_server = 1
#tls_verify_client = 1
#tls_require_client_certificate = 0
#tls_method = TLSv1
#tls_certificate = "/usr/local/etc/kamailio/tls/user/user-cert.pem"
#tls_private_key = "/usr/local/etc/kamailio/tls/user/user-privkey.pem"
#tls_ca_list = "/usr/local/etc/kamailio/tls/user/user-calist.pem"

# ------------------ module loading ----------------------------------
mpath="/usr/local/kamailio/lib/modules/"

loadmodule "db_mysql.so"
loadmodule "sl.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "presence.so"
loadmodule "avpops.so"
loadmodule "mi_fifo.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "pua.so"
loadmodule "pua_mi.so"
loadmodule "pua_usrloc.so"

# Uncomment this if you want digest authentication
# mysql.so must be loaded !
#loadmodule "auth.so"
#loadmodule "auth_db.so"

# ----------------- setting module-specific parameters ---------------
modparam("mi_fifo", "fifo_name", "/tmp/openser_fifo")

# -- usrloc params --
# Uncomment this if you want to use SQL database 
# for persistent storage and comment the previous line
modparam("usrloc", "db_mode", 2)

# -- auth params --
# Uncomment if you are using auth module
#
#modparam("auth_db", "calculate_ha1", yes)
#
# If you set "calculate_ha1" parameter to yes (which true in this config), 
# uncomment also the following parameter)
#
#modparam("auth_db", "password_column", "password")

# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)

modparam("pua_usrloc", "default_domain", "192.168.2.5")

# -- presence params --
modparam("presence|^usrloc$|^pua$", "db_url",
	"mysql://openser:openserrw@localhost/openser")
modparam("presence", "force_active", 1)
modparam("presence", "max_expires", 3600)
modparam("presence", "server_address", "sip:192.168.2.5:5060")

# -------------------------  request routing logic -------------------

# main routing logic

route{

			
	# initial sanity checks -- messages with
	# max_forwards==0, or excessively long requests
	if (!mf_process_maxfwd_header("10")) {
		sl_send_reply("483","Too Many Hops");
		exit;
	};

	if (msg:len >=  2048 ) {
		sl_send_reply("513", "Message too big");
		exit;
	};

	# we record-route all messages -- to make sure that
	# subsequent messages will go through our proxy; that's
	# particularly good if upstream and downstream entities
	# use different transport protocol
	if (!method=="REGISTER")
		record_route();

	# subsequent messages withing a dialog should take the
	# path determined by record-routing
	if (loose_route()) {
		# mark routing logic in request
		append_hf("P-hint: rr-enforced\r\n"); 
		route(1);
	};
	if(method == "INVITE")
		setflag(5);

	#if (!uri==myself) {
		# mark routing logic in request
	#	append_hf("P-hint: outbound\r\n"); 
		# if you have some interdomain connections via TLS
		#if(uri=~"@tls_domain1.net") {
		#	t_relay("tls:domain1.net");
		#	exit;
		#} else if(uri=~"@tls_domain2.net") {
		#	t_relay("tls:domain2.net");
		#	exit;
		#}
	#	route(1);
	#};

	# if the request is for other domain use UsrLoc
	# (in case, it does not work, use the following command
	# with proper names and addresses in it)
	if (uri==myself) {

		if( is_method("PUBLISH|SUBSCRIBE"))
			route(2);

		if (method=="REGISTER") {

			# Uncomment this if you want to use digest authentication
			#if (!www_authorize("openser.org", "subscriber")) {
			#	www_challenge("openser.org", "0");
			#	exit;
			#};

			# make pua_usrloc send PUBLISH for phones which do not support presence
			if(!search("^User-Agent: X-Lite"))
				pua_set_publish();

			save("location");
			exit;
		};

		# native SIP destinations are handled using our USRLOC DB
		if (!lookup("location")) {
			sl_send_reply("404", "Not Found");
			exit;
		};
		append_hf("P-hint: usrloc applied\r\n"); 
	};

	route(1);
}


route[1] {
	# send it out now; use stateful forwarding as it works reliably
	# even for UDP2TCP
	if (!t_relay()) {
		sl_reply_error();
	};
	exit;
}

route[2]
{
	sl_send_reply("100","trying");
	if (!t_newtran())
	{
		sl_reply_error();
		exit;
	};

	append_to_reply("Contact: <sip:192.168.2.5:5060>\r\n");
	if(is_method("PUBLISH"))
	{
		handle_publish();
		t_release();
	} 
	else 
	if( is_method("SUBSCRIBE"))
	{
		handle_subscribe();
		t_release();
	}
	
	exit;
}
</code>

==== Publish Details From System ====

The following scrip makes usage of FIFO transport for Management Interface (MI) to publish details from the system:
* [b]U[/b] - logged in users
* [b]C[/b] - CPU in usage by system
* [b]M[/b] - free memory available
* [b]L[/b] - average load in system

To see them, you have to subscribe to user [b]system[/b] of your VoIP platform.

The [b]kamailio-publish-system.sh[/b] script:

<code>
#!/bin/bash
# buld a FIFO command to PUBLISH number of users, load, system CPU usage
#   and freem memory in the system
#

#config values
OP_SYSUSER="system@192.168.2.5"
OP_SIPURI="sip:$OP_SYSUSER"
OP_EXPIRES="124"

# load values
top -n1 | head -n 4 >/tmp/top-head.txt
OP_USERS=`cat /tmp/top-head.txt| head -1 | awk '{print $6}'`
OP_LOAD=`cat /tmp/top-head.txt| head -1 | awk '{print $10 $11 $12+0}'`
OP_SCPU=`cat /tmp/top-head.txt| grep "^Cpu" | awk '{print substr($3,0,index($3,"%"))}'`
OP_FMEM=`cat /tmp/top-head.txt| grep "^Mem" | awk '{print $7}'`

#build reply fifo file
rm -f /tmp/kamailio_fifo_reply
mkfifo /tmp/kamailio_fifo_reply
cat /tmp/kamailio_fifo_reply&

cat >/tmp/kamailio_fifo <<EOF
:pua_publish:kamailio_fifo_reply
$OP_SIPURI
$OP_EXPIRES
presence
application/pidf+xml
.
.
<?xml version='1.0'?><presence xmlns='urn:ietf:params:xml:ns:pidf' xmlns:dm='urn:ietf:params:xml:ns:pidf:data-model' xmlns:rpid='urn:ietf:params:xml:ns:pidf:rpid' xmlns:c='urn:ietf:params:xml:ns:pidf:cipid' entity='$OP_SYSUSER'><tuple id='0x81935a0'><status><basic>open</basic></status></tuple><dm:person id='mi7d748945'><dm:note>U:$OP_USERS/C:$OP_SCPU/M:$OP_FMEM/L:$OP_LOAD</dm:note></dm:person></presence>

EOF

</code>

==== Publish Details From Kamailio (OpenSER) Statistics ====

The following scrip makes usage of FIFO transport for Management Interface (MI) to publish details from Kamailio (OpenSER) statistics:
* [b]U[/b] - user location records 
* [b]T[/b] - active transactions
* [b]R[/b] - processed SIP requests

To see them, you have to subscribe to user [b]system[/b] of your VoIP platform.

The [b]kamailio-publish-stats.sh[/b] script:

<code>
#!/bin/bash
# buld a FIFO command to PUBLISH number of users, load, system CPU usage
#   and freem memory in the system
#

#config values
OP_SYSUSER="system@192.168.2.5"
OP_SIPURI="sip:$OP_SYSUSER"
OP_EXPIRES="124"
OSERCTL="/usr/local/kamailio/sbin/kamctl"

# load values
$OSERCTL  fifo get_statistics all>/tmp/oser-stats.txt
OP_REQS=`cat /tmp/oser-stats.txt| grep "core:rcv_requests" | awk '{print $3}'`
OP_TRANS=`cat /tmp/oser-stats.txt| grep "tm:inuse_transactions" | awk '{print $3}'`
OP_URECS=`cat /tmp/oser-stats.txt| grep "usrloc:location-users" | awk '{print $3}'`

#build reply fifo file
rm -f /tmp/kamailio_fifo_reply
mkfifo /tmp/kamailio_fifo_reply
cat /tmp/kamailio_fifo_reply&

cat >/tmp/kamailio_fifo <<EOF
:pua_publish:kamailio_fifo_reply
$OP_SIPURI
$OP_EXPIRES
presence
application/pidf+xml
.
.
<?xml version='1.0'?><presence xmlns='urn:ietf:params:xml:ns:pidf' xmlns:dm='urn:ietf:params:xml:ns:pidf:data-model' xmlns:rpid='urn:ietf:params:xml:ns:pidf:rpid' xmlns:c='urn:ietf:params:xml:ns:pidf:cipid' entity='$OP_SYSUSER'><tuple id='0x81935a0'><status><basic>open</basic></status></tuple><dm:person id='mi7d748945'><dm:note>U:$OP_URECS/T:$OP_TRANS/R:$OP_REQS</dm:note></dm:person></presence>

EOF

</code>



==== Using With X-Lite 3.0 ====

Below are links to two screenshots of using X-Lite to view published information by the two scripts above:

[[http://www.kamailio.org/downloads/presence/xlite-openser-system.jpg|X-Lite Subscribed to System Details]]

{{http://www.kamailio.org/downloads/presence/xlite-openser-system.jpg}}

[[http://www.kamailio.org/downloads/presence/xlite-openser-stats.jpg|X-Lite Subscribed to Statistics Details]]

{{http://www.kamailio.org/downloads/presence/xlite-openser-stats.jpg}}



===== Download Files =====

Config file and shell scripts can be downloaded from [[http://www.kamailio.org/downloads/presence/]].

===== Presence-Related Stuff =====

{{indexmenu>presence|js}}