mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
672 lines
19 KiB
672 lines
19 KiB
Resource List Server
|
|
|
|
Anca-Maria Vamanu
|
|
|
|
Voice Sistem SRL
|
|
|
|
Edited by
|
|
|
|
Anca-Maria Vamanu
|
|
|
|
Copyright © 2007 Voice Sistem SRL
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. db_url(str)
|
|
3.2. rlpres_db_url(str)
|
|
3.3. xcap_db_url(str)
|
|
3.4. db_mode(int)
|
|
3.5. xcap_table(str)
|
|
3.6. rlsubs_table(str)
|
|
3.7. rlpres_table(str)
|
|
3.8. clean_period (int)
|
|
3.9. rlpres_clean_period (int)
|
|
3.10. waitn_time (int)
|
|
3.11. notifier_poll_rate (int)
|
|
3.12. notifier_processes (int)
|
|
3.13. max_expires (int)
|
|
3.14. expires_offset (int)
|
|
3.15. hash_size (int)
|
|
3.16. xcap_root (str)
|
|
3.17. integrated_xcap_server (int)
|
|
3.18. to_presence_code (int)
|
|
3.19. rls_event (str)
|
|
3.20. outbound_proxy (str)
|
|
3.21. server_address (str)
|
|
3.22. max_notify_body_length (int)
|
|
3.23. fetch_rows (integer)
|
|
3.24. disable_remote_presence (integer)
|
|
3.25. max_backend_subs (integer)
|
|
|
|
4. Functions
|
|
|
|
4.1. rls_handle_subscribe([watcher_uri])
|
|
4.2. rls_handle_notify()
|
|
4.3. rls_update_subs(uri, event)
|
|
|
|
5. MI Commands
|
|
|
|
5.1. rls_cleanup
|
|
|
|
6. Installation
|
|
|
|
2. Developer Guide
|
|
|
|
List of Examples
|
|
|
|
1.1. Set db_url parameter
|
|
1.2. Set rlpres_db_url parameter
|
|
1.3. Set xcap_db_url parameter
|
|
1.4. Set db_mode parameter
|
|
1.5. Set xcap_table parameter
|
|
1.6. Set rlsubs_table parameter
|
|
1.7. Set rlpres_table parameter
|
|
1.8. Set clean_period parameter
|
|
1.9. Set rlpres_clean_period parameter
|
|
1.10. Set waitn_time parameter
|
|
1.11. Set notifier_poll_rate parameter
|
|
1.12. Set notifier_processes parameter
|
|
1.13. Set max_expires parameter
|
|
1.14. Set expires_offset parameter
|
|
1.15. Set hash_size parameter
|
|
1.16. Set hash_size parameter
|
|
1.17. Set integrated_xcap_server parameter
|
|
1.18. Set to_presence_code parameter
|
|
1.19. Set rls_event parameter
|
|
1.20. Set outbound_proxy parameter
|
|
1.21. Set server_address parameter
|
|
1.22. Set max_notify_body_length parameter
|
|
1.23. Set fetch_rows parameter
|
|
1.24. Set disable_remote_presence parameter
|
|
1.25. Set max_backend_subs parameter
|
|
1.26. rls_handle_subscribe usage
|
|
1.27. rls_handle_notify usage
|
|
1.28. rls_update_subs usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. db_url(str)
|
|
3.2. rlpres_db_url(str)
|
|
3.3. xcap_db_url(str)
|
|
3.4. db_mode(int)
|
|
3.5. xcap_table(str)
|
|
3.6. rlsubs_table(str)
|
|
3.7. rlpres_table(str)
|
|
3.8. clean_period (int)
|
|
3.9. rlpres_clean_period (int)
|
|
3.10. waitn_time (int)
|
|
3.11. notifier_poll_rate (int)
|
|
3.12. notifier_processes (int)
|
|
3.13. max_expires (int)
|
|
3.14. expires_offset (int)
|
|
3.15. hash_size (int)
|
|
3.16. xcap_root (str)
|
|
3.17. integrated_xcap_server (int)
|
|
3.18. to_presence_code (int)
|
|
3.19. rls_event (str)
|
|
3.20. outbound_proxy (str)
|
|
3.21. server_address (str)
|
|
3.22. max_notify_body_length (int)
|
|
3.23. fetch_rows (integer)
|
|
3.24. disable_remote_presence (integer)
|
|
3.25. max_backend_subs (integer)
|
|
|
|
4. Functions
|
|
|
|
4.1. rls_handle_subscribe([watcher_uri])
|
|
4.2. rls_handle_notify()
|
|
4.3. rls_update_subs(uri, event)
|
|
|
|
5. MI Commands
|
|
|
|
5.1. rls_cleanup
|
|
|
|
6. Installation
|
|
|
|
1. Overview
|
|
|
|
The modules is a Resource List Server implementation following the
|
|
specification in RFC 4662 and RFC 4826.
|
|
|
|
The server is independent from local presence servers, retrieving
|
|
presence information with Subscribe-Notify messages.
|
|
|
|
The module uses the presence module as a library, as it requires a
|
|
resembling mechanism for handling Subscribe. Therefore, in case the
|
|
local presence server is not collocated on the same machine with the RL
|
|
server, the presence module should be loaded in a library mode only
|
|
(see doc for presence module).
|
|
|
|
It handles subscription to lists in an event independent way.The
|
|
default event is presence, but if some other events are to be handled
|
|
by the server, they should be added using the module parameter
|
|
"rls_events".
|
|
|
|
It works with XCAP server for storage. There is also the possibility to
|
|
configure it to work in an integrated_xcap server mode, when it only
|
|
queries database for the resource lists documents. This is useful in a
|
|
small architecture when all the clients use an integrated server and
|
|
there are no references to exterior documents in their lists.
|
|
|
|
The same as presence module, it has a caching mode with periodical
|
|
update in database for subscribe information. The information retrieved
|
|
with Notify messages is stored in database only.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* a database module.
|
|
* sl.
|
|
* tm.
|
|
* presence- in a library mode.
|
|
* pua.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
* libxml.
|
|
|
|
3. Parameters
|
|
|
|
3.1. db_url(str)
|
|
3.2. rlpres_db_url(str)
|
|
3.3. xcap_db_url(str)
|
|
3.4. db_mode(int)
|
|
3.5. xcap_table(str)
|
|
3.6. rlsubs_table(str)
|
|
3.7. rlpres_table(str)
|
|
3.8. clean_period (int)
|
|
3.9. rlpres_clean_period (int)
|
|
3.10. waitn_time (int)
|
|
3.11. notifier_poll_rate (int)
|
|
3.12. notifier_processes (int)
|
|
3.13. max_expires (int)
|
|
3.14. expires_offset (int)
|
|
3.15. hash_size (int)
|
|
3.16. xcap_root (str)
|
|
3.17. integrated_xcap_server (int)
|
|
3.18. to_presence_code (int)
|
|
3.19. rls_event (str)
|
|
3.20. outbound_proxy (str)
|
|
3.21. server_address (str)
|
|
3.22. max_notify_body_length (int)
|
|
3.23. fetch_rows (integer)
|
|
3.24. disable_remote_presence (integer)
|
|
3.25. max_backend_subs (integer)
|
|
|
|
3.1. db_url(str)
|
|
|
|
The database url.
|
|
|
|
Default value is “mysql://openser:openserrw@localhost/openser”.
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("rls", "db_url", "dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.2. rlpres_db_url(str)
|
|
|
|
The rlpres (rls_presentity table) database url. This parameter only
|
|
needs to be specified if the rls_watchers table and rls_presentity
|
|
tables are in different databases. rls_presentity is used to cache the
|
|
bodies of back-end NOTIFY requests until an RLS NOTIFY can be sent. On
|
|
a multi-server system having a single cache for all active servers can
|
|
cause issues if both servers try to send RLS NOTIFY requests at the
|
|
same time. This parameter enables each server to have its own (possibly
|
|
local) rls_presentity table.
|
|
|
|
Default value is a mirror of the “db_url” setting.
|
|
|
|
Example 1.2. Set rlpres_db_url parameter
|
|
...
|
|
modparam("rls", "rlpres_db_url", "dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.3. xcap_db_url(str)
|
|
|
|
The xcap database url. This parameter only needs to be specified if the
|
|
rls db and integerated xcap server db have different urls.
|
|
|
|
Default value is a mirror of the “db_url” setting.
|
|
|
|
Example 1.3. Set xcap_db_url parameter
|
|
...
|
|
modparam("rls", "xcap_db_url", "dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.4. db_mode(int)
|
|
|
|
The module supports 2 modes of operation, high speed memory based
|
|
storage (mode 0), and database only (mode 2) where all data is stored
|
|
in a database, allowing scalability at the expense of speed. Mode 1 is
|
|
reserved.
|
|
|
|
Default value is “0”
|
|
|
|
Example 1.4. Set db_mode parameter
|
|
...
|
|
modparam("rls", "db_mode", 2)
|
|
...
|
|
|
|
3.5. xcap_table(str)
|
|
|
|
The name of the xcap table in which the integrated server or the
|
|
xcap_client module writes. If integrated_xcap_server parameter not set,
|
|
the name of the table must be the same as the one set for the
|
|
xcap_client module.
|
|
|
|
Default value is “xcap”.
|
|
|
|
Example 1.5. Set xcap_table parameter
|
|
...
|
|
modparam("rls", "xcap_table", "xcaps");
|
|
...
|
|
|
|
3.6. rlsubs_table(str)
|
|
|
|
The name of the db table where resource lists subscription information
|
|
is stored.
|
|
|
|
Default value is “rls_watchers”.
|
|
|
|
Example 1.6. Set rlsubs_table parameter
|
|
...
|
|
modparam("rls", "rlsubs_table", "rls_subscriptions")
|
|
...
|
|
|
|
3.7. rlpres_table(str)
|
|
|
|
The name of the db table where notified event specific information is
|
|
stored.
|
|
|
|
Default value is “rls_presentity”.
|
|
|
|
Example 1.7. Set rlpres_table parameter
|
|
...
|
|
modparam("rls", "rlpres_table", "rls_notify")
|
|
...
|
|
|
|
3.8. clean_period (int)
|
|
|
|
The period at which to check for expired information. 0 means do not
|
|
check.
|
|
|
|
Default value is “100”.
|
|
|
|
Example 1.8. Set clean_period parameter
|
|
...
|
|
modparam("rls", "clean_period", 100)
|
|
...
|
|
|
|
3.9. rlpres_clean_period (int)
|
|
|
|
The period at which to check for expired rls_presentity information. -1
|
|
means do not use (clean_period) is used instead. 0 means do not check.
|
|
This option can be used when you want to check rls_presentity and
|
|
rls_watchers on different timeouts. This is useful when they are in
|
|
different databases.
|
|
|
|
Default value is “-1”.
|
|
|
|
Example 1.9. Set rlpres_clean_period parameter
|
|
...
|
|
modparam("rls", "rlpres_clean_period", 100)
|
|
...
|
|
|
|
3.10. waitn_time (int)
|
|
|
|
The maximum time period that RLS NOTIFY requests will be buffered for.
|
|
The server will attempt to send NOTIFY requests with the updated
|
|
presence state of the subscribed list or watcher information within
|
|
this many seconds of a change occurring.
|
|
|
|
Default value is “5”.
|
|
|
|
Example 1.10. Set waitn_time parameter
|
|
...
|
|
modparam("rls", "waitn_time", 10)
|
|
...
|
|
|
|
3.11. notifier_poll_rate (int)
|
|
|
|
The number of times per second that the notifier processes should check
|
|
for work. Approximately 1/(waitn_time * notifier_poll_rate *
|
|
notifier_processes) of the pending updates will be sent each time a
|
|
notifier process runs.
|
|
|
|
Separate notifier processes are only run when db_mode is 2 (DB only
|
|
mode).
|
|
|
|
Default value is “10”.
|
|
|
|
Example 1.11. Set notifier_poll_rate parameter
|
|
...
|
|
modparam("rls", "notifier_poll_rate", 20)
|
|
...
|
|
|
|
3.12. notifier_processes (int)
|
|
|
|
The number of notifier processes that should be started.
|
|
|
|
Separate notifier processes are only run when db_mode is 2 (DB only
|
|
mode).
|
|
|
|
Default value is “1”.
|
|
|
|
Example 1.12. Set notifier_processes parameter
|
|
...
|
|
modparam("rls", "notifier_processes", 2)
|
|
...
|
|
|
|
3.13. max_expires (int)
|
|
|
|
The maximum accepted expires for a subscription to a list.
|
|
|
|
Default value is “7200”.
|
|
|
|
Example 1.13. Set max_expires parameter
|
|
...
|
|
modparam("rls", "max_expires", 10800)
|
|
...
|
|
|
|
3.14. expires_offset (int)
|
|
|
|
This paramater only has an effect when the db_mode is DB_ONLY (mode 2).
|
|
When expired subscribers are checked for deletion from the database,
|
|
those that have a value in the expires column which is less than
|
|
current_time - expires_offset are matched. Hence when an offset of zero
|
|
is used, all those that expire prior the current time will be deleted.
|
|
If an offset of 't' is used, only those that expired more than t
|
|
seconds ago are deleted from the database. Negative offsets are treated
|
|
as though an offset of zero was specifed.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.14. Set expires_offset parameter
|
|
...
|
|
modparam("rls", "expires_offset", 0)
|
|
...
|
|
|
|
3.15. hash_size (int)
|
|
|
|
The dimension of the hash table used to store subscription to a list.
|
|
This parameter will be used as the power of 2 when computing table
|
|
size.
|
|
|
|
Default value is “9 (512)”.
|
|
|
|
Example 1.15. Set hash_size parameter
|
|
...
|
|
modparam("rls", "hash_size", 11)
|
|
...
|
|
|
|
3.16. xcap_root (str)
|
|
|
|
The address of the xcap server.
|
|
|
|
Default value is “NULL”.
|
|
|
|
Example 1.16. Set hash_size parameter
|
|
...
|
|
modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")
|
|
...
|
|
|
|
3.17. integrated_xcap_server (int)
|
|
|
|
This parameter should be set if only integrated xcap servers are used
|
|
to store resource lists.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.17. Set integrated_xcap_server parameter
|
|
...
|
|
modparam("rls", "integrated_xcap_server", 1)
|
|
...
|
|
|
|
3.18. to_presence_code (int)
|
|
|
|
The code to be returned by rls_handle_subscribe function if the
|
|
processed Subscribe is not a resource list Subscribe. This code can be
|
|
used in an architecture with presence and rls servers collocated on the
|
|
same machine, to call handle_subscribe on the message causing this
|
|
code.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.18. Set to_presence_code parameter
|
|
...
|
|
modparam("rls", "to_presence_code", 10)
|
|
...
|
|
|
|
3.19. rls_event (str)
|
|
|
|
The default event that RLS handles is presence. If some other events
|
|
should also be handled by RLS they should be added using this
|
|
parameter. It can be set more than once.
|
|
|
|
Default value is “"presence"”.
|
|
|
|
Example 1.19. Set rls_event parameter
|
|
...
|
|
modparam("rls", "rls_event", "dialog;sla")
|
|
...
|
|
|
|
3.20. outbound_proxy (str)
|
|
|
|
The SIP address where to send RLS subscriptions (outbound proxy address
|
|
as SIP URI).
|
|
|
|
Default value is “NULL”.
|
|
|
|
Example 1.20. Set outbound_proxy parameter
|
|
...
|
|
modparam("rls", "outbound_proxy", "sip:presence.kamailio.org")
|
|
...
|
|
|
|
3.21. server_address (str)
|
|
|
|
The address of the server that will be used as a contact in sent
|
|
Subscribe requests and 200 OK replies for Subscribe requests for RLS.
|
|
It is a mandatory parameter.
|
|
|
|
Example 1.21. Set server_address parameter
|
|
...
|
|
modparam("rls", "server_address", "sip:rls@ip.address.ofyour.proxy:5060")
|
|
...
|
|
|
|
3.22. max_notify_body_length (int)
|
|
|
|
The maximum size that the body of a NOTIFY message may be. If set to 0
|
|
(the default), no size limit is applied. Note that this refers only to
|
|
the body, not the complete NOTIFY message.
|
|
|
|
Example 1.22. Set max_notify_body_length parameter
|
|
...
|
|
modparam("rls", "max_notify_body_length", 32000)
|
|
...
|
|
|
|
3.23. fetch_rows (integer)
|
|
|
|
Number of rows to be loaded in one step from database.
|
|
|
|
Default value is 500.
|
|
|
|
Example 1.23. Set fetch_rows parameter
|
|
...
|
|
modparam("rls", "fetch_rows", 1000)
|
|
...
|
|
|
|
3.24. disable_remote_presence (integer)
|
|
|
|
When set to a non-zero value RLS will not perform back-end SUBSCRIBEs
|
|
to non-local presentities. When people have large contact lists RLS
|
|
will make lots of back-end subscriptions for each local subscriber.
|
|
This can be a lot of traffic, and if the contact lists contain
|
|
non-local (as in not on this Kamailio server or cluster) contacts this
|
|
can result in a lot of Internet traffic. Setting this option to a
|
|
non-zero value prevents RLS from performing back-end SUBSCRIBEs for
|
|
remote presentities.
|
|
|
|
Default value is 0
|
|
|
|
Example 1.24. Set disable_remote_presence parameter
|
|
...
|
|
modparam("rls", "disable_remote_presence", 1)
|
|
...
|
|
|
|
3.25. max_backend_subs (integer)
|
|
|
|
When set to a non-zero value RLS will limit the number of back-end
|
|
SUBSCRIBEs for each RLS SUBSCRIBE to this value. Leaving this at the
|
|
default of zero means no limit. When people have large contact lists
|
|
RLS will make lots of back-end subscriptions. This can easily overload
|
|
a system. This option allows you to limit the number of back-end
|
|
SUBSCRIBEs to help prevent overload.
|
|
|
|
Default value is 0
|
|
|
|
Example 1.25. Set max_backend_subs parameter
|
|
...
|
|
modparam("rls", "max_backend_subs", 30)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. rls_handle_subscribe([watcher_uri])
|
|
4.2. rls_handle_notify()
|
|
4.3. rls_update_subs(uri, event)
|
|
|
|
4.1. rls_handle_subscribe([watcher_uri])
|
|
|
|
This function detects if a Subscribe message should be handled by RLS.
|
|
If not it replies with the configured to_presence_code. If it is, it
|
|
extracts the dialog info and sends aggregate Notify requests with
|
|
information for the list.
|
|
|
|
By default this function uses the From: URI from the SUBSCRIBE request
|
|
as the Watcher URI. The optional watcher_uri parameter can be used to
|
|
specify a different Watcher URI, possibly taken from a SIP header like
|
|
P-Asserted-Identity:.
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.26. rls_handle_subscribe usage
|
|
...
|
|
For presence and rls on the same machine:
|
|
modparam("rls", "to_presence_code", 10)
|
|
|
|
if(is_method("SUBSCRIBE"))
|
|
{
|
|
$var(ret_code)= rls_handle_subscribe();
|
|
|
|
if($var(ret_code)== 10)
|
|
handle_subscribe();
|
|
|
|
t_release();
|
|
}
|
|
|
|
For rls only:
|
|
if(is_method("SUBSCRIBE"))
|
|
{
|
|
rls_handle_subscribe();
|
|
t_release();
|
|
}
|
|
|
|
...
|
|
|
|
4.2. rls_handle_notify()
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.27. rls_handle_notify usage
|
|
...
|
|
if(method=="NOTIFY")
|
|
rls_handle_notify();
|
|
...
|
|
|
|
4.3. rls_update_subs(uri, event)
|
|
|
|
This function can be used in configuration to trigger updates to
|
|
resource list subscriptions (for example, after the contents of a
|
|
resource list has changes).
|
|
|
|
Parameters:
|
|
* uri - the uri of the user who made the change and whose resource
|
|
list subscriptions should be updated
|
|
* event - the event package (e.g. presence).
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.28. rls_update_subs usage
|
|
...
|
|
Within event_route[xhttp:request]:
|
|
case "PUT":
|
|
xcaps_put("$var(uri)", "$var(doc_uri)", "$rb");
|
|
if($xcapuri(u=>auid)=~"pres-rules") {
|
|
pres_update_watchers("$var(uri)", "presence");
|
|
pres_refresh_watchers("$var(uri)", "presence", 1);
|
|
} else if ($xcapuri(u=>auid)=~"resource-lists"
|
|
|| $xcapuri(u=>auid)=~"rls-services") {
|
|
rls_update_subs("$var(uri)", "presence");
|
|
}
|
|
exit;
|
|
break;
|
|
...
|
|
|
|
5. MI Commands
|
|
|
|
5.1. rls_cleanup
|
|
|
|
5.1. rls_cleanup
|
|
|
|
Manually triggers the cleanup functions forthe rls_watchers and
|
|
rls_presentity tables. Useful if you have set clean_period to zero or
|
|
less.
|
|
|
|
Name: rls_cleanup
|
|
|
|
Parameters: none
|
|
|
|
MI FIFO Command Format:
|
|
:rls_cleanup:fifo_reply
|
|
_empty_line_
|
|
|
|
6. Installation
|
|
|
|
The module requires 2 tables in Kamailio database: rls_presentity and
|
|
rls_watchers.The SQL syntax to create them can be found in
|
|
rls-create.sql script in the database directories in the
|
|
kamailio/scripts folder. You can also find the complete database
|
|
documentation on the project webpage,
|
|
http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
|
|
|
|
Chapter 2. Developer Guide
|
|
|
|
The module provides no functions to be used in other Kamailio modules.
|