diff --git a/src/modules/rr/README b/src/modules/rr/README index 6d49a9295fd..8b137891791 100644 --- a/src/modules/rr/README +++ b/src/modules/rr/README @@ -1,850 +1 @@ -rr Module -Jan Janak - - FhG FOKUS - -Bogdan-Andrei Iancu - - Voice Sistem SRL - -Carsten Bock - - ng-voice.com - -Edited by - -Jan Janak - -Bogdan-Andrei Iancu - - Copyright © 2003 FhG FOKUS - - Copyright © 2005 Voice Sistem SRL - - Copyright © 2011 Carsten Bock, carsten@ng-voice.com - __________________________________________________________________ - - Table of Contents - - 1. Admin Guide - - 1. Overview - 2. Dialog support - 3. Dependencies - - 3.1. Kamailio Modules - 3.2. External Libraries or Applications - - 4. Parameters - - 4.1. enable_full_lr (integer) - 4.2. append_fromtag (integer) - 4.3. enable_double_rr (integer) - 4.4. add_username (integer) - 4.5. enable_socket_mismatch_warning (integer) - 4.6. custom_user_avp (avp string) - 4.7. force_send_socket (int) - 4.8. ignore_sips (int) - 4.9. sockname_mode (int) - - 5. Functions - - 5.1. loose_route() - 5.2. loose_route_preloaded() - 5.3. loose_route_mode(vmode) - 5.4. record_route([sparams]) - 5.5. remove_record_route() - 5.6. record_route_preset(string [,string2]) - 5.7. record_route_advertised_address(address) - 5.8. add_rr_param(param) - 5.9. check_route_param(re) - 5.10. is_direction(dir) - 5.11. rr_next_hop_route() - - 6. Exported Pseudo Variables - - 6.1. $route_uri - - 2. Developer Guide - - 1. Available Functions - - 1.1. record_route(string) - 1.2. record_route_advertised_address(string) - 1.3. add_rr_param( msg, param) - 1.4. check_route_param( msg, re) - 1.5. is_direction( msg, dir) - 1.6. get_route_param( msg, name, val) - 1.7. register_rrcb( callback, param) - - 2. Examples - - List of Examples - - 1.1. Dialog support in RR module - 1.2. Set enable_full_lr parameter - 1.3. Set append_fromtag parameter - 1.4. Set enable_double_rr parameter - 1.5. Set enable_double_rr to 2 to always have two explicit RR headers - 1.6. Set add_username parameter - 1.7. enable_socket_mismatch_warning usage - 1.8. custom_user_avp usage - 1.9. Set force_send_socket parameter - 1.10. Set ignore_sips parameter - 1.11. Set sockname_mode parameter - 1.12. loose_route usage - 1.13. loose_route_preloaded usage - 1.14. loose_route_mode usage - 1.15. record_route usage - 1.16. remove_record_route usage - 1.17. record_route_preset usage - 1.18. record_route_advertised_address usage - 1.19. add_rr_param usage - 1.20. check_route_param usage - 1.21. is_direction usage - 1.22. rr_next_hop_route usage - 1.23. $route_uri - 2.1. record_route usage - 2.2. record_route_advertised_address usage - 2.3. Loading RR module's API from another module - -Chapter 1. Admin Guide - - Table of Contents - - 1. Overview - 2. Dialog support - 3. Dependencies - - 3.1. Kamailio Modules - 3.2. External Libraries or Applications - - 4. Parameters - - 4.1. enable_full_lr (integer) - 4.2. append_fromtag (integer) - 4.3. enable_double_rr (integer) - 4.4. add_username (integer) - 4.5. enable_socket_mismatch_warning (integer) - 4.6. custom_user_avp (avp string) - 4.7. force_send_socket (int) - 4.8. ignore_sips (int) - 4.9. sockname_mode (int) - - 5. Functions - - 5.1. loose_route() - 5.2. loose_route_preloaded() - 5.3. loose_route_mode(vmode) - 5.4. record_route([sparams]) - 5.5. remove_record_route() - 5.6. record_route_preset(string [,string2]) - 5.7. record_route_advertised_address(address) - 5.8. add_rr_param(param) - 5.9. check_route_param(re) - 5.10. is_direction(dir) - 5.11. rr_next_hop_route() - - 6. Exported Pseudo Variables - - 6.1. $route_uri - -1. Overview - - The module contains record routing logic - -2. Dialog support - - Kamailio is basically only a transaction stateful proxy, without any - dialog support build in. There are many features/services which - actually requires a dialog awareness, like storing the information in - the dialog creation stage, information which will be used during the - whole dialog existence. - - The most urging example is NAT traversal, in dealing with the within - the dialog INVITEs (re-INVITEs). When processing the initial INVITE, - the proxy detects if the caller or callee is behind some NAT and fixes - the signalling and media parts - since not all the detection mechanism - are available for within the dialog requests (like usrloc), to be able - to fix correspondingly the sequential requests, the proxy must remember - that the original request was NAT processed. There are many other cases - where dialog awareness fixes or helps. - - The solution is to store additional dialog-related information in the - routing set (Record-Route/Route headers), headers which show up in all - sequential requests. So any information added to the Record-Route - header will be found (with no direction dependencies) in Route header - (corresponding to the proxy address). - - As storage container, the parameters of the Record-Route / Route header - will be used - Record-Route parameters mirroring are reinforced by RFC - 3261 (see 12.1.1 UAS behavior). - - For this purpose, the modules offers the following functions: - * add_rr_param() - see Section 5.8, “add_rr_param(param)” - * check_route_param() - see Section 5.9, “check_route_param(re)” - - Example 1.1. Dialog support in RR module -... -UAC Kamailio PROXY UAS - ----- INVITE ------> record_route() ----- INVITE ----> - add_rr_param(";foo=true") - ---- reINVITE -----> loose_route() ---- reINVITE ---> - check_route_param(";foo=true") - -<-- reINVITE ------ loose_route() <--- reINVITE ---- - check_route_param(";foo=true") - -<------ BYE ------- loose_route() <----- BYE ------- - check_route_param(";foo=true") -... - -3. Dependencies - - 3.1. Kamailio Modules - 3.2. External Libraries or Applications - -3.1. Kamailio Modules - - The following modules must be loaded before this module: - * (optional) The "outbound" module is needed for outbound routing as - per RFC 5626. - -3.2. External Libraries or Applications - - The following libraries or applications must be installed before - running Kamailio with this module loaded: - * None. - -4. Parameters - - 4.1. enable_full_lr (integer) - 4.2. append_fromtag (integer) - 4.3. enable_double_rr (integer) - 4.4. add_username (integer) - 4.5. enable_socket_mismatch_warning (integer) - 4.6. custom_user_avp (avp string) - 4.7. force_send_socket (int) - 4.8. ignore_sips (int) - 4.9. sockname_mode (int) - -4.1. enable_full_lr (integer) - - If set to 1 then “;lr=on” instead of just “;lr” will be used. This is - to overcome problems with broken UAs which strip “;lr” parameter when - generating Route header fields from Record-Route (“;lr=on” seems to - help). - - Default value is 0 (no). - - Example 1.2. Set enable_full_lr parameter -... -modparam("rr", "enable_full_lr", 1) -... - -4.2. append_fromtag (integer) - - If turned on, request's from-tag is appended to record-route; that's - useful for understanding whether subsequent requests (such as BYE) come - from caller (route's from-tag==BYE's from-tag) or callee (route's - from-tag==BYE's to-tag) - - Default value is 1 (yes). - - Example 1.3. Set append_fromtag parameter -... -modparam("rr", "append_fromtag", 0) -... - -4.3. enable_double_rr (integer) - - There are some situations when the server needs to insert two - Record-Route header fields instead of one. For example when using two - disconnected networks or doing cross-protocol forwarding from UDP->TCP. - This parameter enables inserting of 2 Record-Routes. The server will - later remove both of them. - - Double record-routing does not occur when outbound is used for a - request. - - Default value is 1 (yes). - - Example 1.4. Set enable_double_rr parameter -... -modparam("rr", "enable_double_rr", 0) -... - - Some useragents (e. g. Linphone) incorrectly use UDP transport for - subsequent requests in dialog, despite being configured to use another - SIP transport protocol. This can be worked around by setting - Record-Route header with explicit transport attribute. But - enable_double_rr enabled in default mode omits transport attribute from - being added to header if it detects that both sender and receiver use - same protocol (e. g. TCP or TLS), and this results in UDP being used by - such broken clients. Set enable_double_rr to value 2 to always have two - RR headers with transport attributes explicitly set. - - Example 1.5. Set enable_double_rr to 2 to always have two explicit RR - headers -... -modparam("rr", "enable_double_rr", 2) -... - -4.4. add_username (integer) - - If set to a non 0 value (which means yes), the username part will be - also added in the Record-Route URI. - - This option cannot be set when the “outbound” module is loaded before - this module as outbound uses the username part of Record-Route URIs to - store flow-tokens. - - Default value is 0 (no). - - Example 1.6. Set add_username parameter -... -modparam("rr", "add_username", 1) -... - -4.5. enable_socket_mismatch_warning (integer) - - When a preset record-route header is forced in Kamailio config and the - host from the record-route header is not the same as the host server, a - warning will be printed out in the logs. The - 'enable_socket_mismatch_warning' parameter enables or disables the - warning. When Kamailio is behind a NATed firewall, we don't want this - warning to be printed for every bridged call. - - Default value is 1 (yes). - - Example 1.7. enable_socket_mismatch_warning usage -... -modparam("rr", "enable_socket_mismatch_warning", 0) -... - -4.6. custom_user_avp (avp string) - - When enable_username is enabled, a call to record_route will add the - username of the RequestURI to the Record-Route URI. This parameter - allows you to setup an AVP with which you can customise the username to - be added in the Record-Route URI. - - Default value: if not set, the std add_username behaviour is used - - i.e. Request URI username. - - Example 1.8. custom_user_avp usage -... -modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)") - -#usage in cfg file -$avp(RR_CUSTOM_USER_AVP)="mo"; -record_route(); -... - -4.7. force_send_socket (int) - - If set to 1, local socket is forced even for single Record-Route, - otherwise is done on double Record-Route (should that be enabled). - - When use of “outbound” is enabled, the socket is not forced. - - Default value is 0. - - Example 1.9. Set force_send_socket parameter -... -modparam("rr", "force_send_socket", 1) -... - -4.8. ignore_sips (int) - - If set to 1, the Record-Route header are build with 'sip' schema - always, ignoring the presence of 'sips' schema in request URI. - - Default value is 0 (use 'sips' if present in R-URI). - - Example 1.10. Set ignore_sips parameter -... -modparam("rr", "ignore_sips", 1) -... - -4.9. sockname_mode (int) - - If set to 1, the Record-Route URI is built to contain socket name in - 'sn' parameter. - - Default value is 0. - - Example 1.11. Set sockname_mode parameter -... -modparam("rr", "sockname_mode", 1) -... - -5. Functions - - 5.1. loose_route() - 5.2. loose_route_preloaded() - 5.3. loose_route_mode(vmode) - 5.4. record_route([sparams]) - 5.5. remove_record_route() - 5.6. record_route_preset(string [,string2]) - 5.7. record_route_advertised_address(address) - 5.8. add_rr_param(param) - 5.9. check_route_param(re) - 5.10. is_direction(dir) - 5.11. rr_next_hop_route() - -5.1. loose_route() - - The function performs routing of SIP requests which contain a route - set. The name is a little bit confusing, as this function also routes - requests which are in the “strict router” format. - - This function is usually used to route in-dialog requests (like ACK, - BYE, reINVITE). Nevertheless also out-of-dialog requests can have a - “pre-loaded route set” and my be routed with loose_route. It also takes - care of translating between strict-routers and loose-router. - - The loose_route function analyzes the Route: headers in the requests. - If there is no Route: header, the function returns FALSE and routing - should be done with normal lookup functions. If a Route: header is - found, the function returns 1 and behaves as described in section 16.12 - of RFC 3261. There is only one exception: If the request is - out-of-dialog (no to-tag) and there is only one Route: header - indicating the local proxy, then the Route: header is removed and the - function returns FALSE. - - When the “outbound” module was loaded before this module and the Route: - header contains a username part this function will attempt to use the - username part as a flow-token for routing. If route calculation based - on flow-token succeeds, function returns TRUE even if there is only one - Route: header indicating the local proxy. - - Make sure your loose_routing function can't be used by attackers to - bypass proxy authorization. - - The loose_routing topic is very complex. See the RFC3261 for more - details (grep for “route set” is a good starting point in this - comprehensive RFC). - - Return codes: - * 1 - route calculation has been successful - * 2 - route calculation based on flow-token has been successful - * -1 - route calculation has been unsuccessful - * -2 - outbound flow-token shows evidence of tampering - * -3 - next hop is taken from a preloaded route set - - This function can be used from REQUEST_ROUTE. - - Example 1.12. loose_route usage -... -loose_route(); -... - -5.2. loose_route_preloaded() - - The function is similar to `loose_route()`, but it returns 1 (true) - when the Route header is preloaded (is in an initial request) and -1 - (false) if processing of the Route header failed or it is for requests - within dialog. - - It is a convenient function to use for routing initial requests on an - edge proxy that adds Path header to REGISTER requests. - - This function can be used from REQUEST_ROUTE. - - Example 1.13. loose_route_preloaded usage -... -if(!loose_route_preloaded()) { - sl_send_reply("404" "Preloaded route expected"); - exit; -} -... - -5.3. loose_route_mode(vmode) - - The function is similar to `loose_route()`, but it does only loose - routing processing if vmode==1, skipping the testing of r-uri==myself - for performing strict routing. If vmode==0, it behaves like - loose_route(). - - It is a convenient function to use with application servers that set - the Contact URI to SIP server address. - - This function can be used from REQUEST_ROUTE. - - Example 1.14. loose_route_mode usage -... -if(has_totag() and uri==myself) { - if(loose_route_mode("1")) { - rewritehostport("my.app.server:5090"); - t_relay(); - exit; - } -} -... - -5.4. record_route([sparams]) - - The function adds a new Record-Route header field. The header field - will be inserted in the message before any other Record-Route header - fields. - - If any string is passed as parameter, it will be appended as URI - parameter to the Record-Route header. The string must follow the - “;name=value” scheme and it may contain pseudo-variables. - - When the “outbound” module was loaded before this module this function - will determine whether outbound is required for the request and - generate and add a flow-token as the username part of the - Record-Route-URI. - - Note: if append From-tag is enabled and the function is used for - requests within dialog, it must be executed after loose_route() in - order to detect properly the direction. - - This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and - FAILURE_ROUTE. - - Example 1.15. record_route usage -... -record_route(); -... - -5.5. remove_record_route() - - The function removes the internal lumps added by record_route() - functions. - - Can be used to revert adding Record-Route header(s). - - This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. - - Example 1.16. remove_record_route usage -... -remove_record_route(); -... - -5.6. record_route_preset(string [,string2]) - - This function will put the string into Record-Route, don't use unless - you know what you are doing. - - Meaning of the parameters is as follows: - * string - String to be inserted into the first header field; it may - contain pseudo-variables. - * string2 - String to be inserted into the second header field; it - may contain pseudo-variables. - - Note: If 'string2' is present, then the 'string' param is pointing to - the outbound interface and the 'string2' param is pointing to the - inbound interface. - - When the “outbound” module was loaded before this module this function - will determine whether outbound is required for the request and - generate and add a flow-token as the username part of the - Record-Route-URI. - - This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and - FAILURE_ROUTE. - - Example 1.17. record_route_preset usage -... -record_route_preset("1.2.3.4:5090"); -... - -5.7. record_route_advertised_address(address) - - The function adds a new Record-Route header field using the address - given. The header field will be inserted in the message before any - other Record-Route header fields. - - When the “outbound” module was loaded before this module this function - will determine whether outbound is required for the request and - generate and add a flow-token as the username part of the - Record-Route-URI. - - Meaning of the parameter is as follows: - * address - Advertised address to use in the header; it may contain - pseudo-variables. - - If double record-routing is enabled two Record-Route headers will be - inserted with the same given address with different transports if the - transport changes. - - This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and - FAILURE_ROUTE. - - Example 1.18. record_route_advertised_address usage -... -record_route_advertised_address("1.2.3.4:5080"); -... - -5.8. add_rr_param(param) - - Adds a parameter to the Record-Route URI (param must be in - “;name=value” format. The function may be called also before or after - the record_route() or record_route_advertised_address() calls (see - Section 5.4, “record_route([sparams])” or Section 5.7, - “record_route_advertised_address(address)”)). - - Meaning of the parameters is as follows: - * param - String containing the URI parameter to be added. It must - follow the “;name=value” scheme; it may contain pseudo-variables. - - This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and - FAILURE_ROUTE. - - Example 1.19. add_rr_param usage -... -add_rr_param(";nat=yes"); -... - -5.9. check_route_param(re) - - The function checks if the URI parameters of the local Route header - (corresponding to the local server) matches the given regular - expression. It must be call after loose_route() (see Section 5.1, - “loose_route()”). - - Meaning of the parameters is as follows: - * re - regular expression to check against the Route URI parameters. - - This function can be used from REQUEST_ROUTE. - - Example 1.20. check_route_param usage -... -if (check_route_param("nat=yes")) { - setflag(6); -} -... - -5.10. is_direction(dir) - - The function checks the flow direction of in-dialog requests. This - function uses the “ftag” parameter from the Route header, therefore the - append_fromtag (see ??? module parameter must be enabled. Also this - must be called only after loose_route() (see Section 5.1, - “loose_route()”). - - The function returns true if the “dir” is the same with the request's - flow direction. - - The “downstream” direction means that the request is in the same - direction as the initial request that created the dialog. - - Meaning of the parameters is as follows: - * dir - string containing the direction to be checked. It may be - “upstream” (from callee to caller) or “downstream” (caller to - callee). - - This function can be used from REQUEST_ROUTE. - - Example 1.21. is_direction usage -... -if (is_direction("downstream")) { - xdbg("in-dialog request from caller to callee (downstream) ($rm)\n"); -} else { - xdbg("in-dialog request from callee to caller (upstream) ($rm)\n"); -} -... - -5.11. rr_next_hop_route() - - The function returns 1 (true) if there is a Route header for the next - hop address. It has to be used after loose_route(), when the local - Route headers are processed. - - This function can be used from ANY_ROUTE. - - Example 1.22. rr_next_hop_route usage -... -if(loose_route) { - if(rr_next_hop_route()) { - # next hop address is from Route header - } - -} -... - -6. Exported Pseudo Variables - - 6.1. $route_uri - -6.1. $route_uri - - Returns the URI of the top route-header. - - Example 1.23. $route_uri -... - xdbg("Route-URI is: $route_uri\n"); -... - -Chapter 2. Developer Guide - - Table of Contents - - 1. Available Functions - - 1.1. record_route(string) - 1.2. record_route_advertised_address(string) - 1.3. add_rr_param( msg, param) - 1.4. check_route_param( msg, re) - 1.5. is_direction( msg, dir) - 1.6. get_route_param( msg, name, val) - 1.7. register_rrcb( callback, param) - - 2. Examples - - The RR module provides an internal API to be used by other Kamailio - modules. The API offers support for SIP dialog based functionalities - - for more about the dialog support offered by RR module, see Section 2, - “Dialog support”. - - For internal(non-script) usage, the RR module offers to other module - the possibility to register callback functions to be executed each time - a local Route header is processed. The callback function will receive - as parameter the register parameter and the Route header parameter - string. - -1. Available Functions - - 1.1. record_route(string) - 1.2. record_route_advertised_address(string) - 1.3. add_rr_param( msg, param) - 1.4. check_route_param( msg, re) - 1.5. is_direction( msg, dir) - 1.6. get_route_param( msg, name, val) - 1.7. register_rrcb( callback, param) - -1.1. record_route(string) - - The function adds a new Record-Route header field. The header field - will be inserted in the message before any other Record-Route header - fields. - - If any string is passed as parameter, it will be appended as URI - parameter to the Record-Route header. The string must follow the - “;name=value” scheme and it may contain pseudo-variables. - - This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and - FAILURE_ROUTE. - - Example 2.1. record_route usage -... -record_route(); -... - -1.2. record_route_advertised_address(string) - - This function will add the string into a new Record-Route header field. - Don't use unless you know what you are doing. The header field will be - inserted in the message before any other Record-Route header fields. - - Meaning of the parameters is as follows: - * string - String to be inserted into the header field. - - Calls to add_rr_param() will add parameters to the Record-Route header. - Note: A second Record-Route will be inserted if the transport used on - the inbound and outbound interfaces changes. - - Example 2.2. record_route_advertised_address usage -... -record_route_advertised_address("1.2.3.4:5090"); -... - -1.3. add_rr_param( msg, param) - - Adds a parameter to the requests's Record-Route URI (param must be in - “;name=value” format). - - The function returns 0 on success. Otherwise, -1 is returned. - - Meaning of the parameters is as follows: - * struct sip_msg* msg - request that will has the parameter “param” - added to its Record-Route header. - * str* param - parameter to be added to the Record-Route header - it - must be in “;name=value” format. - -1.4. check_route_param( msg, re) - - The function checks for the request “msg” if the URI parameters of the - local Route header (corresponding to the local server) matches the - given regular expression “re”. It must be call after the loose_route - was done. - - The function returns 0 on success. Otherwise, -1 is returned. - - Meaning of the parameters is as follows: - * struct sip_msg* msg - request that will has the Route header - parameters checked. - * regex_t* param - compiled regular expression to be checked against - the Route header parameters. - -1.5. is_direction( msg, dir) - - The function checks the flow direction of the request “msg”. As for - checking it's used the “ftag” Route header parameter, the - append_fromtag (see ??? module parameter must be enables. Also this - must be call only after the loose_route is done. - - The function returns 0 if the “dir” is the same with the request's flow - direction. Otherwise, -1 is returned. - - Meaning of the parameters is as follows: - * struct sip_msg* msg - request that will have the direction checked. - * int dir - direction to be checked against. It may be - “RR_FLOW_UPSTREAM” or “RR_FLOW_DOWNSTREAM”. - -1.6. get_route_param( msg, name, val) - - The function search in to the “msg”'s Route header parameters the - parameter called “name” and returns its value into “val”. It must be - call only after the loose_route is done. - - The function returns 0 if parameter was found (even if it has no - value). Otherwise, -1 is returned. - - Meaning of the parameters is as follows: - * struct sip_msg* msg - request that will have the Route header - parameter searched. - * str *name - contains the Route header parameter to be searched. - * str *val - returns the value of the searched Route header parameter - if found. It might be empty string if the parameter had no value. - -1.7. register_rrcb( callback, param) - - The function register a new callback (along with its parameter). The - callback will be called when a loose route will be performed for the - local address. - - The function returns 0 on success. Otherwise, -1 is returned. - - Meaning of the parameters is as follows: - * rr_cb_t callback - callback function to be registered. - * void *param - parameter to be passed to the callback function. - -2. Examples - - Example 2.3. Loading RR module's API from another module -... -#include "../rr/api.h" -... -struct rr_binds my_rrb; -... -... -/* load the RR API */ -if (load_rr_api( &my_rrb )!=0) { - LM_ERR("can't load RR API\n"); - goto error; -} -... -... -/* register a RR callback */ -if (my_rrb.register_rrcb(my_callback,0))!=0) { - LM_ERR("can't register RR callback\n"); - goto error; -} -...