ns8-nethvoice-proxy

NS8 NethVoice proxy module, a SIP and RTP proxy allows multiple instances of NethVoice to be hosted on the same Node. The proxy uses Kamailio and rtpengine as core components.

This module is developed by evoseed and maintained by Nethesis. Most of the development is tracked privately inside evoseed portal.

Module overview

flowchart LR
subgraph Host Network
    subgraph Proxy[NethVoice Proxy Module]
        Kamailio
        RTPengine
    end
    subgraph NethVoice1[NethVoice Module 1]
        Kamailio -- Custom sip ports --> Asterisk1[Asterisk]
        RTPengine -- Custom port range --> Asterisk1[Asterisk]
    end
    subgraph NethVoiceN[NethVoice Module N]
        Kamailio -- Custom sip ports --> AsteriskN[Asterisk]
        RTPengine -- Custom port range --> AsteriskN[Asterisk]
    end
    NethVoice1 -.-> NethVoiceN
end
sip>SIP Connections]-- Standard SIP ports --> Kamailio
rtp>RTP Flows]-- 10000-20000 --> RTPengine

Loading

Install

Instantiate the module with:

add-module ghcr.io/nethesis/nethvoice-proxy:latest 1

The output of the command will return the instance name. Output example:

{"module_id": "nethvoice-proxy1", "image_name": "nethvoice-proxy", "image_url": "ghcr.io/nethesis/nethvoice-proxy:latest"}

Configure

Let's assume that the nethvoice-proxy instance is named nethvoice-proxy1.

Launch configure-module, by setting the following parameters:

• fqdn: name of Let's Encrypt certificate to use for Secure SIP connections, the phones must be configured to use this domain name as server SIP.
• addresses: configure the IP where the proxy will receive SIP and RTP connections/streams.
  • address: IPv4 address that is expected to receive VoIP traffic, mandatory.
  • public_address: public IPV4 address that is expected to receive VoIP traffic, in case of NAT.

Example:

api-cli run module/nethvoice-proxy1/configure-module --data '{"fqdn": "example.com", "addresses": { "address": "192.168.1.1", "public_address": "1.2.3.4" }}'

NAT scenario: local networks support

In on-premise installations where NethServer 8 is behind NAT (public_address differs from address), Kamailio normally advertises the public IP in SDP for all clients. Local clients (phones on the same LAN) must then reach NethVoice through the public IP, which requires hairpin NAT firewall rules — complex to configure and often unfeasible.

By providing the optional local_networks parameter the proxy avoids the need for hairpin NAT by automatically:

1. Adding Kamailio listeners on ports 6060 (SIP/TCP/UDP) and 6061 (SIPS/TLS) bound to the private IP.
2. Creating firewall port-forwarding rules that redirect traffic arriving on 5060/5061 from local network sources to 6060/6061.
3. Configuring Kamailio to select PRIVATE_IP:6060 as the outbound socket for destinations inside local networks, so the private IP is advertised in SDP for local clients — eliminating hairpin NAT.

Remote clients are unaffected and continue to use ports 5060/5061 with the public IP in SDP.

The network directly attached to address is detected automatically from the routing table. Additional subnets can be declared explicitly via local_networks.

Example:

api-cli run module/nethvoice-proxy1/configure-module --data \
  '{"fqdn": "proxy.example.com",
    "addresses": {"address": "192.168.1.1", "public_address": "1.2.3.4"},
    "local_networks": ["192.168.1.0/24", "10.0.0.0/8"]}'

The local_networks field accepts an array of CIDR-notation IPv4 subnets. Port-forwarding rules are applied and removed automatically when the configuration is updated or the module is destroyed.

Debug

To enable Kamailio debug at runtime, launch

kamcmd pv.shvSet debug int 1

TLS tracing is enabled when NethServer 8 support session is started, to enable it manually, launch

kamcmd siptrace.status on 

Uninstall

To uninstall the instance:

remove-module --no-preserve nethvoice-proxy1

Testing

Test the module using the test-module.sh script:

./test-module.sh <NODE_ADDR> ghcr.io/nethesis/nethvoice-proxy:latest

The tests are made using Robot Framework

Components

Kamailio

Kamailio® (successor of former OpenSER and SER) is an Open Source SIP Server released under GPLv2+, able to handle thousands of call setups per second. Website: kamailio

Postgres

PostgreSQL is a powerful, open source object-relational database system with over 35 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance. Website: postgresql

Redis

The open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker. Website: redis

RTPengine

The Sipwise NGCP rtpengine is a proxy for RTP traffic and other UDP based media traffic. It's meant to be used with the Kamailio SIP proxy and forms a drop-in replacement for any of the other available RTP and media proxies. Website: RTPengine

How to run locally

1. Compile the .env

   cp .env.template .env

   Edit the .env file and set the correct values

2. Build the docker image and run it

   cd modules/postgres
   make build
   make run && make log
   
   cd modules/redis
   make build
   make run && make log
   
   cd modules/rtpengine
   make build
   make run && make log
   
   cd modules/kamailio
   make build
   make run && make log

How to run remotely (DEV or PROD Virtual Machine)

1. Copy in the remote server the Makefile

2. Run the init stage to creation of ENV file and needed folder (only first time)

   make init

3. Run all the pods

   make run-all