src/modules/topoh/README
b16b1294
 topoh Module
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
9cb2a163
    Copyright © 2009 FhG FOKUS
b16b1294
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
ba7961bb
         3. Parameters
b16b1294
 
               3.1. mask_key (str)
8f212d9b
               3.2. mask_ip (str)
               3.3. mask_callid (integer)
               3.4. uparam_name (str)
               3.5. uparam_prefix (str)
               3.6. vparam_name (str)
               3.7. vparam_prefix (str)
               3.8. callid_prefix (str)
6d8a7267
               3.9. sanity_checks (integer)
3188da9a
               3.10. uri_prefix_checks (integer)
               3.11. event_callback (str)
a4cc0be0
               3.12. event_mode (int)
b16b1294
 
cde68845
         4. Event Routes
 
               4.1. event_route[topoh:msg-outgoing]
a4cc0be0
               4.2. event_route[topoh:msg-sending]
cde68845
 
b16b1294
    List of Examples
 
    1.1. Set mask_key parameter
8f212d9b
    1.2. Set mask_ip parameter
    1.3. Set mask_callid parameter
    1.4. Set uparam_name parameter
    1.5. Set uparam_prefix parameter
    1.6. Set vparam_name parameter
    1.7. Set vparam_prefix parameter
    1.8. Set callid_prefix parameter
6d8a7267
    1.9. Set sanity_checks parameter
3188da9a
    1.10. Set uri_prefix_checks parameter
    1.11. Set event_callback parameter
a4cc0be0
    1.12. Set event_mode parameter
    1.13. Usage of event_route[topoh:msg-outgoing]
    1.14. Usage of event_route[topoh:msg-sending]
b16b1294
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
b16b1294
 
         3.1. mask_key (str)
8f212d9b
         3.2. mask_ip (str)
         3.3. mask_callid (integer)
         3.4. uparam_name (str)
         3.5. uparam_prefix (str)
         3.6. vparam_name (str)
         3.7. vparam_prefix (str)
         3.8. callid_prefix (str)
6d8a7267
         3.9. sanity_checks (integer)
3188da9a
         3.10. uri_prefix_checks (integer)
         3.11. event_callback (str)
a4cc0be0
         3.12. event_mode (int)
b16b1294
 
cde68845
    4. Event Routes
 
         4.1. event_route[topoh:msg-outgoing]
a4cc0be0
         4.2. event_route[topoh:msg-sending]
cde68845
 
b16b1294
 1. Overview
 
2d473a9d
    This module hides the SIP routing headers that show topology details.
a91b2b68
    It is not affected by the server being transaction stateless or
2d473a9d
    stateful. The script interpreter gets the SIP messages decoded, so all
    existing functionality is preserved.
b16b1294
 
7eb41a8e
    The module is transparent for the configuration writer. It only needs
    to be loaded (tune the parameters if needed). The SIP server can be
8868e624
    restarted without affecting ongoing calls - once it is up, can
7eb41a8e
    encode/decode topology details, thus no call will be lost.
b16b1294
 
    By using same mask_key, many SIP servers can decode the message, for
7eb41a8e
    example, applicable for servers behind load balancers.
b16b1294
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * rr module - server must perform record routing to ensure in-dialog
        requests are encoded/decoded.
 
 2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
2d473a9d
      * None. In the future the module can be enhanced to use a stronger
b16b1294
        encryption algorithm.
 
ba7961bb
 3. Parameters
b16b1294
 
    3.1. mask_key (str)
8f212d9b
    3.2. mask_ip (str)
    3.3. mask_callid (integer)
    3.4. uparam_name (str)
    3.5. uparam_prefix (str)
    3.6. vparam_name (str)
    3.7. vparam_prefix (str)
    3.8. callid_prefix (str)
6d8a7267
    3.9. sanity_checks (integer)
3188da9a
    3.10. uri_prefix_checks (integer)
    3.11. event_callback (str)
a4cc0be0
    3.12. event_mode (int)
b16b1294
 
 3.1. mask_key (str)
 
    Keyword to mask the headers.
 
    Default value is "_static_value_".
 
    Example 1.1. Set mask_key parameter
 ...
 modparam("topoh", "mask_key", "some secret here")
 ...
 
8f212d9b
 3.2. mask_ip (str)
 
    IP address to be used in masked headers to build valid SIP URIs. Can be
a35f99d0
    any IP address, even a private-space or non-existing IP address (e.g.,
    192.168.1.1, 127.0.0.2), including the SIP server address, but must not
    be an address potentially used by clients. It is not used at all for
    SIP routing.
8f212d9b
 
a35f99d0
    Default value is "127.0.0.8".
8f212d9b
 
    Example 1.2. Set mask_ip parameter
 ...
 modparam("topoh", "mask_ip", "192.168.0.1")
 ...
 
 3.3. mask_callid (integer)
b16b1294
 
7eb41a8e
    Whether to encode the Call-id: header. Some SIP extensions include the
    Call-id in the SIP message payload or header, so it is safe to not
    encode Call-id in such cases. Well-known extensions such as call
    transfer or conference join will be added to work with encoded Call-id.
b16b1294
 
78324dcc
    NOTE: if you are using dialog module to terminate calls and this
    parameter is enabled, you must set the dialog module parameter
    'lreq_callee_headers' to include the header: 'TH: dlh\r\n'.
 
b16b1294
    Default value is 0 (do not mask).
 
8f212d9b
    Example 1.3. Set mask_callid parameter
b16b1294
 ...
 modparam("topoh", "mask_callid", 1)
 ...
 
8f212d9b
 3.4. uparam_name (str)
b16b1294
 
2d473a9d
    Name of URI parameter where to store encoded value.
b16b1294
 
    Default value is "line".
 
8f212d9b
    Example 1.4. Set uparam_name parameter
b16b1294
 ...
 modparam("topoh", "uparam_name", "myparam")
 ...
 
8f212d9b
 3.5. uparam_prefix (str)
b16b1294
 
2d473a9d
    Prefix to be added in encoded URI parameters.
b16b1294
 
    Default value is "sr-".
 
8f212d9b
    Example 1.5. Set uparam_prefix parameter
b16b1294
 ...
 modparam("topoh", "uparam_prefix", "xyz")
 ...
 
8f212d9b
 3.6. vparam_name (str)
b16b1294
 
2d473a9d
    Name of Via: parameter used to store encoded value.
b16b1294
 
    Default value is "branch".
 
8f212d9b
    Example 1.6. Set vparam_name parameter
b16b1294
 ...
 modparam("topoh", "vparam_name", "myv")
 ...
 
8f212d9b
 3.7. vparam_prefix (str)
b16b1294
 
7eb41a8e
    Prefix to be added in encoded Via: parameters.
b16b1294
 
    Default value is "z9hG4bKsr-".
 
8f212d9b
    Example 1.7. Set vparam_prefix parameter
b16b1294
 ...
 modparam("topoh", "vparam_prefix", "xyz")
 ...
 
8f212d9b
 3.8. callid_prefix (str)
63664db5
 
    Prefix to be added in encoded Call-ID: headers.
 
    Default value is "!!:".
 
8f212d9b
    Example 1.8. Set callid_prefix parameter
63664db5
 ...
 modparam("topoh", "callid_prefix", "***")
 ...
 
6d8a7267
 3.9. sanity_checks (integer)
 
    If set to 1, topoh module will bind to sanity module in order to
    perform sanity checks over received SIP request. Default sanity checks
8868e624
    are done. It is useful to check if received request is well formatted
6d8a7267
    before proceeding to encoding/decoding.
 
    Default value is 0 (do not bind to sanity module).
 
    Example 1.9. Set sanity_checks parameter
 ...
 modparam("topoh", "sanity_checks", 1)
 ...
cde68845
 
3188da9a
 3.10. uri_prefix_checks (integer)
 
    If set to 1, topoh module will check if URIs to be decoded match the
    expected prefix composed from mask IP and parameter name prefix. It can
    make the topoh processing safer by avoiding to try decoding URIs which
    were not encoded previously by topoh.
 
    Note: do not enable this option if you have SIP devices that can alter
    the URI values it takes from Contact or Record-Route headers (like
8868e624
    adding port 5060 when no port is in received URIs, or that introduces
    new parameters at an unknown position).
3188da9a
 
    Default value is 0.
 
    Example 1.10. Set uri_prefix_checks parameter
 ...
 modparam("topoh", "uri_prefix_checks", 1)
 ...
 
 3.11. event_callback (str)
 
    The name of the function in the KEMI configuration file (embedded
    scripting language such as Lua, Python, ...) to be executed instead of
    event_route[...] blocks.
 
    The function receives a string parameter with the name of the event.
 
    Default value is 'empty' (no function is executed for events).
 
    Example 1.11. Set event_callback parameter
 ...
 modparam("topoh", "event_callback", "ksr_topoh_event")
 ...
 -- event callback function implemented in Lua
 function ksr_topoh_event(evname)
         KSR.info("===== topoh module triggered event: " .. evname .. "\n");
         return 1;
 end
 ...
 
a4cc0be0
 3.12. event_mode (int)
 
    Control what event_route blocks to be executed. It is a bitmask of: 1 -
    execute event_route[topoh:msg-outgoing]; 2 - execute
    event_route[topoh:msg-sending].
 
    Default value is 3 (execute both event_route blocks).
 
    Example 1.12. Set event_mode parameter
 ...
 modparam("topoh", "event_mode", 2)
 ...
 
cde68845
 4. Event Routes
 
    4.1. event_route[topoh:msg-outgoing]
a4cc0be0
    4.2. event_route[topoh:msg-sending]
cde68845
 
 4.1. event_route[topoh:msg-outgoing]
 
    It is executed before doing topology hiding processing for an outgoing
    SIP message. If 'drop' is executed inside the event route, then the
    module skips doing the topology hiding.
 
    Inside the event route the variables $sndto(ip), $sndto(port) and
    $sndto(proto) point to the destination. The SIP message is not the one
    to be sent out, but an internally generated one at startup, to avoid
    reparsing the outgoing SIP message for the cases when topology hiding
    is not wanted.
 
a4cc0be0
    Example 1.13. Usage of event_route[topoh:msg-outgoing]
cde68845
 ...
 event_route[topoh:msg-outgoing] {
   if($sndto(ip)=="10.1.1.10") {
     drop;
   }
 }
 ...
a4cc0be0
 
 4.2. event_route[topoh:msg-sending]
 
    It is executed before doing topology hiding processing for a SIP
    message to be sent out, being executed after
    event_route[topoh:msg-outgoing].
 
    Inside the event route the variables $sndto(ip), $sndto(port) and
    $sndto(proto) point to the destination. The SIP message is the one to
    be sent out.
 
    Example 1.14. Usage of event_route[topoh:msg-sending]
 ...
 event_route[topoh:msg-sending] {
   if(is_request() and $fU=="alice") {
     drop;
   }
 }
 ...