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.
Victor Seva
ce718dbc1f
|
13 years ago | |
|---|---|---|
| .. | ||
| doc | 13 years ago | |
| Makefile | 13 years ago | |
| README | 13 years ago | |
| api.h | 13 years ago | |
| list.h | 13 years ago | |
| notify.c | 13 years ago | |
| notify.h | 13 years ago | |
| resource_notify.c | 13 years ago | |
| resource_notify.h | 13 years ago | |
| rls.c | 13 years ago | |
| rls.h | 13 years ago | |
| rls_db.c | 13 years ago | |
| subscribe.c | 13 years ago | |
| subscribe.h | 13 years ago | |
README
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.