Available Now

FreePBX Custom IPv6 Module

One admin page that turns on IPv6 SIP for FreePBX 17 / Asterisk 22. Writes a managed marker block of IPv6 UDP and TCP PJSIP transports bound to the host's global IPv6 address, enables rtp_ipv6 and direct_media=no per selected extension through the core PJSip->addEndpoint() hook, and ships a small root-installed helper that works around a real FreePBX firewall bug that would otherwise mark every IPv6 phone as an attacker. Auto-detects the host's permanent global IPv6 address from /proc/net/if_inet6, so on an IPv6-ready PBX install plus Apply Config is all it takes.

Why This Exists

Asterisk's PJSIP channel driver has supported IPv6 for years, but FreePBX never shipped a GUI for it. Turning it on by hand means writing two transport sections into pjsip.transports_custom.conf, flipping rtp_ipv6=yes and direct_media=no on every extension you want on IPv6 (which has to go through pjsip.endpoint_custom_post.conf because the Extensions GUI does not expose those fields), and remembering to redo all of it after every FreePBX upgrade.

The FreePBX firewall adds a second problem: Smart.class.php::getPjsipContacts() in firewall 17.0.1.35 parses the fixed-width pjsip show contacts output, which truncates IPv6 contact URIs. An IPv6 phone's registration never lands in fpbxregistrations, so the responsive firewall sees a stream of SIP packets from an unknown host and flags it as an attacker — the phone works for a few seconds and then gets banned.

Custom IPv6 does the config writes through the FreePBX module framework (survives reloads and FreePBX upgrades) and ships a tiny customipv6-knownreg helper that reads the full IPv6 URIs from Asterisk's registrar database and keeps a dedicated ip6tables chain in sync. Together: IPv6 SIP works, and the phones stop getting banned.

What's in the box

  • Managed marker block for [ipv6-udp] and [ipv6-tcp] transports — address and port editable from the admin page
  • Per-extension IPv6 media — opt-in rtp_ipv6=yes + direct_media=no from a new "IPv6" tab on each extension
  • Host-address auto-detect from /proc/net/if_inet6, filtered to permanent global addresses on the default-route interface
  • Firewall-6 workaround helper — keeps a customipv6-knownreg ip6tables chain in sync with the live IPv6 registrar contacts, so phones are never mistaken for attackers
  • Pilot-build migration — detects and strips hand-rolled pilot blocks from *_custom_post.conf files on install, with timestamped backups
  • Enable-by-default on IPv6-ready hosts — install plus Apply Config is a zero-config bring-up

Compatibility: FreePBX 17 on Asterisk 22 (primary target). Depends only on the core PJSip driver. MIT licensed.

How It Works

The module owns a small, clearly-marked region of three FreePBX files and leaves everything else alone.

Step 1 — Auto-detect the host's IPv6 address

On install, the module reads /proc/net/if_inet6 and /proc/net/ipv6_route and picks a permanent global address (scope 00, flag 0x80, not temporary/deprecated/tentative) on the interface that holds the IPv6 default route. The result is pre-filled on the admin page. 100% file-only, 100% rootless. If more than one address matches, the admin can pick which one to use and edit the value.

Step 2 — Write a managed marker block to pjsip.transports_custom.conf

On every Apply Config, a sentinel-wrapped block containing [ipv6-udp] and [ipv6-tcp] sections is written atomically (tempfile in the same directory, then rename) to /etc/asterisk/pjsip.transports_custom.conf. Each section binds to [<v6>]:<port> where <port> defaults to the IPv4 SIP listener's port (so a single dual-stack DNS name serves both families on one port). Disabling the toggle strips the block cleanly; nothing else in the file is touched.

Step 3 — Per-extension IPv6 media through the core hook

Each extension gets a new IPv6 tab. Toggling it on makes the module inject rtp_ipv6=yes and direct_media=no through core's \FreePBX::Core()->getDriver('pjsip')->addEndpoint() hook, so the values ride into the generated pjsip.endpoint.conf after core's own lines — and PJSIP's later-line-wins parser rule makes them stick. No file patching, no _custom_post.conf editing by hand.

Step 4 — Workaround helper keeps ip6tables in sync with the registrar

A one-minute asterisk crontab entry runs /usr/local/sbin/customipv6-knownreg under NOPASSWD sudo. The helper reads the full IPv6 contact URIs from asterisk -rx 'database show registrar' (which, unlike pjsip show contacts, does not truncate) and syncs one -s <v6>/128 -j fpbxknownreg rule per live contact into a dedicated customipv6-knownreg chain hooked at INPUT rule 1. Every live IPv6 phone becomes a known-registered host as far as the responsive firewall is concerned.

Pilot-build migration

If you ran a hand-rolled IPv6 pilot before installing — sections in pjsip.transports_custom_post.conf, or a manual rtp_ipv6=yes block in pjsip.endpoint_custom_post.conf — the install detects them, backs each affected file up as <name>.bak-<YYYYmmdd-HHMMSS>-pre-customipv6, and strips the pilot bits so the module's managed block takes over cleanly. Operator content that isn't part of the pilot is left exactly where it was.

Self-retire hint

Once the upstream getPjsipContacts() truncation bug is fixed in the FreePBX firewall and fpbxregistrations starts carrying IPv6 /128s on its own, the helper logs a self_retire_candidate message to syslog — so the module page can surface a "workaround no longer needed" notice and the operator can turn the helper off.

One Admin Page, Live Status

Every moving part shows its current state inline, so you never have to bounce out to the Asterisk CLI to confirm a change took.

Settings

  • Enable IPv6 SIP — master toggle; off strips the marker block on the next Apply Config
  • Static global IPv6 address — auto-detected, editable, warned if the saved value isn't currently on the host
  • Port — defaults to the IPv4 SIP listener; a mismatch warns inline
  • [ipv6-udp] and [ipv6-tcp] transport toggles
  • Firewall-6 knownreg workaround toggle (recommended on)

Status

  • Transport status — one colored badge per transport: green = loaded, red = not loaded or no response, grey = disabled
  • Firewall-6 workaround — helper + sudoers presence, live chain contents from customipv6-knownreg --status
  • IPv6 contacts — table of live IPv6 registrations from database show registrar with extension, contact URI, transport, and expiry
  • Warnings for common misconfigs — no IPv6 on host, saved address not on interface, helper not installed, address mismatch

Per-extension state lives on each extension's own edit page, in a new IPv6 tab — a single on/off toggle for IPv6 media. One Apply Config after the toggle change writes the extension's rtp_ipv6 / direct_media injection into pjsip.endpoint.conf. No GUI reload gymnastics.

Installation

Install as a standard FreePBX module. One extra step as root deploys the firewall workaround helper — everything else is rootless.

From Module Admin (rootless)

Download the module

Download the tarball:

Upload in Module Admin

Go to Admin → Module Admin → Upload modules and upload the tarball. Or add the VoIP Stuff repo and use Download (From Web).

Install and Apply Config

Find Custom IPv6 under the Admin category, click Install, then Apply Config. On an IPv6-ready host, the transports marker block lands in pjsip.transports_custom.conf and the Enable IPv6 SIP toggle is seeded on. Transports go live at the next Apply Config.

One-shot root install (firewall helper)

fwconsole ma install customipv6

Run as root once per host. This deploys /usr/local/sbin/customipv6-knownreg (0750 root:root), /etc/sudoers.d/customipv6 with a narrow visudo-validated NOPASSWD grant for the asterisk user on that one absolute path, and a * * * * * entry in the asterisk user's crontab that runs the helper under sudo -n. The admin page detects whether this step has been done and shows a banner if the helper is missing.

Why root for this one step: the asterisk web user can't write under /etc or /usr/local/sbin, and putting the helper inside the module directory would be a privilege-escalation surface (that directory is asterisk-writable). The transports, endpoint options, and admin page all work rootlessly — only the firewall workaround needs this one-time root step.

Host Prerequisites

The module writes PBX config — not host networking. The host needs a permanent global IPv6 address before the module has anything to bind to.

What the admin needs to set up once, as root

  • Static global IPv6 address and gateway on the SIP interface (/etc/network/interfaces on Debian-family)
  • IPv6 enabled only on the SIP interface + loopback — all/default stay disabled in /etc/sysctl.d/99-disable-ipv6.conf, with accept_ra=0, autoconf=0
  • DNS AAAA record for the dual-stack hostname pointing at the new address
  • firewall-6 rules opening the SIP port over IPv6 (same ports you use on IPv4)

The module page shows a clear warning banner if none of these are detected on the host — and refuses to write anything until an IPv6 address exists on an interface.

Out of scope for v1.0

  • TLS or WebSocket over IPv6 — UDP + TCP transports only in this release
  • IPv6 SIP trunks — per-extension endpoints only
  • Router or OS IPv6 setup — the module does PBX config, not host networking

These are candidates for later versions. The 1.0 release focuses on getting IPv6-capable phones to register and media to flow over IPv6 on the extensions you choose — which is the piece FreePBX never shipped.

Frequently Asked Questions

Does enabling this break IPv4 SIP?

No. The module only adds [ipv6-udp] and [ipv6-tcp] transports in a marker block of its own. Extensions stay on Transport = Auto, and Asterisk's Auto picks the IPv6 transport when a phone's contact address is IPv6 and the IPv4 transport otherwise. IPv4 behavior is byte-for-byte identical to before the install.

What's the firewall workaround actually for?

The FreePBX responsive firewall marks unknown hosts as attackers after a threshold of SIP packets. It builds its "known registrations" chain by parsing pjsip show contacts, which uses a fixed-width formatter that truncates IPv6 URIs. The result: an IPv6 phone registers successfully, then every packet it sends is counted against the "unknown host" quota, and it gets banned. The workaround helper reads the full URIs from the registrar's own database (where they live as JSON) and keeps a parallel ip6tables chain in sync. The responsive firewall is unaware of IPv6 phones; the chain makes sure they're not touched.

Do I have to enable IPv6 on every extension at once?

No. The per-extension IPv6 tab is opt-in. Flip it on one phone, verify the registration and a test call, then roll it out. A phone whose IPv6 tab is off keeps IPv4-only behavior exactly as it was. rtp_ipv6=yes is a willingness flag not a requirement, so even an IPv4-only phone with the toggle on keeps working — but keeping it off until a phone is on IPv6 avoids any ambiguity in the config.

What happens if I disable the module?

The transports marker block is stripped from pjsip.transports_custom.conf on the next Apply Config. Each extension's injected rtp_ipv6 / direct_media=no is dropped from the generated pjsip.endpoint.conf (back to core defaults). Existing transports stay loaded until the next Asterisk restart (allow_reload=false by default on FreePBX 17). fwconsole ma uninstall customipv6 also tears down the ip6tables chain and removes the helper, sudoers grant, and crontab entry.

How much root does it need?

Only the firewall-6 helper. Dropping a file under /etc/sudoers.d/, installing a binary into /usr/local/sbin/, and the matching NOPASSWD grant — that's it. Everything else — transports marker block, per-extension rtp_ipv6, admin page, status panel, IPv6 address detection — runs as the asterisk web user with no special privileges. If the operator chooses not to run the one-shot root install, the module page clearly surfaces that the firewall workaround isn't in place.

Does it survive FreePBX and Asterisk upgrades?

Yes. The transports marker block is self-healing: it's rewritten on every Apply Config from the module's doDialplanHook(), so even if an Asterisk upgrade rewrites pjsip.transports_custom.conf the marker block is back on the next reload. Per-extension rtp_ipv6 rides into the generated endpoint config through the supported core hook, so it stays correct across FreePBX core module updates.

Is the module free?

Yes. Released under the MIT license — free for commercial and personal use. No license keys, no subscriptions, no phone-home.

Get Custom IPv6

Turn on IPv6 SIP for FreePBX 17 / Asterisk 22 from one admin page. Install the module, Apply Config, flip on the extensions that need IPv6 media.