OVERVIEW:
[sip-router] / modules_k / registrar / README
1
2 registrar Module
3
4 Jan Janak
5
6    FhG FOKUS
7
8 Edited by
9
10 Jan Janak
11
12 Bogdan-Andre Iancu
13
14    Copyright © 2003 FhG FOKUS
15      _________________________________________________________
16
17    Table of Contents
18    1. User's Guide
19
20         1.1. Overview
21
22               1.1.1. PATH support
23
24         1.2. Dependencies
25
26               1.2.1. OpenSER Modules
27               1.2.2. External Libraries or Applications
28
29         1.3. Exported Parameters
30
31               1.3.1. default_expires (integer)
32               1.3.2. min_expires (integer)
33               1.3.3. max_expires (integer)
34               1.3.4. default_q (integer)
35               1.3.5. sip_natping_flag (integer)
36               1.3.6. tcp_persistent_flag (integer)
37               1.3.7. realm_prefix (string)
38               1.3.8. append_branches (integer)
39               1.3.9. aor_avp_id (integer)
40               1.3.10. case_sensitive (integer)
41               1.3.11. received_avp (integer)
42               1.3.12. received_param (string)
43               1.3.13. max_contacts (integer)
44               1.3.14. retry_after (integer)
45               1.3.15. sock_flag (integer)
46               1.3.16. sock_hdr_name (string)
47               1.3.17. method_filtering (integer)
48               1.3.18. use_path (integer)
49               1.3.19. path_mode (integer)
50               1.3.20. path_use_received (integer)
51
52         1.4. Exported Functions
53
54               1.4.1. save(domain)
55               1.4.2. save(domain,flags)
56               1.4.3. lookup(domain)
57               1.4.4. registered(domain)
58               1.4.5. add_sock_hdr(hdr_name)
59
60    2. Developer's Guide
61    3. Frequently Asked Questions
62
63    List of Examples
64    1-1. Set default_expires parameter
65    1-2. Set min_expires parameter
66    1-3. Set max_expires parameter
67    1-4. Set default_q parameter
68    1-5. Set sip_natping_flag parameter
69    1-6. Set tcp_persistent_flag parameter
70    1-7. Set realm_prefix parameter
71    1-8. Set append_branches parameter
72    1-9. Set aor_avp_id parameter
73    1-10. Set case_sensitive parameter
74    1-11. Set received_avp parameter
75    1-12. Set received_param parameter
76    1-13. Set max_contacts parameter
77    1-14. Set retry_after parameter
78    1-15. Set sock_flag parameter
79    1-16. Set sock_hdr_namer parameter
80    1-17. Set method_filtering parameter
81    1-18. Set use_path parameter
82    1-19. Set path_mode parameter
83    1-20. Set path_use_received parameter
84    1-21. save usage
85    1-22. save usage
86    1-23. lookup usage
87    1-24. registered usage
88    1-25. add_sock_hdr usage
89      _________________________________________________________
90
91 Chapter 1. User's Guide
92
93 1.1. Overview
94
95    The module contains REGISTER processing logic.
96      _________________________________________________________
97
98 1.1.1. PATH support
99
100    Register module includes Path support (according to RFC 3327)
101    for usage in registrars and home-proxies.
102
103    A call to save(...) stores, if path-support is enabled in the
104    registrar-module, the values of the Path Header(s) along with
105    the contact into usrloc. There are three modes regarding the
106    reply to a REGISTER including one or more Path HFs:
107
108      * off - stores the value of the Path headers into usrloc
109        without passing it back to the UAC in the reply.
110      * lazy - stores the Path header and passes it back to the
111        UAC if Path-support is indicated by the "path" param in
112        the Supported HF.
113      * strict - rejects the registration with "420 Bad Extension"
114        if there's a Path header but no support for it is
115        indicated by the UAC. Otherwise it's stored and passed
116        back to the UAC.
117
118    A call to lookup(...) always uses the path header if found,
119    and inserts it as Route HF either in front of the first Route
120    HF, or after the last Via HF if no Route is present. It also
121    sets the destination uri to the first Path uri, thus
122    overwriting the received-uri, because NAT has to be handled at
123    the outbound-proxy of the UAC (the first hop after client's
124    NAT).
125
126    The whole process is transparent to the user, so no config
127    changes are required beside setting the registrar-parameters
128    "use_path" and "path_mode".
129      _________________________________________________________
130
131 1.2. Dependencies
132
133 1.2.1. OpenSER Modules
134
135    The following modules must be loaded before this module:
136
137      * usrloc - User Location Module.
138      * sl - Stateless Replies.
139      _________________________________________________________
140
141 1.2.2. External Libraries or Applications
142
143    The following libraries or applications must be installed
144    before running OpenSER with this module loaded:
145
146      * None.
147      _________________________________________________________
148
149 1.3. Exported Parameters
150
151 1.3.1. default_expires (integer)
152
153    If the processed message contains neither Expires HFs nor
154    expires contact parameters, this value will be used for newly
155    created usrloc records. The parameter contains number of
156    second to expire (for example use 3600 for one hour).
157
158    Default value is 3600. 
159
160    Example 1-1. Set default_expires parameter
161 ...
162 modparam("registrar", "default_expires", 1800)
163 ...
164      _________________________________________________________
165
166 1.3.2. min_expires (integer)
167
168    The minimum expires value of a Contact, values lower than this
169    minimum will be automatically set to the minimum. Value 0
170    disables the checking.
171
172    Default value is 60. 
173
174    Example 1-2. Set min_expires parameter
175 ...
176 modparam("registrar", "min_expires", 60)
177 ...
178      _________________________________________________________
179
180 1.3.3. max_expires (integer)
181
182    The maximum expires value of a Contact, values higher than
183    this maximum will be automatically set to the maximum. Value 0
184    disables the checking.
185
186    Default value is 0. 
187
188    Example 1-3. Set max_expires parameter
189 ...
190 modparam("registrar", "max_expires", 120)
191 ...
192      _________________________________________________________
193
194 1.3.4. default_q (integer)
195
196    The parameter represents default q value for new contacts.
197    Because ser doesn't support float parameter types, the value
198    in the parameter is divided by 100 and stored as float. For
199    example, if you want default_q to be 0.38, use value 38 here.
200
201    Default value is 0. 
202
203    Example 1-4. Set default_q parameter
204 ...
205 modparam("registrar", "default_q", 100)
206 ...
207      _________________________________________________________
208
209 1.3.5. sip_natping_flag (integer)
210
211    The parameter specifies the flat to be used to mark the
212    contacts to be NAT pinged via a SIP request instead if dummy
213    UDP package. The flag will be stored in usrloc by the "save()"
214    functions and internally used by the "nathelper" module. The
215    flag will NOT be restore by the "lookup()" function.
216
217    Default value is -1 (disabled). 
218
219    Example 1-5. Set sip_natping_flag parameter
220 ...
221 modparam("registrar", "sip_natping_flag", 7)
222 ...
223      _________________________________________________________
224
225 1.3.6. tcp_persistent_flag (integer)
226
227    The parameter specifies the flat to be used to control the
228    module behaviour regarding TCP connections. If the flag is set
229    for a REGISTER via TCP containing a TCP contact, the module,
230    via the "save()" functions will set the lifetime of the TCP
231    connection to the contact expire value. By doing this, the TCP
232    connection will stay on as long as the contact is valid.
233
234    Default value is -1 (disabled). 
235
236    Example 1-6. Set tcp_persistent_flag parameter
237 ...
238 modparam("registrar", "tcp_persistent_flag", 7)
239 ...
240      _________________________________________________________
241
242 1.3.7. realm_prefix (string)
243
244    Prefix to be automatically strip from realm. As an alternative
245    to SRV records (not all SIP clients support SRV lookup), a
246    subdomain of the master domain can be defined for SIP purposes
247    (like sip.mydomain.net pointing to same IP address as the SRV
248    record for mydomain.net). By ignoring the realm_prefix "sip.",
249    at registration, sip.mydomain.net will be equivalent to
250    mydomain.net .
251
252    Default value is NULL (none). 
253
254    Example 1-7. Set realm_prefix parameter
255 ...
256 modparam("registrar", "realm_prefix", "sip.")
257 ...
258      _________________________________________________________
259
260 1.3.8. append_branches (integer)
261
262    The parameter controls how lookup function processes multiple
263    contacts. If there are multiple contacts for the given
264    username in usrloc and this parameter is set to 1, Request-URI
265    will be overwritten with the highest-q rated contact and the
266    rest will be appended to sip_msg structure and can be later
267    used by tm for forking. If the parameter is set to 0, only
268    Request-URI will be overwritten with the highest-q rated
269    contact and the rest will be left unprocessed.
270
271    Default value is 1. 
272
273    Example 1-8. Set append_branches parameter
274 ...
275 modparam("registrar", "append_branches", 0)
276 ...
277      _________________________________________________________
278
279 1.3.9. aor_avp_id (integer)
280
281    If set, the module will try first to get the AOR from the AVP
282    ID instead of fetching it form the processed request.
283
284    The AVP must contain a valid SIP URI. If no AVP is found, it
285    will be tried to get the AOR from the message (standard
286    behaviour).
287
288    Default value is 0 (disabled). 
289
290    Example 1-9. Set aor_avp_id parameter
291 ...
292 modparam("registrar", "aor_avp_id", 3223)
293 ...
294      _________________________________________________________
295
296 1.3.10. case_sensitive (integer)
297
298    If set to 1 then AOR comparison will be case sensitive, if set
299    to 0 then AOR comparison will be case insensitive--This is
300    recommended.
301
302    Default value is 0. 
303
304    Example 1-10. Set case_sensitive parameter
305 ...
306 modparam("registrar", "case_sensitive", 1)
307 ...
308      _________________________________________________________
309
310 1.3.11. received_avp (integer)
311
312    Registrar will store the value of the AVP configured by this
313    parameter in the received column in the user location
314    database. It will leave the column empty if the AVP is empty.
315    The AVP should contain a SIP URI consisting of the source IP,
316    port, and protocol of the REGISTER message being processed.
317
318    Note
319
320    The value of this parameter should be the same as the value of
321    corresponding parameter of nathelper module.
322
323    Default value is 42. 
324
325    Example 1-11. Set received_avp parameter
326 ...
327 modparam("registrar", "received_avp", 43)
328 ...
329      _________________________________________________________
330
331 1.3.12. received_param (string)
332
333    The name of the parameter that will be appended to Contacts of
334    200 OK when the received URI was set by nathelper module.
335
336    Default value is "received". 
337
338    Example 1-12. Set received_param parameter
339 ...
340 modparam("registrar", "received_param", "rcv")
341 ...
342      _________________________________________________________
343
344 1.3.13. max_contacts (integer)
345
346    The parameter can be used to limit the number of contacts per
347    AOR (Address of Record) in the user location database. Value 0
348    disables the check.
349
350    Default value is 0. 
351
352    Example 1-13. Set max_contacts parameter
353 ...
354 # Allow no more than 10 contacts per AOR
355 modparam("registrar", "max_contacts", 10)
356 ...
357      _________________________________________________________
358
359 1.3.14. retry_after (integer)
360
361    The registrar can generate 5xx reply to REGISTER in various
362    situations. It can, for example, happen when the max_contacts
363    parameter is set and the processing of REGISTER request would
364    exceed the limit. In this case the registrar would generate
365    "503 Service Unavailable" response.
366
367    If you want to add the Retry-After header field in 5xx
368    replies, set this parameter to a value grater than zero (0
369    means do not add the header field). See section 20.33 of
370    RFC3261 for more details.
371
372    Default value is 0 (disabled). 
373
374    Example 1-14. Set retry_after parameter
375 ...
376 modparam("registrar", "retry_after", 30)
377 ...
378      _________________________________________________________
379
380 1.3.15. sock_flag (integer)
381
382    Flag to signal to register module to look into REGISTER
383    request for a header which contains a socket description
384    (IP:port). This socket info will be stored by register instead
385    of the received socket info.
386
387    This make sens only in multiple replicated servers scenarios.
388
389    Default value is -1 (no flag). 
390
391    Example 1-15. Set sock_flag parameter
392 ...
393 modparam("registrar", "sock_flag", 18)
394 ...
395      _________________________________________________________
396
397 1.3.16. sock_hdr_name (string)
398
399    Header which contains a socket description (proto:IP:port) to
400    overide the the received socket info. The heaer will be read
401    only if the flag sock_flag is set.
402
403    This make sens only in multiple replicated servers scenarios.
404
405    Default value is NULL. 
406
407    Example 1-16. Set sock_hdr_namer parameter
408 ...
409 modparam("registrar", "sock_hdr_name", "Sock-Info")
410 ...
411      _________________________________________________________
412
413 1.3.17. method_filtering (integer)
414
415    Tells if the contact filtering based on supported methods
416    should be performed during lookup. It's enabled only if it has
417    a non zero value.
418
419    Default value is 0 (disabled). 
420
421    Example 1-17. Set method_filtering parameter
422 ...
423 modparam("registrar", "method_filtering", 1)
424 ...
425      _________________________________________________________
426
427 1.3.18. use_path (integer)
428
429    If set to 1, the Path header is handled according to the
430    parameter "path_mode".
431
432    Default value is 0 (disabled). 
433
434    Example 1-18. Set use_path parameter
435 ...
436 modparam("registrar", "use_path", 1)
437 ...
438      _________________________________________________________
439
440 1.3.19. path_mode (integer)
441
442    The registrar module implements three different modes
443    regarding the response to a registration which includes one or
444    more Path headers:
445
446      * 0 - The Path header is saved into usrloc, but is not
447        included in the reply.
448      * 1 - The Path header is saved into usrloc, but is only
449        included in the reply if path support is indicated in the
450        registration request by the "path" option of the
451        "Supported" header.
452      * 2 - The path header is only saved into usrloc, if path
453        support is indicated in the registration request by the
454        "path" option of the "Supported" header. If no path
455        support is indicated, the request is rejected with "420 -
456        Bad Extension" and the header "Unsupported: path" is
457        included in the reply along with the received "Path"
458        header. This mode is the one recommended by RFC-3327.
459
460    Default value is 2. 
461
462    Example 1-19. Set path_mode parameter
463 ...
464 modparam("registrar", "path_mode", 0)
465 ...
466      _________________________________________________________
467
468 1.3.20. path_use_received (integer)
469
470    If set to 1, the "received" parameter of the first Path uri of
471    a registration is set as received-uri and the NAT flag is set
472    for this contact. This is useful if the registrar is placed
473    behind a SIP loadbalancer, which passes the nat'ed UAC address
474    as "received" parameter in it's Path uri.
475
476    Default value is 0 (disabled). 
477
478    Example 1-20. Set path_use_received parameter
479 ...
480 modparam("registrar", "path_use_received", 1)
481 ...
482      _________________________________________________________
483
484 1.4. Exported Functions
485
486 1.4.1. save(domain)
487
488    The function processes a REGISTER message. It can add, remove
489    or modify usrloc records depending on Contact and Expires HFs
490    in the REGISTER message. On success, 200 OK will be returned
491    listing all contacts that are currently in usrloc. On an
492    error, error message will be send with a short description in
493    reason phrase.
494
495    Meaning of the parameters is as follows:
496
497      * domain - Logical domain within registrar. If database is
498        used then this must be name of the table which stores the
499        contacts.
500
501    This function can be used from REQUEST_ROUTE.
502
503    Example 1-21. save usage
504 ...
505 save("location");
506 ...
507      _________________________________________________________
508
509 1.4.2. save(domain,flags)
510
511    Same as save() but it accepts a set of flags for controlling
512    its behaviour.
513
514    Meaning of the parameters is as follows:
515
516      * domain - Logical domain within registrar. If database is
517        used then this must be name of the table which stores the
518        contacts.
519      * flags - the value may be a bitwise OR of the following
520        flags:
521           + 0x01 - save the contacts only in memory cache without
522             no DB operation;
523           + 0x02 - do not generate a SIP reply to the current
524             REGISTER request.
525        The flags may be given in decimal or hexa format.
526
527    This function can be used from REQUEST_ROUTE.
528
529    Example 1-22. save usage
530 ...
531 save("location","0x01");
532 ...
533      _________________________________________________________
534
535 1.4.3. lookup(domain)
536
537    The functions extracts username from Request-URI and tries to
538    find all contacts for the username in usrloc. If there are no
539    such contacts, -1 will be returned. If there are such
540    contacts, Request-URI will be overwritten with the contact
541    that has the highest q value and optionally the rest will be
542    appended to the message (depending on append_branches
543    parameter value).
544
545    If the method_filtering option is enabled, the lookup function
546    will return only the contacts that support the method of the
547    processed request.
548
549    Meaning of the parameters is as follows:
550
551      * domain - Name of table that should be used for the lookup.
552
553    Return codes:
554
555      * 1 - contacts found and returned.
556        -1 - no contact found.
557        -2 - contacts found, but method not supported.
558        -3 - internal error during processing.
559
560    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
561
562    Example 1-23. lookup usage
563 ...
564 lookup("location");
565 switch ($?) {
566     case -1:
567     case -3:
568         sl_send_reply("404", "Not Found");
569         exit;
570     case -2:
571         sl_send_reply("405", "Not Found");
572         exit;
573 };
574 ...
575      _________________________________________________________
576
577 1.4.4. registered(domain)
578
579    The function returns true if the AOR in the Request-URI is
580    registered, false otherwise. The function does not modify the
581    message being process, it neither rewrites the Request-URI if
582    a contact is found not append branches.
583
584    Meaning of the parameters is as follows:
585
586      * domain - Name of table that should be used for the lookup.
587
588    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
589
590    Example 1-24. registered usage
591 ...
592 if (registered("location")) {
593         sl_send_reply("100", "Trying");
594         ...
595 };
596 ...
597      _________________________________________________________
598
599 1.4.5. add_sock_hdr(hdr_name)
600
601    Adds to the current REGISTER request a new header with
602    "hdr_name" which contains the description of the received
603    socket (proto:ip:port)
604
605    This make sens only in multiple replicated servers scenarios.
606
607    Meaning of the parameters is as follows:
608
609      * hdr_name - header name to be used.
610
611    This function can be used from REQUEST_ROUTE.
612
613    Example 1-25. add_sock_hdr usage
614 ...
615 add_sock_hdr("Sock-Info");
616 ...
617      _________________________________________________________
618
619 Chapter 2. Developer's Guide
620
621    The module does not provide any API to use in other OpenSER
622    modules.
623      _________________________________________________________
624
625 Chapter 3. Frequently Asked Questions
626
627    3.1. What happend with the old "use_domain" module parameter?
628    3.2. What happend with the old "save_noreply" and
629           "save_memory" functions?
630
631    3.3. Where can I find more about OpenSER?
632    3.4. Where can I post a question about this module?
633    3.5. How can I report a bug?
634    3.6. What happened to the desc_time_order parameter?
635
636    3.1. What happend with the old "use_domain" module parameter?
637
638    In was removed, as the module internally loads this option
639    from the "USRLOC' module. This was done in order to simplify
640    the configuration. '"
641
642    3.2. What happend with the old "save_noreply" and
643    "save_memory" functions?
644
645    There functions were merged into the new "save(domain,flags)'
646    functions. If a reply should be sent or if the DB should be
647    updated also is controlled via the flags. '"
648
649    3.3. Where can I find more about OpenSER?
650
651    Take a look at http://openser.org/.
652
653    3.4. Where can I post a question about this module?
654
655    First at all check if your question was already answered on
656    one of our mailing lists:
657
658      * User Mailing List -
659        http://openser.org/cgi-bin/mailman/listinfo/users
660      * Developer Mailing List -
661        http://openser.org/cgi-bin/mailman/listinfo/devel
662
663    E-mails regarding any stable OpenSER release should be sent to
664    <users@openser.org> and e-mails regarding development versions
665    should be sent to <devel@openser.org>.
666
667    If you want to keep the mail private, send it to
668    <team@openser.org>.
669
670    3.5. How can I report a bug?
671
672    Please follow the guidelines provided at:
673    http://sourceforge.net/tracker/?group_id=139143.
674
675    3.6. What happened to the desc_time_order parameter?
676
677    It was removed, as its functionality was mmigrate into usrloc
678    module, were there is a parameter with the same name.