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.
1385 lines
41 KiB
1385 lines
41 KiB
usrloc Module
|
|
|
|
Jan Janak
|
|
|
|
FhG FOKUS
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Jan Janak
|
|
|
|
Edited by
|
|
|
|
Bogdan-Andrei Iancu
|
|
|
|
Edited by
|
|
|
|
Carsten Bock
|
|
|
|
ng-voice GmbH
|
|
|
|
Copyright © 2003 FhG FOKUS
|
|
|
|
Copyright © 2005 Voice Sistem SRL
|
|
|
|
Copyright © 2015 ng-voice GmbH
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
|
|
1.1. Contact matching
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. nat_bflag (integer)
|
|
3.2. user_column (string)
|
|
3.3. domain_column (string)
|
|
3.4. contact_column (string)
|
|
3.5. expires_column (string)
|
|
3.6. q_column (string)
|
|
3.7. callid_column (string)
|
|
3.8. cseq_column (string)
|
|
3.9. methods_column (string)
|
|
3.10. flags_column (string)
|
|
3.11. cflags_column (string)
|
|
3.12. user_agent_column (string)
|
|
3.13. received_column (string)
|
|
3.14. socket_column (string)
|
|
3.15. path_column (string)
|
|
3.16. ruid_column (string)
|
|
3.17. instance_column (string)
|
|
3.18. server_id_column (string)
|
|
3.19. connection_id_column (string)
|
|
3.20. keepalive_column (string)
|
|
3.21. use_domain (integer)
|
|
3.22. desc_time_order (integer)
|
|
3.23. timer_interval (integer)
|
|
3.24. db_url (string)
|
|
3.25. db_mode (integer)
|
|
3.26. matching_mode (integer)
|
|
3.27. cseq_delay (integer)
|
|
3.28. fetch_rows (integer)
|
|
3.29. hash_size (integer)
|
|
3.30. preload (string)
|
|
3.31. db_update_as_insert (string)
|
|
3.32. db_check_update (string)
|
|
3.33. timer_procs (string)
|
|
3.34. xavp_contact (string)
|
|
3.35. db_ops_ruid (int)
|
|
3.36. handle_lost_tcp (int)
|
|
3.37. close_expired_tcp (int)
|
|
3.38. expires_type (int)
|
|
3.39. db_raw_fetch_type (int)
|
|
3.40. db_insert_null (int)
|
|
3.41. skip_remote_socket (int)
|
|
3.42. db_timer_clean (int)
|
|
|
|
4. Functions
|
|
5. MI Commands
|
|
|
|
5.1. ul_rm
|
|
5.2. ul_rm_contact
|
|
5.3. ul_dump
|
|
5.4. ul_flush
|
|
5.5. ul_add
|
|
5.6. ul_show_contact
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. ul.dump
|
|
6.2. ul.lookup table AOR
|
|
6.3. ul.rm table AOR
|
|
6.4. ul.rm_contact table AOR contact
|
|
6.5. ul.flush
|
|
6.6. ul.add
|
|
6.7. ul.db_users
|
|
6.8. ul.db_contacts
|
|
6.9. ul.db_expired_contacts
|
|
|
|
7. Statistics
|
|
|
|
7.1. users
|
|
7.2. contacts
|
|
7.3. expires
|
|
7.4. registered_users
|
|
|
|
2. Developer Guide
|
|
|
|
1. Available Functions
|
|
|
|
1.1. ul_register_domain(name)
|
|
1.2. ul_insert_urecord(domain, aor, rec)
|
|
1.3. ul_delete_urecord(domain, aor)
|
|
1.4. ul_delete_urecord_by_ruid(domain, ruid)
|
|
1.5. ul_get_urecord(domain, aor)
|
|
1.6. ul_lock_udomain(domain)
|
|
1.7. ul_unlock_udomain(domain)
|
|
1.8. ul_release_urecord(record)
|
|
1.9. ul_insert_ucontact(record, contact, expires, q, callid,
|
|
cseq, flags, cont, ua, sock)
|
|
|
|
1.10. ul_delete_ucontact (record, contact)
|
|
1.11. ul_get_ucontact(record, contact)
|
|
1.12. ul_get_all_ucontacts (buf, len, flags)
|
|
1.13. ul_update_ucontact(contact, expires, q, callid, cseq,
|
|
set, res, ua, sock)
|
|
|
|
1.14. ul_bind_ursloc( api )
|
|
1.15. ul_register_ulcb(type ,callback, param)
|
|
1.16. ul_get_num_users()
|
|
|
|
List of Examples
|
|
|
|
1.1. Set nat_bflag parameter
|
|
1.2. Set user_column parameter
|
|
1.3. Set user_column parameter
|
|
1.4. Set contact_column parameter
|
|
1.5. Set expires_column parameter
|
|
1.6. Set q_column parameter
|
|
1.7. Set callid_column parameter
|
|
1.8. Set cseq_column parameter
|
|
1.9. Set methods_column parameter
|
|
1.10. Set flags_column parameter
|
|
1.11. Set cflags_column parameter
|
|
1.12. Set user_agent_column parameter
|
|
1.13. Set received_column parameter
|
|
1.14. Set socket_column parameter
|
|
1.15. Set path_column parameter
|
|
1.16. Set ruid_column parameter
|
|
1.17. Set instance_column parameter
|
|
1.18. Set server_id_column parameter
|
|
1.19. Set connection_id_column parameter
|
|
1.20. Set keepalive_column parameter
|
|
1.21. Set use_domain parameter
|
|
1.22. Set desc_time_order parameter
|
|
1.23. Set timer_interval parameter
|
|
1.24. Set db_url parameter
|
|
1.25. Set db_mode parameter
|
|
1.26. Set matching_mode parameter
|
|
1.27. Set cseq_delay parameter
|
|
1.28. Set fetch_rows parameter
|
|
1.29. Set hash_size parameter
|
|
1.30. Set preload parameter
|
|
1.31. Set db_update_as_insert parameter
|
|
1.32. Set db_check_update parameter
|
|
1.33. Set timer_procs parameter
|
|
1.34. Set xavp_contact parameter
|
|
1.35. Set db_ops_ruid parameter
|
|
1.36. Set handle_lost_tcp parameter
|
|
1.37. Set close_expired_tcp parameter
|
|
1.38. Set expires_type parameter
|
|
1.39. Set db_raw_fetch_type parameter
|
|
1.40. Set db_insert_null parameter
|
|
1.41. Set skip_remote_socket parameter
|
|
1.42. Set db_timer_clean parameter
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
|
|
1.1. Contact matching
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. nat_bflag (integer)
|
|
3.2. user_column (string)
|
|
3.3. domain_column (string)
|
|
3.4. contact_column (string)
|
|
3.5. expires_column (string)
|
|
3.6. q_column (string)
|
|
3.7. callid_column (string)
|
|
3.8. cseq_column (string)
|
|
3.9. methods_column (string)
|
|
3.10. flags_column (string)
|
|
3.11. cflags_column (string)
|
|
3.12. user_agent_column (string)
|
|
3.13. received_column (string)
|
|
3.14. socket_column (string)
|
|
3.15. path_column (string)
|
|
3.16. ruid_column (string)
|
|
3.17. instance_column (string)
|
|
3.18. server_id_column (string)
|
|
3.19. connection_id_column (string)
|
|
3.20. keepalive_column (string)
|
|
3.21. use_domain (integer)
|
|
3.22. desc_time_order (integer)
|
|
3.23. timer_interval (integer)
|
|
3.24. db_url (string)
|
|
3.25. db_mode (integer)
|
|
3.26. matching_mode (integer)
|
|
3.27. cseq_delay (integer)
|
|
3.28. fetch_rows (integer)
|
|
3.29. hash_size (integer)
|
|
3.30. preload (string)
|
|
3.31. db_update_as_insert (string)
|
|
3.32. db_check_update (string)
|
|
3.33. timer_procs (string)
|
|
3.34. xavp_contact (string)
|
|
3.35. db_ops_ruid (int)
|
|
3.36. handle_lost_tcp (int)
|
|
3.37. close_expired_tcp (int)
|
|
3.38. expires_type (int)
|
|
3.39. db_raw_fetch_type (int)
|
|
3.40. db_insert_null (int)
|
|
3.41. skip_remote_socket (int)
|
|
3.42. db_timer_clean (int)
|
|
|
|
4. Functions
|
|
5. MI Commands
|
|
|
|
5.1. ul_rm
|
|
5.2. ul_rm_contact
|
|
5.3. ul_dump
|
|
5.4. ul_flush
|
|
5.5. ul_add
|
|
5.6. ul_show_contact
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. ul.dump
|
|
6.2. ul.lookup table AOR
|
|
6.3. ul.rm table AOR
|
|
6.4. ul.rm_contact table AOR contact
|
|
6.5. ul.flush
|
|
6.6. ul.add
|
|
6.7. ul.db_users
|
|
6.8. ul.db_contacts
|
|
6.9. ul.db_expired_contacts
|
|
|
|
7. Statistics
|
|
|
|
7.1. users
|
|
7.2. contacts
|
|
7.3. expires
|
|
7.4. registered_users
|
|
|
|
1. Overview
|
|
|
|
1.1. Contact matching
|
|
|
|
The User location module module keeps a user location table and
|
|
provides access to the table for other modules. The module exports no
|
|
functions that can be used directly from routing scripts.
|
|
|
|
1.1. Contact matching
|
|
|
|
How the contacts are matched (for the same AOR - Address of Record) is
|
|
an important aspect of the usrloc module, especially in the context of
|
|
NAT traversal - this raises more problems since contacts from different
|
|
phones of the same user may overlap (if both are behind NATs with the
|
|
same configuration) or the re-register contact of the same phone may be
|
|
seen as a new one (due different binding via NAT).
|
|
|
|
The SIP RFC 3261 publishes a matching algorithm based only on the
|
|
contact string with Call-id and Cseq extra checking (if the Call-ID is
|
|
the same, it must have a higher Cseq number, otherwise it is invalid).
|
|
But as argumented above, this is not enough in NAT traversal context,
|
|
so the Kamailio implementation of contact matching offers more
|
|
algorithms:
|
|
* Contact based only - it is strict RFC 3261 compliancy - the Contact
|
|
URI is matched as string and extra checked via Call-ID and cseq (if
|
|
Call-ID is the same, it must have a higher cseq number, otherwise
|
|
it is invalid).
|
|
* Contact and Call-id based - it is an extension of the first case -
|
|
the contact and Call-ID must be matched as string; the cseq must be
|
|
higher than the previous one - so be careful how you deal with
|
|
REGISTER retransmissions in this case.
|
|
* contact and path based - it is an extension of the first case - the
|
|
contact and path must be matched as string; the cseq must be higher
|
|
than the previous one - so be careful how you deal with REGISTER
|
|
retransmissions in this case.
|
|
* Call-id only based - it is not according to RFC3261, as it will
|
|
check the Call-ID only (independent of the Contact-Header or Path).
|
|
|
|
To find out how to control/select the contact maching algorithm, please
|
|
see the module parameter matching_mode - Section 3.26, “matching_mode
|
|
(integer)”.
|
|
|
|
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:
|
|
* Optionally a database module.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None.
|
|
|
|
3. Parameters
|
|
|
|
3.1. nat_bflag (integer)
|
|
3.2. user_column (string)
|
|
3.3. domain_column (string)
|
|
3.4. contact_column (string)
|
|
3.5. expires_column (string)
|
|
3.6. q_column (string)
|
|
3.7. callid_column (string)
|
|
3.8. cseq_column (string)
|
|
3.9. methods_column (string)
|
|
3.10. flags_column (string)
|
|
3.11. cflags_column (string)
|
|
3.12. user_agent_column (string)
|
|
3.13. received_column (string)
|
|
3.14. socket_column (string)
|
|
3.15. path_column (string)
|
|
3.16. ruid_column (string)
|
|
3.17. instance_column (string)
|
|
3.18. server_id_column (string)
|
|
3.19. connection_id_column (string)
|
|
3.20. keepalive_column (string)
|
|
3.21. use_domain (integer)
|
|
3.22. desc_time_order (integer)
|
|
3.23. timer_interval (integer)
|
|
3.24. db_url (string)
|
|
3.25. db_mode (integer)
|
|
3.26. matching_mode (integer)
|
|
3.27. cseq_delay (integer)
|
|
3.28. fetch_rows (integer)
|
|
3.29. hash_size (integer)
|
|
3.30. preload (string)
|
|
3.31. db_update_as_insert (string)
|
|
3.32. db_check_update (string)
|
|
3.33. timer_procs (string)
|
|
3.34. xavp_contact (string)
|
|
3.35. db_ops_ruid (int)
|
|
3.36. handle_lost_tcp (int)
|
|
3.37. close_expired_tcp (int)
|
|
3.38. expires_type (int)
|
|
3.39. db_raw_fetch_type (int)
|
|
3.40. db_insert_null (int)
|
|
3.41. skip_remote_socket (int)
|
|
3.42. db_timer_clean (int)
|
|
|
|
3.1. nat_bflag (integer)
|
|
|
|
The index of the branch flag to be used as NAT marker (if the contact
|
|
is or not natted). This is a branch flag and it will be imported and
|
|
used by all other modules depending of usrloc module.
|
|
|
|
Default value is “not set”.
|
|
|
|
Example 1.1. Set nat_bflag parameter
|
|
...
|
|
modparam("usrloc", "nat_bflag", 3)
|
|
...
|
|
|
|
3.2. user_column (string)
|
|
|
|
Name of database column containing usernames.
|
|
|
|
Default value is “username”.
|
|
|
|
Example 1.2. Set user_column parameter
|
|
...
|
|
modparam("usrloc", "user_column", "username")
|
|
...
|
|
|
|
3.3. domain_column (string)
|
|
|
|
Name of database column containing domains.
|
|
|
|
Default value is “domain”.
|
|
|
|
Example 1.3. Set user_column parameter
|
|
...
|
|
modparam("usrloc", "domain_column", "domain")
|
|
...
|
|
|
|
3.4. contact_column (string)
|
|
|
|
Name of database column containing contacts.
|
|
|
|
Default value is “contact”.
|
|
|
|
Example 1.4. Set contact_column parameter
|
|
...
|
|
modparam("usrloc", "contact_column", "contact")
|
|
...
|
|
|
|
3.5. expires_column (string)
|
|
|
|
Name of database column containing expires value.
|
|
|
|
Default value is “expires”.
|
|
|
|
Example 1.5. Set expires_column parameter
|
|
...
|
|
modparam("usrloc", "expires_column", "expires")
|
|
...
|
|
|
|
3.6. q_column (string)
|
|
|
|
Name of database column containing q values.
|
|
|
|
Default value is “q”.
|
|
|
|
Example 1.6. Set q_column parameter
|
|
...
|
|
modparam("usrloc", "q_column", "q")
|
|
...
|
|
|
|
3.7. callid_column (string)
|
|
|
|
Name of database column containing Call-ID values.
|
|
|
|
Default value is “callid”.
|
|
|
|
Example 1.7. Set callid_column parameter
|
|
...
|
|
modparam("usrloc", "callid_column", "callid")
|
|
...
|
|
|
|
3.8. cseq_column (string)
|
|
|
|
Name of database column containing Cseq.
|
|
|
|
Default value is “cseq”.
|
|
|
|
Example 1.8. Set cseq_column parameter
|
|
...
|
|
modparam("usrloc", "cseq_column", "cseq")
|
|
...
|
|
|
|
3.9. methods_column (string)
|
|
|
|
Name of database column containing supported methods.
|
|
|
|
Default value is “methods”.
|
|
|
|
Example 1.9. Set methods_column parameter
|
|
...
|
|
modparam("usrloc", "methods_column", "methods")
|
|
...
|
|
|
|
3.10. flags_column (string)
|
|
|
|
Name of database column to save the internal flags of the record.
|
|
|
|
Default value is “flags”.
|
|
|
|
Example 1.10. Set flags_column parameter
|
|
...
|
|
modparam("usrloc", "flags_column", "flags")
|
|
...
|
|
|
|
3.11. cflags_column (string)
|
|
|
|
Name of database column to save the branch/contact flags of the record.
|
|
|
|
Default value is “cflags”.
|
|
|
|
Example 1.11. Set cflags_column parameter
|
|
...
|
|
modparam("usrloc", "cflags_column", "cflags")
|
|
...
|
|
|
|
3.12. user_agent_column (string)
|
|
|
|
Name of database column containing user-agent values.
|
|
|
|
Default value is “user_agent”.
|
|
|
|
Example 1.12. Set user_agent_column parameter
|
|
...
|
|
modparam("usrloc", "user_agent_column", "user_agent")
|
|
...
|
|
|
|
3.13. received_column (string)
|
|
|
|
Name of database column containing the source IP, port, and protocol
|
|
from the REGISTER message.
|
|
|
|
Default value is “received”.
|
|
|
|
Example 1.13. Set received_column parameter
|
|
...
|
|
modparam("usrloc", "received_column", "received")
|
|
...
|
|
|
|
3.14. socket_column (string)
|
|
|
|
Name of database column containing the received socket information
|
|
(IP:port) for the REGISTER message.
|
|
|
|
Default value is “socket”.
|
|
|
|
Example 1.14. Set socket_column parameter
|
|
...
|
|
modparam("usrloc", "socket_column", "socket")
|
|
...
|
|
|
|
3.15. path_column (string)
|
|
|
|
Name of database column containing the Path header.
|
|
|
|
Default value is “path”.
|
|
|
|
Example 1.15. Set path_column parameter
|
|
...
|
|
modparam("usrloc", "path_column", "path")
|
|
...
|
|
|
|
3.16. ruid_column (string)
|
|
|
|
Name of database column containing the Kamailio record unique id.
|
|
|
|
Default value is “ruid”.
|
|
|
|
Example 1.16. Set ruid_column parameter
|
|
...
|
|
modparam("usrloc", "ruid_column", "myruid")
|
|
...
|
|
|
|
3.17. instance_column (string)
|
|
|
|
Name of database column containing the SIP instance ID (GRUU -
|
|
RFC5627). This is a unique device identifier - UUID.
|
|
|
|
Default value is “instance”.
|
|
|
|
Example 1.17. Set instance_column parameter
|
|
...
|
|
modparam("usrloc", "instance_column", "myinstance")
|
|
...
|
|
|
|
3.18. server_id_column (string)
|
|
|
|
Name of database table column containing the value for server id.
|
|
|
|
Default value is “server_id”.
|
|
|
|
Example 1.18. Set server_id_column parameter
|
|
...
|
|
modparam("usrloc", "server_id_column", "srv_id")
|
|
...
|
|
|
|
3.19. connection_id_column (string)
|
|
|
|
Name of database table column containing the value for connection id.
|
|
|
|
Default value is “connection_id”.
|
|
|
|
Example 1.19. Set connection_id_column parameter
|
|
...
|
|
modparam("usrloc", "connection_id_column", "con_id")
|
|
...
|
|
|
|
3.20. keepalive_column (string)
|
|
|
|
Name of database table column containing the value for keepalive
|
|
status.
|
|
|
|
Default value is “keepalive”.
|
|
|
|
Example 1.20. Set keepalive_column parameter
|
|
...
|
|
modparam("usrloc", "keepalive_column", "kalive")
|
|
...
|
|
|
|
3.21. use_domain (integer)
|
|
|
|
If the domain part of the user should be also saved and used for
|
|
identifing the user (along with the username part). Useful in multi
|
|
domain scenarios. Non 0 value means true.
|
|
|
|
Default value is “0 (false)”.
|
|
|
|
Example 1.21. Set use_domain parameter
|
|
...
|
|
modparam("usrloc", "use_domain", 1)
|
|
...
|
|
|
|
3.22. desc_time_order (integer)
|
|
|
|
If the user's contacts should be kept timestamp ordered; otherwise the
|
|
contact will be ordered based on q value. Non 0 value means true.
|
|
|
|
Default value is “0 (false)”.
|
|
|
|
Example 1.22. Set desc_time_order parameter
|
|
...
|
|
modparam("usrloc", "desc_time_order", 1)
|
|
...
|
|
|
|
3.23. timer_interval (integer)
|
|
|
|
Number of seconds between two timer runs. The module uses a timer to
|
|
delete expired contacts, synchronize with database and other tasks,
|
|
that need to be run periodically.
|
|
|
|
Default value is 60.
|
|
|
|
Example 1.23. Set timer_interval parameter
|
|
...
|
|
modparam("usrloc", "timer_interval", 120)
|
|
...
|
|
|
|
3.24. db_url (string)
|
|
|
|
URL of the database that should be used.
|
|
|
|
Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
|
|
|
|
Example 1.24. Set db_url parameter
|
|
...
|
|
modparam("usrloc", "db_url", "dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
3.25. db_mode (integer)
|
|
|
|
The usrloc module can utilize a database for persistent contact
|
|
storage. If a database is used, the location database (contacts) will
|
|
survive machine restarts or software crashes. The disadvantage is that
|
|
accessing a database can be very time consuming. Therefore, usrloc
|
|
module implements four database accessing modes:
|
|
* 0 - This disables database completely. Only memory will be used.
|
|
Contacts will not survive restart. Use this value if you need a
|
|
really fast usrloc and contact persistence is not necessary or is
|
|
provided by other means.
|
|
* 1 - Write-Through scheme. All changes to usrloc are immediately
|
|
reflected in database too. This is very slow, but very reliable.
|
|
Use this scheme if speed is not your priority but need to make sure
|
|
that no registered contacts will be lost during crash or reboot.
|
|
* 2 - Write-Back scheme. This is a combination of previous two
|
|
schemes. All changes are made to memory and database
|
|
synchronization is done in the timer. The timer deletes all expired
|
|
contacts and flushes all modified or new contacts to database. Use
|
|
this scheme if you encounter high-load peaks and want them to
|
|
process as fast as possible. The mode will not help at all if the
|
|
load is high all the time. Also, latency of this mode is much lower
|
|
than latency of mode 1, but slightly higher than latency of mode 0.
|
|
* 3 - DB-Only scheme. No memory cache is kept, all operations being
|
|
directly performed with the database. The timer deletes all expired
|
|
contacts from database - cleans after clients that didn't
|
|
un-register or re-register. The mode is useful if you configure
|
|
more servers sharing the same DB without any replication at SIP
|
|
level. The mode may be slower due the high number of DB operation.
|
|
For example NAT pinging is a killer since during each ping cycle
|
|
all nated contact are loaded from the DB; The lack of memory
|
|
caching also disable the statistics exports.
|
|
* 4 - This uses database to load records at startup but uses only
|
|
memory during the runtime. Records are not written back at all, not
|
|
even at shutdown. Useful for scenarios when registrations are
|
|
replicated to a node that does the storage in database during
|
|
runtime.
|
|
|
|
Warning
|
|
|
|
In case of crash or restart contacts that are in memory only and
|
|
haven't been flushed yet will get lost. If you want minimize the risk,
|
|
use shorter timer interval.
|
|
|
|
Default value is 0.
|
|
|
|
Example 1.25. Set db_mode parameter
|
|
...
|
|
modparam("usrloc", "db_mode", 2)
|
|
...
|
|
|
|
3.26. matching_mode (integer)
|
|
|
|
What contact matching algorithm to be used. Refer to section
|
|
Section 1.1, “Contact matching” for the description of the algorithms.
|
|
|
|
The parameter may take the following values:
|
|
* 0 - CONTACT ONLY based matching algorithm.
|
|
* 1 - CONTACT and CALLID based matching algorithm.
|
|
* 2 - CONTACT and PATH based matching algorithm. This mode is like
|
|
mode 0 but allows for duplicate contacts from differing paths. If
|
|
no path is available, it defaults to mode 0.
|
|
* 3 - CALLID only based matching algorithm. This mode will discard
|
|
any duplicate registration coming through different paths.
|
|
|
|
Default value is 0 (CONTACT_ONLY).
|
|
|
|
Example 1.26. Set matching_mode parameter
|
|
...
|
|
modparam("usrloc", "matching_mode", 1)
|
|
...
|
|
|
|
3.27. cseq_delay (integer)
|
|
|
|
Delay (in seconds) for accepting as retransmissions register requests
|
|
with same Call-ID and Cseq. The delay is calculated starting from the
|
|
receiving time of the first register with that Call-ID and Cseq.
|
|
|
|
Retransmissions within this delay interval will be accepted and replied
|
|
as the original request, but no update will be done in location. If the
|
|
delay is exceeded, error is reported.
|
|
|
|
A value of 0 disable the retransmission detection.
|
|
|
|
Default value is “20 seconds”.
|
|
|
|
Example 1.27. Set cseq_delay parameter
|
|
...
|
|
modparam("usrloc", "cseq_delay", 5)
|
|
...
|
|
|
|
3.28. fetch_rows (integer)
|
|
|
|
The number of the rows to be fetched at once from database when loading
|
|
the location records. This value can be used to tune the load time at
|
|
startup. For 1MB of private memory (default) it should be below 4000.
|
|
The database driver must support fetch_result() capability.
|
|
|
|
Default value is “2000”.
|
|
|
|
Example 1.28. Set fetch_rows parameter
|
|
...
|
|
modparam("usrloc", "fetch_rows", 3000)
|
|
...
|
|
|
|
3.29. hash_size (integer)
|
|
|
|
The number of entries of the hash table used by usrloc to store the
|
|
location records is 2^hash_size. For hash_size=4, the number of slots
|
|
of the hash table is 16.
|
|
|
|
Default value is “10” (1024 slots).
|
|
|
|
Example 1.29. Set hash_size parameter
|
|
...
|
|
modparam("usrloc", "hash_size", 12)
|
|
...
|
|
|
|
3.30. preload (string)
|
|
|
|
Preload location table given as value. A location table is loaded based
|
|
on fixup of registrar functions, therefore you need to use this
|
|
parameter only to load tables that are not used by registrar module
|
|
directly in configuration file.
|
|
|
|
Default value is “NULL”.
|
|
|
|
Example 1.30. Set preload parameter
|
|
...
|
|
modparam("usrloc", "preload", "location")
|
|
...
|
|
|
|
3.31. db_update_as_insert (string)
|
|
|
|
Set this parameter if you want to do INSERT DB operations instead of
|
|
UPDATE DB operations. It is recommended to set this parameter if you
|
|
use Cassandra as a DB backend.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.31. Set db_update_as_insert parameter
|
|
...
|
|
modparam("usrloc", "db_update_as_insert", 1)
|
|
...
|
|
|
|
3.32. db_check_update (string)
|
|
|
|
Set this parameter to 1 if you want to do DB INSERT if the number of
|
|
affected rows by contact DB UPDATE operation is 0. The database module
|
|
driver has to implement affected_rows() DB API function, otherwise this
|
|
parameter is ignored - e.g., MySQL and Postgres DB connectors offer
|
|
affected_rows().
|
|
|
|
Default value is “0” (no DB INSERT).
|
|
|
|
Example 1.32. Set db_check_update parameter
|
|
...
|
|
modparam("usrloc", "db_check_update", 1)
|
|
...
|
|
|
|
3.33. timer_procs (string)
|
|
|
|
Number of timer processes to be started by module. Timer processes take
|
|
care of checking expired records and syncronization with database. If
|
|
set to 0, no dedicated timer is started, the one from core will be
|
|
used.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.33. Set timer_procs parameter
|
|
...
|
|
modparam("usrloc", "timer_procs", 4)
|
|
...
|
|
|
|
3.34. xavp_contact (string)
|
|
|
|
The name of XAVP storing the attributes per contact. They are saved in
|
|
location record and restored at lookup. The tm module parameter
|
|
xavp_contact must also be set to the same value to use the
|
|
t_load_contacts and t_next_contacts functions.
|
|
|
|
Default value is “NULL”.
|
|
|
|
Example 1.34. Set xavp_contact parameter
|
|
...
|
|
modparam("usrloc", "xavp_contact", "ulattrs")
|
|
...
|
|
|
|
3.35. db_ops_ruid (int)
|
|
|
|
If set to 1, database queries for update or delete are done using ruid
|
|
value. If it is set to 0, the old style using aor, contact and call-id
|
|
is done.
|
|
|
|
Default value is “1”.
|
|
|
|
Example 1.35. Set db_ops_ruid parameter
|
|
...
|
|
modparam("usrloc", "db_ops_ruid", 0)
|
|
...
|
|
|
|
3.36. handle_lost_tcp (int)
|
|
|
|
If set to 1, Kamailio will remove location records made via
|
|
TCP/TLS/WS/WSS transports when it looses corresponding tcp connections.
|
|
Does not currently work in DB-Only scheme.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.36. Set handle_lost_tcp parameter
|
|
...
|
|
modparam("usrloc", "handle_lost_tcp", 1)
|
|
...
|
|
|
|
3.37. close_expired_tcp (int)
|
|
|
|
If set to 1, Kamailio will close the TCP connection when a contact has
|
|
expired, if the corresponding transport is TCP/TLS/WS/WSS.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.37. Set close_expired_tcp parameter
|
|
...
|
|
modparam("usrloc", "close_expired_tcp", 1)
|
|
...
|
|
|
|
3.38. expires_type (int)
|
|
|
|
If set to 1, Kamailio expects to deal with BIGINT type on database
|
|
columns for expires and last modified values. It allows to handle
|
|
better the daylight time adjustmens. If set to 0, those columns are
|
|
expected to be on default type 'DATETIME'. When it is 1, the database
|
|
columns types have to be changed manually to 'BIGINT'.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.38. Set expires_type parameter
|
|
...
|
|
modparam("usrloc", "expires_type", 1)
|
|
...
|
|
|
|
3.39. db_raw_fetch_type (int)
|
|
|
|
This affect DB-only mode and controls what kind of raw query is used to
|
|
fetch the contacts from database for specific needs (e.g., sending NAT
|
|
keepalives). If it is set to 0, then the common SQL query is used
|
|
(working for MySQL, PostgreSQL, ...). If it is set to 1, the query
|
|
required by Oracle is used.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.39. Set db_raw_fetch_type parameter
|
|
...
|
|
modparam("usrloc", "db_raw_fetch_type", 1)
|
|
...
|
|
|
|
3.40. db_insert_null (int)
|
|
|
|
If set to 1, the insert operation to database will add null values in
|
|
the sql statement.
|
|
|
|
Default value is “0” (don't add null fields in insert statement).
|
|
|
|
Example 1.40. Set db_insert_null parameter
|
|
...
|
|
modparam("usrloc", "db_insert_null", 1)
|
|
...
|
|
|
|
3.41. skip_remote_socket (int)
|
|
|
|
If set to 1, Kamailio will skip location record when loading from
|
|
database, if socket value of the record does not in kamailio listening
|
|
socket list.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.41. Set skip_remote_socket parameter
|
|
...
|
|
modparam("usrloc", "skip_remote_socket", 1)
|
|
...
|
|
|
|
3.42. db_timer_clean (int)
|
|
|
|
Enable (1) or disable (0) cleaning of expired db records on timer basis
|
|
for db_mode WRITE-BACK and WRITE-THROUGH. It uses the secondary timer
|
|
process.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.42. Set db_timer_clean parameter
|
|
...
|
|
modparam("usrloc", "db_timer_clean", 1)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
There are no exported functions that could be used in scripts.
|
|
|
|
5. MI Commands
|
|
|
|
5.1. ul_rm
|
|
5.2. ul_rm_contact
|
|
5.3. ul_dump
|
|
5.4. ul_flush
|
|
5.5. ul_add
|
|
5.6. ul_show_contact
|
|
|
|
5.1. ul_rm
|
|
|
|
Deletes an entire AOR record (including its contacts).
|
|
|
|
Parameters:
|
|
* table name - table where the AOR is removed from (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
|
|
5.2. ul_rm_contact
|
|
|
|
Deletes a contact from an AOR record.
|
|
|
|
Parameters:
|
|
* table name - table where the AOR is removed from (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
* contact - exact contact to be removed
|
|
|
|
5.3. ul_dump
|
|
|
|
Dumps the entire content of the USRLOC in memory cache
|
|
|
|
Parameters:
|
|
* brief - (optional, may not be present); if equals to string
|
|
“brief”, a brief dump will be done (only AOR and contacts, with no
|
|
other details)
|
|
|
|
5.4. ul_flush
|
|
|
|
Triggers the flush of USRLOC memory cache into DB.
|
|
|
|
5.5. ul_add
|
|
|
|
Adds a new contact for an user AOR.
|
|
|
|
Parameters:
|
|
* table name - table where the contact will be added (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
* contact - contact string to be added
|
|
* expires - expires value of the contact
|
|
* Q - Q value of the contact
|
|
* path value of the contact
|
|
* flags - internal USRLOC flags of the contact
|
|
* cflags - per branch flags of the contact
|
|
* methods - mask with supported requests of the contact
|
|
|
|
5.6. ul_show_contact
|
|
|
|
Dumps the contacts of an user AOR.
|
|
|
|
Parameters:
|
|
* table name - table where the AOR resides (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. ul.dump
|
|
6.2. ul.lookup table AOR
|
|
6.3. ul.rm table AOR
|
|
6.4. ul.rm_contact table AOR contact
|
|
6.5. ul.flush
|
|
6.6. ul.add
|
|
6.7. ul.db_users
|
|
6.8. ul.db_contacts
|
|
6.9. ul.db_expired_contacts
|
|
|
|
6.1. ul.dump
|
|
|
|
Dumps the content of the location table
|
|
|
|
Parameters:
|
|
* None.
|
|
|
|
6.2. ul.lookup table AOR
|
|
|
|
Looks up the contents of an AOR entry in the location table
|
|
|
|
Parameters:
|
|
* table name - table where the AOR resides (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
|
|
6.3. ul.rm table AOR
|
|
|
|
Deletes an entire AOR record (including its contacts).
|
|
|
|
Parameters:
|
|
* table name - table where the AOR resides (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
|
|
6.4. ul.rm_contact table AOR contact
|
|
|
|
Deletes a contact from an AOR record.
|
|
|
|
Parameters:
|
|
* table name - table where the AOR is removed from (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
* contact - exact contact to be removed
|
|
|
|
6.5. ul.flush
|
|
|
|
Triggers the flush of USRLOC memory cache into DB.
|
|
|
|
6.6. ul.add
|
|
|
|
Adds a new contact for an user AOR.
|
|
|
|
Parameters:
|
|
* table name - table where the contact will be added (Ex: location).
|
|
* AOR - user AOR in username[@domain] format (domain must be supplied
|
|
only if use_domain option is on).
|
|
* contact - contact string to be added
|
|
* expires - expires value of the contact
|
|
* Q - Q value of the contact
|
|
* path value of the contact
|
|
* flags - internal USRLOC flags of the contact
|
|
* cflags - per branch flags of the contact
|
|
* methods - mask with supported requests of the contact
|
|
|
|
6.7. ul.db_users
|
|
|
|
Tell number of different users (AoRs) in a location table that have
|
|
unexpired contacts.
|
|
|
|
Parameters:
|
|
* table name - location table where the users are looked for, for
|
|
example, location.
|
|
|
|
6.8. ul.db_contacts
|
|
|
|
Tell number of unexpired contacts in a location table.
|
|
|
|
Parameters:
|
|
* table name - location table where the contacts are looked for, for
|
|
example, location.
|
|
|
|
6.9. ul.db_expired_contacts
|
|
|
|
Tell number of expired contacts in a location table.
|
|
|
|
Parameters:
|
|
* table name - location table where the contacts are looked for, for
|
|
example, location.
|
|
|
|
7. Statistics
|
|
|
|
7.1. users
|
|
7.2. contacts
|
|
7.3. expires
|
|
7.4. registered_users
|
|
|
|
Exported statistics are listed in the next sections.
|
|
|
|
7.1. users
|
|
|
|
Number of AOR existing in the USRLOC memory cache for that domain - can
|
|
not be resetted; this statistic will be register for each used domain
|
|
(Ex: location).
|
|
|
|
7.2. contacts
|
|
|
|
Number of contacts existing in the USRLOC memory cache for that domain
|
|
- can not be resetted; this statistic will be register for each used
|
|
domain (Ex: location).
|
|
|
|
7.3. expires
|
|
|
|
Total number of expired contacts for that domain - can be resetted;
|
|
this statistic will be register for each used domain (Ex: location).
|
|
|
|
7.4. registered_users
|
|
|
|
Total number of AOR existing in the USRLOC memory cache for all domains
|
|
- can not be resetted.
|
|
|
|
Chapter 2. Developer Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Available Functions
|
|
|
|
1.1. ul_register_domain(name)
|
|
1.2. ul_insert_urecord(domain, aor, rec)
|
|
1.3. ul_delete_urecord(domain, aor)
|
|
1.4. ul_delete_urecord_by_ruid(domain, ruid)
|
|
1.5. ul_get_urecord(domain, aor)
|
|
1.6. ul_lock_udomain(domain)
|
|
1.7. ul_unlock_udomain(domain)
|
|
1.8. ul_release_urecord(record)
|
|
1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq,
|
|
flags, cont, ua, sock)
|
|
|
|
1.10. ul_delete_ucontact (record, contact)
|
|
1.11. ul_get_ucontact(record, contact)
|
|
1.12. ul_get_all_ucontacts (buf, len, flags)
|
|
1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set,
|
|
res, ua, sock)
|
|
|
|
1.14. ul_bind_ursloc( api )
|
|
1.15. ul_register_ulcb(type ,callback, param)
|
|
1.16. ul_get_num_users()
|
|
|
|
1. Available Functions
|
|
|
|
1.1. ul_register_domain(name)
|
|
1.2. ul_insert_urecord(domain, aor, rec)
|
|
1.3. ul_delete_urecord(domain, aor)
|
|
1.4. ul_delete_urecord_by_ruid(domain, ruid)
|
|
1.5. ul_get_urecord(domain, aor)
|
|
1.6. ul_lock_udomain(domain)
|
|
1.7. ul_unlock_udomain(domain)
|
|
1.8. ul_release_urecord(record)
|
|
1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq,
|
|
flags, cont, ua, sock)
|
|
|
|
1.10. ul_delete_ucontact (record, contact)
|
|
1.11. ul_get_ucontact(record, contact)
|
|
1.12. ul_get_all_ucontacts (buf, len, flags)
|
|
1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set, res,
|
|
ua, sock)
|
|
|
|
1.14. ul_bind_ursloc( api )
|
|
1.15. ul_register_ulcb(type ,callback, param)
|
|
1.16. ul_get_num_users()
|
|
|
|
1.1. ul_register_domain(name)
|
|
|
|
The function registers a new domain. Domain is just another name for
|
|
table used in registrar. The function is called from fixups in
|
|
registrar. It gets name of the domain as a parameter and returns
|
|
pointer to a new domain structure. The fixup than 'fixes' the parameter
|
|
in registrar so that it will pass the pointer instead of the name every
|
|
time save() or lookup() is called. Some usrloc functions get the
|
|
pointer as parameter when called. For more details see implementation
|
|
of save function in registrar.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* const char* name - Name of the domain (also called table) to be
|
|
registered.
|
|
|
|
1.2. ul_insert_urecord(domain, aor, rec)
|
|
|
|
The function creates a new record structure and inserts it in the
|
|
specified domain. The record is structure that contains all the
|
|
contacts for belonging to the specified username.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of Record (aka username) of the new record (at
|
|
this time the record will contain no contacts yet).
|
|
|
|
* urecord_t** rec - The newly created record structure.
|
|
|
|
1.3. ul_delete_urecord(domain, aor)
|
|
|
|
The function deletes all the contacts bound with the given Address Of
|
|
Record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of record (aka username) of the record, that
|
|
should be deleted.
|
|
|
|
1.4. ul_delete_urecord_by_ruid(domain, ruid)
|
|
|
|
The function deletes from given domain a contact with given ruid.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* ruid - ruid of contact that should be deleted.
|
|
|
|
1.5. ul_get_urecord(domain, aor)
|
|
|
|
The function returns pointer to record with given Address of Record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Pointer to domain returned by
|
|
ul_register_udomain.
|
|
|
|
* str* aor - Address of Record of request record.
|
|
|
|
1.6. ul_lock_udomain(domain)
|
|
|
|
The function lock the specified domain, it means, that no other
|
|
processes will be able to access during the time. This prevents race
|
|
conditions. Scope of the lock is the specified domain, that means, that
|
|
multiple domain can be accessed simultaneously, they don't block each
|
|
other.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Domain to be locked.
|
|
|
|
1.7. ul_unlock_udomain(domain)
|
|
|
|
Unlock the specified domain previously locked by ul_lock_udomain.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* udomain_t* domain - Domain to be unlocked.
|
|
|
|
1.8. ul_release_urecord(record)
|
|
|
|
Do some sanity checks - if all contacts have been removed, delete the
|
|
entire record structure.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record to be released.
|
|
|
|
1.9. ul_insert_ucontact(record, contact, expires, q, callid, cseq, flags,
|
|
cont, ua, sock)
|
|
|
|
The function inserts a new contact in the given record with specified
|
|
parameters.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record in which the contact should be inserted.
|
|
* str* contact - Contact URI.
|
|
* time_t expires - Expires of the contact in absolute value.
|
|
* float q - q value of the contact.
|
|
* str* callid - Call-ID of the REGISTER message that contained the
|
|
contact.
|
|
* int cseq - CSeq of the REGISTER message that contained the contact.
|
|
* unsigned int flags - Flags to be set.
|
|
* ucontact_t* cont - Pointer to newly created structure.
|
|
* str* ua - User-Agent of the REGISTER message that contained the
|
|
contact.
|
|
* struct socket_info *sock - socket on which the REGISTER message was
|
|
received on.
|
|
|
|
1.10. ul_delete_ucontact (record, contact)
|
|
|
|
The function deletes given contact from record.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record from which the contact should be
|
|
removed.
|
|
|
|
* ucontact_t* contact - Contact to be deleted.
|
|
|
|
1.11. ul_get_ucontact(record, contact)
|
|
|
|
The function tries to find contact with given Contact URI and returns
|
|
pointer to structure representing the contact.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* urecord_t* record - Record to be searched for the contact.
|
|
|
|
* str_t* contact - URI of the request contact.
|
|
|
|
1.12. ul_get_all_ucontacts (buf, len, flags)
|
|
|
|
The function retrieves all contacts of all registered users and returns
|
|
them in the caller-supplied buffer. If the buffer is too small, the
|
|
function returns positive value indicating how much additional space
|
|
would be necessary to accommodate all of them. Please note that the
|
|
positive return value should be used only as a “hint”, as there is no
|
|
guarantee that during the time between two subsequent calls number of
|
|
registered contacts will remain the same.
|
|
|
|
If flag parameter is set to non-zero value then only contacts that have
|
|
the specified flags set will be returned. It is, for example, possible
|
|
to list only contacts that are behind NAT.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* void* buf - Buffer for returning contacts.
|
|
|
|
* int len - Length of the buffer.
|
|
|
|
* unsigned int flags - Flags that must be set.
|
|
|
|
1.13. ul_update_ucontact(contact, expires, q, callid, cseq, set, res, ua,
|
|
sock)
|
|
|
|
The function updates contact with new values.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* ucontact_t* contact - Contact URI.
|
|
* time_t expires - Expires of the contact in absolute value.
|
|
* float q - q value of the contact.
|
|
* str* callid - Call-ID of the REGISTER message that contained the
|
|
contact.
|
|
* int cseq - CSeq of the REGISTER message that contained the contact.
|
|
* unsigned int set - OR value of flags to be set.
|
|
* unsigned int res - OR value of flags to be reset.
|
|
* str* ua - User-Agent of the REGISTER message that contained the
|
|
contact.
|
|
* struct socket_info *sock - socket on which the REGISTER message was
|
|
received on.
|
|
|
|
1.14. ul_bind_ursloc( api )
|
|
|
|
The function imports all functions that are exported by the USRLOC
|
|
module. Overs for other modules which want to user the internal USRLOC
|
|
API an easy way to load and access the functions.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* usrloc_api_t* api - USRLOC API
|
|
|
|
1.15. ul_register_ulcb(type ,callback, param)
|
|
|
|
The function register with USRLOC a callback function to be called when
|
|
some event occures inside USRLOC.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* int types - type of event for which the callback should be called
|
|
(see usrloc/ul_callback.h).
|
|
* ul_cb f - callback function; see usrloc/ul_callback.h for
|
|
prototype.
|
|
* void *param - some parameter to be passed to the callback each time
|
|
when it is called.
|
|
|
|
1.16. ul_get_num_users()
|
|
|
|
The function loops through all domains summing up the number of users.
|