README

TOPOS Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Frederic Gaisnon

   <frederic.gaisnon@gmail.com>

   Copyright © 2016 FhG FOKUS

   Copyright © 2021 MomentTech
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              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)
              3.8. event_callback (str)
              3.9. event_mode (int)
              3.10. contact_host (str)
              3.11. contact_mode (int)
              3.12. cparam_name (int)
              3.13. xavu_cfg (str)
              3.14. xavu_field_a_contact (str)
              3.15. xavu_field_b_contact (str)
              3.16. xavu_field_contact_host (str)
              3.17. rr_update (int)
              3.18. context (str)
              3.19. methods_nocontact (str)
              3.20. header_mode (int)
              3.21. methods_noinitial (str)

        4. Functions

              4.1. tps_set_context(ctx)

        5. Event Routes

              5.1. event_route[topos:msg-outgoing]
              5.2. event_route[topos:msg-sending]
              5.3. event_route[topos:msg-incoming]
              5.4. event_route[topos:msg-receiving]

   List of Examples

   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
   1.8. Set event_callback parameter
   1.9. Set event_mode parameter
   1.10. Set contact_host parameter
   1.11. Set contact_mode parameter
   1.12. Set cparam_name parameter
   1.13. Set xavu_cfg parameter
   1.14. Set xavu_field_a_contact parameter
   1.15. Set xavu_field_b_contact parameter
   1.16. Set xavu_field_contact_host parameter
   1.17. Set rr_update parameter
   1.18. Set context parameter
   1.19. Set methods_nocontact parameter
   1.20. Set header_mode parameter
   1.21. Set methods_noinitial parameter
   1.22. tps_set_context usage
   1.23. Usage of event_route[topos:msg-outgoing]
   1.24. Usage of event_route[topos:msg-sending]
   1.25. Usage of event_route[topos:msg-incoming]
   1.26. Usage of event_route[topos:msg-receoving]

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        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)
        3.8. event_callback (str)
        3.9. event_mode (int)
        3.10. contact_host (str)
        3.11. contact_mode (int)
        3.12. cparam_name (int)
        3.13. xavu_cfg (str)
        3.14. xavu_field_a_contact (str)
        3.15. xavu_field_b_contact (str)
        3.16. xavu_field_contact_host (str)
        3.17. rr_update (int)
        3.18. context (str)
        3.19. methods_nocontact (str)
        3.20. header_mode (int)
        3.21. methods_noinitial (str)

   4. Functions

        4.1. tps_set_context(ctx)

   5. Event Routes

        5.1. event_route[topos:msg-outgoing]
        5.2. event_route[topos:msg-sending]
        5.3. event_route[topos:msg-incoming]
        5.4. event_route[topos:msg-receiving]

1. Overview

   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.

   The module is transparent for the configuration writer. It only needs
   to be loaded (tune the module parameters if needed).

   It also works for SIP MESSAGE or other requests that do not create a
   dialog (e.g., OPTIONS) -- 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. This module is designed to work for presence (SUBSCRIBE-based)
   dialogs too.

   The REGISTER and PUBLISH requests are skipped from processing by this
   module, expected to be terminated on a local SIP server.

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 (it must be done for all initial
       requests).
     * 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

   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)
   3.8. event_callback (str)
   3.9. event_mode (int)
   3.10. contact_host (str)
   3.11. contact_mode (int)
   3.12. cparam_name (int)
   3.13. xavu_cfg (str)
   3.14. xavu_field_a_contact (str)
   3.15. xavu_field_b_contact (str)
   3.16. xavu_field_contact_host (str)
   3.17. rr_update (int)
   3.18. context (str)
   3.19. methods_nocontact (str)
   3.20. header_mode (int)
   3.21. methods_noinitial (str)

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)

   Database URL.

   Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.

   Example 1.2. Set db_url parameter
...
modparam("topos", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.3. mask_callid (int)

   Note: this functionality is not implemented yet - the parameter is
   present in order to be in pair with topoh module.

   Whether to replace or not the Call-ID with another unique id generated
   by Kamailio.

   Default value is 0 (do not mask).

   Example 1.3. Set mask_callid parameter
...
modparam("topos", "mask_callid", 1)
...

3.4. sanity_checks (int)

   If set to 1, topos module will bind to sanity module in order to
   perform sanity checks over received SIP request. Default sanity checks
   are done. It is useful to check if received request is well formatted
   before proceeding to encoding/decoding.

   Default value is 0 (do not bind to sanity module).

   Example 1.4. Set sanity_checks parameter
...
modparam("topos", "sanity_checks", 1)
...

3.5. branch_expire (int)

   Interval in seconds after which the branch records are deleted.

   Default value is 180 (3 min).

   Example 1.5. Set branch_expire parameter
...
modparam("topos", "branch_expire", 300)
...

3.6. dialog_expire (int)

   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. This key is only relevant for INVITE
   dialog. SUBSCRIBE dialog records lifetime are based on value set in
   expires header. Moreover each re-SUBSCRIBEs update the dialog
   timestamp.

   Default value is 10800 (3 hours).

   Example 1.6. Set dialog_expire parameter
...
modparam("topos", "dialog_expire", 3600)
...

3.7. clean_interval (int)

   Interval in seconds to run the clean up of stored records.

   Default value is 60 (1 min).

   Example 1.7. Set clean_interval parameter
...
modparam("topos", "clean_interval", 30)
...

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
...

3.9. event_mode (int)

   Control what event_route blocks to be executed. It is a bitmask of: 1 -
   execute event_route[topos:msg-outgoing]; 2 - execute
   event_route[topos:msg-sending]; 4 execute
   event_route[topos:msg-incoming]; 8 execute
   event_route[topos:msg-receiving];.

   Default value is 3 (execute both event_route blocks).

   Example 1.9. Set event_mode parameter
...
modparam("topos", "event_mode", 2)
...

3.10. contact_host (str)

   You may need to control the host part of the Contact header added by
   topos. If the xavu_field_contact_host parameter is set, this value is
   ignored. 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")
...

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 xavu_field_a_contact
   and xavu_field_b_contact 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. xavu_cfg (str)

   Name of root XAVU to hold config-specific values to be used by module
   at runtime.

   Note: this parameter must be set if any other parameter prefixed with
   `xavu_field_` is used.

   Default value is “NULL” (disabled).

   Example 1.13. Set xavu_cfg parameter
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_a_contact", "a_contact")
...
    $xavu(_tps_=>a_contact) = "...";
...

3.14. xavu_field_a_contact (str)

   Name of the field inside root XAVU specifed by `xavu_cfg` 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.14. Set xavu_field_a_contact parameter
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_a_contact", "a_contact")
...
    $xavu(_tps_=>a_contact) = "...";
...

3.15. xavu_field_b_contact (str)

   Name of the field inside root XAVU specifed by `xavu_cfg` 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.15. Set xavu_field_b_contact parameter
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_b_contact", "b_contact")
...
    $xavu(_tps_=>b_contact) = "...";

...

3.16. xavu_field_contact_host (str)

   Control from where to take the host part of the Contact header added by
   topos. This parameter allows to take the value from an XAVU during
   run-time, it specifies the field inside XAVU "xavu_cfg". If this
   parameter is set, the contact_host parameter is ignored. 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 empty, not set.

   Example 1.16. Set xavu_field_contact_host parameter
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_contact_host", "contact_host")
...
    $xavu(_tps_=>contact_host) = "kamailio.org";
...

3.17. rr_update (int)

   If set to 1, topos module will track and update record route changes on
   re-invite.

   Default value is 0 (do not update record route changes within dialog).

   Example 1.17. Set rr_update parameter
...
modparam("topos", "rr_update", 1)
...

3.18. context (str)

   Set the global context for topos instance.

   The value has to be maximum 12 characters.

   Default value is “NULL” (disabled).

   Example 1.18. Set context parameter
...
modparam("topos", "context", "srvone")
...

3.19. methods_nocontact (str)

   List of SIP methods to skip adding Contact header for.

   Default value is “BYE,CANCEL,PRACK”.

   Example 1.19. Set methods_nocontact parameter
...
modparam("topos", "methods_nocontact", "CANCEL,PRACK")
...

3.20. header_mode (int)

   List of headers to disable multiple comma separated values inserted in
   compact form. Altough compact form is RFC compliant this paramter gives
   possibilty to disable compact form header values for UA that don't
   support or can't handle it. The following options are available: (1) -
   disable multiple comma separated values for Via header (2) - disable
   multiple comma separated values for Record-Route header (4) - disable
   multiple comma separated values for Route header

   Default value is “0”.

   Example 1.20. Set header_mode parameter
...
modparam("topos", "header_mode", 1)
...

3.21. methods_noinitial (str)

   List of SIP methods to skip doing topos if it is an intial request (no
   To-tag).

   Default value is “” (no method).

   Example 1.21. Set methods_noinitial parameter
...
modparam("topos", "methods_noinitial", "OPTIONS,NOTIFY")
...

4. Functions

   4.1. tps_set_context(ctx)

4.1.  tps_set_context(ctx)

   Update the context at runtime. If the value is emtpy string, then the
   runtime context is reset.

   This function can be used from ANY_ROUTE.

   Example 1.22. tps_set_context usage
...
request_route {
    ...
    tps_set_context("srvone");
    ...
}
...

5. Event Routes

   5.1. event_route[topos:msg-outgoing]
   5.2. event_route[topos:msg-sending]
   5.3. event_route[topos:msg-incoming]
   5.4. event_route[topos:msg-receiving]

5.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.

   Example 1.23. Usage of event_route[topos:msg-outgoing]
...
event_route[topos:msg-outgoing] {
  if($sndto(ip)=="10.1.1.10") {
    drop;
  }
}
...

5.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
   event_route[topos: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.24. Usage of event_route[topos:msg-sending]
...
event_route[topos:msg-sending] {
  if(is_request() and $fU=="alice") {
    drop;
  }
}
...

5.3. event_route[topos:msg-incoming]

   It is executed before doing topology stripping processing for an
   incoming SIP message. If 'drop' is executed inside the event route,
   then the module skips doing the topology hiding.

   Inside the event route the variables $si, $sp and $proto point to the
   source address. 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.

   Example 1.25. Usage of event_route[topos:msg-incoming]
...
event_route[topos:msg-incoming] {
  if($si=="10.1.1.10") {
    drop;
  }
}
...

5.4. event_route[topos:msg-receiving]

   It is executed before doing topology stripping processing for a SIP
   message that was received, being executed after
   event_route[topos:msg-incoing].

   Inside the event route the variables $si, $sp and $proto point to the
   source address. The SIP message is the one to be sent out.

   Example 1.26. Usage of event_route[topos:msg-receoving]
...
event_route[topos:msg-receiving] {
  if(is_request() and $fU=="alice") {
    drop;
  }
}
...