diff --git a/INSTALL b/INSTALL index 97cb277..25d5dd4 100644 --- a/INSTALL +++ b/INSTALL @@ -1,463 +1,459 @@ OpenXCAP -------- -Copyright (c) 2007-2015 AG Projects +Copyright (c) 2007-present AG Projects http://ag-projects.com Home page: http://openxcap.org Installation ------------ Components ---------- * OpenXCAP, the XCAP server itself * opensips-mi-proxy, an optional component that replaces OpenSIPS xml-rpc module that exhibits stability problems, is required to issue the refreshWatchers command in OpenSIPS when the the policy stored in the pres-rules XCAP document for a given presentity has been changed. The proxy has also more features like being able to listen on a custom IP address and provides an access list for the clients allowed to connect * soap-simple-proxy, an optional component that can access XCAP documents using SOAP/XML requests, it can be used to build a web page to perform XCAP requests for pres-rules and pidf-manipulation documents * python-xcaplib, an optional component that can be used for developing an XCAP client or for testing the server using the xcapclient command line utility Dependencies ------------ - * Python 2.5 or 2.6 - http://www.python.org + * Python 2.7 - http://www.python.org * Twisted Core, Twisted Web and Twisted Web 2 >= 8.1.0 - http://twistedmatrix.com * python-lxml >= 2.0.7 - http://codespeak.net/lxml - * python-application >= 1.2.0 - http://pypi.python.org/pypi/python-application - * python-gnutls >=1.8.1 - http://pypi.python.org/pypi/python-gnutls + * python-application >= 1.4.0 - http://pypi.python.org/pypi/python-application + * python-gnutls >= 3.1.0 - http://pypi.python.org/pypi/python-gnutls * python-mysqldb >=1.2.2 - http://pypi.python.org/simple/mysql-python * python-imaging >=1.1.7 - http://pypi.python.org/simple/PIL/ Debian and Ubuntu ----------------- Binary packages are available for Debian and Ubuntu on i386 and amd64 architectures. Install AG Projects debian repository signing key: wget http://download.ag-projects.com/agp-debian-gpg.key -sudo apt-key add agp-debian-gpg.key +sudo apt-key add agp-debian-gpg.key Add the following lines to /etc/apt/sources.list: # Debian Stable deb http://ag-projects.com/debian stable main deb-src http://ag-projects.com/debian stable main # Debian Unstable deb http://ag-projects.com/debian unstable main deb-src http://ag-projects.com/debian unstable main -# Ubuntu Karmic -deb http://ag-projects.com/ubuntu karmic main -deb-src http://ag-projects.com/ubuntu karmic main - -# Ubuntu Lucid -deb http://ag-projects.com/ubuntu lucid main -deb-src http://ag-projects.com/ubuntu lucid main +# Ubuntu (run this as root) +echo "deb http://ag-projects.com/ubuntu `lsb_release -c -s` main" >> /etc/apt/sources.list +echo "deb-src http://ag-projects.com/ubuntu `lsb_release -c -s` main" >> /etc/apt/sources.list Update the list of available packages: sudo apt-get update Install OpenXCAP server: sudo apt-get install openxcap Install opensips-mi-proxy (on the machine running OpenSIPS): sudo apt-get install opensips-mi-proxy Install soap-simple-proxy: sudo apt-get install soap-simple-proxy Install xcap-client library: sudo apt-get install python-xcaplib Tar Archives ------------ OpenXCAP and related software can be downloaded as tar archives from: http://download.ag-projects.com/XCAP/ Extract the software using tar xzvf openxcap-version.tar.gz. Install OpenXCAP: cd openxcap sudo python setup.py install Download and extract opensips-mi-proxy using tar xzvf opensips-mi-proxy-version.tar.gz. Install opensips-mi-proxy: cd opensips-mi-proxy sudo python setup.py install Download soap-simple-proxy and extract it using tar xzvf soap-simple-proxy-version.tar.gz. Install soap-simple-proxy: cd soap-simple-proxy sudo python setup.py install Download python-xcaplib and extract it using tar xzvf python-xcaplib-version.tar.gz. Install python-xcaplib: cd python-xcaplib sudo python setup.py install Version Control Repository -------------------------- The source code is managed using darcs version control tool from http://darcs.net. The darcs repository can be fetched with: darcs get http://devel.ag-projects.com/repositories/openxcap Other packages like python-xcaplib, soap-simple-proxy and opensips-mi-proxy can be obtained in the same way. To obtain the incremental changes after the initial get: cd openxcap darcs pull -a Configuration ------------- 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 sample script: * setup/mysql-create-tables.sql This script creates two tables: * subscriber, which is used to authenticate XCAP requests * 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 For Debian Package the above sql sample scripts are installed in openxcap shared directory, you can locate them using 'dpkg -L openxcap' command. OpenXCAP -------- For 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. 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 ----------------- For 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://:8080 ;trusted = any For more information see the README and INSTALL files that come together with the tar archive. soap-simple-proxy ----------------- For 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. A sample OpenSIPS configuration is available at http://openxcap.org 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 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. 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: Test Suite ---------- A test suite for testing the functionality the server is located in /xcap/test directory. If you have installed the Debian Package you can located the test suite scripts using dpkg -L openxcap command. Configure the credentials of a test account and the xcap root in a configuration file as follows: ~/.xcapclient.ini [Account_test] sip_address=alice@example.com password=123 xcap_root = http://xcap.example.com/xcap-root Replace the xcap_root with the same xcap_root configured in the server and make sure the hostname points to the IP address where the server listens to. Add the same test account to the OpenSIPS subscriber table: INSERT INTO `subscriber` (username,domain,password,ha1) VALUES ('alice','example.com','1234', 'fd7cab2287702c763e7b318b7fb2451a'); Run the test suite: ~$./test.py test_delete (test_attribute.AttributeTest) ... ok test_get (test_attribute.AttributeTest) ... WARNING: test with URI in att_value is disabled ok test_put (test_attribute.AttributeTest) ... ok test_global_auth (test_auth.AuthTest_org_openmobilealliance_pres_rules) ... ok test_users_auth (test_auth.AuthTest_org_openmobilealliance_pres_rules) ... ok test_global_auth (test_auth.AuthTest_pidf_manipulation) ... ok test_users_auth (test_auth.AuthTest_pidf_manipulation) ... ok test_global_auth (test_auth.AuthTest_pres_rules) ... ok test_users_auth (test_auth.AuthTest_pres_rules) ... ok test_global_auth (test_auth.AuthTest_resource_lists) ... ok test_users_auth (test_auth.AuthTest_resource_lists) ... ok test_global_auth (test_auth.AuthTest_rls_services) ... ok test_users_auth (test_auth.AuthTest_rls_services) ... ok test_global_auth (test_auth.AuthTest_test_app) ... ok test_users_auth (test_auth.AuthTest_test_app) ... ok test_global_auth (test_auth.AuthTest_watchers) ... ok test_users_auth (test_auth.AuthTest_watchers) ... ok test_global_auth (test_auth.AuthTest_xcap_caps) ... ok test_users_auth (test_auth.AuthTest_xcap_caps) ... ok test_delete (test_element.ElementTest) ... ok test_get (test_element.ElementTest) ... WARNING: test with URI in att_value is disabled ok test_put_error (test_element.ElementTest) ... ok Testing different ways of inserting an element as described in examples from Section 8.2.3 ... ok Testing PUT requests of form '*[@att="some"]' which require looking into body of PUT ... ok test_replacement (test_element_put.PutElementTest) ... ok test400_1 (test_errors.ErrorsTest) ... ok test400_2 (test_errors.ErrorsTest) ... ok test404 (test_errors.ErrorsTest) ... ok test405 (test_errors.ErrorsTest) ... ok test409 (test_errors.ErrorsTest) ... ok test_gibberish (test_errors.ErrorsTest) ... ok test_conditional_GET (test_etags.ETagTest) ... ok test_conditional_PUT (test_etags.ETagTest) ... ok test_conditional_GET (test_etags.ETagTest2) ... ok test_conditional_PUT (test_etags.ETagTest2) ... ok test_etag_parsing (test_etags.ETagTest2) ... ok test_errors (test_fragment.FragmentTest) ... ok test_success (test_fragment.FragmentTest) ... ok test_has_global (test_global.TestGlobal) ... ok test_no_global (test_global.TestGlobal) ... ok test_ns_bindings (test_nsbindings.NSBindingsTest) ... ok test_pidf_manipulation (test_pidf.PIDFTest) ... ok test_pidf_manipulation (test_presrules.PresenceRulesTest) ... ok test_operations1 (test_resourcelists.DocumentTest) ... ok test_operations2 (test_resourcelists.DocumentTest) ... ok test_operations3 (test_resourcelists.DocumentTest) ... ok test_operations4 (test_resourcelists.DocumentTest) ... ok test_operations1 (test_rlsservices.DocumentTest) ... ok test_operations2 (test_rlsservices.DocumentTest) ... ok test_operations3 (test_rlsservices.DocumentTest) ... ok test_operations4 (test_rlsservices.DocumentTest) ... ok test_get (test_watchers.Test) ... ok test_schema (test_xcap_caps.XCAPCaps) ... ok ---------------------------------------------------------------------- Ran 53 tests in 48.941s Notes: - Running the test suite for a given user will result in the destruction of all xcap documents belonging to that user - Replacing 'test.py' with 'test_something.py' will run only the tests defined in test_something.py xcapclient ---------- A command line client is available in the python-xcaplib package available in same download repository of OpenXCAP server. The client can be used to manipulate full or partial XML documents on XCAP servers (not limited to OpenXCAP) and has a bash shell command line completion facility that makes it very easy to browse through the structure of XML documents based on XPATH. See README of python-xcaplib package for examples on how to create/retrieve a document. diff --git a/README b/README index 6e51929..efa0a73 100644 --- a/README +++ b/README @@ -1,117 +1,117 @@ OpenXCAP -------- Home page: http://openxcap.org Authors ------- Mircea Amarascu Ruud Klaver Lucian Stanescu Denis Bilenko Saul Ibarra Description ----------- OpenXCAP is an open source fully featured XCAP server. An XCAP server is used by SIP SIMPLE clients and servers to manage buddy lists and policy for subscriptions to presence or other types of events published using SIP protocol. OpenXCAP server works out of the box with OpenSIPS Presence Agent. The software is licensed according to the GNU General Public License version 2. For other licensing options please contact sales-request@ag-projects.com Background ---------- XCAP protocol allows a client to read, write, and modify application configuration data stored in XML format on a server. XCAP maps XML document sub-trees and element attributes to HTTP URIs, so that these components can be directly accessed by clients using HTTP protocol. An XCAP server is used by XCAP clients to store data like buddy lists and presence policy in combination with a SIP Presence server that supports PUBLISH, SUBSCRIBE and NOTIFY methods to provide a complete SIP SIMPLE server solution. Features -------- The server is written in Python programming language and implements the -following standards: +following standards: -RFC4825, RFC4826, RFC4827, RFC5025, draft-ietf-simple-xcap-diff-09.txt +RFC4825, RFC4826, RFC4827, RFC5025, 5874 * Suport for multiple domains * Full and partial XML document manipulation * XML schema validation * Supports multiple back-end storage systems * Works out of the box with OpenSIPS Presence agent * TLS encryption and digital certificates using GnuTLS library * Digest or basic HTTP authentication with support for multiple realms * Database passwords can be stored in an encrypted format Supported XCAP applications * XCAP capabilities (auid = xcap-caps). Lists the capabilities of the OpenXCAP server. * Resource lists (auid = resource-lists). A resource lists application is any application that needs access to a list of resources, identified by a URI, to which operations, such as subscriptions, can be applied. * Presence rules (auid = pres-rules, org.openmobilealliance.pres-rules). A Presence Rules application is an application which uses authorization policies, also known as authorization rules, to specify what presence information can be given to which watchers, and when. * RLS services (auid = rls-services). A Resource List Server (RLS) services application is Session Initiation Protocol (SIP) application whereby a server receives SIP SUBSCRIBE requests for resource, and generates subscriptions towards the resource list. See the README file for more details about of the implementation. * PIDF manipulation (auid = pidf-manipulation). Pidf-manipulation application usage defines how XCAP is used to manipulate the contents of PIDF based presence documents. - * XCAP directory (auid = org.openmobilealliance.xcap-directory). + * XCAP directory (auid = org.openmobilealliance.xcap-directory). Lists the documents stored in the XCAP server for a given user. * icon (auid = oma_status-icon). Manipulate the user icon for a given user and provide icon download capability from HTTP clients. * Dialog rules (auid = org.openxcap.dialog-rules). Dialog Rules application is a private application modeled after Presence rules that uses authorization policies, to specify when dialog information can be given to which watchers. * Watchers (auid = org.openxcap.watchers, private application). This application returns the list of watchers from OpenSIPS presence agent. Installation ------------ See INSTALL file. Support ------- The project is developed and supported by AG Projects via the wiki collaboration system provided at http://openxcap.org To open ticket please Register first. The ticketing support system is available only for registered users. Please beware that the support is provided by the community on a best-effort basis. For help on the integration between OpenXCAP and OpenSIPS you may consult the mailing list users@lists.opensips.org. The mailing list archive is available at: http://lists.opensips.org/cgi-bin/mailman/listinfo/users Commercial support ------------------ The software is supported commercially by AG Projects http://ag-projects.com