modules: readme files regenerated - call_control ... [skip ci]
[sip-router] / README
diff --git a/README b/README
index 1a634d0..44645b7 100644 (file)
--- a/README
+++ b/README
 
-sca Module
 
-Andrew Mortensen
+Kamailio v5.2
+=============
 
-   University of Pennsylvania
+https://www.kamailio.org
 
-   Copyright © 2012 Andrew Mortensen, admorten@isc.upenn.edu
-     _________________________________________________________________
+Table of contents
+  I.   About Kamailio
+  II.  Feature List
+  III. Getting started
+  IV.  About the project
+  V.   Obtaining Help
+  VI.  Contributions
+  VII. More Information
 
-   Table of Contents
 
-   1. Admin Guide
+I. About Kamailio
+=================
 
-        1. Overview
-        2. Dependencies
+Kamailio is an industrial-strength, free server for realtime communication,
+based on the Session Initiation Protocol (SIP RFC3261).
 
-              2.1. Modules
+It is engineered to power Realtime Communications such as IP telephony and
+presence infrastructures up to large scale. With embedded support for
+WebSockets/WebRTC, HTTP, XSRP and XMLrpc as well as Json-rpc it's a modern
+server, up to date with current standards on IPv4/IPv6 and TLS security.
 
-        3. Parameters
+Kamailio keeps track of users, sets up multimedia sessions, relays instant
+messages and creates space for new plug-in applications. Its proven
+interoperability guarantees seamless integration with components from other
+vendors, eliminating the risk of a single-vendor trap. Kamailio has
+successfully participated in various interoperability tests in which it worked
+with the products of other leading SIP vendors.
 
-              3.1. domain (str)
-              3.2. hash_table_size (integer)
-              3.3. call_info_max_expires (integer)
-              3.4. line_seize_max_expires (integer)
-              3.5. purge_expired_interval (integer)
-              3.6. db_url (str)
-              3.7. subs_table (str)
-              3.8. db_update_interval (integer)
+The Kamailio software enables a flexible plug-in model for new applications:
+third parties can easily link their plug-ins with the server code and provide
+thereby advanced and customized services. With a modern RPC interface, 3rd
+party application can integrate and interact with services provided by
+Kamailio. By using the EVAPI interface or the embedded HTTP server restful
+applications can be built.
 
-        4. Functions
+Kamailio's performance and robustness allows it to serve millions of users and
+accommodate needs of very large operators. With a low-cost dual-CPU, the
+Kamailio server is able to power IP telephony services in an area as large as
+the Bay Area during peak hours.
 
-              4.1. sca_handle_subscribe() 
-              4.2. sca_call_info_update() 
+The Kamailio server is extremely configurable to allow the creation of various
+routing and admission policies as well as setting up new and customized
+services. Its configurability  allows it to serve many roles: network security
+barrier, presence server, application server,  IMS server or PSTN gateway guard
+(Edge Proxy / Session Border Controller) for example.
 
-        5. Exported RPC Commands
 
-              5.1. sca.all_subscriptions
-              5.2. sca.all_appearances
-              5.3. sca.release_appearance
+II. Feature List
+================
 
-   List of Examples
+Please visit https://www.kamailio.org/ for the most up-to-date feature list.
+Note that as features easily are added as modules, changes can occur quickly.
 
-   1.1. Set domain parameter:
-   1.2. Set hash_table_size:
-   1.3. Set call_info_max_expires:
-   1.4. Set line_seize_max_expires:
-   1.5. Set purge_expired_interval:
-   1.6. Set db_url parameter:
-   1.7. Set subs_table parameter:
-   1.8. Set db_update_interval:
-   1.9. sca_handle_subscribe usage:
-   1.10. sca_call_info_update usage:
+Most of Kamailio's features are implemented as plug-in modules. See
+our web site for a current list.
 
-Chapter 1. Admin Guide
+III. Getting started
+====================
 
-   Table of Contents
+The documentation wiki is an important source of tutorials for installing
+and understanding how Kamailio works:
 
-   1. Overview
-   2. Dependencies
+  * https://www.kamailio.org/wiki/
 
-        2.1. Modules
+The INSTALL document provides more details and guidelines that will help with
+the installation.
 
-   3. Parameters
+Kamailio is composed of a core and additional modules. For each module
+there is a README with documentation on how to configure and use the
+module. These are available in each modules source code directory as well
+as on the kamailio.org web site.
 
-        3.1. domain (str)
-        3.2. hash_table_size (integer)
-        3.3. call_info_max_expires (integer)
-        3.4. line_seize_max_expires (integer)
-        3.5. purge_expired_interval (integer)
-        3.6. db_url (str)
-        3.7. subs_table (str)
-        3.8. db_update_interval (integer)
+We recommend that you continue with reading README-MODULES and then the
+document named INSTALL.
 
-   4. Functions
+IV. About kamailio.org
+========================
 
-        4.1. sca_handle_subscribe() 
-        4.2. sca_call_info_update() 
+The Kamailio project has roots in a line of projects starting with SIP Express
+Router, then OpenSER and now Kamailio. A merge project was started during the
+fall of 2008 by developers from the OpenSER project, recently renamed to
+Kamailio.org, and SIP Express Router (SER) from iptel.org.
 
-   5. Exported RPC Commands
+Kamailio is the result of a merge of the code base and years of experience from
+both developer teams. During the development of the release 4.0, autumn-winter
+of 2012, the merger of the products was completed and a unified product was
+released.
 
-        5.1. sca.all_subscriptions
-        5.2. sca.all_appearances
-        5.3. sca.release_appearance
+See http://www.kamailio.org/ for the story of SER, OpenSER and Kamailio.
 
-1. Overview
+V. Obtaining Help
+=================
 
-   The sca module implements Shared Call Appearances. It handles SUBSCRIBE
-   messages for call-info and line-seize events, and sends call-info NOTIFYs to
-   line subscribers to implement line bridging. The module implements SCA as
-   defined in Broadworks SIP Access Side Extensions Interface Specifications,
-   Release 13.0, version 1, sections 2, 3 and 4.
+We offer best-effort free support for Kamailio. "best-effort" means
+that we try to solve your problems via email as soon as we can,
+subject to available manpower.
 
-   SCA group members are receive call state notifications when other group
-   members participate in calls. An SCA caller can place a call on hold, and
-   the call may be retrieved from hold by another member of the group.
+To receive feedback to your inquiries, we recommend you to subscribe
+to the sr-users mailing list and post your queries there. This mailing
+list is set up for mutual help by the community of Kamailio users and developers.
+To participate in the mailing list, subscribe at the following web address:
+         https://lists.kamailio.org/mailman/listinfo/sr-users
 
-   Subscribers to SCA call-info events SUBSCRIBE to their address-of-record
-   (AoR), asking the application server to send call-info NOTIFYs with line
-   state information as lines in the subscriber group are used.
+The IRC channel #kamailio on freenode.net is a place where to meet and discuss
+with other members of Kamailio community.
 
-   For example, when an SCA subscriber takes the phone off hook, if sends a
-   line-seize SUBSCRIBE to the application server. The application server
-   acknowledges the request, and sends to the subscriber a line-seize NOTIFY
-   with  the appearance index of the line claimed for the subscriber. The
-   application also sends call-info NOTIFYs to the other SCA subscribers to the
-   AoR, letting them know that an appearance within the group has gone off
-   hook. Subscribers update their display appropriately.
+VI. Contributions
+=================
 
-   Subscribers to an SCA address-of-record will receive call-info NOTIFYs when
-   a  member  of the group seizes a line (seized); receives a 180 ringing
-   response  from  the remote party (ringing); receives a 183 progressing
-   response from the remote party (progressing); when the remote party answers
-   the call (active); when either party in the call places the call on hold
-   (held); and when an SCA line goes back on hook (idle).
+Kamailio is an open source project managed and developed by its community.
+Anyone is welcome to join the development efforts and contribute with code,
+documentation or other resources that could help the project.
 
-   The call-info subscriber information is stored in memory and is periodically
-   written to the database. Call state information is stored in memory. A
-   future release may periodically write call state to the database, as well.
-   The database is purely for restoring subscriptions after a restart of the
-   application server. Subscriber information is also flushed to the database
-   when the service is stopped.
+For code contributions, follow the suggestions provided at:
 
-   The  module  implements  SCA  as defined in Broadworks SIP Access Side
-   Extensions Interface Specifications, Release 13.0, version 1, sections 2, 3
-   and 4. At the time of this writing, Polycom and Cisco handsets are known to
-   implement  the  call-info and line-seize event packages defined in the
-   document, which may be found freely on the web.
+  * https://www.kamailio.org/wiki/devel/git-commit-guidelines
 
-   To date, this module has only been tested with Polycom Soundpoint 550s and
-   650s running Polycom SIP 3.3.4.
+The recommended way to contribute code is via pull requests to Kamailio
+project on Github:
 
-2. Dependencies
+  * httpss://github.com/kamailio
 
-   2.1. Modules
+VII. More Information
+=====================
 
-2.1. Modules
+Most up-to-date information is always available at our website,
+                 https://www.kamailio.org/
 
-   The following modules must be loaded before this module:
-     * a database module
-     * sl
-     * tm
+Particularly, it includes:
+- administrator's guide
+- configuration cookbooks (core, pseudovariables and transformations)
+- module documentation
+- installation guidelines (INSTALL)
+- download links
+- etc.
 
-3. Parameters
-
-   3.1. domain (str)
-   3.2. hash_table_size (integer)
-   3.3. call_info_max_expires (integer)
-   3.4. line_seize_max_expires (integer)
-   3.5. purge_expired_interval (integer)
-   3.6. db_url (str)
-   3.7. subs_table (str)
-   3.8. db_update_interval (integer)
-
-3.1. domain (str)
-
-   SIP domain to use in SCA NOTIFY Call-Info headers.
-
-   The module uses this value as the SIP domain in Call-Info headers sent with
-   call-info and line-seize NOTIFYs. The domain must match the domain in the
-   SCA line's address-of-record.
-
-   This parameter is required. A future update of the module may extract this
-   value from client SUBSCRIBEs.
-
-   Example 1.1. Set domain parameter:
-...
-modparam( "sca", "domain", "voice.example.org" )
-...
-
-3.2. hash_table_size (integer)
-
-   Size, as a power of two, of the shared memory hash table containing the
-   call-info subscriptions and the appearance state. A larger power of two
-   means better performance (fewer collisions, making for fewer subscriber URI
-   comparisons) at the expense of increased shared memory use.
-
-   Default value is 9 (2 ^ 9 == 512). 
-
-   Example 1.2. Set hash_table_size:
-...
-# create shared memory hash table with 2^8 (256) slots
-modparam( "sca", "hash_table_size", 8 )
-...
-
-3.3. call_info_max_expires (integer)
-
-   The maximum allowed call-info subscription time in seconds.
-
-   Default value is 3600 (1 hour). 
-
-   Example 1.3. Set call_info_max_expires:
-...
-modparam( "sca", "call_info_max_expires", 1800 )
-...
-
-3.4. line_seize_max_expires (integer)
-
-   The maximum allowed line-seize subscription time in seconds.
-
-   Default value is 15 (15 seconds). 
-
-   A maximum line-seize subscription time of 15 seconds is recommended in the
-   SIP Access Side Extensions document. This interval is purposely short to
-   prevent  a client from seizing an appearance without making a call for
-   extended periods of time.
-
-   Example 1.4. Set line_seize_max_expires:
-...
-modparam( "sca", "line_seize_max_expires", 30 )
-...
-
-3.5. purge_expired_interval (integer)
-
-   The  period of time in seconds between purges of expired call-info and
-   line-seize subscriptions.
-
-   Default value is 120 (2 minutes). 
-
-   On finding an expired subscription, the module removes the subscription from
-   the shared memory hash table, and sends a NOTIFY with Subscription-State
-   "terminated;expired" header value to the subscriber. It also NOTIFYs other
-   members of the group, in the event that the expired subscription was a
-   line-seize.
-
-   Example 1.5. Set purge_expired_interval:
-...
-modparam( "sca", "purge_expired_interval", 60 )
-...
-
-3.6. db_url (str)
-
-   URL of database to which subscribers will be written.
-
-   Default value is mysql://openser:openserrw@localhost/openser
-
-   Example 1.6. Set db_url parameter:
-...
-modparam( "sca", "db_url", "mysql://openser:openserrw@localhost/openser" )
-...
-
-3.7. subs_table (str)
-
-   Name of the database table where call-info subscriptions are written.
-
-   Default value is “sca_subscriptions”. 
-
-   Example 1.7. Set subs_table parameter:
-...
-modparam( "sca", "subs_table", "call_info_subscriptions" )
-...
-
-3.8. db_update_interval (integer)
-
-   Period in seconds between writes of call-info subscriber information to the
-   database.
-
-   Default value is 300 (5 minutes). 
-
-   Example 1.8. Set db_update_interval:
-...
-modparam( "sca", "db_update_interval", 120 )
-...
-
-4. Functions
-
-   4.1. sca_handle_subscribe() 
-   4.2. sca_call_info_update() 
-
-4.1.  sca_handle_subscribe()
-
-   The function handling call-info and line-seize SUBSCRIBE requests. It stores
-   or updates the subscriptions in shared memory, and sends NOTIFYs to the
-   subscriber and other members of the group as needed.
-
-   For example, a line-seize SUBSCRIBE will cause the module to reserve an
-   appearance  index  for the subscriber; send a line-seize NOTIFY to the
-   subscriber indicating which appearance index it must use; and send call-info
-   NOTIFYs to other subscribers to the address-of-record letting them know the
-   appearance is off hook.
-
-   This function can be used from the REQUEST_ROUTE.
-
-   Return code:
-     * 1 - successful
-     * -1 - failed, error logged
-
-   Example 1.9. sca_handle_subscribe usage:
-...
-if ( method == "SUBSCRIBE" &&
-        ( @hf_value.event == "call-info" || @hf_value.event == "line_seize" ))
-{
-    sca_handle_subscribe();
-}
-...
-
-4.2.  sca_call_info_update()
-
-   The sca_call_info_update function updates call state for SCA appearances. If
-   a request or response packet contains a Call-Info header, the function
-   extracts call state from the header and sends NOTIFYs to subscribers if
-   needed. If no Call-Info header is included in the packet, the module looks
-   up the To and From URIs to see if either are SCA addresses-of-record. If
-   either  the  To  or  From URI are SCA, AoRs, the function looks up the
-   appearance by dialog, and updates call state as needed, sending NOTIFYs to
-   members of the group if the call state has changed.
-
-   The sca_call_info_update function updates call state for INVITE, CANCEL,
-   BYE, PRACK and REFER requests and responses.
-
-   This  function  can  be  used from the REQUEST_ROUTE, REPLY_ROUTE, and
-   FAILURE_ROUTE.
-
-   Return code:
-     * 1 - successful
-     * -1 - failed, error logged
-
-   Example 1.10. sca_call_info_update usage:
-...
-route
-{
-    ...
-    if ( $fu.sca == "y" ) {
-        sca_call_info_update();
-    }
-    ...
-}
-
-onreply_route[REPLY_ROUTE]
-{
-...
-    if ( status =~ "[456][0-9][0-9]" ) {
-        # don't update SCA state here, since there may be
-        # failure route processing (e.g., call forwarding).
-        # update state in failure route instead.
-        break;
-    }
-
-    sca_call_info_update();
-...
-}
-
-failure_route[FAILURE_ROUTE]
-{
-...
-    sca_call_info_update();
-...
-}
-...
-
-5. Exported RPC Commands
-
-   5.1. sca.all_subscriptions
-   5.2. sca.all_appearances
-   5.3. sca.release_appearance
-
-5.1. sca.all_subscriptions
-
-   List all current call-info and line-seize subscriptions.
-
-   Name: sca.all_subscriptions
-
-   Parameters: none
-
-   Example:
-            sercmd sca.all_subscriptions
-
-5.2. sca.all_appearances
-
-   List all SCA appearances with non-idle state.
-
-   Name: sca.all_appearances
-
-   Parameters: none
-
-   Example:
-            sercmd sca.all_appearances
-
-5.3. sca.release_appearance
-
-   Set a non-idle appearance index to idle and NOTIFY members of the group.
-
-   Name: sca.release_appearance
-
-   Parameters: 2
-     * SCA Address-of-Record
-     * Appearance Index
-
-   Example:
-            # release appearance of sip:215@voice.example.com with
-            # appearance index 3
-            sercmd sca.release_appearance sip:215@voice.example.com 3
+You can also follow us on Twitter as @kamailio and like us on Facebook
+to get regular updates.