src/modules/path/README
4ffba491
 path Module
 
 Andreas Granig
 
    Inode GmbH
 
 Edited by
 
 Andreas Granig
 
99415516
 Richard Fuchs
 
11b7630b
    Copyright © 2006 Inode GmbH
d9bb387b
      __________________________________________________________________
4ffba491
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
4ffba491
 
d9bb387b
         1. Overview
4ffba491
 
45e50b14
               1.1. Path Insertion For Registrations
d9bb387b
               1.2. Outbound routing to NAT'ed UACs
4ffba491
 
d9bb387b
         2. Dependencies
4ffba491
 
d9bb387b
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
4ffba491
 
ba7961bb
         3. Parameters
4ffba491
 
d9bb387b
               3.1. use_received (int)
7fc44593
               3.2. received_format (int)
981701d4
               3.3. received_name (str)
               3.4. enable_r2 (int)
               3.5. sockname_mode (int)
4ffba491
 
ba7961bb
         4. Functions
4ffba491
 
d9bb387b
               4.1. add_path()
               4.2. add_path(user)
99415516
               4.3. add_path(user, parameters)
               4.4. add_path_received()
               4.5. add_path_received(user)
               4.6. add_path_received(user, parameters)
4ffba491
 
    List of Examples
d77df08a
 
45e50b14
    1.1. Add Supported header
    1.2. Set use_received parameter
7fc44593
    1.3. Set received_format parameter
981701d4
    1.4. Set received_name parameter
    1.5. Set enable_r2 parameter
    1.6. Set sockname_mode parameter
    1.7. add_path usage
    1.8. add_path(user) usage
    1.9. add_path(user, parameters) usage
    1.10. add_path_received() usage
    1.11. add_path_received(user) usage
    1.12. add_path_received(user, parameters) usage
4ffba491
 
9fc784c6
 Chapter 1. Admin Guide
4ffba491
 
d9bb387b
    Table of Contents
 
    1. Overview
 
45e50b14
         1.1. Path Insertion For Registrations
d9bb387b
         1.2. Outbound routing to NAT'ed UACs
 
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
d9bb387b
 
         3.1. use_received (int)
7fc44593
         3.2. received_format (int)
981701d4
         3.3. received_name (str)
         3.4. enable_r2 (int)
         3.5. sockname_mode (int)
d9bb387b
 
ba7961bb
    4. Functions
d9bb387b
 
         4.1. add_path()
         4.2. add_path(user)
99415516
         4.3. add_path(user, parameters)
         4.4. add_path_received()
         4.5. add_path_received(user)
         4.6. add_path_received(user, parameters)
d9bb387b
 
 1. Overview
 
45e50b14
    1.1. Path Insertion For Registrations
d9bb387b
    1.2. Outbound routing to NAT'ed UACs
 
    This module is designed to be used at intermediate sip proxies like
    loadbalancers in front of registrars and proxies. It provides functions
    for inserting a Path header including a parameter for passing forward
    the received-URI of a registration to the next hop. It also provides a
    mechanism for evaluating this parameter in subsequent requests and to
    set the destination URI according to it.
 
45e50b14
 1.1. Path Insertion For Registrations
d9bb387b
 
11b7630b
    For registrations in a scenario like “[UAC] -> [P1] -> [REG]”, the
d9bb387b
    "path" module can be used at the intermediate proxy P1 to insert a Path
    header into the message before forwarding it to the registrar REG. Two
    functions can be used to achieve this:
11b7630b
      * add_path(...) adds a Path header in the form of “Path:
        <sip:1.2.3.4;lr>” to the message using the address of the outgoing
d9bb387b
        interface. A port is only added if it's not the default port 5060.
        If a username is passed to the function, it is also included in the
11b7630b
        Path URI, like “Path: <sip:username@1.2.3.4;lr>”.
d9bb387b
      * add_path_received(...) also add a Path header in the same form as
        above, but also adds a parameter indicating the received-URI of the
11b7630b
        message, like “Path: <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”.
d9bb387b
        This is especially useful if the proxy does NAT detection and wants
989206bd
        to pass the NAT'ed address to the registrar.
d9bb387b
        If the function is called with a username, it's included in the
        Path URI too.
4ffba491
 
45e50b14
    Note that some SIP registrars may check if header Supported includes
    'path'. It can be added in Kamailio.cfg using append_hf() from textops
    module.
 
    Example 1.1. Add Supported header
 ...
 append_hf("Supported: path\r\n");
 ...
 
d9bb387b
 1.2. Outbound routing to NAT'ed UACs
4ffba491
 
989206bd
    If the NAT'ed address of an UAC is passed to the registrar, the
d9bb387b
    registrar routes back subsequent requests using the Path header of the
    registration as Route header of the current request. If the
11b7630b
    intermediate proxy had inserted a Path header including the “received”
d9bb387b
    parameter during the registration, this parameter will show up in the
    Route header of the new request as well, allowing the intermediate
    proxy to route to this address instead of the one propagated in the
    Route URI for tunneling through NAT. This behaviour can be activated by
11b7630b
    setting the module parameter “use_received”.
d9bb387b
 
 2. Dependencies
4ffba491
 
d9bb387b
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
4ffba491
 
d9bb387b
 2.1. Kamailio Modules
4ffba491
 
    The following modules must be loaded before this module:
d9bb387b
      * The "rr" module is needed for outbound routing according to the
11b7630b
        “received” parameter.
      * The "outbound" module is needed for outbound routing as per RFC
        5626.
4ffba491
 
d9bb387b
 2.2. External Libraries or Applications
4ffba491
 
d9bb387b
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
4ffba491
      * None.
 
ba7961bb
 3. Parameters
4ffba491
 
d9bb387b
    3.1. use_received (int)
7fc44593
    3.2. received_format (int)
981701d4
    3.3. received_name (str)
    3.4. enable_r2 (int)
    3.5. sockname_mode (int)
4ffba491
 
d9bb387b
 3.1. use_received (int)
 
11b7630b
    If set to 1, the “received” parameter of the first Route URI is
989206bd
    evaluated and used as destination-URI if present.
4ffba491
 
989206bd
    Default value is 0.
4ffba491
 
45e50b14
    Example 1.2. Set use_received parameter
4ffba491
 ...
 modparam("path", "use_received", 1)
 ...
 
7fc44593
 3.2. received_format (int)
 
    If set to 0, the “received” parameter value will be in the escaped SIP
    URI format.
 
    If set to 1, the “received” parameter value will be in the same format
    as the “alias” parameter added by set_contact_alias() from “nathelper”
    module (i.e., “ip~port~protid”). This is a solution with some SIP
    applications that incorrectly match the transport from received
    parameter instead of the one from the SIP URI.
 
    Default value is 0.
 
    Example 1.3. Set received_format parameter
 ...
 modparam("path", "received_format", 1)
 ...
 
981701d4
 3.3. received_name (str)
 
    Set the name of the header parameter to add the “received” value.
 
    Default value is "received".
 
    Example 1.4. Set received_name parameter
 ...
 modparam("path", "received_name", "rcv")
 ...
 
 3.4. enable_r2 (int)
7fc44593
 
    If set to 1, the module will add two Path headers, similar to the
    double Record-Route done by rr module. One Path headers corresponds to
    incoming network socket and the other to outgoing network socket. The
    URIs in the Path headers will have the 'r2=on' parameter as well.
 
    Note: if enabled, the module adds the two Path headers even when the
    incoming socket is the same as outgoing socket. Improvements to skip
    the second Path header in this case may be introduced in the future,
    meanwhile, if you need to enable this parameter but also deal with same
    socket routing, use 'insert_hf("Path: <$Ru>\r\n")'.
 
    Default value is 0.
 
981701d4
    Example 1.5. Set enable_r2 parameter
7fc44593
 ...
a1d64dea
 modparam("path", "enable_r2", 1)
7fc44593
 ...
 
981701d4
 3.5. sockname_mode (int)
bfe48633
 
    If set to 1, the Path URI is built to contain socket name in 'sn'
    parameter.
 
    Default value is 0.
 
981701d4
    Example 1.6. Set sockname_mode parameter
bfe48633
 ...
 modparam("path", "sockname_mode", 1)
 ...
 
ba7961bb
 4. Functions
d9bb387b
 
    4.1. add_path()
    4.2. add_path(user)
99415516
    4.3. add_path(user, parameters)
    4.4. add_path_received()
    4.5. add_path_received(user)
    4.6. add_path_received(user, parameters)
4ffba491
 
11b7630b
 4.1.  add_path()
4ffba491
 
11b7630b
    This function is used to insert a Path header in the form “Path:
    <sip:1.2.3.4;lr>”, where “1.2.3.4” is the address of the outgoing
d9bb387b
    interface.
4ffba491
 
11b7630b
    If the “outbound” module was loaded before this module, and outbound is
    required for this request, the header will be in the form “Path:
9cb2a163
    <sip:flowtoken@1.2.3.4;lr;ob>”, where “flowtoken” is the RFC 5626
11b7630b
    flow-token that can be used to identify the source and local address
    and transport the request was received on, and where “1.2.3.4” is the
    address of the outgoing interface.
 
4ffba491
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.7. add_path usage
4ffba491
 ...
 if (!add_path()) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...
 
11b7630b
 4.2.  add_path(user)
4ffba491
 
11b7630b
    This function adds a Path header in the form “Path:
    <sip:user@1.2.3.4;lr>”.
4ffba491
 
    Meaning of the parameters is as follows:
99415516
      * user - The username to be inserted as user part. SPVE is supported.
4ffba491
 
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.8. add_path(user) usage
4ffba491
 ...
 if (!add_path("loadbalancer")) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...
 
99415516
 4.3.  add_path(user, parameters)
4ffba491
 
11b7630b
    This function adds a Path header in the form “Path:
99415516
    <sip:user@1.2.3.4;lr>” and appends the given parameters as additional
    URI parameters.
 
    Meaning of the parameters is as follows:
      * user - The username to be inserted as user part. SPVE is supported.
      * parameters - Additional URI parameters to be appended to the URI.
        The semicolon separator is added automatically. The script writer
        is responsible for proper URI escaping. SPVE is supported.
 
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.9. add_path(user, parameters) usage
99415516
 ...
 if (!add_path("loadbalancer", "ob")) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...
 
 4.4.  add_path_received()
 
    This function adds a Path header in the form “Path:
    <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting its own outgoing
d9bb387b
    address as domain-part, and the address the request has been received
    from as received-parameter.
4ffba491
 
9c936647
    If the “outbound” module was loaded before this module, and outbound is
    required for this request, the header will be in the form “Path:
    <sip:flowtoken@1.2.3.4;lr;received=sip:2.3.4.5:1234;ob>”, where
    “flowtoken” is the RFC 5626 flow-token that can be used to identify the
    source and local address and transport the request was received on, and
    where “1.2.3.4” is the address of the outgoing interface.
 
4ffba491
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.10. add_path_received() usage
4ffba491
 ...
 if (!add_path_received()) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...
 
99415516
 4.5.  add_path_received(user)
1061d103
 
11b7630b
    This function adds a Path header in the form “Path:
    <sip:user@1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting 'user' as
99415516
    username part of address, its own outgoing address as domain-part, and
d9bb387b
    the address the request has been received from as received-parameter.
1061d103
 
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.11. add_path_received(user) usage
1061d103
 ...
 if (!add_path_received("inbound")) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...
99415516
 
 4.6.  add_path_received(user, parameters)
 
    This function adds a Path header in the form “Path:
    <sip:user@1.2.3.4;received=sip:2.3.4.5:1234;lr>”, setting 'user' as
    username part of address, its own outgoing address as domain-part, and
    the address the request has been received from as received-parameter.
 
    This function can be used from REQUEST_ROUTE.
 
981701d4
    Example 1.12. add_path_received(user, parameters) usage
99415516
 ...
 if (!add_path_received("inbound", "ob")) {
         sl_send_reply("503", "Internal Path Error");
         ...
 };
 ...