src/modules/topos/README
68717c2a
 TOPOS Module
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
9cb2a163
    Copyright © 2016 FhG FOKUS
68717c2a
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Parameters
 
95fd884f
               3.1. storage (str)
               3.2. db_url (str)
               3.3. mask_callid (int)
               3.4. sanity_checks (int)
               3.5. branch_expire (int)
               3.6. dialog_expire (int)
               3.7. clean_interval (int)
5f0792e7
               3.8. event_callback (str)
3c12f9da
               3.9. event_mode (int)
901d2c8c
               3.10. contact_host (str)
98a19666
               3.11. contact_mode (int)
               3.12. cparam_name (int)
               3.13. a_contact_avp (str)
               3.14. b_contact_avp (str)
5f0792e7
 
         4. Event Routes
 
               4.1. event_route[topos:msg-outgoing]
3c12f9da
               4.2. event_route[topos:msg-sending]
68717c2a
 
    List of Examples
 
95fd884f
    1.1. Set storage parameter
    1.2. Set db_url parameter
    1.3. Set mask_callid parameter
    1.4. Set sanity_checks parameter
    1.5. Set branch_expire parameter
    1.6. Set dialog_expire parameter
    1.7. Set clean_interval parameter
5f0792e7
    1.8. Set event_callback parameter
3c12f9da
    1.9. Set event_mode parameter
901d2c8c
    1.10. Set contact_host parameter
98a19666
    1.11. Set contact_mode parameter
    1.12. Set cparam_name parameter
    1.13. Set a_contact_avp parameter
    1.14. Set b_contact_avp parameter
    1.15. Usage of event_route[topos:msg-outgoing]
    1.16. Usage of event_route[topos:msg-sending]
68717c2a
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Parameters
 
95fd884f
         3.1. storage (str)
         3.2. db_url (str)
         3.3. mask_callid (int)
         3.4. sanity_checks (int)
         3.5. branch_expire (int)
         3.6. dialog_expire (int)
         3.7. clean_interval (int)
5f0792e7
         3.8. event_callback (str)
3c12f9da
         3.9. event_mode (int)
901d2c8c
         3.10. contact_host (str)
98a19666
         3.11. contact_mode (int)
         3.12. cparam_name (int)
         3.13. a_contact_avp (str)
         3.14. b_contact_avp (str)
5f0792e7
 
    4. Event Routes
 
         4.1. event_route[topos:msg-outgoing]
3c12f9da
         4.2. event_route[topos:msg-sending]
68717c2a
 
 1. Overview
 
628d2d3f
    This module offers topology hiding for INVITE-based dialogs, by
    stripping the SIP routing headers that show topology details . The
    script interpreter gets the SIP messages with full content, so all
    existing functionality is preserved.
68717c2a
 
    The module is transparent for the configuration writer. It only needs
628d2d3f
    to be loaded (tune the module parameters if needed).
68717c2a
 
d1f1b08e
    It also works for SIP MESSAGE or other requests that do not create a
628d2d3f
    dialog -- record_route() must be used for them as well, the headers are
    not going to be in the messages sent to the network, they are needed to
    know local addresses used to communicate with each side. At this moment
    it is not designed to work for presence (SUBSCRIBE-based) dialogs. The
    REGISTER and PUBLISH requests are skipped from processing by this
    module, expected to be terminated on a local SIP server.
956b5ae8
 
68717c2a
 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
d1f1b08e
        requests are encoded/decoded (it must be done for all initial
        requests).
68717c2a
      * database module - to store the data for topology stripping and
        restoring.
 
 2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * none.
 
 3. Parameters
 
95fd884f
    3.1. storage (str)
    3.2. db_url (str)
    3.3. mask_callid (int)
    3.4. sanity_checks (int)
    3.5. branch_expire (int)
    3.6. dialog_expire (int)
    3.7. clean_interval (int)
5f0792e7
    3.8. event_callback (str)
3c12f9da
    3.9. event_mode (int)
901d2c8c
    3.10. contact_host (str)
98a19666
    3.11. contact_mode (int)
    3.12. cparam_name (int)
    3.13. a_contact_avp (str)
    3.14. b_contact_avp (str)
68717c2a
 
95fd884f
 3.1. storage (str)
 
    Type of storage, valid types are:
      * db - Database Backend
      * redis - Redis Backend
 
    Default value is “db”.
 
    Example 1.1. Set storage parameter
 ...
 modparam("topos", "storage", "redis")
 ...
 
 3.2. db_url (str)
68717c2a
 
    Database URL.
 
9cb2a163
    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
68717c2a
 
95fd884f
    Example 1.2. Set db_url parameter
68717c2a
 ...
 modparam("topos", "db_url", "dbdriver://username:password@dbhost/dbname")
 ...
 
95fd884f
 3.3. mask_callid (int)
68717c2a
 
750f983a
    Note: this functionality is not implemented yet - the parameter is
    present in order to be in pair with topoh module.
 
68717c2a
    Whether to replace or not the Call-ID with another unique id generated
    by Kamailio.
 
    Default value is 0 (do not mask).
 
95fd884f
    Example 1.3. Set mask_callid parameter
68717c2a
 ...
 modparam("topos", "mask_callid", 1)
 ...
 
95fd884f
 3.4. sanity_checks (int)
68717c2a
 
e87feb9f
    If set to 1, topos module will bind to sanity module in order to
68717c2a
    perform sanity checks over received SIP request. Default sanity checks
8868e624
    are done. It is useful to check if received request is well formatted
68717c2a
    before proceeding to encoding/decoding.
 
    Default value is 0 (do not bind to sanity module).
 
95fd884f
    Example 1.4. Set sanity_checks parameter
68717c2a
 ...
e87feb9f
 modparam("topos", "sanity_checks", 1)
68717c2a
 ...
956b5ae8
 
95fd884f
 3.5. branch_expire (int)
956b5ae8
 
    Interval in seconds after which the branch records are deleted.
 
    Default value is 180 (3 min).
 
95fd884f
    Example 1.5. Set branch_expire parameter
956b5ae8
 ...
815b235f
 modparam("topos", "branch_expire", 300)
956b5ae8
 ...
 
95fd884f
 3.6. dialog_expire (int)
956b5ae8
 
b3d9da5c
    Interval in seconds after which the dialog records are deleted. Keep in
    mind that the module does not update the dialog timestamp after the
    initial call setup on re-INVITEs or other in-dialog messages. So set a
    large enough value (according your longest call duration) to prevent
    problems in re-writing messages.
956b5ae8
 
    Default value is 10800 (3 hours).
 
95fd884f
    Example 1.6. Set dialog_expire parameter
956b5ae8
 ...
815b235f
 modparam("topos", "dialog_expire", 3600)
956b5ae8
 ...
 
95fd884f
 3.7. clean_interval (int)
956b5ae8
 
    Interval in seconds to run the clean up of stored records.
 
    Default value is 60 (1 min).
 
95fd884f
    Example 1.7. Set clean_interval parameter
956b5ae8
 ...
 modparam("topos", "clean_interval", 30)
 ...
5f0792e7
 
 3.8. 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.8. Set event_callback parameter
 ...
 modparam("topos", "event_callback", "ksr_topos_event")
 ...
 -- event callback function implemented in Lua
 function ksr_topos_event(evname)
         KSR.info("===== topos module triggered event: " .. evname .. "\n");
         return 1;
 end
 ...
 
3c12f9da
 3.9. event_mode (int)
 
    Control what event_route blocks to be executed. It is a bitmask of: 1 -
a4cc0be0
    execute event_route[topos:msg-outgoing]; 2 - execute
    event_route[topos:msg-sending].
3c12f9da
 
    Default value is 3 (execute both event_route blocks).
 
    Example 1.9. Set event_mode parameter
 ...
 modparam("topos", "event_mode", 2)
 ...
 
901d2c8c
 3.10. contact_host (str)
 
    You may need to control the host part of the Contact header added by
    topos. For example when using TLS with TOPOS the remote UAS must be
    able to open a new TLS socket to the contact header. In this case, the
    contact header must contain a domain name with a trusted CA signed
    certitificate.
 
    Default value is taken from the Record-Route URI.
 
    Example 1.10. Set contact_host parameter
 ...
 modparam("topos", "contact_host", "proxy.domain.com")
 ...
 
98a19666
 3.11. contact_mode (int)
 
    Control the mode where the key to lookup the message data from the
    database or redis server is stored. The default is to use the Contact
    user (0), alternatively a Contact URI parameter can be used (1) with
    values from the SIP message, or from AVP variables (2). This can be
    useful for interoperating which gateways that need a certain user part
    in the Contact URI.
 
    In mode (1) the a-side contact user is taken from the request URI and
    the b-side contact user from the Contact header of the processed
    initial SIP request.
 
    If you use the mode (2), you need to configure the a_contact_avp and
    b_contact_avp parameter. Furthermore you need to assign values to them
    during the processing of the initial SIP request.
 
    The name of the Contact URI parameter can be customized with the
    cparam_name parameter.
 
    Default value is 0 - use the Contact user
 
    Example 1.11. Set contact_mode parameter
 ...
 modparam("topos", "contact_mode", 1)
 ...
 
 3.12. cparam_name (int)
 
    Name of the Contact URI parameter to store the database or redis server
    key for message lookup.
 
    This parameter is only used when the contact_mode parameter is set to 1
    or 2.
 
    Default value is “tps”.
 
    Example 1.12. Set cparam_name parameter
 ...
 modparam("topos", "cparam_name", "xyz")
 ...
 
 3.13. a_contact_avp (str)
 
    Name of the AVP parameter to evaluate for the A-side Contact Header
    user part. This parameter is only necessary in contact_mode (2).
 
    Default value is “NULL” (disabled).
 
    Example 1.13. Set a_contact_avp parameter
 ...
 modparam("topos", "a_contact_avp", "$avp(tps-act)")
 ...
 
 3.14. b_contact_avp (str)
 
    Name of the AVP parameter to evaluate for the B-side Contact Header
    user part. This parameter is only necessary in contact_mode (2).
 
    Default value is “NULL” (disabled).
 
    Example 1.14. Set b_contact_avp parameter
 ...
 modparam("topos", "b_contact_avp", "$avp(tps-bct)")
 ...
 
5f0792e7
 4. Event Routes
 
    4.1. event_route[topos:msg-outgoing]
3c12f9da
    4.2. event_route[topos:msg-sending]
5f0792e7
 
 4.1. event_route[topos:msg-outgoing]
 
    It is executed before doing topology stripping 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.
 
98a19666
    Example 1.15. Usage of event_route[topos:msg-outgoing]
5f0792e7
 ...
 event_route[topos:msg-outgoing] {
   if($sndto(ip)=="10.1.1.10") {
     drop;
   }
 }
 ...
3c12f9da
 
 4.2. event_route[topos:msg-sending]
 
    It is executed before doing topology stripping processing for a SIP
    message to be sent out, being executed after
2052115f
    event_route[topos:msg-outgoing].
3c12f9da
 
    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.
 
98a19666
    Example 1.16. Usage of event_route[topos:msg-sending]
3c12f9da
 ...
 event_route[topos:msg-sending] {
   if(is_request() and $fU=="alice") {
     drop;
   }
 }
 ...