OPNsense NPTv6 Updater

Automatically updates NPTv6 external prefix on OPNsense when ISP changes the delegated IPv6 prefix on PPPoE connections.

The Problem

When using PPPoE with IPv6 prefix delegation, ISPs may change the delegated prefix periodically (e.g., after reconnection or lease expiration). If you're using NPTv6 (Network Prefix Translation for IPv6), you need to manually update the External IPv6 Prefix in OPNsense each time this happens.

The Solution

This script monitors the delegated prefix and automatically updates the NPTv6 configuration when changes are detected. Run it via cron every minute for seamless IPv6 connectivity.

Features:

• Detects prefix changes from /tmp/<interface>_prefixv6
• Updates NPTv6 rules in OPNsense configuration
• Supports multiple interfaces/rules
• Optional prefix length conversion (e.g., /56 to /64)
• Creates config backups before changes
• Logs all activity for troubleshooting

Requirements

• OPNsense (tested on 23.x and 24.x)
• Python 3 (included in OPNsense)
• PPPoE interface with DHCPv6 prefix delegation enabled
• NPTv6 rule configured in OPNsense

Installation

1. Download the script

# SSH into your OPNsense
ssh root@your-opnsense-ip

# Download directly
fetch -o /usr/local/bin/nptv6-updater.py \
  https://raw.githubusercontent.com/YOUR_USER/opnsense-nptv6-updater/main/nptv6-updater.py

# Or copy from your machine
scp nptv6-updater.py root@your-opnsense-ip:/usr/local/bin/

2. Make it executable

chmod +x /usr/local/bin/nptv6-updater.py

3. Test the script

# Syntax: nptv6-updater.py <interface> <nptv6_rule_name>
/usr/local/bin/nptv6-updater.py pppoe0 MY_RULE

# Check the log
tail -f /var/log/nptv6_update.log

4. Get help

/usr/local/bin/nptv6-updater.py --help

Cron Setup

Via Web UI (Recommended)

1. Go to System > Settings > Cron
2. Click Add (+)
3. Configure:
   • Minutes: */1 (every minute)
   • Hours: *
   • Day of the month: *
   • Months: *
   • Days of the week: *
   • Command: /usr/local/bin/nptv6-updater.py pppoe0 MY_RULE
   • Description: Update NPTv6 prefix
4. Click Save

Multiple interfaces: Create one cron job per interface:

• /usr/local/bin/nptv6-updater.py pppoe0 ISP1_RULE
• /usr/local/bin/nptv6-updater.py pppoe1 ISP2_RULE

Via SSH

crontab -e

Add one line per interface:

*/1 * * * * /usr/local/bin/nptv6-updater.py pppoe0 ISP1_RULE
*/1 * * * * /usr/local/bin/nptv6-updater.py pppoe1 ISP2_RULE

Usage

nptv6-updater.py [-h] [-p PREFIX_LENGTH] interface nptv6_rule

Positional arguments:
  interface             PPPoE interface name (e.g., pppoe0, pppoe1)
  nptv6_rule           NPTv6 rule description (case-sensitive)

Optional arguments:
  -h, --help           Show help message
  -p, --prefix-length  Force prefix length (e.g., 64, 56, 48)
                       If not specified, uses delegated prefix as-is

Examples:
  nptv6-updater.py pppoe0 MY_RULE          # Uses delegated prefix (e.g., /56)
  nptv6-updater.py pppoe0 MY_RULE -p 64    # Forces /64 from delegated prefix
  nptv6-updater.py pppoe1 OTHER_RULE -p 56 # Forces /56 from delegated prefix

How It Works

1. Reads delegated prefix from /tmp/<interface>_prefixv6
2. If -p is specified, forces that prefix length
3. Reads current NPTv6 prefix from /conf/config.xml
4. Compares delegated prefix with current NPTv6 prefix
5. If different, updates NPTv6 configuration
6. Reloads firewall configuration with configctl filter reload
7. Logs all activity to /var/log/nptv6_update.log

Prefix Length Examples

Without -p flag:

• ISP delegates: 2804:30c:13fe::/56
• Script uses: 2804:30c:13fe::/56 (as-is)

With -p 64 flag:

• ISP delegates: 2804:30c:13fe::/56
• Script uses: 2804:30c:13fe::/64 (forced)

With -p 56 flag:

• ISP delegates: 2804:30c:13fe:abcd::/64
• Script uses: 2804:30c:13fe::/56 (forced)

Files

File	Location	Description
Script	/usr/local/bin/nptv6-updater.py	Main Python script
Config	/conf/config.xml	OPNsense configuration
Log	/var/log/nptv6_update.log	Activity log (all interfaces)
Prefix	/tmp/<interface>_prefixv6	Delegated prefix (OPNsense native)

Monitoring

View logs

tail -f /var/log/nptv6_update.log

Check delegated prefix

cat /tmp/pppoe0_prefixv6

Verify NPTv6 configuration

grep -A 10 '<description>MY_RULE</description>' /conf/config.xml

Troubleshooting

Script not detecting prefix

Check if prefix file exists:

cat /tmp/pppoe0_prefixv6

If empty or missing:

• Verify DHCPv6 is enabled on interface
• Check "Request only an IPv6 prefix" is enabled
• Reconnect PPPoE connection

NPTv6 rule not updating

Verify rule description matches exactly (case-sensitive):

grep '<description>MY_RULE</description>' /conf/config.xml

Check interface name

ifconfig | grep pppoe

Uninstallation

# Remove cron job (System > Settings > Cron)
rm /usr/local/bin/nptv6-updater.py
rm /var/log/nptv6_update.log

License

MIT