Asipto - SIP and VoIP Knowledge Base Site

User Tools

Site Tools

Trace::

Book: SIP Routing With Kamailio

Learn how to build your own real time communication service!
Kamailio Advanced Training - Online
~~~ Click Here for More Details!~~~
kamailio:presence:k31-made-simple
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


—kamailio:presence:k31-made-simple [2010/10/25 20:29] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +====== SIP SIMPLE Presence Made Simple with Kamailio 3.1.x ======
 +
 +<code c>
 +Author: Daniel-Constantin Mierla
 +2010-09-29
 +  * http://www.asipto.com
 +
 +ChangeLog:
 +  * 2010-10-25: updated for Kamailio 3.1.0 release
 +</code>
 +
 +New **open source XCAP server** offered by Kamailio and SER projects can be used with their integrated SIMPLE Presence server or as stand-alone XCAP server.
 +
 +{{http://kb.asipto.com/images/kamailio-pres/xcap.png?200 }}
 +
 +[[http://www.kamailio.org|Kamailio (former OpenSER)]] v3.1.0 was [[http://www.kamailio.org/w/kamailio-openser-v3.1.0-release-notes/|released on October 6, 2010]]. v3.1.0 is the first release in so called 3.1.x series, meaning that any change to 'x' number will not affect database structure or configuration file language, but will mark a new release with bug fixes.
 +
 +The purpose of this document is to show how to build a SIP SIMPLE Presence server with XCAP capabilities. Over past years, SIMPLE extensions became famous for their complexity, by mixing SIP and HTTP and not only. Here we talk about a solution that is simple as concept and easy to deploy, everything relaying on open source and free software.
 +
 +**Kamailio** is used to provide SIP SIMPLE presence server and XCAP server functionalities, and **[[http://www.sip-communicator.org|SIP Communicator]]** (latest build version) is used as SIP softphone.
 +
 +===== About SIP SIMPLE Presence =====
 +
 +Kamailio introduced support for SIP SIMPLE presence many years ago. However, the complexity of specifications and architecture still prevent it to take off properly in the market. One of the show stoppers was the interaction with an XCAP server. XCAP is an XML based protocol using HTTP to carry documents to be stored on server side and used in many case by SIP Presence server. Such documents can be:
 +  * buddy lists - your contacts
 +  * presence access and manipulation rules - who is allowed to see your presence status and how
 +
 +While there are few XCAP server implementations, some are pricey being part of expensive application servers, others require tons of dependencies and practically impossible to install apart of several Linux distributions, enough to keep many SIP implementors far from them.
 +
 +==== References ====
 +
 +More about SIP SIMPLE presence and XCAP:
 +  * RFCs: http://www.ietf.org - RFC3265, RFC3856, RFC3857, RFC3858, RFC 4745, RFC 5025
 +  * Good introduction and examples in IBM WebSphere (R) documentation:
 +    * http://publib.boulder.ibm.com/infocenter/wtelecom/v6r1/index.jsp?topic=/com.ibm.glm.dev.doc/xcap_c.html
 +
 +
 +===== Embedded XCAP Server in Kamailio 3.1.x =====
 +
 +Kamailio 3.0 was able to handle HTTP, used only to process XMLRPC requests. v3.1.0 introduces a new module, xhttp, which is able to handle any kind of HTTP request. In top of it can be used another new module, xcap_server, to process XCAP specific request sent over HTTP.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/kamailio-sip-simple-xcap-server.png?700 }}
 +
 +Worth to mention that xhttp and xcap_server modules are completely independent one from the other. Meaning that if you send XCAP documents over SIP (and that is easy and secure over TLS), Kamailio can handle them, it is just a matter of configuration file.
 +
 +Hopefully, ability of handling XCAP requests over SIP will attract some softphone implementors, since they don't need anymore an HTTP stack.
 +
 +With the new xcap_server module, Kamailio 3.1.x completes the set of components required for a full implementation of SIP SIMPLE Presence server. The key benefits are:
 +  * all-in-one solution - no need for external applications or exotic dependencies
 +  * easy installation - it is installed with kamailio, runs wherever kamailio runs, it needs only libxml2 which is a requirement for the other old presence modules
 +  * you can do XCAP operations via HTTP, HTTPS, and SIP (over TLS, TCP, UDP or SCTP)
 +  * huge scalability - practically, the embedded xhttp and xcap_modules reuse the transport layer for core of Kamailio, meaning you get the same processing rate as for SIP traffic. Also, all the code is compiled, no interpreted language.
 +  * security
 +    * all security modules provided by Kamailio can be used, including digest authentication (you can authenticate with SIP username and password), IP filtering, etc.
 +    * one port for both protocols - Kamailio is able to handle at the same time SIP and HTTP requests sent to port 5060 (or port 5061 in case of TLS connection (SIPS or HTTPS)), therefore less ports that should be left open in your firewall
 +  * lightweight and compact solution - in case you want to run on embedded or limited resources system, you don't get a better option - everything is inside SIP server instance, compiled to machine code.
 +  * simple to use - it is what this document tries to prove
 +
 +You can browse the documentation for xhttp and xcap_server modules at:
 +  * http://kamailio.org/docs/modules/devel/modules/xhttp.html
 +  * http://kamailio.org/docs/modules/devel/modules_k/xcap_server.html
 +
 +===== Deployment Description =====
 +
 +The Operating System used for this tutorial is Ubuntu 10.04, but we will use the generic installation from sources that applies to all Unix/Linux based distributions.
 +
 +Requirements are the same as for old presence modules:
 +  * core requirements: gcc, flex, bison, make, ..., see stock installation guidelines
 +  * mysql server, client tool and library
 +  * libxml2 library and development headers (libxml2-dev)
 +  * optional: libssl library and development headers if you want to do XCAP over HTTPS/SIPS
 +
 +As SIP softphone I used SIP Communicator, latest build, I haven't found a better free or open source alternative with nice GUI. SIP Communicator is written in Java, therefore very portable, apart of its large set of features that includes SIP SIMPLE presence and XCAP support.
 +
 +The main focus in next sections is to show how to configure Kamailio to handle SIP SIMPLE presence and XCAP for storing buddy list and presence rules. There are other extensions of SIP SIMPLE that Kamailio supports, less common in practice, that will be skipped this time.
 +
 +===== Kamailio Installation =====
 +
 +For the sake of cleanness, this tutorial install Kamailio from sources, in a custom directory: /usr/local/kamailio-3.1-xcap. This allows to avoid conflicts with other existing installations and very easy uninstall by just removing that folder. If you want default installation, just remove PREFIX=/usr/local/kamailio-3.1-xcap from 'make cfg' command below.
 +
 +Getting sources from GIT and install:
 +
 +<code>
 +  cd /usr/local/src/
 +  git clone --depth 1 git://git.sip-router.org/sip-router kamailio-3.1.0
 +  cd kamailio-3.1.0
 +  git checkout -b 3.1 origin/3.1
 +  make PREFIX=/usr/local/kamailio-3.1-xcap FLAVOUR=kamailio \
 +          include_modules="db_mysql presence presence_xml xhttp xcap_server" cfg
 +  make all
 +  make install
 +</code>
 +
 +If you prefer to install from APT repository for Debian or Ubuntu distributions, then check:
 +  * http://www.kamailio.org/dokuwiki/doku.php/packages:debs
 +
 +In this case, you have to adapt the commands and content of config for the location of the files installed from deb packages.
 +
 +==== Add users ====
 +
 +Edit /usr/local/kamailio-3.1-xcap/etc/kamailio/kamctlrc to set SIP_DOMAIN=yourdomain (or to your server ip) and DBENGINE=MYSQL.
 +
 +<code c>
 +SIP_DOMAIN=192.168.178.23
 +DBENGINE=MYSQL
 +</code> 
 +
 +Then create the database:
 +
 +<code>
 +/usr/local/kamailio-3.1-xcap/sbin/kamdbctl create
 +</code>
 +
 +Note: be sure you create presence tables.
 +
 +Add your users:
 +
 +<code c>
 +/usr/local/kamailio-3.1-xcap/sbin/kamctl add alice alice123
 +/usr/local/kamailio-3.1-xcap/sbin/kamctl add bob bob123
 +</code>
 +
 +To add users, you can use SIREMIS web management interface, more details about it at:
 +  * http://siremis.asipto.com
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis00.png?600 }}
 +
 +==== Start Kamailio ====
 +
 +For the purpose of particular tutorial, you can start kamailio with:
 +
 +<code>
 +/usr/local/kamailio-3.1-xcap/sbin/kamailio
 +</code>
 +
 +You can stop it with:
 +
 +<code>
 +killall kamailio
 +</code>
 +
 +For alternatives, like init.d scripts for start/stop, see documentation on the website of Kamailio project.
 +
 +==== Configuration File ====
 +
 +Replace /usr/local/kamailio-3.1-xcap/etc/kamailio/kamailio.cfg with:
 +
 +<code c>
 +
 +#!KAMAILIO
 +#
 +# Kamailio (OpenSER) SIP Server v3.1 - default configuration script
 +#     - web: http://www.kamailio.org
 +#     - git: http://sip-router.org
 +#
 +# Direct your questions about this file to: <sr-users@lists.sip-router.org>
 +#
 +# Refer to the Core CookBook at http://www.kamailio.org/dokuwiki/doku.php
 +# for an explanation of possible statements, functions and parameters.
 +#
 +# Several features can be enabled using '#!define WITH_FEATURE' directives:
 +#
 +# *** To run in debug mode: 
 +#     - define WITH_DEBUG
 +#
 +# *** To enable mysql: 
 +#     - define WITH_MYSQL
 +#
 +# *** To enable authentication execute:
 +#     - enable mysql
 +#     - define WITH_AUTH
 +#     - add users using 'kamctl'
 +#
 +# *** To enable IP authentication execute:
 +#     - enable mysql
 +#     - enable authentication
 +#     - define WITH_IPAUTH
 +#     - add IP addresses with group id '1' to 'address' table
 +#
 +# *** To enable persistent user location execute:
 +#     - enable mysql
 +#     - define WITH_USRLOCDB
 +#
 +# *** To enable presence server execute:
 +#     - enable mysql
 +#     - define WITH_PRESENCE
 +#
 +# *** To enable nat traversal execute:
 +#     - define WITH_NAT
 +#     - install RTPProxy: http://www.rtpproxy.org
 +#     - start RTPProxy:
 +#        rtpproxy -l _your_public_ip_ -s udp:localhost:7722
 +#
 +# *** To enable PSTN gateway routing execute:
 +#     - define WITH_PSTN
 +#     - set the value of pstn.gw_ip
 +#     - check route[PSTN] for regexp routing condition
 +#
 +# *** To enable database aliases lookup execute:
 +#     - enable mysql
 +#     - define WITH_ALIASDB
 +#
 +# *** To enable multi-domain support execute:
 +#     - enable mysql
 +#     - define WITH_MULTIDOMAIN
 +#
 +# *** To enable TLS support execute:
 +#     - adjust CFGDIR/tls.cfg as needed
 +#     - define WITH_TLS
 +#
 +# *** To enable anti-flood detection execute:
 +#     - adjust pike and htable=>ipban settings as needed (default is
 +#       block if more than 16 requests in 2 seconds and ban for 300 seconds)
 +#     - define WITH_ANTIFLOOD
 +#
 +# *** To enhance accounting execute:
 +#     - enable mysql
 +#     - define WITH_ACCDB
 +#     - add following columns to database
 +#!ifdef ACCDB_COMMENT
 +  ALTER TABLE acc ADD COLUMN src_user VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE acc ADD COLUMN src_domain VARCHAR(128) NOT NULL DEFAULT '';
 +  ALTER TABLE acc ADD COLUMN dst_ouser VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE acc ADD COLUMN dst_user VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE acc ADD COLUMN dst_domain VARCHAR(128) NOT NULL DEFAULT '';
 +  ALTER TABLE missed_calls ADD COLUMN src_user VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE missed_calls ADD COLUMN src_domain VARCHAR(128) NOT NULL DEFAULT '';
 +  ALTER TABLE missed_calls ADD COLUMN dst_ouser VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE missed_calls ADD COLUMN dst_user VARCHAR(64) NOT NULL DEFAULT '';
 +  ALTER TABLE missed_calls ADD COLUMN dst_domain VARCHAR(128) NOT NULL DEFAULT '';
 +#!endif
 +
 +####### Defined Values #########
 +#!define WITH_MYSQL
 +#!define WITH_AUTH
 +#!define WITH_PRESENCE
 +#!define WITH_XCAPSRV
 +
 +# *** Value defines - IDs used later in config
 +#!ifdef WITH_MYSQL
 +# - database URL - used to connect to database server by modules such
 +#       as: auth_db, acc, usrloc, a.s.o.
 +#!define DBURL "mysql://openser:openserrw@localhost/openser"
 +#!endif
 +#!ifdef WITH_MULTIDOMAIN
 +# - the value for 'use_domain' parameters
 +#!define MULTIDOMAIN 1
 +#!else
 +#!define MULTIDOMAIN 0
 +#!endif
 +
 +# - flags
 +#   FLT_ - per transaction (message) flags
 +# FLB_ - per branch flags
 +#!define FLT_ACC 1
 +#!define FLT_ACCMISSED 2
 +#!define FLT_ACCFAILED 3
 +#!define FLT_NATS 5
 +
 +#!define FLB_NATB 6
 +#!define FLB_NATSIPPING 7
 +
 +####### Global Parameters #########
 +
 +#!ifdef WITH_DEBUG
 +debug=4
 +log_stderror=yes
 +#!else
 +debug=2
 +log_stderror=no
 +#!endif
 +
 +memdbg=5
 +memlog=5
 +
 +log_facility=LOG_LOCAL0
 +
 +fork=yes
 +children=4
 +
 +/* uncomment the next line to disable TCP (default on) */
 +#disable_tcp=yes
 +
 +/* uncomment the next line to disable the auto discovery of local aliases
 +   based on reverse DNS on IPs (default on) */
 +#auto_aliases=no
 +
 +/* add local domain aliases */
 +#alias="sip.mydomain.com"
 +
 +/* uncomment and configure the following line if you want Kamailio to 
 +   bind on a specific interface/port/proto (default bind on all available) */
 +#listen=udp:10.0.0.10:5060
 +
 +/* port to listen to
 + * - can be specified more than once if needed to listen on many ports */
 +port=5060
 +
 +#!ifdef WITH_TLS
 +enable_tls=yes
 +#!endif
 +
 +tcp_connection_lifetime=3604
 +
 +#!ifdef WITH_XCAPSRV
 +tcp_accept_no_cl=yes
 +#!endif
 +
 +####### Custom Parameters #########
 +
 +# These parameters can be modified runtime via RPC interface
 +# - see the documentation of 'cfg_rpc' module.
 +#
 +# Format: group.id = value 'desc' description
 +# Access: $sel(cfg_get.group.id) or @cfg_get.group.id
 +#
 +
 +#!ifdef WITH_PSTN
 +# PSTN GW Routing
 +#
 +# - pstn.gw_ip: valid IP or hostname as string value, example:
 +# pstn.gw_ip = "10.0.0.101" desc "My PSTN GW Address"
 +#
 +# - by default is empty to avoid misrouting
 +pstn.gw_ip = "" desc "PSTN GW Address"
 +#!endif
 +
 +
 +####### Modules Section ########
 +
 +# set paths to location of modules
 +#!ifdef LOCAL_TEST_RUN
 +mpath="modules_k:modules"
 +#!else
 +mpath="/usr/local/kamailio-3.1-xcap/lib/kamailio/modules_k/:/usr/local/kamailio-3.1-xcap/lib/kamailio/modules/"
 +#!endif
 +
 +#!ifdef WITH_MYSQL
 +loadmodule "db_mysql.so"
 +#!endif
 +
 +loadmodule "mi_fifo.so"
 +loadmodule "kex.so"
 +loadmodule "tm.so"
 +loadmodule "tmx.so"
 +loadmodule "sl.so"
 +loadmodule "rr.so"
 +loadmodule "pv.so"
 +loadmodule "maxfwd.so"
 +loadmodule "usrloc.so"
 +loadmodule "registrar.so"
 +loadmodule "textops.so"
 +loadmodule "siputils.so"
 +loadmodule "xlog.so"
 +loadmodule "sanity.so"
 +loadmodule "ctl.so"
 +loadmodule "mi_rpc.so"
 +loadmodule "acc.so"
 +
 +#!ifdef WITH_AUTH
 +loadmodule "auth.so"
 +loadmodule "auth_db.so"
 +#!ifdef WITH_IPAUTH
 +loadmodule "permissions.so"
 +#!endif
 +#!endif
 +
 +#!ifdef WITH_ALIASDB
 +loadmodule "alias_db.so"
 +#!endif
 +
 +#!ifdef WITH_MULTIDOMAIN
 +loadmodule "domain.so"
 +#!endif
 +
 +#!ifdef WITH_PRESENCE
 +loadmodule "presence.so"
 +loadmodule "presence_xml.so"
 +#!endif
 +
 +#!ifdef WITH_NAT
 +loadmodule "nathelper.so"
 +loadmodule "rtpproxy.so"
 +#!endif
 +
 +#!ifdef WITH_TLS
 +loadmodule "tls.so"
 +#!endif
 +
 +#!ifdef WITH_ANTIFLOOD
 +loadmodule "htable.so"
 +loadmodule "pike.so"
 +#!endif
 +
 +#!ifdef WITH_XCAPSRV
 +loadmodule "xhttp.so"
 +loadmodule "xcap_server.so"
 +#!endif
 +
 +# ----------------- setting module-specific parameters ---------------
 +
 +
 +# ----- mi_fifo params -----
 +modparam("mi_fifo", "fifo_name", "/tmp/kamailio_fifo")
 +
 +
 +# ----- tm params -----
 +# auto-discard branches from previous serial forking leg
 +modparam("tm", "failure_reply_mode", 3)
 +# default retransmission timeout: 30sec
 +modparam("tm", "fr_timer", 30000)
 +# default invite retransmission timeout after 1xx: 120sec
 +modparam("tm", "fr_inv_timer", 120000)
 +
 +
 +# ----- rr params -----
 +# add value to ;lr param to cope with most of the UAs
 +modparam("rr", "enable_full_lr", 1)
 +# do not append from tag to the RR (no need for this script)
 +modparam("rr", "append_fromtag", 0)
 +
 +
 +# ----- registrar params -----
 +modparam("registrar", "method_filtering", 1)
 +/* uncomment the next line to disable parallel forking via location */
 +# modparam("registrar", "append_branches", 0)
 +/* uncomment the next line not to allow more than 10 contacts per AOR */
 +#modparam("registrar", "max_contacts", 10)
 +
 +
 +# ----- acc params -----
 +/* what special events should be accounted ? */
 +modparam("acc", "early_media", 0)
 +modparam("acc", "report_ack", 0)
 +modparam("acc", "report_cancels", 0)
 +/* by default ww do not adjust the direct of the sequential requests.
 +   if you enable this parameter, be sure the enable "append_fromtag"
 +   in "rr" module */
 +modparam("acc", "detect_direction", 0)
 +/* account triggers (flags) */
 +modparam("acc", "log_flag", FLT_ACC)
 +modparam("acc", "log_missed_flag", FLT_ACCMISSED)
 +modparam("acc", "log_extra", 
 + "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd")
 +modparam("acc", "failed_transaction_flag", FLT_ACCFAILED)
 +/* enhanced DB accounting */
 +#!ifdef WITH_ACCDB
 +modparam("acc", "db_flag", FLT_ACC)
 +modparam("acc", "db_missed_flag", FLT_ACCMISSED)
 +modparam("acc", "db_url", DBURL)
 +modparam("acc", "db_extra",
 + "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd")
 +#!endif
 +
 +
 +# ----- usrloc params -----
 +/* enable DB persistency for location entries */
 +#!ifdef WITH_USRLOCDB
 +modparam("usrloc", "db_url", DBURL)
 +modparam("usrloc", "db_mode", 2)
 +modparam("usrloc", "use_domain", MULTIDOMAIN)
 +#!endif
 +
 +
 +# ----- auth_db params -----
 +#!ifdef WITH_AUTH
 +modparam("auth_db", "db_url", DBURL)
 +modparam("auth_db", "calculate_ha1", yes)
 +modparam("auth_db", "password_column", "password")
 +modparam("auth_db", "load_credentials", "")
 +modparam("auth_db", "use_domain", MULTIDOMAIN)
 +
 +# ----- permissions params -----
 +#!ifdef WITH_IPAUTH
 +modparam("permissions", "db_url", DBURL)
 +modparam("permissions", "db_mode", 1)
 +#!endif
 +
 +#!endif
 +
 +
 +# ----- alias_db params -----
 +#!ifdef WITH_ALIASDB
 +modparam("alias_db", "db_url", DBURL)
 +modparam("alias_db", "use_domain", MULTIDOMAIN)
 +#!endif
 +
 +
 +# ----- domain params -----
 +#!ifdef WITH_MULTIDOMAIN
 +modparam("domain", "db_url", DBURL)
 +# use caching
 +modparam("domain", "db_mode", 1)
 +# register callback to match myself condition with domains list
 +modparam("domain", "register_myself", 1)
 +#!endif
 +
 +
 +#!ifdef WITH_PRESENCE
 +# ----- presence params -----
 +modparam("presence", "db_url", DBURL)
 +modparam("presence", "fallback2db", 1)
 +modparam("presence", "db_update_period", 20)
 +
 +# ----- presence_xml params -----
 +modparam("presence_xml", "db_url", DBURL)
 +modparam("presence_xml", "force_active", 0)
 +modparam("presence_xml", "integrated_xcap_server", 1)
 +#!endif
 +
 +
 +#!ifdef WITH_NAT
 +# ----- rtpproxy params -----
 +modparam("rtpproxy", "rtpproxy_sock", "udp:127.0.0.1:7722")
 +
 +# ----- nathelper params -----
 +modparam("nathelper", "natping_interval", 30)
 +modparam("nathelper", "ping_nated_only", 1)
 +modparam("nathelper", "sipping_bflag", FLB_NATSIPPING)
 +modparam("nathelper", "sipping_from", "sip:pinger@kamailio.org")
 +
 +# params needed for NAT traversal in other modules
 +modparam("nathelper|registrar", "received_avp", "$avp(RECEIVED)")
 +modparam("usrloc", "nat_bflag", FLB_NATB)
 +#!endif
 +
 +
 +#!ifdef WITH_TLS
 +# ----- tls params -----
 +modparam("tls", "config", "/tmp/kamailio-xcap/etc/kamailio/tls.cfg")
 +#!endif
 +
 +#!ifdef WITH_ANTIFLOOD
 +# ----- pike params -----
 +modparam("pike", "sampling_time_unit", 2)
 +modparam("pike", "reqs_density_per_unit", 16)
 +modparam("pike", "remove_latency", 4)
 +
 +# ----- htable params -----
 +# ip ban htable with autoexpire after 5 minutes
 +modparam("htable", "htable", "ipban=>size=8;autoexpire=300;")
 +#!endif
 +
 +#!ifdef WITH_XCAPSRV
 +# ----- xcap_server params -----
 +modparam("xcap_server", "db_url", DBURL)
 +#!endif
 +
 +####### Routing Logic ########
 +
 +
 +# Main SIP request routing logic
 +# - processing of any incoming SIP request starts with this route
 +route {
 +
 + # per request initial checks
 + route(REQINIT);
 +
 + # NAT detection
 + route(NAT);
 +
 + # handle requests within SIP dialogs
 + route(WITHINDLG);
 +
 + ### only initial requests (no To tag)
 +
 + # CANCEL processing
 + if (is_method("CANCEL"))
 + {
 + if (t_check_trans())
 + t_relay();
 + exit;
 + }
 +
 + t_check_trans();
 +
 + # authentication
 + route(AUTH);
 +
 + # record routing for dialog forming requests (in case they are routed)
 + # - remove preloaded route headers
 + remove_hf("Route");
 + if (is_method("INVITE|SUBSCRIBE"))
 + record_route();
 +
 + # account only INVITEs
 + if (is_method("INVITE"))
 + {
 + setflag(FLT_ACC); # do accounting
 + }
 +
 + # dispatch requests to foreign domains
 + route(SIPOUT);
 +
 + ### requests for my local domains
 +
 + # handle presence related requests
 + route(PRESENCE);
 +
 + # handle registrations
 + route(REGISTRAR);
 +
 + if ($rU==$null)
 + {
 + # request with no Username in RURI
 + sl_send_reply("484","Address Incomplete");
 + exit;
 + }
 +
 + # dispatch destinations to PSTN
 + route(PSTN);
 +
 + # user location service
 + route(LOCATION);
 +
 + route(RELAY);
 +}
 +
 +
 +route[RELAY] {
 +#!ifdef WITH_NAT
 + if (check_route_param("nat=yes")) {
 + setbflag(FLB_NATB);
 + }
 + if (isflagset(FLT_NATS) || isbflagset(FLB_NATB)) {
 + route(RTPPROXY);
 + }
 +#!endif
 +
 + /* example how to enable some additional event routes */
 + if (is_method("INVITE")) {
 + #t_on_branch("BRANCH_ONE");
 + t_on_reply("REPLY_ONE");
 + t_on_failure("FAIL_ONE");
 + }
 +
 + if (!t_relay()) {
 + sl_reply_error();
 + }
 + exit;
 +}
 +
 +# Per SIP request initial checks
 +route[REQINIT] {
 +#!ifdef WITH_ANTIFLOOD
 + # flood dection from same IP and traffic ban for a while
 + # be sure you exclude checking trusted peers, such as pstn gateways
 + # - local host excluded (e.g., loop to self)
 + if(src_ip!=myself)
 + {
 + if($sht(ipban=>$si)!=$null)
 + {
 + # ip is already blocked
 + xdbg("request from blocked IP - $rm from $fu (IP:$si:$sp)\n");
 + exit;
 + }
 + if (!pike_check_req())
 + {
 + xlog("L_ALERT","ALERT: pike blocking $rm from $fu (IP:$si:$sp)\n");
 + $sht(ipban=>$si) = 1;
 + exit;
 + }
 + }
 +#!endif
 +
 + if (!mf_process_maxfwd_header("10")) {
 + sl_send_reply("483","Too Many Hops");
 + exit;
 + }
 +
 + if(!sanity_check("1511", "7"))
 + {
 + xlog("Malformed SIP message from $si:$sp\n");
 + exit;
 + }
 +}
 +
 +# Handle requests within SIP dialogs
 +route[WITHINDLG] {
 + if (has_totag()) {
 + # sequential request withing a dialog should
 + # take the path determined by record-routing
 + if (loose_route()) {
 + if (is_method("BYE")) {
 + setflag(FLT_ACC); # do accounting ...
 + setflag(FLT_ACCFAILED); # ... even if the transaction fails
 + }
 + route(RELAY);
 + } else {
 + if (is_method("SUBSCRIBE") && uri == myself) {
 + # in-dialog subscribe requests
 + route(PRESENCE);
 + exit;
 + }
 + if ( is_method("ACK") ) {
 + if ( t_check_trans() ) {
 + # no loose-route, but stateful ACK;
 + # must be an ACK after a 487
 + # or e.g. 404 from upstream server
 + t_relay();
 + exit;
 + } else {
 + # ACK without matching transaction ... ignore and discard
 + exit;
 + }
 + }
 + sl_send_reply("404","Not here");
 + }
 + exit;
 + }
 +}
 +
 +# Handle SIP registrations
 +route[REGISTRAR] {
 + if (is_method("REGISTER"))
 + {
 + if(isflagset(FLT_NATS))
 + {
 + setbflag(FLB_NATB);
 + # uncomment next line to do SIP NAT pinging 
 + ## setbflag(FLB_SIPPING);
 + }
 + if (!save("location"))
 + sl_reply_error();
 +
 + exit;
 + }
 +}
 +
 +# USER location service
 +route[LOCATION] {
 +
 +#!ifdef WITH_ALIASDB
 + # search in DB-based aliases
 + alias_db_lookup("dbaliases");
 +#!endif
 +
 + if (!lookup("location")) {
 + switch ($rc) {
 + case -1:
 + case -3:
 + t_newtran();
 + t_reply("404", "Not Found");
 + exit;
 + case -2:
 + sl_send_reply("405", "Method Not Allowed");
 + exit;
 + }
 + }
 +
 + # when routing via usrloc, log the missed calls also
 + if (is_method("INVITE"))
 + {
 + setflag(FLT_ACCMISSED);
 + }
 +}
 +
 +# Presence server route
 +route[PRESENCE] {
 + if(!is_method("PUBLISH|SUBSCRIBE"))
 + return;
 +
 +#!ifdef WITH_PRESENCE
 + if (!t_newtran())
 + {
 + sl_reply_error();
 + exit;
 + };
 +
 + if(is_method("PUBLISH"))
 + {
 + handle_publish();
 + t_release();
 + }
 + else
 + if( is_method("SUBSCRIBE"))
 + {
 + handle_subscribe();
 + t_release();
 + }
 + exit;
 +#!endif
 +
 + # if presence enabled, this part will not be executed
 + if (is_method("PUBLISH") || $rU==$null)
 + {
 + sl_send_reply("404", "Not here");
 + exit;
 + }
 + return;
 +}
 +
 +# Authentication route
 +route[AUTH] {
 +#!ifdef WITH_AUTH
 + if (is_method("REGISTER"))
 + {
 + # authenticate the REGISTER requests (uncomment to enable auth)
 + if (!www_authorize("$td", "subscriber"))
 + {
 + www_challenge("$td", "0");
 + exit;
 + }
 +
 + if ($au!=$tU)
 + {
 + sl_send_reply("403","Forbidden auth ID");
 + exit;
 + }
 + } else {
 +
 +#!ifdef WITH_IPAUTH
 + if(allow_source_address())
 + {
 + # source IP allowed
 + return;
 + }
 +#!endif
 +
 + # authenticate if from local subscriber
 + if (from_uri==myself)
 + {
 + if (!proxy_authorize("$fd", "subscriber")) {
 + proxy_challenge("$fd", "0");
 + exit;
 + }
 + if (is_method("PUBLISH"))
 + {
 + if ($au!=$tU) {
 + sl_send_reply("403","Forbidden auth ID");
 + exit;
 + }
 + } else {
 + if ($au!=$fU) {
 + sl_send_reply("403","Forbidden auth ID");
 + exit;
 + }
 + }
 +
 + consume_credentials();
 + # caller authenticated
 + } else {
 + # caller is not local subscriber, then check if it calls
 + # a local destination, otherwise deny, not an open relay here
 + if (!uri==myself)
 + {
 + sl_send_reply("403","Not relaying");
 + exit;
 + }
 + }
 + }
 +#!endif
 + return;
 +}
 +
 +# Caller NAT detection route
 +route[NAT] {
 +#!ifdef WITH_NAT
 + force_rport();
 + if (nat_uac_test("19")) {
 + if (method=="REGISTER") {
 + fix_nated_register();
 + } else {
 + fix_nated_contact();
 + }
 + setflag(FLT_NATS);
 + }
 +#!endif
 + return;
 +}
 +
 +# RTPProxy control
 +route[RTPPROXY] {
 +#!ifdef WITH_NAT
 + if (is_method("BYE")) {
 + unforce_rtp_proxy();
 + } else if (is_method("INVITE")){
 + force_rtp_proxy();
 + }
 + if (!has_totag()) add_rr_param(";nat=yes");
 +#!endif
 + return;
 +}
 +
 +# Routing to foreign domains
 +route[SIPOUT] {
 + if (!uri==myself)
 + {
 + append_hf("P-hint: outbound\r\n");
 + route(RELAY);
 + }
 +}
 +
 +# PSTN GW routing
 +route[PSTN] {
 +#!ifdef WITH_PSTN
 + # check if PSTN GW IP is defined
 + if (strempty($sel(cfg_get.pstn.gw_ip))) {
 + xlog("SCRIPT: PSTN rotuing enabled but pstn.gw_ip not defined\n");
 + return;
 + }
 +
 + # route to PSTN dialed numbers starting with '+' or '00'
 + #     (international format)
 + # - update the condition to match your dialing rules for PSTN routing
 + if(!($rU=~"^(\+|00)[1-9][0-9]{3,20}$"))
 + return;
 +
 + # only local users allowed to call
 + if(from_uri!=myself) {
 + sl_send_reply("403", "Not Allowed");
 + exit;
 + }
 +
 + $ru = "sip:" + $rU + "@" + $sel(cfg_get.pstn.gw_ip);
 +
 + route(RELAY);
 + exit;
 +#!endif
 +
 + return;
 +}
 +
 +# Sample branch router
 +branch_route[BRANCH_ONE] {
 + xdbg("new branch at $ru\n");
 +}
 +
 +# Sample onreply route
 +onreply_route[REPLY_ONE] {
 + xdbg("incoming reply\n");
 +#!ifdef WITH_NAT
 + if ((isflagset(FLT_NATS) || isbflagset(FLB_NATB))
 + && status=~"(183)|(2[0-9][0-9])") {
 + force_rtp_proxy();
 + }
 + if (isbflagset("6")) {
 + fix_nated_contact();
 + }
 +#!endif
 +}
 +
 +# Sample failure route
 +failure_route[FAIL_ONE] {
 +#!ifdef WITH_NAT
 + if (is_method("INVITE")
 + && (isbflagset(FLB_NATB) || isflagset(FLT_NATS))) {
 + unforce_rtp_proxy();
 + }
 +#!endif
 +
 + if (t_is_canceled()) {
 + exit;
 + }
 +
 + # uncomment the following lines if you want to block client 
 + # redirect based on 3xx replies.
 + ##if (t_check_status("3[0-9][0-9]")) {
 + ##t_reply("404","Not found");
 + ## exit;
 + ##}
 +
 + # uncomment the following lines if you want to redirect the failed 
 + # calls to a different new destination
 + ##if (t_check_status("486|408")) {
 + ## sethostport("192.168.2.100:5060");
 + ## append_branch();
 + ## # do not set the missed call flag again
 + ## t_relay();
 + ##}
 +}
 +
 +
 +#!ifdef WITH_XCAPSRV
 +#!define WITH_XHTTPAUTH
 +event_route[xhttp:request] {
 + xdbg("===== xhttp: request [$rv] $rm => $hu\n");
 +#!ifdef WITH_XHTTPAUTH
 + if (!www_authorize("xcap", "subscriber"))
 + {
 + www_challenge("xcap", "0");
 + exit;
 + }
 +#!endif
 + if($hu=~"^/xcap-root/")
 + {
 + set_reply_close();
 + set_reply_no_connect();
 + # xcap ops
 + $xcapuri(u=>data) = $hu;
 + if($xcapuri(u=>xuid)=~"^sip:.+@.+")
 + $var(uri) = $xcapuri(u=>xuid);
 + else if($xcapuri(u=>xuid)=~".+@.+")
 + $var(uri) = "sip:" + $xcapuri(u=>xuid);
 + else
 + $var(uri) = "sip:"+ $xcapuri(u=>xuid) + "@" + $Ri;
 + xlog("===== xhttp: $xcapuri(u=>auid) : $xcapuri(u=>xuid)\n");
 + if($xcapuri(u=>auid)=="xcap-caps")
 + {
 + $var(xbody) =
 +"<?xml version='1.0' encoding='UTF-8'?>
 +<xcap-caps xmlns='urn:ietf:params:xml:ns:xcap-caps'>
 +  <auids>
 +    <auid>rls-services</auid>
 +    <auid>pidf-manipulation</auid>
 +    <auid>xcap-caps</auid>
 +    <auid>resource-lists</auid>
 +    <auid>pres-rules</auid>
 +    <auid>org.openmobilealliance.pres-rules</auid>
 +  </auids>
 +  <extensions>
 +  </extensions>
 +  <namespaces>
 +    <namespace>urn:ietf:params:xml:ns:rls-services</namespace>
 +    <namespace>urn:ietf:params:xml:ns:pidf</namespace>
 +    <namespace>urn:ietf:params:xml:ns:xcap-caps</namespace>
 +    <namespace>urn:ietf:params:xml:ns:resource-lists</namespace>
 +    <namespace>urn:ietf:params:xml:ns:pres-rules</namespace>
 +  </namespaces>
 +</xcap-caps>";
 + xhttp_reply("200", "ok", "application/xcap-caps+xml",
 + "$var(xbody)");
 + exit;
 + }
 +#!ifdef WITH_XHTTPAUTH
 +        # be sure auth user access only its documents
 +        if ($au!=$(var(uri){uri.user})) {
 +            xhttp_reply("403", "Forbidden", "text/html",
 +                    "<html><body>$si:$sp</body></html>");
 +            exit;
 +        }
 +
 +#!endif
 + switch($rm) {
 + case "PUT":
 + xcaps_put("$var(uri)", "$hu", "$rb");
 + if($xcapuri(u=>auid)=~"pres-rules")
 + {
 + xlog("===== xhttp put: refreshing watchers for $var(uri)\n");
 + pres_update_watchers("$var(uri)", "presence");
 + pres_refresh_watchers("$var(uri)", "presence", 1);
 + }
 + exit;
 + break;
 + case "GET":
 + xlog("===== xhttp: get $var(uri) => $hu\n");
 + xcaps_get("$var(uri)", "$hu");
 + exit;
 + break;
 + case "DELETE":
 + xcaps_del("$var(uri)", "$hu");
 + if($xcapuri(u=>auid)=~"pres-rules")
 + {
 + xlog("===== xhttp del: refreshing watchers for $var(uri)\n");
 + pres_update_watchers("$var(uri)", "presence");
 + pres_refresh_watchers("$var(uri)", "presence", 1);
 + }
 + exit;
 + break;
 + }
 + }
 +
 + # http ops
 + xhttp_reply("200", "ok", "text/html",
 + "<html><body>OK: $si:$sp</body></html>");
 + exit;
 +}
 +#!endif
 +</code>
 +
 +Remember that any change in configuration file requires to restart Kamailio SIP server, therefore be sure you do it after replacing the config file with above content.
 +
 +==== Config Remarks ====
 +
 +  * config file is based on default config file coming with 3.1.0 at this time, you can easily do a diff with stock default config to see the changes
 +  * SIMPLE presence features are enabled by #!define WITH_PRESENCE - in addition, user authentication and persistent user location were enabled using as backend a MySQL server
 +  * xcap server features are enabled by #!define WITH_XCAPSRV - just search for WITH_XCAPSRV token to discover the parts related to xcap server functionality
 +
 +Regarding the XCAP server configuration, main part is in **event_route[xhttp:request]**. Digest authentication is enable so that only local subscribers can do XCAP operations. You can tighten the security by being sure the user in XCAP URL is the same as authentication user, avoiding identity stealing.
 +
 +Besides using the **xhttp** and **xcap_server** modules in your config, another important setting is 
 +
 +<code c>
 +tcp_accept_no_cl=yes
 +</code>
 +
 +Without it Kamailio is rejecting requests without content-lenght (a requirement in SIP over TCP but optional in HTTP).
 +
 +A big chunk of XCAP's **event_route** is building the reply for XCAP capabilities query (**xcap-caps**): the assignment of **$var(xbody)**. Maybe in the future will be moved in C code, but having it in config offers a very convenient way to add/remove **auids** as you decide to support or not some of those XCAP extensions.
 +
 +===== SIP Communicator Installation =====
 +
 +You can download latest version for your OS at:
 +  * http://www.sip-communicator.org/
 +
 +Configuration is easy via GUI. Starting SIP Communicator without a SIP account setup and no registration will indicate the state 'offline'.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc00.png }}
 +
 +Select "Add a new account" and fill SIP account details.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc01.png }}
 +
 +Click on "Advanced" to setup Presence and XCAP. Note the XCAP server URI - it must be set to Kamailio's IP (or domain) on port 5060. If you use TLS, then you can set the protocol to https and port 5061.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc02.png }}
 +
 +Click next to see the summary of configuration and then sign in.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc03.png }}
 +
 +After signing in, you can notice the status changed to 'onine'.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc04.png }}
 +
 +Now you can add contacts (you can right-click on buddy list panel). Select the SIP account for that contact, then choose the group and set the SIP ID.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc05.png }}
 +
 +The new contact will appear offline until it will add you in its contact list (specific to this particular version of SIP Communicator).
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc06.png }}
 +
 +Use a second SIP Communicator instance to setup second SIP account, following the steps above and add first account as contact. You can see in next image Alice on left, with Mac OS X, and Bob on right, with Ubuntu. When both instances are setup, each will see the other being 'online'.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc07.png }}
 +
 +As soon as you change the state in one SIP Communicator instance, it will become visible on the other instance. In next image, Bob sets the status to 'Away', the icon on Alice's instance changing to show that.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/sc08.png }}
 +
 +===== Updates in Kamailio DB =====
 +
 +Several screenshots taken with SIREMIS show what was stored in Kamailio database. With Siremis 2.0, 'Presence Services' menu offers the options to view Presence and XCAP database.
 +
 +The Wachers list is showing who is watching who - what users subscribed to presence states of other users.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis05.png?600 }}
 +
 +The Active Watchers list shows who has an active subscription - it is online, waiting for presence status notifications coming from its contacts.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis01.png?600 }}
 +
 +In Presentity list you can view what users published states. In this case, Alice published that she is online.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis03.png?600 }}
 +
 +XCAP list allow access to XCAP documents stored by users on XCAP server. There are two kind of documents in this case: presence rules and resource lists (contact lists).
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis04.png?600 }}
 +
 +A detailed look at resource-lists document for user Alice shows that she has Bob in her contact list.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis02.png?600 }}
 +
 +A detailed look at pres-rules document for user Alice shows that she has allowed Bob to see her presence status.
 +
 +{{ http://kb.asipto.com/images/kamailio-pres/siremis06.png?600 }}
 +
 +===== Additional Tools =====
 +
 +There are more SIP clients implementing SIMPLE Presence extensions than XCAP support. The option is to either offer a web management interface where users can accept people willing to see their status. Also, Kamailio presence module can accept new watchers globally via 'force_active' parameter.
 +
 +Besides these two options, an alternative is to use command line tools. A very handy is **curl**, an application which is very portable and spread across distributions.
 +
 +For example, fetching the buddy list for user Alice:
 +
 +<code>
 +# curl --digest -u alice:alice123 \
 +       http://192.168.178.23:5060/xcap-root/resource-lists/users/sip:alice@192.168.178.23/index
 +
 +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
 +<resource-lists xmlns="urn:ietf:params:xml:ns:resource-lists">
 +<list name="RootGroup">
 +<entry uri="sip:bob@192.168.178.23">
 +<display-name>bob</display-name>
 +</entry>
 +</list>
 +</resource-lists>
 +</code>
 +
 +You can save the result in a file, say buddylist.xml, do any changes you want and then you can upload back with:
 +
 +<code>
 +# curl --digest -u alice:alice123 -T buddylist.xml -X PUT \
 +       http://192.168.178.23:5060/xcap-root/resource-lists/users/sip:alice@192.168.178.23/index
 +</code>
 +
 +Deleting the buddy list document from XCAP server can be done with:
 +
 +<code>
 +# curl --digest -u alice:alice123 -X DELETE \
 +       http://192.168.178.23:5060/xcap-root/resource-lists/users/sip:alice@192.168.178.23/index
 +</code>
 +
 +Similar operations can be done over presence rules document, by using the proper URL:
 +
 +<code>
 +# curl --digest -u alice:alice123 \
 +       http://192.168.178.23:5060/xcap-root/pres-rules/users/sip:alice@192.168.178.23/presrules
 +
 +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
 +<ruleset xmlns="urn:ietf:params:xml:ns:common-policy">
 +<rule id="sip_communicator">
 +<conditions>
 +<identity>
 +<one id="sip:bob@192.168.178.23"/>
 +</identity>
 +</conditions>
 +<actions>
 +<sub-handling xmlns="urn:ietf:params:xml:ns:pres-rules">allow</sub-handling>
 +</actions>
 +<transformations>
 +<provide-devices xmlns="urn:ietf:params:xml:ns:pres-rules">
 +<all-devices/>
 +</provide-devices>
 +<provide-persons xmlns="urn:ietf:params:xml:ns:pres-rules">
 +<all-persons/>
 +</provide-persons>
 +<provide-services xmlns="urn:ietf:params:xml:ns:pres-rules">
 +<all-services/>
 +</provide-services>
 +</transformations>
 +</rule>
 +</ruleset>
 +</code>
 +
 +===== Conclusions =====
 +
 +  * turning Kamailio in an XCAP server is only a matter of configuration (less than 100 lines of configuration, most of them compacted in an event_route, handling authentication as well and XCAP capability reply). XCAP configuration part is not mixed with SIP routing part (btw, you can even use **include_file** directive if you want to keep separate file for XCAP's event_route).
 +  * handling XCAP over either HTTP, HTTPS or SIP is trivial, it is your choice. It is **no need** for a dedicated HTTP server.
 +  * presence server and xcap server are now in the same application instance, therefore tightly integrated
 +  * Kamailio can be used as a standalone XCAP server without problems, allowing other SIP servers to use it in this scope
 +  * you can configure Kamailio to listen on port 80 (or 443) just by adding **port=80** in the configuration file
  

Page Tools

100%

Copyright 2010-2020 Asipto.com