| 1 |
registrar Module |
| 2 |
|
| 3 |
Jan Janak |
| 4 |
|
| 5 |
FhG FOKUS |
| 6 |
<[email protected]> |
| 7 |
|
| 8 |
Daniel-Constantin Mierla |
| 9 |
|
| 10 |
<[email protected]> |
| 11 |
|
| 12 |
Juha Heinanen |
| 13 |
|
| 14 |
<[email protected]> |
| 15 |
|
| 16 |
Olle E. Johansson |
| 17 |
|
| 18 |
Edvina AB |
| 19 |
<[email protected]> |
| 20 |
|
| 21 |
Edited by |
| 22 |
|
| 23 |
Jan Janak |
| 24 |
|
| 25 |
<[email protected]> |
| 26 |
|
| 27 |
Bogdan-Andre Iancu |
| 28 |
|
| 29 |
Copyright © 2003 FhG FOKUS |
| 30 |
__________________________________________________________________ |
| 31 |
|
| 32 |
Table of Contents |
| 33 |
|
| 34 |
1. Admin Guide |
| 35 |
|
| 36 |
1. Overview |
| 37 |
|
| 38 |
1.1. PATH support |
| 39 |
1.2. GRUU Support |
| 40 |
|
| 41 |
2. Dependencies |
| 42 |
|
| 43 |
2.1. Kamailio Modules |
| 44 |
2.2. External Libraries or Applications |
| 45 |
|
| 46 |
3. Parameters |
| 47 |
|
| 48 |
3.1. default_expires (integer) |
| 49 |
3.2. default_expires_range (integer) |
| 50 |
3.3. expires_range (integer) |
| 51 |
3.4. min_expires (integer) |
| 52 |
3.5. min_expires_mode (integer) |
| 53 |
3.6. max_expires (integer) |
| 54 |
3.7. default_q (integer) |
| 55 |
3.8. realm_prefix (string) |
| 56 |
3.9. append_branches (integer) |
| 57 |
3.10. aor_avp (str) |
| 58 |
3.11. case_sensitive (integer) |
| 59 |
3.12. received_avp (str) |
| 60 |
3.13. received_param (string) |
| 61 |
3.14. max_contacts (integer) |
| 62 |
3.15. retry_after (integer) |
| 63 |
3.16. sock_flag (integer) |
| 64 |
3.17. sock_hdr_name (string) |
| 65 |
3.18. sock_mode (integer) |
| 66 |
3.19. method_filtering (integer) |
| 67 |
3.20. use_path (integer) |
| 68 |
3.21. path_mode (integer) |
| 69 |
3.22. path_use_received (integer) |
| 70 |
3.23. path_check_local (integer) |
| 71 |
3.24. reg_callid_avp (string) |
| 72 |
3.25. xavp_cfg (string) |
| 73 |
3.26. xavp_rcd (string) |
| 74 |
3.27. xavp_rcd_mask (int) |
| 75 |
3.28. gruu_enabled (integer) |
| 76 |
3.29. outbound_mode (integer) |
| 77 |
3.30. regid_mode (integer) |
| 78 |
3.31. flow_timer (integer) |
| 79 |
3.32. contact_max_size (integer) |
| 80 |
3.33. event_callback (str) |
| 81 |
3.34. lookup_filter_mode (int) |
| 82 |
3.35. use_expired_contacts (int) |
| 83 |
|
| 84 |
4. Functions |
| 85 |
|
| 86 |
4.1. save(domain, [, flags [, uri]]) |
| 87 |
4.2. lookup(domain [, uri]) |
| 88 |
4.3. lookup_to_dset(domain [, uri]) |
| 89 |
4.4. lookup_branches(domain) |
| 90 |
4.5. lookup_xavp(ultable, uri, rxname, cxname) |
| 91 |
4.6. registered(domain [, uri [, match_option [, |
| 92 |
match_action]]]) |
| 93 |
|
| 94 |
4.7. add_sock_hdr(hdr_name) |
| 95 |
4.8. unregister(domain, uri[, ruid]) |
| 96 |
4.9. reg_fetch_contacts(domain, uri, profile) |
| 97 |
4.10. reg_free_contacts(profile) |
| 98 |
4.11. reg_send_reply() |
| 99 |
4.12. reg_from_user(ultable, uri, mode) |
| 100 |
|
| 101 |
5. Event Routes |
| 102 |
|
| 103 |
5.1. event_route[usrloc:contact-expired] |
| 104 |
|
| 105 |
6. Statistics |
| 106 |
|
| 107 |
6.1. max_expires |
| 108 |
6.2. max_contacts |
| 109 |
6.3. default_expires |
| 110 |
6.4. accepted_regs |
| 111 |
6.5. rejected_regs |
| 112 |
|
| 113 |
7. Pseudo Variables |
| 114 |
|
| 115 |
7.1. $ulc(profile=>attr) |
| 116 |
|
| 117 |
2. Frequently Asked Questions |
| 118 |
|
| 119 |
List of Examples |
| 120 |
|
| 121 |
1.1. Set default_expires parameter |
| 122 |
1.2. Set default_expires_range parameter |
| 123 |
1.3. Set expires_range parameter |
| 124 |
1.4. Set min_expires parameter |
| 125 |
1.5. Set min_expires_mode parameter |
| 126 |
1.6. Set max_expires parameter |
| 127 |
1.7. Set default_q parameter |
| 128 |
1.8. Set realm_prefix parameter |
| 129 |
1.9. Set append_branches parameter |
| 130 |
1.10. Set case_sensitive parameter |
| 131 |
1.11. Set received_avp parameter |
| 132 |
1.12. Set received_param parameter |
| 133 |
1.13. Set max_contacts parameter |
| 134 |
1.14. Set retry_after parameter |
| 135 |
1.15. Set sock_flag parameter |
| 136 |
1.16. Set sock_hdr_name parameter |
| 137 |
1.17. Set sock_mode parameter |
| 138 |
1.18. Set method_filtering parameter |
| 139 |
1.19. Set use_path parameter |
| 140 |
1.20. Set path_mode parameter |
| 141 |
1.21. Set path_use_received parameter |
| 142 |
1.22. Set path_check_local parameter |
| 143 |
1.23. Set reg_callid_avp parameter |
| 144 |
1.24. Set xavp_cfg parameter |
| 145 |
1.25. Set xavp_rcd parameter |
| 146 |
1.26. Set xavp_rcd_mask parameter |
| 147 |
1.27. Set gruu_enabled parameter |
| 148 |
1.28. Set outbound_mode parameter |
| 149 |
1.29. Set regid_mode parameter |
| 150 |
1.30. Set flow_timer parameter |
| 151 |
1.31. Set contact_max_size parameter |
| 152 |
1.32. Set event_callback parameter |
| 153 |
1.33. Set xavp_cfg parameter |
| 154 |
1.34. Set use_expired_contacts parameter |
| 155 |
1.35. save usage |
| 156 |
1.36. lookup usage |
| 157 |
1.37. lookup_to_dset usage |
| 158 |
1.38. lookup_branches usage |
| 159 |
1.39. lookup_xavp usage |
| 160 |
1.40. registered usage |
| 161 |
1.41. add_sock_hdr usage |
| 162 |
1.42. unregister usage |
| 163 |
1.43. reg_fetch_contacts usage |
| 164 |
1.44. reg_free_contacts usage |
| 165 |
1.45. reg_send_reply usage |
| 166 |
1.46. reg_from_user usage |
| 167 |
1.47. event_route[usrloc:contact-expired] usage |
| 168 |
1.48. $ulc(name) usage |
| 169 |
|
| 170 |
Chapter 1. Admin Guide |
| 171 |
|
| 172 |
Table of Contents |
| 173 |
|
| 174 |
1. Overview |
| 175 |
|
| 176 |
1.1. PATH support |
| 177 |
1.2. GRUU Support |
| 178 |
|
| 179 |
2. Dependencies |
| 180 |
|
| 181 |
2.1. Kamailio Modules |
| 182 |
2.2. External Libraries or Applications |
| 183 |
|
| 184 |
3. Parameters |
| 185 |
|
| 186 |
3.1. default_expires (integer) |
| 187 |
3.2. default_expires_range (integer) |
| 188 |
3.3. expires_range (integer) |
| 189 |
3.4. min_expires (integer) |
| 190 |
3.5. min_expires_mode (integer) |
| 191 |
3.6. max_expires (integer) |
| 192 |
3.7. default_q (integer) |
| 193 |
3.8. realm_prefix (string) |
| 194 |
3.9. append_branches (integer) |
| 195 |
3.10. aor_avp (str) |
| 196 |
3.11. case_sensitive (integer) |
| 197 |
3.12. received_avp (str) |
| 198 |
3.13. received_param (string) |
| 199 |
3.14. max_contacts (integer) |
| 200 |
3.15. retry_after (integer) |
| 201 |
3.16. sock_flag (integer) |
| 202 |
3.17. sock_hdr_name (string) |
| 203 |
3.18. sock_mode (integer) |
| 204 |
3.19. method_filtering (integer) |
| 205 |
3.20. use_path (integer) |
| 206 |
3.21. path_mode (integer) |
| 207 |
3.22. path_use_received (integer) |
| 208 |
3.23. path_check_local (integer) |
| 209 |
3.24. reg_callid_avp (string) |
| 210 |
3.25. xavp_cfg (string) |
| 211 |
3.26. xavp_rcd (string) |
| 212 |
3.27. xavp_rcd_mask (int) |
| 213 |
3.28. gruu_enabled (integer) |
| 214 |
3.29. outbound_mode (integer) |
| 215 |
3.30. regid_mode (integer) |
| 216 |
3.31. flow_timer (integer) |
| 217 |
3.32. contact_max_size (integer) |
| 218 |
3.33. event_callback (str) |
| 219 |
3.34. lookup_filter_mode (int) |
| 220 |
3.35. use_expired_contacts (int) |
| 221 |
|
| 222 |
4. Functions |
| 223 |
|
| 224 |
4.1. save(domain, [, flags [, uri]]) |
| 225 |
4.2. lookup(domain [, uri]) |
| 226 |
4.3. lookup_to_dset(domain [, uri]) |
| 227 |
4.4. lookup_branches(domain) |
| 228 |
4.5. lookup_xavp(ultable, uri, rxname, cxname) |
| 229 |
4.6. registered(domain [, uri [, match_option [, match_action]]]) |
| 230 |
4.7. add_sock_hdr(hdr_name) |
| 231 |
4.8. unregister(domain, uri[, ruid]) |
| 232 |
4.9. reg_fetch_contacts(domain, uri, profile) |
| 233 |
4.10. reg_free_contacts(profile) |
| 234 |
4.11. reg_send_reply() |
| 235 |
4.12. reg_from_user(ultable, uri, mode) |
| 236 |
|
| 237 |
5. Event Routes |
| 238 |
|
| 239 |
5.1. event_route[usrloc:contact-expired] |
| 240 |
|
| 241 |
6. Statistics |
| 242 |
|
| 243 |
6.1. max_expires |
| 244 |
6.2. max_contacts |
| 245 |
6.3. default_expires |
| 246 |
6.4. accepted_regs |
| 247 |
6.5. rejected_regs |
| 248 |
|
| 249 |
7. Pseudo Variables |
| 250 |
|
| 251 |
7.1. $ulc(profile=>attr) |
| 252 |
|
| 253 |
1. Overview |
| 254 |
|
| 255 |
1.1. PATH support |
| 256 |
1.2. GRUU Support |
| 257 |
|
| 258 |
The module contains REGISTER processing logic. The actual location |
| 259 |
database is managed by the USRLOC module. |
| 260 |
|
| 261 |
1.1. PATH support |
| 262 |
|
| 263 |
The Register module includes Path support (according to RFC 3327) for |
| 264 |
usage in registrars and home-proxies. |
| 265 |
|
| 266 |
If path support is enabled in the registrar module, a call to save(...) |
| 267 |
stores the values of the Path Header(s) along with the contact into |
| 268 |
usrloc. There are three modes regarding the reply to a REGISTER |
| 269 |
including one or more Path header fields: |
| 270 |
* off - stores the value of the Path headers into usrloc without |
| 271 |
passing it back to the UAC in the reply. |
| 272 |
* lazy - stores the Path header and passes it back to the UAC if |
| 273 |
Path-support is indicated by the “path” param in the Supported |
| 274 |
header field. |
| 275 |
* strict - rejects the registration with “420 Bad Extension” if |
| 276 |
there's a Path header but no support for it is indicated by the |
| 277 |
UAC. Otherwise it's stored and passed back to the UAC. |
| 278 |
|
| 279 |
A call to lookup(...) always uses the path header if found, and inserts |
| 280 |
it as Route header field either in front of the first Route header |
| 281 |
field, or after the last Via header field if no Route is present. It |
| 282 |
also sets the destination uri to the first Path uri, thus overwriting |
| 283 |
the received-uri, because NAT has to be handled at the outbound-proxy |
| 284 |
of the UAC (the first hop after client's NAT). |
| 285 |
|
| 286 |
The whole process is transparent to the user, so no config changes are |
| 287 |
required beside setting the registrar-parameters “use_path” and |
| 288 |
“path_mode”. |
| 289 |
|
| 290 |
1.2. GRUU Support |
| 291 |
|
| 292 |
GRUU (RFC5627) is supported with both public and temporary addresses. |
| 293 |
|
| 294 |
The public GRUU is built based on the '+sip.instance' UUID parameter as |
| 295 |
recommended by RFC. |
| 296 |
|
| 297 |
The temporary GRUU is built based on internal SRUID (unique id |
| 298 |
generator) and it is kept the same for the duration of contact |
| 299 |
validity. |
| 300 |
|
| 301 |
2. Dependencies |
| 302 |
|
| 303 |
2.1. Kamailio Modules |
| 304 |
2.2. External Libraries or Applications |
| 305 |
|
| 306 |
2.1. Kamailio Modules |
| 307 |
|
| 308 |
The following modules must be loaded before this module: |
| 309 |
* usrloc - User Location Module. |
| 310 |
* sl - Stateless Replies. |
| 311 |
|
| 312 |
2.2. External Libraries or Applications |
| 313 |
|
| 314 |
The following libraries or applications must be installed before |
| 315 |
running Kamailio with this module loaded: |
| 316 |
* None. |
| 317 |
|
| 318 |
3. Parameters |
| 319 |
|
| 320 |
3.1. default_expires (integer) |
| 321 |
3.2. default_expires_range (integer) |
| 322 |
3.3. expires_range (integer) |
| 323 |
3.4. min_expires (integer) |
| 324 |
3.5. min_expires_mode (integer) |
| 325 |
3.6. max_expires (integer) |
| 326 |
3.7. default_q (integer) |
| 327 |
3.8. realm_prefix (string) |
| 328 |
3.9. append_branches (integer) |
| 329 |
3.10. aor_avp (str) |
| 330 |
3.11. case_sensitive (integer) |
| 331 |
3.12. received_avp (str) |
| 332 |
3.13. received_param (string) |
| 333 |
3.14. max_contacts (integer) |
| 334 |
3.15. retry_after (integer) |
| 335 |
3.16. sock_flag (integer) |
| 336 |
3.17. sock_hdr_name (string) |
| 337 |
3.18. sock_mode (integer) |
| 338 |
3.19. method_filtering (integer) |
| 339 |
3.20. use_path (integer) |
| 340 |
3.21. path_mode (integer) |
| 341 |
3.22. path_use_received (integer) |
| 342 |
3.23. path_check_local (integer) |
| 343 |
3.24. reg_callid_avp (string) |
| 344 |
3.25. xavp_cfg (string) |
| 345 |
3.26. xavp_rcd (string) |
| 346 |
3.27. xavp_rcd_mask (int) |
| 347 |
3.28. gruu_enabled (integer) |
| 348 |
3.29. outbound_mode (integer) |
| 349 |
3.30. regid_mode (integer) |
| 350 |
3.31. flow_timer (integer) |
| 351 |
3.32. contact_max_size (integer) |
| 352 |
3.33. event_callback (str) |
| 353 |
3.34. lookup_filter_mode (int) |
| 354 |
3.35. use_expired_contacts (int) |
| 355 |
|
| 356 |
3.1. default_expires (integer) |
| 357 |
|
| 358 |
If the processed message contains neither Expires header fields nor |
| 359 |
expires contact parameters, this value will be used for newly created |
| 360 |
usrloc records. The parameter contains number of second to expire (for |
| 361 |
example use 3600 for one hour). If it is set to a lower value than the |
| 362 |
“min_expires” parameter then it will be ignored. This parameter can be |
| 363 |
modified via ser config framework. A random value in a specific |
| 364 |
interval can be selected by using the default_expires_range parameter |
| 365 |
|
| 366 |
Default value is 3600. |
| 367 |
|
| 368 |
Example 1.1. Set default_expires parameter |
| 369 |
... |
| 370 |
modparam("registrar", "default_expires", 1800) |
| 371 |
... |
| 372 |
|
| 373 |
3.2. default_expires_range (integer) |
| 374 |
|
| 375 |
This parameter specifies that the expiry used for newly created usrloc |
| 376 |
records are not fixed, but a random value in the interval |
| 377 |
“[default_expires-default_expires_range%, default_expires]”. The value |
| 378 |
is between 0 and 100 and represent the maximum percentage from expires |
| 379 |
that will be subtracted when computing the value. Default is 0, meaning |
| 380 |
default_expires is left unmodified. This parameter can be modified via |
| 381 |
the Kamailio config framework. |
| 382 |
|
| 383 |
Default value is 0. |
| 384 |
|
| 385 |
Example 1.2. Set default_expires_range parameter |
| 386 |
... |
| 387 |
modparam("registrar", "default_expires_range", 30) # expires within [0.7*default |
| 388 |
_expires .. default_expires] |
| 389 |
... |
| 390 |
|
| 391 |
3.3. expires_range (integer) |
| 392 |
|
| 393 |
Similar to default_expires_range, but it applies to the incoming |
| 394 |
expires value. Default in 0, meaning the expires is left unmodified. |
| 395 |
This parameter can be modified via the Kamailio config framework. |
| 396 |
|
| 397 |
Default value is 0. |
| 398 |
|
| 399 |
Example 1.3. Set expires_range parameter |
| 400 |
... |
| 401 |
modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expi |
| 402 |
res] |
| 403 |
... |
| 404 |
|
| 405 |
3.4. min_expires (integer) |
| 406 |
|
| 407 |
The minimum expires value of a “Contact”. Values lower than this |
| 408 |
minimum will be either set to the minimum or 423 response is sent back. |
| 409 |
Value 0 disables the checking. This parameter can be modified via the |
| 410 |
Kamailio config framework. |
| 411 |
|
| 412 |
Default value is 60. |
| 413 |
|
| 414 |
Example 1.4. Set min_expires parameter |
| 415 |
... |
| 416 |
modparam("registrar", "min_expires", 60) |
| 417 |
... |
| 418 |
|
| 419 |
3.5. min_expires_mode (integer) |
| 420 |
|
| 421 |
Control what to do when expires value in REGISTER request is lower than |
| 422 |
min_expires parameter. If set to 0, expires is set to min_expires. If |
| 423 |
set to 1, then 423 Interval Too Brief is sent back. |
| 424 |
|
| 425 |
Default value is 0. |
| 426 |
|
| 427 |
Example 1.5. Set min_expires_mode parameter |
| 428 |
... |
| 429 |
modparam("registrar", "min_expires_mode", 1) |
| 430 |
... |
| 431 |
|
| 432 |
3.6. max_expires (integer) |
| 433 |
|
| 434 |
The maximum accepted expires value of a “Contact”, values higher than |
| 435 |
this maximum will be automatically set to the maximum. Value 0 disables |
| 436 |
the checking. This parameter can be modified via the Kamailio config |
| 437 |
framework. |
| 438 |
|
| 439 |
Default value is 0. |
| 440 |
|
| 441 |
Example 1.6. Set max_expires parameter |
| 442 |
... |
| 443 |
modparam("registrar", "max_expires", 120) |
| 444 |
... |
| 445 |
|
| 446 |
3.7. default_q (integer) |
| 447 |
|
| 448 |
The parameter represents default “q” value for new contacts. Because |
| 449 |
Kamailio doesn't support float parameter types, the value in the |
| 450 |
parameter is divided by 1000 and stored as float. For example, if you |
| 451 |
want default_q to be 0.38, use value 380 here. This parameter can be |
| 452 |
modified via the Kamailio config framework. |
| 453 |
|
| 454 |
Default value is 0. |
| 455 |
|
| 456 |
Example 1.7. Set default_q parameter |
| 457 |
... |
| 458 |
modparam("registrar", "default_q", 1000) |
| 459 |
... |
| 460 |
|
| 461 |
3.8. realm_prefix (string) |
| 462 |
|
| 463 |
Prefix to be automatically stripped from realm. As an alternative to |
| 464 |
SRV records (not all SIP clients support SRV lookup), a subdomain of |
| 465 |
the master domain can be defined for SIP purposes (like |
| 466 |
sip.mydomain.net pointing to same IP address as the SRV record for |
| 467 |
mydomain.net). By ignoring the realm_prefix "sip.", at registration, |
| 468 |
sip.mydomain.net will be equivalent to mydomain.net. This parameter can |
| 469 |
be modified via the Kamailio config framework. |
| 470 |
|
| 471 |
Default value is NULL (none). |
| 472 |
|
| 473 |
Example 1.8. Set realm_prefix parameter |
| 474 |
... |
| 475 |
modparam("registrar", "realm_prefix", "sip.") |
| 476 |
... |
| 477 |
|
| 478 |
3.9. append_branches (integer) |
| 479 |
|
| 480 |
The parameter controls how lookup function processes multiple contacts. |
| 481 |
If there are multiple contacts for the given username in usrloc and |
| 482 |
this parameter is set to 1, Request-URI will be overwritten with the |
| 483 |
highest-q rated contact. The rest will be appended to sip_msg structure |
| 484 |
and can be later used by tm for forking. If the parameter is set to 0, |
| 485 |
only Request-URI will be overwritten with the highest-q rated contact |
| 486 |
and the rest will be left unprocessed. This parameter can be modified |
| 487 |
via Kamailio config framework. |
| 488 |
|
| 489 |
Default value is 1. |
| 490 |
|
| 491 |
Example 1.9. Set append_branches parameter |
| 492 |
... |
| 493 |
modparam("registrar", "append_branches", 0) |
| 494 |
... |
| 495 |
|
| 496 |
3.10. aor_avp (str) |
| 497 |
|
| 498 |
This module parameter has been removed. Use the 'uri' parameter from |
| 499 |
functions (e.g., save, lookup, registered). |
| 500 |
|
| 501 |
3.11. case_sensitive (integer) |
| 502 |
|
| 503 |
If set to 1 then AOR comparison and also storing will be case |
| 504 |
sensitive, if set to 0 then AOR comparison and storing will be case |
| 505 |
insensitive. This is recommended. This parameter can be modified via |
| 506 |
Kamailio config framework. |
| 507 |
|
| 508 |
Default value is 0. |
| 509 |
|
| 510 |
Example 1.10. Set case_sensitive parameter |
| 511 |
... |
| 512 |
modparam("registrar", "case_sensitive", 1) |
| 513 |
... |
| 514 |
|
| 515 |
3.12. received_avp (str) |
| 516 |
|
| 517 |
Registrar will store the value of the AVP configured by this parameter |
| 518 |
in the received column in the user location database. It will leave the |
| 519 |
column empty if the AVP is empty. The AVP should contain a SIP URI |
| 520 |
consisting of the source IP, port, and transport protocol of the |
| 521 |
REGISTER message being processed. |
| 522 |
|
| 523 |
Note |
| 524 |
|
| 525 |
The value of this parameter should be the same as the value of |
| 526 |
corresponding parameter of nathelper module. |
| 527 |
|
| 528 |
Default value is "NULL" (disabled). |
| 529 |
|
| 530 |
Example 1.11. Set received_avp parameter |
| 531 |
... |
| 532 |
modparam("registrar", "received_avp", "$avp(s:rcv)") |
| 533 |
... |
| 534 |
|
| 535 |
3.13. received_param (string) |
| 536 |
|
| 537 |
The name of the parameter that will be appended to Contact URI's of 200 |
| 538 |
OK when the received URI was set by the “nathelper” module. If the |
| 539 |
value is an empty string, then the parameter is not appended anymore. |
| 540 |
|
| 541 |
Default value is "received". |
| 542 |
|
| 543 |
Example 1.12. Set received_param parameter |
| 544 |
... |
| 545 |
modparam("registrar", "received_param", "rcv") |
| 546 |
... |
| 547 |
|
| 548 |
3.14. max_contacts (integer) |
| 549 |
|
| 550 |
The parameter can be used to limit the number of contacts per AOR |
| 551 |
(Address of Record) in the user location database. If the maximum |
| 552 |
number of contacts is exceeded, Kamailio will not accept the |
| 553 |
registration and send an error response. Value 0 disables the check. |
| 554 |
This parameter can be modified via the Kamailio config framework. |
| 555 |
(Please also check the flag for save() if you only want only one active |
| 556 |
registration). |
| 557 |
|
| 558 |
Default value is 0. |
| 559 |
|
| 560 |
Example 1.13. Set max_contacts parameter |
| 561 |
... |
| 562 |
# Allow no more than 10 contacts per AOR |
| 563 |
modparam("registrar", "max_contacts", 10) |
| 564 |
... |
| 565 |
|
| 566 |
3.15. retry_after (integer) |
| 567 |
|
| 568 |
The registrar can generate a 5xx reply to REGISTER requests in various |
| 569 |
situations. It can, for example, happen when the max_contacts parameter |
| 570 |
is set and the processing of REGISTER request would exceed the limit. |
| 571 |
In this case the registrar would generate "503 Service Unavailable" |
| 572 |
response. This parameter can be modified via the Kamailio config |
| 573 |
framework. |
| 574 |
|
| 575 |
If you want to add the Retry-After header field in 5xx replies, set |
| 576 |
this parameter to a value grater than zero (0 means do not add the |
| 577 |
header field). See section 20.33 of RFC3261 for more details. |
| 578 |
|
| 579 |
Default value is 0 (disabled). |
| 580 |
|
| 581 |
Example 1.14. Set retry_after parameter |
| 582 |
... |
| 583 |
modparam("registrar", "retry_after", 30) |
| 584 |
... |
| 585 |
|
| 586 |
3.16. sock_flag (integer) |
| 587 |
|
| 588 |
Message flag to signal to the registrar module to look into REGISTER |
| 589 |
request for a header which contains a socket description (IP:port). |
| 590 |
This socket info will be stored by registrar instead of the received |
| 591 |
socket info. |
| 592 |
|
| 593 |
This makes sense only in multiple replicated servers scenarios. |
| 594 |
|
| 595 |
Default value is -1 (no flag). |
| 596 |
|
| 597 |
Example 1.15. Set sock_flag parameter |
| 598 |
... |
| 599 |
modparam("registrar", "sock_flag", 18) |
| 600 |
... |
| 601 |
|
| 602 |
3.17. sock_hdr_name (string) |
| 603 |
|
| 604 |
Header which contains a socket description (proto:IP:port) to override |
| 605 |
the received socket info. The header will be read only if the flag |
| 606 |
sock_flag is set. |
| 607 |
|
| 608 |
This makes sense only in multiple replicated servers scenarios. |
| 609 |
|
| 610 |
Default value is NULL. |
| 611 |
|
| 612 |
Example 1.16. Set sock_hdr_name parameter |
| 613 |
... |
| 614 |
modparam("registrar", "sock_hdr_name", "Sock-Info") |
| 615 |
... |
| 616 |
|
| 617 |
3.18. sock_mode (integer) |
| 618 |
|
| 619 |
If set to 1, the server stores the advertised address in socket field, |
| 620 |
instead of bind address. |
| 621 |
|
| 622 |
This could be useful when kamailio is installed behind NAT and it is |
| 623 |
necessary to store its public IP instead socket on which the register |
| 624 |
request was received. |
| 625 |
|
| 626 |
Default value is 0 (store bind address). |
| 627 |
|
| 628 |
Example 1.17. Set sock_mode parameter |
| 629 |
... |
| 630 |
modparam("registrar", "sock_mode", 1) |
| 631 |
... |
| 632 |
|
| 633 |
3.19. method_filtering (integer) |
| 634 |
|
| 635 |
Tells if the contact filtering based on supported methods should be |
| 636 |
performed during lookup on initial requests without to-tag. It's |
| 637 |
enabled only if it has a non zero value. Supported methods are listed |
| 638 |
in the “Allow:” header in the REGISTER message and stored in the |
| 639 |
location database. |
| 640 |
|
| 641 |
Default value is 0 (disabled). |
| 642 |
|
| 643 |
Example 1.18. Set method_filtering parameter |
| 644 |
... |
| 645 |
modparam("registrar", "method_filtering", 1) |
| 646 |
... |
| 647 |
|
| 648 |
3.20. use_path (integer) |
| 649 |
|
| 650 |
If set to 1, the “Path:” header is handled according to the parameter. |
| 651 |
This parameter can be modified via Kamailio config framework. |
| 652 |
“path_mode”. |
| 653 |
|
| 654 |
Default value is 0 (disabled). |
| 655 |
|
| 656 |
Example 1.19. Set use_path parameter |
| 657 |
... |
| 658 |
modparam("registrar", "use_path", 1) |
| 659 |
... |
| 660 |
|
| 661 |
3.21. path_mode (integer) |
| 662 |
|
| 663 |
The registrar module implements three different modes regarding the |
| 664 |
response to a registration which includes one or more Path headers: |
| 665 |
* 0 - The Path header is saved into usrloc, but is not included in |
| 666 |
the reply. |
| 667 |
* 1 - The Path header is saved into usrloc, but is only included in |
| 668 |
the reply if path support is indicated in the registration request |
| 669 |
by the “path” option in the “Supported:” header. |
| 670 |
* 2 - The path header is only saved into usrloc, if path support is |
| 671 |
indicated in the registration request by the “path” option of the |
| 672 |
“Supported” header. If no path support is indicated, the request is |
| 673 |
rejected with “420 - Bad Extension” and the header “Unsupported: |
| 674 |
path” is included in the reply along with the received “Path” |
| 675 |
header. This mode is the one recommended by RFC-3327. |
| 676 |
|
| 677 |
Default value is 2. |
| 678 |
|
| 679 |
Example 1.20. Set path_mode parameter |
| 680 |
... |
| 681 |
modparam("registrar", "path_mode", 0) |
| 682 |
... |
| 683 |
|
| 684 |
3.22. path_use_received (integer) |
| 685 |
|
| 686 |
If set to 1, the “received” parameter of the first Path URI of a |
| 687 |
registration is set as received-uri and the NAT branch flag is set for |
| 688 |
this contact. This is useful if the registrar is placed behind a SIP |
| 689 |
loadbalancer, which passes the nat'ed UAC address as “received” |
| 690 |
parameter in its Path uri. |
| 691 |
|
| 692 |
Default value is 0 (disabled). |
| 693 |
|
| 694 |
Example 1.21. Set path_use_received parameter |
| 695 |
... |
| 696 |
modparam("registrar", "path_use_received", 1) |
| 697 |
... |
| 698 |
|
| 699 |
3.23. path_check_local (integer) |
| 700 |
|
| 701 |
If set to 1, when performing a lookup the Path (if present) is |
| 702 |
evaluated and if the first hop is local (according to “myself” test), |
| 703 |
we skip it to avoid unnecessary looping. |
| 704 |
|
| 705 |
This is useful if multiple servers are sharing a common location |
| 706 |
database, each saving contacts with their local address as the Path. |
| 707 |
|
| 708 |
Default value is 0 (disabled). |
| 709 |
|
| 710 |
Example 1.22. Set path_check_local parameter |
| 711 |
... |
| 712 |
modparam("registrar", "path_check_local", 1) |
| 713 |
... |
| 714 |
|
| 715 |
3.24. reg_callid_avp (string) |
| 716 |
|
| 717 |
obsolete. use match_option in registered function |
| 718 |
|
| 719 |
If reg_callid_avp is defined and populated when the registered() is |
| 720 |
invoked, the result is TRUE only if an active registration with the |
| 721 |
specified callID is found. |
| 722 |
|
| 723 |
Default value is NULL (disabled). |
| 724 |
|
| 725 |
Example 1.23. Set reg_callid_avp parameter |
| 726 |
... |
| 727 |
modparam("registrar", "reg_callid_avp", "$avp(s:avp)") |
| 728 |
... |
| 729 |
|
| 730 |
3.25. xavp_cfg (string) |
| 731 |
|
| 732 |
Defines the name of XAVP class to store runtime module config values. |
| 733 |
The values are stored as inner XAVPs, like $xavp(class=>attribute). |
| 734 |
Valid inner XAVP names: |
| 735 |
* match_callid - filter contacts by callid. Used in registered(). |
| 736 |
* match_contact - filter contacts by contact. Used in registered(). |
| 737 |
* match_received - filter contacts by received. Used in registered(). |
| 738 |
* rlf_bflags - filter contacts by branch flags. Used in lookup(). |
| 739 |
* q - q value of contact (integer 0-1000). It overrides q value given |
| 740 |
in contact header and default_q parameter. Used in save(). |
| 741 |
* expires - the expires value, to overwrite the value from SIP |
| 742 |
headers. Used in save(). |
| 743 |
* max_contacts - the number of maximum contacts to be stored for the |
| 744 |
current registration AoR. It overwrites the 'max_contacts' module |
| 745 |
parameter value. Used in save(). |
| 746 |
* socket - the string representing the socket on which the register |
| 747 |
request was received, as alternative to using the sock_hdr. Used in |
| 748 |
save(). |
| 749 |
* tcpconn_id This can be set with $conid, the TCP connection ID of |
| 750 |
the connection the current message. This is useful when calling |
| 751 |
save() on a reply route to set the connecion of the original |
| 752 |
request. Used in save(). |
| 753 |
|
| 754 |
For example if this parameter is set to 'reg', then the number of |
| 755 |
maximum contacts can be set in $xavp(reg=>max_contacts). |
| 756 |
|
| 757 |
Default value is NULL (disabled). |
| 758 |
|
| 759 |
Example 1.24. Set xavp_cfg parameter |
| 760 |
... |
| 761 |
modparam("registrar", "xavp_cfg", "reg") |
| 762 |
... |
| 763 |
request_route { |
| 764 |
... |
| 765 |
$xavp(reg=>max_contacts) = 4; |
| 766 |
$xavp(reg[0]=>expires) = 600; |
| 767 |
save("location"); |
| 768 |
... |
| 769 |
} |
| 770 |
... |
| 771 |
|
| 772 |
3.26. xavp_rcd (string) |
| 773 |
|
| 774 |
Defines the name of XAVP class to store details from the location |
| 775 |
records. The values are stored as inner XAVPs, like |
| 776 |
$xavp(class[0]=>attribute). Valid inner XAVP names: |
| 777 |
* ruid - the record's internal unique id. |
| 778 |
* contact - the record's contact value. |
| 779 |
* expires - the record's expires value. |
| 780 |
* received - the record's received value. |
| 781 |
* path - the record's path value. |
| 782 |
|
| 783 |
For example. if this parameter is set to 'ulrcd', then values are set |
| 784 |
in: |
| 785 |
* $xavp(ulrcd[0]=>ruid) |
| 786 |
* $xavp(ulrcd[0]=>contact) |
| 787 |
* $xavp(ulrcd[0]=>received) |
| 788 |
* $xavp(ulrcd[0]=>path) |
| 789 |
|
| 790 |
Default value is NULL (disabled). |
| 791 |
|
| 792 |
Example 1.25. Set xavp_rcd parameter |
| 793 |
... |
| 794 |
modparam("registrar", "xavp_rcd", "ulrcd") |
| 795 |
... |
| 796 |
|
| 797 |
3.27. xavp_rcd_mask (int) |
| 798 |
|
| 799 |
Defines what values to skip when xavp_rcd is stored. |
| 800 |
* 1 - ruid |
| 801 |
* 2 - contact |
| 802 |
* 4 - expires |
| 803 |
* 8 - received |
| 804 |
* 16 - path |
| 805 |
|
| 806 |
Default value is 0 (none). |
| 807 |
|
| 808 |
Example 1.26. Set xavp_rcd_mask parameter |
| 809 |
... |
| 810 |
# skip path value |
| 811 |
modparam("registrar", "xavp_rcd_mask", 16) |
| 812 |
... |
| 813 |
# skip path and expires values |
| 814 |
modparam("registrar", "xavp_rcd_mask", 20) |
| 815 |
... |
| 816 |
|
| 817 |
3.28. gruu_enabled (integer) |
| 818 |
|
| 819 |
If set to 1 and the “+sip.instance” parameter to Contact header of |
| 820 |
REGISTER is present, then the value of the parameter is saved to |
| 821 |
location and pub-gruu and temp-gruu addresses are generated. |
| 822 |
|
| 823 |
Set it to 0 if you want to ignore GRUU extensions in REGISTER. |
| 824 |
|
| 825 |
Default value is 1 (enabled). |
| 826 |
|
| 827 |
Example 1.27. Set gruu_enabled parameter |
| 828 |
... |
| 829 |
modparam("registrar", "gruu_enabled", 0) |
| 830 |
... |
| 831 |
|
| 832 |
3.29. outbound_mode (integer) |
| 833 |
|
| 834 |
If set to 0 this module will accept REGISTER requests that do not |
| 835 |
contain a “Supported:” header with the outbound options-tag. The 200 OK |
| 836 |
response to REGISTER requests that this module generates will not |
| 837 |
contain “Require:” or “Supported:” headers with the outbound |
| 838 |
options-tag. If the client has a “Require:” header with the outbound |
| 839 |
options tag the REGISTER will be rejected with a “420 Bad Extension” |
| 840 |
response. |
| 841 |
|
| 842 |
If set to 1 this module will accept REGISTER requests that do not |
| 843 |
contain a “Supported:” header with the outbound options-tag and |
| 844 |
REGISTER requests that do contain a Supported: or Requires: header with |
| 845 |
the outbound options-tag. When the client supports outbound the |
| 846 |
appropriate RFC5626 procedures will be followed. |
| 847 |
|
| 848 |
If set to 2 this module will reject REGISTER requests that do not |
| 849 |
contain a “Supported:” header with the outbound options-tag. When the |
| 850 |
client supports outbound the appropriate RFC5626 procedures will be |
| 851 |
followed. |
| 852 |
|
| 853 |
Default value is 0. |
| 854 |
|
| 855 |
Example 1.28. Set outbound_mode parameter |
| 856 |
... |
| 857 |
modparam("registrar", "outbound_mode", 2) |
| 858 |
... |
| 859 |
|
| 860 |
3.30. regid_mode (integer) |
| 861 |
|
| 862 |
If set to 0 this module will ignore the “regid” contact param when |
| 863 |
saving REGISTER request if the request does not indicate support for |
| 864 |
outbound. |
| 865 |
|
| 866 |
If set to 1 this module will use “regid” contact param (if present) |
| 867 |
when saving REGISTER request even if REGISTER request does not indicate |
| 868 |
support for outbound. |
| 869 |
|
| 870 |
Default value is 0. |
| 871 |
|
| 872 |
Example 1.29. Set regid_mode parameter |
| 873 |
... |
| 874 |
modparam("registrar", "regid_mode", 1) |
| 875 |
... |
| 876 |
|
| 877 |
3.31. flow_timer (integer) |
| 878 |
|
| 879 |
If set to 0 then this module will not add a “Flow-Timer:” header to 200 |
| 880 |
OK responses to REGISTER requests. |
| 881 |
|
| 882 |
If set to > 0 then this module will add a “Flow-Timer:” header |
| 883 |
containing this value to 200 OK responses to REGISTER requests. This |
| 884 |
parameter may only be set to a value > 0 when outbound_mode is set to 1 |
| 885 |
or 2. |
| 886 |
|
| 887 |
When set to a value greater than 0 this parameter should be set to |
| 888 |
slightly less than the connection timeout value between the UAC and the |
| 889 |
network (this corresponds to the core tcp_connection_lifetime option |
| 890 |
and websocket keepalive_timeout modparam). This parameter is most |
| 891 |
useful when you have a single edge proxy/registrar or if you have an |
| 892 |
edge proxy that cannot modify responses. If you are using a separate |
| 893 |
edge proxy you should consider leaving this parameter set to 0 and |
| 894 |
adding the “Flow-Timer:” header on the edge proxy as this allows you to |
| 895 |
keep all of the timer values for a specific flow in one configuration. |
| 896 |
|
| 897 |
Default value is 0. |
| 898 |
|
| 899 |
Example 1.30. Set flow_timer parameter |
| 900 |
... |
| 901 |
modparam("registrar", "flow_timer", 25) |
| 902 |
... |
| 903 |
|
| 904 |
3.32. contact_max_size (integer) |
| 905 |
|
| 906 |
Max size of URIs in “Contact:” header. |
| 907 |
|
| 908 |
The size of URIs in “Contact:” headers are checked to be lower or equal |
| 909 |
to this value. A warning is logged and a 400 Bad Request is sent in |
| 910 |
response to REGISTER requests with contact URIs that are longer than |
| 911 |
this value. |
| 912 |
|
| 913 |
If a database is used then you must make sure that your database model |
| 914 |
supports strings of the configured size in the column “contact” of the |
| 915 |
table specified in “save()” function. |
| 916 |
|
| 917 |
Default value is 512. |
| 918 |
|
| 919 |
Example 1.31. Set contact_max_size parameter |
| 920 |
... |
| 921 |
modparam("registrar", "contact_max_size", 1024) |
| 922 |
... |
| 923 |
|
| 924 |
3.33. event_callback (str) |
| 925 |
|
| 926 |
The name of the function in the KEMI configuration file (embedded |
| 927 |
scripting language such as Lua, Python, ...) to be executed instead of |
| 928 |
event_route[...] blocks. |
| 929 |
|
| 930 |
The function receives a string parameter with the name of the event. |
| 931 |
The only possible value currently is 'usrloc:contact-expired'. |
| 932 |
|
| 933 |
Default value is 'empty' (no function is executed for events). |
| 934 |
|
| 935 |
Example 1.32. Set event_callback parameter |
| 936 |
... |
| 937 |
modparam("registrar", "event_callback", "ksr_registrar_event") |
| 938 |
... |
| 939 |
-- event callback function implemented in Lua |
| 940 |
function ksr_registrar_event(evname) |
| 941 |
KSR.info( "Expired contact for " .. KSR.pv.getw("$ulc(exp=>aor)") .. "\n"); |
| 942 |
return 1; |
| 943 |
end |
| 944 |
... |
| 945 |
|
| 946 |
3.34. lookup_filter_mode (int) |
| 947 |
|
| 948 |
Control what filters should be applied to lookup(...) operations. It |
| 949 |
can be a combination (sum) of the next values: |
| 950 |
* 1 - apply the branch flags filter - return only contact records |
| 951 |
with branch flags matching at least one set inside xavp specified |
| 952 |
by xavp_cfg parameter with inner name rlf_bflags - e.g., |
| 953 |
$xavp(reg=>rlf_bflags). |
| 954 |
* 2 - apply the active tcp connection filter - return only contact |
| 955 |
records that have the associated TCP/TLS/WSS connection active. UDP |
| 956 |
and SCTP contacts are not filtered, all are returned. |
| 957 |
|
| 958 |
Default value is NULL (disabled). |
| 959 |
|
| 960 |
Example 1.33. Set xavp_cfg parameter |
| 961 |
... |
| 962 |
modparam("registrar", "xavp_cfg", "reg") |
| 963 |
modparam("registrar", "lookup_filter_mode", 1) |
| 964 |
... |
| 965 |
request_route { |
| 966 |
... |
| 967 |
$xavp(reg=>rlf_bflags) = 8; |
| 968 |
if(lookup("location")) { ... } |
| 969 |
... |
| 970 |
} |
| 971 |
... |
| 972 |
|
| 973 |
3.35. use_expired_contacts (int) |
| 974 |
|
| 975 |
Allow/Disallow the usage of the expired contacts. |
| 976 |
* 0 Disallow the usage of the expired contacts. |
| 977 |
* 1 Allow the usage of the expired contacts. |
| 978 |
|
| 979 |
Default value is 0 (Disallow). |
| 980 |
|
| 981 |
Example 1.34. Set use_expired_contacts parameter |
| 982 |
... |
| 983 |
modparam("registrar", "use_expired_contacts", 1) |
| 984 |
... |
| 985 |
|
| 986 |
kamctl rpc cfg.set_now_int registrar use_expired_contacts 1 |
| 987 |
kamctl rpc cfg.set_now_int registrar use_expired_contacts 0 |
| 988 |
|
| 989 |
4. Functions |
| 990 |
|
| 991 |
4.1. save(domain, [, flags [, uri]]) |
| 992 |
4.2. lookup(domain [, uri]) |
| 993 |
4.3. lookup_to_dset(domain [, uri]) |
| 994 |
4.4. lookup_branches(domain) |
| 995 |
4.5. lookup_xavp(ultable, uri, rxname, cxname) |
| 996 |
4.6. registered(domain [, uri [, match_option [, match_action]]]) |
| 997 |
4.7. add_sock_hdr(hdr_name) |
| 998 |
4.8. unregister(domain, uri[, ruid]) |
| 999 |
4.9. reg_fetch_contacts(domain, uri, profile) |
| 1000 |
4.10. reg_free_contacts(profile) |
| 1001 |
4.11. reg_send_reply() |
| 1002 |
4.12. reg_from_user(ultable, uri, mode) |
| 1003 |
|
| 1004 |
4.1. save(domain, [, flags [, uri]]) |
| 1005 |
|
| 1006 |
The function processes a REGISTER message. It can add, remove or modify |
| 1007 |
location records (in usrloc) depending on Contact and Expires header |
| 1008 |
fields in the REGISTER message. On success and when called from the |
| 1009 |
REQUEST_ROUTE, “200 OK” will be returned listing all contacts that are |
| 1010 |
currently in the location database. As a side effect, also branch flags |
| 1011 |
are stored in usrloc. On an error, an error message will be sent with a |
| 1012 |
short description in reason phrase. |
| 1013 |
|
| 1014 |
Meaning of the parameters is as follows: |
| 1015 |
* domain - Logical domain within the registrar. If a database is used |
| 1016 |
then this must be name of the table which stores the contacts. |
| 1017 |
* flags (optional) - the value may be a bitwise OR of the following |
| 1018 |
flags: |
| 1019 |
+ 0x01 - save the contacts only in memory cache with no DB |
| 1020 |
operation; |
| 1021 |
+ 0x02 - do not generate a SIP reply to the current REGISTER |
| 1022 |
request. When used in ONREPLY_ROUTE, this parameter is |
| 1023 |
obsolete. |
| 1024 |
+ 0x04 - store and maintain one contact per AoR. If there are |
| 1025 |
other contact addresses for AoR not matching current |
| 1026 |
registration, remove them. This mode ensures one contact per |
| 1027 |
AoR (user). |
| 1028 |
+ 0x08 - Do not apply expires_range or default_expires_range to |
| 1029 |
this registration. |
| 1030 |
+ 0x10 - prepare the headers for reply, used only if flag 0x02 |
| 1031 |
is set. |
| 1032 |
The flags may be given in decimal or hexadecimal format. |
| 1033 |
* uri (optional - flags param has to be set and can be 0 for default |
| 1034 |
behavior) - SIP URI to be used instead of To header URI. It can be |
| 1035 |
a dynamic string with pseudo-variables. |
| 1036 |
|
| 1037 |
Return codes: |
| 1038 |
* -2 - error, too many contacts for AOR. |
| 1039 |
* -1 - error. |
| 1040 |
* 1 - contacts inserted. |
| 1041 |
* 2 - contacts updated. |
| 1042 |
* 3 - contacts deleted. |
| 1043 |
* 4 - contacts returned. |
| 1044 |
|
| 1045 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and |
| 1046 |
REPLY_ROUTE. |
| 1047 |
|
| 1048 |
Example 1.35. save usage |
| 1049 |
... |
| 1050 |
save("location"); |
| 1051 |
save("location", "0x01"); |
| 1052 |
save("location", "0x00", "sip:[email protected]"); |
| 1053 |
... |
| 1054 |
|
| 1055 |
4.2. lookup(domain [, uri]) |
| 1056 |
|
| 1057 |
The lookup function extracts username and/or domain from Request-URI |
| 1058 |
and tries to find all contacts for the username in usrloc. If there are |
| 1059 |
no such contacts, -1 will be returned. If there are such contacts, |
| 1060 |
Request-URI will be overwritten with the contact that has the highest q |
| 1061 |
value and optionally the rest will be appended to the message |
| 1062 |
(depending on append_branches parameter value). As a side effect, also |
| 1063 |
branch flags are restored from usrloc. |
| 1064 |
|
| 1065 |
If the method_filtering option is enabled and request is initial |
| 1066 |
request without to-tag, the lookup function will return only the |
| 1067 |
contacts that support the method of the processed request. |
| 1068 |
|
| 1069 |
Meaning of the parameters is as follows: |
| 1070 |
* domain - Name of table that should be used for the lookup. |
| 1071 |
* uri (optional) - SIP URI to be used instead of R-URI. It can be a |
| 1072 |
dynamic string with pseudo-variables. |
| 1073 |
|
| 1074 |
Return codes: |
| 1075 |
* 1 - contacts found and returned. |
| 1076 |
* -1 - no contact found. |
| 1077 |
* -2 - contacts found, but method not supported. |
| 1078 |
* -3 - internal error during processing. |
| 1079 |
|
| 1080 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1081 |
|
| 1082 |
Example 1.36. lookup usage |
| 1083 |
... |
| 1084 |
lookup("location"); |
| 1085 |
switch ($retcode) {:1 |
| 1086 |
|
| 1087 |
case -1: |
| 1088 |
case -3: |
| 1089 |
sl_send_reply("404", "Not Found"); |
| 1090 |
exit; |
| 1091 |
case -2: |
| 1092 |
sl_send_reply("405", "Not Found"); |
| 1093 |
exit; |
| 1094 |
}; |
| 1095 |
... |
| 1096 |
|
| 1097 |
4.3. lookup_to_dset(domain [, uri]) |
| 1098 |
|
| 1099 |
Similar to lookup(...), but push the location contacts to destination |
| 1100 |
set, without changing the R-URI (first branch not changed, it creates |
| 1101 |
additional branches). For the meaning of the parameters and the return |
| 1102 |
codes, see the documentation for lookup(...) function. |
| 1103 |
|
| 1104 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1105 |
|
| 1106 |
Example 1.37. lookup_to_dset usage |
| 1107 |
... |
| 1108 |
lookup_to_dset("location"); |
| 1109 |
... |
| 1110 |
|
| 1111 |
4.4. lookup_branches(domain) |
| 1112 |
|
| 1113 |
The function performs lookup(domain) on r-uri and additional branches |
| 1114 |
(only branches that have no other attributes set than uri). |
| 1115 |
|
| 1116 |
Meaning of the parameters is as follows: |
| 1117 |
* domain - Name of table that should be used for the lookup. |
| 1118 |
|
| 1119 |
Return codes are propagated from the lookup(domain) function. |
| 1120 |
|
| 1121 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1122 |
|
| 1123 |
Example 1.38. lookup_branches usage |
| 1124 |
... |
| 1125 |
lookup_branches("location"); |
| 1126 |
... |
| 1127 |
|
| 1128 |
4.5. lookup_xavp(ultable, uri, rxname, cxname) |
| 1129 |
|
| 1130 |
Similar to lookup(...), but store the location record attributes in |
| 1131 |
XAVPs. Note that not all contact record fields are stored |
| 1132 |
|
| 1133 |
Meaning of the parameters: |
| 1134 |
* ultable - name of the usrloc table that is used for the lookup. |
| 1135 |
* uri - the URI to be searched in location table. |
| 1136 |
* rxname - name of the XAVP to store record attributes. These are: |
| 1137 |
+ aor - the address of record. |
| 1138 |
+ count - the number of contacts. |
| 1139 |
* cxname - name of the XAVP to store content attributes, name mapping |
| 1140 |
is done from the perspective of using them to send out SIP |
| 1141 |
requests. These are: |
| 1142 |
+ uri - the contact address. |
| 1143 |
+ socket - the socket of the contact record. |
| 1144 |
+ dsturi - the destination uri of the contact record (the |
| 1145 |
received field in location contact). |
| 1146 |
|
| 1147 |
This function can be used from ANY_ROUTE. |
| 1148 |
|
| 1149 |
Example 1.39. lookup_xavp usage |
| 1150 |
... |
| 1151 |
lookup_xavp("location", "$fu", "rul", "cul"); |
| 1152 |
xinfo("aor: $xavp(rul=>aor)\n"); |
| 1153 |
xinfo("number of contacts: $xavp(rul=>count)\n"); |
| 1154 |
xinfo("first contact record - uri: $xavp(cul=>uri)\n"); |
| 1155 |
xinfo("first contact record - socket: $xavp(cul=>socket)\n"); |
| 1156 |
... |
| 1157 |
|
| 1158 |
4.6. registered(domain [, uri [, match_option [, match_action]]]) |
| 1159 |
|
| 1160 |
The function returns true if the AOR in the URI is registered, false |
| 1161 |
otherwise. The function does not modify the message being processed, it |
| 1162 |
neither rewrites the Request-URI if a contact is found nor append |
| 1163 |
branches. If uri parameter is not provided, then it considered to be |
| 1164 |
the Request-URI for SIP requests and To-URI for SIP replies. |
| 1165 |
|
| 1166 |
Meaning of the parameters is as follows: |
| 1167 |
* domain - Name of table that should be used for the lookup. |
| 1168 |
* uri (optional) - SIP URI to be used instead of Request/To-URI. It |
| 1169 |
can be a dynamic string with pseudo-variables. |
| 1170 |
* match_option (optional) - flag parameter to restrict contact |
| 1171 |
search. use xavp_cfg to set the values to compare to. |
| 1172 |
flag values is as follows: |
| 1173 |
+ 1 - match_callid |
| 1174 |
+ 2 - match_received |
| 1175 |
+ 4 - match_contact |
| 1176 |
* match_action (optional) - actions to perform when match is |
| 1177 |
positive. |
| 1178 |
flag values is as follows: |
| 1179 |
+ 1 - restore the xavps associated with the matched contact |
| 1180 |
+ 2 - skip adding the matched location record attributes to |
| 1181 |
xavp_rcd (e.g., the ruid, contact, received, ...) |
| 1182 |
|
| 1183 |
This function can be used from ANY_ROUTE. |
| 1184 |
|
| 1185 |
Example 1.40. registered usage |
| 1186 |
... |
| 1187 |
if (registered("location")) { |
| 1188 |
sl_send_reply("100", "Trying"); |
| 1189 |
... |
| 1190 |
}; |
| 1191 |
... |
| 1192 |
$xavp(regcfg=>match_received) = $su; |
| 1193 |
if (registered("location","$rz:$Au", 2)) { |
| 1194 |
sl_send_reply("100", "Trying"); |
| 1195 |
... |
| 1196 |
}; |
| 1197 |
... |
| 1198 |
|
| 1199 |
4.7. add_sock_hdr(hdr_name) |
| 1200 |
|
| 1201 |
Adds a new header to the current REGISTER request with “hdr_name” which |
| 1202 |
contains the description of the received socket (proto:ip:port) |
| 1203 |
|
| 1204 |
This makes sense only in multiple replicated servers scenarios. |
| 1205 |
|
| 1206 |
Meaning of the parameters is as follows: |
| 1207 |
* hdr_name - header name to be used, it can be a static string or |
| 1208 |
contain variables. |
| 1209 |
|
| 1210 |
This function can be used from REQUEST_ROUTE. |
| 1211 |
|
| 1212 |
Example 1.41. add_sock_hdr usage |
| 1213 |
... |
| 1214 |
add_sock_hdr("Sock-Info"); |
| 1215 |
... |
| 1216 |
|
| 1217 |
4.8. unregister(domain, uri[, ruid]) |
| 1218 |
|
| 1219 |
The function removes contacts associated with 'uri' from the location |
| 1220 |
database. If 'ruid' is provided a specific contact is removed, if |
| 1221 |
'ruid' is not provided all the current contacts are removed. If 'ruid' |
| 1222 |
is provided and the “usrloc” module is using “db_mode=3”, 'uri' does |
| 1223 |
not need to be given and can be empty string. |
| 1224 |
|
| 1225 |
Meaning of the parameters is as follows: |
| 1226 |
* domain - Name of table that should be used for the lookup or |
| 1227 |
contact addresses. |
| 1228 |
* uri - The SIP URI address of the user which to remove the contact |
| 1229 |
addresses for. It can contain pseudo-variables that are evaluated |
| 1230 |
at runtime. |
| 1231 |
* ruid - The record unique ID for a specific contact to be removed. |
| 1232 |
It can contain pseudo-variables that are evaluated at runtime. |
| 1233 |
|
| 1234 |
This function can be used from ANY_ROUTE. |
| 1235 |
|
| 1236 |
Return values: |
| 1237 |
* 0 - Successfully deleted contact(s) |
| 1238 |
* -1 - Failed to extract or parse address of record from argument |
| 1239 |
* -2 - Error in unregistering user |
| 1240 |
* -3 - Contacts for AOR not found |
| 1241 |
|
| 1242 |
Example 1.42. unregister usage |
| 1243 |
... |
| 1244 |
unregister("location", "$ru"); |
| 1245 |
unregister("location", "sip:[email protected]"); |
| 1246 |
unregister("location", "$ru", "$ulc(caller=>ruid)"); |
| 1247 |
unregister("location", "", "$ruid"); |
| 1248 |
... |
| 1249 |
|
| 1250 |
4.9. reg_fetch_contacts(domain, uri, profile) |
| 1251 |
|
| 1252 |
The function fetches the contacts for 'uri' from table 'domain' to |
| 1253 |
pseudo-variable $ulc(profile). |
| 1254 |
|
| 1255 |
Meaning of the parameters is as follows: |
| 1256 |
* domain - Name of table that should be used for the lookup of |
| 1257 |
contact addresses. |
| 1258 |
* uri - The SIP URI address of the user which to fetch the contact |
| 1259 |
addresses for. It can contain pseudo-variables that are evaluated |
| 1260 |
at runtime. |
| 1261 |
* profile - Name of $ulc pseudo-variable profile that will store the |
| 1262 |
fetched contacts. It is a static string. |
| 1263 |
|
| 1264 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1265 |
|
| 1266 |
Example 1.43. reg_fetch_contacts usage |
| 1267 |
... |
| 1268 |
reg_fetch_contacts("location", "$ru", "callee"); |
| 1269 |
reg_fetch_contacts("location", "sip:[email protected]", "caller"); |
| 1270 |
... |
| 1271 |
|
| 1272 |
4.10. reg_free_contacts(profile) |
| 1273 |
|
| 1274 |
The function frees the contacts from pseudo-variable $ulc(profile). |
| 1275 |
Should be called to release the content of a profile. Anyhow, fetching |
| 1276 |
a new contact addresses set over a profile will release any existing |
| 1277 |
data in that profile. |
| 1278 |
|
| 1279 |
Meaning of the parameters is as follows: |
| 1280 |
* profile - Name of $ulc pseudo-variable profile that stores fetched |
| 1281 |
contacts. It is a static string. |
| 1282 |
|
| 1283 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1284 |
|
| 1285 |
Example 1.44. reg_free_contacts usage |
| 1286 |
... |
| 1287 |
reg_free_contacts("callee"); |
| 1288 |
... |
| 1289 |
|
| 1290 |
4.11. reg_send_reply() |
| 1291 |
|
| 1292 |
The function sends the SIP reply that is normally sent by save(...), |
| 1293 |
but that was skipped due to flag 0x2. It must be used after save(..., |
| 1294 |
"0x2"). Practically it allows saving registration to location table, do |
| 1295 |
other operations and then send the reply. |
| 1296 |
|
| 1297 |
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. |
| 1298 |
|
| 1299 |
Example 1.45. reg_send_reply usage |
| 1300 |
... |
| 1301 |
save("location", "0x2"); |
| 1302 |
... |
| 1303 |
reg_send_reply(); |
| 1304 |
... |
| 1305 |
|
| 1306 |
4.12. reg_from_user(ultable, uri, mode) |
| 1307 |
|
| 1308 |
The function returns true if the SIP message comes from the user |
| 1309 |
identified by 'uri' parameter by matching the associated location |
| 1310 |
records. The matching is done with the field 'received' if it is set, |
| 1311 |
otherwise with the contact address. |
| 1312 |
|
| 1313 |
Meaning of the parameters is as follows: |
| 1314 |
* ultable - user location table (e.g., 'location') |
| 1315 |
* uri - SIP URI to identify the location records to match against. |
| 1316 |
* mode - matching mode (int) - host part (IP address) is matched |
| 1317 |
always. If mode has bit 1 set (value 1), then the port is matched |
| 1318 |
as well. If mode has bit 2 set (value 2), then the protocol is |
| 1319 |
matched as well. |
| 1320 |
|
| 1321 |
This function can be used from ANY_ROUTE. |
| 1322 |
|
| 1323 |
Example 1.46. reg_from_user usage |
| 1324 |
... |
| 1325 |
if(reg_from_user("location", "sip:[email protected]", "0")) { |
| 1326 |
# message coming from where 'alice' sent before a REGISTER request |
| 1327 |
} |
| 1328 |
... |
| 1329 |
|
| 1330 |
5. Event Routes |
| 1331 |
|
| 1332 |
5.1. event_route[usrloc:contact-expired] |
| 1333 |
|
| 1334 |
5.1. event_route[usrloc:contact-expired] |
| 1335 |
|
| 1336 |
Executed when a contact in location table has expired. The variable |
| 1337 |
$ulc(exp=>...) is filled with the attributes of the expired contact. |
| 1338 |
|
| 1339 |
Example 1.47. event_route[usrloc:contact-expired] usage |
| 1340 |
... |
| 1341 |
event_route[usrloc:contact-expired] { |
| 1342 |
xlog("expired contact for $ulc(exp=>aor)\n"); |
| 1343 |
} |
| 1344 |
... |
| 1345 |
|
| 1346 |
6. Statistics |
| 1347 |
|
| 1348 |
6.1. max_expires |
| 1349 |
6.2. max_contacts |
| 1350 |
6.3. default_expires |
| 1351 |
6.4. accepted_regs |
| 1352 |
6.5. rejected_regs |
| 1353 |
|
| 1354 |
6.1. max_expires |
| 1355 |
|
| 1356 |
Value of max_expires parameter. |
| 1357 |
|
| 1358 |
6.2. max_contacts |
| 1359 |
|
| 1360 |
The value of max_contacts parameter. |
| 1361 |
|
| 1362 |
6.3. default_expires |
| 1363 |
|
| 1364 |
The value of default_expires parameter. |
| 1365 |
|
| 1366 |
6.4. accepted_regs |
| 1367 |
|
| 1368 |
Number of accepted registrations. |
| 1369 |
|
| 1370 |
6.5. rejected_regs |
| 1371 |
|
| 1372 |
Number of rejected registrations. |
| 1373 |
|
| 1374 |
7. Pseudo Variables |
| 1375 |
|
| 1376 |
7.1. $ulc(profile=>attr) |
| 1377 |
|
| 1378 |
7.1. $ulc(profile=>attr) |
| 1379 |
|
| 1380 |
Access the attributes of contact addresses stored in 'profile'. It must |
| 1381 |
be used after a call of “reg_fetch_contacts()”. |
| 1382 |
|
| 1383 |
The “profile” has to be one of the values used with |
| 1384 |
“reg_fetch_contacts()”. |
| 1385 |
|
| 1386 |
The “attr” can be: |
| 1387 |
* aor - address of record |
| 1388 |
* domain - used location domain/table name |
| 1389 |
* aorhash - hash id for the record |
| 1390 |
* addr - contact address |
| 1391 |
* path - path vector |
| 1392 |
* received - received address |
| 1393 |
* expires - expires value |
| 1394 |
* callid - call-id header value |
| 1395 |
* q - the q value |
| 1396 |
* cseq - the cseq value |
| 1397 |
* flags - flags value |
| 1398 |
* cflags - cflags value |
| 1399 |
* user_agent - user agent |
| 1400 |
* socket - local socket |
| 1401 |
* modified - last modified time |
| 1402 |
* methods - methods value |
| 1403 |
* count - number of contacts |
| 1404 |
* ruid - record unique ID |
| 1405 |
* regid - reg-id value |
| 1406 |
* instance - instance value |
| 1407 |
* conid - TCP socket internal connection ID ($null if UDP) |
| 1408 |
* server_id - server_id value |
| 1409 |
|
| 1410 |
The pseudo-variable accepts positive index value to access a specific |
| 1411 |
contact record. |
| 1412 |
|
| 1413 |
Example 1.48. $ulc(name) usage |
| 1414 |
... |
| 1415 |
if(reg_fetch_contacts("location", "$fu", "caller")) |
| 1416 |
{ |
| 1417 |
xlog("caller=>aor: $(ulc(caller=>aor))\n"); |
| 1418 |
xlog("caller=>domain: $(ulc(caller=>domain))\n"); |
| 1419 |
xlog("caller=>aorhash $(ulc(caller=>aorhash))\n"); |
| 1420 |
xlog("caller=>count $(ulc(caller=>count))\n"); |
| 1421 |
$var(i) = 0; |
| 1422 |
while($var(i) < $(ulc(caller=>count))) |
| 1423 |
{ |
| 1424 |
xlog("--- contact [$var(i)]\n"); |
| 1425 |
xlog("caller=>addr: $(ulc(caller=>addr)[$var(i)])\n"); |
| 1426 |
xlog("caller=>path: $(ulc(caller=>path)[$var(i)])\n"); |
| 1427 |
xlog("caller=>received: $(ulc(caller=>received)[$var(i)])\n"); |
| 1428 |
xlog("caller=>expires: $(ulc(caller=>expires)[$var(i)])\n"); |
| 1429 |
xlog("caller=>callid: $(ulc(caller=>callid)[$var(i)])\n"); |
| 1430 |
xlog("caller=>regid: $(ulc(caller=>regid)[$var(i)])\n"); |
| 1431 |
xlog("caller=>q: $(ulc(caller=>q)[$var(i)])\n"); |
| 1432 |
xlog("caller=>cseq: $(ulc(caller=>cseq)[$var(i)])\n"); |
| 1433 |
xlog("caller=>flags: $(ulc(caller=>flags)[$var(i)])\n"); |
| 1434 |
xlog("caller=>cflags: $(ulc(caller=>cflags)[$var(i)])\n"); |
| 1435 |
xlog("caller=>user_agent: $(ulc(caller=>user_agent)[$var(i)])\n"); |
| 1436 |
xlog("caller=>socket: $(ulc(caller=>socket)[$var(i)])\n"); |
| 1437 |
xlog("caller=>modified: $(ulc(caller=>modified)[$var(i)])\n"); |
| 1438 |
xlog("caller=>methods: $(ulc(caller=>methods)[$var(i)])\n"); |
| 1439 |
$var(i) = $var(i) + 1; |
| 1440 |
} |
| 1441 |
} |
| 1442 |
... |
| 1443 |
|
| 1444 |
Chapter 2. Frequently Asked Questions |
| 1445 |
|
| 1446 |
2.1. What happened with the old “nat_flag” module parameter? |
| 1447 |
2.2. What happened with the old “use_domain” module parameter? |
| 1448 |
2.3. What happened with the old “save_noreply” and “save_memory” |
| 1449 |
functions? |
| 1450 |
|
| 1451 |
2.4. Where can I find more about Kamailio? |
| 1452 |
2.5. Where can I post a question about this module? |
| 1453 |
2.6. How can I report a bug? |
| 1454 |
2.7. What happened to the desc_time_order parameter? |
| 1455 |
|
| 1456 |
2.1. |
| 1457 |
|
| 1458 |
What happened with the old “nat_flag” module parameter? |
| 1459 |
|
| 1460 |
In was removed, as the module internally loads this value from the |
| 1461 |
“USRLOC” module (see the “nat_bflag” USRLOC parameter). |
| 1462 |
|
| 1463 |
2.2. |
| 1464 |
|
| 1465 |
What happened with the old “use_domain” module parameter? |
| 1466 |
|
| 1467 |
In was removed, as the module internally loads this option from the |
| 1468 |
“USRLOC” module. This was done in order to simplify the configuration. |
| 1469 |
|
| 1470 |
2.3. |
| 1471 |
|
| 1472 |
What happened with the old “save_noreply” and “save_memory” functions? |
| 1473 |
|
| 1474 |
There functions were merged into the new “save(domain,flags)” |
| 1475 |
functions. If a reply should be sent or if the DB should be updated |
| 1476 |
also is controlled via the flags. |
| 1477 |
|
| 1478 |
2.4. |
| 1479 |
|
| 1480 |
Where can I find more about Kamailio? |
| 1481 |
|
| 1482 |
Take a look at https://www.kamailio.org/. |
| 1483 |
|
| 1484 |
2.5. |
| 1485 |
|
| 1486 |
Where can I post a question about this module? |
| 1487 |
|
| 1488 |
First at all check if your question was already answered on one of our |
| 1489 |
mailing lists: |
| 1490 |
* User Mailing List - |
| 1491 |
https://lists.kamailio.org/mailman3/postorius/lists/sr-users.lists. |
| 1492 |
kamailio.org/ |
| 1493 |
* Developer Mailing List - |
| 1494 |
https://lists.kamailio.org/mailman3/postorius/lists/sr-dev.lists.ka |
| 1495 |
mailio.org/ |
| 1496 |
|
| 1497 |
E-mails regarding any stable Kamailio release should be sent to |
| 1498 |
<[email protected]> and e-mails regarding development |
| 1499 |
versions should be sent to <[email protected]>. |
| 1500 |
|
| 1501 |
2.6. |
| 1502 |
|
| 1503 |
How can I report a bug? |
| 1504 |
|
| 1505 |
Please follow the guidelines provided at: |
| 1506 |
https://github.com/kamailio/kamailio/issues. |
| 1507 |
|
| 1508 |
2.7. |
| 1509 |
|
| 1510 |
What happened to the desc_time_order parameter? |
| 1511 |
|
| 1512 |
It was removed, as its functionality was migrated into usrloc module, |
| 1513 |
were there is a parameter with the same name. |