Nethvoice: Vianova trunk

[Amygos]

Proposed Feature
Support for Multiple Vianova Trunks on a Single Proxy Using Dynamic Port
Bindings

Purpose and Motivation
Currently, when configuring multiple Vianova trunks (each with its own number
and user extension) on separate instances behind the same proxy, outbound calls
only work from the instance that first registers with the provider.
The provider (Vianova) restricts registration such that only the first client
using a given IP:port pairing succeeds; subsequent attempts from the same IP
and port for different clients are rejected with 403 forbidden.
This limitation arises because Vianova identifies trunks by their unique IP and
source port combinations. As a result, it is currently not possible to operate
more than one Vianova trunk per external IP address, limiting the ability to
serve multiple tenants from the same server/infrastructure.

NAT Handling and Vianova Behavior
Vianova’s SBC (Session Border Controller) handles NAT scenarios as follows:

• If the source IP and the Contact IP in the REGISTER are the same, Vianova’s
  SBC will rely on the Contact header for routing.
• If NAT is detected (Contact IP ≠ source IP), Vianova will cache the (IP:Port)
  tuple observed for the REGISTER and always use that for signaling traffic
  to the trunk.

Proposed Solution

• Maintain a configurable list of SIP domains that require special port
  assignment logic (e.g., Vianova).
• When Kamailio processes a REGISTER request to any listed domain, it
  dynamically assigns an available slot (port) that is unique for each (user, domain) tuple. No two users on the same domain may share a slot.
• The Contact header in the REGISTER is rewritten by Kamailio to reflect the
  assigned slot/port, so that the provider can implicitly identify the trunk
  from it.
• After assignment, all SIP communications in that session (INVITE, BYE,
  etc.) are routed through the selected slot, guaranteeing session consistency
  and compatibility with the provider.
• Establish a slot lifecycle managed by a TTL mechanism: unused slots are
  reclaimed automatically, optimizing resource usage.

Implementation References in nethesis/ns8-nethvoice-proxy

• Kamailio listen bindings and startup — slots must be statically declared
  as named listen directives at startup; the bootstrap script is the entry
  point for this:

  • modules/kamailio/bootstrap.sh
  • modules/kamailio/config/template.kamailio-local.cfg

• REGISTER handling and Contact rewriting

  • modules/kamailio/config/kamailio.cfg — route[REWRITE_CONTACT]
  • modules/kamailio/config/kamailio.cfg — route[SET_SOCKET]
  • modules/kamailio/config/kamailio.cfg — route[NATDETECT]

• In-memory slot state

  • modules/kamailio/config/kamailio.cfg — modparam("htable", ...)
  • ndb_redis module can be considered for persistent assignment.

• Trunk provisioning actions

  • A new actions for trunk provisioning that includes slot assignment logic
    must be added:
    • Add a new destination domain
    • List the domains that require slot-based port assignment and their
      assigned ports and ttl
    • Remove a destination domain and free its assigned slot
    • List allocated ports range

• Firewall / port exposure

  • imageroot/actions/create-module/20firewall

• Trunk restore and reload safety

  • imageroot/actions/restore-module/71restore_trunks

Implementation Considerations

• The list of special domains requiring slot-based port assignment must be easy
  to configure and reload without a Kamailio restart (e.g., stored in an htable
  or Redis, reloadable via kamcmd).
• Slot pool exhaustion must be handled gracefully (log + fallback to default
  behavior or error to caller).
• Slot TTL should align with the SIP REGISTER expiry to avoid premature
  reclamation of active registrations.
• All new slot listen ports must be opened in the firewall
  (imageroot/actions/create-module/20firewall).
• Legacy behavior (no slot assignment) must be preserved for domains not in the
  special list.
• The slot port range and total number of slots are fixed at startup; adding
  more slots requires a Kamailio container restart.

Alternative solutions

• Using multiple IPs was ruled out, as most environments have access to only
  one external IP.

Additional Context

• Reference: Kamailio Core Cookbook
• The solution must pre-allocate a sufficient number of ports (e.g., 10) for
  expected tenants; exceeding this would require a proxy restart to allocate
  more.
• All Kamailio bindings must be created for each protocol (UDP, TCP, TLS),
  multiplying process counts.

See Also

• Private Mattermost chat: https://mattermost.nethesis.it/nethesis/pl/d1r9ag5od7doz8wyqeys1pzaka
• Evoseed ticket: https://nethesis.evoseed.it/helpdesk/ticket/144