feat: Add NAT localnet support with custom ports 6060/6061 by paolovisintin · Pull Request #113 · nethesis/ns8-nethvoice-proxy

paolovisintin · 2025-12-18T11:03:32Z

This pull request introduces several improvements and bug fixes related to SIP port forwarding, firewall rules, and Kamailio configuration to better handle NAT scenarios and internal service network routing. The changes focus on more robust port forwarding management, expanded firewall port exposure, and enhanced Kamailio socket selection logic for both requests and replies, particularly when traffic is destined for internal networks or behind NAT.

Firewall and Port Forwarding Management:

Added dynamic creation and cleanup of rich firewall rules for SIP port forwarding (5060/5061 to 6060/6061) based on detected local networks in configure-module, with matching removal logic in destroy-module. This ensures correct port forwarding when the configuration changes or is destroyed. [1] [2]
Expanded public firewall exposure to include custom SIP ports (6060/6061 TCP/UDP) in addition to standard SIP/SIPS and RTP ports.

Kamailio Configuration and Routing:

Enhanced Kamailio bootstrap and config files to add listeners for ports 6060/6061 and to select the correct outbound socket (PRIVATE_IP:6060 or SERVICE_IP:5060) depending on whether traffic is destined for local networks or the internal service network (Asterisk). This improves NAT traversal and internal routing. [1] [2] [3] [4] [5] [6]
Ensured that ACKs and in-dialog NOTIFYs use the correct socket by invoking the new SET_SOCKET route in Kamailio config.

Update and Maintenance Scripts:

Added a new Python script to safely reapply configuration during module updates if the FQDN is valid, improving update reliability.
Removed an obsolete workaround script (90srv) from update-module.d, cleaning up the update process.
Modified restart logic to only restart relevant services (Postgres, Redis) instead of all SIP-related services, reducing unnecessary restarts.

Miscellaneous:

Updated .gitignore and .cursorindexingignore to exclude SpecStory project files and auto-saves, improving repo hygiene. [1] [2]
Updated image build labels to reflect new authorizations for portsadm.

NethServer/dev#7725

Copilot

Pull request overview

This PR adds support for NAT configurations with custom ports 6060/6061 and introduces a LOCAL_SOURCE_SUBNETS feature to handle SIP clients from local subnets differently than external clients, avoiding the use of advertised public IP for internal clients.

Key changes:

Added custom TCP/UDP port 6060 and TLS port 6061 for SIP traffic
Implemented LOCAL_SOURCE_SUBNETS functionality to selectively use private IP for clients in specified local subnets
Added firewall rules, configuration validation, and comprehensive documentation

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`imageroot/actions/create-module/20firewall`	Opens custom ports 6060 (TCP/UDP) and 6061 (TCP) in firewall
`modules/kamailio/bootstrap.sh`	Adds listen directives for custom ports 6060/6061 and initializes LOCAL_SOURCE_SUBNETS environment variable
`modules/kamailio/config/kamailio.cfg`	Implements CHECK_LOCAL_SOURCE route to selectively use private IP for requests from configured local subnets
`modules/kamailio/config/template.kamailio-local.cfg`	Adds LOCAL_SOURCE_SUBNETS configuration variable
`imageroot/actions/configure-module/20configure`	Handles LOCAL_SOURCE_SUBNETS configuration from API input
`imageroot/actions/get-configuration/20read`	Returns LOCAL_SOURCE_SUBNETS in configuration output
`imageroot/actions/configure-module/validate-input.json`	Adds validation schema for local_source_subnets array with CIDR pattern
`tests/10_actions/15_configure_local_source_subnets.robot`	Adds automated tests for LOCAL_SOURCE_SUBNETS configuration
`examples/test-local-source-subnets.sh`	Provides test script for manual verification of LOCAL_SOURCE_SUBNETS
`examples/configure-with-local-subnets.json`	Sample configuration with local_source_subnets
`docs/LOCAL_SOURCE_SUBNETS.md`	Technical documentation for LOCAL_SOURCE_SUBNETS feature
`README_LOCAL_SOURCE_SUBNETS_IT.md`	Italian user guide for LOCAL_SOURCE_SUBNETS
`CHANGELOG.md`	Documents the new LOCAL_SOURCE_SUBNETS feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-27T08:04:32Z

+        if ($du != $null && $du != 0 && $du != "") {
+            $var(destination_ip) = $(du{uri.host});
+        } else {
+            $var(destination_ip) = $(ru{uri.host}); # fetch the destination ip from ru
+        }


The new logic to extract destination_ip from $du when present (lines 1071-1075) is a good improvement. However, the comparison $du != 0 is checking if $du is the numeric value 0, which may not be meaningful for a URI string. Consider simplifying to just check $du != $null && $du != "" for clarity.

@paolovisintin What do you think about this?

Copilot · 2026-01-29T10:44:47Z

@Amygos I've opened a new pull request, #129, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

modules/kamailio/bootstrap.sh:46

When behind NAT, the script adds listeners for ports 6060/6061, but when not behind NAT (lines 40-46), these additional listeners are not added. This creates an inconsistency where the new ports are only available in NAT scenarios. Consider whether this is intentional or if the non-NAT case should also include these listeners.

else
    # now I have to add the listen with the public IP in the kamailio-local-additional.cfg
    echo "listen=udp:${PUBLIC_IP}:5060" > /tmp/kamailio-local-additional.cfg
    # doind the same for TCP
    echo "listen=tcp:${PUBLIC_IP}:5060" >> /tmp/kamailio-local-additional.cfg
    # doing the same for TLS
    echo "listen=tls:${PUBLIC_IP}:5061" >> /tmp/kamailio-local-additional.cfg

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-29T10:51:38Z

@Amygos I've opened a new pull request, #130, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2026-01-29T11:33:43Z

@Amygos I've opened a new pull request, #131, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2026-01-29T14:03:15Z

@Amygos I've opened a new pull request, #132, to work on those changes. Once the pull request is ready, I'll request review from you.

Open custom ports: * 6060 udp/tcp: SIP * 6061 tcp: SIPS

Enable port 6060 and 6061 in the Kamailio bootstrap script.

Update SET_SOCKET route to handle LOCALNETWORKS and INTERNAL_NETWORK more accurately. This forces PRIVATE_IP for LAN SIP traffic and uses SERVICE_IP for service network destinations (e.g., Asterisk). Fixes NAT connectivity issues for clients behind local subnets by ensuring advertised address matches network scope.

Add a script for making SIP calls using the baresip application. The script includes functions for printing banners, scenarios, usage, steps, success messages, and information messages. It also includes functions for starting the caller and callee, initiating the call, displaying progress, and cleaning up after the call. The script supports LAN, WAN reverse call scenarios.

Updated the rsync destination path in.sh script to correctly sync files the specified directory on the server.

Added .cursorindexingignore to exclude SpecStory auto-save files from indexing and allow explicit context inclusion via @ references. Also added .specstory/.gitignore to ignore SpecStory project identity and explanation files.

Wrap TT157 xlog statements in conditional debug checks to reduce unnecessary log noise in production.

Introduce helper to generate IPv4 rich rules mapping SIP ports 5060/5061 to alternate targets when proxy is behind NAT. Ensure previous rules are removed before applying updates, preventing stale firewall entries. Also store multiple local networks in environment, improving flexibility for multi-subnet deployments.

Ensure any port forwarding rich rules created during module configuration are cleaned up when destroying the module, but only in scenarios where BEHIND_NAT is true and a public IP was present.

Introduce 40reconfigure step to reapply configuration when FQDN is valid and not ending with ".invalid". This ensures smooth update flows and allows modules to self-correct without manual intervention. Remove restart logic for kamailio and rtpengine from 20restart, as those services are no longer required to be restarted here. Remove the obsolete 90srv workaround script, this step is now performed by module reconfiguration.

Bump the org.nethserver.min-core label from 3.12.4-0 to 3.17.0-0 to align container metadata with the required release for issue NethServer/dev#7836.

Describe the on-premise behind-NAT scenario introduced in PR #113 (NethServer/dev#7725): how Kamailio avoids hairpin NAT by advertising the private IP in SDP for local clients via port-forwarding rules and dedicated listeners on ports 6060/6061. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Amygos requested a review from Copilot January 7, 2026 15:58

Copilot started reviewing on behalf of Amygos January 7, 2026 15:58 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

Amygos force-pushed the 157-under-nat-localnet branch 2 times, most recently from 33786ee to 93fc0b7 Compare January 26, 2026 10:26

Amygos requested a review from Copilot January 27, 2026 07:57

Copilot started reviewing on behalf of Amygos January 27, 2026 07:57 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

Amygos force-pushed the 157-under-nat-localnet branch 2 times, most recently from e7aefa7 to 6f22ae7 Compare January 28, 2026 14:36

Amygos requested a review from Copilot January 29, 2026 10:39

Copilot started reviewing on behalf of Amygos January 29, 2026 10:40 View session

Copilot AI mentioned this pull request Jan 29, 2026

Use range pattern for custom SIP ports 6060-6061 to match standard ports #129

Merged

Copilot AI reviewed Jan 29, 2026

View reviewed changes

Comment thread imageroot/actions/destroy-module/20firewall Outdated

Comment thread modules/kamailio/config/kamailio.cfg

Comment thread imageroot/actions/configure-module/20configure Outdated

Comment thread imageroot/actions/destroy-module/20firewall

Copilot AI mentioned this pull request Jan 29, 2026

Remove unused private_ip parameter from create_port_forward_rules #130

Merged

7 tasks

Copilot AI mentioned this pull request Jan 29, 2026

Fix missing sys import in destroy-module firewall script #131

Merged

Copilot AI mentioned this pull request Jan 29, 2026

Fix inaccurate comment describing socket configuration in kamailio.cfg #132

Merged

Paolo and others added 8 commits January 29, 2026 16:14

feat: Add custom ports to firewall configuration

d1c81a1

Open custom ports: * 6060 udp/tcp: SIP * 6061 tcp: SIPS

feat(kamailio): support fo custom ports

3b2f66b

Enable port 6060 and 6061 in the Kamailio bootstrap script.

build: Fix rsync destination path in script

b111249

Updated the rsync destination path in.sh script to correctly sync files the specified directory on the server.

feat: Add .cursorindexingignore and .specstory/.gitignore

d1260fa

Added .cursorindexingignore to exclude SpecStory auto-save files from indexing and allow explicit context inclusion via @ references. Also added .specstory/.gitignore to ignore SpecStory project identity and explanation files.

fix(kamailio): guard TT157 logs with debug checks

16efaf6

Wrap TT157 xlog statements in conditional debug checks to reduce unnecessary log noise in production.

Amygos force-pushed the 157-under-nat-localnet branch from 0019e79 to 64e0fcb Compare January 30, 2026 10:43

Amygos added 3 commits February 10, 2026 12:12

feat(destroy-module): remove firewall rich rules

d33bf29

Ensure any port forwarding rich rules created during module configuration are cleaned up when destroying the module, but only in scenarios where BEHIND_NAT is true and a public IP was present.

fix(build-images): update min-core label to 3.17.0

7e9f414

Bump the org.nethserver.min-core label from 3.12.4-0 to 3.17.0-0 to align container metadata with the required release for issue NethServer/dev#7836.

Amygos force-pushed the 157-under-nat-localnet branch from 46f03b9 to 7e9f414 Compare February 10, 2026 11:12

Amygos merged commit ffa708d into main Feb 10, 2026
9 checks passed

Amygos deleted the 157-under-nat-localnet branch February 10, 2026 11:30

Amygos mentioned this pull request Feb 23, 2026

docs: add NAT local networks section to README #149

Merged

Uh oh!

Conversation

paolovisintin commented Dec 18, 2025 • edited by Amygos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Amygos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jan 29, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jan 29, 2026

Uh oh!

Copilot AI commented Jan 29, 2026

Uh oh!

Copilot AI commented Jan 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paolovisintin commented Dec 18, 2025 •

edited by Amygos

Loading