OpenXCAP

= Configuration =

OpenXCAP

If you have installed the debian package copy /etc/openxcap/config.ini.sample to /etc/openxcap/config.ini. For other Linux OS copy config.ini.sample from the tar archive to the same directory. Edit config.ini with your settings.

[source:config.ini.sample Sample OpenXCAP configuration file]

The specific settings for an installation must be set from the configuration file, which is split in several configuration sections.

The [Server] section contains global settings: the IP address and port where OpenXCAP listens for client requests.

The XCAP root is the context that contains all the documents across all applications and users that
are managed by the server. Only the client requests that address the root defined here are accepted.
If the root URI has the "https" scheme, the server will listen for requests in TLS mode. The X509
certificate and private key that will identify the server are loaded using the values in the [TLS] section.

OpenXCAP support multiple, interchangeable backend modules. Each backend knows where and how to
authorize and authenticate XCAP users and where to store the XCAP documents. Currently, supported values
are "Database" and "OpenSIPS", the specific settings will be taken the corresponding sections, [Database] or
[OpenSIPS].

An XCAP request must be authenticated before it's handled, and the various settings are found in the
[Authentication] section. The HTTP authentication algorithm can be chosen from 'basic' and 'digest'.
A trusted peer IP list can be defined, requests matching this list will be accepted without authentication.
Client requests must be authenticated in the context of a realm that is the same as the SIP domain. This realm is
derived in real time for each request using the following logic:

• if the user section of the XCAP URI (the section following the "users" path segment) is in the form of username@domain, the realm is taken from the domain part
• some XCAP clients (e.g. CounterPath's Eyebeam), only put the username in the XCAP URI, so there is the need for a convention to determine the realm: it must be included in the XCAP root URI on the client side. For example, if the XCAP root of the server is http://example.com/xcap-root, the client should be provisioned with http://example.com/xcap-root@domain/
• if the above logic does not provide the realm, the realm will be taken from the default_realm setting of [Authentication]

There are separate configuration settings for each backend. The current supported back-ends are Database
and OpenSIPS.

The Database section contains the database connection URI to the database where the service subscribers
are kept (authentication_db_uri) and the database connection URI to the database where XCAP documents are
stored. Currently, only the MySQL database engine has been thoroughly tested.

The OpenSIPS section contains all the settings of the Database section, plus the URL where OpenSIPS's XMLRPC
management interface is listening for commands. The refreshWatchers command is sent to OpenSIPS management
interface to inform the server that the XCAP documents have been changed for a user so that OpenSIPS can send notifications out according to the new policy in real-time.

When using TLS you must generate an X.509 certificate and a key. Consult Internet resources for how to do this. The procedure is the same as for any other TLS server like Apache web server.

Database

Both OpenXCAP backends (Database and OpenSIPS) depend on a database engine to store service subscribers
and XCAP resources. The database creation scripts are found in the scripts/ directory, and involve 2 tables:
subscriber, which is used to authenticate XCAP requests, and xcap, where XCAP documents are stored.
The subscriber table is a subset of the subscriber table from OpenSIPS, xcap table is the same as the one
from OpenSIPS.

opensips-mi-proxy

If you have installed the debian package copy /etc/opensips-mi-proxy/config.ini.sample to /etc/opensips-mi-proxy/config.ini. For other Linux OS copy config.ini.sample from the tar archive to the same directory. Edit config.ini with your settings.

{{{
[OpenSIPS]
socket = /var/run/opensips/socket

[MIProxy]
;listen_url = http://<defaultIPAddress>:8080
;trusted = any
}}}

For more information see the README and INSTALL files that come together with the tar archive.

soap-simple-proxy

If you have installed the debian package copy /etc/soap-simple-proxy/config.ini.sample to /etc/soap-simple-proxy/config.ini. For other Linux OS copy config.ini.sample from the tar archive to the same directory. Edit config.ini with your settings.

{{{
[SOAP Server]
address = 0.0.0.0
port = 9300
log_requests = Yes

[WSDL]
public_service_url = https://example.com/soap-simple-proxy/
internal_service_url = http://private-address:9200/

[XCAP]
root_uri = http://xcap.example.com/xcap-root
}}}

For more information see the README and INSTALL files that come together with the tar archive.

OpenSIPS

The following OpenSIPS configuration example enables OpenSIPS to act like a dedicated SIP Presence server that accepts messages from a trusted SIP Proxy with XCAP authorization enabled using OpenXCAP as policy server. The SIP Proxies defined as trusted peers must be configured to authenticate and authorize the PUBLISH and SUBSCRIBE methods.

Is advisable to consult http://opensips.org web site, documentation section for the up to date configuration and settings.

{{{

listen = 10.0.0.1:5060

1. --- module loading ---

mpath = "/usr/lib/opensips/modules"
loadmodule "mi_fifo.so"
loadmodule "mi_datagram.so"
loadmodule "mysql.so"
loadmodule "sl.so"
loadmodule "maxfwd.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "xlog.so"

loadmodule "presence.so"
loadmodule "presence_xml.so"
loadmodule "presence_mwi.so"
loadmodule "presence_xcapdiff.so"
loadmodule "pua.so"
loadmodule "pua_mi.so"
loadmodule "rls.so"

1. ----------------- setting module-specific parameters ---------------

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

modparam("mi_datagram", "socket_name", "/var/run/opensips/socket")
modparam("mi_datagram", "unix_socket_user", "opensips")
modparam("mi_datagram", "unix_socket_group", "opensips")

modparam("mi_fifo", "fifo_name", "/var/run/opensips/fifo")
modparam("mi_fifo", "fifo_user", "opensips")
modparam("mi_fifo", "fifo_group", "opensips")

1. -- presence params --
   modparam("presence", "db_url", "mysql://opensips:password@db/opensips")
   modparam("presence", "server_address", "sip:presence@10.0.0.1")
   modparam("presence", "fallback2db", 1)
   modparam("presence", "clean_period", 30)

1. -- xcap params --
   modparam("presence_xml", "db_url", "mysql://opensips:password@db/opensips")
   modparam("presence_xml", "force_active", 0)
   modparam("presence_xml", "pidf_manipulation", 1)
   modparam("presence_xml", "integrated_xcap_server", 1)

1. -- rls params --

modparam("rls", "db_url", "mysql://opensips:password@db/opensips")
modparam("rls", "server_address", "sip:rls@10.0.0.1")
modparam("rls", "to_presence_code", 5)
modparam("rls", "integrated_xcap_server", 1)

1. ------------------------- request routing logic -------------------

1. main routing logic

route {
xlog("L_INFO", "----- Start routing");

if ((method=="PUBLISH" || method=="SUBSCRIBE" || method=="NOTIFY")) {
        xlog("L_INFO", "Presence event: $hdr(Event)\n");
    }

if(is_method("PUBLISH")) {
        if ((src_ip==10.0.0.1 && src_port==5060)) {  
            sl_send_reply("404", "Domain not served here");
            return;
        }
        if (is_from_local()) {
            if (avp_check("$hdr(Event)", "fm/presence*/i") && ($au != $rU || $ar != $rd)) {
                xlog("L_WARN", "Account $au@$ar tried to publish $hdr(Event) event for $ru\n");
                sl_send_reply("403", "Publishing $hdr(Event) events for others is forbidden");
               return; 
            }
       } else {
            sl_send_reply("403", "PUBLISH forbidden for outside domains");
            return;
        }

if (t_newtran()) {  
            handle_publish();
            t_release();
        } else {
            sl_reply_error();
        }
        exit;
    } else if( is_method("NOTIFY"))
        if (has_totag()) {
            if (!loose_route()) {
                if (!t_newtran()) {
                    sl_reply_error();
                    exit;
                }
                rls_handle_notify();
                switch ($retcode) {
                case 1:
            # Notify processed by rls
                    xlog("L_INFO", "$rm processed by RLS\n");
                    t_release();
                    exit;
                    break;
                case -1:
            # Error
                    xlog("L_INFO", "$rm processed by RLS but has error\n");
                    t_reply("500", "Server error while processing RLS NOTIFY");
                    exit;
                    break;
                default:
                    if (uri  "sip:rls@10.0.0.1") {
                        xlog("L_ERR", "$rm should be processed by RLS but was not recognized\n");
                        xlog("L_INFO", "Dropping $rm because it will loop\n");
                        t_reply("500", "Server error while processing RLS NOTIFY");
                        exit;  
                    } else {   
                        xlog("L_INFO", "$rm handled by presence\n");
                        t_release();
                    }
                }
            }
        } else {
    # Out-of-dialog NOTIFY
            sl_send_reply("405", "Method Not Allowed");
            exit;
        }

} else if( is_method("SUBSCRIBE")) {
        if (!has_totag()) {
            if (loose_route()) {
                xlog("L_ERR", "Incorrectly formatted $rm request. Rejected.\n");
                sl_send_reply("400", "Incorrectly formatted request");
                return;
            }

if ((src_ip10.0.0.1 && src_port==5060) && is_present_hf("Record-Route")) {
                sl_send_reply("404", "Domain not served here");
                return;
            }

if (is_from_local()) {
                   if (!(src_ip==10.0.0.1 && src_port==5060)) {
                       xlog("L_INFO", "Request came directly from the subscriber\n");
                        setflag(18);
                   }

if ((avp_check("$hdr(Event)", "fm/*.winfo/i") || avp_check("$hdr(Event)", "eq/message-summary/i")) &&
                        ($au != $rU || $ar != $rd)) {
                        xlog("L_WARN", "Account $au@$ar tried to subscribe to $ru for $hdr(Event)\n");
                        sl_send_reply("403", "Subscription to others $hdr(Event) is forbidden");
                        return;
                    }
                }
            }

1. Internal presence handling
   if (!t_newtran()) {
   sl_reply_error();
   exit;
   }

rls_handle_subscribe();

switch ($retcode) {
case 5: # RLS indicated that message should be processed by presence

1. In-dialog SUBSCRIBE
   if (uri=="sip:presence@10.0.0.1" || uri=="sip:rls@10.0.0.1" || !loose_route()) { # Internal presence handling
   if (t_newtran()) {
   rls_handle_subscribe();
   if ($retcode==5) {
   handle_subscribe();
   }
   t_release();
   } else {
   sl_reply_error();
   }
   exit;
   }
   }
   } else {
   xlog("L_INFO", "Method $rm Not Acceptable Here");
   sl_send_reply("488", "Not Acceptable Here");
   exit;
   };
   }
   }}}

if (is_uri_host_local()) {
                    if (does_uri_exist()) {
                        handle_subscribe();
                        t_release();
                    } else {   
                        t_reply("404", "User not found");
                    }
                    exit;
                }
                break;
            default:
                t_release();   
                exit;
            }
        } else {

= Running the server =

For non Debian systems copy openxcap, soap-simple-proxy and opensips-mi-proxy startup scripts from their debian directory present in each tar file to /etc/init.d/ and edit them to match your system.

Start OpenXCAP server:

{{{
/etc/init.d/openxcap start
}}}

Start opensips-mi-proxy:

{{{
/etc/init.d/opensips-mi-proxy start
}}}

Start soap-simple-proxy:

{{{
/etc/init.d/soap-simple-proxy start
}}}

OpenXCAP logs its messages to /var/log/openxcap/. All other servers log their messages to the system syslog. Check the log files for any startup or runtime errors.

Creating user accounts

The user accounts are stored in OpenSIPS subscriber table. You can add subscribers by using your favorite OpenSIPS subscriber management tool.