OpenXCAP

= Configuration =

== Configure OpenXCAP server ==

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.

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 setup ==

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.

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

== Configure  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.

== Configure  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.

== Configure 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

# --- 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"

# ----------------- setting module-specific parameters ---------------

# -- rr params --

# 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")

# -- 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)

# -- 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)

# -- 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)

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

# 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_ip==10.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;

                    }

                }

            }

            # 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

                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 {

            # 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;

    };

}

}}}

= 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.