RESOURCE LIST SERVER module
Admin Guide
Section titled “Admin Guide”Overview
Section titled “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.
Dependencies
Section titled “Dependencies”OpenSIPS Modules
Section titled “OpenSIPS Modules”The following modules must be loaded before this module:
- a database module.
- signaling.
- tm.
- presence- in a library mode.
- pua.
- xcap.
External Libraries or Applications
Section titled “External Libraries or Applications”- libxml-dev.
Exported Parameters
Section titled “Exported Parameters”rlsubs_table(str)
Section titled “rlsubs_table(str)”The name of the db table where resource lists subscription information is stored.
Default value is “rls_watchers”.
...modparam("rls", "rlsubs_table", "rls_subscriptions")...rlpres_table(str)
Section titled “rlpres_table(str)”The name of the db table where notified event specific information is stored.
Default value is “rls_presentity”.
...modparam("rls", "rlpres_table", "rls_notify")...clean_period (int)
Section titled “clean_period (int)”The period at which to check for expired information.
Default value is “100”.
...modparam("rls", "clean_period", 100)...waitn_time (int)
Section titled “waitn_time (int)”The timer period at which the server should attempt to send Notifies with the updated presence state of the subscribed list or watcher information.
Default value is “50”.
...modparam("rls", "waitn_time", 10)...max_expires (int)
Section titled “max_expires (int)”The maximum accepted expires for a subscription to a list.
Default value is “7200”.
...modparam("rls", "max_expires", 10800)...hash_size (int)
Section titled “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)“.
...modparam("rls", "hash_size", 11)...xcap_root (str)
Section titled “xcap_root (str)”The address of the xcap server.
Default value is “NULL”.
...modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")...to_presence_code (int)
Section titled “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”.
...modparam("rls", "to_presence_code", 10)...rls_event (str)
Section titled “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"".
...modparam("rls", "rls_event", "dialog;sla")...presence_server (str)
Section titled “presence_server (str)”The address of the presence server. It will be used as outbound proxy for Subscribe requests sent by the RLS server to bouncing on and off the proxy and having to include special processing for this messages in the proxy’s configuration file.
...modparam("rls", "presence_server", "sip:pres@opensips.org:5060")...contact_user (str)
Section titled “contact_user (str)”This is the username that will be used in the Contact header for the 200 OK replies to SUBSCRIBE and in the following in-dialog NOTIFY requests, as well as for the SUBSCRIBE requests that are generated by the RLS server. The IP address, port and transport for the Contact will be automatically determined based on the interface where the SUBSCRIBE was received or sent from.
If set to an empty string, no username will be added to the contact and the contact will be built just out of the IP, port and transport.
Default value is “rls”.
...modparam("rls", "contact_user", "rls")...Exported Functions
Section titled “Exported Functions”rls_handle_subscribe()
Section titled “rls_handle_subscribe()”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.
This function can be used from REQUEST_ROUTE.
...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(); }
...rls_handle_notify()
Section titled “rls_handle_notify()”This function has to be called for Notify messages sent by presence servers in reply to the Subscribe messages sent by RLS.
This function can be used from REQUEST_ROUTE.
It can return 3 codes:
- 1 - the Notify was inside a dialog that was recognized by the RLS server and was processed successfully.
- 2 - the Notify did not belog to a dialog initiated by the RLS server.
- -1 - an error occurred during processing.
...if($rm=="NOTIFY") rls_handle_notify();...Exported MI Functions
Section titled “Exported MI Functions”rls:update_subscriptions
Section titled “rls:update_subscriptions”Replaces obsolete MI command: rls_update_subscriptions.
Triggers updating backend subscriptions after a resources-list or rls-services document has been updated.
Name: rls:update_subscriptions
Parameters:
- presentity_uri : the uri of the user who made the change and whose subscriptions should be updated
MI FIFO Command Format:
opensips-cli -x mi rls:update_subscriptions sip:alice@atlanta.comInstallation
Section titled “Installation”The module requires 2 table in OpenSIPS 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 opensips/scripts folder. You can also find the complete database documentation on the project webpage, https://opensips.org/docs/db/db-schema-devel.html.
Developer Guide
Section titled “Developer Guide”The module provides no functions to be used in other OpenSIPS modules.
Contributors
Section titled “Contributors”By Commit Statistics
Section titled “By Commit Statistics”Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| # | Name | DevScore | Commits | Lines++ | Lines— |
|---|---|---|---|---|---|
| 1. | Anca Vamanu | 104 | 41 | 5463 | 991 |
| 2. | Saúl Ibarra Corretgé (@saghul) | 42 | 18 | 1220 | 780 |
| 3. | Bogdan-Andrei Iancu (@bogdan-iancu) | 30 | 23 | 441 | 145 |
| 4. | Dan Pascu (@danpascu) | 24 | 10 | 484 | 495 |
| 5. | Razvan Crainea (@razvancrainea) | 18 | 16 | 32 | 46 |
| 6. | Liviu Chircu (@liviuchircu) | 18 | 11 | 227 | 248 |
| 7. | Daniel-Constantin Mierla (@miconda) | 9 | 7 | 18 | 15 |
| 8. | Stefan Darius (@dariusstefan) | 9 | 4 | 452 | 60 |
| 9. | Vlad Patrascu (@rvlad-patrascu) | 7 | 5 | 29 | 36 |
| 10. | Henning Westerholt (@henningw) | 7 | 3 | 167 | 117 |
All remaining contributors: Vlad Paiu (@vladpaiu), Walter Doekes (@wdoekes), Maksym Sobolyev (@sobomax), Stanislaw Pitucha, Ovidiu Sas (@ovidiusas), Sergio Gutierrez, Konstantin Bokarius, John Riordan, UnixDev, Ken Rice, Peter Lemenkov (@lemenkov), Julián Moreno Patiño, Edson Gellert Schubert.
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits
(3) ignoring whitespace edits, renamed files and auto-generated files
By Commit Activity
Section titled “By Commit Activity”| # | Name | Commit Activity |
|---|---|---|
| 1. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jan 2008 - Jul 2026 |
| 2. | Stefan Darius (@dariusstefan) | Jun 2026 - Jul 2026 |
| 3. | Razvan Crainea (@razvancrainea) | Feb 2012 - Jun 2026 |
| 4. | Ken Rice | Sep 2025 - Sep 2025 |
| 5. | Liviu Chircu (@liviuchircu) | Mar 2014 - May 2024 |
| 6. | Maksym Sobolyev (@sobomax) | Feb 2023 - Nov 2023 |
| 7. | Dan Pascu (@danpascu) | Aug 2008 - Jul 2019 |
| 8. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Apr 2019 |
| 9. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 10. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
All remaining contributors: Ovidiu Sas (@ovidiusas), Saúl Ibarra Corretgé (@saghul), Vlad Paiu (@vladpaiu), Anca Vamanu, Stanislaw Pitucha, Walter Doekes (@wdoekes), John Riordan, UnixDev, Sergio Gutierrez, Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert.
(1) including any documentation-related commits, excluding merge commits
Documentation
Section titled “Documentation”Contributors
Section titled “Contributors”Last edited by: Razvan Crainea (@razvancrainea), Dan Pascu (@danpascu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu), Saúl Ibarra Corretgé (@saghul), Walter Doekes (@wdoekes), Anca Vamanu, Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert.
License
Section titled “License”All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0