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