OpenXCAP

= Configuration =

[[TOC(Installation,Configuration,Testing, depth=2)]]

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

=== Create Tables ===

If you use OpenSIPS backend, you do not need to create any tables and configure OpenXCAP to use the same database as OpenSIPS. 

If you want to setup OpenXCAP to use its own database, create the database:

{{{

mysqladmin create openxcap

}}}

and the tables using the script: 

[browser:setup/mysql-create-tables.sql]

This script creates two tables:

 1. subscriber, which is used to authenticate XCAP requests

 1. xcap, where the XCAP documents are actually stored

The subscriber table is a subset of the subscriber table from OpenSIPS, xcap table is the same as the one from OpenSIPS.

=== Add MySQL user ===

Use the following script as template, edit it first and run it against on your database:

{{{

setup/mysql-create-user.sql

}}}

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

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 MySQL database engine has been implemented.

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.

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

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

}}}

You can also start OpenXCAP in no fork mode, which is useful to debug the configuration. This will not put the server in the background and will log its messages in the console where it was started:

{{{

adigeo@ag-imac3:~/work/openxcap$sudo ./openxcap --no-fork

Starting OpenXCAP 1.2.0

Listening on: 0.0.0.0:80

XCAP root: http://xcap.example.com/xcap-root

xcap.server.HTTPFactory starting on 80

}}}

Start opensips-mi-proxy: 

{{{

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

}}}

Start soap-simple-proxy: 

{{{

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

}}}

Start opensips-mi-proxy

{{{

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

}}}

== Logging ==

OpenXCAP logs its start, stop and error messages to /var/log/syslog. Client access requests are logged in /var/log/openxcap/access.log. You can configure the logging of the headers and bodies of client requests and responses in the Logging section of the configuration file.

== Adding Accounts ==

The accounts used for authentication of XCAP requests are stored in OpenSIPS subscriber table. You can add subscribers by using your favorite OpenSIPS subscriber management tool. Check the following script that can be used to add manually account to opensips subscriber table:

[browser:scripts/add-openxcap-user.py]

After completing this chapter, go to [wiki:Testing] section.