Installation guide

Debian unstable installation

Get OpenXCAP's dependencies:

apt-get install python-mysqldb libxml2 python-lxml python-zopeinterface python-twisted python-twisted-web python-twisted-web2 libgnutls13 python-application python-gnutls

For non Debian installations, you must perform the following steps to install OpenXCAP:

  • Download the tarball from http://download.ag-projects.com/OpenXCAP/
  • Extract it using tar -xzvf openxcap-version.tar.gz and change directory to the newly created openxcap directory
  • Run python setup.py install as root.
  • Copy the config.ini.sample file to /etc/openxcap/config.ini and edit it as needed.
  • Copy the startup script, debian/openxcap.init to /etc/init.d/openxcap, and start the service: /etc/init.d/openxcap start

Manual installation

Prerequisites:

To enable TLS support, you need the following libraries:

Database setup

Both OpenXCAP backends (Database and OpenSER) 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_xml, where XCAP documents are stored. The subscriber table is a subset of the subscriber table from OpenSER, xcap table is the same as the one from OpenSER.

Configuration

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 "OpenSER", the specific settings will be taken the corresponding sections, [Database] or [OpenSER].

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 choose from 'basic' and 'digest'. A trusted peer IP list can be defined, he requests matching this list will accepted without the overhead of the HTTP 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 OpenSER.

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

Sample OpenXCAP configuration file

OpenSER configuration

The following OpenSER configuration example enables OpenSER 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. 

# ------------------ module loading ----------------------------------
mpath="/usr/local/openser/lib/openser/modules/"
 
loadmodule "mysql.so"
loadmodule "sl.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "presence.so"
loadmodule "rls.so"
loadmodule "presence_xml.so"
loadmodule "xlog.so"
loadmodule "mi_fifo.so"
loadmodule "mi_xmlrpc.so"
loadmodule "pua.so"
loadmodule "pua_mi.so"
loadmodule "usrloc.so"
loadmodule "permissions.so"

modparam("mi_xmlrpc", "log_file", "/var/log/openser-xmlrpc.log")
modparam("mi_xmlrpc", "port", 8080)

# ----------------- setting module-specific parameters ---------------
 
# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)
 
# -- presence params --
modparam("presence|pua|rls", "db_url", "mysql://openser:password@db/openser")
modparam("presence", "server_address", "sip:10.0.1:5060")
modparam("presence", "fallback2db", 1)

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

# -- rls params --
modparam("rls", "integrated_xcap_server", 1)
modparam("rls", "to_presence_code", 10)

# -- permissions params -- 
modparam("permissions", "db_url", "mysql://openser:password@db/openser")

# -------------------------  request routing logic -------------------
 
# main routing logic
 
route {
    if (!mf_process_maxfwd_header("10")) {
        xlog("L_ERR", "Too many hops");
        if (method!="ACK") {
            force_rport();
            sl_send_reply("483", "Too many hops");
        }   
        return;
    }

    if (msg:len >= max_len) {
        xlog("L_ERR", "Message too big");
        if (method!="ACK") {
            force_rport();
            sl_send_reply("513", "Message too big");
        }   
        return;
    }

    # accept requests only from SIP Proxies that we trust and perform AAA
    if (!allow_trusted()) {
        xlog("L_ERR", "$rm from $fu ($si:$sp) to $tu: Reject with 403, not a trusted party");
        force_rport();
        sl_send_reply("403", "Not a trusted party");
        exit;
    }

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

    if(is_method("PUBLISH")) {
        xlog("L_INFO", "$rm $hdr(event) for $fu ($ua)");
        if (!t_newtran()) {
            sl_reply_error();
            exit;
        };
        handle_publish();
	t_release();

    } else if( is_method("SUBSCRIBE")) {
		
        xlog("L_INFO", "$rm $hdr(event) from $fu to $ru ($ua)");
        if (!t_newtran()) {
            sl_reply_error();
            exit;
        };

        $var(ret_code)= rls_handle_subscribe();
        if($var(ret_code)== 10) {
		handle_subscribe();
        }

        t_release();

    } else {
        xlog("L_INFO", "Method $rm Not Acceptable Here");
        sl_send_reply("488", "Not Acceptable Here");
        exit;
    };
}